GO BACK

design.md and your component library: how to scale a design system AI won't outgrow

Jun 4, 2026 • Dianne Alter

Most design.md files top out at "here are my brand colors."

That's fine when you're styling a landing page. But the moment you point an AI agent at a real product — dozens of components, layered states, edge cases that only make sense in context — a surface-level design.md stops being enough. The agent has the palette and the fonts, so it produces something that's on brand, but it still guesses at which component to use, how a variant behaves, and what it should never do. You end up with output that looks like your product and behaves like a stranger's.

I've been pushing past that ceiling, and the fix isn't a longer design.md. It's a lightweight design.md that knows where the complexity lives — one that points the agent to your component library's metadata instead of trying to hold every rule itself. In this guide I'll show you how to build the standard design.md from a real repo, then take it one level deeper so it can carry a complex product without bloating into something nobody maintains.

Table of contents

What it means to connect design.md to your component library

A design.md file is a plain-text design system written for AI agents — YAML front matter with machine-readable tokens up top, then a markdown body that explains those tokens in plain English. The spec originated with Google Stitch, and the format has caught on because it gives an agent one file to read every time it designs, so it follows your guidelines instead of inventing decisions on its own.

Connecting it to your component library means keeping that file deliberately thin while making it reference the deeper documentation each component already has. The design.md stays high-level — colors, type scale, spacing, the feel of the brand — and for anything component-specific it says, in effect: "this is the button; open its metadata file before you build with it." The complexity doesn't live in the design.md. It lives in the component metadata, and the design.md just knows the address.

In practice, a connected design.md does three things:

  • Defines the system-level rules (tokens, typography, spacing, depth) once, lightly
  • Names each component without restating its full contract
  • Points to a metadata file per component where the variants, relationships, and anti-patterns are spelled out in detail

That last move is the whole game. It's what lets one file stay readable while still covering a product with two hundred components behind it.

design.md vs. a full component spec

A full component spec tries to document every prop, state, and rule inline. That works for one component and collapses across fifty — the file becomes unscannable and the agent drowns in detail it doesn't need yet. A connected design.md inverts it: stay light at the system level, defer the detail to where it's needed, and let the agent pull the deep contract only when it's actually composing that component.

design.md vs. CLAUDE.md and AGENTS.md

Your CLAUDE.md and AGENTS.md are entry points — the first files an agent reads. Your design.md is the design source of truth they should route to. The two aren't interchangeable: the job of CLAUDE.md is to send the agent to design.md ("before creating any UI, read and follow design.md"), and the job of design.md is to define the rules once it gets there.

Why a surface-level design.md breaks on complex products

A design.md pulled straight from a website is the version you see everywhere right now. Drop it in, and your site looks on brand in seconds. It's genuinely useful, and for marketing pages it's often all you need.

The problem shows up when the design has to go into the product. A real application isn't a palette and a font — it's a button that behaves differently in a toolbar than in a dialog, an input with five validation states, a destructive action that needs a confirm step. None of that fits in a surface-level file, and an agent working from one will fill the gaps with whatever it saw most during training. New variants appear. Spacing drifts. A second primary button shows up next to the first because nothing told it not to.

You could try to cram all of that into the design.md. Don't. A file that documents every edge case for every component becomes a file nobody reads or updates, and a stale design system is worse than none — the agent follows rules that aren't true anymore.

Keep it lightweight and point it deeper, and you get the opposite:

  • It scales without bloating. The design.md stays scannable no matter how many components you add, because depth lives in the metadata, not the index.
  • The agent stops hallucinating. Every component decision is documented somewhere the agent can reach, so there's no gap left for it to improvise into.
  • Your whole team can build. Designers, engineers, PMs, even founders can prompt for a new feature and get something close to pixel-perfect, because the rules are written down once and reused everywhere.

Building a design.md from a real repo

The fastest way to a good design.md is to generate it from a codebase that already has a real design system. I'll use Cal.com — the open-source scheduling platform — because it's public, it's genuinely complex, and you can follow along.

Generating the file with the design.md skill

Google Labs published a Claude Code skill that knows the design.md spec cold. Install it per-project or globally through the CLI, and it gives you four moves: validate an existing design.md for structural correctness, compare yours against the standard, convert a design into tokens, or run a full spec against a repo. (Adding it as a project dependency will trip the CLAUDE.md "ask before adding dependencies" prompt — that's expected; approve it for the one project.)

The setup: I worked on a dedicated branch so the generation couldn't touch anything live, then pointed the skill at the whole repo — components, Tailwind config, CSS, the theme package — and asked it to build the design.md from the branding it found. What it did, step by step:

  1. Found the design tokens in the theme package and read them
  2. Converted every color to hex, per the spec's requirement (the "Google way" — not always how I'd do tokens, but it keeps everything unambiguous)
  3. Wrote the file, then ran its own lint command to check itself
  4. Caught and fixed an inconsistency on its own — a size named 2XL that should have been XXL — and noted it wouldn't repeat the mistake

The result: a validated design.md with 28 colors, 10 typography levels, plus defined elevation, shapes, components, and layout. The front matter held the machine-readable tokens; the body translated them into English. It even captured the feel — "Cal is open-source scheduling: trustworthy, precise" — alongside the hard specs: source-of-truth tokens defined as HSL custom properties, a dark mode, a typography rule of weight 600 only, a type scale on Tailwind's default steps, and a layout built on strict 4px spacing. I love when a generated spec uses concrete words like strict — it gives the agent nothing to negotiate with.

A note from experience: read the generated file closely and expect to go back and forth. It won't catch everything on the first pass, and when you spot the agent making something up later, that's your cue to come back and tighten the design.md so it can't happen again.

How to take your design.md deeper

Generating the file is step one. Here's how to turn a standard design.md into one that can hold a real product — lightweight on the surface, deep underneath.

1. Wire it into CLAUDE.md and AGENTS.md

The agent reads CLAUDE.md (or AGENTS.md, if you're on Codex or another tool) before anything else, so the routing instruction has to live there, right at the front. Add an explicit rule to both: "Do not forget this step. When creating or modifying any UI, read and follow design.md." Keep the two files as mirrors of each other so it doesn't matter which agent picks up the work — the design source of truth is the same either way.

2. Build a real component library with metadata

This is the layer the deeper design.md will point to. I use Storybook to document every component in one place — whether you're bringing them in from Figma or another tool — and then attach a metadata file to each one. The metadata is where you get obsessive: every size, every variant, the relationships (a button belongs in a footer or a form, not floating on its own), and the anti-patterns written in plain language the agent can act on. Never put two default buttons side by side. Never use a destructive variant without a confirm step. Pair those with the do's and don'ts — use the brand colors, don't introduce new hues; don't use more than two font weights in a single region — and you've left nothing for the agent to improvise.

3. Reference the metadata — don't inline it

Here's the move that keeps everything lightweight. In the design.md, where you describe the button, do not paste the full contract. Add a pointer instead: a system-level summary that says, plainly, "this section intentionally doesn't restate every component's full contract — open the metadata file first when you're ready to build, compose, or modify a button." Then link it to the component's meta file. The agent reads the design.md to understand the system, and only opens the deep metadata at the moment it actually needs the detail.

4. Add the pointer per component

Do the same on each individual component entry. Under the button, add a line: "Reference: open this metadata file before building or composing a button for the full contract." Now the design.md is a map — system rules at the top, and a clearly labeled door to the deep detail next to every component. You can make these pointers as lightweight as you like; the goal is that the agent always knows where to look when it wants to go deeper, without the design.md ever carrying that weight itself.

5. Read it, refine it, repeat

The first generated pass will be roughly 80% right and 20% generic. The system-level rules will be solid; the component anti-patterns will list the obvious ones and miss the ones that actually bite your team. Go in, read every line, and add the rules only you know. As you ship features and catch the agent inventing something, trace it back to the design.md or the relevant metadata and fix it at the source. This is genuinely a lot of work on a large repo — but it's work that compounds, because every fix is one the agent never makes again.

Done across the whole library, this is what lets anyone on the team — not just designers — spin up a new feature and get something close to pixel-perfect on the first try.

Tools and resources

The short, honest list of what I actually reach for when setting this up:

If your team is spending more time fixing what the agent generated than shipping the next feature, the design system is almost always the gap — and a lightweight design.md that points to deep component metadata is how you close it. That's exactly the work we do at TDP: we go into a team's design-to-code process, find where it's breaking, and rebuild it so AI ships features inside the system instead of around it. (I also run paid workshops for teams that want to build this themselves, and help design teams stand up the underlying design system.)

If you want the structure, the metadata schema, and the reference pattern we use with clients — plus the free toolkit my team and I rely on to design and ship faster Want a design-to-code playbook built around your team's workflow? Book a workshop with TDP →

Dianne Alter

Dianne Alter

    Let’s build something awesome together!

    Get Started!