| name | mobile-ui-playbook |
| description | Use when building or polishing mobile app UI visuals (Flutter, SwiftUI, Jetpack Compose) — before choosing spacing, typography, color, corner radius, elevation, or motion duration; when a screen "looks off", feels cluttered, cheap, or inconsistent; when reviewing touch targets, contrast ratio, Dynamic Type, text overflow, or dark mode; also when hard-coded colors/paddings spread across widgets, or every new screen re-invents its own styling. |
🌐 繁體中文（canonical） · English mirror
Mobile UI Aesthetics Judgment Handbook
"Looks good" is not mystical taste — it is the byproduct of four things: consistency, hierarchy, density, and contrast. This handbook turns them into adjudicable numbers and criteria.
Core principles
- Beauty is a byproduct of consistency: tokens (spacing/type/color/radius) come before screens — screens only consume tokens, never invent values; every "tweak it locally just this once" is borrowing at loan-shark rates.
- A green light under light mode + default font size + big screen + short data counts for nothing: dark mode, enlarged text, small physical screens, and long strings / real data are four independent verification axes — any one of them alone can break your UI.
- Hierarchy is expressed through size, weight, lightness difference, and position — not decoration: shadows, gradients, and dividers are the last 10% of polish, not a remedy for unclear hierarchy.
- Anything tappable must be big enough and look tappable: touch targets ≥44×44pt (iOS) / 48×48dp (Android); interactive elements must be visibly distinguishable from plain text.
- Motion is the narration of state change: appearing/disappearing/moving elements need transitions (small components 100–200ms, screen transitions 250–350ms); beyond 500ms users feel "laggy", not "fancy".
Task triage
| Situation | Path | Read first |
|---|
| Starting a new screen | Confirm spacing/color/type tokens exist, then lay out | references/design-tokens.md |
| Choosing font size, weight, line height | Follow the type scale criteria; ≤4 sizes per screen | references/design-tokens.md §Type |
| Picking colors, building dark mode | Semantic color roles only, never raw hex | references/design-tokens.md §Color |
| Screen "looks off" but can't say why | Run the five-step diagnosis: alignment→spacing→hierarchy→color→density | references/layout-hierarchy.md §Diagnosis |
| Layout, alignment, information density | Single leading edge + 4/8 grid | references/layout-hierarchy.md |
| Adding motion/transitions | Duration and easing ranges | references/layout-hierarchy.md §Motion |
| UI done, ready to ship | Verify all four axes + extreme data, item by item | references/release-checklist.md |
Red lines (absolutely forbidden)
- Never hard-code color values, font sizes, or spacing numbers inside widgets/views — dark mode and redesigns collapse everything; all values go through theme/tokens.
- Never ship touch targets smaller than 44×44pt / 48×48dp — mis-taps and missed taps are the most direct source of "this app feels cheap"; visuals may shrink, hit areas may not.
- Never ship body text below 4.5:1 contrast (3:1 for large text, WCAG AA) — low contrast is simply unreadable in outdoor sunlight; "that's the gray in the mockup" is not a reason.
- Never build dark mode by inverting the light theme color-by-color — dark mode is a re-mapping of semantic roles (surfaces lighten to express elevation, colors desaturate), not an invert.
- Never hard-position with fixed widths/heights copied off the mockup — one long username, one German label, or 130% text scaling will break it; always flexible layout + extreme-data verification.
- Never introduce a 3rd accent color or a 4th corner-radius step on one screen — when tempted, adjudicate at the token layer; no inventing values on the spot.
- Never declare UI done after verifying only light mode + default font size + a big simulator screen — the four axes are independent failure domains with zero evidential overlap.
Failure signals (turn back, don't retry)
| Symptom | Usually means | Fall back to |
|---|
| Every new screen re-decides its padding numbers | Missing spacing token scale | Define the 4/8 scale at the token layer, snap everything |
| Dark mode full of unreadable or glaring elements | Hard-coded colors, no semantic roles | Rebuild the color layer, don't patch spot by spot |
| Layout breaks on language switch or real data | Fixed-size thinking | Flexible layout + re-verify with extreme data |
| "Just a bit more shadow will fix it" for the 3rd time | A hierarchy-structure problem, not missing decoration | Size/weight/spacing hierarchy design |
| Spacing micro-tweaks oscillating back and forth | No grid baseline, aligning by feel | Snap everything to the 4/8 grid first |
| Fix this screen, that screen drifts again | Styles scattered, no single source of truth | theme/token single source |
References index
references/design-tokens.md — spacing scale, type scale, semantic color, dark mode, radius/elevation step counts, machine-enforcing tokens. Read before laying anything out.references/layout-hierarchy.md — alignment, visual hierarchy, density, touch targets, motion durations, the five-step "looks off" diagnosis. Read when a screen feels wrong.references/release-checklist.md — pre-ship UI checks: four-axis verification, extreme data, contrast and touch-target audits. Tick through before shipping.references/test-scenarios.md — judgment quiz set to verify a successor model follows the criteria. Not for the model currently executing tasks.
