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
1---2name: atomic-design3description: Atomic Design quick reference — levels, composition rules, tokens, naming4---56# Atomic Design — Quick Reference78## Level Decision Table910| Level | Folder | Composes | Has State | Fetches Data | Real Content |11|-------|--------|----------|-----------|--------------|-------------|12| Atom | `components/ui/` | Nothing | No | No | No |13| Molecule | `components/molecules/` | 2–5 atoms | Maybe | No | No |14| Organism | `components/organisms/` | Molecules + atoms | Yes | Yes | No |15| Template | `components/templates/` | Organisms | No | No | Placeholder |16| Page | (route file) | Templates | No | Yes | Real |1718**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.1920## Composition Rules2122- Atoms: no `composesSpecs`, no imports of other atoms23- Molecules: 2–5 atom imports, no data fetching, may have internal open/closed state24- Organisms: own breakpoints, document composition in spec25- Templates: CSS Grid or Flexbox only, must match Figma page spec26- Pages: handle all data states — loading, empty, error, populated2728## File Structure2930```31components/32 ui/ # atoms (shadcn primitives)33 molecules/34 organisms/35 templates/36```3738## Design Tokens3940```41Global tokens (--blue-500, --space-4)42 → Alias tokens (--color-primary, --spacing-component)43 → Component tokens (--button-bg, --card-radius)44```4546Override alias tokens per theme: `:root`, `.dark`, `.brand-b`.4748## Accessibility by Level4950| Level | Required |51|-------|---------|52| Atom | ARIA role, keyboard focus, contrast, label |53| Molecule | Focus management, error announcements |54| Organism | Landmark roles, skip links, focus trapping |55| Template | Page title, heading hierarchy, main landmark |56| Page | Full WCAG 2.1 AA |5758## Naming5960| Element | Convention | Example |61|---------|-----------|---------|62| Components | PascalCase | `MetricCard` |63| Props | camelCase | `isLoading` |64| CSS classes | kebab-case | `text-muted-foreground` |65| Constants | UPPER_SNAKE | `MAX_RETRY_COUNT` |66| Tokens | path/style | `color/primary/500` |6768## Figma ↔ Code6970| Figma | Code |71|-------|------|72| Component | React component |73| Component Set | Variant type union |74| Component Property | React prop |75| Auto Layout | Flexbox / Grid |76| Design Token | CSS Variable → Tailwind class |77| Section | Organism |7879## Anti-Patterns80811. **Premature abstraction** — wait for 3+ use cases before extracting822. **Prop explosion** — 15+ props → decompose into smaller pieces833. **CSS override chains** — 5+ overrides → create a variant844. **Token drift** — hardcoded values that should be tokens855. **Missing states** — every interactive component needs: default, hover, focus, active, disabled, loading, error
memi-design