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:

Tailwind utilities for basic styling
Add Radix primitives for interaction
Use shadcn/ui for complete solutions
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

TailwindCSS - Foundation
shadcn/ui CLI - Includes Radix dependencies
Add components - Install only what you need
Configure theme - CSS variables + Tailwind config
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

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

Direct Modification: Edit shadcn/ui files in your codebase
Variant Extension: Use CVA for type-safe variants
Wrapper Components: Add custom logic around base components
Theme Customization: Modify CSS variables globally

Dark Mode Setup

ThemeProvider with next-themes
Class strategy (class, not media query)
CSS variables in .dark class
Accessible toggle component

📖 See 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

Automated: Use contrast checkers during design
Manual: Tab through entire interface
Screen readers: Test with at least one screen reader
Real users: Include users with disabilities in testing

Common Pitfalls

Avoid these frequent issues:

Dynamic classes: Tailwind doesn't generate at runtime → use conditionals
Content config: Verify paths include all component files
Import paths: Check tsconfig.json aliases
Dark mode: Ensure ThemeProvider setup and CSS variables
Accessibility: Never remove ARIA attributes

📖 See PERFORMANCE_OPTIMIZATION.md for complete troubleshooting guide with 10+ common issues and solutions.

Resources

Official Documentation

TailwindCSS: https://tailwindcss.com/docs
Radix UI: https://www.radix-ui.com/primitives
shadcn/ui: https://ui.shadcn.com | https://ui.shadcn.com/llms.txt

Authoritative Design System Sources

USWDS Design Tokens: https://designsystem.digital.gov/design-tokens/
Smashing Magazine Naming: https://www.smashingmagazine.com/2024/05/naming-best-practices/
OKLCH Color Space: https://evilmartians.com/chronicles/oklch-in-css-why-quit-rgb-hsl
WCAG Contrast: https://webaim.org/articles/contrast/

Reference Files (Detailed Guides & Patterns)

Core Concepts:

DESIGN_TOKENS.md - Three-tier token system, OKLCH, naming
RESPONSIVE_PATTERNS.md - Breakpoints, container queries, testing
CUSTOMIZATION.md - Component customization, dark mode, forms
PERFORMANCE_OPTIMIZATION.md - Performance, Core Web Vitals, pitfalls

Implementation References:

TAILWIND_REFERENCE.md - Complete utilities
RADIX_REFERENCE.md - Primitives with code
SHADCN_REFERENCE.md - Components with install
INTEGRATION_PATTERNS.md - Advanced patterns

Triggers & Use Cases

Behavioral Traits

Code Quality: Component composition | Single responsibility | Proper hooks usage | Optimized rendering | Comprehensive testing

Response Approach

Review: Understand context → Systematic audit → Identify issues → Provide evidence → Recommend solutions → Prioritize

Design: Gather requirements → Choose architecture → Design tokens → Component structure → Implement accessibly → Include states → Responsive → Document

Improve: Analyze current state → Identify bottlenecks → Plan improvements → Implement incrementally → Measure impact → Document → Test

Integration: Verify compatibility → Follow official patterns → Best practices → Type safety → Performance budget → Error boundaries

Implementation Checklist

Setup: Install Tailwind + shadcn/ui | Configure three-tier tokens | Set up dark mode | Create cn() helper

Development: Apply mobile-first design | Implement dark mode | Test accessibility | Verify WCAG AA contrast

Production: Validate Tailwind purging | Test all states | Cross-browser testing | Performance audit

📖 Detailed checklists available in:

Best Practices Summary

Skill Summary

Primary Functions:

Review: Audit UI/UX for accessibility, performance, and design system consistency
Design: Create production-ready interfaces with modern React and styling systems
Improve: Enhance existing implementations for better UX, performance, and maintainability

Technology Focus:

TailwindCSS, Radix UI, shadcn/ui (styling layer)
Design tokens and design systems
Accessibility standards (WCAG 2.1/2.2)
Responsive design and mobile-first patterns
Color systems (OKLCH) and typography

Activation Triggers:

UI/UX review, audit, or analysis requests
Design system architecture and token design
Accessibility improvements (WCAG compliance)
Tailwind/Radix/shadcn/ui implementation
Responsive design and mobile-first development
Color system and typography design

Boundaries: ✅ Design systems, styling, accessibility, design tokens, UI patterns ❌ React architecture (react-nextjs-expert), state management, backend APIs, infrastructure

Skill Version: 2.1.0 Last Updated: 2025-11-15 Enhanced With: UI/UX review capabilities, design system architecture, framework-agnostic patterns Authoritative Sources: WCAG 2.1/2.2, OKLCH color science, industry design systems (USWDS, Carbon, Polaris) Progressive Disclosure: Reference files for detailed guides ✅ Scope: Design systems, styling, accessibility, UI/UX patterns (framework-agnostic) Companion Skills: react-nextjs-expert (for React/Next.js architecture and state management)

ui-design-system

Safety Notice

Copy this and send it to your AI assistant to learn

UI/UX Design & Development Expert

Stack Architecture

The Three Pillars

Architecture Hierarchy

Core Capabilities

UI/UX Review & Audit

UI/UX Design

UI/UX Improvement

Styling Integration

When to Use Each Layer

Use TailwindCSS Directly When:

Use Radix UI Primitives When:

Use shadcn/ui Components When:

Critical Design Principles

1. Progressive Enhancement

2. Composition Over Complexity

3. Accessibility First

4. Design Token Consistency

5. Mobile-First Responsive

Setup Strategy

Installation Order

Configuration Best Practices

Integration Patterns

Pattern 1: shadcn/ui + Custom Tailwind

Pattern 2: Radix Primitives + Tailwind

Pattern 3: Hybrid Approach

Pattern 4: Component Composition

Design Token Architecture

Responsive Design Strategy

Form Architecture

Performance Best Practices

Component Customization & Dark Mode

Customization Strategies

Dark Mode Setup

Accessibility Standards

Radix UI Built-In Guarantees

WCAG Contrast Requirements (Critical)

Implementation Checklist

Testing Strategy

Common Pitfalls

Resources

Official Documentation

Authoritative Design System Sources

Reference Files (Detailed Guides & Patterns)

Triggers & Use Cases

Behavioral Traits

Response Approach

Implementation Checklist

Best Practices Summary

Skill Summary

Source Transparency

Related Skills

ui-ux-design

mise-expert

claude-md-architect