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