Useful LInks:
Agnostic Design: https://www.figma.com/design/QJa6sj5iHBmR1PBVJsXlHh
Plugin (responsive controls): https://wordpress.org/plugins/block-responsive/
Plugin (responsive controls): https://wordpress.org/plugins/tzm-responsive-block-controls/
Contents:
Good practices for CSS-Var Naming
- Short names, but with the necessary detail.
- Avoid naming by content (component)
--color-button– bad--color-bg-primary– better - Hierarchy – category first, then narrowing
Eg:--color-text-heading-bold-active
Design System Concept
Suffix --adm
Add this prefix for all css classes which you add for blocks from admin panel to write custom styles. This will help to realize that selectors (classes) added from admin and not exists in code.
Units
Units comparation
| Unit | Преимущества | Недостатки | Где особенно уместны |
|---|---|---|---|
| rem | Одна «точка правды»: всё масштабируется от html{font-size}; – Хорошо дружит с браузерной настройкой шрифта → доступность; – Удобно строить скейл токенов (0.25 rem, 0.5 rem … 8 rem). | Меняется глобально: компонент, ожидающий «точно 40px», тоже вырастет; – Требует дисциплины при верстке. | Базовая типографика, миксин spacing-токенов, радиусы, тени. |
| em | Относится к контекстному font-size → в компоненте можно «упаковать» внутренние отступы в em и менять их вместе со шрифтом; | Слишком «чувствительный»: вложенные элементы накапливают масштаб; – Тяжелее просчитывать, если дизайн-система строится вокруг rem. | Внутренние отступы/иконки внутри кнопок, badge-ов, тэгов. |
| % | Простое правило «доля родителя»; – Почти везде поддерживается; | Зависит от типа свойства (ширина — от width, паддинг — от ширины, а margin — от ширины родителя и т. д.); – Для высоты часто бессмыслен, если у родителя высота авто. | Проценты в flex/float/grid- layout-ах, заполнение доступной ширины. |
| vh/vw dvh/lvh/svh vmin/vmax | «Настоящая» адаптивность: 1 vw = 1 % ширины вьюпорта; – Новые динамические единицы (dvh, dvw) учитывают изменение браузерных панелей на мобайле и устраняют «скачок» 100 vh; (MDN Web Docs) | Опасно задавать шрифт напрямую во vw: при очень широком мониторе появляется «газетная» верстка; – На iOS 15–16 старые vh всё ещё «прыгают» — нужен прогрессив-фолбэк. | Hero-баннеры на 100 dvh, full-width/height секции, эффектные заголовки c clamp(1.8rem, 3vw, 3.2rem). |
| px | Интуитивно ясно дизайнерам; – Не «плывёт»; | Не уважает пользовательское zoom/настройки шрифта; – Нужны медиа-квери для любой адаптивности; | Тонкие границы (1 px hairline), ретро-браузерные хаки. |
Ограничения WordPress, о которых стоит помнить
- Не все разделы theme.json принимают
var().
Дляsettings.layout.contentSizeилиsettings.typography.fontFamiliesнужны буквальные значения; там придётся дублировать число либо держать его в PHP фильтре. - Duotone работает только с HEX/RGB, поэтому для фильтров изображений primitives всё-таки могут понадобиться напрямую. (эти стили наверное нужно вообще отключить)
Архитектура системы
Дизайн-система построена вокруг одной core FSE-темы и набора брендовых дочерних тем.
Core-тема задает общие настройки редактора, структуру токенов и флюидные шкалы.
Брендовые темы наследуют core и переопределяют только то, что относится к бренду – палитру, часть семантических токенов и отдельные стили.
Плагин блоков
Функциональность и разметка кастомных блоков вынесены в отдельный плагин FSE-блоков.
Темы отвечают за токены и визуальный слой, плагин – за структуру блоков, поведения и варианты отображения. Это позволяет переиспользовать одни и те же блоки на разных брендовых темах без дублирования логики.
Примитивы и флюидная шкала
В core-теме определен слой примитивов – флюидные размеры для типографики, отступов и других размерных параметров.
Шкалы работают в заданном диапазоне ширины экрана (например, 375–1280 px) и задаются через заранее посчитанные шаги и коэффициенты. Все размеры в системе опираются только на эти примитивы.
Семантические токены
Поверх примитивов описан слой семантики.
На уровне theme.json и CSS-переменных примитивы мапятся в осмысленные токены: типы размеров, роли цветов, служебные переменные (например, высота шапки, мини-бара и т.п.), которые могут вычисляться в JS и сохраняться в CSS. Блоки и темы используют только семантические токены, а не “сырые” значения.
Цветовая система
Core-слой задает не конкретные цвета, а роли.
Каждая брендовая тема объявляет свою палитру, но использует общий набор ролей: базовый фон, контрастный текст, акцент, текст/фон на акценте и вспомогательные слоты. Для расширения используются нейтральные слоты вида color-base-1/2/3 и т.п., что позволяет сочетать “говорящие” роли и более универсальные места под цвет.
Эффекты, тени и motion
В системе есть отдельные шкалы для теней, z-index и motion-параметров.
Дефолтные произвольные градиенты, фильтры и другие “домохозяйские” эффекты WordPress по умолчанию отключены ради предсказуемости и перфоманса. При необходимости эталонные градиенты и эффекты демонстрируются на Agnostic FSE-сайте как часть документации.
Компоненты, блоки и паттерны
Привязка к компонентам реализуется на уровне блоков и паттернов.
Каждый блок (например, кнопка) использует семантические токены размеров и цветов, а не собственные “жестко вшитые” значения. Agnostic FSE-сайт служит витриной: для каждого блока и паттерна есть эталонные конфигурации, которые можно переиспользовать на брендовых сайтах при сохранении тех же имен токенов.
Правила работы редактора
Большинство произвольных настроек редактора выключены: кастомные цвета, случайные градиенты и т.п.
Контент-менеджеры работают только с заранее настроенной палитрой, типографикой и токенами. Это удерживает сайты в рамках дизайн-системы и предотвращает разъезд визуального языка между разными брендами и проектами.
ACF vs нативные блоки
- Мы не будем использовать ACF блоки!
- Возможно нужно делать блоки нативно, без АЦФ, потому что появляются возможности гибко и грамотно добавить кнопки, настройки и т.д. В АЦФ это либо нельзя сделать, либо можно через костыли.
- Лимит — с АЦФ вкладывать блоки внутри блоков очень сложно, почти невозможно, поэтому нужно будет делать блоки нативно (без АЦФ).
- Неработает “HTML anchor” для ACF блока 🙁
- Баг в админке АЦФ: двойные стили, и у родительского блока, например, padding верхний 2 раза применяется, хотя на деле должен быть один раз и на фронте как нужно один раз. Какой-то косяк с лишним тегом обертки для рендеринга в админке…
Margin System
Vertical margins
We use top-only spacing. Each component sets margin-top to control the gap from the element above it, and never relies on margin-bottom. This makes vertical rhythm predictable, avoids margin collapsing, and keeps spacing responsibility on the current element only.
Lock For Blocks
Разобраться с локом блоков. Как это точно работает, где это нам пригодится. Написать об этом доку какую-то.
Есть возможность заблокировать блок (lock). Обсудить, как это будем использовать. Применил в сплит блоке.
Лок в шаблоне блока: https://developer.wordpress.org/block-editor/reference-guides/block-api/block-templates/#locking
Blocks Notes
- Префикс у блоков должен быть
nblockа неblock-
theme.json Notes
- Для каждого цвета в theme.json создать свою переменную. Потому что ВП выбирает по значению а не по слагу и если значение совпадает то цвет может быть выбран не тот…
Helper variables for using in theme.json.
NOTE: These variables are needed to provide uniq variable name to use
it theme.json due to WordPress limitations.
When multiple properties share the same value, WordPress match the
selected element in block editor by the item “value” but not by item “slug”,
because of this we can NOT select the variable. For example:
{ “slug”: “fluid-xl”, “name”: “fluid-xl”, “size”: “var(–some-var)” },
{ “slug”: “edge-x”, “name”: “edge-x”, “size”: “var(–some-var)” },
Since both use the same value, selecting “edge-x” will actually select “fluid-xl” in the block editor.