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.
| Tipo | Regra | Não fazer |
|---|---|---|
| Cor | Vincular 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 vincular | Não aproximar para a cor mais próxima |
| Raio, traço, espaçamento, tamanho de tipo | Vincular apenas quando o valor for exatamente igual | Não alterar 3px para 2px ou 4px |
| Tokens de alias | Um 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 tem | Não escolher entre dois tokens semânticos com o mesmo valor adivinhando; reporte |
| Estilo de texto | Vincular apenas quando fonte, tamanho e altura da linha forem todos iguais | Se a fonte diferir, vincular apenas o tamanho |
| Ícone | Substituir apenas quando a biblioteca tiver um componente com o mesmo nome; aceitar nomes antigos apenas para mapeamentos confirmados como tendo o mesmo propósito | Não usar um ícone com significado semelhante, mas aparência diferente |
| Componente | Substituir apenas quando o componente da biblioteca tiver a mesma aparência que o do produto; manter o tamanho do produto | Se 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.
- Após extrair a árvore de layout, liste cada
lib(nome do ícone) no JSON - Para cada nome, pesquise no Sistema de Ícones com
search_design_system:system:crossmapeia paraicon / system / cross. Aceite apenas correspondências exatas de nome - Use
search_design_systempara encontrar o conjunto de componentes, coloque algumas instâncias, capture a tela, compare a aparência com o produto e decidabuttons.rules - Monte
opts.libs. Construa 3–4 cartões primeiro e verifiquelog.drifte 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,
TypeeState; 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