Изучите фактические семантические токены Web Awesome в нативных пользовательских элементах, включая локальные изменения радиуса и интервалов, стилизацию Shadow DOM, поведение списков выбора и валидацию полей ввода.
Нативные пользовательские элементы Web Awesome 3.14.0 и тема по умолчанию, локально собранные. · Справочник по реализации
02
Справочник дизайн-системы Web Awesome
Тема по умолчанию CSS для Web Awesome 3.14.0, изученная в установленном пакете. Приведённые ниже значения цветов — семантические псевдонимы; ссылки на палитру сохранены, а не заменены предположительными HEX-значениями. Примеры размеров в пикселях, рассчитанные по шкале, предполагают корневой размер шрифта 16 px и масштаб 1.
Пользовательские элементы дизайн-системы Web Awesome со своей границей компонента
Пользовательские элементы со своей границей компонента
Web Awesome предоставляет зарегистрированные пользовательские элементы HTML, поэтому приложение React не требуется. После импорта wa-input или wa-select элемент можно поместить в обычный HTML и управлять им с помощью документированных свойств и событий. В этой рабочей области локально собрана версия 3.14.0 и используются только компоненты из общедоступного пакета.
Видимые элементы управления — это настоящие пользовательские элементы со своей реализацией в теневом DOM. Заголовок, разделы и область отображения кода вокруг них — оригинальные элементы HTML. Благодаря этому пример позволяет увидеть, какие решения о стилизации распространяются через границу компонента с помощью наследуемых пользовательских свойств, а какие относятся к композиции страницы.
Сохраняйте семантические псевдонимы цветов дизайн-системы Web Awesome
Сохраняйте семантические псевдонимы цветов
Тема по умолчанию различает приподнятые, базовые и утопленные поверхности, обычный и спокойный текст, а также несколько пар цветов заливки бренда и текста на ней. Для области отображения токенов используется утопленная поверхность, для основного примера — базовая поверхность, а небольшой бейдж сочетает brand-fill-quiet и brand-on-quiet. Эти роли сохраняют смысл при смене оформления.
В справочнике сохранены псевдонимы, например var(--wa-color-neutral-10), вместо того чтобы подставлять предполагаемые HEX-значения для каждой роли. Палитра может измениться, а семантическое назначение останется корректным. Если вы меняете цвет заливки для важного действия бренда, учитывайте также цвет текста на ней. Изменение только одного из этих цветов может ухудшить читаемость текста кнопки.
Меняйте шкалу, не переписывая каждый компонент дизайн-системы Web Awesome
Меняйте шкалу, не переписывая каждый компонент
Переключатель скруглений меняет только у образца значение --wa-border-radius-scale. При масштабе 1 значения токенов скругления малого, среднего и большого размера составляют три, шесть и двенадцать пикселей при корневом размере шрифта 16 px. При масштабе 0 масштабируемые углы становятся прямыми; при масштабе 2 их размер удваивается. Токены для формы таблетки и круга — отдельные понятия; не следует считать, что их размер зависит от этого множителя.
Переключатель отступов меняет --wa-space-scale. Для полей, интервалов и отступов в области отображения кода используются официальные токены space, поэтому их соотношения меняются согласованно. Это не означает, что масштабируются все размеры каждого компонента: для размеров элементов управления есть собственные зависимости от токенов. Панель редактирования находится вне области действия настройки, поэтому её вид остаётся неизменным, пока меняется пример.
Выберите «Квадратные углы» и изучите скругления поля ввода, контейнера и области отображения кода.
Выберите увеличенные отступы и сравните интервалы в примере с неизменившейся панелью редактирования.
Восстановите значения по умолчанию, чтобы одновременно вернуть исходные множители и оформление.
Токены типографики и авторский выбор заголовков в дизайн-системе Web Awesome
Токены типографики и авторский выбор заголовков
По умолчанию для основного текста используется семейство шрифтов ui-sans-serif, system-ui, sans-serif. Для заголовков используется то же семейство, что и для основного текста, а для кода — ui-monospace. Обычный токен межстрочного интервала равен 1.6, сжатый — 1.2. Средний типографический токен равен одному rem, умноженному на font-size-scale, а для более крупных размеров используются округлённые вычисления. В таблице приведены эти выражения, чтобы показать их зависимости.
В самой рабочей области для заголовка выбрано значение 34px, а для заголовка раздела — 23px; при локальной контрольной точке 700px размер заголовка страницы уменьшается. Это явно заданные оригинальные правила страницы. Для нативных полей сохраняются стили меток и подсказок библиотеки, чтобы пользователь мог сравнить собственную иерархию страницы с типографикой компонентов по умолчанию.
Начальные значения, свойства и события изменения дизайн-системы Web Awesome
Начальные значения, свойства и события изменений
Каждый элемент select содержит дочерние элементы wa-option со стабильными значениями. В вариантах по умолчанию используется атрибут selected, как и предписывает актуальное руководство по начальному выбору компонента. При изменениях во время работы читается свойство value элемента select. Элементы управления темой отслеживают события change и обновляют пользовательские свойства CSS; текст отображаемых подписей вариантов для этого не анализируется.
Выбор региона — обычное демонстрационное поле, которое не управляет внешней службой хранения данных. Выбранное значение отображается в локальном сообщении о действии. Интерфейс не создаёт впечатления, будто выбор региона «Европа» выделяет хранилище. Это различие важно, когда реалистично выглядящая демонстрация компонента использует продуктовую терминологию.
Стилизация дизайн-системы Web Awesome с помощью токенов и документированных частей
Стилизуйте с помощью токенов и документированных частей
Обычные селекторы потомков не могут напрямую обращаться к содержимому теневого дерева компонента. В этом примере используются наследуемые переменные темы: так фон поля, цвет текста и радиус можно согласовать с окружающими элементами HTML. Это поддерживаемый способ стилизации, а не попытка обратиться к внутренней сгенерированной разметке.
Чтобы внести изменения для конкретного компонента, изучите документированные пользовательские свойства и части CSS этого компонента. Глобальный селектор input не обязательно изменит внутренний элемент input компонента wa-input. И наоборот, класс темы или переменная на общем предке могут намеренно влиять на множество дочерних пользовательских элементов, поэтому область действия нужно выбирать внимательно.
Обновление, проверка и локальные результаты дизайн-системы Web Awesome
Обновление, проверка и локальные результаты
С точки зрения страницы регистрация компонентов выполняется асинхронно. В примере ожидается выполнение customElements.whenDefined для используемых API, а затем — обновление элементов select, прежде чем считываются начальные значения. Так начальные значения не применяются к элементу, который ещё не прошёл обновление из неизвестного тега HTML до класса компонента.
Для локального применения имени рабочая область использует setCustomValidity и reportValidity на wa-input. Имя после удаления пробелов по краям должно содержать не менее двух символов; иначе оно отклоняется. Событие input сбрасывает пользовательскую ошибку, чтобы можно было повторить попытку после исправления. Кнопка «Пригласить позже» отключена с помощью нативного состояния disabled компонента. Текст состояния сообщает только о локально применённом имени; полный код не отправляет запросов на создание рабочей области или выделение хранилища.
Подписанные поля размечены с помощью атрибутов label.
Подсказки сообщают об ограничении для имени до появления ошибки.
Отключённая кнопка остаётся неинтерактивной, но её назначение видно.
Импорт темы и используемых компонентов дизайн-системы Web Awesome
Подключайте тему и используемые компоненты
Установите @awesome.me/[email protected] в обычное приложение Vite и используйте предоставленный main.js как точку входа. Таблица стилей темы по умолчанию обязательна; пример намеренно не подключает более широкий набор сброса нативных стилей или утилит, поскольку макет страницы задан явно CSS. Импорты регистрируют пять типов компонентов, используемых в разметке.
Модули npm dist предназначены для сборщиков. Вариант dist-cdn подходит для непосредственной загрузки модулей в браузере, поскольку зависимости в нём объединены иначе. Не копируйте импорт из dist в обычный тег script, рассчитывая, что зависимости без указания пути будут разрешены автоматически. Для компонентов, которым нужны внешние ресурсы, требуется настроить базовый путь согласно документации; в этом образце не используются предоставляемые пользователем иконки, а сборка выполняется для автономной работы.
Публичные компоненты и границы темы дизайн-системы Web Awesome
Общедоступные компоненты и реальные границы темы
В рабочей области показаны тема по умолчанию и публичные компоненты. Некоторые компоненты, шаблоны и ресурсы для дизайна Web Awesome доступны в версии Pro, поэтому страница не создаёт впечатления, будто установка публичного пакета открывает доступ ко всему каталогу. Прежде чем делать компонент обязательной зависимостью общей дизайн-системы, следует проверить, доступен ли он.
В документации к повторно используемой теме продукта следует указать, какие переменные изменены, где они действуют и как проверены оба режима отображения. Рабочая область — небольшой пример такого процесса: читатель может увидеть конкретно изменённые переменные и сравнить результат на нативных компонентах, а не полагаться на отдельное изображение палитры.
Для начального выбора на wa-option используется selected.
Используются только бесплатные компоненты.
Полные импорты и элементы управления токенами
Регистрирует компоненты, ожидает их обновления, изменяет ограниченные областью действия пользовательские свойства и применяет локальную проверку допустимости.
javascript
import '@awesome.me/webawesome/dist/styles/themes/default.css';
import '@awesome.me/webawesome/dist/components/button/button.js';
import '@awesome.me/webawesome/dist/components/input/input.js';
import '@awesome.me/webawesome/dist/components/select/select.js';
import '@awesome.me/webawesome/dist/components/option/option.js';
import '@awesome.me/webawesome/dist/components/switch/switch.js';
import './style.css';
const $=id=>document.getElementById(id);function update(){const s=$('specimen');s.style.setProperty('--wa-border-radius-scale',$('radius').value);s.style.setProperty('--wa-space-scale',$('spacing').value);s.classList.toggle('wa-dark',$('dark').checked);s.classList.toggle('wa-light',!$('dark').checked);$('values').textContent=`--wa-border-radius-scale: ${$('radius').value};\n--wa-space-scale: ${$('spacing').value};`;}
Promise.all(['wa-select','wa-switch','wa-input','wa-button'].map(x=>customElements.whenDefined(x))).then(async()=>{await Promise.all([...document.querySelectorAll('wa-select')].map(e=>e.updateComplete));for(const id of ['radius','spacing','dark'])$(id).addEventListener('change',update);$('reset').addEventListener('click',()=>{$('radius').value='1';$('spacing').value='1';$('dark').checked=false;update()});$('create').addEventListener('click',()=>{const field=$('workspace');field.setCustomValidity(field.value.trim().length<2?'Use at least two non-space characters.':'');if(!field.reportValidity())return;$('result').textContent=`Applied “${field.value.trim()}” in the ${$('region').value} specimen. No workspace or storage allocation was created.`});$('workspace').addEventListener('input',()=>$('workspace').setCustomValidity(''));update()});
Создайте проект Vite без фреймворка и используйте полные версии main.js и style.css, приведённые выше.
04
Настройка агента дизайн-системы Web Awesome
Отправная точка для реализации
Полные примеры main.js, CSS и body воспроизводят рабочую область в сборщике. Автономная демонстрация собрана с помощью esbuild, а тема CSS встроена в пакет. Провайдер React не требуется.
javascript
// Create a Vite vanilla project, then install:
// npm install @awesome.me/[email protected]
// index.html: paste the complete workbench markup in body,
// then add <script type="module" src="/main.js"></script>.
// main.js: use the complete imports and token-controls example above.
// style.css: use the complete scoped specimen CSS above.
// Minimum registration pattern used by this example:
import '@awesome.me/webawesome/dist/styles/themes/default.css';
import '@awesome.me/webawesome/dist/components/button/button.js';
import '@awesome.me/webawesome/dist/components/input/input.js';
import '@awesome.me/webawesome/dist/components/select/select.js';
import '@awesome.me/webawesome/dist/components/option/option.js';
import '@awesome.me/webawesome/dist/components/switch/switch.js';
// Do not duplicate these imports if using the complete main.js above.
Запрос для вашего проекта
Промпт для AI-агента
Используйте рабочую область с токенами Web Awesome 3.14.0 и зарегистрируйте предоставленные элементы wa-select, wa-option, wa-input, wa-button и wa-switch. Прежде чем считывать начальные значения, дождитесь определения компонентов и выполнения updateComplete. Применяйте --wa-border-radius-scale и --wa-space-scale только к демонстрационной области, а её класс wa-light/wa-dark переключайте, не изменяя остальное содержимое страницы. Синхронизируйте отображаемые значения токенов с нативными элементами управления и сохраните подписи. Используйте рабочую область для изучения компонентов, а не как интерфейс управления устройствами.
05
Источники и область действия дизайн-системы Web Awesome
Публичные компоненты Web Awesome 3.14.0 и тема по умолчанию. Макет выбран самостоятельно; локальное применение имени не создаёт рабочую область и не выделяет хранилище.
