{"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.","category":"design","tags":["tailwind","design-system","ui"],"models":["any"],"proven":false,"passing_families":0,"model_testing":"Not yet model-tested; testing Jan 2027","url":"https://theskillvault.ai/skills/build-tailwind-design-system","api_url":"https://theskillvault.ai/api/skills/build-tailwind-design-system","raw_url":"https://theskillvault.ai/api/skills/build-tailwind-design-system/raw","body":"# Build a Tailwind design system\n\nTurn 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.\n\n## When to use\n- Buttons, inputs and cards look slightly different on every page.\n- You are starting a component library for a product or team.\n- You are moving a project from Tailwind v3 to v4.\n\n## When not to use\n- You only need a colour palette and fonts. Use design-tailwind-theme-tokens first.\n- You want ready-made accessible React parts. Use build-ui-with-shadcn.\n\n## Steps\n1. Check the Tailwind version in package.json. On v3, plan the move first (see the table).\n2. 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.\n3. List the primitives you repeat: button, input, label, card, badge, dialog. Start with three.\n4. Give each primitive a variant map with class-variance-authority (cva): intent (primary, secondary, danger) and size (sm, md, lg).\n5. Merge caller classes safely with `tailwind-merge` so `className` overrides win.\n6. Add focus rings, disabled styles and a dark-mode variant to every primitive.\n7. Put the parts in one folder, such as `components/ui/`, and export them from an index file.\n8. Make a single demo page that shows every variant side by side. Use it to review changes.\n9. Replace old one-off buttons and cards across the app, one page at a time.\n\n```ts\nconst button = cva(\"inline-flex items-center rounded-md font-medium focus-visible:ring-2\", {\n  variants: {\n    intent: { primary: \"bg-primary text-on-primary\", danger: \"bg-danger text-white\" },\n    size: { sm: \"h-8 px-3 text-sm\", md: \"h-10 px-4\" },\n  },\n  defaultVariants: { intent: \"primary\", size: \"md\" },\n});\n```\n\n| Tailwind v3 | Tailwind v4 |\n| --- | --- |\n| `tailwind.config.js` theme | `@theme { ... }` in CSS |\n| `@tailwind base; ...` | `@import \"tailwindcss\";` |\n| `darkMode: \"class\"` | `@custom-variant dark (...)` |\n\n## Gotchas\n- Building class names from strings (`\"bg-\" + colour`) breaks Tailwind's scanner. Write full class names.\n- Too many variants make a library nobody can learn. Add one only when two pages need it.\n- Do not paste licence keys or private brand files into public demo pages.\n- Back up or branch before a v3 to v4 upgrade; the official upgrade tool rewrites many files.\n\n## Portability\nWorks 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.\n\n## Example prompt\n\"Our buttons and cards all look different. Build a small Tailwind v4 component library with variants and a demo page.\"\n\n## Done when\n- Components use semantic names, with no raw colour values.\n- Each primitive has documented variants on one demo page.\n- Keyboard focus is visible on every interactive part.\n- Old one-off styles are replaced on at least the main pages.\n\n---\nAdapted from \"tailwind-design-system\" in wshobson/agents (MIT, Copyright (c) 2024 Seth Hobson). See LICENSE.txt.","files":["LICENSE.txt"],"license":"MIT","license_name":"MIT License","license_url":"https://opensource.org/license/mit","attribution":"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","install":{"claude_code":"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":"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'","agents":"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'","mcp_url":"https://theskillvault.ai/mcp","cursor_mcp_deeplink":"cursor://anysphere.cursor-deeplink/mcp/install?name=theskillvault&config=eyJ1cmwiOiJodHRwczovL3RoZXNraWxsdmF1bHQuYWkvbWNwIn0%3D","mcp_config":{"mcpServers":{"theskillvault":{"url":"https://theskillvault.ai/mcp"}}}},"bundles":[],"tested_on":[{"family":"chatgpt","name":"ChatGPT","outcome":null,"date":null,"source":null,"counts":false,"stale":false},{"family":"claude","name":"Claude","outcome":null,"date":null,"source":null,"counts":false,"stale":false},{"family":"gemini","name":"Gemini","outcome":null,"date":null,"source":null,"counts":false,"stale":false},{"family":"grok","name":"Grok","outcome":null,"date":null,"source":null,"counts":false,"stale":false},{"family":"llama","name":"Llama","outcome":null,"date":null,"source":null,"counts":false,"stale":false},{"family":"deepseek","name":"DeepSeek","outcome":null,"date":null,"source":null,"counts":false,"stale":false},{"family":"mistral","name":"Mistral","outcome":null,"date":null,"source":null,"counts":false,"stale":false},{"family":"qwen","name":"Qwen","outcome":null,"date":null,"source":null,"counts":false,"stale":false},{"family":"kimi","name":"Kimi K","outcome":null,"date":null,"source":null,"counts":false,"stale":false}],"proven_rule":{"threshold":5,"window_days":365,"computed_at":"2026-11-02T03:20:33.817Z"}}