mobile-design-system

mobile-design-system: Tokens, Theme, and the SAFE/RISK Proposal

One coherent system, proposed honestly, then written as real files. No screens.

Flow

1. Stack sniff + App Read essentials

Read package.json / tailwind config / existing theme files / MOBILE-DESIGN.md. Detect the styling system (NativeWind, StyleSheet, Tamagui, Paper) - the output format follows it. Establish app kind, audience, platform posture, and dials (one line each; inherit from MOBILE-DESIGN.md when present). Apply the category bias table (mobile-taste SKILL.md 1.A2).

2. The SAFE/RISK proposal

Propose the ENTIRE system as one package, split explicitly:

SAFE CHOICES - the category baseline the user expects. For most apps: system fonts, native chrome, a restrained neutral ramp, platform-conventional radii. Say plainly that these are safe and why safe is right here (or isn't).

RISKS (at least 2, at most 4) - deliberate departures, each with:

RISK: <the move>            e.g. "true-black OLED dark mode as the primary theme"
gain: <what it buys>        "distinctive night identity, battery on OLED"
cost: <what it costs>       "elevation must come from borders, not shadows"

A proposal with zero risks is a template; a proposal that is all risks is a costume.

Coherence validation - if two choices fight (dense pro-tool density + playful rounded type; per-platform posture + a fully custom tab bar), flag it in one sentence and propose the resolution. Flag, never silently "fix".

The proposal covers: palette (semantic tokens: background, surface, text-primary, text-muted, accent, border, destructive - light AND dark values), type scale (display/title/body/caption + Dynamic Type bounds per SKILL.md 6.1), spacing scale, radius scale + shape lock, elevation tokens (iOS shadow + Android elevation pairs), icon family + stroke weight, haptics vocabulary, motion posture (the three dials' implications), and the signature element budget.

Hard rules inherited from mobile-taste 6.2: one accent; one gray family; no indigo pipeline; saturation < 80% default; both modes from day one; OLED pure black allowed only as a declared deliberate choice.

3. Preview (optional, offer once)

Offer a self-contained HTML specimen - one file, no external requests: the palette as swatches (both modes, toggle), the type scale rendered in the actual (system or declared) fonts, radius/elevation samples on mock components. Open it locally. This is the no-tooling path and it is the primary path; do not depend on image generation or external binaries.

4. Write the real files

Per the sniffed stack:

• NativeWind: tailwind.config theme extension + theme/tokens.ts (+ vars() wiring if the project uses CSS-variable theming) + dark values.
• StyleSheet: theme/tokens.ts with typed color/type/spacing/radius/elevation objects and a useTheme() hook honoring useColorScheme.
• Existing token file present: EXTEND it; renaming existing token names is on the never-change-silently list (../_shared/references/redesign-protocol.md).

5. Persist to MOBILE-DESIGN.md

Write (or refresh, with a delta report) the ## Design System section: the approved proposal, the RISK register, and where the token files live. Later sessions and sibling skills read this before any UI decision.

Rules that bind this skill

• Propose once, coherently - not a menu of five palettes to pick from. One system with named risks beats a mood board.
• Every value in the written files traces to the approved proposal. No stowaway tokens.
• If the user rejects a RISK, replace it with the SAFE version and note the swap in MOBILE-DESIGN.md; do not quietly keep it.