AI Agents
DESIGN.md for Kiro
How to use DESIGN.md with Kiro, the AWS agentic IDE built around specs, steering, hooks, and production-minded implementation.
Why Kiro needs design context
Kiro is built around a more structured version of AI development: specs, steering files, hooks, and agentic chat. That structure is powerful because it can turn a rough product request into requirements, implementation tasks, tests, and supporting docs. But UI quality still depends on the information the agent receives. If the product brief only says "make a modern dashboard", the result can still drift toward generic cards, random gradients, weak spacing, and default component choices. DESIGN.md gives Kiro a visual contract to use alongside product specs. Instead of asking Kiro to guess the brand, you can tell it exactly how the product should feel, what colors mean, what density to use, which component states matter, and which visual patterns are off-limits.
Best workflow
A practical Kiro workflow is to keep DESIGN.md in the repository next to the normal engineering instructions. Use Kiro specs for what the feature should do, and DESIGN.md for how the feature should look and behave visually. Before starting a UI feature, ask Kiro to read the DESIGN.md file and summarize the design constraints it will follow. Then ask it to create or update the feature spec with explicit UI acceptance criteria: color roles, responsive layout, navigation density, empty states, form behavior, loading states, and accessibility checks. This turns design taste into reviewable tasks instead of chat-only guidance. It also helps hooks and automated follow-up work preserve the same design language after the first implementation pass.
What to put in DESIGN.md
For Kiro, the most useful DESIGN.md is specific but not bloated. Include brand personality, core product surfaces, typography, color tokens, semantic color roles, spacing scale, radius scale, shadow rules, page layout patterns, component behavior, examples of good UI, and examples of what to avoid. Add rules such as "settings pages should be dense and quiet", "primary actions use one color only", "dashboard cards use compact headers", or "do not wrap operational tools in marketing-style hero sections". If your project uses Tailwind, shadcn, Radix, or a custom token system, map the design rules to the actual classes or variables Kiro will edit.
Prompt pattern
Use a short prompt that binds Kiro to both files: "Read AGENTS.md for engineering rules and DESIGN.md for visual rules. Update the feature spec for this screen, then implement it. Preserve the existing component system. Do not introduce a new visual style unless DESIGN.md says to." This is especially useful when Kiro is working on production paths rather than prototypes. The goal is not to make the agent slower; it is to prevent rework by giving it the design information before it creates files. Kiro already encourages structured work. DESIGN.md makes the visual side of that structure explicit.
Use DESIGN.md with a real product reference
Browse curated DESIGN.md examples from product teams, design systems, developer tools, SaaS dashboards, and AI-native apps. Use them as references before your agent builds the next screen.
Related guides
DESIGN.md for Windsurf
How to use DESIGN.md with Windsurf and Cascade so AI edits follow your product design system instead of default editor taste.
DESIGN.md for Bolt
How DESIGN.md helps bolt.new generate full-stack browser apps with stronger UI direction, cleaner components, and less generic styling.
DESIGN.md for v0
How to use DESIGN.md with Vercel v0 to generate UI, prototypes, and full-stack app surfaces that match your real product design system.