Getting Started

Turn your real design system into specs that AI coding agents can reliably follow. Works with CSS variables, JSON tokens, and DTCG format.

The Problem

AI agents are good at implementation, but weak at consistency. They commonly:

Invent values

Pick 12px instead of your spacing token, or a plausible blue instead of your semantic link color

Miss composition rules

Understand a component API but not when and how to combine components

Lose context

Drift between sessions — each conversation starts from scratch

This tool fixes it

Creates a stable, local, project-readable source of truth for agents

Installation

Run directly with npx or install globally.

npx design-system-ai-starter init .

Quick Start

Three commands to go from zero to AI-readable specs:

# 1. Scaffold the structure
npx design-system-ai-starter init .

# 2. Sync your real tokens
npx design-system-ai-starter sync-tokens \
  --input ./tokens.css --target .

# 3. Verify everything is in place
npx design-system-ai-starter doctor .

Who This Is For

Design systems teams

With existing tokens or theme files that agents should respect

Frontend teams using AI

Cursor, Claude Code, Copilot — any agent that writes UI code

Product teams

That want AI to stop inventing colors, spacing, and component behavior

CLI Commands

init

Scaffolds the AI-readable structure into an existing project.

npx design-system-ai-starter init .
FilePurpose
.cursor/rules/design-system.mdcCursor agent rule
CLAUDE.design-system.mdClaude Code guide
AGENTS.design-system.mdGeneric agent guide
specs/foundations/*.mdColor, spacing, typography, radius, motion
specs/tokens/token-reference.mdFull token list
specs/components/_template.mdComponent spec template

sync-tokens

Reads your real token source and updates markdown specs.

npx design-system-ai-starter sync-tokens \
  --input ./tokens.css --target .
FlagDescription
--input <file>Path to CSS or JSON token file
--target <dir>Project directory with specs/

doctor

Checks if all AI-readable files exist and are complete.

npx design-system-ai-starter doctor .
OK Cursor rule: .cursor/rules/design-system.mdc OK Claude guide: CLAUDE.design-system.md OK Token reference: specs/tokens/token-reference.md OK Color foundation: specs/foundations/color.md OK Spacing foundation: specs/foundations/spacing.md OK Typography foundation: specs/foundations/typography.md WARN No detected tokens in specs/foundations/motion.md WARN No component specs found beyond the template Doctor checks passed with 2 warning(s).

Supported Inputs

FormatExample
CSS variablestokens.css with --color-primary: #3b82f6
DTCG JSON{ "$value": "#3b82f6", "$type": "color" }
Custom JSON{ "value": "#3b82f6", "type": "color" }
Name/value arrays[{ "name": "primary", "value": "#3b82f6" }]

Before / After

You already have tokens. This tool creates the agent-readable layer on top.

Before

app/ styles/ tokens.css ← your tokens exist src/ components/ ← but agents can't read them

After

app/ .cursor/rules/design-system.mdc ← Cursor reads this CLAUDE.design-system.md ← Claude reads this AGENTS.design-system.md ← any agent reads this specs/ foundations/ color.md ← 5 color tokens spacing.md ← 6 spacing tokens typography.md ← 6 typography tokens tokens/ token-reference.md ← full token list components/ _template.md ← fill per component

CSS Token Example

Input file with CSS custom properties:

:root {
  --color-primary: #3b82f6;
  --color-secondary: #6366f1;
  --color-text: #0a0a0a;
  --color-bg: #fafafa;
  --color-muted: #737373;

  --spacing-xs: 4px;
  --spacing-sm: 8px;
  --spacing-md: 16px;
  --spacing-lg: 24px;
  --spacing-xl: 32px;
  --spacing-2xl: 48px;

  --font-size-sm: 0.875rem;
  --font-size-base: 1rem;
  --font-size-lg: 1.25rem;
  --font-size-xl: 1.5rem;
  --font-size-2xl: 2rem;
  --font-size-display: 3rem;
}

Run sync-tokens → get structured markdown with tables, categories, and agent-readable format.

JSON Token Example

DTCG-format token file:

{
  "color": {
    "primary": {
      "$value": "#3b82f6",
      "$type": "color"
    },
    "bg": {
      "$value": "#fafafa",
      "$type": "color"
    }
  },
  "spacing": {
    "sm": {
      "$value": "8px",
      "$type": "dimension"
    },
    "md": {
      "$value": "16px",
      "$type": "dimension"
    }
  }
}

Output Structure

What each generated file contains:

FileContents
specs/foundations/color.mdMarkdown table of all color tokens with names and values
specs/foundations/spacing.mdSpacing scale with token names and pixel values
specs/foundations/typography.mdFont sizes, weights, line-heights
specs/foundations/radius.mdBorder-radius tokens
specs/foundations/motion.mdDuration and easing tokens
specs/tokens/token-reference.mdComplete flat list of all tokens
.cursor/rules/design-system.mdcCursor agent rule referencing specs
CLAUDE.design-system.mdClaude-specific instructions with token paths

Pipeline

Pairs with figma-to-design-md for a full Figma-to-AI pipeline:

Figma ──▶ figma-to-design-md ──▶ specs/ │ ▼ design-system-ai-starter ──▶ .cursor/rules/ CLAUDE.md AGENTS.md │ ▼ AI agent uses specs when writing code
View onGitHub →