Mobile Design System
Turn visual intent and repeated UI behavior into a small, semantic, accessible system that can survive new screens and platform variants.
Establish the input contract
Prefer design-dna.json, ui-design.json, and the selected visual-direction.md. For new or replacement visual work, require the ui-design.json visual lock and consume its selected style family, reference IDs, theme variant, and exact theme tokens. Preserve provenance: inherited values come from an upstream artifact, specified values are deliberate target decisions, and estimated values remain estimates. Never turn a screenshot guess into an observed token.
Build the system in layers
- Define foundations: color roles, type roles, spacing, shape, elevation/material, iconography, motion, content voice, and accessibility rules.
- Copy the locked reference fingerprint into the system thesis and keep the selected semantic theme tokens as the renderer source of truth.
- Define tokens as
primitive → semantic → componentwhere the system benefits from the extra layer. Prefer semantic roles over raw values in screen contracts. - Define components by user meaning and repeated anatomy, not by a generic “card” bucket.
- Specify default, pressed, focused, selected, disabled, loading, success, warning, failure, stale, expired, and permission states as applicable.
- Record light/dark, compact/regular, iOS/Android, large-text, keyboard, Reduce Motion, and localization variants.
- Establish governance: naming, deprecation, change ownership, contrast/target-size checks, and acceptance signals.
Read references/system-rules.md for token and component boundaries. Use references/design-system-schema.md before creating structured output.
Produce and validate
Create:
design-system.mdusing assets/design-system-template.md.design-system.jsonusing assets/design-system-template.json.
Run python3 scripts/validate_design_system.py <path-to-design-system.json> and fix every error. When a UI artifact is available, also validate that every referenced UI token and component has a system definition.
If ui-design.json contains visualExploration, run the validator with --source-ui and reject any Design System whose visualLock is missing, unlocked, or inconsistent with the chosen direction. Never rebuild the system from Design DNA alone after a visual lock exists.
Enforce the output order
- System thesis, scope, and provenance.
- Foundations and semantic tokens.
- Component contracts and state behavior.
- Themes, platform variants, and accessibility pressure.
- Governance, coverage, open questions, and confidence.
Do not finish with a color palette alone, a component gallery with no state semantics, or a system that cannot explain how a new screen consumes its roles.


