---
name: build-tailwind-design-system
description: Builds a reusable component library on Tailwind CSS v4 - a CSS-first @theme layer, semantic colour names, component variants with class-variance-authority, and a small docs page - and covers the v3 to v4 move. Use when the user wants a component library, consistent buttons and cards, UI variants, or to upgrade Tailwind v3 to v4.
license: MIT
metadata:
  category: design
  tags: "tailwind,design-system,ui"
  author: johnny-bravo
  version: "1.0"
  updated: "2026-11-02"
  status: published
  aliases: "component library, tailwind v4 upgrade, ui variants"
  source_url: "https://github.com/wshobson/agents/tree/7e2fb559cf4b824b27f1fec49fe88f7511066d26/plugins/frontend-mobile-development/skills/tailwind-design-system"
  source_license: MIT
  copyright: "Copyright (c) 2024 Seth Hobson"
  original_author: "Seth Hobson (wshobson/agents, tailwind-design-system)"
  modified: "Adapted by TheSkillVault: rewritten for beginners as a build order (semantic layer, primitives, variants, docs), shortened the v3-to-v4 table, added gotchas and done-when; long code samples replaced with short original ones."
  imported_on: "2026-11-02"
---

# Build a Tailwind design system

Turn scattered utility classes into a small set of components everyone reuses. Tokens are the paint; this skill is about the parts you build from them.

## When to use
- Buttons, inputs and cards look slightly different on every page.
- You are starting a component library for a product or team.
- You are moving a project from Tailwind v3 to v4.

## When not to use
- You only need a colour palette and fonts. Use design-tailwind-theme-tokens first.
- You want ready-made accessible React parts. Use build-ui-with-shadcn.

## Steps
1. Check the Tailwind version in package.json. On v3, plan the move first (see the table).
2. Add a semantic layer in your main CSS with `@theme`: names like `--color-surface`, `--color-primary` and `--color-danger`. Components use these names, never raw hex values.
3. List the primitives you repeat: button, input, label, card, badge, dialog. Start with three.
4. Give each primitive a variant map with class-variance-authority (cva): intent (primary, secondary, danger) and size (sm, md, lg).
5. Merge caller classes safely with `tailwind-merge` so `className` overrides win.
6. Add focus rings, disabled styles and a dark-mode variant to every primitive.
7. Put the parts in one folder, such as `components/ui/`, and export them from an index file.
8. Make a single demo page that shows every variant side by side. Use it to review changes.
9. Replace old one-off buttons and cards across the app, one page at a time.

```ts
const button = cva("inline-flex items-center rounded-md font-medium focus-visible:ring-2", {
  variants: {
    intent: { primary: "bg-primary text-on-primary", danger: "bg-danger text-white" },
    size: { sm: "h-8 px-3 text-sm", md: "h-10 px-4" },
  },
  defaultVariants: { intent: "primary", size: "md" },
});
```

| Tailwind v3 | Tailwind v4 |
| --- | --- |
| `tailwind.config.js` theme | `@theme { ... }` in CSS |
| `@tailwind base; ...` | `@import "tailwindcss";` |
| `darkMode: "class"` | `@custom-variant dark (...)` |

## Gotchas
- Building class names from strings (`"bg-" + colour`) breaks Tailwind's scanner. Write full class names.
- Too many variants make a library nobody can learn. Add one only when two pages need it.
- Do not paste licence keys or private brand files into public demo pages.
- Back up or branch before a v3 to v4 upgrade; the official upgrade tool rewrites many files.

## Portability
Works with React, Vue, Svelte or plain HTML. If you use a non-React stack, swap cva for the equivalent variant helper or plain class maps.

## Example prompt
"Our buttons and cards all look different. Build a small Tailwind v4 component library with variants and a demo page."

## Done when
- Components use semantic names, with no raw colour values.
- Each primitive has documented variants on one demo page.
- Keyboard focus is visible on every interactive part.
- Old one-off styles are replaced on at least the main pages.

---
Adapted from "tailwind-design-system" in wshobson/agents (MIT, Copyright (c) 2024 Seth Hobson). See LICENSE.txt.