Context Injection
Deliver the right design-system context to AI agents at the right time.
Key takeaways
- Context injection layers persistent repo instructions, design intent, component docs, tool context, and prompt context for the agent.
- Keep stable rules in auto-loaded files, large references searchable, and mention only relevant components for narrow tasks.
- A context budget gives the smallest set that prevents the most likely mistake, scaling from a tiny task up to a system migration.
- Use MCP tools when freshness matters and repository files when repeatability matters; each context type has its own staleness or availability risk.
- A responsibility map keeps AGENTS.md, CLAUDE.md, DESIGN.md, component MDX, and registry metadata each owning a distinct slice of context.
Agents cannot use a design system they cannot see. Context injection is the practice of giving the agent the right mix of durable instructions, local docs, tool data, and task-specific examples.
Context Layers
| Layer | Example | Use |
|---|---|---|
| Persistent repo instructions | AGENTS.md, CLAUDE.md | Stable engineering and design rules. |
| Design intent | DESIGN.md | Brand feel, layout rules, forbidden patterns. |
| Component docs | MDX, Storybook, registry metadata | API and composition details. |
| Tool context | Figma MCP, screenshots, design tokens | Current design source. |
| Prompt context | User request and mentioned files | Task-specific intent. |
Injection Strategy
- Keep stable rules in files the agent loads automatically.
- Keep large references searchable rather than always injected.
- Mention only relevant components for narrow tasks.
- Use MCP for live design data when source-of-truth freshness matters.
- Ask for evidence when the agent makes design decisions.
Context Budget
More context is not always better. Give the agent the smallest set that can prevent the most likely mistake.
| Budget tier | Include |
|---|---|
| Tiny task | User request, one file, one component spec, verification command. |
| Component change | Component spec, token rules, examples, tests, accessibility contract. |
| Screen change | DESIGN.md, relevant component specs, screenshot target, route, responsive rules. |
| System migration | Token architecture, registry metadata, migration plan, governance rules, test strategy. |
File Context vs MCP Context
| Context type | Best for | Risk |
|---|---|---|
| Repository files | Stable rules, APIs, ownership, commands, quality gates. | Can go stale if not maintained. |
| MCP tools | Live design frames, variables, screenshots, external system state. | Can be unavailable, partial, or beta. |
| User prompt | Immediate intent and task constraints. | Often underspecified. |
| Generated summary | Long-running work and handoff state. | May omit details that matter for UI. |
Use MCP when freshness matters. Use repository files when repeatability matters.
Responsibility Map
| File | Owns |
|---|---|
AGENTS.md | Engineering workflow, commands, repo conventions, verification expectations. |
CLAUDE.md | Claude-specific work style and project memory when the team uses Claude Code. |
DESIGN.md | Product feel, layout philosophy, density, visual rules, forbidden patterns. |
| Component MDX | Props, slots, states, accessibility, examples, anti-patterns. |
| Registry metadata | Machine-readable component availability, dependencies, and installation paths. |
Example Agent Instruction
Before creating UI:
- Read DESIGN.md for product feel and layout rules.
- Use existing components from packages/ui.
- Do not invent tokens or variants.
- Run typecheck and a responsive screenshot check for meaningful UI changes.Context Packet Template
Relevant files:
- DESIGN.md
- packages/ui/src/button.tsx
- content/docs/components/button.mdx
Task constraints:
- Surface type:
- Density:
- Allowed components:
- Forbidden patterns:
- Token rules:
- Accessibility requirements:
- Verification command:
Expected response:
- Implementation summary
- Verification evidence
- Missing context or design-system gapsFailure Modes
| Failure | Fix |
|---|---|
| Agent ignores DS | Make component docs discoverable and mention relevant files. |
| Agent invents tokens | Add explicit token prohibition and validation. |
| Agent overuses cards | Put card rules in DESIGN.md and review screenshots. |
| Agent misses accessibility | Move accessibility into primitives and tests. |
Verification
- Confirm the generated code imports approved components.
- Search for raw color, spacing, or font values.
- Run screenshot checks at desktop and mobile widths.
- Document any missing context the agent asked for.