UI Design System

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

Application Layer
    ↓
shadcn/ui Components (Beautiful defaults, ready-to-use)
    ↓
Radix UI Primitives (Accessible behavior, unstyled)
    ↓
TailwindCSS Utilities (Design system, styling)

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

:root {
  /* Tier 1: Primitives (immutable) */
  --gray-50: 250 250 250;
  --gray-900: 24 24 27;
  --blue-500: oklch(0.55 0.22 264);

  /* Tier 2: Semantics (theme-aware) */
  --background: var(--gray-50);
  --foreground: var(--gray-900);
  --primary: var(--blue-500);

  /* Tier 3: Components */
  --button-height: 2.5rem;
  --card-padding: 1.5rem;
}

.dark {
  /* Only semantic tokens change */
  --background: var(--gray-900);
  --foreground: var(--gray-50);
}

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