What Is an Agentic Design System? (Part 1)

The short version

Your design system is probably unreadable to AI. Not because AI is dumb. Because your system was built for humans, and humans fill in gaps that machines cannot.

An agentic design system is one that AI tools can actually use. It has tokens an agent can parse. Components with intent documented, not just styling. Rules Claude Code respects. Context files that load on demand. The same design system, but readable by a second audience: agents.

This matters because the people using AI to generate UI (designers, engineers, PMs) are finding that their design system does not survive the trip. AI hallucinates components that do not exist. It invents token names. It mixes variants. The output looks plausible but ships broken.

The fix is not a better prompt. The fix is a system that the agent can read.

---

---

Who this is for

This is the foundation piece of the Agentic Design System series. Read this first if:

• You use Claude, Cursor, Figma Make, or any AI tool to generate UI
• You are tired of AI inventing components or mixing up tokens
• You want to know what “agentic” actually means for design systems
• You are curious why your system works fine for humans but breaks with agents

---

The traditional design system was built for two audiences

For 15 years, design systems have served designers (via Figma libraries) and engineers (via code libraries). Documentation lives in one place. Tokens in another. Design intent in people’s heads. Naming conventions in a Slack thread somewhere.

Humans can fill in the gaps. An engineer reading “use the primary button” knows what that means because they have context. They know the brand. They know which button counts as primary. They know not to use it for dangerous actions.

An agent does not have that context. It reads what is in front of it and guesses the rest.

---

What makes a design system agentic

Six traits, each fixable in an afternoon.

System Agentic DS Built for humans and AI to read

• Trait 01 Readable Tokens Category, intent, and scale
• Trait 02 Readable Components Documented intent, not just styling
• Trait 03 Readable Rules Path-scoped, loaded contextually
• Trait 04 Readable Knowledge graph How the pieces connect
• Trait 05 Readable MCP Live access to the source of truth
• Trait 06 Readable Verification Automated drift checks

1. Every token has a category, intent, and scale that an agent can parse

Bad: blue-2, theme-color-7, primaryBtnBg

Good: color.background.primary, spacing.md, radius.sm

The naming pattern is consistent, predictable, and parseable by a machine. When Claude sees color.background.primary, it knows that is a background color, and that it is the primary role. No guessing.

2. Components have documented intent, not just styling

Traditional docs say: “Button component. Padding 16px. Border-radius 8px.”

Agentic docs say: “Button is used for primary actions only. Never use it as a link. It has three variants (primary, secondary, tertiary) that map to action importance. It is the wrong choice when you need an inline action; use Link instead.”

The agent now knows when to use the component, not just what it looks like.

3. Rules are path-scoped, not dumped in one giant file

An agentic system loads rules contextually:

• Working on tokens? Load .claude/rules/token-naming.md
• Working on components? Load .claude/rules/component-conventions.md
• Writing code? Load .claude/rules/code-generation.md

This keeps context windows small and responses accurate. One giant CLAUDE.md file means Claude reads everything on every request, and quality drops.

4. A knowledge graph connects the pieces

A JSON file that says: “Button uses color.background.primary, spacing.md, radius.sm. It belongs to the interactive pattern. It appears in these flows: checkout, signup, onboarding.”

An agent reading this can generate new UI that respects how pieces connect. Without it, the agent generates in isolation and creates drift.

5. MCP or similar gives agents live access

MCP (Model Context Protocol) lets AI tools read your Figma file, your token JSON, your component library in real time. No stale export. No copy-paste mistakes. The agent reads the source of truth directly.

6. Verification is automated

An agentic system includes checks that flag drift: tokens used that do not exist, components invented, accessibility rules violated. The agent generates. The verifier catches mistakes before they ship.

---

Why this matters now

Three things changed in the past year:

1. AI generates UI faster than humans can review it. Your team is shipping AI-assisted code whether you planned for it or not.
2. Hallucination kills trust. One AI-generated button with the wrong color token erodes the whole system.
3. The tools exist. MCP, Claude Code skills, path-scoped rules, and context folders are all real, shipping, production-ready technology.

The teams that make their system agentic now will ship faster and with fewer bugs. The teams that wait will spend the next year cleaning up AI-generated drift.

---

---

How this is different from a traditional design system

Traditional design system	Agentic design system
Readable by humans	Readable by humans and agents
Tokens named for aesthetics	Tokens named for parseability
Components documented for style	Components documented for intent
Rules live in people’s heads	Rules live in .claude/rules/ files
Context loaded manually	Context loaded on demand (path-scoped)
Drift caught in QA (if ever)	Drift caught by automated verification
Source of truth: Figma or code	Source of truth: shared, MCP-accessible

Neither is wrong. The agentic version is the traditional version plus an extra audience (the agent).

---

Common misunderstandings

• “I need to rebuild my design system.” No. You need to add a layer. The existing tokens, components, and docs stay.
• “Agentic means autonomous.” No. Agents still follow the system. The system needs to be readable enough for them to follow it correctly.
• “This is just for engineers.” No. Designers benefit most, because it stops AI from inventing UI that bypasses your system.
• “MCP is optional.” For now, yes. In 12 months, it will be table stakes.

---

Where the rest of the series goes

This is Part 1. The next four parts each expand on one piece of the foundation. They publish over the coming weeks.

Part	Title	What it covers
1	What Is an Agentic Design System? (this piece)	The foundation: what agentic means, why it matters, the six traits
2	Trust Levels: How Agents Earn Autonomy	The five levels (Observer, Advisor, Junior, Senior, Autonomous) and how to move between them
3	Observer Mode: Learning Before Acting	How to run a DS audit for months before giving the agent any authority to change things
4	The Self-Healing Flywheel	When and how an agent can start fixing issues autonomously, and the guardrails you need
5	Building the Agentic Operating Model	Team structure, workflow redesign, and the governance patterns that make this sustainable

Want to be notified when each part drops? The weekly newsletter covers the whole series as it publishes.

---

Exercise

Audit your design system against the six agentic traits

25 min

1. Score your system against the six traits

   Open a blank doc. List the six traits from this guide. For each one, write a one-line honest answer: present, partial, or missing. Add a one-sentence note explaining the answer (e.g., “Tokens parseable: partial. Colors use dot notation, spacing uses kebab-case.”).

   • Every trait has a label (present, partial, missing) and a note grounded in real files, not hopes
   • At least one trait is labeled missing (this is normal; a fully agentic system is rare)
   • You can name the exact file that fails the weakest trait

2. Pick one fix and ship it inside the week

   From the missing or partial traits, pick the one with the smallest surface area. Common choices: write a first .claude/rules/token-naming.md, add intent to one component doc, or generate a knowledge graph JSON for a single component. Commit the change with a message that references the trait you addressed.

   • The fix lives in a real file in the repo, not a doc or a ticket
   • The commit message names which trait moved from missing or partial to present
   • The next time Claude works in that path, it reads the new rule or doc automatically