Atomic Design Methodology
Systematic component hierarchy based on Brad Frost's Atomic Design: atoms -> molecules -> organisms -> templates -> pages. Applied across all 4 frontend platforms.
When to Apply
Reference these guidelines when:
- Creating new UI components (determine correct atomic level)
- Reviewing component composition (verify import rules)
- Organizing component directories across platforms
- Building or extending a design system / component library
- Deciding where data fetching logic belongs
Rule Categories
| # |
Category |
Prefix |
Priority |
Description |
| 1 |
Atoms |
atom- |
HIGH |
Indivisible primitive components |
| 2 |
Molecules |
molecule- |
HIGH |
Simple compositions of atoms |
| 3 |
Organisms |
organism- |
MEDIUM |
Complex UI sections |
| 4 |
Templates |
template- |
MEDIUM |
Page-level layout skeletons |
| 5 |
Pages |
page- |
MEDIUM |
Templates with real data |
| 6 |
Organization |
org- |
MEDIUM |
Directory structure & naming |
Quick Reference -- All Rules
Atoms (HIGH)
atom-standalone-primitives -- Atoms are indivisible, cannot compose other atomsatom-theming-tokens -- Atoms must consume design tokens, never hardcode values
Molecules (HIGH)
molecule-atom-composition -- Molecules compose only atomsmolecule-single-responsibility -- Each molecule = one cohesive function
Organisms (MEDIUM)
organism-section-boundary -- Organisms = distinct interface sectionsorganism-data-awareness -- Organisms are the lowest data-aware level
Templates (MEDIUM)
template-layout-skeleton -- Templates define layout without real content
Pages (MEDIUM)
page-template-instance -- Pages = templates + real data
Organization (MEDIUM)
org-directory-structure -- Directory trees for all 4 platformsorg-naming-conventions -- Naming conventions per platform
Composition Rules
| Level |
Can Import From |
Data-Aware? |
Example |
| Atoms |
Nothing (standalone) |
No |
Button, Input, Label, Icon |
| Molecules |
Atoms only |
No |
SearchForm, FormField, NavLink |
| Organisms |
Atoms + Molecules |
Yes (props/hooks) |
Header, ProductGrid, Sidebar |
| Templates |
Atoms + Molecules + Organisms |
Layout only |
DashboardLayout, AuthLayout |
| Pages |
Everything |
Full data |
Articles::Index, DashboardPage |
Deep guides (read on demand, do not preload)
Every rule id listed above maps to a self-contained file at rules/<rule-id>.md, each with its
own bad/good code pair for all 4 platforms.
Read only the rule file matching your task — not the set:
rules/<rule-id>.md
Owned elsewhere
This skill owns the hierarchy — which level a component belongs at, and what may compose what.
It does not own the tokens those components style with:
std-design-system is scoped to the same files you will be editing (**/components/ui/**,
**/app/components/**/*.rb, **/styles/**) and owns the token rules.
rules/atom-theming-tokens.md is the hierarchy-side rule; the registry of names that actually
exist is @skills/theming/references/platform-integration.md. A class naming an unregistered
token compiles to no CSS at all — silently — so "uses a token" and "uses a registered token"
are different claims, and only the second one renders.
Loading one ~60-line rule beats skimming the whole directory. Do not preload it.
The rules answer "how do I write this level correctly?". These references answer the questions that
come before and after that — read one only when the question is yours:
| Reference |
Read it when |
references/choosing-the-atomic-level.md |
You don't yet know which level a component is. Decision tree, classification questions, data/state boundaries, the standard atom and molecule catalogs, and whether a level changes when you port across platforms. |
references/diagnosing-misplaced-components.md |
The hierarchy exists but feels wrong — an import goes the wrong way, a component won't reuse, an atom has too many props. Symptom → diagnosis → fix. |
references/nextjs-server-client-boundary.md |
Next.js only. Deciding "use client" placement, whether an organism should await or use a hook, or layout.tsx vs an Atomic Design template. Skip on Vite, Phlex, and React Native. |
1---2name: atomic-design3description: |4 Atomic Design methodology for component hierarchy across Phlex (Rails),5 ReactJS Vite SPA, Next.js App Router, and React Native. Covers atoms,6 molecules, organisms, templates, and pages with composition rules.7 Triggers on "atomic design", "component hierarchy", "atom component",8 "molecule component", "organism component", "design system structure",9 or "component organization".10model: sonnet11---1213# Atomic Design Methodology1415Systematic component hierarchy based on Brad Frost's Atomic Design: atoms -> molecules -> organisms -> templates -> pages. Applied across all 4 frontend platforms.1617## When to Apply1819Reference these guidelines when:20- Creating new UI components (determine correct atomic level)21- Reviewing component composition (verify import rules)22- Organizing component directories across platforms23- Building or extending a design system / component library24- Deciding where data fetching logic belongs2526## Rule Categories2728| # | Category | Prefix | Priority | Description |29|---|----------|--------|----------|-------------|30| 1 | Atoms | `atom-` | HIGH | Indivisible primitive components |31| 2 | Molecules | `molecule-` | HIGH | Simple compositions of atoms |32| 3 | Organisms | `organism-` | MEDIUM | Complex UI sections |33| 4 | Templates | `template-` | MEDIUM | Page-level layout skeletons |34| 5 | Pages | `page-` | MEDIUM | Templates with real data |35| 6 | Organization | `org-` | MEDIUM | Directory structure & naming |3637## Quick Reference -- All Rules3839### Atoms (HIGH)40- `atom-standalone-primitives` -- Atoms are indivisible, cannot compose other atoms41- `atom-theming-tokens` -- Atoms must consume design tokens, never hardcode values4243### Molecules (HIGH)44- `molecule-atom-composition` -- Molecules compose only atoms45- `molecule-single-responsibility` -- Each molecule = one cohesive function4647### Organisms (MEDIUM)48- `organism-section-boundary` -- Organisms = distinct interface sections49- `organism-data-awareness` -- Organisms are the lowest data-aware level5051### Templates (MEDIUM)52- `template-layout-skeleton` -- Templates define layout without real content5354### Pages (MEDIUM)55- `page-template-instance` -- Pages = templates + real data5657### Organization (MEDIUM)58- `org-directory-structure` -- Directory trees for all 4 platforms59- `org-naming-conventions` -- Naming conventions per platform6061## Composition Rules6263| Level | Can Import From | Data-Aware? | Example |64|-------|----------------|-------------|---------|65| Atoms | Nothing (standalone) | No | Button, Input, Label, Icon |66| Molecules | Atoms only | No | SearchForm, FormField, NavLink |67| Organisms | Atoms + Molecules | Yes (props/hooks) | Header, ProductGrid, Sidebar |68| Templates | Atoms + Molecules + Organisms | Layout only | DashboardLayout, AuthLayout |69| Pages | Everything | Full data | Articles::Index, DashboardPage |7071## Deep guides (read on demand, do not preload)7273Every rule id listed above maps to a self-contained file at `rules/<rule-id>.md`, each with its74own bad/good code pair for all 4 platforms.7576**Read only the rule file matching your task** — not the set:7778```79rules/<rule-id>.md80```8182### Owned elsewhere8384This skill owns the **hierarchy** — which level a component belongs at, and what may compose what.85It does not own the tokens those components style with:8687- **`std-design-system`** is scoped to the same files you will be editing (`**/components/ui/**`,88 `**/app/components/**/*.rb`, `**/styles/**`) and owns the token rules.89 `rules/atom-theming-tokens.md` is the hierarchy-side rule; the **registry of names that actually90 exist** is `@skills/theming/references/platform-integration.md`. A class naming an unregistered91 token compiles to no CSS at all — silently — so "uses a token" and "uses a *registered* token"92 are different claims, and only the second one renders.9394Loading one ~60-line rule beats skimming the whole directory. Do not preload it.9596The rules answer "how do I write this level correctly?". These references answer the questions that97come before and after that — read one only when the question is yours:9899| Reference | Read it when |100|-----------|--------------|101| `references/choosing-the-atomic-level.md` | You don't yet know which level a component is. Decision tree, classification questions, data/state boundaries, the standard atom and molecule catalogs, and whether a level changes when you port across platforms. |102| `references/diagnosing-misplaced-components.md` | The hierarchy exists but feels wrong — an import goes the wrong way, a component won't reuse, an atom has too many props. Symptom → diagnosis → fix. |103| `references/nextjs-server-client-boundary.md` | **Next.js only.** Deciding `"use client"` placement, whether an organism should `await` or use a hook, or `layout.tsx` vs an Atomic Design template. Skip on Vite, Phlex, and React Native. |
Kaakati