tailwind-design-system

name	tailwind-design-system
description	Builds scalable design systems with Tailwind CSS 4 using CSS-based tokens, component patterns, and responsive guidelines with accessibility checks. Use when creating component libraries, implementing design systems, or refactoring and standardizing UI patterns.

Tailwind Design System

Design tokens, components, and responsive patterns for Tailwind CSS 4 with accessibility in mind.

When to Use

• Building a new design system or component library with Tailwind CSS 4
• Refactoring UI to standardize patterns and tokens
• Auditing and improving responsive behavior and accessibility

Inputs to Gather

• Product goals and brand constraints
• Target platforms and browsers
• Existing UI patterns or components to migrate
• Required breakpoints and density targets
• Accessibility requirements (default: best effort)

Steps

1. Define tokens (CSS-based config)

   • Create a single source of truth in a CSS file using @theme.
   • Prefer semantic tokens (e.g., --color-surface, --color-text) mapped to primitives.
   • Keep token names stable and design-system oriented.

2. Create component patterns

   • Define base classes in @layer components.
   • Keep variants and sizes consistent and composable.
   • Use utilities directly in templates for layout decisions.

3. Establish responsive rules

   • Adopt a small set of breakpoints with consistent naming.
   • Use container and spacing tokens to scale layouts.
   • Prefer logical properties when possible for RTL readiness.

4. Accessibility pass

   • Ensure visible focus (:focus-visible) on interactive elements.
   • Enforce minimum touch target sizes.
   • Respect reduced motion.
   • Keep color contrast readable for text and controls.

5. Deliverables

   • Token file (CSS)
   • Component pattern catalog
   • Responsive usage guidelines
   • Accessibility notes and exceptions

Templates

Token file (CSS)

@import 'tailwindcss';

@theme {
  /* Color primitives */
  --color-brand-50: #f5f7ff;
  --color-brand-500: #4f46e5;
  --color-neutral-0: #ffffff;
  --color-neutral-950: #0b0b0f;

  /* Semantic colors */
  --color-surface: var(--color-neutral-0);
  --color-surface-muted: #f6f7f9;
  --color-text: var(--color-neutral-950);
  --color-text-muted: #4b5563;
  --color-border: #e5e7eb;
  --color-ring: var(--color-brand-500);

  /* Typography */
  --font-sans: ui-sans-serif, system-ui, sans-serif;
  --text-sm: 0.875rem;
  --text-base: 1rem;
  --text-lg: 1.125rem;

  /* Spacing and radius */
  --spacing-1: 0.25rem;
  --spacing-2: 0.5rem;
  --spacing-3: 0.75rem;
  --spacing-4: 1rem;
  --radius-sm: 0.375rem;
  --radius-md: 0.5rem;
  --radius-lg: 0.75rem;

  /* Shadow */
  --shadow-card: 0 1px 2px rgba(0, 0, 0, 0.08);
}

@layer base {
  :root {
    color: var(--color-text);
    background: var(--color-surface);
  }
}

Component pattern (example)

@layer components {
  .btn {
    @apply inline-flex items-center justify-center gap-2 rounded-md px-4 py-2 text-sm font-medium;
    @apply bg-[var(--color-brand-500)] text-white;
    @apply focus-visible:ring-2 focus-visible:ring-[var(--color-ring)] focus-visible:outline-none;
    @apply disabled:pointer-events-none disabled:opacity-50;
  }

  .btn--ghost {
    @apply bg-transparent text-[var(--color-text)] hover:bg-[var(--color-surface-muted)];
  }

  .card {
    @apply rounded-lg border border-[var(--color-border)] bg-[var(--color-surface)] shadow-[var(--shadow-card)];
  }
}

Responsive rules (example)

Breakpoints:

- sm: compact layouts and stacked controls
- md: default desktop baseline
- lg: expanded content density

Layout:

- Use grid for page scaffolding with `gap` tied to spacing tokens
- Avoid fixed heights for content blocks
- Prefer `min-w-0` in flex layouts to avoid overflow

Accessibility checklist (best effort)

- Focus styles visible on all interactive elements
- Minimum target size 44px for touch
- Reduced motion respected (avoid forced animations)
- Text contrast readable on primary surfaces
- Form labels tied to inputs and error text announced

Scripts

Use the token extractor to keep a JSON snapshot of @theme tokens:

node ".cursor/skills/tailwind-design-system/scripts/extract-theme-tokens.mjs" path/to/tokens.css > tokens.json

Examples

Creating a new token set

1. Create design-tokens.css with @theme.
2. Add semantic tokens that map to primitives.
3. Generate tokens.json using the script above.

Refactoring a component library

1. Map existing class clusters to new component patterns.
2. Replace raw colors and spacing with tokens.
3. Document variants and states.

Output

Provide results as:

Design System Output
- Tokens file: <path>
- Components added/updated: <list>
- Responsive rules: <summary>
- Accessibility notes: <bullets>
- Open questions: <bullets>

Present Results to User

Return a concise report using the output template above, followed by any recommended next steps (tests, audits, or migration plan).