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

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:

{
  "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.