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:

1. 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).

2. 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.

3. 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.

4. 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.

1. Pass all data through props or equivalent
2. Emit events for user actions -- do not handle side effects
3. 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.

1. Define tokens as the first step of any new design system
2. Every color, spacing value, and font size in a component must come from a token
3. 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.

1. Pass children or slots to compose layout
2. Keep the component tree flat -- prefer siblings over deep nesting
3. 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:

• Every UI element traces to an atom (no raw markup in organisms/templates)
• Design tokens exist and components reference them (no hard-coded values)
• Each component has a single responsibility appropriate to its level
• Components are presentational (data passed in, events emitted out)
• The hierarchy is documented or self-evident from directory structure

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