version: "1.0.0" name: design-system-governor description: | This skill should be used after visual-spec-review passes and before OpenSpec UI update or frontend implementation. It expands screenshot-derived visual specs into a production design system by adding interaction states, responsive behavior, accessibility rules, UX checklist, and implementation constraints without overriding UI type, layout paradigm, component tree, rejected assumptions, or asset strategy. argument-hint: "[visual-spec-directory]"

Version: 2.0.0

design-system-governor

Expand a reviewed visual spec into a product-grade design system.

This skill reads the seven visual-to-spec files and optional visual-spec-review results. It adds the missing product-level rules that static screenshots cannot show: states, responsive behavior, accessibility, motion, and implementation constraints.

It must never redesign the UI or override screenshot-derived facts.

Trigger Conditions

Use this skill when:

• visual-spec-review has passed or conditionally passed
• the user asks to build or expand a design system from visual specs
• the user asks to add hover/focus/loading/empty/error states
• the user asks to add responsive and accessibility rules
• the visual spec must be prepared for OpenSpec UI update or Codex implementation

Required Inputs

Read:

03_visual_spec/
  visual-analysis.md
  layout-spec.md
  component-tree.md
  DESIGN.md
  tokens.json
  implementation-risks.md
  human-review-needed.md

Recommended:

04_visual_spec_review/
  spec-review-report.md
  conflict-log.md
  revised-files-needed.md

If spec-review-report.md says Fail, stop. Do not generate 05_design_system/.

Source of Truth

1. reference.png — visual appearance
2. visual-analysis.md / UI Type Classification
3. visual-analysis.md / Visible Element Inventory
4. visual-analysis.md / Rejected Assumptions
5. layout-spec.md / Layout Paradigm
6. layout-spec.md / Layer Model
7. component-tree.md
8. component-tree.md / Prohibited Components
9. implementation-risks.md / Asset Strategy
10. DESIGN.md
11. tokens.json
12. human-review-needed.md

Required Sections to Read

From visual-analysis.md:

• UI Type Classification
• Visible Element Inventory
• Rejected Assumptions

From layout-spec.md:

• Layout Paradigm
• Layer Model
• Region Layout
• Forbidden Layouts

From component-tree.md:

• Component Tree Type
• bboxRef for reference-visible components
• Prohibited Components

From implementation-risks.md:

• Asset Strategy
• UI Type Drift Risks
• Asset Misuse Risks
• Hallucinated Component Risks

From DESIGN.md:

• UI Type and Rendering Strategy
• Asset Strategy
• Forbidden Assumptions
• Implementation Rules

From tokens.json:

• source
• confidence
• strictness
• usedBy
• bboxRef if present

Main Workflow

1. Confirm visual-spec-review did not fail.
2. Read UI Type and Layout Paradigm.
3. Read Rejected Assumptions and Prohibited Components.
4. Read Asset Strategy.
5. Branch design-system generation by UI Type.
6. Generate component states only for allowed components.
7. Generate responsive rules without changing layout paradigm.
8. Generate accessibility rules.
9. Generate implementation constraints.
10. Write 05_design_system/.

Hard Rules

• Do not override screenshot-derived values.
• Do not change UI Type.
• Do not change Layout Paradigm.
• Do not change Asset Strategy.
• Do not add prohibited components.
• Do not add rejected layouts.
• Do not invent dashboard components for non-dashboard UIs.
• Do not redraw raster/photorealistic main visuals with CSS/SVG if Asset Strategy forbids it.
• Do not generate frontend code.
• Do not modify 03_visual_spec/.
• Do not modify 04_visual_spec_review/.
• Do not merge this skill with implementation or validation skills.

Output

Write:

05_design_system/
  MASTER.md
  pages/
    target-page.md
  ux-checklist.md
  component-state-spec.md
  responsive-spec.md
  accessibility-spec.md
  implementation-constraints.md

Supporting Files

Read these references directly:

• references/governance-workflow.md
• references/ui-type-branching-rules.md
• references/state-rules.md
• references/responsive-rules.md
• references/accessibility-rules.md
• references/asset-aware-design-rules.md
• references/implementation-constraints-rules.md
• references/external-skill-usage.md
• references/output-files.md

Examples:

• examples/master.example.md
• examples/target-page.panorama.example.md
• examples/target-page.dashboard.example.md
• examples/component-state-spec.panorama.example.md
• examples/component-state-spec.dashboard.example.md
• examples/responsive-spec.example.md
• examples/accessibility-spec.example.md
• examples/implementation-constraints.example.md