DESIGN.md for Kiro

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.

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.

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.

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.