Building a Design System AI Agents Can Read
AI agents are guided by how to structure design system guidelines so they can accurately understand a product design system and generate UI/code.
Problem Statement: Visual design alone is not enough
- Even if you use Figma MCP or AI tools to instantly generate frontend code from design, limitations arise because they miss the detailed intent and rules of the design system, such as hover state errors and inappropriate color/spacing usage.
- A style file (`tokens.json`) only conveys visual elements and cannot explain behavior rules or the interaction hierarchy among components.
Solution: 3-Step Structuring (Authoring → Specification → Delivery)
- Authoring: Define the visual elements of foundations, components, patterns, and templates through Figma.
- Specification: Build a divided Markdown structure that AI agents can read and interpret.
- tokens.json: defines visual foundations
- design.md: global rules and conventions
- components.md / patterns.md / templates.md : act as registries (lists) for each element
- *.md files: instead of putting everything into a single file, split into individual specification files (e.g., `wizard.template.md`) and cross-reference them to reduce the agent's context consumption and improve accuracy.
- Delivery: Let the agent access this specification and the product codebase to review compliance with the design system and propose improvements in the form of a Pull Request.
Conclusion
In the AI era, to preserve product distinctiveness and consistency, you need to prepare a design system not as a document for humans alone, but as a structured specification that agents can understand and apply.
