Navigation
DevelopmentnavigationNavigation is an Agent Skill for development published in the igorescodro/alkaa repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/igorescodro/alkaa/blob/HEAD/.claude/skills/navigation/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/navigation, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Alkaa Navigation
Overview
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.
Required Files per Navigation Change
| 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.
Steps
- Create the Event — Name after the action, not the destination (
OnEditClick, notNavigateToEdit) → seereferences/CODE_PATTERNS.md - Create the Destination — Add
@Serializable; choose interface based on screen type → seereferences/CODE_PATTERNS.md - Add a NavGraph Entry —
entry<Destination>block with appropriate transition spec → seereferences/CODE_PATTERNS.md - Hoist Navigation — Composables receive lambdas; NavGraph calls
navEventController.sendEvent()→ seereferences/CODE_PATTERNS.md
Destination Interface Rules
| 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.
Checklist
- Event named after an action (verb phrase:
On*Click,On*Save) - Destination annotated with
@Serializable -
TopLevelonly for bottom-nav root screens (with@CommonParcelize,title,icon) -
TopAppBarVisibleonly for dialogs/sheets/non-full-screen -
TopLevel/TopAppBarVisibledestinations registered inDestination.ktsets - NavGraph
entry<>block exists for each new destination - Navigation events sent from within NavGraph lambda, not from composables or ViewModels
- Back navigation uses
Event.OnBack, not custom events
Common Mistakes
| 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 |