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

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.

Create component patterns

• Define base classes in @layer components .

• Keep variants and sizes consistent and composable.

• Use utilities directly in templates for layout decisions.

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.

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.

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

• Create design-tokens.css with @theme .

• Add semantic tokens that map to primitives.

• Generate tokens.json using the script above.

Refactoring a component library

• Map existing class clusters to new component patterns.

• Replace raw colors and spacing with tokens.

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