Design System Doc

Use this skill whenever work touches UI, visual design, theming, motion, layout, component variants, or brand expression on any platform.

Objective

Keep <repo-root>/DESIGN.md as the authoritative present-state design doctrine: language, style, interaction character, and system-level constraints across platforms.

Required Workflow

1. Resolve repository root and open DESIGN.md.
2. If missing: create a concise doctrine-style DESIGN.md focused on principles and aesthetic rules.
3. Read current constraints before editing UI code: design language, hierarchy, motion posture, accessibility baseline, and platform expression.
4. Implement with strict adherence to documented system rules.
5. If divergence is required, update the doctrine directly (current state), preferring reusable rules over one-off exceptions.
6. Update DESIGN.md in the same task:
   • changed principles/language/aesthetic constraints
   • changed semantic token intent or interaction posture
   • per-platform expression updates (web, ios, optional macos)
   • remove stale implementation-specific detail that does not define durable system rules
7. In delivery notes, reference what was enforced and what was updated in DESIGN.md.

Enforcement Rules

• Keep DESIGN.md designer-authored in tone: normative, concise, and principle-led.
• Avoid decision logs, rationale trails, ticket references, and per-feature implementation diaries.
• Avoid overly granular component inventories unless they describe reusable system primitives.
• Preserve established design language/vibe unless a rebrand is explicitly requested.
• Codify typography as system behavior:
  • semantic hierarchy before visual decoration
  • explicit role->size->weight->line-height mapping
  • prose measure targets (typically ~45-75 chars)
  • body leading ranges for sustained reading (typically ~1.2-1.45)
  • spacing policy for letter/word/line/paragraph rhythm
  • glyph policy (real quotes/dashes/ellipsis; no faux styles or stretched text)
  • long-form line-break policy (widow/orphan/rivers/ladders handling)
• Record accessibility implications per platform (for example WCAG contrast/focus for web, Dynamic Type/VoiceOver/reduced motion for iOS).
• Keep semantics stable: one visual cue should map to one meaning.
• Keep DESIGN.md concise and scannable; short sections and rule lists over long narrative.
• For mobile navigation overlays, codify explicit rules for target sizes, section/link type hierarchy, safe-area behavior, modal focus behavior, and zero-layout-shift open/close behavior.

File Convention

• Canonical path: <repo-root>/DESIGN.md
• Prefer stable headings (for example scope, language, principles, accessibility, governance) for diff clarity.
• If a platform is not in scope, mark it as N/A.

Output Contract

• For implementation tasks: deliver code changes + DESIGN.md updates together.
• For review tasks: deliver findings + concrete DESIGN.md patch suggestions.

Local Cross-References

• design-typography-system-doc - create/maintain canonical TYPO.md with strict ratio-based typography rules.
• frontend-design - implementation companion for applying doctrine constraints in production UI code.
• design-quality-gates - Mandatory objective gate checks for layout, type, hierarchy, color, and accessibility before design sign-off.
• design-interaction-motion-craft - Motion/interaction doctrine for transitions, gestures, causality, and timing consistency.
• ios-hig - Use for fast HIG-aligned decisions while editing UI and design tokens.
• ios-hig-ref - Use for detailed guideline lookups backing durable DESIGN.md updates.
• ios-liquid-glass - Use when introducing or refining iOS 26 material behaviors in the design system.
• ios-swiftui-layout - Use when layout constraints should become documented system-level rules.
• ios-typography-ref - Use for type hierarchy and Dynamic Type standards in DESIGN.md.
• ios-sf-symbols - Use for iconography policy and symbol behavior consistency.
• css-grid-overlay-debug - Use when grid guide rendering (columns/rows/gutters/subgrid) needs deterministic instrumentation and debugging.