---
name: design-system-architect
description: "Build a complete design system: tokens, components, docs, themes, accessibility audits. Drafts your design system from scratch or refactors an existing one. Tokens via Style Dictionary, components as headless primitives + styled wrappers, MDX docs, full a11y audits, theme variants."
license: MIT
---

# Design System Architect

Design System Architect scaffolds and maintains production design systems end to end: a Style Dictionary token pipeline, headless component primitives with styled wrappers, MDX documentation, theme variants, and WCAG accessibility audits. It's built for frontend engineers and design-system maintainers who need a coherent, multi-platform system rather than a pile of one-off components — whether starting cold or untangling an existing CSS-variable mess.

## When to use it

- You have Figma tokens (or a spreadsheet of hex values) and want a real token build that emits CSS, JS/TS, and native formats.
- An existing component library has inconsistent spacing, hardcoded colors, and no dark mode, and you want it refactored onto tokens.
- You need a documented, audited component set before handing off to a larger team.
- You want light/dark plus brand themes generated from one source of truth.

## How it works

Tokens are authored as W3C-style JSON and compiled with **Style Dictionary** (`config.json`, `StyleDictionary.buildAllPlatforms()`), producing `css/variables.css`, `js/tokens.ts`, and optional `scss`/native outputs. Custom transforms (e.g. `size/rem`, `color/css`) and a `filter` per platform are wired automatically. Components are scaffolded in two layers: unstyled **Radix UI primitives** (or React Aria, your choice) wrapped in token-driven styled components, so behavior and accessibility stay decoupled from theming. Docs are emitted as **MDX** consumable by Storybook (`*.stories.tsx` + `*.mdx`) or a Docusaurus site. Accessibility audits run via **axe-core** against rendered stories, plus contrast checks against your color tokens, with failures reported per component.

## Example

```bash
curl -fsSL --create-dirs -o ~/.claude/skills/design-system-architect/SKILL.md https://claudeskil.com/skills/design-system-architect/SKILL.md

# in your repo
claude "scaffold a design system from tokens/figma-export.json,
        headless via Radix, output CSS + TS, add a dark theme"
```

A token source it understands:

```json
{
  "color": { "brand": { "500": { "$value": "#2563eb", "$type": "color" } } },
  "space": { "md": { "$value": "16", "$type": "dimension" } }
}
```

Then: `npm run build:tokens` (Style Dictionary) → `npm run storybook` to view docs and run the audit.

## Tips & gotchas

- Keep **reference (primitive)** tokens separate from **semantic alias** tokens (`color.brand.500` vs `color.action.bg`). Theming swaps aliases only — don't let components reference primitives directly.
- Themes are layered as additional CSS custom-property scopes (`[data-theme="dark"]`), not separate stylesheets, so SSR doesn't flash.
- Style Dictionary's default `name/cti/kebab` transform changes key casing; if your CSS variable names look wrong, check the configured `transformGroup` before editing output by hand.
- The a11y audit catches contrast and ARIA issues but not focus-order logic — review keyboard traversal manually.

## FAQ

**Does it lock me into Radix?** No. Radix is the default headless layer; React Aria or Ark UI can be specified, or you can request pure-CSS primitives.

**Can it refactor an existing system instead of greenfield?** Yes — point it at your current components and CSS; it extracts hardcoded values into tokens and rewrites references incrementally.

**What does the audit actually check?** axe-core rule violations on rendered stories plus computed contrast ratios against WCAG AA/AAA thresholds, reported per component.