---
name: design-tailwind-theme-tokens
description: Designs a small design system of colour palette, typography scale, spacing and radius tokens as Tailwind theme variables so the whole UI looks consistent. Use when the user wants a colour scheme, brand colours, fonts, a style guide, design tokens, or the app looks inconsistent or ugly.
license: CC-BY-4.0
metadata:
  category: design
  tags: "tailwind,design-tokens,typography,css"
  author: johnny-bravo
  version: "1.0"
  updated: "2026-10-30"
  status: published
---

# Design Tailwind theme tokens

## When to use
- The UI uses random hex colours and font sizes, or a new project needs a look.

## Steps
1. Pick one brand hue and generate a 50-950 scale (e.g. with OKLCH). Add one neutral scale and semantic colours: success, warning, danger.
2. Define semantic tokens, not raw colours, in Tailwind v4 CSS:
   ```css
   @theme {
     --color-brand-600: oklch(0.55 0.2 260);
     --color-surface: var(--color-white);
     --color-text: var(--color-zinc-900);
     --font-sans: "Inter", system-ui, sans-serif;
     --radius-card: 0.75rem;
   }
   ```
   (v3: put the same values in `tailwind.config` `theme.extend`.)
3. Typography: max two families; a scale like 12/14/16/20/24/32/48; body line-height 1.5, headings 1.1-1.2.
4. Spacing on a 4px grid; pick 2-3 radii and 2 shadows and use only those.
5. Replace hard-coded values across components with the tokens (`bg-surface text-text rounded-card`).
6. Build one sample page (buttons, inputs, card, alert) to review all tokens together, in light and dark.

## Gotchas
- Check text contrast for every background token (4.5:1 for body text).
- Too many accent colours makes the UI noisy; one brand colour plus neutrals is enough.

## Example prompt
"Pick nice brand colours and fonts for my app and make everything consistent."