// Use when adding a new screen or modifying navigation in the Alkaa project — triggers on tasks like "add a new screen", "navigate to X", "add destination", "wire up navigation", or "create a navigation event". Also triggers when connecting UI actions to routes in NavGraph.
| name | navigation |
| description | Use when adding a new screen or modifying navigation in the Alkaa project — triggers on tasks like "add a new screen", "navigate to X", "add destination", "wire up navigation", or "create a navigation event". Also triggers when connecting UI actions to routes in NavGraph. |
Alkaa uses event-driven navigation: UI components send named action events, and the system resolves where to go. Navigation is never triggered directly from UI or ViewModels — it always flows through NavEventController.
| File | Package | Purpose |
|---|---|---|
*Event.kt | com.escodro.navigationapi.event | Defines action events |
*Destination.kt | com.escodro.navigationapi.destination | Defines typed routes |
*NavGraph.kt | feature module | Registers entries and sends events |
Both *Event.kt and *Destination.kt live in features/navigation-api. → See references/CODE_PATTERNS.md for Kotlin examples of all three files.
OnEditClick, not NavigateToEdit) → see references/CODE_PATTERNS.md@Serializable; choose interface based on screen type → see references/CODE_PATTERNS.mdentry<Destination> block with appropriate transition spec → see references/CODE_PATTERNS.mdnavEventController.sendEvent() → see references/CODE_PATTERNS.md| Interface | When to use |
|---|---|
TopLevel | Bottom-nav root screens only (requires title, icon, @CommonParcelize) |
TopAppBarVisible | Dialogs, bottom sheets, non-full-screen destinations |
| Neither | Regular full-screen push destinations |
Also register TopLevel and TopAppBarVisible destinations in the corresponding sets in Destination.kt.
On*Click, On*Save)@SerializableTopLevel only for bottom-nav root screens (with @CommonParcelize, title, icon)TopAppBarVisible only for dialogs/sheets/non-full-screenTopLevel/TopAppBarVisible destinations registered in Destination.kt setsentry<> block exists for each new destinationEvent.OnBack, not custom events| Mistake | Fix |
|---|---|
navEventController.sendEvent() in a ViewModel | Must not leave the NavGraph — pass navigation as lambda callbacks instead |
navEventController.sendEvent() inside a @Composable | Move to NavGraph entry<> block via lambda callback |
Event named NavigateToDetail or GoToSettings | Name after the action: OnDetailClick, OnSettingsClick |
Destination without @Serializable | Add annotation — Navigation3 requires it |
Full-screen destination with TopAppBarVisible | Remove — use only for dialogs/sheets |
New feature with no NavGraph implementation | Create *NavGraph.kt and bind in Koin module |
Use when writing or modifying end-to-end tests in the Alkaa project — triggers on tasks like "add an E2E test", "write a flow test", "test this feature end-to-end", "add a test to shared module", or "cover this user journey with a test".
Use when writing or modifying UI/Compose instrumented tests in the Alkaa project — triggers on tasks like "add a UI test", "test this composable", "add instrumented test", "test this screen behavior".
Use when the user asks to commit changes, stage and commit, or says "commit my changes" — stages all uncommitted changes and creates a structured commit message with emoji, title, and summary
Use when adding, editing, or reviewing user-facing strings in the Alkaa project — UI labels, button text, content descriptions, empty states, error messages, plurals, or any text visible to the user.
Use when creating a new Composable or modifying an existing one in the Alkaa project — screen structure, state handling, adaptive layouts, Kuvio usage, or previews.
Use when implementing a new Kuvio component for the Alkaa Design System after design spec and structure decisions are finalized