Правила оформления компонентов

Источник: ds-docs/reference/guidelines/component-authoring-rules.md

Версия документа 2.0.

Как заводить и дорабатывать компоненты в Figma: атомарность, нейминг, свойства (Variant, Boolean, Text, Instance swap), значения переменных, слои и State layer. Теги в именах — Теги в названии компонентов; версии компонента — Версии компонента. Связано: README, ds-internal/AUDIT.md.

Зачем

«Общая библиотека компонентов будет включать основные цвета, шрифты и готовые элементы дизайна с использованием этих стилей.»
«Необходимо создавать компоненты таким образом, чтобы они были доступны к пониманию любым дизайнерам и разработчикам.»
«Компоненты представляют собой универсальный инструмент для совместной работы, они должны быть чётко определены и тщательно проработаны. Разработчик должен понимать суть, назначение и особенности компонентов. Пользователи должны получать удовольствие от удобства и быстрого решения своих задач.»

Вопросы — «Сереге и Жасуру из команды дизайн-системы» (контакты — Теги в названии компонентов, «Запросить новый код»).

1. Атом в компоненте

«Наши компоненты должны быть организованы соответствуя методологии „Атомарный дизайн“.»
«Компоненты атомы будут частыми элементами нашего дизайна. Это детали наших компонентов молекул, организмов и шаблонов.»
Атомы не используются напрямую в макетах — «они являются частью больших и направленных на определённые цели компонентов».
Правило именования. Знаком в имени атом больше не отмечают: различие «атом» живёт в контракте, а не в названии слоя.

⚠️ Версия 2.0 требовала: «В макетах вы должны отмечать их символом перед названием ✱.» Соглашение отменено 14.10.2026, знак снят во всех трёх файлах Figma (Astra DS, Astra Fintech UI, Astra DS: Icons) и в 126 контрактах. Вслед снято правило каталога NAME-005, которое на этом знаке держалось.

2. Планирование нового компонента

«Перед тем как приступить к работе, необходимо проанализировать предыдущую версию компонента и определить его недостатки. Некоторые компоненты уже обладают хорошими характеристиками, но требуют дополнительной доработки.»

Порядок действий:

Найти существующий компонент и доработать его.
Нет точного — «найдите его ближайший аналог и доработайте его».
Только если и это не выход — «создайте локальный новый компонент».

«Знайте, чем больше компонентов, тем сложнее это поддерживать.»

Работа над компонентами

Название компонентов и слоёв

«Будем использовать аннотацию Pascal Case, только с пробелом для наименования компонентов и слоёв. Так будет проще искать компоненты в Assets и читать их. А разработчику видеть привычную аннотацию, но только с пробелом.»

Пример. Calculate Elephant Weight

Properties — общее правило

Главное правило. «Properties (свойства в боковой панели Figma) должны выводиться по логике их расположения в компоненте (визуально), слева направо.»

1. `Variant`

«Variant — функция вариации компонентов. Компоненты должны быть адаптивными и простыми в использовании. Применяйте Variants, чтобы другой дизайнер мог настроить компонент в соответствии со своими потребностями. Для уменьшения количества Variants используйте Instance swap.»

«Важно правильно подписывать свойства компонентов по их смыслам»:


`◆ Type`	«Тип — это состояния, которые сильно отличаются друг от друга. Сильное отличие в структуре компонента.»
`◆ Style`	«Визуальные варианты компонентов, структурно все свойства компонента должны быть затронуты.»
`◆ Size`	«Варианты размера компонентов. Значения должны быть `small (sm)`, `medium (md)`, `large (lg)`, `max`.»
`◆ State`	«Состояние компонента, такие как `hover`, `pressed`, `filled`, `disabled`, `error` и т.д.»
`◆ Selected`	«Состояние выделения или выбора, значения `false` и `true`.»

«Данная таблица будет пополняться.»

2. `Boolean props`

«Boolean — это свойство, которое позволяет изменять видимость слоя компонента, используя два значения: True или False. Оно скрывает как сам слой, так и связанные с ним параметры в панели Properties.»

Правило именования. «Название свойства всегда должно иметь следующую форму: Show "Название слоя или компонента".»

3. `Text`

«Позволяет изменять текст с помощью панели Properties. Можно выбрать несколько объектов и обновить текст одновременно. Огромную ценность имеет правильное именование текстовых свойств — по их смыслу и предназначению.»


`Label` \| `Text` \| `Description` \| `Value`	«Базовое значение текста, оно должно быть всегда статично»
`Placeholder`	«Наполнитель в компоненте, для информированности пользователя»
`Default Value`	«Значение по умолчанию»
`Default Selected`	«Выбранное значение по умолчанию. Пример, dropdown с выбранным значением по умолчанию»
`Filled Value`	«Заполненное значение»
`Disabled Empty`	«Заблокированное значение, для удобства отображения не заполненного состояния»
`Disabled Filled`	«Заблокированное значение, для удобства отображения заполненного состояния»
`Helper text` \| `Description`	«Текст подсказки»
`Warning message`	«Предупреждающий текст»
`Error message Empty`	«Текст ошибки о не заполнении компонента»
`Error message Filled`	«Текст ошибки валидации при проверке заполненного состояния»

4. `Instance swap`

«Instance swap — смена компонента на другой компонент. Позволяет заменять вложенные компоненты через панель Properties. Можно выбрать стандартный экземпляр из локальной или подключённой библиотеки.»

«Обратите внимание, что Instance Swap учитывает иерархию и может заменять только те компоненты, которые находятся на одном уровне. Таким образом, варианты вложенного компонента должны быть отдельными элементами, а не объединёнными в Variants.»

Обязательная обёртка:

«Компонент со свойством Instance swap должен быть помещён во frame. Frame должен иметь следующее название: ["Название" Container].»
«Если есть необходимость в скрытии слоя с помощью функции Boolean props, используйте это на frame ["Название" Container], а не на компоненте.»
«В Properties используйте следующую формулу для обозначения Instance swap: Swap "Название" Container. Название должно соответствовать frame в слоях.»

Это источник конвенции Format Container / … Container в карточках компонентов: контейнер — точка подстановки, а не самостоятельный компонент (см. D-009).

Название `Value` в `Variable`

«В данном разделе мы будем собирать и стандартизировать списки в Variable компонента.»


`Default`	По умолчанию
`Hovered`	Наведение
`Focused Empty`	«Фокус до ввода или выбора значения»
`Focused Filled`	«Фокус при вводе или выборе значения»
`Pressed`	Нажатие
`Filled`	«Заполнено или выбрано»
`Filled Confirmed`	«Заполнено и подтверждено»
`Read Only`	Только чтение
`Warning`	Предупреждение
`Warning Focused`	«Состояние предупреждения с фокусом»
`Error Empty`	«Ошибка о не заполнении, выборе и т.д.»
`Error Filled`	«Ошибка при валидации, проверке на заполненное или выбранное значение»
`Disabled Empty`	«Заблокировано не заполнено»
`Disabled Filled`	«Заблокировано заполнено»
`Skeleton`	Скелетон

⚠️ В источнике значение записано как Filled Сonfirmed — с кириллической С вместо латинской C (Q-001).

Layers

«Правильное оформление слоёв — залог успеха в жизни. Все слои нужно подписывать и держать в чистоте и порядке.»

Нейминг слоёв — тот же Pascal Case с пробелом, что и у компонентов.

Две категории компонентов


Статичные	«Элементы, по которым невозможно кликать. Они могут иметь только информативное состояние.»
Кликабельные	«Элементы, по которым мы можем кликать. У них есть такие состояния как: наведение, нажатие, фокус, выделение, перетаскивание и свайп.»

Про наведение в мобильном приложении: «вы скажете, наведения в мобилке нет, ты о чём? Но мы разрабатываем на React, и использовать их в вебе — вопрос времени». То есть hover заводится даже для мобильных компонентов — заранее, под веб.

Счётная высота

«Хорошим тоном считается делать высоту компонентов счётным числом. Из-за этого важно контролировать все размеры слоёв компонента. Это можно делать фиксированием с помощью токенов размера или функциями Add min width (height)… и Add max width….»

State layer

«State layer — это полупрозрачное покрытие элемента, указывающее на его состояние. Слои состояния обеспечивают системный подход к визуализации состояний с помощью непрозрачности.»

«Вне зависимости от цвета background компонента, слои состояния всегда одни и те же. Получается, слой состояния должен быть на всей области изменения слоя.»

Порядок слоёв (снизу вверх):

Контейнер
Слой состояния
Контент

Токен анимации нажатия — motion-state-layer-press (см. motion).

Открытые вопросы


Q-001	В таблице `Variable` значение записано как `Filled Сonfirmed` с кириллической `С` — в Figma это даст невалидное имя варианта	Заменить на латиницу	Владелец ДС
Q-002	Список слоёв `State layer` в источнике идёт как «Контент / Контейнер / Слой состояния / Контент» — порядок дублируется и противоречит тексту «1. Контейнер, 2. Слой состояния»	Оставить один однозначный стек: Контейнер → Слой состояния → Контент	Владелец ДС
Q-003	`◆ State` в таблице `Variant` перечисляет `hover`, `pressed`, `filled`, `disabled`, `error`, а раздел `Variable` — `Hovered`, `Pressed`, `Filled`, `Disabled Empty/Filled`, `Error Empty/Filled`. Формы не совпадают (`hover` vs `Hovered`, без разделения Empty/Filled)	Свести к одному списку значений	Владелец ДС
Q-004	«Высота компонента — счётное число» не задаёт шага сетки (4/8 px)	Указать шаг явно и сослаться на `space`-шкалу	Владелец ДС
Q-005	Не указано, какие токены прозрачности использует `State layer` (в motion есть `opacity-hidden/veil/visible`, но привязки к состояниям нет)	Задать таблицу «состояние → токен прозрачности»	Владелец токенов
Q-006	Правило «атомы не используются напрямую в макетах» не описывает, что делать с уже собранными макетами, где атом вставлен напрямую	Дать процедуру миграции или явно разрешить как исключение	Владелец ДС
Q-007	Синтаксис контейнера в источнике приведён в трёх написаниях: `(["Название" Container])`, `["Название" Container]`, `(Swap "Название" Container)` — неясно, входят ли скобки в имя слоя	Зафиксировать точный шаблон имени frame и имени свойства	Владелец ДС
Q-008	Заявлено «версия документа 2.0», но истории изменений нет — непонятно, что изменилось относительно 1.0	Добавить блок «История изменений»	Владелец ДС

Источник

buildin.ai, «Гайды → Компонентные библиотеки → Правила оформления компонентов» 83ad7582-0576-4196-a13b-109e3082dee0, версия документа 2.0.
Прочитано 2026-07-30; 4 таблицы сняты из блочной модели документа (в вёрстке они виртуализированы и в текст страницы не попадают).
Иллюстрации в источнике (image.png, 9 шт.) не переносились — смысловая часть в тексте выше.