ADR-085: Atomic Design Component Library
Document: ADR-085-atomic-design-component-library
Version: 1.0.0
Purpose: Establish Atomic Design as component hierarchy standard
Audience: Frontend developers, UI designers, agent builders
Date Created: 2026-01-19
Status: ACCEPTED
Related ADRs:
- ADR-084-moe-ui-agent-architecture (agent pipeline)
- ADR-086-ag-ui-event-protocol-integration (event streaming)
Related Documents:
- coditect-core-standards/CODITECT-STANDARD-COMPONENT-LIBRARY.md
- coditect-core-standards/CODITECT-STANDARD-DESIGN-TOKENS.md
Context and Problem Statement
CODITECT needs a systematic approach to UI component organization that:
- Enables consistent composition patterns
- Supports AI-assisted component selection
- Scales from simple inputs to complex page layouts
- Works across multiple frontend frameworks
Current state: Components are organized ad-hoc, making it difficult for agents to select appropriate abstraction levels and compose UIs systematically.
Why now: The MoE UI agent pipeline (ADR-084) requires a well-defined component hierarchy for the moe-ui-component-library-curator agent to make intelligent component selections.
Decision Drivers
Mandatory Requirements (Must-Have)
- Clear hierarchy for component classification
- Composability rules that AI agents can follow
- Framework-agnostic definitions (React, Vue, Angular)
- Complete coverage of enterprise UI patterns
Important Goals (Should-Have)
- Design tokens integration at all levels
- Accessibility built into component contracts
- Storybook documentation compatibility
- TypeScript type definitions
Nice-to-Have
- Automatic component suggestion based on context
- Visual component explorer
- Design system migration tools
Considered Options
Option 1: Atomic Design (SELECTED)
Description: Brad Frost's Atomic Design methodology with 4 levels: Atoms → Molecules → Organisms → Templates. Pages are runtime instances, not components.
┌─────────────────────────────────────────────────────┐
│ TEMPLATES (6) │
│ Page layouts - arrange organisms │
│ DashboardGrid, DetailView, KanbanBoard │
├─────────────────────────────────────────────────────┤
│ ORGANISMS (9) │
│ Complex sections - distinct purpose │
│ Header, Card, Modal, DataTable, Form │
├─────────────────────────────────────────────────────┤
│ MOLECULES (11) │
│ Groups of atoms - simple features │
│ FormField, SearchInput, StatusIndicator │
├─────────────────────────────────────────────────────┤
│ ATOMS (13) │
│ Basic building blocks - indivisible │
│ Button, Input, Label, Badge, Avatar, Icon │
└─────────────────────────────────────────────────────┘
Pros:
- Industry-standard methodology with extensive documentation
- Clear composition rules (atoms compose into molecules, etc.)
- Matches mental model of design systems
- AI agents can follow decision tree for classification
- Scales from simple to enterprise-complex UIs
Cons:
- Learning curve for teams new to methodology
- Some edge cases don't fit cleanly into levels
- Templates vs Pages distinction can confuse
Effort: Medium
Option 2: Flat Component Library (REJECTED)
Description: All components at single level, categorized by function (forms, navigation, display).
Pros:
- Simpler mental model
- No hierarchy to learn
- Easy to add new components
Cons:
- No composition guidance
- AI cannot infer abstraction level
- Leads to inconsistent component granularity
- Hard to enforce design system rules
Effort: Low
Option 3: Custom 6-Level Hierarchy (REJECTED)
Description: Custom hierarchy: Primitives → Elements → Patterns → Features → Layouts → Applications.
Pros:
- More granular than Atomic Design
- Custom-tailored to our needs
Cons:
- No industry adoption (documentation burden)
- Harder to train AI agents
- No existing tooling support
- Reinventing the wheel
Effort: High
Decision Outcome
Chosen Option: Option 1 - Atomic Design
Rationale: Atomic Design is the industry standard for design systems, with extensive documentation, community support, and tooling. AI agents can be trained on published Atomic Design materials, and the clear hierarchy enables the decision tree classification needed by moe-ui-a2ui-renderer.
Consequences
Positive Consequences
- Consistent Abstraction: All components have defined level
- Compositional Rules: Clear contracts between levels
- AI-Friendly: Decision tree classification for agents
- Industry Alignment: Developers familiar with methodology
- Tooling Support: Storybook, Figma plugins, etc.
Negative Consequences
- Edge Cases: Some components span levels (addressed in guidelines)
- Learning Curve: Teams must understand 4-level model
- Migration Work: Existing components need reclassification
Risk Mitigation
| Risk | Mitigation |
|---|---|
| Edge case components | Document explicit guidelines; when unclear, go higher level |
| Team confusion | Training documentation; decision tree in standards |
| Migration friction | Gradual adoption; legacy components grandfathered |
Implementation Details
Component Inventory
Atoms (13):
| Component | Purpose |
|---|---|
| Button | Primary interaction |
| Input | Text entry |
| Label | Form field label |
| Badge | Count/status indicator |
| Avatar | User profile image |
| Icon | SVG icon |
| Dot | Status indicator |
| ProgressBar | Progress visualization |
| Checkbox | Multi-select |
| Radio | Single-select |
| Toggle | On/off switch |
| Spinner | Loading indicator |
| Divider | Content separator |
Molecules (11):
| Component | Composition |
|---|---|
| FormField | Label + Input + Error |
| SearchInput | Input + Icon |
| StatusIndicator | Dot + Label |
| ProgressIndicator | ProgressBar + Label + Percentage |
| AvatarGroup | Avatar[] + Overflow |
| ButtonGroup | Button[] |
| TagList | Badge[] + Add/Remove |
| Breadcrumb | Link[] + Separator |
| Pagination | Button[] + Input |
| EmptyState | Icon + Title + Description + Action |
| Toast | Icon + Message + Action |
Organisms (9):
| Component | Purpose |
|---|---|
| Header | Navigation bar |
| Card | Content container |
| Modal | Dialog overlay |
| DataTable | Data display |
| Form | Complex form layout |
| KanbanColumn | Board column |
| Sidebar | Side navigation |
| UserMenu | User actions menu |
| FilterPanel | Search/filter controls |
Templates (6):
| Template | Use Case |
|---|---|
| DashboardGrid | Main dashboard |
| DetailView | Entity detail page |
| KanbanBoard | Task management |
| ListDetail | Master-detail layout |
| FormPage | Data entry page |
| EmptyPage | No data/onboarding |
Classification Decision Tree
Is it a single, indivisible element?
├── YES → ATOM
│ Examples: Button, Input, Icon
└── NO → Does it combine 2-3 atoms for one purpose?
├── YES → MOLECULE
│ Examples: FormField, StatusIndicator
└── NO → Is it a distinct UI section?
├── YES → ORGANISM
│ Examples: Card, Modal, Header
└── NO → TEMPLATE
Examples: DashboardGrid, FormPage
Composition Rules
- Atoms can only use design tokens (no other components)
- Molecules compose atoms only (never other molecules)
- Organisms can compose atoms, molecules, or organisms
- Templates arrange organisms (no business logic)
Affected Components
| Component | Change Type | Impact |
|---|---|---|
packages/ui/atoms/ | Add | 13 atom components |
packages/ui/molecules/ | Add | 11 molecule components |
packages/ui/organisms/ | Add | 9 organism components |
packages/ui/templates/ | Add | 6 template components |
agents/moe-ui-component-library-curator.md | Add | Component selection agent |
Validation and Compliance
Success Criteria
- All 39 components implemented
- Each component classified at correct level
- Composition rules enforced in code review
- Storybook documentation complete
- TypeScript types for all components
- 80%+ test coverage
Testing Requirements
- Unit tests for each component
- Visual regression tests (Chromatic/Percy)
- Accessibility audit (axe-core)
- Composition tests (molecules use atoms only, etc.)
Links
Internal Documentation
External References
Code Locations
packages/ui/atoms/- Atom componentspackages/ui/molecules/- Molecule componentspackages/ui/organisms/- Organism componentspackages/ui/templates/- Template components
Changelog
| Version | Date | Author | Changes |
|---|---|---|---|
| 1.0.0 | 2026-01-19 | CODITECT | Initial version |
Compliance: CODITECT-STANDARD-ADR v1.0.0