---

name: design-system-governance description: Enforces token-first, composition-first governance for any design system project. Auto-detects the project's token naming conventions, grid system, animation keyframes, and shared component library before applying rules. Use when building UI components, composite layouts, pages, design tokens, or Storybook stories — or when the user mentions design tokens, hardcoded styles, component reuse, animations, i18n text, or design system governance.

Design System Governance

Phase 0: Discover Project Conventions (Always First)

Before any implementation, scan the project to establish:

| Convention | Where to look | What to find | |---|---|---| | Token naming | src/styles/, *.css, *.scss, tokens/ | prefix for ref / sys / comp layers (e.g. sd-ref-, --color-) | | Token layer structure | Token files | Are there 3 layers (ref → sys → comp) or 2 (primitive → semantic)? | | Grid / layout system | CSS, HTML templates | Class prefix for page grid, cell spans, color variants | | Animation keyframes | CSS files | Keyframe name prefix, motion token names | | Shared components | src/components/, Storybook | List of available shared components | | i18n source | src/, locales/, i18n.json | Path to display text source file |

Record findings before proceeding. If the project has no token system, stop and ask the user whether to establish one first.

---

Mandatory Workflow

1. Check if an existing shared component satisfies the requirement.
2. If new visual semantics are needed, define or extend tokens first (using discovered layer structure).
3. Follow token inheritance strictly: ref → sys → comp (or project equivalent).
4. Implement or update the component only after token mapping is confirmed.
5. Add or update Storybook stories to cover key visual states.
6. If any required token or component is missing, stop and ask the user before continuing.

---

Blocking Decision Gates

Token Gate

Stop immediately when:

• No matching component-layer token exists for the required state/variant.
• No semantic-layer token exists for the required role mapping.

Required response:

• Ask user whether to create the required tokens.
• Do not use hardcoded fallback values.
• Do not create tokens without user confirmation.

Composition Gate

Stop immediately when:

• A composite component or page section requires a child component that does not exist in the shared component library.

Required response:

• Attempt composition from existing components first.
• If not possible, ask user whether to create a new shared child component.
• Do not create one-off inline subcomponents without approval.

Ask Templates

Use these exact prompts (adapt layer names to the discovered project convention):

• Missing token: 找不到對應的 design token（sys/comp 層）。是否要先建立這組 token，再繼續元件開發？
• Missing component: 目前既有元件無法完整組裝此組件。是否要先建立新的共用子元件，再繼續？

---

Design Principles (Universal)

Apply all ten when writing or reviewing UI:

1. Character-first visual focus — strong personality over generic appearance.
2. Saturated accent colors on neutral surfaces — avoid muted-on-muted combinations.
3. Rounded, friendly geometry — pill-like interactive affordances; avoid sharp corners on interactive elements.
4. Section-based narrative rhythm — modular page blocks with clear entry points.
5. Bold display scale — use large display typography (36–96px) for brand and hero contexts.
6. Dense content with scan hierarchy — group related elements; support F-pattern and Z-pattern reading.
7. Foreground–background contrast pairing — every background token must have a paired on-* foreground token. Never assume white or black text.
8. Emotional visuals with explicit accessibility states — hover, focus-visible, disabled states must all be defined.
9. Purposeful motion — use token-driven durations and easings; staggered entrance; ambient phase-offset animations.
10. Layered surface depth — use the project's surface container and elevation system; avoid flat single-surface layouts.

---

Non-Negotiable Constraints

• No hardcoded color literals (#hex, rgb, hsl) in component code — always use tokens.
• No hardcoded spacing/radius/typography values when tokenized alternatives exist.
• No cross-layer token bypass — comp tokens must not reference ref tokens directly.
• No new components without approval — see Composition Gate.
• No animation ms values or cubic-bezier literals — always use discovered motion tokens.
• No display text in templates — all user-facing strings must come from the project's i18n source file.

---

Token Layer Rules

Apply using discovered project prefixes:

| Layer | Role | Required naming pattern | |---|---|---| | ref | Raw values only (palette, spacing, radius, type scale, elevation) | project's ref prefix | | sys | Semantic roles mapped from ref (color roles, shape roles, motion roles) | project's sys prefix | | comp | Component-facing slots referencing sys only | project's comp prefix |

---

Animation Governance

• Entrance animations: use the project's enter keyframe + stagger delay custom property per element (60–80ms increment per step).
• Ambient animations (float, pulse): use animation-delay phase offset across multiple elements — never identical timings.
• Hover transitions: use motion tokens for duration + easing. Patterns: lift (translateY), scale, or focus-fade.
• All keyframe names must use the project's established prefix to avoid global conflicts.

---

Page Composition Rules

• Use the project's grid container class as the page root.
• Each section is a grid cell with span and color variant classes.
• Color variant classes must auto-apply matching on-* foreground tokens.
• Responsive breakpoints: follow the project's established breakpoints (typically 960px / 600px step-down).

---

Storybook Story Requirements

For every changed component, include stories covering:

• Default — base appearance.
• Hover — if the component has interactive hover state.
• FocusVisible — keyboard focus ring.
• Disabled — if the component supports disabled state.

For composite components, include a composition story showing assembly from existing shared components.

---

Output Contract

When proceeding after user approval, always report:

• Which existing components were reused.
• Which tokens were reused or newly created.
• Why new tokens/components were necessary.
• Which stories were added or updated.

---

Additional Reference

• principles.md — extended rationale for each design principle.