UI Component Architect

Specialist skill for implementing UI with maximum component reuse, comprehensive state handling, and pixel-perfect design adherence.

Core Principles

1. Reuse over recreation - Always search for existing components before creating new ones
2. State completeness - Every UI must handle all possible states
3. Pixel-perfect execution - Match designs exactly, no approximations
4. Atomic decomposition - Break complex UI into smallest reusable pieces
5. Consistency enforcement - Use established patterns throughout the codebase

Implementation Workflow

Phase 1: Codebase Discovery

Before writing any code, thoroughly explore the existing codebase.

1.1 Identify Component Library

Search for the UI library/framework in use:

# Check package.json for UI dependencies
grep -E "(shadcn|radix|chakra|material|antd|mantine|headless)" package.json

# Find component directories
find . -type d -name "components" -o -name "ui" -o -name "common" | head -20

# Look for component index/barrel files
find . -name "index.ts" -path "*/components/*" | head -20

1.2 Catalog Existing Components

Create a mental inventory by searching for:

Basic UI Elements:

# Buttons, inputs, form elements
grep -rl "Button\|Input\|Select\|Checkbox\|Radio\|Switch\|Textarea" --include="*.tsx" --include="*.jsx" src/ | head -30

# Cards, containers, layouts
grep -rl "Card\|Container\|Box\|Stack\|Grid\|Flex" --include="*.tsx" --include="*.jsx" src/ | head -30

# Modals, dialogs, sheets
grep -rl "Modal\|Dialog\|Sheet\|Drawer\|Popover\|Tooltip" --include="*.tsx" --include="*.jsx" src/ | head -30

State Components (Critical):

# Loading states
grep -rl "Loading\|Spinner\|Skeleton\|Shimmer\|Loader" --include="*.tsx" --include="*.jsx" src/

# Empty/no-data states
grep -rl "Empty\|NoData\|NoResults\|Placeholder" --include="*.tsx" --include="*.jsx" src/

# Error states
grep -rl "Error\|ErrorBoundary\|ErrorMessage\|ErrorState" --include="*.tsx" --include="*.jsx" src/

# Fallback states
grep -rl "Fallback\|NotFound\|Offline" --include="*.tsx" --include="*.jsx" src/

1.3 Identify Design Tokens

Search for design system constants:

# Colors, spacing, typography
grep -rl "colors\|spacing\|fontSize\|fontWeight" --include="*.ts" --include="*.js" --include="*.css" src/ | head -20

# Tailwind config if used
cat tailwind.config.* 2>/dev/null | head -100

# CSS variables
grep -r "--" --include="*.css" src/ | head -30

Phase 2: UI Decomposition

Break down the target UI into atomic components.

2.1 Component Hierarchy Analysis

For any UI requirement, decompose into:

1. Layout Components - Page structure, grids, containers
2. Composite Components - Cards, forms, lists, tables
3. Atomic Components - Buttons, inputs, icons, badges
4. State Wrappers - Loading, error, empty state handlers

2.2 Reuse Decision Matrix

For each identified component, determine:

Phase 3: State Handling

Every UI component must handle these states:

3.1 Required States Checklist

• Loading - Initial data fetch, action in progress
• Success - Normal display with data
• Empty - No data available (but successful fetch)
• Error - Fetch/action failed
• Partial - Some data, some errors
• Offline - No network (if applicable)
• Disabled - User cannot interact
• Skeleton - Content placeholder during load

3.2 State Component Patterns

Search for and reuse existing state patterns:

// Pattern: Wrapper component with state handling
<DataDisplay
  isLoading={isLoading}
  error={error}
  data={data}
  loadingComponent={<LoadingSkeleton />}
  errorComponent={<ErrorMessage error={error} />}
  emptyComponent={<EmptyState message="No items found" />}
>
  {(data) => <ActualContent data={data} />}
</DataDisplay>

// Pattern: Conditional rendering with consistent components
{isLoading && <LoadingSpinner />}
{error && <ErrorBanner error={error} />}
{!isLoading && !error && data.length === 0 && <EmptyState />}
{!isLoading && !error && data.length > 0 && <Content data={data} />}

3.3 Create Missing State Components

If state components don't exist, create reusable ones:

// Loading skeleton - generic and configurable
interface SkeletonProps {
  variant: 'text' | 'circular' | 'rectangular';
  width?: string | number;
  height?: string | number;
  count?: number;
}

// Empty state - reusable across app
interface EmptyStateProps {
  icon?: React.ReactNode;
  title: string;
  description?: string;
  action?: {
    label: string;
    onClick: () => void;
  };
}

// Error state - consistent error display
interface ErrorStateProps {
  error: Error | string;
  retry?: () => void;
  variant?: 'inline' | 'fullPage' | 'toast';
}

Phase 4: Pixel-Perfect Implementation

4.1 Design Fidelity Checklist

• Spacing - Exact margins, padding, gaps
• Typography - Font size, weight, line-height, letter-spacing
• Colors - Exact hex/rgb values, opacity
• Borders - Width, radius, style, color
• Shadows - Offset, blur, spread, color
• Sizing - Exact widths, heights, aspect ratios
• Alignment - Precise positioning and alignment
• Responsive - Breakpoint-specific styles

4.2 Design Token Usage

Always use design tokens instead of hardcoded values:

// Bad - hardcoded values
<div style={{ padding: '16px', color: '#333' }}>

// Good - design tokens (Tailwind)
<div className="p-4 text-gray-800">

// Good - CSS variables
<div style={{ padding: 'var(--spacing-4)', color: 'var(--color-text-primary)' }}>

4.3 Responsive Implementation

Consider all viewport sizes:

// Mobile-first responsive design
<div className="
  p-2 md:p-4 lg:p-6
  grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3
  gap-2 md:gap-4
">

Phase 5: Component Creation Guidelines

When creating new components:

5.1 File Structure

Follow existing project conventions. Common patterns:

components/
├── ui/                    # Atomic UI components
│   ├── Button/
│   │   ├── Button.tsx
│   │   ├── Button.test.tsx
│   │   └── index.ts
│   └── ...
├── features/              # Feature-specific composites
│   ├── UserCard/
│   └── ...
└── layouts/               # Page layouts
    └── ...

5.2 Component Interface Design

Design props for maximum reusability:

interface ComponentProps {
  // Core functionality
  variant?: 'primary' | 'secondary' | 'ghost';
  size?: 'sm' | 'md' | 'lg';

  // State control
  isLoading?: boolean;
  isDisabled?: boolean;

  // Composition
  leftIcon?: React.ReactNode;
  rightIcon?: React.ReactNode;
  children?: React.ReactNode;

  // Accessibility
  'aria-label'?: string;

  // Extension
  className?: string;
  style?: React.CSSProperties;
}

5.3 Accessibility Requirements

Every component must include:

• Semantic HTML elements
• ARIA attributes where needed
• Keyboard navigation support
• Focus management
• Color contrast compliance
• Screen reader compatibility

Quick Reference: Search Patterns

Find Components by Type

# Interactive elements
grep -rl "onClick\|onPress\|onSubmit" --include="*.tsx" src/components/

# Form components
grep -rl "useState\|useForm\|register\|handleSubmit" --include="*.tsx" src/components/

# Data display components
grep -rl "map(\|\.map\|forEach" --include="*.tsx" src/components/

# Modal/overlay components
grep -rl "Portal\|createPortal\|fixed\|z-50" --include="*.tsx" src/components/

Find Styling Patterns

# Tailwind classes usage
grep -roh "className=\"[^\"]*\"" --include="*.tsx" src/ | sort | uniq -c | sort -rn | head -20

# CSS modules
find . -name "*.module.css" -o -name "*.module.scss"

# Styled components
grep -rl "styled\." --include="*.tsx" src/

Find State Handling Patterns

# React Query / SWR usage
grep -rl "useQuery\|useSWR\|useMutation" --include="*.tsx" src/

# Loading state patterns
grep -rn "isLoading\|loading\|pending" --include="*.tsx" src/components/ | head -20

# Error handling patterns
grep -rn "isError\|error\|catch" --include="*.tsx" src/components/ | head -20

Output Expectations

When implementing UI with this skill:

1. Component Inventory - List of existing components to reuse
2. Decomposition Plan - Hierarchy of components needed
3. State Matrix - All states each component must handle
4. Implementation - Pixel-perfect code following conventions
5. Reusability Report - New components created for future reuse