Tailwind CSS Design System Builder

You are a design systems engineer specializing in Tailwind CSS who has built and maintained design systems used by large frontend teams. Create a complete Tailwind-based design system for the following project.

Project Details:
Brand Name: [BRAND NAME]
Design Maturity: [NO EXISTING DESIGN SYSTEM/MIGRATING FROM ANOTHER SYSTEM/EXTENDING EXISTING TAILWIND SETUP]
Framework: [REACT/VUE/SVELTE/ANGULAR/MULTI-FRAMEWORK]
Component Library Base: [HEADLESS UI/RADIX/SHADCN/CUSTOM]
Team Size: [NUMBER OF DEVELOPERS USING THE SYSTEM]
Brand Guidelines: [STRICT BRAND GUIDE/FLEXIBLE/BEING DEFINED]

Section 1 - Tailwind Configuration and Token Architecture:
Design the tailwind.config.ts file structure defining the complete token system including color scales with semantic naming like primary, secondary, destructive, and muted alongside numeric shades from 50 through 950. Establish the typography scale covering font families, font sizes with corresponding line heights and letter spacing, and font weight definitions that map to the brand typography guide. Define the spacing scale including whether to extend or override the default scale and how to handle component-specific spacing tokens. Create the breakpoint system covering mobile, tablet, desktop, and wide screen sizes with guidelines on when to add custom breakpoints. Address how to structure the configuration for multi-theme support including light mode, dark mode, and potential brand themes using CSS custom properties that Tailwind classes reference.

Section 2 - Component Pattern Library:
Define the base component patterns using Tailwind including buttons with size variants and states, form inputs with focus and error styling, cards with consistent padding and shadow scales, and badge and tag components. Create the compound component styling approach showing how complex components like modals, dropdowns, and navigation menus should compose Tailwind classes across their sub-elements. Establish the variant management strategy using either class-variance-authority (CVA) or a custom utility function that maps variant props to Tailwind class combinations. Specify how to handle interactive states consistently including hover, focus-visible, active, and disabled states with accessible focus indicators. Address the approach for animation and transition classes including entrance and exit animations for dynamic elements like toasts, modals, and expanding sections.

Section 3 - Utility Class Organization and Conventions:
Establish the class ordering convention specifying the sequence in which utility classes should appear such as layout, positioning, sizing, spacing, typography, colors, borders, effects, and responsive modifiers. Define the strategy for managing long class strings including when to extract classes into component abstractions versus keeping them inline and how to use the cn or clsx utility for conditional class merging. Create guidelines for responsive design patterns showing how to apply mobile-first breakpoint prefixes consistently across components. Specify the approach for handling one-off styles using Tailwind's arbitrary value syntax including when arbitrary values are acceptable and when they indicate a missing design token. Address the team workflow for reviewing Tailwind class usage in code reviews including common anti-patterns to watch for and Prettier plugin configuration for automatic class sorting.

Section 4 - Dark Mode and Theme Implementation:
Design the dark mode implementation strategy using either the class-based or media-based approach with justification for the choice. Define the color mapping between light and dark themes ensuring sufficient contrast ratios for accessibility compliance across all color pairings. Create the theme switching mechanism including how to persist the user preference, handle system preference detection, and prevent the flash of incorrect theme on initial page load. Specify how semantic color tokens should adapt between themes so components use context-aware colors like background, foreground, and muted rather than fixed color values. Address how to handle images, illustrations, and other visual assets that need theme-specific treatment including SVG fill colors and image overlays.

Section 5 - Custom Plugin and Extension Development:
Create custom Tailwind plugins for project-specific utilities that extend the framework with domain-relevant classes such as prose styles for content, grid templates for dashboard layouts, or container query utilities. Define the approach for creating component-level plugins that register new base styles, component classes, or utility classes specific to the design system. Establish guidelines for when to create a Tailwind plugin versus using the theme configuration versus applying styles in component code. Specify how to build responsive typography using fluid type scales with clamp functions exposed as Tailwind utilities. Address how to create and distribute the design system configuration as a shareable Tailwind preset that other projects in the organization can import and extend.

Section 6 - Documentation, Tooling, and Governance:
Define the design system documentation structure including a token reference showing all available design tokens with visual previews, a component gallery with live examples, and usage guidelines with do and don't examples. Specify the developer tooling setup including the Tailwind CSS IntelliSense VS Code extension configuration, the Prettier plugin for class sorting, and ESLint rules for enforcing Tailwind conventions. Create the contribution workflow for adding new tokens, components, or utilities to the design system including the proposal, review, and release process. Design the versioning strategy for the design system including how breaking changes to tokens or component patterns are communicated and migrated. Address the design-to-development handoff process including how designers should reference Tailwind tokens in design tools like Figma and how to maintain synchronization between design files and code.