Атомарный дизайн на практике: перестань лепить интерфейс с нуля каждый раз

В проекте без системы каждый новый экран начинается с нуля. Дизайнер рисует кнопку — не ту же что на прошлом экране, похожую. Чуть другой padding. Чуть другой шрифт. Через год в продукте 40 вариантов кнопки где по логике должно быть 4.

Атомарный дизайн — методология которая делает это невозможным. Не через договорённости, а через структуру.

## Пять уровней и зачем каждый

### Атомы

Несократимые элементы. Нельзя разобрать на части без потери смысла.

Button, Input, Icon, Label, Checkbox, Avatar, Badge — атомы.

Ключевое свойство: атом не знает контекста. Button не знает что она на странице оплаты. Она просто Button с вариантами (Primary/Secondary/Ghost) и состояниями (Default/Hover/Active/Disabled/Loading). Это намеренно — атом работает в любом контексте без изменений.

Следствие: в системе один мастер-компонент Button. Не «кнопка для форм» и «кнопка для хедера» — одна кнопка, разные варианты.

### Молекулы

Группы атомов с одной конкретной функцией.

SearchBar = Input + Icon + Button/Ghost. Как целое — ищет. UserCard = Avatar + Text/Name + Text/Role + Badge/Status. Как целое — показывает пользователя. FormField = Label + Input + HelperText/Error. Как целое — поле формы с подсказкой.

Правило: молекула делает одно — хорошо. Если молекула пытается делать два разных дела — это две молекулы или уже организм.

### Организмы

Сложные компоненты из молекул и атомов. Пользователь взаимодействует с организмом как с единицей — «заполняет форму», «использует навигацию».

Header = Logo + Navigation + SearchBar + Button/CTA + Avatar/User. RegistrationForm = несколько FormField + Select + Checkbox + Button/Primary. UserList = несколько UserCard + Pagination + SearchBar.

Организм — граница между «компонент» и «раздел страницы».

### Шаблоны и страницы

Шаблон — каркас без реального контента: где что стоит, какая сетка, как соотносятся организмы. Страница — шаблон с реальными данными.

На практике дизайнеры часто работают сразу со страницами. Это нормально когда атомы, молекулы и организмы уже выстроены.

## Где методология ломается — реальные ситуации

### Молекула внутри молекулы

Самое частое нарушение. ProductCard помещают внутрь CartRow — обе молекулы. Это уже организм.

Последствие практическое: когда обновляешь атом (Button), ожидаешь что обновятся все молекулы которые его используют, и все организмы из этих молекул. Цепочка обновлений работает только если иерархия соблюдена. Нарушение = непредсказуемые обновления.

### Локальная кастомизация вместо системного варианта

«Здесь нужна кнопка чуть побольше» — кто-то детачит компонент. Через месяц три кнопки «побольше» с разными значениями.

Правильный ответ: добавь вариант size/xl в мастер-компонент. Один раз — и вариант доступен везде, обновляется централизованно, не создаёт скрытый долг.

Цена детача которую не считают: детачнутый компонент нужно искать при рефакторинге, он не обновляется с библиотекой, его нет в аналитике использования компонентов.

### Именование которое устаревает

Button/Blue/Large — неправильное имя. Когда бренд меняется и кнопка становится зелёной — имя лжёт. Когда размеры унифицируются — имя теряет смысл.

Button/Primary/Default — правильное имя. Primary — функциональная роль (главное действие). Default — состояние. Ни то ни другое не зависит от конкретного цвета.

Правило: имя не должно содержать конкретный цвет, размер в пикселях или любую характеристику которая управляется через токены или варианты.

## Атомарная система и AI: как меняется промпт

Без иерархии: «создай карточку пользователя» → AI придумывает новые атомы. Свой Avatar, свою типографику, новые отступы. Всё не из системы.

С иерархией и AGENTS.md:

Создай молекулу UserCard используя только эти атомы:
- atoms/Avatar/Medium — 48×48px, fallback на инициалы
- atoms/Text/Subheading — имя пользователя
- atoms/Text/Caption — должность
- atoms/Badge/Status — online/offline/away

Auto Layout Horizontal, gap var(--spacing-4).
Варианты: Default и Compact (Avatar/Small, без Caption).
Hover: background → color/background/surface-hover.
Не создавать новых атомов — только из списка выше.

AI собирает из существующего. Результат консистентен по определению.

## Карта иерархии для команды

Один документ — одна страница в Notion:

Атомы:
  Button, Input, Icon, Label, Avatar, Badge, Checkbox, Toggle, Divider

Молекулы:
  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)

Организмы:
  Header      (Logo + NavItems + SearchBar + Button/CTA + Avatar)
  UserForm    (несколько FormField + Button/Primary)
  UserList    (несколько UserCard + Pagination)
  SideNav     (Logo + несколько NavItem)

Новый человек читает это за пять минут и понимает систему. AI-агент получает через AGENTS.md и знает что собирать из чего.

Обновлять при добавлении каждого нового компонента — не раз в квартал.

## Частые вопросы о методологии

«Мы используем shadcn/ui — нужен ли атомарный дизайн?» Да. shadcn даёт атомы и базовые молекулы. Но организмы и их связи — это ваша система. Атомарный дизайн описывает как организовать то что вы строите поверх shadcn.

«Как называть компоненты которые не вписываются в иерархию?» Называй честно. Если это нечто между молекулой и организмом — называй организмом. Чистота иерархии важнее чем строгое соответствие теории.

«AI не соблюдает атомарную иерархию.» Потому что ты не объяснил явно. В AGENTS.md: «Новые компоненты строятся из существующих атомов. Список атомов: [Button, Input, Icon, Label, Avatar, Badge]. Не создавать новые атомы без явного запроса». Явный список работает.

## Промпт для аудита дублей

Найди дублирующиеся компоненты в проекте.

1. Найди все файлы с "Button" в имени в src/components/.
   Для каждого: padding (top/bottom, left/right), border-radius,
   font-size, font-weight, background-color в Default-состоянии.

2. Какие из них визуально идентичны или отличаются ОДНИМ значением?
   Это кандидаты на объединение через вариант или пропс.

3. Для каждого кандидата предложи: новый пропс size/variant/intent
   который заменяет отдельный компонент.

Цель: свести количество Button-компонентов к минимально необходимому
и объяснить как каждый из оставшихся отличается функционально.

## Как атомарный дизайн меняет скорость на больших проектах

На проекте с 5 экранами атомарная система — накладные расходы. Нужно потратить время на её создание, при том что проект маленький.

На проекте с 50 экранами — ситуация меняется. Первые 10 экранов без системы и с системой занимают примерно одинаково. К 30-му экрану разница становится ощутимой: с системой ты берёшь готовые блоки, без системы — снова решаешь уже решённые вопросы.

К 50-му экрану без системы продукт выглядит как сделанный разными командами. С системой — консистентно. И скорость с системой выше: разработчик берёт компонент из библиотеки, а не пишет с нуля.

Пороговое значение — около 15 экранов. Если продукт вырастет до 15+ экранов, система окупится. Если это одностраничный лендинг — не тратить время.

## Связь с AI-воркфлоу: почему без иерархии генерация деградирует

Когда AI генерирует 5-й экран подряд без чёткой атомарной структуры в AGENTS.md — начинается дрейф. Первая кнопка была сгенерирована одним способом, пятая — немного другим. Между ними нет явной связи.

С атомарной иерархией и AGENTS.md который явно перечисляет атомы — дрейф исключён. AI всегда возвращается к одному и тому же списку атомов. Каждая молекула строится из тех же кирпичей. Консистентность обеспечивается не через контроль каждого вывода, а через ограничение доступных блоков.

Это принципиальная разница в подходе: вместо «проверяй что сгенерировано» — «ограничь что может быть использовано».

☐ Каждый атом — одна мастер-копия, не несколько похожих
☐ Молекулы состоят только из атомов (не из других молекул)
☐ Организмы могут содержать молекулы
☐ Имена функциональные: Button/Primary, не Button/Blue
☐ Формат имени: [Тип]/[Вариант]/[Состояние]
☐ Карта иерархии (атомы/молекулы/организмы) актуальна
☐ В AGENTS.md: список атомов, запрет создавать новые без явного запроса
☐ Детачнутых компонентов: ноль или задача в бэклоге