# Atomic Design > 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. - Skill: `josecortezz25/atomic-design` (Agent Skill) - Install (CLI): `npx skillmds@latest add josecortezz25/atomic-design` - Raw SKILL.md: https://api.skillmd.com/api/skills/josecortezz25/atomic-design/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: josecortezz25 (https://skillmd.com/u/josecortezz25) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/josecortezz25/atomic-design --- # 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 |