JSON-формат токенов

#Overview

Эта страница описывает JSON-формат token-файлов на вкладке Tokens. Он следует форме DTCG ($value, $type, $extensions, …). Для файлов компонентов ($type: "composition") см. Composition.

Любая нода — это либо токен, либо группа:

#Корень файла

Корень должен быть JSON-объектом (массивы, строки и числа отклоняются валидацией).

{
  "colors": {
    "brand": {
      "primary": {
        "$value": "#635BFF",
        "$type": "color"
      }
    }
  }
}

#Основные поля

#Формы $value

Строка:

{ "$value": "#635BFF", "$type": "color" }
{ "$value": "16px", "$type": "spacing" }
{ "$value": "Inter", "$type": "fontFamily" }

Число / Boolean:

{ "$value": 8, "$type": "number" }
{ "$value": true, "$type": "boolean" }

Чистый алиас — один dot-notation путь внутри {...}:

{ "$value": "{colors.brand.primary}", "$type": "color" }

Математическое выражение (алиас, встроенный в строку):

{ "$value": "{spacing.base} * 2", "$type": "spacing" }
{ "$value": "clamp(16px, {spacing.base} * 4, 64px)", "$type": "sizing" }

Объект / массив (композитные значения):

{
  "$value": { "fontFamily": "Inter", "fontSize": "16px", "fontWeight": 500, "lineHeight": "24px" },
  "$type": "typography"
}

{
  "$value": [{ "type": "DROP_SHADOW", "x": 0, "y": 2, "blur": 8, "spread": 0, "color": "#00000033" }],
  "$type": "shadow"
}

#Типы токенов ($type)

SXL Studio поддерживает 38 канонических типов токенов. Понятнее всего группировать их по тому, во что превращается каждый тип при Export Variables & Styles.

Экспортируются как переменные Figma (17) — скалярные токены, которые становятся переменными в коллекции.

Экспортируются как стили Figma (10) — композитные токены, которые становятся локальными стилями.

Только внутренние / редактируемые (11) — полностью редактируются в SXL Studio и используются логикой плагина или рендером, но напрямую не экспортируются как переменная или стиль: border, strokeStyle, fontStyle, textCase, textDecoration, transition, duration, cubicBezier, template, composition, custom.

Полное поведение по типам: Token types.

#Нормализация $type

Легаси- и множественные значения $type автоматически нормализуются к каноническому ключу.

Экспорты Tokens Studio (легаси value / type / extensions) можно сконвертировать через Migrate from Tokens Studio.

#Резолв типа и inference

$type резолвится в таком порядке:

Если ничего не резолвится, валидация выдаёт ошибку. Когда $type не задан и не унаследован, парсер выводит его из формы $value:

#$extensions

figma.scopes — подсказки scope для экспорта:

{ "$extensions": { "figma.scopes": ["ALL_FILLS", "STROKE_COLOR"] } }

Полный список scope и дефолты по типам — на странице Scopes & Code Syntax.

figma.codeSyntax — сниппеты для Dev Mode. Используйте ключи ровно как показано: Web, Android, iOS.

{
  "$extensions": {
    "figma.codeSyntax": {
      "Web": "var(--color-brand-primary)",
      "Android": "@color/brand_primary",
      "iOS": "Color.brandPrimary"
    }
  }
}

figma.hide — скрыть переменную из публикации:

{ "$extensions": { "figma.hide": true } }

figma.modify — модификаторы цвета:

{ "$extensions": { "figma.modify": { "type": "lighten", "value": 0.2, "space": "oklch" } } }

figma.modify может быть одним объектом или цепочкой-массивом, применяемой по порядку:

{
  "$extensions": {
    "figma.modify": [
      { "type": "lighten", "value": 0.12, "space": "oklch" },
      { "type": "alpha", "value": 0.6 }
    ]
  }
}

Если space опущен, SXL Studio использует oklch. space также принимает алиас $space.

Наследование. $extensions группы наследуются детьми и мержатся поверхностно — ключ ребёнка перекрывает такой же ключ родителя, а непересекающиеся ключи комбинируются.

{
  "brand": {
    "$type": "color",
    "$extensions": { "figma.scopes": ["ALL_FILLS"] },
    "primary": { "$value": "#635BFF" },
    "primary-soft": {
      "$value": "{brand.primary}",
      "$extensions": { "figma.modify": { "type": "alpha", "value": 0.7 } }
    }
  }
}

#Алиасы

Правила: один путь в фигурных скобках, dot-notation для сегментов, без циклических ссылок. Чистый алиас ("{a.b}") трактуется как алиас — не как математика — и его тип резолвится из целевого токена.

#Математические выражения

Строка $value, содержащая оператор или функцию, вычисляется после резолва алиасов.

Математика применяется только к числовым типам токенов: dimension, number, spacing, sizing, borderWidth, borderRadius, opacity, fontSize, lineHeight, letterSpacing, paragraphSpacing, paragraphIndent, duration, blur, backdrop-blur — и к числовым полям внутри композитов (offsets/blur/spread у теней, размеры в typography, тайминги transition). Строковые значения никогда не вычисляются: text-токен "37-37" остаётся литералом "37-37", а не 0.

{ "$value": "{spacing.base} * 4", "$type": "spacing" }
{ "$value": "round({spacing.base} * 1.5, 2)", "$type": "spacing" }

Примечания: round(x, n) округляет до n знаков; rem / em и секунды нормализуются при вычислении; нерезолвнутый алиас или неизвестная функция инвалидируют выражение.

#Валидация

JSON-редактор проверяет:

• синтаксис JSON;
• ошибки парсинга DTCG (нерезолвимый $type; неизвестные значения $type сохраняются как редактируемые opaque-токены custom);
• некорректные фигурные скобки алиасов;
• неизвестные ссылки на токены.

Для файлов composition / template строковые ссылки также проверяются по путям токенов воркспейса, включая локальные встроенные namespace'ы composition-токенов.

#Полный пример

{
  "color": {
    "$type": "color",
    "brand": {
      "primary": {
        "$value": "#635BFF",
        "$description": "Primary brand color",
        "$extensions": {
          "figma.codeSyntax": {
            "Web": "var(--color-brand-primary)",
            "Android": "@color/brand_primary",
            "iOS": "Color.brandPrimary"
          }
        }
      },
      "primary-soft": {
        "$value": "{color.brand.primary}",
        "$extensions": {
          "figma.modify": [
            { "type": "lighten", "value": 0.1, "space": "oklch" },
            { "type": "alpha", "value": 0.65 }
          ]
        }
      }
    }
  },
  "spacing": {
    "$type": "spacing",
    "base": { "$value": "4px" },
    "md": { "$value": "{spacing.base} * 4" }
  }
}

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

• Обзор Tokens
• Token types
• Scopes & Code Syntax
• Migrate from Tokens Studio