Overview
Establishes a complete, maintainable Tailwind CSS design system by extending the config with semantic design tokens (colors, spacing, typography, shadows, radii), creating reusable component classes via @apply or a component library approach, setting up dark mode (class or media), and providing plugin examples for custom utilities.
When to Use This Skill
- Starting a new project that will use Tailwind and needs a design language from day one.
- Standardizing an existing Tailwind project that has inconsistent colors, spacing, or component styles.
- Building or contributing to a design system / component library.
Prerequisites
- Tailwind CSS 3.4+ installed (or via CDN for prototypes).
tailwind.config.ts or .js in the project root.- PostCSS and build pipeline set up.
- Design tokens or brand guidelines (or the skill will propose a sensible neutral + accent system).
Steps
Audit current usage (if existing project): Find all hard-coded colors, spacing, fonts.
Design token architecture in tailwind.config.ts:
- Extend
theme.extend.colors with semantic names (primary, neutral, success, background, foreground).
- Use OKLCH or HSL for better dark mode and accessibility.
- Define spacing scale, typography scale, border radius, box shadows as tokens.
Dark mode setup:
- Preferred:
darkMode: 'class' + dark: variants.
- Alternative:
media for system preference.
- Provide a theme toggle component (button that adds/removes
dark class on <html>).
Component abstraction strategy:
- For simple components: use
@apply in a components.css layer.
- For complex or highly reusable: create actual React/Vue/Svelte components.
- Document pros/cons of each approach.
Create custom plugins (optional but powerful):
- Plugin for
text-balance, container-query utilities, or brand-specific helpers.
Output:
- Complete
tailwind.config.ts with tokens and plugins.
app/globals.css or equivalent with layers and component classes.- 3 example custom components (Button, Card, Input) using the tokens.
- Theme toggle implementation.
- Documentation of the token system.
Examples
Full recommended tailwind.config.ts, CSS layers, and three component examples (Button with variants, Card, Form Input) are included in the skill output, along with dark mode toggle code.
Edge Cases & Error Handling
- Design token drift: Recommend a token studio or Figma Tokens plugin for sync.
- Bundle size: Use Tailwind's content paths correctly and purge in production.
- Arbitrary values abuse: Provide a "when to use arbitrary" guideline.
Verification
- Build the project — Tailwind classes generate correctly.
- Toggle dark mode — all components adapt properly.
- Check contrast ratios for primary/foreground pairs.
- Success: New developers can use
bg-primary, text-foreground, etc. consistently without guessing hex values.
References
1---2name: tailwind-design-system3description: Creates a Tailwind CSS design system with custom tokens, component classes, and dark mode. Use when establishing a consistent design language for a project.4license: Apache-2.05---67## Overview89Establishes a complete, maintainable Tailwind CSS design system by extending the config with semantic design tokens (colors, spacing, typography, shadows, radii), creating reusable component classes via `@apply` or a component library approach, setting up dark mode (class or media), and providing plugin examples for custom utilities.1011## When to Use This Skill1213- Starting a new project that will use Tailwind and needs a design language from day one.14- Standardizing an existing Tailwind project that has inconsistent colors, spacing, or component styles.15- Building or contributing to a design system / component library.1617## Prerequisites1819- Tailwind CSS 3.4+ installed (or via CDN for prototypes).20- `tailwind.config.ts` or `.js` in the project root.21- PostCSS and build pipeline set up.22- Design tokens or brand guidelines (or the skill will propose a sensible neutral + accent system).2324## Steps25261. **Audit current usage** (if existing project): Find all hard-coded colors, spacing, fonts.27282. **Design token architecture in tailwind.config.ts**:29 - Extend `theme.extend.colors` with semantic names (`primary`, `neutral`, `success`, `background`, `foreground`).30 - Use OKLCH or HSL for better dark mode and accessibility.31 - Define spacing scale, typography scale, border radius, box shadows as tokens.32333. **Dark mode setup**:34 - Preferred: `darkMode: 'class'` + `dark:` variants.35 - Alternative: `media` for system preference.36 - Provide a theme toggle component (button that adds/removes `dark` class on `<html>`).37384. **Component abstraction strategy**:39 - For simple components: use `@apply` in a `components.css` layer.40 - For complex or highly reusable: create actual React/Vue/Svelte components.41 - Document pros/cons of each approach.42435. **Create custom plugins** (optional but powerful):44 - Plugin for `text-balance`, `container-query` utilities, or brand-specific helpers.45466. **Output**:47 - Complete `tailwind.config.ts` with tokens and plugins.48 - `app/globals.css` or equivalent with layers and component classes.49 - 3 example custom components (Button, Card, Input) using the tokens.50 - Theme toggle implementation.51 - Documentation of the token system.5253## Examples5455Full recommended `tailwind.config.ts`, CSS layers, and three component examples (Button with variants, Card, Form Input) are included in the skill output, along with dark mode toggle code.5657## Edge Cases & Error Handling5859- **Design token drift**: Recommend a token studio or Figma Tokens plugin for sync.60- **Bundle size**: Use Tailwind's content paths correctly and purge in production.61- **Arbitrary values abuse**: Provide a "when to use arbitrary" guideline.6263## Verification64651. Build the project — Tailwind classes generate correctly.662. Toggle dark mode — all components adapt properly.673. Check contrast ratios for primary/foreground pairs.684. Success: New developers can use `bg-primary`, `text-foreground`, etc. consistently without guessing hex values.6970## References7172- [Tailwind CSS Configuration](https://tailwindcss.com/docs/configuration)73- [Tailwind Dark Mode](https://tailwindcss.com/docs/dark-mode)74- [Designing with Tailwind CSS (book)](https://tailwindcss.com/)75- [OKLCH Color Space](https://oklch.com/)
Nikoxkx