Инициализировать единый источник достоверной информации для токенов и подключить чистый рабочий процесс, управляемый конфигурационным JSON-файлом, чтобы обеспечить согласованность именования на разных платформах. Записывайте токены один раз в репозитории и расширяйте их с помощью цветовых и типографических шкал с помощью style-dictionary-utils.
Внутри репозитория определите строгий набор переменных для цвета, интервалов и типографики. Если вы adding новые токены, поддерживайте четкое правило именования, например, colors.primary, font.body и spacing.grid. Вы можете найти токены в вашем дереве исходного кода и автоматизировать обновления с помощью простого механизма записи, который выводит JSON для веб- и мобильных целей.
Для включения кросс-платформенной темы используйте поток инициализации для импорта базовых токенов, а затем расширяйте их для каждой платформы. Инструмент style-dictionary-utils сопоставляет токены с transforms для форматов платформы, чтобы можно было добавлять платформенно-специфические преобразования без дублирования определений.
Сохраняйте запись configjson минимальной и explicit; объявляйте цвета, типографику и семантику в одном месте, а затем публикуйте результаты через этап сборки. Такой подход помогает командам быстро и безопасно распространять согласованные темы.
Готовы прокачать вашу UI-систему? Ознакомьтесь с репозиторием, изучите соглашения об именовании и начните писать токены, масштабируемые для веб, iOS и Android, с помощью Style Dictionary: Design Tokens для кросс-платформенной темы.
Руководство по установке: Быстрый старт для веб-, iOS- и Android-проектов
Установите Style Dictionary с помощью npm i -D style-dictionary, затем создайте минимальный файл токенов и конфигурацию, охватывающую веб, iOS и Android. Обратите внимание, что конфигурация должна генерировать CSS-переменные для веб, константы Swift для iOS и colors.xml для Android за один проход. Используйте метаданные для аннотирования токенов с указанием источника, примечаний и намерения дизайна; комментарии помогают членам команды просматривать решения, что полезно для аудитов. Поскольку токены могут ссылаться друг на друга, включите транзитивные ссылки и используйте shouldoutputref, чтобы поддерживать согласованность значений на разных платформах. Четко определяйте цветовые палитры colorarray и помечайте токены типом styledictionarycolor, когда это уместно. Используйте экспорты, чтобы предоставлять значения downstream-проектам, и организуйте свои файлы по папкам по платформе и типу, чтобы члены команды могли быстро найти то, что им нужно. Начните с playground для предварительного просмотра значений и основывайте типографику на 1rem, чтобы поддерживать согласованный размер на всех выходах.
Web quick start: add a platforms.web section to sd.config.json and emit a tokens.css file at build/web/tokens.css. Map color tokens to CSS custom properties like --color-primary and --color-neutral-900, applying a normal naming scheme that mirrors the token path (e.g., color.primary, color.gray.900). For web, keep the CSS output lightweight, and expose a reference to color tokens so design decisions remain traceable via metadata. If you plan to reuse colors in UI frameworks, consider exporting a JS module as part of the same run to simplify integration, and use the styledictionarybuildallplatforms script alias to test end-to-end across all targets.
iOS quick start: configure the ios platform to generate a Swift file (Colors.swift or Tokens.swift) containing a struct with static constants for each color token. Example: static let colorPrimary = UIColor(named: "color_primary") or a direct hex initializer. Leverage transitive token references to keep palettes aligned, and mark values with styledictionarycolor for clarity in the playground. Ensure the output aligns with normal iOS color handling and includes a note in metadata to explain the design rationale. This approach keeps what users see consistent with the design system while simplifying code reviews and theming experiments.
Быстрый старт Android: настройка платформы Android для вывода colors.xml с записями наподобие
| Step | Команда / Вывод |
|---|---|
| 1. Install | npm i -D style-dictionary |
| 2. Подготовить токены | Create tokens/colors.json (or colors.yaml) with entries like "color": { "primary": { "value": "#FF3B30" } }; add comments to explain usage and set type to styledictionarycolor where applicable |
| 3. Настройте | sd.config.json с платформами platforms.web, platforms.ios, platforms.android; определить buildPath и выходные файлы для каждой целевой платформы; включить транзитивные зависимости |
| 4. Постройте | npx style-dictionary build; или npm run styledictionarybuildallplatforms, если вы добавили псевдоним скрипта |
| 5. Проверить результаты | Web: build/web/tokens.css; iOS: build/ios/Colors.swift; Android: build/android/colors.xml; проверьте соответствие цветов и метаданных |
Токенизация: наименование, области видимости и особенности платформы
Начните с принятия платформенно-зависимого наименования: префиксируйте токены платформой и областью, чтобы поддерживать согласованность кросс-платформенной тематики. Используйте единую карту ссылок и поддерживайте упрощенный вывод для каждой платформы, поскольку четкая схема наименования уменьшает расхождение по мере развития форматов. Этот подход упростит интеграцию и опирается на build-tokensjs для управления конвейером в проектах.
Называйте токены стабильным, читаемым шаблоном: включайте базовые токены, такие как цвет, размер и типографика; используйте sizefontbase в качестве канонического базового токена шрифта. Объедините категорию, роль токена и суффикс платформы (например, button.size или text.color), чтобы одно и то же имя токена могло четко преобразовываться при переключении форматов. Это означает, что вы можете импортировать единый источник достоверной информации и вывод на каждую платформу становится простым.
Четко определите области видимости: глобальные параметры управляют системными значениями по умолчанию; компоненты охватывают элементы пользовательского интерфейса; темы соответствуют палитрам; определите переопределения для каждой платформы в области видимости платформы (web, ios, android). Выровненная структура помогает при генерации ссылок для кода, обеспечивая возможность чтения ссылками инструментами без разбора вложенных деревьев. Используйте фильтрацию для отсечения неиспользуемых токенов и поддержания компактности поверхности, а затем документируйте ссылки в центральном файле ссылок для дизайнеров и разработчиков.
Форматы и инструменты: выбирайте форматы, соответствующие вашей фреймворк и среде сборки. Для кроссплатформенной темы javascriptesm модули поддерживают tree-shaking и легкий импорт в веб-приложения и нативные оболочки. Вывод одних и тех же токенов в несколько форматов – json, style dictionary и css переменных – снижает трение при интеграции. Варианты включают выходные данные для каждой платформы, частичные сборки и grunt-управляемый watch, который перестраивает при изменении. Инструментарий должен поддерживать согласованность стилевых токенов во всех платформах, при этом позволяя переопределения, специфичные для платформы.
Практики работы со средой выполнения: определяйте токены со стабильными именами, поддерживайте выровненную карту ссылок и используйте фильтрацию, чтобы избежать утечки особенностей, специфичных для платформы. Генерируйте артефакты с помощью build-tokensjs, а затем используйте их через потоки javascriptesm в вашем приложении. Поскольку карта имеет хорошо структурированный формат, команды могут добавлять новые форматы без нарушения существующих интеграций, экономя время и уменьшая количество ошибок.
Создание основных токенов: Цвета, Типографика, Интервалы и Тени
Определите основные токены сейчас: Цвета, Типографика, Интервалы и Тени как единый источник истины и опубликуйте их на каждой платформе.
Цвета определяют цветовую базу graydark, с токенами для нейтральных и акцентных цветов. Храните их в nsarray для быстрого поиска и присвойте каждому подписанное шестнадцатеричное значение. Система использует uicolor для iOS и генерирует CSS-переменные для веб, с полем комментария, описывающим использование. Она предоставит варианты для светлой и темной тем и возвращает цветовые значения в шестнадцатеричном, rgba или упакованном целочисленном формате. Спецификация говорит разработчикам, как сопоставлять токены.
Типографические токены определяют семейства шрифтов, начертания, размеры и высоту строки с использованием глубокой шкалы размеров. Функция с именем dimensionpixeltorem преобразует метрики в пикселях в значения, основанные на rem. Инструменты nodejs потребляют стартовые шаблоны и генерируют определения типографики, работающие на разных платформах, а также блоки комментариев, описывающие использование.
Интервалы используют глубокую шкалу размеров для полей, отступов и промежутков: 4, 8, 12, 16, 24, 32, 48. Токены интервалов поступают в transformgroup, который формирует блоки макета. Из этого единственного источника вы генерируете интервалы для каждого компонента через шаблоны.
Тени кодируют глубину с помощью знаковых смещений, радиусов размытия и цвета, полученного из colorbasegraydark. Каждый токен тени сопоставляется с уровнем высоты и использует цвет, взятый из базового серого. Пайплайн возвращает значения CSS box-shadow и платформо-специфичные представления для uicolor на iOS. Добавьте комментарий для использования и предоставьте опции для наложения теней на элементы.
Чтобы реализовать это на практике, создайте стартовый JSON, который определяет цвета, типографику, интервалы и тени. Инструментарий будет вызывать трансформатор для создания CSS-переменных, значений UIColor Swift/ObjC и стилей Android. На основе JSON скрипт Node.js возвращает набор артефактов.
Применяйте этот подход и связывайте его с шаблонами в вашей дизайн-системе; результат – согласованная отправная точка, которая развивается вместе с вашим продуктом и доказала свою эффективность в упрощении обновлений. Это стабилизировало бы оформление (theming) в командах.
Миграция устаревших токенов: стратегия сопоставления и распространенные подводные камни
Экспортируйте ваши устаревшие токены в configjson и сопоставьте их с formatsscssvariables для немедленной кроссплатформенной разработки тем.
Рассматривайте font_dimensxml как базовую линию типографики: получайте размеры шрифтов, высоту строк, толщину шрифтов и псевдонимы семейств в базовой группе токенов, питающую HTML и компоненты фреймворка.
Настройте рабочий процесс сопоставления, который выводит два артефакта: токены, готовые для HTML, и typescriptesm-декларации, с выделенным проектом для проверки результатов. Затем выполните проверку CI с использованием yarn и небольшой демонстрационной страницы.
Стратегия определения соответствий
Определите категории источников: цвет, типографика, интервалы и заголовки; сохраняйте заголовки узкоспециализированными, чтобы сохранить семантическое наименование на разных платформах.
Выровнять наименование между configjson и целевыми результатами: formatsscssvariables для CSS и TS-интерфейс для javascriptesm и typescriptesm-declarations. Используйте styledictionaryregistertransform для принудительного соблюдения наименования и подключите его к yarn-скриптам, чтобы вы могли запустить преобразование в обоих режимах из корневого проекта. Рассматривая следующие шаги: 1) нормализовать наименование, 2) сгенерировать результаты, 3) протестировать на небольшом примере страницы. Рассмотреть различные категории и найти пробелы; не пропускать ни один шаг и избегать процесса, который кажется догадкой.
Ищите пересечения и обеспечьте единый источник истины; указывайте каждый токен на его происхождение в font_dimens.xml или определениях цветов, чтобы избежать расхождения на разных платформах. вниз и обеспечьте согласованность во всём.
Общие подводные камни
Отсутствующие токены в целевом формате вызывают разрывы во время выполнения; убедитесь, что font_dimensxml, заголовки и цветовые токены существуют как в configjson, так и в formatsscssvariables перед выпуском.
Несогласованные масштабы нарушают оформление; фиксируйте масштабы типографики и цветовые шкалы на базовом уровне и распространяйте эти решения через последующие токены.
Чрезмерная автоматизация без проверки приглашает регрессии; поддерживайте страницу тестирования на уровне проекта для рендеринга токенов и подтверждения соответствия отображения ожиданиям фреймворка.
Создание, проверка и предварительный просмотр: CLI, конфигурации и визуальный QA
Запустите yarn build-tokensjs в корне проекта, чтобы сгенерировать единый файл в следующей директории: tokens/outputting. CLI читает из вашей конфигурации и записывает статическую карту токенов, которую вы можете повторно использовать на разных платформах.
Load the config with the option --config path/to/config.json to keep the build deterministic and open the door for consistent results across teams.
- Build: От корня команда проходит по файловому дереву через структуру каталогов, чтобы группировать токены по области видимости; она создает плоский, статический JSON-файл и записывает ресурсы в tokens/outputting. Сборка поддерживает scssmap-deep для создания глубокой карты SCSS и ссылается на токены, такие как bodythemedark и styledictionarycolorh в цветовых группах.
- Проверка: Выполните этап проверки, который проверяет обязательные поля, имена токенов и существование пути; когда группа токенов отсутствует, инструмент сообщает об отсутствующем пути, и вы можете исправить его до повторного запуска. Это гарантирует, что файл соответствует конфигурации и предполагаемой структуре.
- Предварительный просмотр: Откройте страницу визуального контроля качества, которая отображает токены в виде образцов и CSS-переменных; статический предварительный просмотр читает вывод и отображает токены в сценарии, который вы добавляете, чтобы вы могли подтвердить контраст, группировку и типографику в простом пользовательском интерфейсе. Используйте предоставленный путь, чтобы открыть предварительный просмотр по адресу http://localhost:8080/preview.
Заметка об автоматизации: используйте легковесный рабочий процесс, который вызывает build-tokensjs, затем выполняет отдельную проверку, а затем генерирует предварительный просмотр; вы можете добавить дополнительные токены, такие как buildts, и описать, как каждый токен сопоставляется с компонентом пользовательского интерфейса, например, bodythemedark или styledictionarycolorh.
Стратегии оформления: светлая/темная тема, переключение тем и переопределения во время выполнения
Начните с единственного источника истины: реализуйте светлые и темные токены как переменные CSS и сделайте их доступными через атрибут data-theme на корневом элементе. Используйте variablesscss для привязки токенов к переменным и соедините их с вашим токеном mystyledictionary styledictionarycolorkt для цветовых значений.
Структурируйте данные в репозитории с использованием шаблонов для файлов токенов и глобов, которые собирают данные в разных форматах. Поддерживайте глубокую карту токенов и scssmap-deep, которая отражает иерархию, чтобы компоненты могли получать токены цвета, типографики и интервалов без жесткого кодирования значений. Включайте метаданные и флаг showfileheader, чтобы документировать изменения, и сохраняйте основные токены на месте, чтобы макет оставался предсказуемым с течением времени. Настройка отдает предпочтение выводу, удобному для HTML, сохраняя при этом языковую нейтральность в модели данных.
Theme switching proceeds with a small, fast script that toggles the root data-theme attribute, then reflows only the affected styles. Respect OS preferences by reading matchMedia('(prefers-color-scheme: dark)'), and provide a user-facing option in templates to store the choice in localStorage so the setting survives reloads.
Переопределения времени выполнения позволяют расширить набор токенов на уровне компонента, не изменяя базовую тему. Используйте атрибуты data- или переопределения встроенных CSS-переменных, чтобы указать на другую палитру для диалога, карточки или модального окна. При переопределении расширяйте существующие токены вместо замены их, чтобы сохранить исходные токены mystyledictionary нетронутыми и просто переопределять значения в точке использования.
Примечания по реализации
В конфигурации проекта включите метаданные, храните отображение scssmap-deep и используйте showfileheader для аннотирования изменений. Поддерживайте единый источник достоверной информации для слоя данных и поддерживайте соответствие выходного html-кода слою CSS. Используйте четкий шаблон именования и минимальный набор шаблонов, чтобы уменьшить расхождения между платформами и масштабом, и убедитесь, что репозиторий поставляется с готовым к запуску примером, демонстрирующим, как связать html, переменные CSS и данные токенов.
