Helping Agents Use Design System Components Correctly
1. Background and problems
- Limits of using AI agents: When asking an agent to generate interface code using tools such as Figma MCP, complex cases or screens that combine multiple components can produce unintended code. The agent may also ignore the design system and implement the interface directly.
- Insufficient information: The information provided to the agent is limited to simple prop mappings, preventing it from understanding interaction rules between components or state-management patterns.
2. Solution: dividing the information structure
Two types of information are provided so that AI agents can write code accurately and consistently.
- Code Connect (Figma ↔ code mapping): Maps Figma properties to their corresponding code props. It is useful for simple prop mappings in individual components and for communicating basic component-composition structures.
- Agent Docs (Markdown documentation for agents):
- Agent-specific guide documents written in Markdown inside the agent/ directory.
- Provides complex context and rules, including anatomy, props, composition patterns, and state-management guidance such as separating temporary state from committed state.
- Uses agent/README.md as the entry point so the agent can independently find and read relevant references such as useCalendar.md and DatePicker.md.
3. Results and conclusion
- Improved accuracy and consistency: After introducing Agent Docs, the variation characteristic of agent-generated results decreased significantly, along with the frequency of manual corrections.
- A new perspective on design systems: As the consumers of a design system expand from people to AI agents, documentation must be structured in a form that agents can process and consume effectively.
