React UI component systems with TailwindCSS + Radix + shadcn/ui. Stack: TailwindCSS (styling), Radix UI (primitives), shadcn/ui (components), React/Next.js. Capabilities: design system architecture, accessible components, responsive layouts, theming, dark mode, component composition. Actions: review

UI/UX Design & Development Expert Comprehensive UI/UX design, review, and improvement for modern web applications. Production ready implementations with TailwindCSS + Radix UI + shadcn/ui and modern React patterns. Stack Architecture The Three Pillars Layer 1: TailwindCSS (Styling Foundation) Utility first CSS framework with build time generation Zero runtime overhead, minimal production bundles Design tokens: colors, spacing, typography, breakpoints Responsive utilities and dark mode support Layer 2: Radix UI (Behavior & Accessibility) Unstyled, accessible component primitives WAI ARIA compliant with keyboard navigation Focus management and screen reader support Unopinionated full styling control Layer 3: shadcn/ui (Beautiful Components) Pre built components = Radix primitives + Tailwind styling Copy paste distribution (you own the code) Built in React Hook Form + Zod validation Customizable variants with type safety Architecture Hierarchy Key Principle: Each layer enhances the one below. Start with Tailwind for styling, add Radix for accessible behavior, use shadcn/ui for complete components. Core Capabilities UI/UX Review & Audit Systematic evaluation of existing interfaces: Component Architecture Review: Analyze component composition, reusability, and single responsibility Accessibility Audit: WCAG 2.1/2.2 AA/AAA compliance, keyboard navigation, screen reader support Performance Analysis: Core Web Vitals (LCP, FID, CLS), bundle size, render performance Responsive Design Review: Mobile first implementation, breakpoint usage, container queries Design System Consistency: Token usage, spacing scale adherence, color palette compliance Code Quality: React best practices, hooks usage, state management patterns Visual Hierarchy: Typography scale, spacing rhythm, color contrast, focus indicators UI/UX Design Creating production ready interface designs: Component Design: Atomic design principles, composition patterns, variant systems Layout Architecture: Grid systems, flexbox patterns, responsive containers Interaction Design: Hover states, focus states, loading states, error states Design Tokens: Three tier token system (primitive → semantic → component) Color Systems: OKLCH color space, accessible palettes, dark mode support Typography Systems: Scale design, hierarchy, readability optimization Animation & Transitions: Micro interactions, loading feedback, state changes UI/UX Improvement Enhancing existing implementations: Accessibility Enhancement: ARIA patterns, semantic HTML, keyboard navigation Performance Optimization: Code splitting, lazy loading, virtualization, image optimization Responsive Refinement: Breakpoint optimization, mobile first improvements Component Refactoring: Extract shared patterns, reduce complexity, improve reusability Visual Polish: Spacing consistency, typography refinement, color harmony State Management: Optimistic updates, error handling, loading states Developer Experience: Component documentation, Storybook stories, type safety Styling Integration Framework agnostic styling approaches: Tailwind with Components: Utility first styling for any framework CSS in JS: emotion, styled components, vanilla extract CSS Modules: Scoped styles without runtime overhead Design System Integration: Token based styling across frameworks When to Use Each Layer Use TailwindCSS Directly When: Building custom layouts and spacing Styling static content and containers Rapid prototyping without complex interactions Non interactive UI elements Example scenarios: Hero sections, grid layouts, cards without interaction, text styling Use Radix UI Primitives When: Building custom component libraries Need accessibility but require custom design shadcn/ui doesn't have the component you need Full control over component structure required Example scenarios: Custom date picker, unique navigation pattern, specialized modal behavior Use shadcn/ui Components When: Building standard UI components quickly Need beautiful defaults with customization options Enterprise application development Form heavy applications with validation Example scenarios: Admin dashboards, CRUD applications, settings pages, data tables Critical Design Principles 1. Progressive Enhancement Start simple, enhance as needed: 1. Tailwind utilities for basic styling 2. Add Radix primitives for interaction 3. Use shadcn/ui for complete solutions 4. Customize components in your codebase 2. Composition Over Complexity Build complex UIs from simple, reusable components: Small, focused components (single responsibility) Compose primitives rather than creating monoliths Leverage component slots and children patterns 3. Accessibility First Radix UI handles accessibility automatically: ARIA attributes applied correctly Keyboard navigation built in Focus management and trapping Screen reader compatibility Never override accessibility features enhance them. 4. Design Token Consistency Use Tailwind's design system consistently: Stick to spacing scale (4, 8, 16, 24px) Use color palette (50 950 shades) Apply typography scale systematically Avoid arbitrary values unless necessary 5. Mobile First Responsive Always design mobile first, scale up: Base styles for mobile Use breakpoints (sm, md, lg, xl, 2xl) to enhance Test on actual devices, not just browser resize Setup Strategy Installation Order 1. TailwindCSS Foundation 2. shadcn/ui CLI Includes Radix dependencies 3. Add components Install only what you need 4. Configure theme CSS variables + Tailwind config 5. Setup dark mode Theme provider + toggle Configuration Best Practices Tailwind Config: Use content paths correctly (scan all component files) Extend theme with CSS variables, not hardcoded values Enable dark mode with class strategy Install tailwindcss animate plugin CSS Variables (Three Tier System): Color Space Recommendation: Modern : Use OKLCH for perceptual uniformity Legacy support : Use HSL with fallbacks Avoid : RGB/HEX for design tokens (not human readable) Token Storage: Store in JSON for platform agnostic distribution Transform to CSS variables, Swift, XML using Style Dictionary Version control tokens separately from component code Path Aliases: Configure @/components and @/lib in tsconfig Ensure consistency between Next.js and TypeScript configs Use aliases in imports for cleaner code Integration Patterns Pattern 1: shadcn/ui + Custom Tailwind Use shadcn/ui components as base, customize with Tailwind classes: Apply custom spacing, colors via className prop Override default styles with Tailwind utilities Maintain component accessibility Pattern 2: Radix Primitives + Tailwind Build custom components from scratch: Use Radix for behavior (Dialog, Dropdown, etc.) Style completely with Tailwind utilities Full control over structure and appearance Pattern 3: Hybrid Approach Modify shadcn/ui components in your codebase: Edit component files in components/ui/ Add new variants, sizes, or styles Maintain type safety with CVA (Class Variance Authority) Pattern 4: Component Composition Combine multiple primitives for complex UIs: Popover + Select for searchable dropdown Dialog + Form for modal forms Tabs + Cards for multi section interfaces Design Token Architecture Use three tier token system for scalable, maintainable design systems: Tier 1 (Primitive) : Raw values ( gray 50 , spacing 4 ) Tier 2 (Semantic) : Purpose driven ( background primary , text error ) Tier 3 (Component) : Component specific ( button height , card padding ) Modern Color: Use OKLCH color space for perceptual uniformity and better accessibility calculations. 📖 See [DESIGN TOKENS.md](references/DESIGN TOKENS.md) for: Complete three tier token system implementation OKLCH color space guide and examples Token naming conventions and best practices CSS variable configuration Multi theme support patterns Responsive Design Strategy Mobile first approach: Start with mobile (0 639px), scale up through sm/md/lg/xl/2xl breakpoints. Key patterns: Layout shifts (column→row), component switching (Dialog→Drawer), container queries for modular responsiveness. 📖 See [RESPONSIVE PATTERNS.md](references/RESPONSIVE PATTERNS.md) for: Complete breakpoint strategy and implementation Responsive component patterns and examples Container queries guide Image optimization strategies Performance considerations for responsive design Comprehensive testing checklist Form Architecture Strategy: React Hook Form + Zod for schema first validation with type inference and accessible error handling. 📖 See [CUSTOMIZATION.md](references/CUSTOMIZATION.md form architecture) for: Complete React Hook Form + Zod setup Reusable field wrapper patterns Multi step form implementation Accessibility requirements checklist Performance Best Practices Core strategies: Code splitting (React.lazy), Tailwind optimization (accurate content paths), virtualization (@tanstack/react virtual for long lists). 📖 See [PERFORMANCE OPTIMIZATION.md](references/PERFORMANCE OPTIMIZATION.md) for: Complete performance optimization guide Core Web Vitals optimization strategies Bundle analysis and tree shaking Common pitfalls and solutions Performance monitoring setup Component Customization & Dark Mode Customization Strategies 1. Direct Modification : Edit shadcn/ui files in your codebase 2. Variant Extension : Use CVA for type safe variants 3. Wrapper Components : Add custom logic around base components 4. Theme Customization : Modify CSS variables globally Dark Mode Setup 1. ThemeProvider with next themes 2. Class strategy ( class , not media query) 3. CSS variables in .dark class 4. Accessible toggle component 📖 See [CUSTOMIZATION.md](references/CUSTOMIZATION.md) for: Complete customization strategies with examples CVA variant implementation guide Dark mode setup and configuration Design considerations and testing Form architecture patterns Accessibility Standards Radix UI Built In Guarantees ✅ ARIA attributes applied correctly ✅ Keyboard navigation functional ✅ Focus management and trapping automatic ✅ Screen reader compatible WCAG Contrast Requirements (Critical) WCAG 2.1 Level AA (Legal Minimum): Normal text: 4.5:1 minimum contrast ratio Large text (18pt/14pt bold+): 3:1 minimum UI components/graphics: 3:1 minimum Industry standard : Most legal requirements specify AA WCAG Level AAA (Enhanced): Normal text: 7:1 contrast ratio Large text: 4.5:1 contrast ratio Best practice : Aim for AAA when design constraints allow Measurement: Contrast ratio range: 1:1 (white on white) to 21:1 (black on white) Use tools: WebAIM Color Contrast Checker, browser DevTools Test during design phase, not after implementation OKLCH Advantage: Perceptually uniform color space makes contrast calculations more reliable and predictable compared to HSL. Implementation Checklist ✅ All text meets 4.5:1 minimum (AA standard) ✅ Interactive elements meet 3:1 minimum ✅ Provide descriptive labels ( aria label , <label ) ✅ Test complete keyboard navigation flow ✅ Verify visible focus indicators (not just browser default) ✅ Test with screen readers (NVDA, JAWS, VoiceOver) ✅ Use semantic HTML elements ( <button , <nav , <main ) ✅ Provide alternative text for images and icons ✅ Ensure dark mode maintains contrast standards Testing Strategy 1. Automated : Use contrast checkers during design 2. Manual : Tab through entire interface 3. Screen readers : Test with at least one screen reader 4. Real use

ui-design-system