Архитектура дизайн-системы на React: как не скатиться в хаос из 300 кнопок
Текст написан с позиции октября 2022 года: так, как тема выглядела тогда, без технологий и событий, появившихся позже.
Когда команда впервые начинает строить дизайн-систему на React, все обычно выглядит довольно невинно. Есть несколько кнопок, пара инпутов, модалка, таблица, теги, тултипы, что-то для форм, несколько layout-компонентов — и кажется, что задача в основном организационная. Нужно просто вынести повторяющиеся элементы, оформить их аккуратно, собрать документацию, подключить Storybook или похожий инструмент, и постепенно получится хорошая внутренняя библиотека интерфейса. На ранней стадии это действительно может работать почти без боли. Проблема в том, что именно такой безобидный старт часто и подталкивает команду к архитектурной самоуверенности.
Самая вредная реакция на растущую библиотеку — увидеть, что компонентов стало много, и решить, что проблема в дисциплине отдельных людей: мол, кто-то поленился переиспользовать существующее. Это почти никогда не так. Хаос в дизайн-системе появляется не в тот момент, когда кто-то сознательно решает делать плохо. Он появляется тогда, когда библиотека компонентов растет быстрее, чем растет ясность правил. Сначала появляется одна кнопка. Потом вторая, потому что “у этой немного другой размер и иконка слева”. Потом третья, потому что “для маркетинга нужен свой вариант”. Потом оказывается, что внутри продукта уже живут четыре способа отображать dropdown, три несовместимые модалки, два разных Select и целое семейство полей ввода, похожих друг на друга только на уровне названия. Формально все это еще может находиться в одном репозитории дизайн-системы. Но по сути система уже давно перестала быть системой и стала просто складом React-компонентов.
Именно поэтому разговор об архитектуре дизайн-системы куда важнее, чем разговор о том, как быстро сделать красивый компонентный каталог. Настоящая трудность не в том, чтобы создать кнопку. Настоящая трудность в том, чтобы спустя год у вас по-прежнему была одна осмысленная кнопка как архитектурный примитив, а не тридцать вариантов, каждый из которых появился по локальной причине, но в сумме уничтожил целостность библиотеки. Это, в общем, и есть главный страх любой зрелой команды: дизайн-система не должна стать местом, где хаос получает официальный статус переиспользуемости.
Особенно остро это чувствуется в React-мире, потому что сама компонентная модель очень легко создает иллюзию порядка. Если UI разбит на компоненты, кажется, будто архитектура уже почти случилась. Но компонентность сама по себе ничего не гарантирует. Можно иметь сотни прекрасно оформленных компонентов и при этом не иметь ни ясной системы слоев, ни правил вариативности, ни нормального разделения между примитивами, паттернами и продуктовыми сборками. Тогда библиотека растет, но не взрослеет. И если вовремя не остановиться, команда действительно приходит в ситуацию, где у нее есть не дизайн-система, а хаос из трехсот кнопок, каждая из которых когда-то была “временно нужной”.
Главная ошибка на старте: путать набор компонентов с системой
Это, пожалуй, самая частая и самая дорогая ошибка. Как только команда вынесла несколько общих компонентов в отдельный пакет или папку, возникает ощущение, что дизайн-система уже появилась. На практике это обычно означает только одно: появился общий склад интерфейсных деталей. Система начинается не там, где есть общая директория ui, а там, где возникает управляемый набор правил: какие уровни абстракции существуют, что считается базовым примитивом, что считается композиционным паттерном, что можно расширять, а что нельзя, где проходит граница между универсальным элементом и продуктовой особенностью.
Если этих правил нет, библиотека очень быстро начинает раздуваться не по смыслу, а по инерции. Разработчики добавляют компоненты по локальным потребностям продукта. Дизайнеры называют похожие вещи чуть по-разному. Команда не успевает каждый раз разбираться, является ли новый запрос реально новой сущностью или всего лишь вариантом существующей. В результате в системе появляются сущности, которые различаются не по архитектурной роли, а по историческим обстоятельствам. Именно так и рождается ощущение беспорядка: вроде бы все переиспользуется, но понимания общей модели уже нет.
Хорошая дизайн-система начинается с признания неприятной истины: библиотека компонентов — это не коллекция “всего, что удалось обобщить”. Это язык интерфейса. А у языка должны быть грамматика, словарь и ограничение на бесконтрольное словообразование. Иначе вместо языка получится шум.
Нельзя начинать с кнопок, нужно начинать с уровней
Внешне это может звучать почти странно, потому что большинство дизайн-систем действительно стартуют с кнопок, инпутов и карточек. Но архитектурно начинать нужно не с инвентаризации компонентов, а с определения уровней системы. Это гораздо важнее.
Обычно в зрелой React-дизайн-системе можно различить как минимум несколько уровней. Внизу лежат design tokens: цвета, отступы, типографика, радиусы, тени, размеры, анимационные константы. Выше — базовые примитивы, которые не несут продуктового смысла, но формируют строительный материал интерфейса: Box, Stack, Text, Icon, возможно, примитивы для интерактивности и layout-логики. Затем идут контролы и базовые UI-элементы: Button, Input, Checkbox, Select, Tabs, Modal primitives. Над ними — композиционные паттерны и более крупные строительные блоки: формы, хедеры карточек, меню действий, таблицы с устойчивой структурой, layout-шаблоны, navigation-композиции. И только потом — конкретные продуктовые сборки, которые уже сильно ближе к приложению, чем к самой дизайн-системе.
Если команда не различает эти уровни с самого начала, библиотека очень быстро начинает смешивать все со всем. Рядом лежат токены и специфический WizardStepForm. Базовая кнопка соседствует с MarketingHeroBannerActionButton. Общий Input внезапно зависит от продуктового валидатора. И в этот момент архитектура начинает размываться. Не потому, что кто-то сделал одну ошибку, а потому что сама система не знает, какие типы сущностей в ней вообще существуют.
Уровни нужны не ради академической красоты, а ради дешевизны поддержки через год. Они нужны, чтобы остановить одну из самых опасных тенденций любой дизайн-системы: утечку продуктового контекста в слой, который только притворяется переиспользуемым.
Button — это не один компонент, а контракт вариативности
Разговор о трехстах кнопках почти всегда символический. Речь не буквально о количестве файлов с названием Button. Речь о том, что одна и та же интерфейсная роль начинает дробиться на множество локальных версий. У одной кнопки свой цвет. У другой чуть иная высота. Третья поддерживает loading, но первая почему-то нет. Четвертая знает про иконку справа, но не слева. Пятая — “специальная кнопка для таблиц”, хотя на самом деле отличается только комбинацией двух пропсов. Со временем библиотека начинает производить не систему кнопок, а зоопарк исключений.
Поэтому архитектурно важно мыслить не отдельными компонентами, а контрактом вариативности. Вопрос не “сколько у нас кнопок”, а “каким образом одна кнопка выражает свои допустимые варианты”. Какие размеры разрешены? Какие visual intent’ы есть? Какие состояния входят в стандарт? Что является variant, а что — продуктовой надстройкой? Какие комбинации допустимы, а какие запрещены? Как меняется API при добавлении новой возможности? Если этого договора нет, любое локальное отличие почти неизбежно превращается в “еще одну кнопку”.
Хорошая дизайн-система не борется с разнообразием интерфейса путем насилия над продуктом. Она делает разнообразие управляемым. То есть не плодит новый компонент каждый раз, когда появляется новый угол использования, а сначала пытается понять: это действительно новая сущность или просто вариант существующей роли? И если команда системно отвечает на этот вопрос, число компонентов растет гораздо медленнее, чем число экранов. Это очень хороший признак.
Самая опасная вещь — временные продуктовые исключения
Если спросить, откуда обычно берется хаос в дизайн-системе, ответ почти всегда будет один и тот же: из временных исключений, которые пережили свой временный статус. Продукт приходит с задачей. Нужен особый баннер. Нужна кнопка чуть другого размера. Нужен блок с очень специфическим отступом. Разработчик или дизайнер не хочет задерживать релиз. В систему добавляется “маленькое расширение”, “всего один новый variant”, “специальный case для этого экрана”. В моменте это кажется разумным. Через полгода система уже не помнит, какие из этих решений были осмысленной частью языка, а какие — временным компромиссом под дедлайн.
В этом и состоит одна из самых неприятных ловушек дизайн-системы. Она всегда существует между двумя давлениями: давлением на повторяемость и давлением на скорость продуктовой поставки. Если система слишком жесткая, команда начинает обходить ее из раздражения. Если слишком податливая, она перестает быть системой. Самые опасные решения почти всегда маскируются под прагматизм: “давайте сейчас добавим это быстро, а потом наведем порядок”. Проблема в том, что “потом” почти никогда не наступает само.
Поэтому зрелая архитектура дизайн-системы требует довольно строгого отношения к исключениям. Не в смысле “запрещать продукту жить”, а в смысле фиксировать, какие отклонения действительно становятся частью системы, а какие должны оставаться локальными и не прорастать в библиотечный API. Иначе библиотека начинает накапливать историю компромиссов вместо языка интерфейса.
React провоцирует переабстракцию не меньше, чем хаос
Интересно, что у дизайн-системы есть не только риск расползтись в зоопарк компонентов, но и обратный риск — начать слишком рано строить “идеальные универсальные сущности”. React особенно к этому подталкивает. Как только команда видит повторение в трех местах, появляется искушение создать супер-гибкий компонент, который сможет быть и кнопкой, и ссылкой, и dropdown trigger, и CTA, и почти всем на свете. На бумаге это выглядит как победа над дублированием. На практике часто рождает чудовищный API с десятками пропсов и тоннами условной логики.
Почему это все равно хаос, хотя компонент один? Потому что сложность никуда не делась — она просто переехала из числа файлов в число пропсов. Вместо трехсот кнопок вы получаете одну кнопку-монстра, которая знает слишком много о слишком разных сценариях. Такой компонент сложно документировать, тяжело тестировать, неприятно изменять и почти невозможно сделать по-настоящему предсказуемым. Более того, разработчики все равно начинают оборачивать его тонкими локальными обертками, потому что прямое использование становится слишком сложным. И библиотека снова разрастается, только теперь еще и через скрытые уровни адаптации.
Хорошая архитектура дизайн-системы поэтому должна уметь держать две границы сразу. Не плодить сущности без меры. Но и не схлопывать слишком разные роли в один “универсальный” компонент ради формальной элегантности. Это, пожалуй, один из самых трудных навыков: понимать, где обобщение действительно укрепляет язык системы, а где просто переносит хаос внутрь API.
Токены важнее компонентов, но компоненты заметнее
Во многих командах дизайн-система воспринимается прежде всего как библиотека React-компонентов. Это понятная оптика, потому что компоненты — видимая часть работы. Их рендерят, тестируют, документируют, обсуждают в pull request’ах. Но архитектурно самым долговечным слоем системы чаще оказываются не они, а design tokens. Именно токены удерживают язык цвета, отступов, размеров, типографики, радиусов, теней и состояний в форме, которую можно масштабировать, рефакторить и синхронизировать между платформами.
Если токены устроены плохо, никакая красота компонентов не спасет систему надолго. Потому что каждый следующий UI-элемент начнет принимать решения о цветах, расстояниях и визуальных состояниях локально. Это быстро производит очень дорогой эффект: компоненты внешне похожи, но не происходят из одного языка. Тогда дизайнеру кажется, что библиотека есть, а разработчику — что в ней нельзя ничего менять без каскада побочных последствий.
И наоборот, если токены организованы хорошо, даже довольно простые компоненты уже начинают вести себя как часть единой системы. Их легче тематизировать, легче поддерживать консистентность, легче переносить между продуктами и даже легче обсуждать между дизайном и разработкой. Поэтому одна из самых больших ошибок — строить дизайн-систему “сверху вниз”, только через компоненты, не договорившись о достаточно зрелом слое визуальных примитивов.
Разделяйте визуальный примитив и поведенческий примитив
В React-системах это различие особенно важно. Очень многие проблемы библиотек компонентов возникают потому, что визуальная и поведенческая ответственность смешиваются в одних и тех же сущностях без ясных правил. Например, Modal может одновременно определять и логику focus trap, и порталы, и keyboard interaction, и конкретную визуальную рамку, и типовые отступы, и заголовок, и кнопки, и layout футера. На старте это удобно. Потом оказывается, что продукту нужны разные визуальные оболочки для одной и той же интерактивной механики. И начинается боль.
Зрелая архитектура обычно выигрывает, когда умеет отделять headless или behavior-oriented primitives от визуальных реализаций там, где это оправдано. Это не значит, что вся дизайн-система должна срочно стать headless. Но означает, что команда должна уметь различать: что в этом компоненте является общей интерактивной механикой, а что — конкретной визуальной договоренностью. Когда эти уровни спаяны без нужды, система либо становится слишком негибкой, либо начинает плодить визуальные клоны одного и того же поведения.
Это особенно заметно на Select, Dropdown, Popover, Tooltip, Modal, Tabs, Menu и других богатых интерактивных сущностях. Там, где поведение сложно и повторяется, а визуальная оболочка имеет право меняться, архитектурная развязка почти всегда окупается.
Документация — не приложение к системе, а часть ее архитектуры
Очень часто команды начинают относиться к документации дизайн-системы как к чему-то вторичному. Сначала “доделаем компоненты”, потом “подтянем сторисы”, потом “когда все стабилизируется, опишем правила”. На практике это почти всегда путь к деградации. Потому что система без документации перестает быть системой довольно быстро, даже если код у нее пока хороший.
Архитектурная ценность документации в том, что она фиксирует не только то, как компонент выглядит, но и то, что он вообще означает. Какова его роль? Когда его использовать, а когда нет? Какие variants являются системными, а какие — продуктовой адаптацией? Какие пропсы обязательны и почему? Какие сочетания состояний допустимы? Какие решения уже приняты на уровне системы, чтобы разработчик не пытался “улучшить” компонент локально? Без таких ответов библиотека начинает жить как набор технических API без продуктового и дизайнерского контекста. А это очень короткий путь к хаосу.
Storybook и подобные инструменты ценны не потому, что красиво показывают кнопки. Они ценны тогда, когда становятся местом, где система описывает свои границы и намерения. Если документация этого не делает, компоненты начинают интерпретироваться командами по-своему. И даже хорошо написанный код не спасает от расхождения практик.
Пакетная структура и монорепозиторий не решают архитектуру автоматически
Как только дизайн-система становится заметной частью организации, почти неизбежно начинается разговор о пакетах, workspace-структуре, versioning, токен-пакетах, иконках, shared-utils, theming, build pipeline и публикации в registry. Все это важно. Но здесь есть риск, который стоит проговорить прямо: техническая инфраструктура вокруг дизайн-системы может создать очень убедительную иллюзию зрелости, даже если архитектурные границы самой системы остаются мутными.
Можно иметь монорепозиторий, отдельные пакеты для tokens, primitives, icons и components, CI-пайплайн, changelog, релизы и визуальные тесты — и при этом все равно страдать от того, что в библиотеке не проведена граница между системным элементом и продуктовой импровизацией. Точно так же можно иметь идеальный пакет @company/ui-button, внутри которого зашит хаос из семи несогласованных сценариев использования. Инфраструктура полезна, но она не заменяет семантической архитектуры.
Это особенно важно в больших организациях, где зрелость часто начинают измерять количеством инженерной обвязки. На практике хаос в дизайн-системе редко происходит из-за отсутствия хорошего bundler’а. Он происходит из-за отсутствия ясного языка компонентов и политики изменений.
Политика изменений важнее идеального API первого дня
Еще одна зрелая мысль, которая спасает систему от превращения в свалку, звучит так: главное не придумать идеальный API компонентов сразу, а построить такую политику изменений, при которой библиотека не разрастается от каждого нового продуктового запроса. Почти все API устаревают. Почти все ранние решения окажутся неполными. Это нормально. Ненормально — если каждый продуктовый кейс моментально получает статус новой официальной вариации системного компонента.
Поэтому архитектура дизайн-системы должна включать не только слои и сущности, но и процедуру принятия решений. Когда добавляется новый variant? Кто определяет, системный это кейс или частный? Когда нужно расширить существующий компонент, а когда — оставить кастомизацию локально? Когда пора делать breaking change, а когда лучше дать переходный путь? Как документируется причина появления нового API? Если таких правил нет, библиотека неизбежно превращается в историю накопленных уступок.
Сильные дизайн-системы редко побеждают тем, что у них безупречный первый draft. Они побеждают тем, что умеют не терять целостность под давлением постоянных изменений.
Accessibility не должна жить “рядом” с компонентом
К 2022 году для React-дизайн-системы это уже не дискуссионный вопрос: доступность нельзя рассматривать как отдельный слой доработки, который прикручивается потом. Если библиотека компонентов не включает accessibility в саму архитектуру примитивов, она почти наверняка начнет производить красивый, но ненадежный интерфейсный долг.
Особенно опасна ситуация, когда команда создает десятки визуально “готовых” компонентов, а потом обнаруживает, что keyboard navigation, ARIA-атрибуты, focus management, screen reader expectations и interactive semantics каждый раз нужно доводить заново. В такой модели библиотека вроде бы экономит время, но на самом деле лишь консервирует визуальную оболочку без поведенческой зрелости.
Если же accessibility входит в архитектурное определение компонентного примитива с самого начала, количество действительно качественных сущностей в системе может быть меньше, но их ценность намного выше. Это один из тех случаев, когда лучше иметь двадцать зрелых элементов, чем двести полуготовых. Потому что каждая новая вариация поверх слабого основания лишь умножает стоимость исправления в будущем.
Не каждая повторяемость заслуживает места в дизайн-системе
Это правило особенно трудно принять продуктовым командам. Когда что-то повторилось несколько раз, возникает естественное желание “занести это в систему”. Кажется, что так и должна работать зрелая библиотека: все переиспользуемое должно жить в одном месте. Но на практике это не всегда так. Есть повторяемости случайные, временные, обусловленные этапом развития продукта. Если такие вещи слишком рано попадают в дизайн-систему, библиотека начинает хранить следы локальных решений как будто это часть языка интерфейса.
Поэтому зрелая система умеет говорить “нет” не только хаотичным отклонениям, но и преждевременному обобщению. Иногда компонент должен еще пожить в продукте, прежде чем получит право стать системным. Иногда два похожих паттерна еще не означают, что у них одна и та же сущность. Иногда правильнее подождать, пока повторение стабилизируется по смыслу, а не только по внешнему виду.
Это очень важный фильтр. Без него библиотека быстро превращается в архив всех решений, которые когда-либо дважды встретились на экране. А это почти гарантированный путь к шуму под видом системности.
Лучшая метрика здоровья — не количество компонентов, а предсказуемость выбора
Команды часто пытаются измерять зрелость дизайн-системы числом покрытых кейсов, количеством компонентов, полнотой документации или шириной adoption внутри организации. Все это имеет значение, но есть более показательная метрика: насколько предсказуемо разработчик и дизайнер понимают, что использовать в конкретной ситуации.
Если в библиотеке десять кнопок, и каждый раз нужно вспоминать исторические отличия между ними — система нездорова. Если есть три похожих Select-компонента и только два человека в команде понимают, почему один для форм, второй для фильтров, а третий “старый, но еще везде используется” — система нездорова. Если новый экран каждый раз требует консультации с автором библиотеки, потому что API и роли элементов неочевидны — система нездорова. И наоборот, если у библиотеки сравнительно скромный набор примитивов, но выбор между ними почти всегда ясен, это очень сильный сигнал архитектурной зрелости.
Дизайн-система побеждает не широтой ассортимента, а снижением когнитивной нагрузки. Когда она этого не делает, число компонентов перестает быть достижением и становится симптомом.
Итог
Архитектура дизайн-системы на React нужна не для того, чтобы аккуратно разложить компоненты по папкам, а для того, чтобы библиотека оставалась языком интерфейса, а не складом исторических компромиссов. Хаос из трехсот кнопок возникает не потому, что кто-то однажды ошибся с Button.tsx. Он возникает тогда, когда система не различает уровни абстракции, не умеет управлять вариативностью, принимает каждое продуктовое исключение как новую официальную сущность и путает повторяемость с правом на системный статус.
Чтобы этого не произошло, важно начинать не с инвентаризации компонентов, а с определения слоев: tokens, примитивы, контролы, композиционные паттерны, продуктовые сборки. Важно держать контракт вариативности, а не плодить новые сущности по каждому локальному поводу. Важно различать визуальные и поведенческие примитивы, включать accessibility в само основание системы, относиться к документации как к части архитектуры и иметь политику изменений, которая фильтрует временные исключения и преждевременные обобщения.
И если сформулировать совсем прямо: зрелость дизайн-системы измеряется не числом компонентов, а предсказуемостью выбора — тем, насколько уверенно команда знает, что взять под конкретную задачу, и насколько редко новый продуктовый запрос вынуждает размывать язык библиотеки. Как только команда начинает мыслить именно так, React перестает быть фабрикой случайных reusable-элементов и становится действительно хорошей основой для системы. А это и есть лучший способ не проснуться однажды в проекте, где у вас официально существует триста кнопок и ни одной по-настоящему понятной.