What is the tailwind-design-system skill?
The tailwind-design-system skill is a SKILL.md in wshobson/agents, under the frontend-mobile-development plugin. It guides an AI coding agent to build Tailwind CSS v4 design systems: CSS-first @theme tokens, OKLCH semantic colors, dark mode variants, CVA components and a v3 to v4 migration checklist.
The tailwind-design-system skill is a Tailwind CSS v4 playbook for AI coding agents. It lives in the wshobson/agents repository inside the frontend-mobile-development plugin, and it ships SKILL.md with two reference files, details.md and advanced-patterns.md.
Its core idea is that Tailwind v4 moves configuration into CSS. Instead of a tailwind.config file, tokens are declared in an @theme block, and the skill shows how to structure those tokens for a whole design system.
What changes in your agent's output
- Config moves into CSS:
@import "tailwindcss",@themefor tokens, and@custom-variant darkfor class-based dark mode. - Semantic OKLCH tokens such as background, foreground, primary, muted, accent, destructive, border and ring come in pairs with a foreground.
- Components use class-variance-authority with a
cn()helper built from clsx and tailwind-merge. - The agent follows a token hierarchy of brand, semantic and component, and a component structure of base, variants, sizes, states and overrides.
Who the tailwind-design-system skill is for
Best for
- New Tailwind v4 projects that need a token system from day one.
- Migrating a v3 codebase, with a table and a ten-item checklist.
- Agents that keep hardcoding colors or reaching for arbitrary values.
Not for
- Tailwind v3 projects you are not migrating.
- Choosing a component library. Use pick-ui-library for that decision.
- Component installation itself. The shadcn skill handles project context for shadcn/ui.
Use it with UiChemy
Tailwind tokens describe a design. UiChemy brings designs into WordPress: Figma to WordPress converts a file, and Composer edits the result in Elementor or Gutenberg. Click Get Started on uichemy.com.
How to install Tailwind Design System Skill: Tailwind v4 Tokens and Variants
git clone https://github.com/wshobson/agents.gitClone the repository
Run
git clone https://github.com/wshobson/agents.git. The skill is at plugins/frontend-mobile-development/skills/tailwind-design-system.Copy the skill folder
Copy that folder into your agent's skills folder with SKILL.md and the references folder, which holds details.md and advanced-patterns.md.
Or add the plugin in Claude Code
In Claude Code you can instead run
/plugin marketplace add wshobson/agents, then/plugin install frontend-mobile-development@claude-code-workflows.Invoke it
Ask your agent to set up or migrate a Tailwind v4 design system and name the tokens you need.
Check that it loaded
Ask for a Tailwind v4 token setup. The agent should write an @theme block with OKLCH semantic tokens, use @import "tailwindcss", and avoid a tailwind.config file. Check there are no hardcoded hex colors in components.
Key features
- v3 to v4 mappingA table maps tailwind.config to
@theme, the three@tailwinddirectives to one import, and thedarkModesetting to a custom variant. - OKLCH semantic tokensThe quick start defines background, foreground, primary, secondary, muted, accent, destructive, border, ring and card tokens.
- Token hierarchyBrand, semantic and component layers keep raw values apart from meaning.
- CVA componentsVariant-driven components use class-variance-authority with a shared
cn()utility. - Compound and form componentsdetails.md covers compound components in React 19, form components and a responsive grid.
- CSS-native animationAnimations live as
--animate-*tokens with@keyframesand@starting-styleinstead of a plugin. - Advanced themingadvanced-patterns.md covers
@utility,@theme inline, namespace resets,color-mix()alpha variants and container query tokens. - Migration checklistA ten-item checklist walks a v3 codebase to v4.
- Do and don't rulesUse
size-*, skipforwardRefon React 19, avoid arbitrary values and never hardcode colors.
Frequently asked questions
What is the tailwind-design-system skill?
It is a skill in wshobson/agents, under the frontend-mobile-development plugin. It guides an AI coding agent to build Tailwind CSS v4 design systems with CSS-first tokens, OKLCH colors, CVA components and a v3 migration path.
How do I install the tailwind-design-system skill?
Clone wshobson/agents and copy plugins/frontend-mobile-development/skills/tailwind-design-system into your agent's skills folder. In Claude Code, you can add the repository as a plugin marketplace and install the frontend-mobile-development plugin instead, which brings its other skills too.
Does it support Tailwind v3?
The skill targets Tailwind v4. It includes a v3 to v4 table and a ten-item migration checklist, so it helps you move off v3, but it does not teach v3 patterns for projects that stay there.
What does @theme do in this skill?
It declares design tokens in CSS, replacing the theme section of tailwind.config. The skill puts semantic OKLCH colors, radius values and --animate-* tokens there, with .dark overrides for dark mode.
Which components does it show?
details.md has CVA button-style components, compound components for React 19, form components and a responsive grid, plus a cn() helper with focus and disabled styles. These are patterns for your system, not a packaged library.
How does it relate to shadcn?
The tokens it defines, such as background, foreground and primary, follow the semantic naming common in shadcn/ui setups. For shadcn project context, use the shadcn skill, and the shadcn MCP for registry access.
Which AI agents can use it?
The repository is built around Claude Code plugins, and the skill itself is a SKILL.md folder, so agents that load skills from a folder, such as Cursor or Codex, can use the copy route. Check your agent's skills path.
What should I pair it with?
Use design-taste-frontend for visual judgment and fixing-accessibility to check contrast and focus states on the tokens it produces. For preset palettes to start from, see theme-factory, which lists ten ready themes.