Levyra Compose

Levyra Compose workflow

Required context

1. Read the root AGENTS.md and app/AGENTS.md.
2. Read docs/ARCHITECTURE.md.
3. Read .agents/claude/rules/compose-ui.md, .agents/claude/rules/localization.md, and .agents/claude/rules/architecture.md.
4. Inspect the affected composable, state holder, ViewModel, navigation path, theme, resources, and nearby tests.

Change contract

Before editing, identify:

• the exact user-visible behavior;
• the smallest state slice the screen should observe;
• lifecycle and cleanup ownership;
• long-text, RTL, accessibility, restoration, loading, empty, error, and offline states;
• behavior that must remain unchanged on other screens and form factors.

Guardrails

• Keep I/O, parsing, persistence, networking, and orchestration outside composables.
• Preserve unidirectional data flow and immutable UI state.
• Use stable lazy-list keys and avoid observing broader state than the screen needs.
• Key effects to their true dependencies and clean up callbacks, listeners, receivers, players, surfaces, and jobs deterministically.
• Keep cached or real content visible during refresh when safe; avoid blank-screen regressions.
• Respect reduced motion, lifecycle, low-RAM, battery/data saver, touch targets, contrast, focus, screen readers, and RTL.
• Add localization entries for every user-facing string; do not hardcode visible text.
• Avoid broad visual rewrites when a focused state or layout correction is sufficient.

Android platform UI guardrails

Adapt the stable, useful parts of Google's official Android agent guidance to Levyra's current Compose architecture. Do not force an architecture or dependency migration merely because an upstream recipe assumes one.

Edge-to-edge and system insets

• Treat edge-to-edge as a screen/layout correctness concern, not decorative polish.
• Before adding padding, trace which parent already consumes status-bar, navigation-bar, cutout, caption-bar, or IME insets. Apply each inset once; double-padding is a regression.
• Prefer existing Material 3/Scaffold inset handling and pass PaddingValues into scrollable content where that preserves drawing behind system bars. Avoid padding a lazy-list parent when contentPadding is the correct ownership point.
• For text-entry screens, verify the keyboard does not obscure the focused field and do not stack imePadding() on top of an ancestor that already supplies/consumes IME insets.
• Keep critical controls tappable outside unsafe system areas and verify status/navigation-bar icon legibility against the actual light/dark surface.
• Full-screen dialogs and media surfaces need explicit inset review; do not assume activity-level handling automatically fixes nested windows.

Adaptive layouts and larger form factors

• Verify the current navigation architecture before introducing adaptive-navigation APIs. Do not migrate Levyra to Navigation 3, multi-pane scenes, Grid/FlexBox, or other experimental APIs as collateral work.
• Preserve media-first full-screen behavior where detail content genuinely benefits from the space; do not introduce list-detail solely because a device is wide.
• For grids/lists, prefer the existing stable adaptive pattern already used in Levyra. When changing column behavior, base it on available width and a usable minimum item width rather than device-name checks.
• Check phone portrait/landscape plus at least one larger width when a layout change can materially alter composition, navigation, artwork sizing, or controls.
• Pointer/keyboard/desktop-style input support should reuse existing platform behavior and semantics; do not add a second interaction model unless the affected surface needs it.

Experimental Compose APIs

Google's current Android skills include experimental Compose Styles, Grid, FlexBox, MediaQuery, and related alpha/beta APIs. They are references, not Levyra defaults.

• Do not upgrade Compose or opt the project into an experimental API merely to modernize code.
• Do not migrate custom components to the experimental Compose Styles API unless the owner explicitly asks for that experiment and the compatibility/maintenance tradeoff is reviewed.
• If an experimental API is explicitly approved, isolate the opt-in, preserve the visual/behavior baseline, and add focused validation so reverting it is straightforward.

Compose performance diagnosis

For jank, slow scrolling, frame drops, or suspected recomposition problems, measure before redesigning the UI.

1. Start with the affected code and trace the state reads that can invalidate it.
2. Inspect stable identity in lazy layouts, broad state collection, work performed during composition, allocation churn, image sizing/loading, subcomposition, and expensive layout/intrinsic measurement.
3. Compare against a nearby smooth screen or component when one exists before introducing a new pattern.
4. If code inspection is not enough, gather direct evidence with the narrowest useful tool: Layout Inspector/recomposition counts, System Trace or Perfetto for frame timing, and the existing benchmark/baseline-profile infrastructure when a repeatable metric is appropriate.
5. Diagnose release-like behavior for performance claims. Debug-only jank or timings are evidence about the debug build, not proof of release performance.
6. Change one material performance variable at a time and remeasure. Do not cargo-cult remember, derivedStateOf, @Stable, @Immutable, persistent collections, or a new dependency without showing that it fixes the measured invalidation/allocation/layout problem.

Performance findings must distinguish code-review suspicion from measured evidence. Report the before/after metric when one was actually collected. Load levyra-android-performance when the investigation needs Perfetto/System Trace, thread-state, blocking, memory, I/O, power, startup, or other cross-thread/runtime evidence.