Tailwind CSS design system file
Tailwind CSS DESIGN.md for AI coding agents
A practical design contract for agents styling with Tailwind CSS utility classes. It defines the spacing scale, color tokens, radius, component tone, and prompt-ready constraints so generated UI stops looking like default Tailwind.
Why Tailwind CSS needs DESIGN.md
Tailwind CSS design tokens
Spacing scale
4px base unit
Starter example for the Tailwind spacing scale (`p-1`…`p-16`). Replace it with the local product rhythm.
Color tokens
--color-app-bg / --color-app-accent
Starter examples for mapping brand colors onto Tailwind theme variables.
Radius
--radius-app-card: 0.5rem
Starter example for card, button, and input corner rhythm.
Dark mode
class strategy
Starter example for toggling dark surfaces without hardcoding one-off colors.
AI-agent workflow
Cursor
Save the file in the repo, reference it from .cursor/rules, and ask Cursor to follow the documented spacing scale and color tokens before writing new Tailwind classes.
Claude Code
Keep the Tailwind token map beside CLAUDE.md, then ask Claude Code to follow DESIGN.md for spacing, color, radius, and dark mode before editing UI.
Codex
Put DESIGN.md near AGENTS.md and tell Codex to read both before UI work. Codex should reuse the token names instead of inventing new arbitrary Tailwind values.
v0
Paste the token and component sections into the prompt when generating Tailwind UI, then adapt the output back into the existing project theme.
Reference vs template
Reference page
Use this page for the full Tailwind CSS DESIGN.md workflow: spacing scale, color tokens, component tone, dark mode, and agent instructions.
Template page
Use the template when you want a shorter file scaffold to customize inside a repo that already has a Tailwind config.
Conventions covered
Spacing rhythm, color token naming, radius scale, shadow rhythm, buttons, cards, tables, forms, and anti-patterns like arbitrary one-off values.
Not official docs
This page is a DesignMD workflow reference. It does not replace the official Tailwind CSS 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.
# Tailwind CSS DESIGN.md
## What this is
Tailwind CSS is a utility-first framework: classes compose directly in markup instead of hand-written stylesheets.
DESIGN.md helps agents turn that utility vocabulary into a consistent product system instead of a pile of arbitrary one-off classes.
## Why this page exists in DesignMD
This reference is not a scraped brand style page. It is a workflow page for teams that want to pair Tailwind CSS theme documentation with a durable DESIGN.md file.
Use it when an AI builder needs visual taste before it edits Tailwind classes, creates React components, or turns a prompt into a working interface.
The goal is practical: make the agent read a small design contract before it starts guessing color, density, hierarchy, radius, and component behavior.
## How DESIGN.md fits the workflow
- Define the spacing scale and color tokens before asking an agent to build a screen.
- Document radius, shadow, and border rhythm so generated UI does not default to rounded-lg everywhere.
- Tell agents which utility patterns are canonical for buttons, cards, and forms.
- Explain dark mode strategy (class vs media) so agents do not hardcode one-off dark colors.
- List anti-patterns so agents stop inventing arbitrary values like `p-[13px]`.
- Keep DESIGN.md close to the source code, usually in the project root or beside the frontend app that owns the product surface.
- Treat the file as a living design contract. Update it after visual decisions change, not only after a full redesign.
- Reference the file explicitly in your coding-agent instructions so it is read before UI work begins.
- Prefer concrete values over adjectives. Agents follow `--radius-card: 8px` more reliably than "make it polished".
- Pair visual rules with acceptance checks: responsive behavior, hover states, empty states, error states, and accessibility.
## Recommended DESIGN.md structure
A useful DESIGN.md for this workflow should be readable by a human reviewer and precise enough for an agent.
### Product feel
- Define the product category and emotional target in one paragraph.
- Name what the interface should avoid, not only what it should become.
- Include the density target: sparse marketing, focused SaaS, data-heavy console, or code-first tool.
### Color
- Put canonical color values in CSS variables or token names.
Related pages and guides
Tailwind DESIGN.md template
A starter file for color tokens, radius, spacing, shadows, and component tone.
DESIGN.md for Tailwind guide
The educational guide for writing Tailwind-specific design memory.
shadcn/ui DESIGN.md
A related component-system reference for building agent-generated UI with shadcn/ui.
Vercel DESIGN.md
A related devtool reference for monochrome AI-built interfaces.
Cursor DESIGN.md
A related agent workflow page for applying Tailwind rules in Cursor.
v0 DESIGN.md
A related workflow page for generated React, Tailwind, and shadcn UI.
Related Tailwind, shadcn, Vercel, and Cursor pages
Tailwind DESIGN.md template
A template style file for Tailwind apps: color tokens, radius, spacing, shadows, and component tone.
shadcn/ui DESIGN.md
A practical design contract for AI agents using shadcn/ui: component rules, Tailwind tokens, density, states, forms, tables, dashboards, and prompt-ready constraints.
Vercel
Vercel design system as a DESIGN.md — monochrome Geist UI, electric-blue accent.
FAQ
What is a Tailwind DESIGN.md?
It is an independent markdown reference that tells AI coding agents how to use Tailwind CSS utility classes with product-specific rules for spacing, color tokens, radius, component tone, and dark mode.
Is this official Tailwind Labs documentation?
No. This is an independent DesignMD reference for AI-agent workflows. Use the official Tailwind CSS documentation for utility syntax and configuration details.
How do I use it with Cursor or Codex?
Copy the DESIGN.md file into your project, point Cursor or Codex at it before UI work, then ask the agent to reuse the documented spacing scale, color tokens, and component tone instead of inventing new arbitrary values.
Does it work with shadcn/ui?
Yes. Tailwind CSS is the styling layer under shadcn/ui, so the spacing and color token conventions here translate directly into shadcn component variants. See the shadcn/ui DESIGN.md reference for the component-specific rules.