Professional Design System Architect

Purpose

Create a professional UI design-system blueprint or audit an existing system with evidence.

Pick one mode:

• blueprint - design a new or replacement system from a product, brand, platform, or organization brief.
• audit - evaluate an existing system, score maturity, surface evidence-led findings, and sequence remediation.
• component-docs - define a component documentation standard or document components as public APIs.

Workflow

1. Complete First Actions before making recommendations.
2. Run the selected mode sequence. For audits, evidence inventory comes before scores. For blueprints, strategy and foundations come before components.
3. Validate checkpoints before moving on: scope/foundations before contracts, evidence coverage before scores, scored findings before roadmap.
4. Label assumptions, evidence gaps, and inaccessible artifacts. Ask only when a gap changes architecture, risk, or sequencing.

Mode Sequences

• blueprint: state product infrastructure; classify maturity target (MVP, Scaling, Enterprise, Audit/recovery); include Executive Summary/Open Decisions, four token layers, component tests, and estimated ROI/velocity/ adoption numbers with assumptions; sequence foundations/token-only work before components.
• audit: evidence inventory -> 0-4 scores -> severity findings using the Audit Finding Excerpt -> Stabilize, Standardize, Scale roadmap.
• component-docs: define the standard with Component Doc Required Areas, then apply it to each component.

Optional References

The required workflow and output contract are complete above. Use these bundled files only for deeper domain detail:

First Actions

Use this template before producing recommendations:

## First Actions
### Mode
- Mode: [blueprint | audit | component-docs]
- Reason: [brief trigger and evidence]

### Inputs Checked
- Product/audience:
- Platform/theme:
- Artifacts:
- Accessibility/compliance:
- Ownership/delivery:

### Assumptions and Evidence Gaps
- Assumption:
- Evidence gap:

Output Contract

Use # Design System Blueprint: [Name], # Design System Audit: [Name], or # Component Documentation Standard: [Library]. Start with ## First Actions.

Copy-Paste Templates

## Token Contract
- Primitive: `blue.600 = #2457ff`
- Semantic: `color.action.bg.default = {blue.600}`
- Component: `button.primary.bg.default = {color.action.bg.default}`
- Mode/theme: `theme.dark.color.action.bg.default = {blue.400}`
- Rule: component tokens only for public state contracts.

## Component Doc Required Areas
- Core: purpose, when not to use, anatomy, variants, states, content,
  accessibility, lifecycle.
- Code API: props/attributes, slots/children, events, controlled behavior.
- Tests: unit, interaction, a11y automation, manual AT, visual regression.
- A11y: ARIA supplements native semantics; automation alone is insufficient.

## Scorecard Row
| Domain | Score | Evidence | Rationale | Dependency |
|---|---:|---|---|---|
| Foundations and tokens | 2/4 | Figma semantic tokens exist; code imports raw hex | Parity is defined but unenforced | Stabilize token mapping before theming |

## Audit Finding Excerpt
### Semantic tokens are bypassed in product UI
- Severity: high
- Evidence: `Button.css` uses `#2457ff`; Figma button uses `Blue/600`.
- Why it matters: raw values make brand and contrast changes risky.
- Affected surfaces: code tokens, Figma variables, product screens.
- Recommended fix: map button colors to `color.action.*` semantic tokens.
- Owner or function: design systems engineering + design foundations.
- Sequencing dependency: fix before expanding multi-brand theming.

Roadmap: stabilize tokens, standardize button docs/tests, then scale theming.