Communitygithub.com

vinculação-de-biblioteca-figma

Vincula telas do Figma a uma biblioteca de design system — tokens somente em correspondências exatas de valor, substitui ícones e componentes por versões da biblioteca e lista valores não correspondidos para os designers decidirem, sem aproximar para o token mais próximo. Use quando o usuário pedir para 'vincular tokens', 'usar componentes da biblioteca' ou 'encontrar cores não vinculadas'.

O que é vinculação-de-biblioteca-figma?

Esta skill automatiza o processo de vincular telas do Figma a uma biblioteca de design system, garantindo que os produtos usem tokens, ícones e componentes padronizados. Ela segue regras rigorosas: só vincula cores, raios, traços, espaçamentos e tamanhos de fonte quando o valor é exatamente igual ao do token, evitando aproximações que poderiam gerar inconsistências com o código. Ícones são substituídos apenas quando a biblioteca possui um componente com o mesmo nome exato, e componentes são trocados somente se a aparência for idêntica. Para valores sem token correspondente, a skill reporta como lacunas do design system para os designers decidirem, em vez de escolher um valor aproximado automaticamente. A skill suporta workflows manuais (via script `al-bind.js`) e automáticos (via `al-capture.cjs` e `al-pack.py`), e inclui a capacidade de criar e atualizar presets de bibliotecas para reuso em projetos futuros.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/byby325/code-to-figma-ui-states/tree/HEAD/skills/figma-library-binding

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Vinculando a uma biblioteca de design system

As telas do produto devem usar o design system do projeto, não apenas camadas locais.

Escolher um preset

Cada design system possui um preset, em presets/. Pergunte ao usuário qual o preset do projeto ou verifique as dependências do projeto (por exemplo, se o projeto depende de um pacote de tokens de design, use o preset correspondente). Veja presets/README.md para o formato. Se não houver preset, faça uma consulta seguindo "Como funciona a vinculação automática" abaixo e salve o resultado como um novo preset. Se o projeto não tiver biblioteca, escreva "Nenhum" e informe isso no relatório.

Antes de começar, use get_libraries para confirmar que todas as bibliotecas estão em libraries_added_to_file. Para as que estiverem faltando, peça ao usuário para adicioná-las no Figma em Assets › Libraries; não continue até que estejam adicionadas.

Regras de vinculação

É melhor deixar algo não vinculado do que alterar a tela. A ferramenta faz apenas o que está abaixo; todo o resto permanece local e é reportado.

TipoRegraNão fazer
CorVincular apenas em correspondência exata, incluindo opacidade. Cores semitransparentes precisam de um token com aquela transparência, porque o Figma redefine a opacidade para 1 ao vincularNão aproximar para a cor mais próxima
Raio, traço, espaçamento, tamanho de tipoVincular apenas quando o valor for exatamente igualNão alterar 3px para 2px ou 4px
Tokens de aliasUm token que aponta para outro token (token semântico sobre primitivo) conta com o valor no final da cadeia. Quando um valor tem ambos, o token com seu próprio valor vence; o alias é usado apenas para valores que mais nada temNão escolher entre dois tokens semânticos com o mesmo valor adivinhando; reporte
Estilo de textoVincular apenas quando fonte, tamanho e altura da linha forem todos iguaisSe a fonte diferir, vincular apenas o tamanho
ÍconeSubstituir apenas quando a biblioteca tiver um componente com o mesmo nome; aceitar nomes antigos apenas para mapeamentos confirmados como tendo o mesmo propósitoNão usar um ícone com significado semelhante, mas aparência diferente
ComponenteSubstituir apenas quando o componente da biblioteca tiver a mesma aparência que o do produto; manter o tamanho do produtoSe tiver aparência diferente, manter o componente local e não alterar a tela do produto

Por que não aproximar para o valor mais próximo: um valor correspondente não significa significado correspondente, e isso faz com que o painel de estado discorde do código. Um valor sem token correspondente é uma lacuna no design system; liste para o design decidir, em vez de deixar a ferramenta escolher.

Como funciona a vinculação automática

Com um preset, defina preset no arquivo de configuração al-capture.cjs e passe o nome do preset como quarto argumento para al-pack.py; as telas são vinculadas automaticamente quando são construídas. Apenas sem um preset, siga o processo abaixo, depois salve o resultado como presets/<nome>.json: libs é a configuração de vinculação, e extract é o mapeamento de sprite usado durante a extração.

  1. Após extrair a árvore de layout, liste cada lib (nome do ícone) no JSON
  2. Para cada nome, pesquise no Sistema de Ícones com search_design_system: system:cross mapeia para icon / system / cross. Aceite apenas correspondências exatas de nome
  3. Use search_design_system para encontrar o conjunto de componentes, coloque algumas instâncias, capture a tela, compare a aparência com o produto e decida buttons.rules
  4. Monte opts.libs. Construa 3–4 cartões primeiro e verifique log.drift e as capturas de tela; faça em lote apenas se estiverem corretos
const libs = {
  tokens: ['My DS - Foundation'],        // ler variáveis dessas bibliotecas
  icons: { 'system:cross': '<componentKey>' },
  buttons: {
    set: '<componentSetKey>',
    rules: { FFE13A: { Type: 'primary', Size: 'medium', Compact: 'false', Status: 'default' } }, // chave é a cor de fundo do botão
  },
  words: { value: 'Price' },             // renomear propriedades de texto para corresponder aos termos da equipe
};

A saída de al-capture.cjs inclui unmappedIcons, listando os ícones usados desta vez que o preset ainda não mapeia. Consulte-os com search_design_system e adicione correspondências exatas de nome ao preset; na próxima vez, eles serão vinculados automaticamente, então o preset fica mais completo com o uso.

O stat retornado por __alBuild tem os resultados da vinculação: boundColors, boundLayout, libIcons, dsButtons, unboundColors, localIcons.

Vinculando telas existentes

al-bind.js pode ser usado por conta própria. Ele vincula apenas tokens e não substitui ícones ou componentes. Cole todo o script em use_figma (ou carregue com eval), depois chame:

return await __alBind(['<id do frame>'], { tokens: ['<nome da biblioteca>'] });

Ele retorna boundColors, boundLayout e unboundColors (cores sem token). skippedText conta textos cuja fonte não pôde ser carregada, então seu tamanho foi deixado não vinculado.

Quando as telas são construídas com __alBuild, a tabela de tokens é armazenada em cache em _registry para que telas posteriores não importem todas as variáveis novamente. Ela é reconstruída quando o preset lista bibliotecas de tokens diferentes. Após a biblioteca publicar tokens novos ou alterados, passe refreshTokens: true na próxima chamada de __alBuild.

Componentes

  • Centralizar com Auto Layout: não com padding ou largura de caixa de texto, para que alterar o texto não o desloque
  • Contêineres não são componentes: uma estrutura repetida que já contém componentes é apenas um contêiner
  • Estados são variantes: selecionado e desabilitado devem ser alternáveis por propriedades, não por sobrescrita de cores da instância
  • Dividir componentes pequenos em propriedades: duas propriedades de variante, Type e State; tornar o texto uma propriedade do componente
  • Componentes principais devem estar completos: não transformar elementos cortados pela viewport em componentes

Relatório

Sempre liste:

  • Taxa de vinculação: cores, valores de layout
  • Número de ícones e componentes substituídos pelas versões da biblioteca
  • Cores sem token (as principais), para o design decidir
  • Ícones e componentes mantidos localmente e o motivo

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

code-to-figma

Rebuild screens from a running web app as native, editable Figma layers (Auto Layout, components, instances) and diff them against browser screenshots — not a screenshot import or a Code layer. Use when the user asks to "turn this page into Figma", "code to Figma", "push this screen to Figma" or "rebuild the UI in Figma". 把 Web 專案實際跑出來的畫面重建成 Figma 原生圖層:造狀態、抽 DOM 版面樹,建 Auto Layout 和 component/instance,再跟瀏覽器截圖比對。單一畫面或一批畫面都能用,不需要做情境稿。Use when 使用者要「code to figma」「把這頁轉成 Figma」「從程式重建畫面」「push 畫面到 Figma」,或 figma-state-board 走路線 B。產出是可編輯圖層,不是 Code layer 或截圖。

figma-state-board

Inventory every UI state of a feature from its code and lay them out on one Figma canvas (a state board) — real screens for states the prototype already handles, plus a gap check of missing error, empty and loading states, split into spec-required and suggested. Use when the user asks for a "state board", "all states of this feature in Figma", "which error screens are missing", or to update an existing board. 從任何產品專案的程式碼盤點一個功能的所有狀態,在 Figma 產出或更新「情境稿」:原型(通常是 mock data 做的)已經有的狀態畫真實畫面,原型缺的狀態全列進「缺漏檢查」,再分「規格有寫」(規格要求、原型漏做)和「建議補」(規格和原型都沒提的錯誤、空狀態、載入等)。Use when 使用者要「做情境稿」「把所有狀態/狀況畫到 Figma」「state board」「檢查缺了哪些 error 畫面」,或要依新規則增修既有情境稿。只要狀態清單用 state-discovery,只要把畫面轉進 Figma 用 code-to-figma。

Habilidades Relacionadas