Properties Vocabulary
Единый словарь свойств и вариаций (props) компонентов дизайн-системы. Определяет унифицированные имена, допустимые значения и правила применения свойств для всех компонентов системы.
См. также: states.md — стандарты состояний компонентов, sizes.md — размерная шкала, theming.md — система тематизации.
1. Ключевые принципы
- Единство — одинаковые имена и значения свойств для всех компонентов.
- Семантика, не внешний вид — описывают смысл и роль, а не конкретные визуальные значения.
- Группировка — свойства разделены на три чёткие группы с разными задачами.
- Связь с токенами — каждое свойство — это не хардкод, а ссылка на токен дизайн-системы. Меняется бренд или тема — меняются токены. Набор свойств и их значения остаются неизменными.
2. Классификация свойств
Свойства у компонентов и у элементов разделены на три группы и располагаются по порядку:
- Appearance — изменяют визуальное оформление компонента. Напрямую связаны с токенами дизайн-системы.
- State — отображают поведение компонента. Состояния стилизуются токенами.
- Structure — определяют состав и компоновку содержимого компонента. Управляют слотами и внутренними элементами.
3. Appearance
Свойства влияют на то:
- как компонент выглядит;
- какой визуальный стиль он несёт.
Не влияют на: поведение компонента, его функциональность, состояние (state).
Правила:
- В названиях используются существительные или прилагательные, обозначающие семантическую вариацию внешнего вида.
- Для отображения визуальных эффектов в дизайне имеются булевые свойства в квадратных скобках
[ ]с префиксом Has. В коде нет соответствующих свойств компонента — они реализуются через стили, токены или CSS-классы.
3.1 Visual Style / Стиль и визуальная роль
Свойства отображают семантический визуальный стиль — какую роль компонент играет в интерфейсе.
| Props | Значения свойства | Примеры компонентов |
|---|---|---|
| View — визуальная роль/стиль компонента. Частный вариант: IndicatorView | Default — основной, первичный вид; Secondary — вторичный вид; Tertiary — третичный вид; Accent — акцентный; Positive — позитивный сценарий; Warning — предупреждение; Negative — негативный сценарий; Info — нейтральная информация; AccentGradient — акцентный градиентный | Button, Chip и др. |
3.2 Shape & Boundaries / Форма и границы
Свойства отображают геометрию и контур компонента.
| Props | Значения свойства | Примеры компонентов |
|---|---|---|
| Shape — определяет форму компонента или элементов внутри группы компонентов. В дизайне свойство располагается на уровне Structure компонента — это исключение, связанное с возможностями Figma/Pixso | Default — стандартная форма компонента (базовое скругление по токену из ДС); Pilled — овальная форма; Circled — круглая форма; Segmented — форма для группы компонентов: крайние элементы группы имеют стандартные скругления, внутренние — прямые стыкующиеся края | Badge, Chip и др. |
| Clipped — определяет поведение обрезки содержимого, выходящего за границы компонента. В дизайне свойство располагается на уровне Structure компонента — это исключение, связанное с возможностями Figma/Pixso | True / False (boolean) | Tabs |
3.3 Separation / Разделители
Отображают визуальное разделение между элементами или группами.
| Props | Значения свойства | Примеры компонентов |
|---|---|---|
| SeparationType — определяет, какой тип разделителя | None — разделитель не отображается; Shadow — тень; Divider — дивайдер | TabBar и др. |
3.4 Surface Effects / Визуальные эффекты
Свойства отображают наложение визуальных эффектов поверх компонента.
| Props | Значения свойства | Примеры компонентов |
|---|---|---|
| [HasShadow] — свойство, определяющее наличие тени. В дизайне может располагаться на уровне Structure компонента — исключение, связанное с возможностями Figma/Pixso | True / False (boolean) | Notification и др. |
| [HasOverlay] — свойство, определяющее наличие затемнения | True / False (boolean) | Loader |
| [HasBlur] — свойство, определяющее наличие размытия | True / False (boolean) | Loader |
4. State
Свойства влияют на:
- поведение — в каком состоянии компонент;
- как визуально отображается состояние.
Не влияют на: его функциональность, содержимое.
Правила:
- В названиях используются прилагательные или причастия, обозначающие текущее состояние компонента.
- Для отображения визуальных состояний в дизайне имеются булевые свойства в квадратных скобках
[ ]с префиксом Has. В коде нет соответствующих свойств компонента — они реализуются через CSS-псевдоклассы.
4.1 Process & Feedback States
Свойства отображают состояния процесса и статус валидации.
| Props | Значения свойства | Примеры компонентов |
|---|---|---|
| Loading — отображает состояние загрузки | True / False (boolean) | Button |
| ValidationState — определяет текущий статус выполнения операции и тип обратной связи для пользователя | Default — нейтральное состояние, визуально компонент отображается в стандартном виде; Success — успешное состояние; Warning — состояние предупреждения, данные приняты, но требуют внимания; Error — состояние ошибки, введённые данные не прошли валидацию | Группа компонентов Input (элементы ввода) |
4.2 Selection States
Свойства отображают состояния выбора.
| Props | Значения свойства | Примеры компонентов |
|---|---|---|
| Selected — отображает состояние выбора пользователем компонента или его части (элемента) | True / False (boolean) | Элементы списков (ListItem) |
| Checked — частный случай Selected для контролов или отображением индикацией | True / False (boolean) | CheckBox, RadioBox |
| TernedOn — отображает включённое состояние (компонент имеет тумблер, переключатель) | True / False (boolean) | Switch |
4.3 Data States
Свойства отображают состояния данных внутри компонента.
| Props | Значения свойства | Примеры компонентов |
|---|---|---|
| Filled — отображает состояние, при котором компонент заполнен данными | True / False (boolean) | Группа компонентов Input (элементы ввода) |
| EmptyState — отображает пустое состояние компонента | True / False (boolean) | Select |
| Undefined — отображает пустое состояние компонента | True / False (boolean) |
4.4 Visibility States
Свойства видимости и отображение компонента.
| Props | Значения свойства | Примеры компонентов |
|---|---|---|
| Hidden — свойство, обозначающее скрытое состояние | True / False (boolean) | CodeInput и др. |
| Opened — свойство, обозначающее открытое состояние | True / False (boolean) | DropDown, Accordion |
| Visible — свойство, указывающее на видимость объекта. Частный вариант: ValueVisible в компоненте RatingInput | True / False (boolean) | Rating |
4.5 Interaction States
Свойства отображают визуальную реакцию компонента на взаимодействие.
| Props | Значения свойства | Примеры компонентов |
|---|---|---|
| [Hovered] — отображает состояние, которое показывает пользователю, что элемент интерактивен: визуальное состояние при наведении. В макетах опционально | True / False (boolean) | Группа компонентов Input (элементы ввода), Button, Chip |
| [Actived] — отображает состояние, которое показывает пользователю, что элемент интерактивен: визуальное состояние при нажатии. В макетах опционально | True / False (boolean) | Группа компонентов Input (элементы ввода), Button, Chip |
| [Focused] — отображает состояние, при котором компонент готов к вводу или взаимодействию с клавиатуры. Частный вариант: FocusedLeft и FocusedRight — отображает, какое из двух полей ввода (левое или правое) находится в фокусе в компоненте Range | True / False (boolean) | Группа компонентов Input (элементы ввода) |
4.6 Availability States
Свойства отображают доступность компонента для взаимодействия.
| Props | Значения свойства | Примеры компонентов |
|---|---|---|
| ReadOnly — отображает состояние, при котором компонент доступен только для чтения | True / False (boolean) | Группа компонентов Input (элементы ввода) |
| Disabled — отображает состояние, при котором компонент недоступен для взаимодействия | True / False (boolean) | Группа компонентов Input (элементы ввода), Button, Chip |
5. Structure
Свойства влияют на:
- состав компонента — какие части и элементы в него входят;
- расположение элементов — как они организованы внутри компонента.
Не влияют на: визуальное оформление компонента, состояние компонента.
Правила:
- В названиях используются существительные, обозначающие структурную часть или элемент компонента.
- Булевые свойства, обозначающие наличие частей компонента, начинаются с префикса Has — HasIcon, например.
- Не используется префикс is.
- Свойства, отвечающие за размещение, выравнивание, позиционирование, называются с суффиксами Placement, Align, Direction, Orientation и т.п.
- Если нужно задать свойство, которое определяет пропорции, то название должно состоять из существительного и заканчиваться суффиксом Ratio.
- Если компонент содержит слот («дырку»), то помимо булевого свойства для него создаётся свойство с выбором инстанса — Swap Instance Property. В названии такого свойства обязательно указывается символ «◇», а в значениях перечисляются предпочтительные компоненты для подстановки. В остальных случаях Swap Instance Property не применяется.
5.1 Content Slots / Контент
Наличие и выбор слотов для контента внутри компонента.
| Props | Значения свойства | Примеры компонентов |
|---|---|---|
| HasSlotName — определяет наличие определённого элемента или Слота — именованной позиции внутри компонента, в которую можно поместить контент. Примеры: HasContentBefore, HasContentAfter, HasOptionalIndicator, HasCaption | True / False (boolean) | Во всех компонентах с опциональными элементами |
| ◇SlotName — свойство выбора инстанса: перечисляются предпочтительные компоненты для подстановки. Примеры: ◇Content, ◇ContentBefore, ◇ContentAfter, ◇Action | SwapContent | Во всех компонентах, имеющих Content slots |
5.2 ContentPlacement
Наличие и позиция вложенного контента.
| Props | Значения свойства | Примеры компонентов |
|---|---|---|
| ElementName — свойство наследует имя вложенного компонента. Определяет наличие определённого элемента и его позиционирование в компоненте. Примеры: Hint, Caption, Counter | None — элемент отсутствует; Inner — элемент расположен внутри основного фрейма компонента; Outer — элемент расположен снаружи основного фрейма компонента | TextField и др. |
5.3 Position / Расположение
| Props | Значения свойства | Примеры компонентов |
|---|---|---|
| Placement — определяет расположение основного элемента относительно триггера или расположения на экране Overlay-компонента (частный случай для Stack) | None — независимое положение, нет элемента/триггера, относительно которого может быть расположен компонент; Start — элемент располагается в начале/перед триггером; End — в конце/после триггера; Top — сверху относительно триггера; Bottom — снизу относительно триггера. Частные варианты для Stack: Top-End, Top-Start, Top-Center, Bottom-End, Bottom-Start, Bottom-Center, End-Top, End-Center, End-Bottom, Start-Top, Start-Center, Start-Bottom, Center | DropdownMenu и др. |
| Alignment — управляет выравниванием всего компонента или его основного элемента относительно контейнера. Частный вариант: *ElementName*Align — управляет выравниванием конкретного элемента внутри компонента. Примеры: LabelAlign, LimitLabelsAlign, ValueAlign | None — независимое положение; Start — элемент в начале/перед триггером; End — в конце/после триггера; Top — сверху; Bottom — снизу; Center — элемент выровнен по центру | DropdownMenu и др. |
| Reversed — свойство, которое разворачивает направление компонента на противоположное | True / False (boolean) | Slider |
5.4 Layout Flow
Описывают отступы между элементами в группе и перенос на следующую строку.
| Props | Значения свойства | Примеры компонентов |
|---|---|---|
| Gap — свойство, определяющее отступ между элементами в группах | Dense — маленький отступ, элементы расположены компактно, близко друг к другу; Wide — большой отступ, элементы расположены свободно, с увеличенным пространством между ними; None — без отступа, элементы вплотную друг к другу | Группа компонентов Input (элементы ввода) |
| Wrapped — свойство, определяющее перенос содержимого | True / False (boolean) | Form |
| HasSingleLine — свойство, определяющее обрезку текста в одну строку | True / False (boolean) | Типографические элементы |
5.5 Sizing / Размеры
Описывают размеры элементов и компонентов.
| Props | Значения свойства | Примеры компонентов |
|---|---|---|
| Size — свойство, задающее размер компонента. Важно! В дизайне компоненты разбиты по размерам на отдельные конфигурации, размер указан в названии компонента. Частный вариант: *ElementName*Size — задаёт размер вложенного элемента. Примеры: SpinnerSize, StrockSize | XXS, XS, S, M, L, XL, XXL, Scale | Все компоненты, имеющие размер. Progress — частный случай |
| PointerSize — частный случай Size для элемента Pointer в компоненте Slider | S — маленький размер Pointer; L — большой размер Pointer; None — Pointer отсутствует | Slider |
| Ratio — свойство, определяющее пропорции компонента — соотношение ширины к высоте. Используется преимущественно в медиа-компонентах | 1x1 — квадрат, ширина равна высоте; 1x2 — портретная ориентация, высота в 2 раза больше ширины; 2x1 — альбомная ориентация, ширина в 2 раза больше высоты; 3x4 — близко к портретному формату; 4x3 — классический экранный формат; 16x9 — широкоэкранный формат (видео, баннеры); 9x16 — вертикальный широкоэкранный формат; Custom — произвольные пропорции, задаются вручную | Image |
Примечания из исходника (требуют уточнения у команды): написание TernedOn (в states.md — turnedOn); свойства [Hovered]/[Actived]/[Focused] помечены «в []???»; у PointerSize значения указаны как «Small — надо S / Large — надо L» — в таблице приведены целевые S/L.
Нашли расхождение документации и библиотеки — напишите команде.Сообщить о расхождении