Componentes bonitos, mas sem personalidade: como criei o Datum, o design system do meu portfólio

Meu site antigo era bonito. Escuro, moderno, com os componentes do shadcn/ui bem montados. O problema é que ele podia ser o site de qualquer pessoa: os botões, os cards e os menus eram exatamente os que vêm na instalação, sem nenhum trabalho em cima que dissesse quem eu sou. E ainda travava o celular: o fundo tinha umas cem estrelas animadas em JavaScript, para sempre.

O Datum nasceu para resolver as duas coisas. É o design system do meu portfólio: tokens, temporadas e componentes que dão a mesma personalidade a tudo o que eu construo, do site às ferramentas.

Por que um design system para uma pessoa só

Parece coisa de empresa grande, mas design system não é sobre o tamanho do time. É sobre não decidir tudo de novo. Com ele, cada coisa que eu construo, uma página ou uma ferramenta, já nasce sabendo a cor, o espaço, a tipografia e a mensagem que quero passar. Eu paro de perguntar "como isso deveria parecer?" e começo direto no problema.

E tem o outro lado: quem encontra o meu trabalho, no site, numa ferramenta ou num post, reconhece a mesma personalidade em qualquer lugar. Identidade visual consistente é o que faz as pessoas lerem a marca como uma personalidade, e não como um amontoado de telas.

Por que comecei pelo shadcn (e não pelo MUI)

Bibliotecas como MUI, Chakra e Mantine entregam componentes prontos dentro do node_modules. Funcionam bem, mas o componente fica numa caixa preta: dá para configurar, não para evoluir. O shadcn/ui faz o contrário e copia o código-fonte do componente para o seu projeto. A própria documentação resume: não é uma biblioteca de componentes, é o jeito de construir a sua.

Isso decidiu a base. Os componentes do Datum partem do shadcn e do Radix, que cuida do teclado, do foco e do leitor de tela, e ganham por cima uma camada de personalidade. Quando um componente precisa mudar, eu mudo o código dele, em vez de brigar com ele.

Uma fonte só para cor, espaço e tipografia

Os tokens, as decisões de base do sistema, ficam em arquivos JSON no formato do Design Tokens Community Group do W3C, que ganhou a primeira versão estável em 2025. Ele não é um padrão oficial do W3C, mas é um formato aberto e independente de ferramenta, e é isso que importa: cor, tipografia, espaço de 4 px e raio de 2 px descritos uma vez só.

"color": {
  "board": { "$value": "{palette.navy.900}", "$description": "Page background, the drafting board" },
  "ink": { "$value": "{palette.slate.50}", "$description": "Main text" },
  "line": { "$value": "#7dd3fc24", "$description": "Hairline borders" }
}

Um build transforma esses arquivos em três saídas: variáveis CSS, um tema do Tailwind 4 e um módulo TypeScript. Os componentes usam só os nomes semânticos (bg-board, text-ink), nunca a cor crua.

A personalidade: uma prancheta

Antes do código, escrevi os princípios da marca. O central é cuidar do que ninguém vê: o lado de dentro do trabalho recebe a mesma atenção que o de fora. Com isso, comparei três direções visuais: Blueprint, Órbita e Constelação. Venceu a Blueprint, uma prancheta de projeto com grade fina, cotas e anotações em fonte monoespaçada, porque ela mostra justamente o lado de dentro.

O nome também vem do desenho técnico. Numa planta, o datum é a referência de onde todas as medidas partem. As cotas não se medem umas das outras, todas saem do mesmo ponto, e é isso que faz a peça encaixar. Um design system faz o mesmo papel para cor, espaço e tipografia.

Temporadas: o mesmo site, com a cor da data

O Datum tem oito temporadas: a base, Ano-Novo, Carnaval, Páscoa, Festa Junina, Dia do Programador, Halloween e Natal. Só a cor de destaque e o degradê do logo mudam. Layout, contraste e regras ficam iguais.

O detalhe técnico: as páginas são estáticas e ficam um ano em cache, então decidir a temporada no build faria o site ficar preso na data em que foi publicado. Um script pequeno no <head> lê a data de quem visita e marca a temporada antes da primeira pintura, sem o site piscar.

Regras que se defendem sozinhas

Regra que depende de alguém lembrar é regra que um dia se perde. No Datum, as importantes estão no código:

• Contraste. Todo par de texto e fundo precisa passar no WCAG AA (4,5:1), inclusive a cor de cada temporada. Os testes reprovam a build se um token novo quebrar isso.
• Só peças gerais. O Datum é público, então só entra o que faria sentido em qualquer projeto. O card de artigo e as métricas da home são montados no site, com peças do Datum, e nunca entram nele.
• Desempenho faz parte da marca. Nada de animação contínua em JavaScript. Com movimento reduzido no sistema, o movimento decorativo para.

IA executando, eu orquestrando

Construí o Datum com agentes de IA, e o trabalho que mais pesou foi direcionar. Eu defini as tecnologias (o shadcn como base, o formato do W3C para os tokens, o Storybook para documentar), a personalidade e as regras do sistema, e pedi três direções para escolher, em vez de aceitar a primeira.

Não foi o meu primeiro design system. Contribuí no Mozaic, o design system do grupo ADEO, e construí o do Castle Raiders. Essa bagagem fez diferença: eu sabia quais decisões tomar e em que ordem, e o agente acelerou a parte de escrever. Do primeiro token ao site inteiro usando os componentes foram três dias, sem retrabalho grande. Se eu começasse de novo, faria igual.

O que deu errado mesmo assim

Dois bugs só apareceram com gente usando:

• O asChild que quebrava a página. No Storybook, ligar o asChild no painel de controles fazia o exemplo do Button cair: o asChild aplica o visual ao elemento filho, e ali o filho era só um texto. O componente estava certo; o painel é que oferecia um controle que não tinha como funcionar sozinho.
• O indicador de carregamento parado. Com o modo de desempenho do Windows, o sistema pede movimento reduzido, e o botão parava o indicador. Só que ele não é decoração: mostra que algo está acontecendo. Agora ele continua girando, mais devagar.

Os dois viraram regra escrita e entrada na página de Novidades do Storybook.

Os números

O Datum chegou junto com um orçamento de desempenho, e a mudança foi visível. Parte veio de trocar o fundo animado pela grade da prancheta, que é só CSS; parte de renderizar as páginas no servidor e cortar o JavaScript do primeiro carregamento. Na home, no Lighthouse com perfil de celular:

• Performance: de 54 para 90 ou mais.
• Bloqueio da página (TBT): de 1.424 ms para menos de 100 ms.

E o sistema em si: 14 componentes, 69 histórias no Storybook, cada uma checada com axe, 8 temporadas e contraste AA em todo par de cor.

Tudo está aberto: os componentes no Storybook do Datum e o código no GitHub.

Lições

1. Um design system serve para não decidir tudo de novo: vale até para uma pessoa só.
2. Prefira uma base que entrega o código do componente quando você quer personalidade, não só configuração.
3. Descreva cor, espaço e tipografia uma vez só, em tokens, e gere o resto a partir deles.
4. Coloque as regras importantes no código: um teste de contraste lembra por você.
5. Com IA, o resultado depende de saber o que pedir: tecnologias, regras e opções para escolher.

Perguntas frequentes

Vale a pena criar um design system para um projeto pessoal?

Vale quando a sua marca aparece em mais de um lugar, como um site, ferramentas e posts. O ganho é não decidir cor, espaço e tipografia de novo a cada peça, e manter a mesma personalidade em todas.

O shadcn/ui é uma biblioteca de componentes?

Não no sentido tradicional. Ele copia o código-fonte de cada componente para o seu projeto, então você pode mudar e criar componentes a partir dele, em vez de depender de um pacote fechado no node_modules.

O que são design tokens?

São as decisões de base de um design system, como cores, fontes, espaços e raios, guardadas num formato neutro. O formato do Design Tokens Community Group do W3C permite gerar a partir deles variáveis CSS, temas do Tailwind e código para outras plataformas.

Como garantir contraste acessível em um design system?

Teste cada par de texto e fundo contra o WCAG AA (4,5:1) de forma automática e faça a build falhar quando um par não passar. Assim um token novo não quebra a acessibilidade sem ninguém perceber.

Referências

• shadcn/ui: Introduction
• Design Tokens Format Module 2025.10 (W3C Design Tokens Community Group)
• Radix Primitives
• Understanding WCAG 2.2: Contrast (Minimum)