Design System Design Tokens Acessibilidade WCAG Documentação Handoff
sys.vc
O design system compartilhado pelo app, pelo painel admin e pela loja da Reconhece.vc. Três camadas de token, tema e plataforma resolvidos como atributos na raiz — nenhum componente recebe prop de tema. A documentação é um produto em si, e ela está rodando ao vivo nesta página.
Contexto
O sys.vc é o design system da Reconhece.vc. Ele atende três produtos ao mesmo tempo: o aplicativo do colaborador em iOS e Android, o painel administrativo na web e a loja de resgate de pontos.
São contextos que não compartilham densidade, grid nem plataforma. O que os une é a camada de token — e a regra de que o que não está escrito é porque é igual nos três. Cada produto documenta apenas o que acrescenta ao sistema.
Desafio
O sistema nasceu para resolver problemas que apareceram nos outros dois projetos:
- O app estava fora de conformidade com o sistema que estava sendo construído — foi um dos três problemas do levantamento inicial do Reconhece Card.
- App e painel divergiam em componentes que deveriam ser o mesmo, obrigando o time de desenvolvimento a manter duas versões de cada peça.
- O material de origem era o Figma, com nomes de variável, componentes em SVG e telas — mas sem uma camada intermediária que o código pudesse consumir.
Meu papel
Estruturei o sistema da variável do Figma até o arquivo que o desenvolvedor importa, e escrevi a documentação:
- Definição das três camadas de token
- Auditoria de contraste contra as diretrizes WCAG
- Biblioteca de componentes e suas regras de composição
- Exportação em CSS e no formato do Design Tokens Community Group
- Documentação navegável, com exemplo e código por componente
- Handoff para os times de front-end dos três produtos
Camadas de token
O sistema tem três camadas. Os primitivos são as rampas de cor cruas. Os semânticos dão papel a elas com nomenclatura padronizada — brand, alert, neutral, border. Os contextuais nomeiam o uso final, e é essa distância entre camadas que permite trocar o azul pelo teal no tema escuro sem tocar em componente nenhum.
Os nomes seguem o caminho da variável no Figma, com traço no lugar do ponto e sem o segmento de tema: light.button.surface.filled.hovered vira --button-surface-filled-hovered. Isso não é detalhe de estilo — é o que permite a alguém procurar um token no código e achar a mesma coisa na biblioteca.
A mesma camada sai em dois formatos: tokens.css, que os produtos web consomem direto, e tokens.json no padrão do Design Tokens Community Group, com referências {alias} — a fonte para Style Dictionary, iOS e Android.
Tema e plataforma
Esta é a decisão estruturante do sistema: tema e plataforma são atributos na raiz. data-theme e data-platform ficam no <html>, e nenhum componente recebe prop de tema ou de plataforma. Todos leem --accent, --family-ui e afins.
Trocar um atributo repinta e repagina o produto inteiro de uma vez — que é, no fim, o motivo de o design system existir. Você pode testar isso na própria documentação embutida abaixo: os controles de tema e de plataforma estão na barra do painel.
A troca de família tipográfica é o único caso em que a plataforma manda: SF Pro no iOS, Roboto no Android, Lato na web. E é uma decisão da plataforma, não da marca.
Acessibilidade
A auditoria de contraste encontrou três tokens que não cumpriam a WCAG 2.1 AA. Eles estão corrigidos no sistema e sinalizados na documentação como divergência a reconciliar na biblioteca do Figma — porque um design system que corrige em silêncio cria duas fontes de verdade:
- Texto de apoio no tema claro passou de
grey.500paragrey.800. Estava em 1,97:1. - Borda de componente no claro passou de
grey.500paragrey.700. Estava em 1,97:1 e precisa de 3:1. - Rótulo de campo passou a usar
brand.primary.bold. Estava em 4,44:1 e precisa de 4,5:1 — reprovava por seis centésimos.
A marca também mudou no escuro: brand.primary migra de azul para teal. O azul #1F71DB alcança apenas 1,6:1 sobre o fundo #101214, e clarear o azul o afastaria da identidade — enquanto o teal já era a segunda cor da marca. A rampa darkgrey foi reordenada para abrir espaço a #738496, a borda que faltava para atingir 3:1 no escuro.
Documentação ao vivo
O que está abaixo não é print: é a documentação do sys.vc rodando, dentro desta página. Use os controles da barra para trocar o tema e a plataforma — é a tese do projeto sendo demonstrada, e não descrita.
Entrega
Cada componente sai em dois arquivos: um CSS escrito sobre os tokens e um JSX pronto para importar. Não são exemplos da documentação — são os mesmos arquivos que a documentação carrega, o que elimina a possibilidade de a doc mostrar uma coisa e o produto entregar outra.
A documentação também registra o que ainda falta: tokens de sombra e de movimento não existiam no material de origem, e as durações citadas nos organismos vieram da observação dos vídeos, ainda sem token. Escrever a lacuna é parte da entrega — é o que impede alguém de assumir que a ausência foi uma decisão.
Stack e ferramentas
- Origem
- Figma · Variáveis e componentes
- Tokens
- CSS Custom Properties · Design Tokens Community Group · Style Dictionary
- Entrega
- CSS e JSX por componente · Documentação navegável
- Método
- Auditoria de contraste WCAG 2.1 AA · Nomenclatura espelhada do Figma
Vamos conversar
- E-mail eu@leonsampaio.me
- Celular +55 11 94920 0571
- LinkedIn linkedin.com/in/leonsampaio