mobile-ui-slicing-playbook

name: mobile-ui-slicing-playbook description: Mobile UI slicing workflow for Android Compose, Android XML, and Flutter widgets. Use when implementing new screens/components, splitting large UI tasks into safe incremental slices, fixing layout/state coupling, or converting design specs into maintainable UI without logic leakage.

Mobile UI Slicing Playbook

Overview

Build UI in thin, verifiable slices so each commit changes one concern: structure, styling, state wiring, interactions, and edge states.

Workflow

1. Detect target stack

• Compose: @Composable, Modifier, ui/ packages.
• XML View system: res/layout/*.xml, adapters, custom views.
• Flutter: Widget trees, build(), feature presentation files.

2. Create slice plan before coding

• Slice 1: static layout skeleton.
• Slice 2: design tokens, spacing, typography, and colors.
• Slice 3: state rendering (loading, content, error, empty).
• Slice 4: interactions and callbacks.
• Slice 5: accessibility, previews/tests, and polish.

3. Implement in minimal deltas

• Keep each slice scoped to one screen/component boundary.
• Keep business rules out of UI files; invoke state/use-case layers only.
• Prefer extracted subcomponents over one giant file.

4. Verify every slice

• Build and run target module.
• Verify one happy path and one edge state per slice.
• If layout-related, validate spacing and alignment on at least one small and one large viewport.

Stack-Specific Rules

Compose

• Split into small composables with clear parameter contracts.
• Hoist mutable state up; keep leaf composables stateless where possible.
• Use previews for key states.

XML

• Keep XML declarative; avoid logic-heavy custom views unless required.
• Move behavior to view-model/presenter/controller layers.
• Reuse styles/themes to avoid duplicated attributes.

Flutter

• Break long build() trees into private widgets.
• Keep state boundaries explicit (Bloc, Provider, Riverpod, or existing pattern).
• Avoid pushing domain logic into widget classes.

Output Format

Use this structure in responses:

# UI Slicing Plan

## Target
- Platform:
- Screen/component:
- Files:

## Slices
1. Skeleton
2. Visual styling
3. State rendering
4. Interactions
5. Verification/polish

## Risks
- ...

## Next Patch
- Exact files to modify
- Minimal diff scope

Guardrails

• Do not refactor unrelated architecture while slicing UI.
• Do not mix layout and deep business logic in the same patch.
• Keep patches reversible and easy to review.

Resources

• Run scripts/ui_slice_snapshot.sh <repo_root> to map UI files and hotspots.
• Use references/ui-slicing-checklist.md for review criteria.