atomic-design
Atomic Design (UI Library Structure)
Organize your UI library — the core-ui package (see project) — with Atomic Design: four folders, atoms → molecules → organisms → templates, where each level composes the ones below it and never the reverse. This keeps the library scannable ("a labeled input is a molecule, so it's in molecules/"), keeps primitives reusable, and gives you one clear answer to where does this component go?
The other half of the discipline is a promotion policy. Not everything belongs in core-ui on day one: the obvious primitives (Button, Input) go straight in, but a component born inside a feature stays there until a second place needs it — only then is it promoted down into core-ui and generalized. That's how you avoid both copy-paste duplication and premature, wrong abstractions.
Pairs with project (the package graph this lives inside — shared UI moves down into core-*), component-architecture (how one component is built internally), and compound-components (organisms are often compounds).
The four levels
| Level | What it is | Composes | Examples (Hogwarts) |
|---|---|---|---|
| Atoms | The smallest indivisible primitives — one job, no app knowledge | Nothing but raw elements / other atoms sparingly | Button, Input, Icon, Text, Avatar, Badge, Spinner |
| Molecules | A small, reusable group of atoms acting as one unit | Atoms | SearchField (Input + Icon), FormField (Label + Input + error), HouseBadge, Tabs |
| Organisms | A distinct, self-contained section of an interface | Molecules + atoms | NavigationSidebar, SpellbookCard, HouseLeaderboard, ProfileMenu |
| Templates | A page-level layout skeleton — arranges organisms into a structure, no real data | Organisms (as slots) | DashboardLayout, DetailLayout, AuthLayout |
The line between molecule and organism is fuzzy and not worth agonizing over — the useful test is "is this a small reusable widget (molecule) or a whole section of the screen (organism)?" Templates are layout only: they define where things sit and take content through slots/children, never fetch or own data.