DESIGN.mdPreview
Give coding agents HeroUI's default visual language and theme guidance
HeroUI provides a ready-to-use DESIGN.md for coding agents. Add it to your project so generated interfaces follow HeroUI's default theme, semantic tokens, component patterns, and design principles.
Add It to Your Project
Download the latest file to the root of your project:
curl -fsSL https://heroui.com/react/DESIGN.md -o DESIGN.mdOr view the complete DESIGN.md and copy the parts your project needs.
DESIGN.md is not a universally auto-discovered instruction file. Link it from your AGENTS.md, CLAUDE.md, or editor rules so your agent knows to read it. AGENTS.md explains how to build with HeroUI, while DESIGN.md defines what the result should look and feel like.
Connect It to Your Agent
Tell your coding agent to use the root-level DESIGN.md in your prompt or project instructions:
Build this interface with HeroUI v3. Follow DESIGN.md for visual decisions and use semantic HeroUI tokens instead of hardcoded values.For automatic project-wide guidance, add this line to your AGENTS.md or equivalent instructions file:
Follow [DESIGN.md](./DESIGN.md) for all visual and interaction decisions.What's Included
- HeroUI's default light and dark color roles
- Semantic Tailwind utilities and their CSS variable mappings
- The 4px spacing rhythm and default radius scale
- Surface, overlay, field, and elevation guidance
- Component and interaction conventions
- Practical do's and don'ts for consistent agent-generated UI
The document includes raw theme values for design handoff and visual QA, but instructs agents to implement with semantic utilities such as bg-background, text-foreground, bg-surface, and border-separator. This keeps the same UI correct in both light and dark modes.
Default Theme Principles
| Principle | Agent guidance |
|---|---|
| Semantic color | Use purpose-based tokens; do not hardcode mode-specific colors |
| Clear hierarchy | Prefer content order, spacing, typography, and surface levels over decoration |
| Intentional emphasis | Use one primary action per context and reserve accent for meaningful emphasis |
| Accessible interaction | Preserve HeroUI focus, keyboard, validation, and disabled behavior |
| Consistent geometry | Follow the 4px spacing rhythm and the shared radius scale |
| Composition | Start with HeroUI components and compose their exported parts |
Source of Truth
The public file describes the current open-source default theme. Its values come from HeroUI's default theme variables and Tailwind token mappings.
If you customize the theme, update your local DESIGN.md alongside your CSS overrides so agents receive the same decisions that users see. See Theming and Colors for the full customization model.
Need a custom design system instead of the default theme? The HeroUI Theme Builder lets you customize the theme and export its CSS.