In a component library built with atomic design, why can mirroring the five levels as top-level folders cause problems, and what do teams do instead?
answer
- vocabulary, not directory plan
- components change level as they grow
- people search by purpose
- moves become path changes
- keep the words, not the folders
basics
~20 sLevel boundaries are fuzzy and components drift between them, so level folders force classification debates, file moves that can break consumers, and poor discovery. Teams usually organise by component or purpose and keep the atomic words for design conversation.
solid answer
~50 sAtomic design's levels are a mental model, not a folder rule. When a library mirrors them as `atoms/`, `molecules/` and `organisms/` folders, three problems appear. Components change level as they grow — a scan field gains a quantity stepper and "becomes" an organism — so reclassifying means moving files, and if consumers import by path, a move becomes a breaking change for them. Contributors must win a classification argument before they can add anything. And engineers look for a component by purpose, not by level: a newcomer cannot guess whether the stepper lives under molecules. Templates and pages rarely belong in a shared library at all. So most teams use one folder per component, or purpose groups such as inputs, navigation and feedback, keep the public entry point independent of the internal layout, and keep the atomic words for design reviews and documentation.
go deeper
Recall that the atomic levels are a way of thinking about scale, and that a library does not have to use them as folder names.
Explain the concrete costs of level folders: drift as components grow, moves that change import paths, classification debates and weak discovery by purpose.
Show how you would structure a shared library for many consumers: a stable public entry point, a findable internal layout, and where atomic words still earn their place.
Consider how library structure shapes contribution and ownership across teams, and when the vocabulary should live only in documentation.
## Levels are a vocabulary, not a directory plan Brad Frost presents **atomic design** as a mental model: a shared way of talking about the scale of interface parts. He also says the method is not tied to any code architecture. Many teams nonetheless make the literal move of creating top-level folders named after the levels in their component library. It feels principled, and it is usually where trouble starts. ## What goes wrong when folders mirror the levels Consider the component library behind a warehouse scanner app. - **Components drift between levels.** A scan input starts as a molecule: label, field, scan button. Later it gains a quantity stepper and a validation message and now forms a distinct section of the screen. By the method's own terms it is an organism. Keeping it in the wrong folder erodes the scheme; moving it creates churn. - **Moves can break consumers.** If product teams import components by their file path, moving the scan field from one folder to another changes every import site. What was a vocabulary decision becomes a breaking change for someone else's app. - **Contribution stalls on classification.** Before adding a component, the contributor must decide its level, and reviewers must agree. The time goes into taxonomy rather than into the component. - **Discovery suffers.** An engineer who needs a quantity control searches by purpose. Whether it sits under molecules or organisms is a question they cannot answer without already knowing the library. - **The top levels do not fit.** Templates and pages are rarely shared library code; they tend to be product screens. Folders for them stay empty or fill with product-specific screens that do not belong in a shared library. - **Organisms are often product-specific.** A pick-list section may only make sense in one app. A shared organisms folder pulls such parts into the library by default. ## What teams do instead | Structure | How it works | Good for | Cost | |---|---|---|---| | **One folder per component, flat** | Each component in its own folder; any level recorded as a documentation tag | Most shared libraries | Needs good search and docs navigation | | **Purpose groups** | Inputs, navigation, feedback, data display, layout | Discovery by what a component does | Some components fit two groups | | **Ownership tiers** | Foundations, core shared components, product-local parts | Clarity about who maintains what | Needs a promotion path between tiers | | **Level folders behind a stable entry point** | Keep atomic folders internally; consumers import only from one public surface | Teams attached to the vocabulary | Internal moves still cost reviews | ## How to choose 1. **Start from how consumers find things.** If people look up components by purpose or name, organise for that. 2. **Separate the public surface from the internal layout.** Whatever the folders, consumers should import from a stable entry point, so reorganising is an internal change. 3. **Keep the atomic words where they help.** Design reviews, documentation pages and teaching benefit from a vocabulary of scale even when folders do not use it. 4. **Revisit when debates start.** The moment classification arguments appear in reviews, the folder scheme is costing more than it returns. ## The same issue beyond code The problem is not specific to one platform. A design-editor library whose pages are named after the levels has the same discovery problem, and a native codebase with modules per level has the same drift. The underlying point is identical everywhere: a model for thinking about scale is not automatically a good index for finding things. ## Signals the scheme is failing - reviews spend time on which folder a component belongs in - the same component has moved between folders more than once - engineers ask in support channels where a component lives - product-only screens start appearing in shared folders ## When level folders are fine - A small library owned by one team, where everyone already knows every component. - A teaching or prototype context where the goal is to learn the hierarchy. - A design-editor file used only by its authors for exploration. In those cases the costs above are small. They grow with the number of contributors, consumers and years.
- If you keep level folders, how do you stop reclassification from breaking consumers?Expose a single public entry point and forbid deep imports into folders. Consumers then depend on the component's public name, not its location, so moving the scan field from one level folder to another is an internal change reviewed by the library team, not a change every product team must absorb.
- Do templates and pages belong in a shared component library?Rarely. Templates can be shared when several products genuinely use the same screen skeleton, but pages are template instances with real content and belong to products or to documentation as worked examples. Treating them as library components usually pulls product-specific screens into a shared package.
saying these in an interview costs you the question
- Atomic design requires atoms, molecules and organisms folders in the codebase.
- A component's level is fixed forever once it is first classified.
- Consumers find components by level, so level folders help discovery.
- Every level, including pages, belongs in the shared component library.
- Organising by purpose means abandoning atomic design entirely.