Build new UIs from scratch or refactor existing UIs using Brad Frost's Atomic Design methodology. Use this skill whenever the user mentions atomic design, design systems, component hierarchies, UI component architecture, or asks to organize/restructure/refactor UI components into a systematic hierarchy. Also trigger when the user wants to create a component library, establish a pattern library, break a monolithic UI into reusable parts, or audit an existing interface for consistency. Works with any language or framework — React, Vue, Angular, Svelte, Flutter, SwiftUI, Jetpack Compose, vanilla HTML/CSS, or any component-based UI system.
Apply Brad Frost's Atomic Design methodology to build or refactor user interfaces as hierarchical, composable component systems. This skill works in two modes — Greenfield (building new UIs from scratch) and Refactor (restructuring existing UIs to conform to atomic principles). Both modes produce the same outcome: a well-organized, five-level component hierarchy that maximizes reusability, consistency, and scalability.
Atomic Design decomposes every interface into five levels. These are not sequential build steps — they are a way of seeing an interface as both a cohesive whole and a collection of composable parts simultaneously. Think of it as a zoom lens: pages are the wide shot, atoms are the macro close-up, and everything in between shows how parts compose into wholes.
Atoms → smallest meaningful UI elements (a button, an input, a label, an icon). Molecules → small groups of atoms functioning as a single unit (a search field = label + input + button). Organisms → complex sections composed of molecules and atoms (a site header = logo + nav + search). Templates → page-level layouts that arrange organisms with placeholder content (the wireframe). Pages → templates filled with real content, revealing edge cases and validating the system.
Before classifying components, read classification-guide.md for the decision framework
and worked examples that resolve common ambiguities (especially the molecule-vs-organism boundary).
Determine which mode applies based on the user's request and the state of the codebase.
Greenfield mode when any of these are true: the user says "build," "create," or "new"; there is no existing component directory; the project is being initialized from scratch.
Refactor mode when any of these are true: the user says "refactor," "restructure," "reorganize," or "migrate"; there is an existing UI codebase with components that are not organized atomically; the user asks for an "interface inventory" or "component audit."
If ambiguous, ask the user which mode they intend.
Before writing any code, gather the following from the user (ask if not provided):
Design tokens sit beneath atoms as a sub-atomic layer. They are the named constants that atoms
reference for all visual properties. Read design-tokens.md for full guidance.
Create a tokens/foundations file appropriate to the framework. At minimum define: color palette (primary, secondary, neutral, semantic), typography scale (font families, sizes, weights, line heights), spacing scale (consistent increments — e.g., 4px base), border radii, shadows/elevation, and breakpoints. Every atom must reference tokens, never hard-coded values.
Atoms are the irreducible UI elements. They should be stateless, purely presentational, and accept all variation through props/parameters. Each atom must: reference tokens for all visual properties, support all relevant states (default, hover, focus, disabled, error, loading), include accessibility attributes (aria labels, roles, keyboard handling), and export a clean public API.
Common atoms: Button, Input, Label, Icon, Avatar, Badge, Divider, Spinner, Typography (Heading, Text), Image, Link, Checkbox, Radio, Toggle, Tag/Chip, Tooltip (trigger only).
Molecules combine atoms into small, single-purpose functional units. A molecule should do one thing and do it well. It should remain reusable across contexts — if it is only meaningful in one specific organism, reconsider whether it should be a molecule or an internal part of that organism.
Common molecules: SearchField (label + input + button), FormField (label + input + error message), NavItem (icon + label + link), MediaObject (image + text block), Card (image + heading + description), Dropdown (button + option list), Breadcrumb (series of links + separators).
Organisms are the first level with real contextual meaning. They form distinct interface sections. Organisms define their own data contracts — they declare what data they need (via props/interfaces) but do not fetch it themselves. Two varieties exist: heterogeneous organisms combine different molecules (a header with logo, nav, and search) and homogeneous organisms repeat the same molecule (a product grid of identical cards).
Common organisms: Header, Footer, Sidebar, HeroSection, ProductGrid, CommentThread, NavigationBar, PricingTable, FeatureSection, LoginForm, RegistrationForm, DataTable.
Templates are layout skeletons that place organisms into a page structure using placeholder content. They contain zero business logic and zero real data — only layout rules. Templates answer the