| name | atomic-design |
| description | Atomic Design quick reference — levels, composition rules, tokens, naming |
Atomic Design — Quick Reference
Level Decision Table
| Level | Folder | Composes | Has State | Fetches Data | Real Content |
|---|
| Atom | components/ui/ | Nothing | No | No | No |
| Molecule | components/molecules/ | 2–5 atoms | Maybe | No | No |
| Organism | components/organisms/ | Molecules + atoms | Yes | Yes | No |
| Template | components/templates/ | Organisms | No | No | Placeholder |
| Page | (route file) | Templates | No | Yes | Real |
If you can't decide: IF it composes nothing → atom. IF it composes ≤5 atoms → molecule. IF it manages state or fetches data → organism. IF it's a full layout skeleton → template.
Composition Rules
- Atoms: no
composesSpecs, no imports of other atoms
- Molecules: 2–5 atom imports, no data fetching, may have internal open/closed state
- Organisms: own breakpoints, document composition in spec
- Templates: CSS Grid or Flexbox only, must match Figma page spec
- Pages: handle all data states — loading, empty, error, populated
File Structure
components/
ui/ # atoms (shadcn primitives)
molecules/
organisms/
templates/
Design Tokens
Global tokens (--blue-500, --space-4)
→ Alias tokens (--color-primary, --spacing-component)
→ Component tokens (--button-bg, --card-radius)
Override alias tokens per theme: :root, .dark, .brand-b.
Accessibility by Level
| Level | Required |
|---|
| Atom | ARIA role, keyboard focus, contrast, label |
| Molecule | Focus management, error announcements |
| Organism | Landmark roles, skip links, focus trapping |
| Template | Page title, heading hierarchy, main landmark |
| Page | Full WCAG 2.1 AA |
Naming
| Element | Convention | Example |
|---|
| Components | PascalCase | MetricCard |
| Props | camelCase | isLoading |
| CSS classes | kebab-case | text-muted-foreground |
| Constants | UPPER_SNAKE | MAX_RETRY_COUNT |
| Tokens | path/style | color/primary/500 |
Figma ↔ Code
| Figma | Code |
|---|
| Component | React component |
| Component Set | Variant type union |
| Component Property | React prop |
| Auto Layout | Flexbox / Grid |
| Design Token | CSS Variable → Tailwind class |
| Section | Organism |
Anti-Patterns
- Premature abstraction — wait for 3+ use cases before extracting
- Prop explosion — 15+ props → decompose into smaller pieces
- CSS override chains — 5+ overrides → create a variant
- Token drift — hardcoded values that should be tokens
- Missing states — every interactive component needs: default, hover, focus, active, disabled, loading, error