React + Tailwind z kontextového balíčku Figmy

Výchozím cílem exportu figmascope je Jetpack Compose. Ale balíček je na agenty nezávislý — typy uzlů IR, formát tokenů a string refs se mapují stejně čistě na React + Tailwind. Jen řeknete agentovi, aby cílil na JSX místo Kotlinu.

Tato příručka pokrývá mapování IR na JSX, jak rozšířit tailwind.config.js tokeny z tokens.json a promptovací vzory, které na straně Reactu produkují nejmenší drift.

Jeden důležitý předběžný caveat

Compose je to, co figmascope testuje nejvíce. IR, formát tokenů a omezení CONTEXT.md byly navrženy s ohledem na Compose. React + Tailwind funguje — IR se mapuje čistě — ale uvidíte mírně větší drift, zejména u typografie a překryvných rozvržení. Označte vše, co vypadá špatně, a po prvním průchodu spusťte kontrolu tokenů.

Krok 1: Vygenerujte a rozbalte balíček

unzip ~/Downloads/context-bundle.zip -d ./design/

ls design/
# CONTEXT.md  _meta.json  components/  screens/  strings.json  tokens.json

Krok 2: Rozšiřte konfiguraci Tailwind o designové tokeny

Před promptováním namapujte tokens.json do svého tailwind.config.js. Toto je klíčový krok, který Tailwind učiní aware-of-tokens — místo hardcódovaných hexadecimálních hodnot v řetězcích className získáte sémantická jména, která jsou sledovatelná zpět k designu.

// tailwind.config.js
const tokens = require('./design/tokens.json')

// Build color map: { 'brand-7f5cfe': '#7F5CFE', ... }
const colors = Object.fromEntries(
  Object.entries(tokens.color).map(([key, val]) => [
    `brand-${key}`, val
  ])
)

// Build spacing map: { 'ds-4': '4px', 'ds-8': '8px', ... }
const spacing = Object.fromEntries(
  Object.entries(tokens.spacing).map(([key, val]) => [
    `ds-${key}`, `${val}px`
  ])
)

// Build border-radius map
const borderRadius = Object.fromEntries(
  Object.entries(tokens.radius).map(([key, val]) => [
    `ds-${key}`, val === 9999 ? '9999px' : `${val}px`
  ])
)

module.exports = {
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {
      colors,
      spacing,
      borderRadius,
    }
  }
}

Toto produkuje Tailwind třídy jako bg-brand-7f5cfe, p-ds-16, rounded-ds-12. Ne nejhezčí názvy tříd, ale jsou sledovatelné — každá třída se mapuje zpět na klíč tokenu.

Pokud raději preferujete sémantické aliasy, přidejte vrstvu aliasů:

// in theme.extend.colors:
primary: tokens.color['7f5cfe'],
background: tokens.color['f6f2ea'],
surface: tokens.color['ffffff'],

Předejte agentovi obojí — raw konfiguraci tokenů a sémantické aliasy — aby mohl v kontextu vybrat správné jméno.

Krok 3: Promptujte agenta, aby cílil na React + Tailwind

CONTEXT.md říká, že výchozí cíl je Compose. Explicitně to přepište ve svém promptu:

Implement ./design/screens/home.json as a React functional component using Tailwind CSS.

Framework override: ignore the Compose instructions in CONTEXT.md. Target React + Tailwind.

Rules:
- Read ./design/tokens.json. The tokens are extended into Tailwind config —
  use Tailwind classes that correspond to token keys (e.g. bg-brand-7f5cfe, p-ds-16).
- UI strings come from ./design/strings.json. Import and reference them by key.
- IR node kind mapping:
    stack (axis:vertical)   → <div className="flex flex-col gap-[Xpx]">
    stack (axis:horizontal) → <div className="flex flex-row gap-[Xpx]">
    overlay                 → <div className="relative"> with absolute-positioned children
    absolute                → <div className="absolute" style={{"{{"}}top, left, width, height{{"}}"}}>
    leaf (text)             → <span> or <p> with Tailwind text classes
    leaf (rectangle)        → <div> with bg and rounded classes
- Do not hardcode hex values. All colors must use Tailwind classes from the token config.
- Do not hardcode strings. Use the strings.json keys.

Output to: src/screens/HomeScreen.tsx

Mapování IR na JSX

Zde je úplná tabulka mapování pro React + Tailwind:

Hodnoty gap a padding: použijte třídy mezer ds-{n} z rozšíření konfigurace Tailwind. Pokud hodnota gap není čistý klíč tokenu, použijte syntaxi libovolné hodnoty Tailwind: gap-[20px].

Skutečný příklad: IR domovské obrazovky do JSX

Použití stejného IR z průvodce Compose:

import strings from '../../design/strings.json'

export function HomeScreen() {
  return (
    <div className="flex flex-col gap-ds-24 p-ds-16 bg-brand-f6f2ea min-h-screen">
      <h1 className="text-2xl font-bold leading-tight text-brand-1a1a2e">
        {strings['home.title'].value}
      </h1>
      <div className="flex flex-col gap-ds-12">
        <div className="bg-white rounded-ds-12 p-ds-16">
          <span className="text-xs font-medium text-brand-7f5cfe">
            {strings['home.card.label'].value}
          </span>
        </div>
      </div>
    </div>
  )
}

Každý className je sledovatelný. gap-ds-24 → spacing.24 → 24px. text-brand-7f5cfe → color.7f5cfe → #7F5CFE. Pokud hodnota driftuje (např. agent napíše gap-6 místo gap-ds-24), je to okamžitě viditelné při revizi kódu.

Proč tokens.json + konfigurace Tailwind funguje

Oba systémy jsou token-first. Tailwind rozšiřuje základní konfiguraci o vlastní hodnoty; tokens.json je již strukturován jako mapa vlastních hodnot. Krok rozšíření (Krok 2 výše) je jednorázové nastavení — poté agent používá názvy tříd Tailwind, které jsou sémanticky vázány na designový systém spíše než libovolné třídy utilit.

Výsledek: když se token designu změní (řekněme primární barva se posune z #7F5CFE na #6B4EE6), aktualizujete jednu hodnotu v tokens.json, znovu spustíte import konfigurace a Tailwind se regeneruje. Kód komponenty se nemění.

Kontrola driftu tokenů

Po implementaci požádejte agenta o audit driftu:

Audit src/screens/HomeScreen.tsx for token drift.

Check:
1. Any hex color values not referenced through a Tailwind class from the token config.
2. Any hardcoded px or rem spacing values that should be ds-{n} classes.
3. Any UI strings not sourced from design/strings.json.

List violations. Produce a diff that fixes them.

Overlay a absolute — záludné případy

Uzly overlay potřebují rodiče relative a absolutně-pozicované děti. IR uvádí děti v z-pořadí (první = spodní vrstva). Řekněte agentovi, aby zachoval toto pořadí v JSX — React renderuje v pořadí DOM a CSS position: absolute se skládá odpovídajícím způsobem.

Absolutní uzly používají raw pixelové souřadnice z Figmy. Ty téměř vždy pocházejí z designů, které nebyly postaveny s auto-layoutem. Pokud vidíte mnoho absolutních uzlů, obvykle to znamená, že soubor Figmy má manuální pozicování — generovaný kód bude křehký při různých velikostech viewportu. Zvažte označení tohoto a refaktorování na flex layouty.

Zpracování řetězců v Reactu

Na rozdíl od Androidu (kde klíče strings.json mapují na ID zdrojů R.string.*), v Reactu importujete JSON přímo:

import strings from '../../design/strings.json'

// usage
{strings['home.title'].value}
// or with fallback
{strings['home.title']?.value ?? strings['home.title']?.fallback ?? 'Untitled'}

Pokud používáte i18n knihovny (react-i18next, next-intl), klíče tečkové notace v strings.json se přímo mapují na jmenné prostory překladových klíčů. Řekněte agentovi, kterou i18n knihovnu používáte, aby generoval správný vzor volání.

Upřímné mezery na straně Reactu

Typografické utility. Textové utility Tailwind (text-xs, text-2xl) se 1:1 nemapují na tokeny typography v tokens.json. Tailwind má pevnou typovou škálu; soubor tokenů má libovolné velikosti. Budete muset buď rozšířit konfiguraci fontSize Tailwind o hodnoty tokenů nebo použít libovolné hodnoty (text-[24px]). Obojí funguje; rozšíření konfigurace je čistší.

Výška řádku. Stejný problém — utility leading Tailwind neodpovídají libovolným hodnotám lineHeight. Použijte leading-[{value}] nebo rozšiřte konfiguraci.

Přechody. V IR nejsou podporovány. Jakákoli výplň přechodem se objeví jako varování v _meta.json a je vynechána z vlastnosti výplně uzlu. Zpracujte ručně.

Žádná z těchto věcí není blocker — jsou to známé mezery. Základ tokeny-aware je solidní; okraje jen potřebují ruční zpracování.

Začněte s figmascope pro export svého balíčku, pak použijte tuto příručku společně s pracovním postupem Cursor nebo pracovním postupem Claude Code pro řízení implementace.