UI Component Architect

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

Memory Integration

Before Starting

Recall existing component patterns and past UI decisions:

code

mcp__memory__memory_recall(query="UI component [component-type] pattern reuse")

After Completing

Store new component patterns for future reuse:

code

mcp__memory__memory_store(
  content="UI pattern: [component-name] - [description]. Location: [path]. Props: [key-props]. Reuse for: [use-cases].",
  type="fact",
  tags=["ui", "component", "[component-type]"],
  importance=6
)

Core Principles

•Reuse over recreation - Always search for existing components before creating new ones
•State completeness - Every UI must handle all possible states
•Pixel-perfect execution - Match designs exactly, no approximations
•Atomic decomposition - Break complex UI into smallest reusable pieces
•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:

bash

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

bash

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

bash

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

bash

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

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

2.2 Reuse Decision Matrix

For each identified component, determine:

Component Need	Action
Exact match exists	Import and use directly
Similar exists, minor diff	Extend via props/variants
Pattern exists, new content	Create using same structure
Nothing similar	Create new, following conventions

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:

tsx

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

tsx

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

tsx

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

tsx

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

code

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:

tsx

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:

Quick Reference: Search Patterns

Find Components by Type

bash

# 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

bash

# 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

bash

# 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

Playwright Visual Testing

After implementing UI components, use Playwright MCP to verify visual correctness.

Navigate to Component

code

mcp__playwright__browser_navigate(url="http://localhost:3000/[page]")

Take Screenshots at Different Viewports

code

# Mobile
mcp__playwright__browser_resize(width=375, height=667)
mcp__playwright__browser_screenshot()

# Desktop
mcp__playwright__browser_resize(width=1920, height=1080)
mcp__playwright__browser_screenshot()

Get Accessibility Snapshot

code

mcp__playwright__browser_snapshot()

Test Interactive States

code

# Hover state
mcp__playwright__browser_hover(selector="[data-testid='button']")
mcp__playwright__browser_screenshot()

# Focus state
mcp__playwright__browser_click(selector="input[name='field']")
mcp__playwright__browser_screenshot()

# Active/pressed state
mcp__playwright__browser_click(selector="[data-testid='button']")

Visual Verification Checklist

• Component renders correctly on mobile (375px)
• Component renders correctly on desktop (1920px)
• All states visible and correct (loading, error, empty, success)
• Interactive states work (hover, focus, active)
• Accessibility tree is correct (proper roles, labels)
• No visual regressions from existing components

Output Expectations

When implementing UI with this skill:

•Component Inventory - List of existing components to reuse
•Decomposition Plan - Hierarchy of components needed
•State Matrix - All states each component must handle
•Implementation - Pixel-perfect code following conventions
•Visual Verification - Screenshots from Playwright testing
•Reusability Report - New components created for future reuse