Design system1 de mai. de 2026
Heurix: um design system com um produto em mente
Um design system React feito do zero cuja lista de componentes entrega para que ele foi construído. O Heurix não é um kit neutro: seus tokens, modelo de tema e organisms foram moldados para vestir um produto específico, e publicado no npm.
Brief
Construir um design system React de verdade, publicável, do zero: tokens, tema, componentes, docs. Coerente o bastante para vestir um produto inteiro sem recorrer a um UI kit, e acabado o bastante para ir para o npm.
Ideia inicial
A maioria dos sistemas começa genérica e é dobrada em direção a um produto depois. Eu queria o contrário: deixar o vocabulário do produto moldar o sistema desde o primeiro commit. Um kit com um ScanBar, um EvalRow e um AIBlock não finge ser neutro. Ele sabe para que serve, e essa honestidade é a feature.
Decisões
- 01Os neutros são uma única matiz movida só pela luminosidade: --bg oklch(0.10 0.008 130), --surface oklch(0.13 0.008 130), --fg oklch(0.96 0.005 130). Mesma matiz (130), croma quase zero, então claro e escuro lêem como uma ideia em duas exposições, não duas paletas casadas na mão para parecerem parentes.
- 02Escuro é a base, não um modo parafusado por cima. :root e [data-theme="dark"] o carregam; [data-theme="light"] é o override.
- 03Exatamente dois tokens de borda: --border e --border-strong. Sem variações pontuais com alpha. A mesma disciplina de deleção que impede um tema escuro de derivar.
- 04Um único acento vivo, de propósito um hex chapado: --accent #a8e009. Os neutros merecem a matemática perceptual do OKLCH; o acento só precisa ser ele mesmo.
- 05Atomic design é o sistema de arquivos, não um slide. Atoms, molecules, organisms, cada um na sua pasta atrás de um barrel export plano.
- 06Os organisms do produto (EvalRow, SuggestionCard, AIBlock, SuggestionRunHeader, StatsTile) vivem no sistema, não no app. O app compõe; nunca reestiliza.
- 07Duas superfícies de documentação de propósito: um showcase em Vite para a sensação real do produto composto, e Storybook 8 para os estados componente a componente.
- 08Sem CSS-in-JS em runtime: custom properties para tokens, CSS Modules para componentes e um cx() minúsculo para juntar classes. TypeScript estrito e Vitest seguram as bordas.
Conclusão
Um sistema delimitado por um produto acaba mais honesto e mais reutilizável que um kit genérico. As decisões difíceis (o que é um EvalRow, o que um AIBadge significa) são tomadas uma vez, no sistema, onde é o lugar delas. A rampa de neutros em OKLCH é a parte que eu pegaria de volta primeiro: escolha uma matiz, mova só a luminosidade, e o tema simplesmente não deriva.
A pista está na lista de organisms. Um kit neutro entrega `Card` e `List`; o Heurix entrega `EvalRow`, `SuggestionCard` e `AIBlock`. Esses nomes são um produto vazando para dentro do seu design system de propósito. É esse o ponto inteiro. O sistema não tenta ser tudo; tenta ser uma coisa bem feita, e ser honesto sobre qual coisa.
Os neutros em OKLCH são o herói discreto. Ancorar `--bg`, `--surface` e `--fg` a uma única matiz com croma quase zero e mover só a luminosidade faz com que claro e escuro sejam a mesma ideia em duas exposições, não duas paletas ajustadas até parecerem parentes. É a diferença entre um tema que se sustenta por seis meses e um que deriva já na terceira tela nova. É também por isso que a única decisão saturada do arquivo inteiro, o `--accent` lima, pode ser um hex simples.
Componentes ao vivo
Os componentes reais do @heurix/design-system, rodando aqui na página. Alterne o tema, selecione heurísticas e rode um scan.