IDE Resolver

#Overview

IDE Resolver добавляет IntelliSense для дизайн-токенов в VS Code-совместимых редакторах. В маркетплейсах расширение опубликовано как SXL Resolver, поэтому поиск расширения и команды в Command Palette могут использовать это имя.

• hover для {token.path} в JSON/JSONC;
• hover для var(--token-name) в CSS/SCSS и смежных языках;
• автокомплит CSS custom properties внутри var(--...);
• отображение raw -> resolved значения и цепочки ссылок;
• переход к определению токена;
• поддержка 35+ типов токенов: color, typography, spacing, sizing, dimension, border, shadow, effects, transition, grid и другие;
• CSS-first стратегия резолва: текущий файл -> настроенные CSS sources -> ближайшие CSS/SCSS файлы -> workspace; fallback в JSON используется только если CSS-переменная не найдена;
• для JSON и CSS используется контекстный scope токенов: сначала ближайший token-root относительно текущего файла, затем более дальние.

Для дизайнеров, которые проверяют JSON

Дизайнеры обычно работают с экспортированными DTCG-style JSON/JSONC файлами. Укажите sxlResolver.tokenPaths и наводите курсор на ссылки вида {color.brand.primary} или {spacing.reg.md}, чтобы увидеть итоговое значение и цепочку alias.

Resolver не изменяет token-файлы. Он только читает JSON/JSONC, резолвит ссылки в памяти и показывает preview. Это безопасно для ревью токенов, проверки naming и аудита того, куда реально указывает токен.

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

tokenPaths может содержать пути относительно workspace или абсолютные пути. Для командной настройки лучше использовать относительные пути.

Что увидит разработчик в CSS/SCSS

• При наведении на var(--space-md) в padding — итоговое число с единицей (8px, 12px и т.д.).
• При наведении на var(--font-title) в font — typography-превью и раскладка основных свойств (font-family, font-size, line-height, font-weight).
• Для color, gradient и effects Resolver показывает визуальный preview-блок и итоговое значение.
• При вводе var(--...) — подсказки CSS custom properties из текущего workspace и настроенных package sources.

Если CSS-переменные поставляются из другого пакета, настройте sxlResolver.cssVariableSources. Resolver пройдет по entrypoint imports пакета и проиндексирует только разрешенные файлы, без полного сканирования node_modules.

tokens-manifest.json опционален. Без manifest Resolver все равно читает CSS-переменные, резолвит цепочки var(...) и эвристически выводит широкий тип по CSS-значению. Он не генерирует manifest-файлы и не записывает новые файлы в репозиторий пользователя. Добавляйте manifest только когда нужны точные token metadata для CSS-переменных.

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

• JSON: json, jsonc
• CSS: css, scss, less, sass
• Смежные файлы: typescript, typescriptreact, javascript, javascriptreact, vue, svelte, html

#Установка

VS Code

Найдите расширение SXL Resolver в VS Code Marketplace и установите.

Cursor

Cursor использует OpenVSX-совместимый маркетплейс. Найдите SXL Resolver в панели Extensions Cursor.

Если в поиске пока не появилось из-за кеша маркетплейса, ставьте вручную из VSIX:

1. Command Palette
2. Extensions: Install from VSIX...
3. Выберите .vsix package

#Настройки

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

Настройки Resolver — это настройки IDE, а не runtime-конфиг приложения.

• Используйте .vscode/settings.json в репозитории, если вся команда должна получать одни и те же token/CSS sources. Cursor читает VS Code-compatible workspace settings.
• Используйте .code-workspace файл и кладите настройки в верхнеуровневый "settings", если в одном окне IDE открыто несколько репозиториев.
• Используйте User Settings JSON для личных absolute paths. В VS Code или Cursor откройте Command Palette и выполните Preferences: Open User Settings (JSON).

Для командной настройки лучше коммитить .vscode/settings.json с относительными путями. Абсолютные пути используйте только для личных настроек или локальных multi-repository workspace, которые нельзя описать относительно одного root.

#CSS Sources

Используйте CSS sources, когда приложение потребляет переменные из опубликованного design-system пакета, например @org/design-system-styles, или из сгенерированных CSS-файлов внутри текущего workspace.

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

С manifest или без manifest

Resolver поддерживает оба CSS-режима.

Без manifest укажите только entrypoints или paths. Resolver читает CSS-файлы, проходит относительные @import, резолвит цепочки CSS-переменных и эвристически определяет широкие типы: color, gradient, typography, dimension, duration, number, shadow или text. Он никогда не создает tokens-manifest.json или другие generated files.

С manifest добавьте manifests, если design-system пакет или generated workspace output содержит token metadata. Manifest metadata полезна, когда CSS-значения неоднозначны. Например, 8px может быть spacing, sizing, fontSize, borderRadius или borderWidth; по чистому CSS это нельзя безопасно отличить.

Чтобы сгенерировать tokens-manifest.json, используйте @sxl-studio/token-transformer с output platform: manifest. Если подключаемый design-system пакет уже публикует manifest-файлы, application repositories должны только сослаться на них; запускать Transformer в приложении не нужно.

Manifest metadata может сохранить любой Resolver token type, который отдает ваш token pipeline, включая color, gradient, typography, fontFamily, fontWeight, fontSize, lineHeight, letterSpacing, spacing, sizing, borderRadius, borderWidth, opacity, shadow, boxShadow, blur, effects, grid, transition, duration и composition.

Composite JSON tokens, экспортированные в CSS, показываются как CSS-значение. Если нужен полный breakdown composite object, используйте JSON token files.

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

Замените placeholder package name, entrypoints, manifests и appliesTo globs на значения вашего проекта.

{
  "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/**"]
    }
  ]
}

Поля source

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

1. Локальные CSS-переменные в текущем файле.
2. Подходящие группы из cssVariableSources.
3. Другие просканированные workspace CSS-переменные по близости к текущему файлу.
4. Fallback в JSON token mapping из figma.codeSyntax.Web или kebab-case пути токена.

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

#Команды

Команды установленного расширения используют marketplace-префикс:

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

#Как пользоваться

1. Укажите папки токенов в sxlResolver.tokenPaths.
2. Для CSS-переменных из пакетов или сгенерированных workspace-файлов настройте sxlResolver.cssVariableSources.
3. Откройте JSON/JSONC или CSS/SCSS файл.
4. Наведите курсор на ссылку токена ({...}) или var(--...).
5. Используйте Reveal Token in File для быстрого перехода к источнику.

#Для команды

Рекомендуемый процесс публикации:

1. Публикация в VS Code Marketplace.
2. Публикация в Open VSX.

Только публикация в VS Code Marketplace не гарантирует discoverability в Cursor.