---
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:

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

Recommended:

```text
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:

```text
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`