Agentic Design System Starter Kit

What this is

Most design systems break the moment AI tools touch them. Tokens have unclear names. Components live in code but their intent lives in someone’s head. Claude has to guess.

This kit fixes that. It is a complete folder structure you drop into any project to make your design system machine-readable from the first prompt. Path-scoped rules, a knowledge graph, component intent maps, token schemas — the whole infrastructure that lets AI actually understand your system instead of pretending to.

I built this for myself after watching Claude Code hallucinate tokens for the fifth time in one week. It is the single biggest quality upgrade you can make to AI-assisted design system work.

Download

The starter kit is a zip with the full folder structure ready to drop in. 14KB.

Download starter kit (.zip)

What’s inside

starter-kit/
├── CLAUDE.md                          # Project context (loaded every request)
├── .claude/
│   ├── rules/
│   │   ├── token-naming.md            # Loaded only when working with tokens
│   │   ├── component-conventions.md   # Loaded only when working with components
│   │   └── code-generation.md         # Loaded only when writing code
│   └── skills/
│       └── audit-tokens/SKILL.md      # Reusable token audit skill
├── .design-system/                    # The knowledge layer
│   ├── CLAUDE.md                      # Explains this folder to Claude
│   ├── token-schema.json              # What makes a valid token
│   ├── knowledge-graph.json           # Component-token-pattern relationships
│   ├── component-intent.json          # When/where/why for each component
│   └── naming-conventions.md          # Human-readable naming rules
├── tokens/
│   ├── CLAUDE.md                      # Token folder context
│   ├── primitives.json                # Base values (edit these)
│   └── semantic.json                  # Semantic aliases (edit these)
└── src/
    └── components/
        └── CLAUDE.md                  # Component folder context

Why this structure works

Most CLAUDE.md files are one giant file with everything. Claude reads it on every request, even when most of it is irrelevant. This kit splits context across path-scoped rules so Claude only loads what matches the file you are working on.

Editing tokens? Only token-naming.md loads. Building a component? Only component-conventions.md loads. Writing code? Only code-generation.md loads.

The result: faster responses, more accurate output, and Claude that actually respects your conventions instead of inventing new ones.

Setup steps

1. Drop the kit into your project

Unzip and copy everything into your project root. The hidden folders (.claude/, .design-system/) will be picked up automatically by Claude Code.

2. Edit the project CLAUDE.md

Open the root CLAUDE.md and replace the placeholder values:

# Project name: [YOUR PROJECT NAME]
# Component count: [X]
# Token count: [Y]
# Last updated: [DATE]

3. Customize the token schema

Open .design-system/token-schema.json and adjust:

• Categories you actually use (color, spacing, typography, etc.)
• Naming intents (background, foreground, border, etc.)
• Abbreviations your team uses (xs, sm, md, lg)

4. Add your components to the knowledge graph

Open .design-system/knowledge-graph.json and add an entry for each component:

{
  "name": "Button",
  "tokens": ["color.background.primary", "spacing.md", "radius.sm"],
  "patterns": ["interactive", "feedback"],
  "context": "Use for primary actions only. Never as a link."
}

5. Run your first AI audit

In Claude Code:

Audit my design system. Use the rules in .claude/ and the schema in .design-system/.
Tell me which components do not follow conventions.

Claude will load only the relevant rules, check against your schema, and give you a real audit instead of generic AI guesses.

What you get

After dropping this in:

• A design system Claude understands from prompt one
• Path-scoped rules that load only when relevant (faster, more accurate)
• A reusable token audit skill
• A knowledge graph mapping components to tokens to patterns
• A CLAUDE.md infrastructure your future projects can reuse

Common pitfalls

• Skipping the customization step. The default values are placeholders. Claude will still hallucinate if you do not put in your real conventions.
• Mixing this with an existing CLAUDE.md. If you already have one, merge carefully. Path-scoped rules in .claude/rules/ should not duplicate content from the root CLAUDE.md.
• Forgetting to update the knowledge graph. Every new component should be added. Otherwise Claude treats it as unknown.

Related