Atomic Design

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

1. Premature abstraction — wait for 3+ use cases before extracting
2. Prop explosion — 15+ props → decompose into smaller pieces
3. CSS override chains — 5+ overrides → create a variant
4. Token drift — hardcoded values that should be tokens
5. Missing states — every interactive component needs: default, hover, focus, active, disabled, loading, error

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sarveshsea
• Source: sarveshsea/design-skills
• License: MIT
• Homepage: https://www.memoire.cv/notes/community/

Install and usage instructions live in the source repository linked above.