Designové tokeny jsou sdílenou slovní zásobou mezi designéry a vývojáři. Existují v různých podobách od éry Salesforce Lightning — Style Dictionary, Theo, návrh specifikace W3C Design Token Community Group. Co se v poslední době změnilo, je to, že jsou nyní také sdílenou slovní zásobou mezi vaším kódem a AI kódovacími agenty.

Agent, který zná color.accent = #d96a3a, použije tuto hodnotu. Agent, který dostane screenshot, odhadne „teplá oranžová" a vyprodukuje něco blízkého, ale špatného. Rozdíl se znásobuje přes desítky komponent.

figmascope exportuje tokens.json jako součást každého kontextového balíčku. Tento článek podrobně vysvětluje formát, jak figmascope získává tokeny z Figmy, záložní odvozování ze četnosti pro soubory bez Figma Variables, a jak propojit výstup s běžnými frameworky. Chcete-li vidět, jak tokeny zapadají do celkového pracovního postupu exportu, navštivte aplikaci figmascope nebo si přečtěte Figma do Cursor a Figma do Claude Code.

Formát tokens.json

figmascope používá formát inspirovaný W3C Design Token Community Group. Každý token je objekt s poli $value a $type, vnořený pod sémantické klíče kategorií:

{
  "color": {
    "surface":      { "$value": "#f6f2ea", "$type": "color" },
    "surface-2":    { "$value": "#efe9dc", "$type": "color" },
    "ink":          { "$value": "#1f1d1a", "$type": "color" },
    "ink-muted":    { "$value": "#4a4641", "$type": "color" },
    "accent":       { "$value": "#d96a3a", "$type": "color" },
    "accent-soft":  { "$value": "#f2c7a8", "$type": "color" },
    "good":         { "$value": "#6a8f5a", "$type": "color" },
    "warn":         { "$value": "#c89a3a", "$type": "color" },
    "bad":          { "$value": "#b8553a", "$type": "color" }
  },
  "spacing": {
    "1":  { "$value": "4px",   "$type": "dimension" },
    "2":  { "$value": "8px",   "$type": "dimension" },
    "3":  { "$value": "12px",  "$type": "dimension" },
    "4":  { "$value": "16px",  "$type": "dimension" },
    "6":  { "$value": "24px",  "$type": "dimension" },
    "8":  { "$value": "32px",  "$type": "dimension" },
    "12": { "$value": "48px",  "$type": "dimension" },
    "16": { "$value": "64px",  "$type": "dimension" }
  },
  "radius": {
    "sm":   { "$value": "4px",  "$type": "dimension" },
    "md":   { "$value": "8px",  "$type": "dimension" },
    "lg":   { "$value": "16px", "$type": "dimension" },
    "full": { "$value": "9999px", "$type": "dimension" }
  },
  "typography": {
    "body": {
      "fontFamily": { "$value": "Inter",  "$type": "fontFamily" },
      "fontSize":   { "$value": "14px",   "$type": "dimension" },
      "fontWeight": { "$value": 400,       "$type": "number" },
      "lineHeight": { "$value": 1.45,     "$type": "number" }
    },
    "heading": {
      "sm": {
        "fontFamily": { "$value": "Inter",  "$type": "fontFamily" },
        "fontSize":   { "$value": "18px",   "$type": "dimension" },
        "fontWeight": { "$value": 600,       "$type": "number" },
        "lineHeight": { "$value": 1.25,     "$type": "number" }
      }
    },
    "mono": {
      "fontFamily": { "$value": "JetBrains Mono", "$type": "fontFamily" },
      "fontSize":   { "$value": "13px",   "$type": "dimension" },
      "fontWeight": { "$value": 400,       "$type": "number" }
    }
  }
}

Proč W3C-ish a ne přesně specifikace?

Specifikace W3C Design Token Community Group je stále návrhem. figmascope se řídí základními konvencemi ($value, $type, vnořené skupiny), ale neimplementuje všechny okrajové případy jako složené typy a řetězce rozlišování aliasů. Výstup je dostatečně stabilní, aby ho mohl konzumovat Style Dictionary, přímé procházení JSON nebo jazykový model — který je primárním konzumentem.

Používané typy tokenů

$type Kategorie Formát $value Příklad
color barva hex řetězec "#d96a3a"
dimension rozestupy, poloměr CSS řetězec s jednotkou "16px"
fontFamily typografie název písma "Inter"
number typografie číslo bez jednotky 400, 1.45

Barvy jsou vždy exportovány jako hex řetězce. Pokud zdroj ve Figmě používá RGBA s neúplnou průhledností, alfa kanál je zachován v 8místném hexu (#d96a3a80).

Jak figmascope získává tokeny

figmascope používá dvouúrovňovou strategii získávání. Figma Variables jsou preferovaným zdrojem; odvozování ze četnosti je záložní možností.

Úroveň 1: Figma Variables

Pokud má soubor Figma definované Variables (nativní systém tokenů ve Figmě, dostupný na plánech Professional a Organization), figmascope je čte prostřednictvím endpointu /v1/files/:key/variables/local REST API. Názvy proměnných jsou použity jako klíče tokenů, sanitizovány do kebab-case. Módy jsou zredukovány na výchozí mód, pokud soubor nemá jediný mód, v takovém případě jsou přímo použity hodnoty tohoto módu.

Kolekce proměnných se mapují na klíče nejvyšší úrovně kategorií v tokens.json. Kolekce nazvaná "Color" vytváří tokens.color.*; "Spacing" vytváří tokens.spacing.*. Pokud váš soubor Figma používá nestandardní názvy kolekcí, figmascope se pokusí odvodit kategorii z rozlišeného typu proměnné.

Úroveň 2: Odvozování ze četnosti

Mnoho souborů Figma — zejména starší nebo soubory od klientů, kteří nepřijali Variables — nemá žádné definice proměnných. figmascope to řeší procházením celého stromu uzlů a sestavováním histogramů četností barev výplní, hodnot rozestupů, poloměrů rohů a vlastností typografie.

Hodnoty vyskytující se nad prahem četnosti se stávají kandidáty na tokeny. Jsou pojmenovány podle kategorie a pořadového indexu (color.0, color.1...), pokud nelze odvodit čitelný název z toho, jak je hodnota použita (např. barva použitá pouze na pozadích napříč více rámci se stane color.surface).

Manifest _meta.json zaznamenává tokensSource buď jako "variables" nebo "inferred", takže vaše výzva pro agenta může poznamenat, kdy bylo použito odvozování:

// _meta.json — záložní odvozování
{
  "tokensSource": "inferred",
  "warnings": [
    {
      "code": "tokens-inferred",
      "message": "No Figma Variables found. Tokens were inferred from usage frequency."
    }
  ]
}

Odvozené tokeny jsou užitečné, ale ne autoritativní. Považujte je za výchozí bod, ne za specifikaci designového systému.

Reference tokenů v layout IR

Soubory IR pro jednotlivé obrazovky (screens/*.json) odkazují na tokeny cestou pomocí řetězců $ref místo vkládání surových hodnot. Tím je IR kompaktní a zajišťuje, že agent vždy rozlišuje hodnoty z jediného zdroje pravdy:

{
  "kind": "stack",
  "name": "PrimaryButton",
  "direction": "horizontal",
  "gap": { "$ref": "spacing.2" },
  "padding": {
    "top": 10, "right": 16, "bottom": 10, "left": 16
  },
  "background": { "$ref": "color.accent" },
  "radius": { "$ref": "radius.sm" },
  "children": [
    {
      "kind": "leaf",
      "name": "ButtonLabel",
      "type": "text",
      "style": { "$ref": "typography.body" },
      "color": { "$ref": "color.surface" }
    }
  ]
}

Agent zpracovávající tento uzel rozlišuje color.accent na #d96a3a a spacing.2 na 8px z paralelního souboru tokens.json. Žádná nejednoznačnost, žádné halucinace hodnot.

Viz vysvětlení IR pro jednotlivé obrazovky pro kompletní dokumentaci schématu uzlů.

Použití tokens.json se Style Dictionary

Výstup figmascope je kompatibilní se Style Dictionary s minimální konfigurací. Protože již používá konvenci $value / $type, můžete Style Dictionary namířit přímo na tokens.json:

// style-dictionary.config.js
module.exports = {
  source: ['design/tokens.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      prefix: 'fs',
      buildPath: 'src/styles/',
      files: [{ destination: 'tokens.css', format: 'css/variables' }]
    },
    js: {
      transformGroup: 'js',
      buildPath: 'src/',
      files: [{ destination: 'tokens.js', format: 'javascript/es6' }]
    }
  }
};

Spuštění style-dictionary build vytvoří CSS vlastní vlastnosti a exporty ES modulů ze stejného zdrojového souboru, který agent používá.

Použití tokens.json s Tailwind

Malý skript převede tokens.json na rozšíření tématu Tailwind. Struktura je dostatečně plochá, aby ji bylo možné procházet bez rekurze pro běžné případy:

// scripts/tokens-to-tailwind.js
const fs = require('fs');
const tokens = JSON.parse(fs.readFileSync('design/tokens.json', 'utf8'));

function flattenGroup(group) {
  return Object.fromEntries(
    Object.entries(group).map(([k, v]) => [k, v.$value])
  );
}

const extend = {
  colors:      flattenGroup(tokens.color),
  spacing:     flattenGroup(tokens.spacing),
  borderRadius: flattenGroup(tokens.radius),
};

console.log(JSON.stringify(extend, null, 2));
node scripts/tokens-to-tailwind.js > design/tailwind-extend.json

Poté v tailwind.config.ts:

import extend from './design/tailwind-extend.json';

export default {
  content: ['./src/**/*.{ts,tsx}'],
  theme: { extend },
};

Použití tokens.json s Jetpack Compose

Pro projekty Android se struktura tokenů čistě mapuje na Kotlin object. Můžete ho generovat programově nebo požádat Claude Code. Pro barevné tokeny:

// Generováno z design/tokens.json
object DesignTokens {
  object Color {
    val surface    = Color(0xFFF6F2EA)
    val ink        = Color(0xFF1F1D1A)
    val accent     = Color(0xFFD96A3A)
    val accentSoft = Color(0xFFF2C7A8)
  }
  object Spacing {
    val s1 = 4.dp
    val s2 = 8.dp
    val s4 = 16.dp
    val s8 = 32.dp
  }
}

Viz Jetpack Compose z Figmy pro kompletní průvodce včetně integrace MaterialTheme.

Co tokens.json neobsahuje

Znalost omezení rozsahu pomáhá nastavit správná očekávání:

Pole warnings v _meta.json zaznamená jakékoli hodnoty, které nebylo možné čistě exportovat. Zkontrolujte je před předáním balíčku agentovi.

Jak jsou odvozovány názvy tokenů

Když figmascope čte Figma Variables, název proměnné ve Figmě se stane klíčem tokenu. Proměnná pojmenovaná Colors/Surface/Primary v kolekci pojmenované Color se stane tokens.color.surface.primary v tokens.json — oddělovač cesty je / ve Figmě, . ve vnořených klíčích JSON.

Figma umožňuje názvy proměnných s mezerami, velkými písmeny a speciálními znaky. figmascope je normalizuje:

Krok transliterace je důležitý pro mezinárodní týmy. Ukrajinský designový tým používající kyrylické názvy proměnných jako Фон (pozadí) získá stabilní ASCII klíč (fon) ve výstupu, který je použitelný v názvech CSS tříd a JSON bez problémů s kódováním. Původní název je zachován jako pole $description, pokud je přítomen v metadatech Figma Variable.

Kontrola pokrytí tokenů před generováním kódu

Před předáním balíčku agentovi stojí za to ověřit, že pokrytí tokenů vypadá rozumně. Rychlý Node skript, který zkontroluje, zda se všechny hodnoty barev odkazované v IR obrazovek rozlišují na záznamy v tokens.json:

// scripts/check-token-coverage.js
const fs = require('fs');
const glob = require('glob');

const tokens = JSON.parse(fs.readFileSync('design/tokens.json', 'utf8'));
const screenFiles = glob.sync('design/screens/*.json');

function getRef(obj) {
  const refs = [];
  if (obj && typeof obj === 'object') {
    if (obj.$ref) refs.push(obj.$ref);
    for (const v of Object.values(obj)) refs.push(...getRef(v));
  }
  return refs;
}

function resolveRef(ref, tokens) {
  return ref.split('.').reduce((o, k) => o?.[k], tokens);
}

let missing = 0;
for (const file of screenFiles) {
  const screen = JSON.parse(fs.readFileSync(file, 'utf8'));
  for (const ref of getRef(screen)) {
    if (!resolveRef(ref, tokens)) {
      console.error(`Missing token: ${ref} (in ${file})`);
      missing++;
    }
  }
}
if (missing === 0) console.log('All token refs resolve.');
else console.error(`${missing} unresolved token refs.`);

Nulový počet chybějících odkazů znamená, že agent bude schopen rozlišit každý $ref v layout IR bez vymýšlení hodnot. Pokud existují chybějící odkazy, obvykle to znamená, že se soubor Figma změnil po exportu balíčku — znovu spusťte figmascope pro nový export. Více tipů k udržení pokrytí tokenů napříč iteracemi designu najdete také na blogu figmascope.