| name | atomic-design |
| description | Guide for creating, componentizing, and refactoring UI components following Atomic Design. Use this skill whenever the user is actively building a new component, breaking down a UI into components, or refactoring an existing component. Trigger when the user shares a design/screenshot/code to componentize, when they are writing a new component from scratch, when they are splitting a large component into smaller ones, or when they are refactoring a component's structure or responsibilities. Do NOT trigger for general questions about Atomic Design theory — only when there is a concrete component being created, split, or refactored. |
Atomic Design — Componentization Guide
This skill teaches how to classify and build decoupled components following Atomic Design. The scope is deliberate: classify correctly, build correctly. Business logic, routing, and state management live elsewhere in the app architecture — this skill does not dictate those.
Mandatory vs Optional Levels
| Level | Status | Notes |
|---|
| ⚛️ Atom | Mandatory | Always applies in every project |
| 🧪 Molecule | Mandatory | Always applies in every project |
| 🦠 Organism | Mandatory | Always applies in every project |
| 🧩 Template | Optional | Skip if the framework provides layout conventions (e.g. Next.js layout.tsx) |
| 📄 Page | Optional | Skip if the framework owns routing and page structure (e.g. Next.js app/ or pages/) |
The mandatory core is always Atom → Molecule → Organism. Templates and Pages are useful in framework-agnostic projects or when the app has no built-in layout/routing conventions. When the framework already handles those concerns — like Next.js does — imposing them as extra component folders creates unnecessary duplication. In those cases, skip them and let the framework own that layer.
The Five Levels
⚛️ Atom
The smallest indivisible unit. Renders one thing. No business logic. No API calls. No knowledge of the app it lives in.
Characteristics:
- Cannot be broken down further without losing its meaning
- Purely presentational — controlled entirely via props
- Has its own visual states (disabled, hover, error, sizes, variants)
- Zero side effects unrelated to its own UI behavior
- Unaware of context, feature, or domain
Examples: Button, Input, Label, Icon, Badge, Avatar, Spinner, Checkbox, Tag, Divider, Heading, Text, Tooltip
Rule: If you can drop it into any other project and it still makes sense — it's an Atom.
🧪 Molecule
A functional composition of atoms (and sometimes HTML elements). Does one thing well, but that thing requires coordination between atoms.
Characteristics:
- Composed of 2+ atoms working together as a unit
- May hold internal UI state (open/closed, focused, etc.) — but NOT app state
- Passes data down and events up via props
- No API calls
- No access to global stores or app-level context
- Single responsibility: one clear function
Examples: SearchBar (Input + Button + Icon), FormField (Label + Input + ErrorMessage), Dropdown (Button + Menu + Option), CardHeader (Avatar + Heading + Badge), PaginationControls, DatePicker
Rule: If it combines atoms to accomplish one specific UI task — it's a Molecule.
🦠 Organism
A distinct, self-contained section of the UI. Product-specific. May coordinate multiple molecules and atoms into a meaningful feature area.
Characteristics:
- Combines molecules (and atoms) into a complete interface section
- May hold local feature state and trigger data fetching (via hooks/services, not inline)
- Can be connected to app state or context — but should isolate this via props/hooks
- Product-specific: usually tied to a domain (e.g.,
ProductCard, LoginForm, UserMenu)
- Reusable across pages/templates of the same product, but not universally portable
- Should remain composable: avoid hardcoding layout positions or external margins
Examples: Header, Footer, ProductCard, LoginForm, NavigationMenu, DataTable, UserProfilePanel, HeroSection, CommentThread
Rule: If it represents a full, meaningful section of the UI with its own identity — it's an Organism.
🧩 Template (optional — depends on project)
The skeleton of a page. Defines layout and slot positions for organisms. Contains no real content — uses placeholders.
Skip this level if the framework provides its own layout primitive (e.g. Next.js layout.tsx in App Router, _app.tsx in Pages Router). In those cases the framework already owns the layout layer — creating a /templates folder would duplicate that responsibility.
Characteristics:
- Defines the spatial structure of a page (grid, columns, zones)
- Slots in organisms without knowing their content
- No styles beyond layout (no colors, no business logic, no data)
- Acts like a wireframe — validates that the layout holds up before content arrives
- Rarely contains conditional logic
Examples: DashboardLayout, TwoColumnLayout, ArticleLayout, AuthLayout, MarketingPageLayout
Rule: If it only arranges organisms into a layout and has no real content — it's a Template.
📄 Page (optional — depends on project)
A template instance populated with real content, connected to the app. This is where the system integrates with routing, data, and state.
Skip this level if the framework owns the routing and page file structure (e.g. Next.js app/page.tsx, Remix routes/). The framework's route files already are the Pages — there's no need to create a parallel /pages component folder.
Characteristics:
- Implements a Template with real data
- Connected to routing
- Passes real content/data down to organisms and molecules
- The integration point between the design system and the application logic
- May orchestrate multiple data sources
Examples: HomePage, ProductDetailPage, DashboardPage, LoginPage, UserProfilePage
Rule: If it's a route + a template filled with real content — it's a Page.
Classification Decision Tree
Is it a single HTML element / design token / icon with visual states only?
└─ YES → Atom ✅ mandatory
Does it combine 2+ atoms into one functional UI unit? No API calls, no app state?
└─ YES → Molecule ✅ mandatory
Does it represent a complete, identifiable section of the UI? May use app state/hooks?
└─ YES → Organism ✅ mandatory
Does it only define the spatial layout / grid structure? (and framework doesn't own this)
└─ YES → Template ⚙️ optional
Is it a specific route with real data? (and framework doesn't own routing)
└─ YES → Page ⚙️ optional
When in doubt: start from the bottom. Check if it's an Atom first. If it violates Atom rules, check Molecule. Work upward until you find the lowest level that fits.
Rules for Decoupled Components
These rules apply regardless of the level:
1. Props down, events up
Components receive data through props. They communicate back to parents through callback props. They don't reach up into the tree.
2. No hardcoded margins or positions on the outer wrapper
Atoms and molecules must not set their own margin, position, top, left. Position is the parent's responsibility. Use internal padding only.
3. No business logic below Organism
Atoms and molecules must not know about users, products, carts, or any domain entity. They deal with UI state only (open, disabled, focused).
4. Single Responsibility Principle
Each component does one thing. If you struggle to name it with one clear noun or noun-phrase, it probably does too much. Split it.
5. Avoid prop drilling beyond 2 levels
If data needs to travel 3+ levels down, move it to context/state at the Organism or Page level. Don't pass business data through molecules.
6. No direct API calls in atoms or molecules
Data fetching belongs at the Organism or Page level. Atoms and molecules receive data as props, period.
Folder Structure
Respect the existing app structure. If the project already has a defined folder convention, place components in the correct category within that convention.
Default structure (if not already defined):
src/
├── components/
│ ├── atoms/
│ │ └── Button/
│ │ ├── Button.tsx
│ │ └── Button.module.css (if applicable)
│ ├── molecules/
│ ├── organisms/
│ └── templates/ ← omit if framework owns layouts (Next.js, Remix)
├── pages/ ← omit if framework owns routing (Next.js app/, Remix routes/)
└── ...
Key rule: Always check the existing project structure first. If the project uses features/, modules/, or shared/ folders, the atomic hierarchy may live inside those. Don't impose a structure that conflicts with what's already there.
For deeper guidance on folder organization, scope conventions, and monorepo patterns, see references/folder-patterns.md.
Common Mistakes to Avoid
| Mistake | Fix |
|---|
| Atom that makes an API call | Move data fetching to Organism or Page |
| Molecule with business domain logic | Strip it out; pass results as props |
| Organism with hardcoded pixel margins | Use layout wrapper or let the Template position it |
| Page mixing routing logic with render logic | Separate data orchestration from JSX |
| "God component" doing everything | Split by responsibility — find the seam |
| Different teams disagreeing on Molecule vs Organism | Default to the lower level; upgrade when complexity justifies it |
