Claude Code Prompts for Tailwind CSS v4

Copy-paste Claude Code prompts for Tailwind v4 — config migration, custom utilities, dark-mode, design-token discipline, and finding ad-hoc colour drift.

Tailwind v4's @theme directive turns design tokens into CSS variables that Tailwind generates utility classes for. The biggest Claude-related risk is reaching for arbitrary values (text-[#abc123]) instead of token-based classes (text-brand-primary). The prompts below enforce the discipline.

Prompt 1 — Set up @theme tokens from a design spec

Set up app.css with @theme based on this design spec:

Colours:
- brand:    50 → 950 (use the existing palette in /designs/palette.txt)
- accent:   50 → 950 (same)
- semantic: success, warning, danger, info — each with -bg and -fg variants

Typography:
- font-sans: Inter Variable
- font-display: Manrope Variable
- font-mono: JetBrains Mono Variable

Radii:
- sm 4px, md 6px, lg 10px, xl 16px, 2xl 24px, full 9999px

Shadows:
- card (light, subtle), pop (heavier, for modals)

Constraints:
- Generate the @theme block in app.css. Do NOT use tailwind.config.js (v4 is
  CSS-native).
- For dark mode use @layer base with html[data-theme='dark'] { ... } overriding
  the semantic colour variables.
- Add a brief comment at the top of @theme: "Source of truth for design
  tokens. Never use arbitrary values in components."
- Do not generate hex colours I didn't provide — read /designs/palette.txt.

Prompt 2 — Drift audit (find ad-hoc colours)

Audit the codebase for Tailwind drift. Specifically:

1. Find every arbitrary colour value: text-[#...], bg-[#...], border-[#...],
   ring-[#...], from-[#...], to-[#...], via-[#...].
2. Find every default Tailwind palette usage that the design system has
   replaced: text-red-500, bg-blue-600, etc. (We use brand/accent/semantic
   only.) Allowlist: text-white, bg-white, text-black, bg-black, bg-transparent.
3. Group by file. Rank files by total drift count, descending.

Output a markdown table:
| file | arbitrary | default-palette | total |

Then propose the top 10 most-common ad-hoc colours and suggest the token
each one should become. Do NOT change any files — I'll review.

Prompt 3 — Refactor one component to design tokens

Read src/components/PricingCard.tsx (currently uses arbitrary colours and
default palette).

Convert every class to a design-token class:
- bg-[#0f172a]  → bg-brand-900
- text-[#94a3b8] → text-brand-300 (or check the closest token in @theme)
- border-blue-500 → border-accent-500
- etc.

Constraints:
- For each substitution, write a comment // was:   at the END of
  the line so I can verify the mapping.
- If a colour doesn't have a clean token mapping, leave it AND list it at the
  bottom of the diff with a suggested @theme addition.
- Don't touch layout/spacing/typography classes — colour-only refactor.
- After the diff, list the remaining un-mapped colours and propose tokens.

CLAUDE.md for Tailwind v4

## Design system
Source of truth: app.css @theme block. NEVER use arbitrary values like
text-[#...] or bg-[#...]. NEVER use the default Tailwind palette
(blue, red, green, etc.) except in this allowlist: white, black, transparent.
All colours, radii, shadows come from tokens.

Dark mode: data-theme switching, NOT the class strategy. No 'dark:' prefix —
the CSS variables flip via the [data-theme="dark"] selector.

Related: shadcn/ui prompts.

Frequently asked questions

Free tools

More examples