agentic-dev-template/docs/decisions/adr-005-atomic-design.md

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