Pular para o conteúdo
cssdesign-systemtailwindfrontendarquitetura

Um design system de três arquivos CSS, sem build

Douglas Haruo 11 min 22/09/2026

O problema que gerou este design system não foi estético. Foi de topologia. Três produtos da casa renderizam HTML de maneiras incompatíveis entre si. Um é um site em Astro com Tailwind 4. Outro é um app que serve CSS estático por Fastify. O terceiro é um painel operacional cujo HTML é montado como string em Python, com gráficos desenhados em Pillow. A mesma marca precisava atravessar os três.

A resposta reflexa da indústria, biblioteca de componentes, morre no enunciado: componente de quê? Astro component não roda no Fastify. Web Components rodariam em todo lugar, mas ao custo de introduzir JavaScript de terceiro em páginas que hoje têm zero JS. A única tecnologia que atravessa os três front-ends sem exigir nada de nenhum é a mais velha disponível: custom properties de CSS, variáveis declaradas no próprio CSS.

O resultado tem três arquivos e nenhum passo de build para quem consome. Algumas decisões valem a nota de campo: cada uma tem um porquê medido, e duas delas contradizem o instinto.


Três arquivos porque são três camadas de compartilhamento

A estrutura não é “três arquivos por organização”. É uma tese sobre o que de fato se compartilha entre produtos de uma mesma casa:

tokens.css (~400 linhas): só custom properties, os valores nomeados da marca. Cores de superfície e texto, o acento, uma escala de severidade, tipografia, espaçamento, forma, movimento. O domínio da casa é risco, então low/elevated/high são tokens de primeira classe. Compartilhamento: 100%. É onde a marca mora.

primitives.css (~185 linhas): cerca de 20 classes, como .btn, .chip, .card, .callout, .field, .table e .prose. Todas referenciam tokens; nenhuma tem cor literal. O compartilhamento é total, mas com uma restrição deliberada: primitiva é classe CSS, não componente. A razão é que <button class="btn"> sai igual de um template Astro, de um HTML estático e de uma f-string de Python.

Composições: zero compartilhamento, de propósito. A tela de relatório de um produto, o dashboard de outro: cada um mora no CSS do seu produto e não entra no design system. Essa fronteira não foi decretada, foi medida. A folha de estilos do produto mais maduro tem 256 classes, das quais só ~20 são genéricas. Cerca de 92% daquele CSS é aquela tela, e não deve ser compartilhado com ninguém. Um design system que tentasse absorver isso viraria o repositório de tudo, e “o repositório de tudo” é como design systems morrem.

A regra que fecha a camada: token que só um produto usa mora no CSS daquele produto. A barra de redação de um produto e o selo de um badge específico ficaram fora do sistema por decisão registrada. O sistema carrega o que é da casa, não o que é de alguém.

As decisões contra-intuitivas

Aliases com valor literal duplicado — e um script que audita a duplicação

Os tokens canônicos seguem a nomenclatura do Tailwind v4: --color-bg, --text-2xl, --radius-lg. A razão é pragmática. Com esses nomes, o mesmo arquivo vira utilitários no projeto Astro, via @theme, e continua sendo custom property comum para quem não usa Tailwind.

Mas o arquivo também define aliases curtos: --bg, --text, --accent, --low, --high. E aqui vem a heresia: os aliases repetem o valor literal, não fazem var(--color-bg). A razão é sobre leitura humana, porque var() só o navegador resolve. Quem abre o arquivo para consultar um hex, num code review, num script Python ou num grep, pega o primeiro bloco e para. Um alias que aponta para outro alias transforma consulta em caça.

A duplicação é o custo. Um script de verificação (aliases.mjs --ci, no teste do repositório) cobra que as duas cópias nunca divirjam. Duplicação auditada é diferente de duplicação: a primeira é um formato de leitura, a segunda é uma bomba.

Os aliases tiveram um segundo papel: migração sem reescrita. O produto de origem tinha milhares de linhas de CSS usando os nomes curtos. A adoção do sistema não exigiu uma edição nelas. E o diff da adoção conta a história inteira: um único valor de token mudou. Quando extrair um design system de um produto muda um valor, o sistema veio do lugar certo.

O tema escuro entra por duas portas — e não é o claro invertido

O bloco escuro é definido duas vezes: em @media (prefers-color-scheme: dark) guardado por :root:not([data-theme="light"]), e de novo em :root[data-theme="dark"]. É o que faz um botão de tema vencer nas duas direções: forçar claro sob sistema escuro e forçar escuro sob sistema claro. E sem JavaScript além de gravar o atributo. A regra de manutenção que sustenta isso: nenhuma cor tem sua única definição dentro de um bloco de tema. O claro é a base em :root, e o escuro redefine.

Duas escolhas de conteúdo, não de mecânica. O fundo escuro não é preto nem cinza neutro: puxa levemente para o verde do acento, porque tema escuro invertido matematicamente parece de outra marca. E o acento clareia no escuro (teal-700 → teal-400), porque a mesma cor que tem contraste sobre branco não tem sobre quase-preto.

E um bug que virou regra: color-scheme é contrato, não enfeite. Na migração de um dos produtos, a declaração se perdeu. A página escura ganhou barra de rolagem clara, porque quem pinta scrollbar é o navegador, e o navegador só sabe do tema se o CSS declarar. Custou um commit e entrou para a lista do que o preview verifica.

O arquivo do Tailwind é gerado — por causa de uma colisão de namespace

theme.css é o bloco @theme que o Tailwind 4 consome. Ele é gerado de tokens.css por um script de 92 linhas, e o gerador corta os aliases: só a metade canônica entra. Não é purismo. No Tailwind v4, --text-* é o namespace de tamanho de fonte, ou seja, um prefixo já reservado pela ferramenta. Um --text-muted: #5a625e que vazasse para o @theme geraria um utilitário text-muted aplicando um hex como font-size.

A colisão entre “nossa convenção de nome” e “a convenção da ferramenta” é o tipo de coisa que um humano esquece e um gerador não. O --check do gerador roda no teste, então um theme.css desatualizado reprova.

O mesmo pipeline gera tokens.py, os tokens como dicionário Python, para o front-end que monta HTML em string e desenha PNG com Pillow. O design system não pergunta o que o consumidor usa. Entrega o mesmo dado no formato que cada um lê.

Adoção por cópia versionada, não por dependência

Nenhum consumidor instala o design system. Cada um guarda uma cópia versionada no próprio repositório. Num produto é um bloco colado entre marcadores no CSS. No outro, um cp do theme.css. No terceiro, um módulo Python copiado. Junto vai um comando --check que compara a cópia com a origem, declaração a declaração. Comentários e espaços não contam como divergência.

O contrato do check tem dois detalhes finos:

  • Silencioso quando a origem não está ao lado. Quem clona um produto sem clonar o design system não quebra CI nem máquina: o check imprime “pulando” e sai 0. A verificação é para quem tem os dois repositórios. A ausência de um não pode punir quem só precisa de um.
  • Rodando dentro do npm test dos consumidores. Cópia divergente reprova a suíte junto com qualquer outro teste. (Confissão de rodapé: dos três consumidores, um tem o check fora do CI. É o tipo de lacuna que esta nota existe para envergonhar até alguém fechar.)

Por que cópia e não pacote npm? Três razões, em ordem de honestidade. A primeira: o repositório do sistema é privado, e a imagem docker de um dos consumidores não tem credencial para cloná-lo. “Um arquivo versionado de 80 linhas é mais honesto que um segredo de build.” A segunda: um dos consumidores nem é Node. A terceira: a cópia com check dá o benefício real de um lockfile, com mudança explícita e diff visível, sem custo de registry.

E por que colado em vez de @import no consumidor mais sensível a performance? @import no topo de uma folha bloqueia a renderização até a segunda requisição chegar, e aquela folha está no caminho crítico de toda página pública. Bloco colado custa zero requisição.

Contraste é teste, não opinião

O repositório do sistema tem um script que roda WCAG 2.1, o padrão de acessibilidade, sobre 46 pares de frente/fundo, nos dois temas, em CI. Não é teatro: ele já reprovou duas cores que “pareciam boas”. Uma foi a borda de um controle a 2,89:1 sobre superfície afundada, quando o mínimo de não-texto é 3:1. A outra foi a borda do botão secundário, a 1,74:1. Cor nova entra no sistema passando pelo mesmo portão que qualquer código: com verificação que pode dizer não.


O resumo generalizável

  1. Compartilhe por camada medida, não por ambição. Tokens: tudo. Primitivas: como classe, o mínimo que os três emitem igual. Composições: nada. Meça a proporção no seu CSS antes de discordar (aqui deu ~92% de tela).
  2. A tecnologia de compartilhamento certa é a que o consumidor mais pobre lê. Aqui, custom properties, porque um dos consumidores é uma f-string Python.
  3. Duplicação auditada é um formato de leitura. Alias com valor literal mais script que compara vence indireção que só o navegador resolve.
  4. Gere o que tem colisão de namespace; verifique o que é gerado. --check no CI para tudo que é cópia ou derivado.
  5. Tema escuro: duas portas, base fora dos blocos, color-scheme sempre.
  6. Cópia versionada com check silencioso-quando-sozinho é um mecanismo de distribuição legítimo. Para três consumidores heterogêneos, é mais honesta que um pacote.
  7. Contraste em CI. Se a acessibilidade não pode reprovar um merge, ela é intenção, não propriedade.

Precisa de um projeto técnico sob medida?

Arquitetura, TypeScript, APIs e automação, do protótipo à produção. Quem responde o seu e-mail é quem escreve o código, e o prazo que eu prometo é o prazo que eu consigo cumprir.

Me manda uma mensagem →