UI Components

UI Components

Build accessible, responsive, and visually intentional UI components. Production quality — not AI-generated boilerplate.

Core principle: Every component ships with: keyboard navigation, screen reader support, loading/error/empty states, and responsive behavior. Accessibility is not optional.

When to Use

• Building new UI components
• Reviewing existing components for quality
• Implementing accessibility (WCAG 2.1 AA)
• Detecting and removing AI aesthetic anti-patterns
• Creating component variants with consistent API

When NOT to Use

• Design system setup (color, typography, tokens) — use design-system skill
• Performance optimization of components — use frontend-performance skill

Component Architecture

Atomic Design Hierarchy

Composition Over Configuration

// Good: composable — caller controls structure
<Card>
  <CardHeader>
    <CardTitle>Tasks</CardTitle>
    <CardDescription>Your pending work</CardDescription>
  </CardHeader>
  <CardContent>
    <TaskList tasks={tasks} />
  </CardContent>
</Card>

// Avoid: over-configured — caller can't customize structure
<Card title="Tasks" subtitle="Your pending work" content={<TaskList />} />

Container/Presentation Split

// Container: fetches and manages data
function TaskListContainer() {
  const { tasks, isLoading, error } = useTasks();
  if (isLoading) return <TaskListSkeleton />;
  if (error) return <ErrorState message="Failed to load tasks" />;
  if (tasks.length === 0) return <EmptyState message="No tasks yet" action={<CreateTaskButton />} />;
  return <TaskList tasks={tasks} />;
}

// Presentation: pure display, no data fetching
function TaskList({ tasks }: { tasks: Task[] }) {
  return (
    <ul role="list">
      {tasks.map(task => <TaskItem key={task.id} task={task} />)}
    </ul>
  );
}

Component Variants (class-variance-authority)

import { cva } from 'class-variance-authority';

const buttonVariants = cva(
  'inline-flex items-center justify-center rounded-md font-medium transition-colors',
  {
    variants: {
      variant: {
        default: 'bg-primary text-primary-foreground hover:bg-primary/90',
        outline: 'border border-input hover:bg-accent',
        ghost: 'hover:bg-accent hover:text-accent-foreground',
        destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
      },
      size: {
        sm: 'h-9 px-3 text-sm',
        default: 'h-10 px-4 py-2',
        lg: 'h-11 px-8 text-base',
        icon: 'h-10 w-10',
      },
    },
    defaultVariants: { variant: 'default', size: 'default' },
  }
);

Required States

Every interactive component must handle all states:

WCAG 2.1 AA Accessibility

Keyboard Navigation

// All interactive elements must be keyboard accessible
// Tab moves focus, Enter/Space activates, Escape closes modals/dropdowns

// Modal: trap focus inside
function Modal({ isOpen, onClose, children }) {
  const ref = useRef<HTMLDivElement>(null);
  
  useEffect(() => {
    if (!isOpen) return;
    const firstFocusable = ref.current?.querySelector<HTMLElement>(
      'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
    );
    firstFocusable?.focus();
  }, [isOpen]);

  return isOpen ? (
    <div role="dialog" aria-modal="true" ref={ref} => {
      if (e.key === 'Escape') onClose();
    }}>
      {children}
    </div>
  ) : null;
}

ARIA Checklist

<!-- Icon-only button: must have label -->
<button aria-label="Close dialog"><XIcon aria-hidden="true" /></button>

<!-- Toggle button: announce state -->
<button aria-expanded="false" aria-controls="menu">Menu</button>

<!-- Live region for dynamic content -->
<div aria-live="polite" aria-atomic="true">3 items in cart</div>

<!-- Form input: label association -->
<label for="email">Email address</label>
<input id="email" type="email" aria-required="true" 
       aria-describedby="email-hint email-error">
<p id="email-hint">We'll never share your email.</p>
<p id="email-error" role="alert">Email is required.</p>

Full Accessibility Checklist

• Keyboard navigation works (Tab through entire page)
• Screen reader announces content and structure correctly
• Color contrast passes (4.5:1 text, 3:1 UI elements)
• Focus indicators visible on every interactive element
• All form inputs have associated labels (not just placeholder)
• All images have descriptive alt text (or alt="" if decorative)
• Headings are hierarchical (h1→h2→h3, no skips)
• Link text is descriptive ("View task details" not "click here")
• Touch targets minimum 44×44px
• aria-label on all icon-only buttons
• Modals trap focus and restore focus on close

Responsive Design

Breakpoints:
  375px  — mobile portrait (minimum)
  768px  — tablet portrait
  1024px — tablet landscape / small desktop
  1440px — desktop

Rules:
  - Mobile-first: start with mobile styles, add breakpoints upward
  - All multi-column layouts collapse below 768px
  - No horizontal scroll on any viewport (critical failure)
  - Touch targets ≥44px on mobile
  - Body text ≥16px on mobile
  - Use min-h-[100dvh] not h-screen (iOS Safari fix)

// Mobile-first responsive grid
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
  {items.map(item => <Card key={item.id} {...item} />)}
</div>

AI Slop Anti-Patterns (Banned)

These patterns signal AI-generated UI without design intent:

8 specific forbidden patterns:

Interactive State Completeness Rule

Every component must implement all four data states before it is considered complete:

A component missing any of these four states is incomplete and must not ship.

Content Standards

• Never lorem ipsum — use realistic placeholder content
• No broken image links — use picsum.photos or SVG placeholders
• No generic names ("John Doe", "Acme Corp") — use realistic names
• No placeholder copy that will ship (it will ship)

Component Quality Limits

Verification Checklist

• All interactive states handled (default, hover, focus, active, disabled, loading, error, empty)
• Keyboard navigation works (Tab, Enter, Escape)
• Screen reader announced content tested
• Color contrast passes (run axe DevTools or Lighthouse)
• Focus indicators visible and meet 3:1 contrast
• All icon-only buttons have aria-label
• All form inputs have associated <label>
• Touch targets ≥44px on mobile
• Responsive: works at 375px, 768px, 1024px, 1440px
• No horizontal scroll at any viewport
• No AI aesthetic patterns (purple gradients, excessive rounding, lorem ipsum)
• Semantic color tokens used throughout (no raw hex values)
• Component <200 lines
• No inline styles or arbitrary pixel values