# ADR-005: Atomic Design for UI Components

## Status: Accepted

## Context

Need a scalable component architecture for the shared UI package.

## Decision

Atomic Design (atoms/molecules/organisms/templates) + shadcn/ui + Storybook.

## Rationale

- Clear hierarchy makes agents know exactly where to place new components
- Import rules enforce composition direction (atoms never import molecules)
- Co-located stories make components self-documenting
- shadcn/ui provides excellent base atoms that map naturally to atomic levels
- Storybook sidebar mirrors the hierarchy via story titles
- Pages live in apps (not UI package) — they connect to real data