Figma Code Connect

O GovBR DS publica snippets de Figma Code Connect para os Web Components públicos. No Dev Mode, a pessoa desenvolvedora pode copiar o HTML do componente junto com o import do pacote @govbr-ds/webcomponents.

Cobertura

O inventário atual possui 88 custom elements públicos. Há 37 templates co-localizados com os componentes que possuem link para uma representação Figma. Os outros 51 ficam fora da integração: três são aliases sem representação visual independente:

• br-crumb → br-breadcrumb-item;
• br-checkgroup → br-checkbox-group;
• br-skiplink-item → br-skip-link-item.

Os outros 48 componentes não possuem link de componente correspondente no arquivo Figma informado. Eles são registrados na mesma lista de exceções para que a auditoria não espere templates que não serão publicados.

A lista de exceções fica em figma.ignore.json; cada item precisa explicar o motivo e, quando houver, apontar o componente substituto. Os wrappers Angular, React e Vue não criam conjuntos duplicados: todos consomem o mesmo contrato visual dos Web Components.

Como os templates funcionam

Cada arquivo *.figma.ts fica ao lado do .tsx correspondente, por exemplo:

packages/webcomponents/src/components/button/
├── button.tsx
└── button.figma.ts

Os templates usam a API atual de arquivos de template do Code Connect e figma.code com saída html. O parser: "html" explícito evita que a presença dos wrappers React no monorepo altere a detecção automática do projeto. Propriedades booleanas, textuais e variantes são obtidas da instância Figma com getBoolean, getString ou getEnum; conteúdo livre e slots nomeados usam getSlot. Isso mantém o snippet fiel ao estado selecionado e permite aninhar componentes sem importar APIs internas.

O exemplo gerado inclui o registro público do pacote:

<br-button color-mode="...">Conteúdo</br-button>

Os nomes de propriedades do template seguem os nomes expostos no componente (em Title Case na configuração da instância Figma). Propriedades de transporte, referências de DOM, objetos complexos e atributos de acessibilidade derivados não são inventados no snippet; permanecem responsabilidade do código da aplicação.

URLs e configuração central

Os templates não contêm links reais de arquivos Figma. Eles usam placeholders como <FIGMA_BUTTON>, e todos os valores ficam em figma.config.json, na chave codeConnect.documentUrlSubstitutions:

{
  "<FIGMA_BUTTON>": "https://www.figma.com/design/<arquivo>/<nome>?node-id=<id>"
}

Preencha somente URLs HTTPS oficiais da Figma. O comando status mostra a quantidade configurada, pendente e a cobertura do inventário:

pnpm figma:status
# Inclui a tabela por componente no terminal
pnpm figma:status -- --coverage

O status também alerta quando dois placeholders apontam para o mesmo node-id. No estado atual, <FIGMA_SIGN_IN> e <FIGMA_TAG> usam 126-2013; confirme no Dev Mode se essa duplicidade é intencional antes de publicar.

Não coloque token ou outro segredo nos templates, no JSON versionado ou em exemplos. Os links ficam somente no config central e podem ser protegidos pelo controle de acesso do próprio arquivo Figma, conforme a política do time de Design.

Fluxo local

Instale as dependências com o lockfile e execute as validações nesta ordem:

# Inventário, co-localização, IDs, placeholders e ignore list
pnpm figma:validate:structure

# Parse local sem publicar
pnpm figma:parse

# Preview autenticado dos snippets
FIGMA_ACCESS_TOKEN=<token> pnpm figma:preview

# Validação estrutural + parse + simulação autenticada de publicação
FIGMA_ACCESS_TOKEN=<token> pnpm figma:validate

# Publicação deliberada
FIGMA_ACCESS_TOKEN=<token> pnpm figma:publish

FIGMA_ACCESS_TOKEN é lido apenas do ambiente ou solicitado de forma oculta no terminal interativo. Em CI, o script exige --non-interactive e falha se o segredo não existir. Use um token de acesso da Figma com o menor escopo necessário para publicar Code Connect, armazenado como variável protegida e mascarada do GitLab. A documentação do Figma recomenda um Plan Access Token (PLANT) para CI, pois ele pertence ao plano, tem escopo fixo para a CLI e pode ter expiração de até um ano; um Personal Access Token (PAT) é uma alternativa quando o plano ainda não disponibiliza PLANT. Nunca passe o token como argumento nem o registre em log.

Para remover mappings, informe explicitamente o label e confirme a operação:

FIGMA_ACCESS_TOKEN=<token> pnpm figma:unpublish \
  -- --label "Web Components" --confirm-unpublish

O --dry-run pode ser usado antes da remoção. O comando não remove mappings de forma implícita durante uma release.

CI e releases

O job figma_code_connect roda no GitLab para alterações relevantes e executa pnpm figma:validate:structure sem token. Assim, Merge Requests verificam a estrutura, os tipos e o parse dos 37 arquivos sem publicar nada.

A publicação real acontece no job pós-release figma_post_release, depois que os pacotes foram publicados no npm. O job precisa receber FIGMA_ACCESS_TOKEN como variável protegida e mascarada. Se o token não estiver configurado, o job é ignorado; se o serviço falhar, a publicação npm continua válida e o job pode ser reexecutado. O label acompanha o canal:

Canal	Label no Figma
main/estável	Web Components
next	Web Components (next)
alpha	Web Components (alpha)

Corrija credenciais, permissões ou URLs e reexecute o job do Code Connect de forma deliberada; a separação por labels evita que prereleases sobrescrevam o canal estável.

Novo componente

pnpm plop agora cria também o *.figma.ts e adiciona o placeholder ao figma.config.json. Antes de abrir o MR:

1. vincule o template a uma instância visual Figma e substitua o placeholder pela URL oficial em figma.config.json;
2. revise props, variantes, slots e o HTML emitido;
3. rode pnpm figma:validate:structure e pnpm figma:parse;
4. confirme que o componente não é um alias já coberto pela ignore list.

Consulte a documentação oficial de templates, da configuração e do uso em CI/CD para detalhes da plataforma.