Atomic design in practice: stop sculpting the interface from scratch every time

In a project without a system, each new screen starts from scratch. The designer draws a button — not the same as on the previous screen, similar. A different padding. A little different typeface. In a year, the product has 40 options of the button, where logic should be 4.

Atomic design is a methodology that makes this impossible. Not through agreements, but through structure.

## Five levels and why

### Atoms

Inconsistent elements. You can't take it apart without losing meaning.

Button, Input, Icon, Label, Checkbox, Avatar, Badge are atoms.

The key property is that the atom has no context. Button doesn't know she's on the payment page. It's just Button with options (Primary/Secondary/Ghost) and states (Default/Hover/Active/Disabled/Loading). It's intentional -- the atom works in any context without change.

Consequence: There is one Button master component in the system. Not a “form button” and a “header button” – one button, different options.

### Molecules

Groups of atoms with one specific function.

SearchBar = Input + Icon + Button/Ghost. As a whole, looking. UserCard = Avatar + Text/Name + Text/Role + Badge/Status As a whole, it shows the user. FormField = Label + Input + HelperText / Error. As a whole, a form field with a hint.

The rule is, the molecule does one thing, well. If a molecule tries to do two different things, it's two molecules or an organism.

### Organisms

Complex components of molecules and atoms. The user interacts with the body as a unit - "fills the form", "uses navigation".

Header = Logo + Navigation + SearchBar + Button/CTA + Avatar/User RegistrationForm = several FormField + Select + Checkbox + Button/Primary UserList = Multiple UserCard + Pagination + SearchBar.

The body is the boundary between “component” and “page section”.

### Templates and pages

A template is a framework without real content: where what is worth, what a grid, how organisms relate. A page is a template with real data.

In practice, designers often work directly with pages. It is normal for atoms, molecules and organisms to be built.

## Where methodology breaks down - real situations

### A molecule inside a molecule

The most common violation. ProductCard is placed inside CartRow – both molecules. It's an organism.

The practical consequence is that when you renew an atom (Button), you expect all the molecules that use it, and all the organisms from those molecules, to renew themselves. The update chain only works if the hierarchy is followed. Violation = unpredictable updates.

### Local customization instead of the system version

“You need a little bigger button here,” someone breaks the component. After a month, there are three more buttons with different meanings.

The correct answer is to add the size/xl variant to the master component. Once, the option is available everywhere, updated centrally, does not create hidden debt.

The price of the detouch that is not considered: the detouched component should be searched for when refactoring, it is not updated with the library, it is not in the analytics of the use of components.

### A name that is becoming obsolete

Button/Blue/Large is the wrong name. When a brand changes and the button goes green, the name lies. When sizes are unified, the name loses meaning.

Button/Primary/Default is the correct name. Primary is a functional role (main action). Default is a condition. Neither depends on the specific color.

Rule: A name should not contain a specific color, pixel size, or any characteristic that is managed through tokens or options.

## Atomic system and AI: how to change the industrial

No hierarchy: Create a user card → AI invents new atoms Your Avatar, your typography, new indentations. It's out of the system.

With hierarchy and AGENTS.md:

Create a UserCard molecule using only these atoms:
- atoms/Avatar/Medium - 48x48px, fallback on initials
atoms/Text/Subheading – user name
- atoms/Text/Caption - position
- atoms/Badge/Status - online/offline/away

Auto Layout Horizontal, gap var(-spacing-4).
Default and Compact (Avatar/Small, without Caption)
Hover: background → color/background/surface-hover.
Do not create new atoms, just from the list above.

AI collects from an existing one. The result is consistent by definition.

## Map of hierarchy for the team

One document, one page in Notion:

Atoms:
Button, Input, Icon, Label, Avatar, Badge, Checkbox, Toggle, Divider

Molecules:
SearchBar (Input + Icon + Button)
UserCard (Avatar + Text/Name + Text/Role + Badge/Status)
FormField (Label + Input + HelperText)
NavItem (Icon + Text/Body + Badge/Count)
NotificationItem (Avatar + Text/Title + Text/Body + Text/Time)

Organisms:
Header (Logo + NavItems + SearchBar + Button/CTA + Avatar)
UserForm (Multiple FormField + Button/Primary)
UserList (Multiple UserCard + Pagination)
SideNav (Logo + several NavItem)

The new person reads this in five minutes and understands the system. The AI agent receives through AGENTS.md and knows what to collect from what.

Update each new component more than once a quarter.

## Frequent questions about methodology

"We use shadcn/ui - do we need atomic design?" Yes. shadcn gives atoms and basic molecules. But organisms and their connections are your system. Atomic design describes how to organize what you build on top of shadcn.

"How do you name components that don't fit into the hierarchy?" Be honest. If it is between a molecule and an organism, call it an organism. The purity of the hierarchy is more important than the strict conformity of the theory.

"AI doesn't follow the atomic hierarchy" because you didn't explicitly explain. AGENTS.md: New components are built from existing atoms. List of atoms: [Button, Input, Icon, Label, Avatar, Badge]. Not to create new atoms without explicit request.” The clear list works.

## Prompt for double audit

Find duplicate components in the project.

1. Find all Button files in the name in src/components/.
For everyone: padding (top/bottom, left/right), border-radius
font-size, font-weight, background-color in the Default state.

2. Which of them are visually identical or differ by the same meaning?
These are candidates for unification through option or props.

3. For each candidate, offer a new props size/variant/intent
It replaces a single component.

Purpose: Reduce the number of Button components to the minimum required
Explain how each of the others is functionally different.

## How atomic design changes speed on large projects

On a project with 5 screens, the atomic system is overhead. You need to spend time creating it, even though the project is small.

With 50 screens, things are changing. The first 10 screens without the system and with the system are about the same. By the 30th screen, the difference becomes tangible: with the system you take the finished blocks, without the system - again solve the already solved issues.

By the 50th screen, the product looks like it was made by different teams. System-consistent. And the speed with the system is higher: the developer takes the component from the library, rather than writing from scratch.

The threshold is about 15 screens. If the product grows to 15+ screens, the system will pay off. If this is a one-page landing, do not waste time.

## Link to AI Workflow: Why Generation Degrades Without Hierarchy

When AI generates a 5th screen in a row without a clear atomic structure in AGENTS.md, drift begins. The first button was generated in one way, the fifth in a slightly different way. There is no obvious connection between them.

With the atomic hierarchy and AGENTS.md which explicitly lists atoms, drift is excluded. AI always goes back to the same list of atoms. Each molecule is made of the same bricks. Consistency is ensured not by controlling each output, but by limiting the available blocks.

This is a fundamental difference in approach: instead of “check what is generated” – “limit what can be used”.

● Each atom is one master copy, not several similar
Molecules consist only of atoms (not other molecules)
● Organisms may contain molecules.
Functional names: Button/Primary, not Button/Blue
● Name format: [Type]/[Variant]/[State]
The hierarchy map (atoms/molecules/organisms) is relevant
● AGENTS.md: list of atoms, prohibition to create new ones without explicit request
Detached components: zero or task in the backlog