shadcn/ui design system file
shadcn/ui DESIGN.md for AI coding agents
A practical design contract for agents using shadcn/ui. It defines component rules, Tailwind tokens, density, states, forms, tables, dashboards, and prompt-ready constraints.
Why shadcn/ui needs DESIGN.md
shadcn/ui theme tokens
--background
0 0% 100%
Starter example for the app background. Replace it with the local product token.
--foreground
222 47% 11%
Starter example for primary text and high-contrast UI copy.
--card / --border
0 0% 100% / 214 32% 91%
Starter examples for cards, panels, separators, and table edges.
--primary / --radius
222 89% 55% / 0.5rem
Starter examples for main actions and component corner rhythm.
AI-agent workflow
Cursor
Add the file to repo context, list installed shadcn components, and ask Cursor to reuse local primitives before creating new Button, Card, Dialog, Table, Form, or Badge code.
Claude Code
Keep the shadcn component inventory beside CLAUDE.md, then ask Claude Code to follow DESIGN.md for variants, density, validation states, and dashboard composition.
Codex
Put DESIGN.md near AGENTS.md and tell Codex to read both before UI work. Codex should preserve local imports, states, responsive behavior, and accessibility checks.
v0
Paste the token and component sections into the prompt when generating shadcn UI, then adapt the output back into the existing repo component system.
Reference vs starter
Reference page
Use this page when you need the full shadcn/ui DESIGN.md workflow: component ownership, token interpretation, composition rules, agent instructions, and review checks.
Starter page
Use the starter when you want a shorter scaffold to customize inside a repo that already has shadcn-style primitives installed.
Component rules covered
Buttons, card density, table rows and headers, dialog sizing, badge/status usage, form labels, helper text, validation errors, disabled states, loading states, and focus states.
Not official docs
This page is a DesignMD workflow reference. It does not replace official shadcn/ui installation or component documentation.
Raw DESIGN.md File
The full source file in Markdown format, plus export variants for Tailwind config, CSS variables, and design tokens. Sign in to copy or download the full file.
# shadcn/ui DESIGN.md
## Product feel
A practical design contract for AI agents using shadcn/ui: component rules, Tailwind tokens, density, states, forms, tables, dashboards, and prompt-ready constraints.
Build for a Vercel-style, Monochrome UI, Devtool visual taste. Keep density practical, typography strong, and layouts easy for AI agents to repeat.
## Color direction
- Primary text: #101828
- Accent / interactive: #e11d48
- Surface: #fff1f2
- Border / separators: #fda4af
## Typography
- Use a modern sans for body copy and a sharper display face for hero/page titles.
- Titles should feel deliberate, not shouty. Avoid oversized marketing fluff.
- Meta text should stay compact and quiet.
## Layout rules
- Prefer light UI by default.
- Use compact spacing and card grids that still feel breathable.
- Keep navigation practical: search first, then filters, then actions.
- This entry belongs to the "design-creative" lane.
## Components
- Buttons: slightly rounded, clear hierarchy, only one primary CTA per section.
- Cards: soft border, useful metadata, preview-first composition.
- Empty states: helpful, never dead.
- Code panels: mono, dense, copy-friendly.
## Agent rules
- Do not generate generic Tailwind marketing blocks.
- Respect the palette and keep component states consistent.
- Optimize for these tools: Cursor, Claude Code, Codex, Google Stitch.
## Accessibility
- Preserve contrast for text and controls.
- Use visible focus states.
- Avoid relying on color alone for meaning.
## License
Reference only
Related pages and guides
shadcn/ui DESIGN.md starter
A starter file for installed components, variants, density, and UI states.
DESIGN.md for shadcn/ui guide
The educational guide for writing shadcn-specific design memory.
Tailwind CSS DESIGN.md
The primary Tailwind CSS reference: spacing scale, color tokens, and component tone for AI agents.
Tailwind DESIGN.md template
A companion template for CSS variables, spacing, and component tone.
Cursor DESIGN.md
A related agent workflow page for applying shadcn/ui rules in Cursor.
Vercel DESIGN.md
A related devtool reference for monochrome AI-built interfaces.
v0 DESIGN.md
A related workflow page for generated React, Tailwind, and shadcn UI.
Related shadcn, Tailwind, Cursor, Vercel, and v0 pages
shadcn/ui DESIGN.md starter
Practical starter rules for AI agents building shadcn dashboards, forms, and tables.
Tailwind CSS DESIGN.md
A practical design contract for AI agents styling with Tailwind CSS: spacing scale, color tokens, radius, component tone, dark mode, and prompt-ready constraints.
Tailwind DESIGN.md template
A template style file for Tailwind apps: color tokens, radius, spacing, shadows, and component tone.
Vercel
Vercel design system as a DESIGN.md — monochrome Geist UI, electric-blue accent.
FAQ
What is shadcn/ui DESIGN.md?
It is an independent markdown reference that tells AI coding agents how to use shadcn-style components with product-specific rules for tokens, density, component variants, forms, tables, dialogs, states, and dashboard composition.
Is this official shadcn/ui documentation?
No. This is an independent DesignMD reference for AI-agent workflows. Use the official shadcn/ui documentation for installation and component API details.
How do I use it with Cursor?
Copy the DESIGN.md file into your project, point Cursor at it before UI work, then ask Cursor to reuse existing shadcn components and follow the documented tokens, variants, density, and state rules.
How do I use it with Codex?
Put the DESIGN.md file beside your repository instructions and tell Codex to read it before editing UI. Codex should check the local component inventory, reuse existing primitives, and verify responsive, hover, active, disabled, loading, empty, and error states.
Does it work with Tailwind?
Yes. The reference uses shadcn/ui and Tailwind token language, including CSS variables such as --background, --foreground, --card, --border, --primary, and --radius as starter examples.
Should I use this or the starter page?
Use this reference page to understand the full workflow and component rules. Use the starter page when you want a shorter file scaffold to adapt inside an existing shadcn/ui project.