SXL Resolver (VS Code)

SXL Resolver добавляет IntelliSense для дизайн-токенов в VS Code и Cursor. Расширение читает JSON/JSONC-файлы токенов и CSS custom properties и показывает итоговое значение, визуальное превью и цепочку alias прямо в редакторе. Оно только читает: файлы токенов не изменяются, в репозиторий ничего не записывается.

Текущая версия: 2.3.4. Нужен VS Code 1.85 или новее. Cursor поддерживается через его реестр, совместимый с Open VSX.

#Установка

VS Code

1. Откройте Extensions (Cmd+Shift+X на macOS, Ctrl+Shift+X на Windows и Linux).
2. Найдите SXL Resolver и нажмите Install.

Cursor

1. Откройте Extensions в Cursor и найдите SXL Resolver.
2. Если свежая версия ещё не предлагается, откройте страницу расширения на Open VSX и скачайте .vsix нужной версии. Зеркала реестра могут отставать от Open VSX.
3. Выполните команду и выберите скачанный файл:

Extensions: Install from VSIX...

#Где работает

Multi-root workspace поддерживается.

#Файлы токенов

1. Перечислите папки с токенами в sxlResolver.tokenPaths в настройках workspace (.vscode/settings.json).
2. Откройте JSON- или JSONC-файл из этих папок и наведите курсор на ссылку вида {color.brand.primary} или {spacing.reg.md}.

{
  "sxlResolver.tokenPaths": [
    "tokens",
    "packages/design-system/tokens"
  ]
}

Пути задаются относительно корня workspace или абсолютно. В командных настройках используйте относительные пути. Несколько папок объединяются в один набор токенов. Файлы, где type, value и extensions записаны без $, тоже распознаются (sxlResolver.allowNoDollar).

#Подсказка при наведении

Наведите курсор на ссылку токена. Часть Result показывает итоговое значение, часть Source показывает цепочку alias от ссылки до базового токена с файлом, в котором лежит каждый токен. Имена токенов в Source кликабельны: клик открывает файл на определении.

Цветовой токен в файле композиции: образец цвета, итоговый HEX и цепочка от токена компонента до orange.500 в core.json.

Составные токены раскрываются по свойствам.

Токен типографики: в Result каждое свойство с его значением, в Source цепочка alias для каждого свойства.

Тень из двух слоёв: x, y, blur, spread и цвет каждого слоя.

Глубину цепочки ограничивает sxlResolver.maxChainLength (по умолчанию 5). Иконки типов отключаются через sxlResolver.showIcons.

Поддерживаемые типы токенов: цвета, градиенты и заливки; типографика и её части (семейство, начертание, размер, межстрочный интервал, трекинг, отступ и красная строка абзаца, регистр и оформление текста); тени, размытия, backdrop blur, стекло и эффекты; dimension, sizing и spacing; радиусы, толщины, обводки и стили обводки; прозрачность, числа, строки и булевы значения; grid; переходы, длительности и кривые cubic-bezier; шаблоны и композиции.

#Автодополнение

Ввод {orange. в JSON-файле: подходящие токены с иконками типов и подсказка для выделенного пункта.

• В JSON список открывается после { и фильтруется по пути токена.
• В CSS и файлах компонентов при вводе var(-- предлагаются custom properties из текущего workspace и из настроенных источников.
• Размер списка ограничивает sxlResolver.maxSuggestions (по умолчанию 300).

#Переход к определению

Наведение на {w-button.size.sm.height} в файле композиции, клик по первой ссылке в Source, и редактор открывает components/WButton.json на токене height.

• Ctrl+Click (Cmd+Click на macOS) или Go to Definition на {token.path} либо var(--name) открывает файл с определением.
• Ссылки в части Source подсказки делают то же самое через команду SXL Resolver: Reveal Token in File.

#CSS-переменные

По умолчанию Resolver сканирует CSS, SCSS, Less и Sass открытого workspace и пропускает node_modules, .git, dist и build. Наведите курсор на var(--space-md) в padding, чтобы увидеть итоговое значение, например 8px. Наведите на var(--font-title), чтобы получить превью типографики с font-family, font-size, line-height и font-weight. Для цветов, градиентов и эффектов показывается визуальное превью.

Если переменные приходят из опубликованного пакета дизайн-системы или из сгенерированного CSS в другой папке, добавьте их в sxlResolver.cssVariableSources. Resolver проходит по entrypoint-файлам пакета и их относительным @import и индексирует только эти файлы. Не указывайте весь node_modules: это медленно, может проиндексировать несколько версий одного пакета и смешать переменные разных продуктов или тем.

#Из опубликованного пакета

Замените имя пакета, entrypoints, manifests и глобы appliesTo на значения своего проекта. Поле manifests необязательно, см. раздел «Манифест» ниже.

{
  "sxlResolver.cssVariableSources": [
    {
      "name": "Commerce app styles",
      "package": "@org/design-system-styles",
      "entrypoints": ["commerce/index.css", "components/index.css"],
      "manifests": ["commerce/tokens-manifest.json"],
      "appliesTo": ["apps/storefront/**", "packages/storefront-ui/**"]
    },
    {
      "name": "Operations app styles",
      "package": "@org/design-system-styles",
      "entrypoints": ["operations/index.css", "components/index.css"],
      "manifests": ["operations/tokens-manifest.json"],
      "appliesTo": ["apps/operations/**", "packages/operations-ui/**"]
    }
  ]
}

#Из текущего workspace

Используйте paths, если CSS-файлы лежат в текущем репозитории или нужен абсолютный локальный путь.

{
  "sxlResolver.cssVariableSources": [
    {
      "name": "Local design-system styles",
      "paths": [
        "packages/design-system/styles/commerce/index.css",
        "packages/design-system/styles/components/index.css"
      ],
      "manifests": [
        "packages/design-system/styles/commerce/tokens-manifest.json"
      ],
      "appliesTo": ["apps/storefront/**", "packages/storefront-ui/**"]
    }
  ]
}

Источник можно задать и просто строкой: путь к CSS-файлу или папке относительно workspace либо абсолютный.

#Поля источника

#Приоритет резолва

При наведении или автодополнении var(--token-name) Resolver ищет в таком порядке:

1. CSS-переменные, объявленные в текущем файле.
2. Подходящие группы из cssVariableSources.
3. Остальные просканированные CSS-переменные workspace, сначала ближайшие к текущему файлу.
4. JSON-токен, у которого Code Syntax Web или kebab-case путь совпадает с именем переменной.

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

#Манифест

tokens-manifest.json необязателен.

Без манифеста Resolver читает CSS-файлы, проходит цепочки var(...) и определяет широкий тип по значению: color, gradient, typography, dimension, duration, number, shadow или text.

С манифестом сохраняются исходные типы токенов. Это важно, когда CSS-значение неоднозначно: 8px может быть spacing, sizing, fontSize, borderRadius или borderWidth, и по одному CSS их не различить. Добавьте файлы манифеста в поле manifests группы источников.

Манифест создаёт Transformer с платформой manifest. Если пакет дизайн-системы уже поставляет манифесты, просто сошлитесь на них: запускать Transformer в репозитории приложения не нужно. Сам Resolver никогда не создаёт манифесты и другие файлы.

Составные токены, экспортированные в CSS, показываются как CSS-значение. Полную раскладку по свойствам смотрите в JSON-файлах токенов.

#Настройки

#Где хранить настройки

Настройки Resolver относятся к редактору, а не к конфигурации приложения.

• .vscode/settings.json в репозитории, если вся команда должна использовать одни и те же источники токенов и CSS. Cursor читает workspace-настройки в формате VS Code.
• Файл .code-workspace, ключ "settings" верхнего уровня, если в одном окне открыто несколько репозиториев.
• User Settings JSON для личных абсолютных путей. Открывается командой:

Preferences: Open User Settings (JSON)

Коммитьте относительные пути. Абсолютные пути держите только в личных настройках.

#Команды

SXL Resolver: Force Refresh Tokens
SXL Resolver: Reveal Token in File

Force Refresh Tokens перечитывает все файлы токенов и CSS-переменные; кнопка Refresh Tokens в строке состояния делает то же самое. Reveal Token in File открывает файл токена; её используют ссылки в подсказке.

#Если что-то не работает

#Приватность

SXL Resolver работает локально в редакторе. Он читает файлы токенов и CSS из открытого workspace и настроенных источников и не отправляет файлы токенов или значения CSS во внешние сервисы.

#Связанные страницы

• Transformer
• Токены в код
• Scopes и Code Syntax
• Storybook Addon