Atomic Design
Value: Simplicity and communication. Building UI from small, named,
composable pieces makes the interface understandable to everyone on the team
and prevents the complexity that comes from monolithic components.
Purpose
Teaches how to organize UI components into a hierarchy of increasing complexity:
atoms, molecules, organisms, and templates. Each level has clear responsibilities
and composition rules. The outcome is a component system where every piece is
reusable, testable in isolation, and named in a shared vocabulary.
Practices
Build Bottom-Up Through Four Levels
Start with the smallest reusable elements and compose upward. Never skip a level.
The four levels:
Atoms: Indivisible UI elements. A button, an input, a label, an icon.
One visual element, one responsibility. Atoms reference design tokens for
all visual properties (color, spacing, typography).
Molecules: Small groups of atoms functioning as a unit. A form field
(label + input + error message). A search bar (input + button + icon).
One interaction pattern per molecule.
Organisms: Complex components composed of molecules and atoms that form
a distinct section of the interface. A navigation header, a complete form,
a data table. One feature area per organism.
Templates: Page-level layouts that arrange organisms into a complete
view. A dashboard template, a list-detail template. Templates define
structure and content slots, not specific data.
Example:
Atom: Button, Input, Label, ErrorMessage
Molecule: FormField (Label + Input + ErrorMessage)
Organism: LoginForm (FormField + FormField + Button)
Template: AuthPage (Header + LoginForm + Footer)
Do:
- Start with atoms when building new UI
- Name components by what they ARE, not what data they show
- Keep atoms under 50 lines, molecules under 100
Do not:
- Build organisms directly from raw markup -- extract atoms first
- Create a molecule that does not compose atoms from your system
- Skip to templates before organisms exist
Keep Components Presentational
Components render UI. They receive data as props. They do not fetch data,
manage business logic, or hold application state.
- Pass all data through props or equivalent
- Emit events for user actions -- do not handle side effects
- Separate data containers from presentational components
Example:
Presentational (good):
UserCard({ name, email, avatar }) -> renders UI
Container (separate):
UserCardContainer() -> fetches data, passes to UserCard
Do not:
- Put API calls inside atoms, molecules, or organisms
- Couple a component to a specific data source
- Mix rendering logic with business logic in the same component
Use Design Tokens for All Visual Properties
Extract every design decision (colors, spacing, typography, shadows, radii)
into named tokens. Components reference tokens, never raw values.
- Define tokens as the first step of any new design system
- Every color, spacing value, and font size in a component must come from a token
- Changing a token updates every component that references it
Example:
/* Tokens */
--color-primary: #0066cc;
--spacing-sm: 8px;
--spacing-md: 16px;
/* Component uses tokens, not values */
.button { background: var(--color-primary); padding: var(--spacing-sm); }
Do not:
- Hard-code
#0066cc or 8px in any component
- Create one-off token names for single components
- Define tokens that are never used (tokens should earn their place)
Compose, Do Not Inherit
Build complex components by nesting simpler ones. Do not extend base components
through class inheritance or deep prop-forwarding chains.
- Pass children or slots to compose layout
- Keep the component tree flat -- prefer siblings over deep nesting
- When you need a variant, compose a new molecule from atoms rather than
adding flags to an existing molecule
Do:
IconButton = Icon + Button (composition)
Card > CardHeader + CardBody (slots)
Do not:
FancyButton extends Button (inheritance)
- A single Button component with 15 variant props
Enforcement Note
Advisory in all modes. Component hierarchy and token discipline are
self-enforced.
Hard constraints:
- Token-only references (no raw values in components):
[RP]
Constraints
- "Never skip a level": An atom that's actually a molecule (it composes
multiple visual elements) is skipping a level even if you name it "atom."
The classification is based on what the component IS, not what directory
it's in. If your "atom" has 3 internal elements with layout logic, it's
a molecule.
- "No raw values": Defining a token for every unique value and then
never reusing those tokens defeats the purpose. Tokens exist for reuse
and consistency. If a token is used exactly once, ask: should this value
be shared with other components? If yes, the token is correct. If no,
the value should probably come from a more general token (e.g., use
spacing-md not card-header-padding-top).
- Presentational boundary: Presentational means: data in via props,
events out via callbacks. Filtering data for display IS presentational
(it's a view concern). Fetching data, mutating state, or calling APIs is
NOT presentational. The test: could this component render identically in
a Storybook story with mock props? If it needs a running backend, it's
not presentational.
Verification
After completing work guided by this skill, verify:
If any criterion is not met, revisit the relevant practice before proceeding.
Dependencies
This skill works standalone. For enhanced workflows, it integrates with:
- design-system: The design system specification provides the token
definitions, component catalog, and hierarchy that this skill implements
in code.
- domain-modeling: Read models from the domain define what data components
receive as props.
- tdd: Test components in isolation at each level -- atom tests,
molecule tests, organism tests.
- event-modeling: Wireframes from event modeling sessions identify which
components are needed.
Missing a dependency? Install with:
npx skills add jwilger/agent-skills --skill tdd
1---2name: atomic-design3description: >-4 Brad Frost's Atomic Design methodology for UI component hierarchies: atoms5 (indivisible elements), molecules (small groups of atoms), organisms6 (complex sections of molecules), and templates (page layouts). Enforces7 bottom-up composition (never skip levels), presentational components (data8 via props, events via callbacks, no data fetching), design tokens for all9 visual properties, and composition over inheritance. Use when building user10 interfaces, creating component libraries, organizing frontend code,11 designing form systems, or structuring any UI. Triggers on: "build a12 component", "component hierarchy", "design tokens", "presentational13 components", "composition over inheritance", "React/Vue/SwiftUI14 components", "atomic design". Applies to any UI framework.15license: CC0-1.016compatibility: Designed for any coding agent (Claude Code, Codex, Cursor, OpenCode, etc.)17metadata:18 source: https://skillmd.com/skills/jwilger/atomic-design19 author: jwilger20 version: "1.2.1"21 requires: []22 context: [source-files]23 phase: build24 standalone: true25---2627# Atomic Design2829**Value:** Simplicity and communication. Building UI from small, named,30composable pieces makes the interface understandable to everyone on the team31and prevents the complexity that comes from monolithic components.3233## Purpose3435Teaches how to organize UI components into a hierarchy of increasing complexity:36atoms, molecules, organisms, and templates. Each level has clear responsibilities37and composition rules. The outcome is a component system where every piece is38reusable, testable in isolation, and named in a shared vocabulary.3940## Practices4142### Build Bottom-Up Through Four Levels4344Start with the smallest reusable elements and compose upward. Never skip a level.4546**The four levels:**47481. **Atoms:** Indivisible UI elements. A button, an input, a label, an icon.49 One visual element, one responsibility. Atoms reference design tokens for50 all visual properties (color, spacing, typography).51522. **Molecules:** Small groups of atoms functioning as a unit. A form field53 (label + input + error message). A search bar (input + button + icon).54 One interaction pattern per molecule.55563. **Organisms:** Complex components composed of molecules and atoms that form57 a distinct section of the interface. A navigation header, a complete form,58 a data table. One feature area per organism.59604. **Templates:** Page-level layouts that arrange organisms into a complete61 view. A dashboard template, a list-detail template. Templates define62 structure and content slots, not specific data.6364**Example:**65```66Atom: Button, Input, Label, ErrorMessage67Molecule: FormField (Label + Input + ErrorMessage)68Organism: LoginForm (FormField + FormField + Button)69Template: AuthPage (Header + LoginForm + Footer)70```7172**Do:**73- Start with atoms when building new UI74- Name components by what they ARE, not what data they show75- Keep atoms under 50 lines, molecules under 1007677**Do not:**78- Build organisms directly from raw markup -- extract atoms first79- Create a molecule that does not compose atoms from your system80- Skip to templates before organisms exist8182### Keep Components Presentational8384Components render UI. They receive data as props. They do not fetch data,85manage business logic, or hold application state.86871. Pass all data through props or equivalent882. Emit events for user actions -- do not handle side effects893. Separate data containers from presentational components9091**Example:**92```93Presentational (good):94 UserCard({ name, email, avatar }) -> renders UI9596Container (separate):97 UserCardContainer() -> fetches data, passes to UserCard98```99100**Do not:**101- Put API calls inside atoms, molecules, or organisms102- Couple a component to a specific data source103- Mix rendering logic with business logic in the same component104105### Use Design Tokens for All Visual Properties106107Extract every design decision (colors, spacing, typography, shadows, radii)108into named tokens. Components reference tokens, never raw values.1091101. Define tokens as the first step of any new design system1112. Every color, spacing value, and font size in a component must come from a token1123. Changing a token updates every component that references it113114**Example:**115```css116/* Tokens */117--color-primary: #0066cc;118--spacing-sm: 8px;119--spacing-md: 16px;120121/* Component uses tokens, not values */122.button { background: var(--color-primary); padding: var(--spacing-sm); }123```124125**Do not:**126- Hard-code `#0066cc` or `8px` in any component127- Create one-off token names for single components128- Define tokens that are never used (tokens should earn their place)129130### Compose, Do Not Inherit131132Build complex components by nesting simpler ones. Do not extend base components133through class inheritance or deep prop-forwarding chains.1341351. Pass children or slots to compose layout1362. Keep the component tree flat -- prefer siblings over deep nesting1373. When you need a variant, compose a new molecule from atoms rather than138 adding flags to an existing molecule139140**Do:**141- `IconButton = Icon + Button` (composition)142- `Card > CardHeader + CardBody` (slots)143144**Do not:**145- `FancyButton extends Button` (inheritance)146- A single Button component with 15 variant props147148## Enforcement Note149150Advisory in all modes. Component hierarchy and token discipline are151self-enforced.152153**Hard constraints:**154- Token-only references (no raw values in components): `[RP]`155156## Constraints157158- **"Never skip a level"**: An atom that's actually a molecule (it composes159 multiple visual elements) is skipping a level even if you name it "atom."160 The classification is based on what the component IS, not what directory161 it's in. If your "atom" has 3 internal elements with layout logic, it's162 a molecule.163- **"No raw values"**: Defining a token for every unique value and then164 never reusing those tokens defeats the purpose. Tokens exist for reuse165 and consistency. If a token is used exactly once, ask: should this value166 be shared with other components? If yes, the token is correct. If no,167 the value should probably come from a more general token (e.g., use168 `spacing-md` not `card-header-padding-top`).169- **Presentational boundary**: Presentational means: data in via props,170 events out via callbacks. Filtering data for display IS presentational171 (it's a view concern). Fetching data, mutating state, or calling APIs is172 NOT presentational. The test: could this component render identically in173 a Storybook story with mock props? If it needs a running backend, it's174 not presentational.175176## Verification177178After completing work guided by this skill, verify:179180- [ ] Every UI element traces to an atom (no raw markup in organisms/templates)181- [ ] Design tokens exist and components reference them (no hard-coded values)182- [ ] Each component has a single responsibility appropriate to its level183- [ ] Components are presentational (data passed in, events emitted out)184- [ ] The hierarchy is documented or self-evident from directory structure185186If any criterion is not met, revisit the relevant practice before proceeding.187188## Dependencies189190This skill works standalone. For enhanced workflows, it integrates with:191192- **design-system:** The design system specification provides the token193 definitions, component catalog, and hierarchy that this skill implements194 in code.195- **domain-modeling:** Read models from the domain define what data components196 receive as props.197- **tdd:** Test components in isolation at each level -- atom tests,198 molecule tests, organism tests.199- **event-modeling:** Wireframes from event modeling sessions identify which200 components are needed.201202Missing a dependency? Install with:203```204npx skills add jwilger/agent-skills --skill tdd205```