{"id":44781864,"url":"https://github.com/aldefy/lumen","last_synced_at":"2026-04-01T16:40:25.239Z","repository":{"id":336492687,"uuid":"1149853597","full_name":"aldefy/Lumen","owner":"aldefy","description":"Compose Multiplatform coachmark library. Real transparent cutouts, not dimmed overlays. Android + iOS.","archived":false,"fork":false,"pushed_at":"2026-02-23T13:55:52.000Z","size":2184,"stargazers_count":67,"open_issues_count":6,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-23T21:43:31.527Z","etag":null,"topics":["android","coachmark","compose-desktop","compose-multiplatform","compose-web","ios","jetpack-compose","kotlin-multiplatform","onboarding","spotlight","tooltip"],"latest_commit_sha":null,"homepage":null,"language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aldefy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-04T15:46:08.000Z","updated_at":"2026-02-23T13:55:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aldefy/Lumen","commit_stats":null,"previous_names":["aldefy/lumen"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/aldefy/Lumen","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aldefy%2FLumen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aldefy%2FLumen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aldefy%2FLumen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aldefy%2FLumen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aldefy","download_url":"https://codeload.github.com/aldefy/Lumen/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aldefy%2FLumen/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29829408,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-25T15:41:19.027Z","status":"ssl_error","status_checked_at":"2026-02-25T15:40:47.150Z","response_time":61,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","coachmark","compose-desktop","compose-multiplatform","compose-web","ios","jetpack-compose","kotlin-multiplatform","onboarding","spotlight","tooltip"],"created_at":"2026-02-16T08:20:23.641Z","updated_at":"2026-02-25T16:00:45.023Z","avatar_url":"https://github.com/aldefy.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lumen\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"logo.svg\" width=\"128\" height=\"128\" alt=\"Lumen Logo\"/\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eSpotlight your UI, not a screenshot of it.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://central.sonatype.com/artifact/io.github.aldefy/lumen\"\u003e\u003cimg src=\"https://img.shields.io/maven-central/v/io.github.aldefy/lumen.svg?label=Maven%20Central\u0026logo=apachemaven\" alt=\"Maven Central\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://kotlinlang.org\"\u003e\u003cimg src=\"https://img.shields.io/badge/Kotlin-2.0-blue.svg?logo=kotlin\" alt=\"Kotlin\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.jetbrains.com/compose-multiplatform/\"\u003e\u003cimg src=\"https://img.shields.io/badge/Compose_Multiplatform-1.7-4285F4.svg?logo=jetpackcompose\" alt=\"Compose Multiplatform\"/\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-Apache%202.0-green.svg\" alt=\"License\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://aldefy.github.io/Lumen/\"\u003e\u003cimg src=\"https://img.shields.io/badge/Docs-Website-blue.svg?logo=readthedocs\" alt=\"Documentation\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://aldefy.github.io/Lumen/demo/\"\u003e\u003cimg src=\"https://img.shields.io/badge/Live_Demo-Try_It-10B981.svg?logo=googlechrome\u0026logoColor=white\" alt=\"Live Demo\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://aldefy.github.io/Lumen/dashboard/\"\u003e\u003cimg src=\"https://img.shields.io/badge/Dashboard_Demo-Try_It-6366F1.svg?logo=googlechrome\u0026logoColor=white\" alt=\"Dashboard Demo\"/\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Android-3DDC84.svg?logo=android\u0026logoColor=white\" alt=\"Android\"/\u003e\n  \u003cimg src=\"https://img.shields.io/badge/iOS-000000.svg?logo=apple\u0026logoColor=white\" alt=\"iOS\"/\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Desktop-JVM-orange.svg?logo=openjdk\u0026logoColor=white\" alt=\"Desktop\"/\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Web-Wasm-purple.svg?logo=webassembly\u0026logoColor=white\" alt=\"Web\"/\u003e\n\u003c/p\u003e\n\n---\n\nA Compose Multiplatform coachmark library that creates **true transparent cutouts** in the overlay scrim. Your actual UI remains visible and interactive through the spotlight - animations play, buttons respond, nothing is faked.\n\n\u003e **Supports Android, iOS, Desktop, and Web** via Kotlin Multiplatform.\n\n**[Live Demo](https://aldefy.github.io/Lumen/demo/)** | **[Dashboard Demo](https://aldefy.github.io/Lumen/dashboard/)** — Try it in your browser, no install required.\n\n## Installation\n\n### Kotlin Multiplatform\n\nAdd to your shared module's `build.gradle.kts`:\n\n```kotlin\nkotlin {\n    sourceSets {\n        commonMain.dependencies {\n            implementation(\"io.github.aldefy:lumen:1.0.0-beta06\")\n        }\n    }\n}\n```\n\nThis resolves the correct artifact per target automatically:\n\n| Target | Artifact |\n|--------|----------|\n| Android | `lumen-android` (AAR) |\n| iOS arm64 | `lumen-iosarm64` (klib) |\n| iOS Simulator arm64 | `lumen-iossimulatorarm64` (klib) |\n| iOS Simulator x64 | `lumen-iosx64` (klib) |\n| Desktop (JVM) | `lumen-jvm` (JAR) |\n| Web (Wasm) | `lumen-wasmjs` (klib) |\n\n### Android Only\n\nIf your project is not using KMP:\n\n```kotlin\ndependencies {\n    implementation(\"io.github.aldefy:lumen-android:1.0.0-beta06\")\n}\n```\n\n## Usage\n\n```kotlin\nval controller = rememberCoachmarkController()\n\nCoachmarkHost(controller = controller) {\n    // Your screen content\n    Button(\n        onClick = { },\n        modifier = Modifier.coachmarkTarget(controller, \"my-button\")\n    ) {\n        Text(\"Click me\")\n    }\n}\n\n// Show the coachmark\ncontroller.show(\n    CoachmarkTarget(\n        id = \"my-button\",\n        title = \"Welcome\",\n        description = \"Tap here to get started.\",\n    )\n)\n```\n\n## Demo\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"demo_basic.png\" width=\"280\" alt=\"Basic Coachmark\"/\u003e\n  \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\n  \u003cimg src=\"demo_sequence.png\" width=\"280\" alt=\"Multi-Step Sequence\"/\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eSingle coachmark with pulse animation\u003c/em\u003e\n  \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\n  \u003cem\u003eMulti-step onboarding tour\u003c/em\u003e\n\u003c/p\u003e\n\n## [API Reference](https://aldefy.github.io/Lumen/#/api-reference)\n\n\u003e For the full API documentation, visit the [docs site](https://aldefy.github.io/Lumen/#/api-reference).\n\n### Core Components\n\n| Component | Description |\n|-----------|-------------|\n| `CoachmarkHost` | Wraps your content and renders the overlay scrim |\n| `CoachmarkController` | Manages coachmark state, show/dismiss operations |\n| `CoachmarkTarget` | Defines a single spotlight target with tooltip content |\n| `Modifier.coachmarkTarget()` | Tags a composable as a coachmark target |\n\n### CoachmarkTarget Properties\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `id` | `String` | Unique identifier for the target |\n| `title` | `String` | Tooltip headline |\n| `description` | `String` | Tooltip body text |\n| `shape` | `CutoutShape` | Shape of the transparent cutout |\n| `tooltipPosition` | `TooltipPosition` | Where tooltip appears relative to target |\n| `connectorStyle` | `ConnectorStyle` | Style of line connecting cutout to tooltip |\n| `connectorEndStyle` | `ConnectorEndStyle` | Endpoint decoration (DOT, ARROW, NONE, CUSTOM) |\n| `highlightAnimation` | `HighlightAnimation` | Animation effect on the cutout |\n| `targetTapBehavior` | `TargetTapBehavior` | What happens when user taps the cutout area |\n| `showDontShowAgain` | `Boolean` | Show \"Don't show again\" checkbox |\n| `ctaText` | `String` | Call-to-action button text |\n\n### CutoutShape\n\n| Shape | Description |\n|-------|-------------|\n| `Circle` | Circular cutout, ideal for FABs and icons |\n| `Rect` | Rectangular cutout with sharp corners |\n| `RoundedRect` | Rectangle with rounded corners |\n| `Squircle` | iOS-style superellipse with smooth curves |\n| `Star` | Star shape for gamification highlights |\n\n### HighlightAnimation\n\n| Animation | Description |\n|-----------|-------------|\n| `NONE` | Static cutout, no animation |\n| `PULSE` | Gentle breathing/scaling effect |\n| `GLOW` | Pulsing stroke width and opacity |\n| `RIPPLE` | Expanding rings emanating outward |\n| `SHIMMER` | Highlight sweeping around the stroke |\n| `BOUNCE` | Energetic scale with overshoot |\n\n### ConnectorStyle\n\n| Style | Description |\n|-------|-------------|\n| `AUTO` | Auto-select based on tooltip position |\n| `VERTICAL` | Straight vertical line |\n| `HORIZONTAL` | Straight horizontal line |\n| `ELBOW` | L-shaped with 90° bend |\n| `DIRECT` | Diagonal line pointing to tooltip |\n| `CURVED` | Smooth quadratic Bezier curve |\n\n### ConnectorEndStyle\n\n| Style | Description |\n|-------|-------------|\n| `DOT` | Small filled circle (default) |\n| `ARROW` | Directional arrowhead toward tooltip |\n| `NONE` | No endpoint decoration |\n| `CUSTOM` | Custom rendering via `DrawScope` lambda |\n\n### CoachmarkConfig\n\n| Property | Default | Description |\n|----------|---------|-------------|\n| `scrimOpacity` | `MEDIUM` | Darkness of the overlay (LIGHT, MEDIUM, DARK, EXTRA_DARK) |\n| `scrimTapBehavior` | `DISMISS` | Action when tapping outside cutout |\n| `backPressBehavior` | `DISMISS` | Action on back press |\n| `showSkipButton` | `false` | Show skip button in tooltip |\n| `showProgressIndicator` | `true` | Show step dots for sequences |\n| `delayBeforeShow` | `0L` | Milliseconds to wait before showing |\n| `connectorCutoutGap` | `12.dp` | Minimum gap between cutout animation edge and connector dot |\n| `ctaMinWidth` | `Dp.Unspecified` | Minimum width for the CTA button (unspecified = wrap content) |\n| `ctaMinHeight` | `48.dp` | Minimum height for the CTA button |\n| `ctaCornerRadius` | `22.dp` | Corner radius for the CTA button shape |\n\n### Controller Methods\n\n```kotlin\ncontroller.show(target)           // Show single coachmark\ncontroller.showSequence(targets)  // Show multi-step tour\ncontroller.next()                 // Advance to next step\ncontroller.previous()             // Go back one step\ncontroller.dismiss()              // Hide coachmark\ncontroller.enabled = false        // Disable all coachmarks\n```\n\n## Sample Apps\n\n### Feature Catalog (`sample`)\n\nA Compose Multiplatform app with interactive demos for all features.\n\n- **Android:** Open the project in Android Studio and run the `sample` configuration.\n- **iOS:** Open `iosApp/iosApp.xcodeproj` in Xcode and run on a simulator or device.\n- **Desktop:** Run `./gradlew :sample:run` from the terminal to launch the desktop window.\n- **Web:** Run `./gradlew :sample:wasmJsBrowserRun` to open the sample in a browser.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"art/ios-sample-screenshot.png\" width=\"280\" alt=\"iOS Sample App\"/\u003e\n\u003c/p\u003e\n\n### Analytics Dashboard (`sample-web`)\n\nA web-only (wasmJs) dashboard demo showing Lumen coachmarks in a real-world SaaS onboarding scenario. Features a 7-step auto-starting feature tour with varied cutout shapes, animations, and connector styles.\n\n- **Web:** Run `./gradlew :sample-web:wasmJsBrowserDevelopmentRun` to open the dashboard in a browser.\n- **[Live Dashboard Demo](https://aldefy.github.io/Lumen/dashboard/)**\n\n## Platform Support\n\n| Platform | Min Version | Artifact |\n|----------|-------------|----------|\n| Android  | API 23      | `lumen` (via Gradle metadata) or `lumen-android` |\n| iOS arm64 | iOS 16     | `lumen-iosarm64` |\n| iOS Simulator arm64 | iOS 16 | `lumen-iossimulatorarm64` |\n| iOS Simulator x64   | iOS 16 | `lumen-iosx64` |\n| Desktop (JVM) | JDK 17 | `lumen-jvm` |\n| Web (Wasm) | Modern browser | `lumen-wasmjs` |\n\n## Requirements\n\n- Kotlin 2.0+\n- Compose Multiplatform 1.7+\n- Android API 23+ / iOS 16+ / JDK 17+ / Modern browsers (Chrome, Firefox, Safari)\n\n## License\n\n```\nCopyright 2024 Adit Lal\n\nLicensed under the Apache License, Version 2.0\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faldefy%2Flumen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faldefy%2Flumen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faldefy%2Flumen/lists"}