ui-design-system

What this skill does

# 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):**
```css
: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
Mod