Design · Skill

Build a Tailwind design system

build-tailwind-design-system

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.

Works with: Any AI Not yet model-tested; testing Jan 2027

View raw SKILL.mdInstall

Paste it into ChatGPT, Claude, Gemini or any AI chat, then tell it about your project. How it works

Install in Claude Code, Cursor or Codex (optional)

Only for AI coding tools that read skill folders. Run one line in a terminal, in your project folder. It downloads this skill's text files from TheSkillVault and nothing else; you can read them first with “View raw SKILL.md”.

Claude Code (all your projects)

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/build-tailwind-design-system/raw' -o ~/'.claude/skills/build-tailwind-design-system/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/build-tailwind-design-system/files/LICENSE.txt' -o ~/'.claude/skills/build-tailwind-design-system/LICENSE.txt'

Cursor (this project)

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/build-tailwind-design-system/raw' -o '.cursor/skills/build-tailwind-design-system/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/build-tailwind-design-system/files/LICENSE.txt' -o '.cursor/skills/build-tailwind-design-system/LICENSE.txt'

Codex and other Agent Skills tools (this project)

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/build-tailwind-design-system/raw' -o '.agents/skills/build-tailwind-design-system/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/build-tailwind-design-system/files/LICENSE.txt' -o '.agents/skills/build-tailwind-design-system/LICENSE.txt'

Or connect the whole library over MCP

Add TheSkillVault to Cursor or add this to your app's MCP settings (read-only; help):

{
  "mcpServers": {
    "theskillvault": {
      "url": "https://theskillvault.ai/mcp"
    }
  }
}

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.
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.

Bundled files

Licence

Adapted from Seth Hobson (wshobson/agents, tailwind-design-system) (Copyright (c) 2024 Seth Hobson), MIT License. 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.

Licence: MIT License. Attribution when you reuse it: Based on work by Seth Hobson (wshobson/agents, tailwind-design-system) (Copyright (c) 2024 Seth Hobson, MIT License), https://github.com/wshobson/agents/tree/7e2fb559cf4b824b27f1fec49fe88f7511066d26/plugins/frontend-mobile-development/skills/tailwind-design-system; adapted by TheSkillVault, https://theskillvault.ai