Danila Poyarkov 7ee621ec41

feat: import and export W3C design tokens (#964 )

* feat(core): read and write W3C design tokens

Variables export as DTCG 2025.10 token files, one per collection mode in the shape Figma imports, with text and effect styles as typography and shadow tokens and a resolver document that combines them. OpenPencil's own token fields ride in a dev.openpencil extension, so an export reads back as it was.

Import reads plain mode files, resolver documents, and Tokens Studio themes, plans what it would add, update, or skip against the document without changing it, and applies the plan as one undo step: values merge into variables by name, nothing is deleted, and an updated style updates the layers that use it.

* feat: import and export design tokens from the variables dialog

The stylesheet menu exports the document's variables and styles as a zip of W3C design tokens, and Import design tokens reads token files, folders, or a zip into a dialog that shows where each collection and mode goes, what would be added, updated, or skipped and why, before applying it as one undo step.

* feat: import and export design tokens from tools and the CLI

openpencil tokens --format dtcg --out <folder> writes the token files, design_to_tokens takes the same format, and import_design_tokens imports token files into a document for AI, MCP, and openpencil tool call. The editor and these paths share one apply step behind a target interface: the editor makes each change undoable, a headless document takes them directly.

Re-importing an export changes nothing it does not need to: values that match are left alone, layers that use an updated style are changed only outside instances, where they follow their component, and collections that share a name keep their own files apart.

* perf(core): index token lookups when planning an import

Resolving each reference scanned every token and variable, which made importing a large design system quadratic. A resolver now also finds files picked without their folders by name.

* docs: document design token import and export

* test: type the design token result in the tokens command test

* fix: lay out the design token import dialog as a mapping list

Each collection and mode sits beside the picker for where it goes, in one bordered list, so the pickers no longer read as headings. Skipped tokens use AppCollapsible, file problems AppAlert, and the counts move to the footer.

* fix: keep durations, variable metadata, and style edits through design token import

A duration Figma's format writes in seconds goes back into a variable that holds milliseconds. Tokens without OpenPencil's extension leave an updated variable's unit, scopes, and code syntax as they are. A style token whose value was edited in another tool takes that edit instead of the stale exact fields its extension still carries. Aliases to a repeated collection name resolve within one collection, a collection named Styles no longer collides with the resolver's styles set, and the dialog plans again when the document changes and right before applying. The editor imports the apply step directly rather than the whole format barrel.

* fix: keep effect order and explicit alias targets in design token import

Edited shadows take the places of the shadows they replace, so blurs keep their positions. An alias whose Figma data names a collection that is left out or absent is missing rather than bound to the same path in another collection. The resolver reserves the Styles set name only when there is a styles file.

* perf(cli): print token stylesheets without loading every page

A CSS or Tailwind stylesheet reads only variables, which load with the document, so tokens skips populating and laying out every page as variables already does. On an 85 MB design kit this takes the command from about seven minutes to seconds.

2026-10-08 16:53:46 +00:00

15 KiB

Raw Permalink Blame History

title	description
Переменные	Переменные дизайна, коллекции, режимы и привязка цветов в OpenPencil.

Переменные

Переменные хранят повторно используемые токены дизайна: цвета, интервалы и другие свойства, которые можно привязать к объектам. Если изменить значение переменной, обновятся все объекты, которые её используют.

Открытие диалога переменных

Откройте его через Вид → Переменные…, найдите «Переменные» в палитре команд или, если ничего не выделено, откройте раздел «Переменные» на вкладке «Дизайн». Кнопка Развернуть в углу диалога отдаёт ему большую часть окна.

Слева диалог показывает переменные активной коллекции, справа позволяет редактировать выбранную переменную или коллекцию, а внизу показывает таблицу стилей, которую они образуют. В узком окне или на телефоне он показывает один режим за раз, а переменная, настройки коллекции или таблица стилей открываются поверх списка с кнопкой «Назад».

Коллекции

Переменные объединяются в коллекции. В широком диалоге они перечислены на боковой панели с числом переменных в каждой; в более узком — вкладками, а на телефоне — меню.

Переключить коллекцию: щёлкните её на боковой панели или её вкладку
Создать коллекцию: нажмите + рядом с Коллекции или кнопку с папкой на панели инструментов (Создать коллекцию)
Переименовать или удалить: если переменная не выбрана, справа редактируется коллекция: измените её имя или удалите её через меню ⋯ рядом с именем (Удалить коллекцию)
Атрибут переключения: атрибут, который включает режимы, переключаемые вручную, по умолчанию data-theme для коллекции Theme; укажите другое имя, например data-color-scheme, чтобы оно совпадало с существующим кодом

Режимы

В каждой коллекции может быть несколько режимов (например, Light и Dark). Режимы отображаются в списке столбцами значений, а у переменной есть значение для каждого режима. Управлять ими можно в разделе Настройки коллекции:

Добавить режим: нажмите + рядом с разделом Режимы
Переименовать: измените имя режима
Дублировать, сделать основным, удалить: используйте меню ⋯ рядом с режимом (Дублировать режим, Сделать основным, Удалить режим)

Основной режим — Всегда включён, он попадает в :root. У каждого другого режима есть Применяется, когда: это определяет, когда режим вступает в силу в экспортированной таблице стилей; получающийся CSS показан ниже:

Применяется, когда	CSS
переключено вручную	атрибут переключения коллекции со значением режима, например `[data-theme="dark"]` для режима Dark коллекции Theme
система в тёмном режиме / система в светлом режиме	`@media (prefers-color-scheme: dark)` / `light`
включён высокий контраст	`@media (prefers-contrast: more)`
включено уменьшение движения	`@media (prefers-reduced-motion: reduce)`
экран уже, чем / экран шире, чем ширина	`@media (max-width: 640px)` / `min-width`
контейнер уже, чем / контейнер шире, чем ширина	`@container (max-width: 640px)` / `min-width`
Свой CSS	любой селектор или запрос `@media`, `@supports` либо `@container`

На холсте слой показывает режим, когда вы задали его слою, независимо от условия. В экспортированном коде режим, переключаемый вручную, включается добавлением его атрибута элементу, поэтому слои с этим режимом экспортируются с этим атрибутом. Слои с режимом с любым другим условием, включая собственные селекторы, экспортируются с буквальными значениями вместо токенов, потому что когда режим применяется, решает таблица стилей, а не слой.

Работа с переменными

Переменные группируются по папкам в их именах (Brand/Primary отображается как Primary в папке Brand) и показываются с именем CSS и значением для каждого режима.

Создать переменную: нажмите Создать переменную (или +) и выберите тип; новая переменная откроется для редактирования
Выбрать: щёлкните строку или перемещайтесь стрелками и нажмите Enter. Щелчок с Shift выделяет диапазон, а щелчок с Cmd (Ctrl в Windows и Linux) добавляет строку или убирает её из выделения
Фильтровать: введите текст в строке поиска, чтобы отфильтровать по имени, CSS-имени, описанию или значению, например --color-brand, шестнадцатеричному цвету или переменной, на которую указывает алиас, с той же терпимостью к опечаткам, что и в палитре команд; щёлкните группу на боковой панели, чтобы показать только её и вложенные в неё группы, или нажмите кнопку фильтра (Фильтр по типу), чтобы показать только некоторые типы
Переименовать или изменить на месте: дважды щёлкните имя или числовое или текстовое значение в списке
Правая кнопка мыши: переименовать, дублировать (Дублировать), переместить в группу или в новую группу (Переместить в группу, Новая группа…) либо удалить (Удалить переменные) выбранные переменные; их удаляют также Delete и Backspace
Изменить порядок: перетащите строку; порядок сохраняется в файле
Выбрано несколько: справа их можно переместить в группу, дублировать или удалить
Отмена и повтор: Cmd+Z и Cmd+Shift+Z или Cmd+Y (Ctrl в Windows и Linux) работают в диалоге так же, как на холсте, по одному шагу на изменение. Enter применяет поле и возвращает к списку; пока в поле есть неприменённый текст, Cmd+Z отменяет ввод

При выборе переменной можно редактировать:

Имя и Имя CSS: оставьте имя CSS пустым, чтобы получить его из имени и областей применения, например --color-brand-primary. Вводите имя без --; имя, которое CSS не может использовать, помечается и не сохраняется
Единица: для чисел px, rem, %, ms, s, deg или без единицы; значения вводятся в этой единице
Значение или Значения: по одному для каждого режима; цвет открывает выбор цвета. Кнопка переменной (Использовать переменную) рядом со значением направляет его на другую переменную того же типа — псевдоним, который следует за этой переменной; Открепить переменную возвращает значение, которое он показывал
Выражение CSS: для чисел значение вроде clamp(1rem, 4vw, 1.5rem), которое записывается в CSS вместо числа, а холст продолжает рисовать число
Области применения: для каких свойств предлагается переменная
Описание
Скрыть при публикации: файлы, которые используют этот как библиотеку, не видят переменную

Таблица стилей

Внизу диалога активная коллекция показана как пользовательские свойства CSS. Кнопка копирования (Копировать все переменные как CSS) копирует переменные всего документа как CSS или как тему Tailwind v4 (Копировать все переменные как тему Tailwind), поэтому ссылки на другие коллекции разрешаются.

Импорт и экспорт дизайн-токенов

Переменные и стили переходят между OpenPencil, Figma и кодом как дизайн-токены W3C:

Экспорт: в меню копирования таблицы стилей выберите Экспортировать как дизайн-токены. В zip-архиве по файлу на каждый режим коллекции, который Figma импортирует как режим; стили текста и эффектов как токены типографики и теней; и resolver, который объединяет их для инструментов вроде Style Dictionary
Импорт: нажмите Импортировать дизайн-токены на панели инструментов и выберите файлы токенов или zip. Подходят файлы из Figma, resolver с файлами, на которые он ссылается, и темы Tokens Studio
Куда импортировать: до каких-либо изменений диалог показывает каждую найденную коллекцию и режим и то, куда они попадут: в новую коллекцию или режим, в существующие или никуда. Переменные и стили с тем же именем обновляются, остальное добавляется; ничего не удаляется. Диалог считает, что будет добавлено, обновлено и пропущено, и объясняет, почему пропущен каждый токен
Импорт — один шаг: Отменить возвращает всё обратно

Привязка переменных к заливке

В разделе «Заливка» панели свойств используйте выбор переменной, чтобы привязать цветовую переменную к заливке объекта.

Привязать: выберите цветовую переменную в списке. У заливки появится фиолетовая метка с именем переменной.
Отвязать: нажмите кнопку отвязки на метке, чтобы удалить привязку. Заливка вернётся к вычисленному значению цвета.

Когда значение переменной меняется (или при переключении режима), все привязанные заливки обновляются автоматически.

Советы

Объединяйте связанные токены в коллекции, например Primitives для исходных цветов, Semantic для смысловых псевдонимов и Spacing для значений макета.
Режимы удобны для переключения тем: значения Light и Dark можно задать в одной коллекции.
Переменные поддерживают псевдонимы: коллекция Semantic может ссылаться на значения из коллекции Primitives.
Работа с заливками и выбором цвета описана в разделе Фигуры.

15 KiB Raw Permalink Blame History Unescape Escape