How to Give an LLM a Design System Without Dumping the Whole RepoHow to Give an LLM a Design System Without Dumping the Whole Repo

The instinct is to point the LLM at your component library and let it figure out the design system. This produces code that uses your component names but reaches into internal props, ignores the spacing scale, and occasionally resurrects a deprecated pattern that still exists in the file but hasn't been used in two years. The problem isn't that the LLM is bad at reading code — it's that your component library was written for humans who already understand the system. An LLM needs a different artifact: a minimal, explicit, LLM-specific reference document.

---

Why Your Existing Docs Won't Work

Your README explains how to install the package and run Storybook. Your Storybook shows every prop variant with examples. Your design system site has the rationale behind each decision. None of these are optimized for LLM consumption.

The README is for onboarding humans. The Storybook is interactive — useful for browsing, useless as text context. The rationale docs are valuable for understanding, not for generating code. When you dump any of these into context, you get noise: lengthy prose explanations, deprecated examples, variant documentation for edge cases, installation instructions that take up tokens without contributing to output quality.

The other problem: component library source code is messy from an LLM perspective. It contains internal utilities, test files, deprecated exports, internal prop names that shouldn't be used directly, and type overloads that confuse the surface area. The LLM has no way to know which parts are the public API and which parts are implementation details.

---

What the LLM Actually Needs

To generate on-brand component code, the LLM needs:

• Available component names and their key props — specifically, the props that control visual variant (not every prop, just the ones that change appearance)
• Token names — color roles, spacing scale values, typography tokens, as they're named in your system
• Composition patterns — how components nest, what wraps what, what's a layout component vs a content component
• The constraints — what you don't do (hardcoded colors, magic pixel values, non-token spacing)

That's it. A document that answers those four questions produces better AI output than a full component library dump, because the signal-to-noise ratio is dramatically higher.

---

The ai-reference.md Pattern

Write a file specifically for LLM consumption. Not a README. Not component docs. A structured reference that answers exactly the questions above, in a format that's efficient as context.

Here's a representative excerpt:

# Design System AI Reference
> Use this file as context when generating component code.
> Do not use hardcoded colors, hex values, or pixel values — use token names.

## Available Components

### Layout
- `Stack` — vertical or horizontal flex container. Props: `gap` (token name), `align`, `justify`
- `Grid` — CSS grid wrapper. Props: `columns` (number or responsive obj), `gap`
- `Center` — centers content horizontally. No required props.

### Primitives
- `Text` — all body text. Props: `size` (xs/sm/md/lg/xl), `weight` (regular/medium/bold), `color` (token name)
- `Heading` — h1–h6. Props: `level` (1–6), `size` (overrides semantic level if needed)
- `Button` — Props: `variant` (primary/secondary/ghost/destructive), `size` (sm/md/lg), `loading` (boolean)
- `Icon` — Props: `name` (from icon set below), `size` (sm/md/lg)

## Token Reference

### Color Roles (use these names, never hex values)
- `color.surface.default` — page background
- `color.surface.raised` — card, panel, popover backgrounds
- `color.text.primary` — primary readable text
- `color.text.secondary` — secondary/muted text
- `color.text.disabled` — disabled state text
- `color.border.default` — standard borders
- `color.accent.default` — primary brand action color
- `color.accent.hover` — hover state for accent elements
- `color.feedback.error` — error states
- `color.feedback.success` — success states

### Spacing Scale (use token names, not pixel values)
- `space.1` = 4px
- `space.2` = 8px
- `space.3` = 12px
- `space.4` = 16px
- `space.6` = 24px
- `space.8` = 32px
- `space.12` = 48px

### Typography
- Font family: inherit from body (do not set font-family directly)
- Scale: use Text or Heading component size props — do not use arbitrary rem values

## Composition Patterns

Cards: `Box` with `shadow="sm"` and `padding="space.6"`. Use `Stack` inside for content.
Form fields: `FormField` wraps `Label`, `Input` or `Select`, and `HelperText`. Do not place Input without FormField.
Page sections: `Section` → `Container` → content. Do not use raw divs for page structure.

## What Not to Do

- Do not use hardcoded colors: no `#fff`, no `rgb()`, no CSS named colors
- Do not use magic pixel values in style props: use token names
- Do not reach into internal component files — use only named exports from `@acme/ui`
- Do not use deprecated components: Avatar (use UserAvatar), Spinner (use LoadingIndicator)

---

How This Differs from a README

A README answers: what is this, how do I install it, how do I use it for the first time. An ai-reference.md answers: given that you're generating code right now, what are the exact names and constraints you need?

The format choices are deliberate. Short bullet lists over prose. Token names as literal strings, not described in words. "Do not" rules explicitly stated rather than implied. Component props listed as they appear in JSX, not in TypeScript interface notation.

The goal is for the LLM to be able to answer "what's the token name for primary background?" and "what variant do I use for a destructive button?" without reading more than a few lines. Low friction, high precision.

---

Maintaining the Reference

The risk with any LLM-specific document is that it drifts from the actual system. A component gets renamed, a token gets updated, a pattern gets deprecated — and the ai-reference.md is still pointing at the old version.

Two things help: keep the document short (less to update), and put it on the same review checklist as the component docs. When a breaking change ships in the design system, the ai-reference.md update should be in the same PR.

Some teams generate the ai-reference.md automatically from the token source files and component type exports — a build step that extracts component names and prop types into the reference format. This keeps it in sync without manual maintenance. The output won't be as clean as a hand-written version, but it's accurate.

---

Putting It in Claude Code's Context

In a project CLAUDE.md file, add a line pointing to the ai-reference.md:

## Design System
When generating component code, read /docs/ai-reference.md first.
Use only the component names, token names, and patterns listed there.

This means any Claude Code session in that project starts with a pointer to the right context. The LLM reads the reference when it's about to generate UI code, applies the constraints, and produces output that uses your actual token names and component patterns.

The difference in output quality is significant. Not because the LLM suddenly understands your design system better — but because it has the exact names it needs to produce correct code, without wading through noise to find them.

That's the whole trick: give the LLM the right artifact, not the most artifact.