Mapa de Tokens

Especificação §10 / §21.3.1: toda execução de figma-migration / code-migration cruza a mesma fronteira — "a origem tem seus próprios tokens; o destino usa o sistema de design OD ativo; precisamos de um mapeamento determinístico". Este átomo produz esse mapeamento.

Entradas

• figma/tokens.json de figma-extract (figma-migration), OU
• code/tokens.json de design-extract (code-migration).
• O sistema de design ativo DESIGN.md (já injetado no prompt; o átomo lê do contexto do sistema de design em staging).

Saída

project-cwd/
└── token-map/
    ├── colors.json     # { source: '#hex' | 'tokenName', target: '--ds-token' }[]
    ├── typography.json # font + size + weight pairings
    ├── spacing.json    # spacing scale crosswalk
    ├── unmatched.json  # { source: ..., reason: 'no-target-equivalent' }[]
    └── meta.json       # { sourceKind: 'figma' | 'code', generatedAt, atomDigest }

unmatched.json é a lista de auditoria que um humano revisa; o agente não deve inventar tokens de destino silenciosamente.

Inferência de Token Semântico

O Figma frequentemente exporta nomes de origem anônimos como color-3, paint/17, ou o valor bruto #5B8DEF. Não peça ao usuário para renomeá-los antes do mapeamento. Primeiro, infira o papel semântico a partir de evidências de uso:

• Caminho do nó, nome do componente, substituições de instância, rótulos de variante/estado, nome do frame, nome da camada e texto próximo como Primary, Selected, Link, Error, Focus, Nav, Button, ou CTA.
• Posição semelhante a CSS na árvore renderizada: preenchimento de fundo, texto/ícone de primeiro plano, borda, divisor, sobreposição, tonalidade de sombra, anel de foco, selo de status, série de gráficos ou tratamento de marca/acento.
• Relações de contraste: uma cor emparelhada repetidamente com a tela principal é provavelmente de primeiro plano; uma emparelhada com o primeiro plano dentro de componentes CTA é provavelmente fundo primário/acento; um contorno fino ao redor de elementos interativos é provavelmente borda ou anel de foco.
• Topologia de reutilização: um valor que aparece em botões primários, abas selecionadas e itens de navegação ativos é uma evidência mais forte para --ds-color-primary do que um valor que aparece uma vez em uma ilustração.

Use essa evidência de papel para escolher entre os tokens existentes do sistema de design ativo e para decidir se um token anônimo deve ser renomeado ou deixado sem correspondência antes da passagem de mapeamento executável. Mantenha o contrato do mapa de tokens no disco inalterado: o átomo ainda grava apenas os arquivos de bucket existentes, unmatched.json e meta.json.

Por exemplo, esta é uma nota de raciocínio útil para decidir se color-3 deve ser mapeado para o token primário ativo:

{
  "source": "color-3",
  "value": "#5B8DEF",
  "role": "primary",
  "targetCandidates": ["--ds-color-primary", "--ds-color-link"],
  "evidence": [
    "Button/Primary fill",
    "Selected tab indicator",
    "Link text in Settings frame"
  ]
}

Em seguida, mapeie para um token de sistema de design ativo apenas quando a evidência for baseada em papel, não apenas em valor. Se os principais candidatos estiverem muito próximos para decidir, ou se a evidência apontar para papéis conflitantes (primary vs link vs focus-ring), deixe o token de origem sem correspondência usando o motivo existente no-target-equivalent e inclua os candidatos concorrentes na dica. Isso mantém a automação útil para casos comuns de tokens anônimos, preservando a revisão humana para decisões de marca ambíguas.

Expectativa antes / depois

Sem inferência semântica, um token Figma anônimo só pode produzir um mapeamento incerto de nível de valor:

{
  "source": "color-3",
  "value": "#5B8DEF",
  "target": null,
  "reason": "no-target-equivalent"
}

Com inferência semântica, o mesmo token deve carregar evidências de papel antes de ser aceito:

{
  "source": "color-3",
  "value": "#5B8DEF",
  "target": "--ds-color-primary",
  "via": "name"
}

Este átomo determinístico v1 não reivindica um aumento de precisão medido por si só. Trate a melhoria esperada como cobertura de casos de tokens anônimos anteriormente manuais quando a árvore Figma contiver evidências de papel suficientes. Números de precisão reais requerem um conjunto de fixtures com tokens de origem conhecidos, papéis semânticos esperados e uma execução do agente antes/depois. Veja examples/semantic-inference-before-after.json para uma simulação determinística de lote de mesmo token que compara a saída de nível de valor antiga com a saída de inferência semântica.

Convergência

O átomo é concluído quando cada token de entrada é mapeado ou explicitamente registrado sob unmatched.json com um reason não vazio. O avaliador until lê tokens.unmatched.length === 0

…