SXL Studio
Tokens

Scopes и Code Syntax

Где переменная предлагается в Figma и как она называется в Dev Mode: секции Scopes и Code Syntax в форме токена, поле $extensions в JSON, допустимые scopes по видам переменных, шаблоны code syntax и наследование.

Две настройки переменной задаются в форме токена и хранятся в $extensions:

НастройкаУправляет
Scopes (figma.scopes)В каких полях Figma предлагается переменная
Code Syntax (figma.codeSyntax)Как переменная называется в Dev Mode для платформ Web, Android и iOS

Обе необязательны и действуют только на типы, которые экспортируются переменными. У стилей и внутренних типов таких секций нет. В Figma эти настройки записываются, когда в окне Export to Figma включён переключатель Apply codeSyntax & scopes, по умолчанию он включён.

JSON
{
  "color": {
    "brand": {
      "$type": "color",
      "$value": "#635BFF",
      "$extensions": {
        "figma.scopes": ["ALL_FILLS", "STROKE_COLOR"],
        "figma.codeSyntax": { "Web": "var(--color-brand)", "iOS": "Color.brand" }
      }
    }
  }
}

Где настраивать

  • В форме создания или редактирования токена: секции Scopes и Code Syntax.
  • Для многих токенов сразу: в таблице коллекции выделите строки и выберите Edit token fields… в контекстном меню, там те же Scopes и поля Code Syntax для Web, iOS и Android. Пункт Inherit from group… возвращает наследование от группы. См. Коллекции.
  • В JSON: поле $extensions у токена или у группы.

Scopes

Scope ограничивает, в каких полях Figma предлагается переменная. Набор допустимых scopes зависит от вида переменной, в который экспортируется тип токена.

Вид переменнойТипы токенов
Colorcolor
Numberopacity, dimension, number, spacing, sizing, borderWidth, borderRadius, fontSize, lineHeight, letterSpacing, paragraphSpacing, paragraphIndent
StringfontFamily, fontWeight, text
Booleanboolean
Timingduration
EasingcubicBezier, easing

Допустимые scopes по видам

Другие значения редактор считает ошибкой и не записывает в Figma.

ВидДопустимые figma.scopes
ColorALL_SCOPES, ALL_FILLS, FRAME_FILL, SHAPE_FILL, TEXT_FILL, STROKE_COLOR, EFFECT_COLOR
NumberALL_SCOPES, TEXT_CONTENT, CORNER_RADIUS, WIDTH_HEIGHT, GAP, STROKE_FLOAT, EFFECT_FLOAT, OPACITY, FONT_SIZE, LINE_HEIGHT, LETTER_SPACING, PARAGRAPH_SPACING, PARAGRAPH_INDENT, FONT_WEIGHT
StringALL_SCOPES, TEXT_CONTENT, FONT_FAMILY, FONT_STYLE
Boolean, Timing, EasingScopes не поддерживаются, поле должно отсутствовать или быть пустым

ALL_SCOPES означает «везде» и не сочетается с другими значениями. Для fontWeight допустим только FONT_STYLE: Figma хранит начертание строкой, поэтому scope FONT_WEIGHT для него не подходит и вызывает ошибку валидации файла.

Scopes по умолчанию

Если figma.scopes не задан, плагин ставит scope по типу. Типы-переменные, которых нет в таблице, получают ALL_SCOPES.

$typeScope по умолчанию
colorALL_FILLS, STROKE_COLOR, EFFECT_COLOR
sizingWIDTH_HEIGHT
spacingGAP
borderRadiusCORNER_RADIUS
borderWidthSTROKE_FLOAT
opacityOPACITY
fontFamilyFONT_FAMILY
fontWeightFONT_STYLE
fontSizeFONT_SIZE
lineHeightLINE_HEIGHT
letterSpacingLETTER_SPACING
paragraphSpacingPARAGRAPH_SPACING
paragraphIndentPARAGRAPH_INDENT
dimension, number, textALL_SCOPES
JSON
{
  "spacing": {
    "$type": "spacing",
    "md": { "$value": "16px", "$extensions": { "figma.scopes": ["GAP", "WIDTH_HEIGHT"] } }
  }
}

Code Syntax

figma.codeSyntax задаёт строку, которую Dev Mode показывает рядом с переменной, отдельно для каждой платформы. Все ключи необязательны.

КлючПлатформаПример
WebCSS, SCSS, Lessvar(--color-brand), $color-brand
AndroidKotlin, XMLColorBrand, @color/brand
iOSSwift, SwiftUIColor.brand, UIColor.brand
JSON
{
  "$extensions": {
    "figma.codeSyntax": { "Web": "var(--color-brand)", "Android": "@color/brand", "iOS": "Color.brand" }
  }
}

Шаблоны

Вместо имени для каждого токена задайте шаблон: плагин соберёт имя из пути токена.

ШаблонРезультат для color.brand.primary
{var(--css-variable)}var(--color-brand-primary)
{$sass-variable}$color-brand-primary
{@less-variable}@color-brand-primary
{UpperCamelCase}ColorBrandPrimary
{lowerCamelCase}colorBrandPrimary
{UPPER_SNAKE_CASE}COLOR_BRAND_PRIMARY
{lower_snake_case}color_brand_primary
JSON
{
  "$extensions": {
    "figma.codeSyntax": { "Web": "{var(--css-variable)}", "Android": "{UpperCamelCase}", "iOS": "{lowerCamelCase}" }
  }
}

Путь разбивается на слова по разделителям /, . и _, а шаблон складывает слова в своём стиле.

Наследование

Задайте $extensions у группы, и каждый токен внутри его унаследует. Токен может переопределить отдельный ключ, остальные ключи объединяются.

JSON
{
  "color": {
    "$type": "color",
    "$extensions": { "figma.scopes": ["ALL_FILLS", "STROKE_COLOR"] },
    "brand": { "$value": "#635BFF" },
    "brand-strong": {
      "$value": "{color.brand}",
      "$extensions": { "figma.scopes": ["STROKE_COLOR"] }
    }
  }
}

В подсказке бейджа токена видно, что настройки унаследованы от группы.

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

JSON
{
  "color": {
    "$type": "color",
    "$extensions": { "figma.scopes": ["ALL_FILLS", "STROKE_COLOR"], "figma.codeSyntax": { "Web": "{var(--css-variable)}" } },
    "brand": {
      "primary": { "$value": "#635BFF" },
      "on-primary": { "$value": "#FFFFFF", "$extensions": { "figma.scopes": ["TEXT_FILL"] } }
    }
  },
  "radius": {
    "$type": "borderRadius",
    "md": { "$value": "8px", "$extensions": { "figma.scopes": ["CORNER_RADIUS"] } }
  }
}

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