Refatorar mais de 80% de uma plataforma sem um sistema de design por trás é receita para inconsistência: cada tela com seu botão, cada desenvolvedor com seu espaçamento. O que organizou o nosso processo foi o Atomic Design, combinado com design tokens e Tailwind CSS. Neste artigo compartilho as lições práticas: como estruturar o sistema, por que a abordagem atômica facilita a implementação e a manutenção, e o que ganhamos em padronização, acessibilidade e performance.
O problema de começar sem sistema
Antes do design system, os sintomas eram conhecidos:
- cinco tons ligeiramente diferentes de azul no mesmo produto;
- o mesmo botão implementado de várias formas, cada uma com seus bugs;
- acessibilidade tratada tela a tela (ou esquecida);
- qualquer mudança visual significando uma caçada por todo o código;
- CSS crescendo sem parar, com sobreposições e
!important.
Um design system resolve isso criando um vocabulário compartilhado entre design e desenvolvimento.
Por que Tailwind para um design system?
À primeira vista, Tailwind e design system parecem opostos: classes utilitárias espalhadas pelo JSX contra um sistema centralizado. Na prática, eles se complementam, desde que você respeite uma regra:
As classes utilitárias vivem dentro dos componentes do design system. As telas consomem componentes, não utilitários.
Assim você ganha o que o Tailwind faz de melhor (velocidade, escala restrita de valores, CSS gerado em build time) sem o "sopão de classes" nas páginas.
Design tokens: a base
Tokens são valores nomeados (cores, espaçamentos, tipografia, raios, sombras) centralizados em um único lugar. No Tailwind v4, a configuração é CSS-first, feita com a diretiva @theme:
/* globals.css */
@import "tailwindcss";
@theme {
/* Remove a paleta padrão: só os tokens do sistema existem */
--color-*: initial;
--color-primary: #0b5fff;
--color-primary-hover: #0a4fd6;
--color-danger: #d92d20;
--color-danger-hover: #b42318;
--color-text: #101828;
--color-text-muted: #475467;
--color-surface: #ffffff;
--color-surface-muted: #f2f4f7;
--color-border: #d0d5da;
--radius-sm: 4px;
--radius-md: 8px;
--font-sans: "Inter", sans-serif;
}
Cada variável de tema gera automaticamente as utilitárias correspondentes: --color-primary vira bg-primary, text-primary, border-primary; --radius-md vira rounded-md. Ao zerar a paleta padrão com --color-*: initial, ninguém consegue usar bg-blue-500 por engano: se a cor não está nos tokens, ela não existe.
Quem ainda está no Tailwind v3 faz o equivalente em tailwind.config.ts:
// tailwind.config.ts (v3)
import type { Config } from 'tailwindcss';
export default {
content: ['./src/**/*.{ts,tsx}'],
theme: {
colors: {
primary: { DEFAULT: '#0B5FFF', hover: '#0A4FD6' },
danger: { DEFAULT: '#D92D20', hover: '#B42318' },
text: { DEFAULT: '#101828', muted: '#475467' },
surface: { DEFAULT: '#FFFFFF', muted: '#F2F4F7' },
border: '#D0D5DA',
},
borderRadius: { sm: '4px', md: '8px' },
fontFamily: { sans: ['Inter', 'sans-serif'] },
},
} satisfies Config;
Mudar a cor primária da marca vira uma alteração em um único lugar. Tokens também são a ponte natural com o design: o mesmo nome (primary, radius-md) aparece no Figma e no código.
Tokens semânticos e temas
Para suportar temas (claro/escuro, ou marcas diferentes), nomeie pelo papel, não pela aparência, e troque os valores por contexto:
@theme {
--color-surface: #ffffff;
--color-text: #101828;
}
@layer base {
[data-theme="dark"] {
--color-surface: #0c111d;
--color-text: #f5f5f6;
}
}
Os componentes continuam usando bg-surface text-text, e o tema muda sem tocar em nenhum deles.
Atomic Design: pensar em camadas
O Atomic Design, de Brad Frost, divide a interface em cinco níveis:
- Átomos: elementos indivisíveis, como
Button,Input,Label,Icon,Badge. - Moléculas: combinações simples de átomos com um propósito, como um
FormField(label + input + mensagem de erro) ou umaSearchBar(input + botão). - Organismos: seções completas e relativamente independentes, como um
Header, umaDataTable, umLoginForm. - Templates: o esqueleto de uma página, com layout e áreas definidas, mas sem dados reais.
- Páginas: templates preenchidos com dados reais.
components/
atoms/
Button/
Button.tsx
Button.stories.tsx
Button.test.tsx
index.ts
Input/
Badge/
molecules/
FormField/
SearchBar/
organisms/
DataTable/
Sidebar/
templates/
DashboardLayout/
lib/
cn.ts
A regra de ouro é a direção das dependências: átomos não conhecem moléculas, moléculas não conhecem organismos. A dependência só flui de baixo para cima.
Por que o design atômico facilita a vida
Implementação mais rápida
Antes de criar algo novo, você olha para baixo na hierarquia: "já existe um átomo ou uma molécula que resolve isso?". Na prática, uma tela nova costuma ser a composição de peças que já existem. O trabalho deixa de ser escrever CSS e passa a ser montar blocos.
Criação de componentes com critério
A pergunta "isso é um átomo, uma molécula ou um organismo?" força uma decisão de design a cada componente. Isso evita componentes gigantes, acoplados e cheios de props condicionais. Se algo não se encaixa, geralmente é sinal de que está fazendo coisas demais e deve ser dividido.
Alterações seguras e localizadas
Mudar o Button propaga a alteração para todos os organismos que o usam, de forma consistente. Como a dependência só flui de baixo para cima, o impacto de uma mudança é previsível: alterar um átomo afeta tudo acima dele, e alterar um organismo não afeta os átomos. Uma mudança de visual como bordas mais arredondadas passa a ser uma alteração de tokens, não uma refatoração de telas.
Testes mais simples
Átomos e moléculas têm poucas responsabilidades, então são fáceis de testar isoladamente e de documentar no Storybook. Cada estado (hover, foco, desabilitado, erro) vira uma story, que serve ao mesmo tempo de documentação, de teste visual e de playground para o design.
Onboarding mais rápido
O catálogo de componentes funciona como documentação viva. Uma pessoa nova no time consegue ver o que existe, como se usa e quais variações são permitidas, sem ler o código de dez telas.
Padronização de estilo com Tailwind
Duas bibliotecas pequenas resolvem os dois maiores problemas de usar Tailwind em componentes reutilizáveis: variantes e conflito de classes.
class-variance-authority(cva): declara variantes (variant,size) de forma tipada.tailwind-merge+clsx: permitem que o consumidor sobrescreva classes (className) sem gerar conflitos comopx-4 px-2no mesmo elemento.
O helper cn
// lib/cn.ts
import { clsx, type ClassValue } from 'clsx';
import { twMerge } from 'tailwind-merge';
export function cn(...inputs: ClassValue[]) {
return twMerge(clsx(inputs));
}
Átomo: Button
// components/atoms/Button/Button.tsx
import { cva, type VariantProps } from 'class-variance-authority';
import type { ButtonHTMLAttributes } from 'react';
import { cn } from '@/lib/cn';
const button = cva(
[
'inline-flex items-center justify-center gap-2 rounded-md font-medium transition-colors',
'focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-text',
'disabled:cursor-not-allowed disabled:opacity-50',
],
{
variants: {
variant: {
primary: 'bg-primary text-white hover:bg-primary-hover',
secondary: 'bg-surface text-text border border-border hover:bg-surface-muted',
danger: 'bg-danger text-white hover:bg-danger-hover',
},
size: {
sm: 'px-2 py-1 text-sm',
md: 'px-4 py-2 text-base',
},
},
defaultVariants: { variant: 'primary', size: 'md' },
},
);
export interface ButtonProps
extends ButtonHTMLAttributes<HTMLButtonElement>,
VariantProps<typeof button> {}
export function Button({ variant, size, className, type = 'button', ...props }: ButtonProps) {
return <button type={type} className={cn(button({ variant, size }), className)} {...props} />;
}
As variantes viram props tipadas (variant="primary" | "secondary" | "danger"), e o TypeScript recusa valores inexistentes. O className no final permite ajustes pontuais pelo consumidor, e o twMerge garante que o último valor vença.
Átomos: Label e Input
// components/atoms/Input/Input.tsx
import type { InputHTMLAttributes } from 'react';
import { cn } from '@/lib/cn';
export function Input({ className, ...props }: InputHTMLAttributes<HTMLInputElement>) {
return (
<input
className={cn(
'w-full rounded-md border border-border bg-surface px-3 py-2 text-text',
'placeholder:text-text-muted',
'focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-primary',
'aria-[invalid=true]:border-danger',
'disabled:bg-surface-muted',
className,
)}
{...props}
/>
);
}
Note o aria-[invalid=true]:border-danger: o estado visual de erro é derivado do atributo ARIA, o que mantém acessibilidade e estilo sincronizados por construção.
Molécula: FormField
// components/molecules/FormField/FormField.tsx
import type { InputHTMLAttributes } from 'react';
import { Input } from '@/components/atoms/Input';
type FormFieldProps = InputHTMLAttributes<HTMLInputElement> & {
id: string;
label: string;
error?: string;
};
export function FormField({ id, label, error, ...inputProps }: FormFieldProps) {
const erroId = `${id}-erro`;
return (
<div className="flex flex-col gap-1">
<label htmlFor={id} className="text-sm font-medium text-text">
{label}
</label>
<Input
id={id}
aria-invalid={!!error}
aria-describedby={error ? erroId : undefined}
{...inputProps}
/>
{error && (
<p id={erroId} role="alert" className="text-sm text-danger">
{error}
</p>
)}
</div>
);
}
Organismo: LoginForm
// components/organisms/LoginForm/LoginForm.tsx
import { Button } from '@/components/atoms/Button';
import { FormField } from '@/components/molecules/FormField';
export function LoginForm({ onSubmit, errors }: LoginFormProps) {
return (
<form onSubmit={onSubmit} className="flex w-full max-w-sm flex-col gap-4 rounded-md bg-surface p-6">
<FormField id="email" type="email" label="E-mail" error={errors?.email} />
<FormField id="senha" type="password" label="Senha" error={errors?.senha} />
<Button type="submit">Entrar</Button>
</form>
);
}
Repare que o organismo praticamente não tem decisões de estilo próprias: ele compõe moléculas e átomos e cuida do layout. É isso que torna a criação de telas rápida e consistente.
Armadilhas do Tailwind em design systems
- Classes dinâmicas não funcionam. O Tailwind encontra classes lendo o código-fonte como texto, então
`bg-${cor}`não gera nada. Use sempre nomes completos (como no mapa de variantes docva). - "Sopão de classes" nas páginas. Se uma tela precisa de dez utilitários para ficar certa, provavelmente falta um componente no sistema.
- Uso excessivo de
@apply. Ele recria o CSS tradicional dentro do Tailwind e esconde a vantagem das utilitárias. Prefira componentes React para reaproveitar estilos. - Valores arbitrários em excesso (
w-[137px],bg-[#123456]). Uma ou outra exceção é aceitável; muitas indicam tokens faltando. - Ordem das classes. Use o
prettier-plugin-tailwindcsspara ordenar automaticamente e evitar ruído em code reviews.
Acessibilidade desde os átomos
A acessibilidade deve entrar nos átomos, e não ser remendada depois. Se o Button já tem foco visível, o Input já se associa ao Label e o Modal gerencia o foco, todas as telas herdam essas garantias sem esforço extra.
Na prática, isso inclui:
- Contraste de cores validado nos tokens (WCAG AA como mínimo). Como as cores são centralizadas, basta corrigir uma vez.
- Navegação por teclado e ordem de foco coerente.
- Foco visível em todos os elementos interativos, com a variante
focus-visible:. - Semântica correta:
buttonpara ações,apara navegação,labelligado aoinput. - Atributos ARIA apenas quando o HTML nativo não basta (
aria-invalid,aria-describedby,role="dialog"). - Respeito a
prefers-reduced-motion, com as variantesmotion-reduce:emotion-safe:. - Texto para leitores de tela com a classe
sr-only, por exemplo em botões que só têm ícone.
<button aria-label="Fechar" className="rounded-md p-2 hover:bg-surface-muted">
<XIcon className="size-4" aria-hidden="true" />
<span className="sr-only">Fechar</span>
</button>
Para pegar regressões, combine jest-axe nos testes e as verificações de acessibilidade do Storybook.
Ganho de performance
A padronização também trouxe ganhos de performance, mesmo que esse não fosse o objetivo inicial:
- CSS gerado em build time: o Tailwind inclui no CSS final apenas as utilitárias que aparecem no código. O arquivo de estilos tende a ser pequeno e para de crescer conforme o produto cresce, já que as mesmas classes são reutilizadas.
- Zero JavaScript de estilo em runtime: diferentemente de soluções CSS-in-JS, não há geração de classes nem injeção de
<style>no navegador. Isso reduz o trabalho na renderização e combina bem com React Server Components e SSR, porque os componentes não precisam ser Client Components só por causa do estilo. - Menos CSS duplicado e menos componentes redundantes no bundle.
- Code splitting e lazy loading aplicados nos organismos mais pesados (tabelas, editores, gráficos), em vez de carregar tudo na primeira tela.
- Menos re-renderizações, graças a componentes pequenos e bem delimitados, combinados com
memoquando faz sentido.
Como em qualquer otimização, o ponto é medir: tamanho do CSS e do bundle, LCP e o profiler do React antes e depois.
Como conduzir uma refatoração grande
Refatorar mais de 80% de uma plataforma não acontece de uma vez. O que funcionou:
- Começar pelos tokens: definir o
@themee a convenção de nomes antes de qualquer componente. - Atacar os átomos mais usados (botões, inputs, tipografia), pois eles rendem a maior cobertura.
- Migrar por tela, não por componente isolado, trocando o legado pelo novo sistema de forma incremental, com os dois convivendo.
- Documentar no Storybook conforme os componentes nascem.
- Definir regras de contribuição: quando criar um componente novo, como propor mudanças e quem revisa.
- Automatizar a disciplina: ESLint para impedir utilitários fora do padrão, Prettier para ordenar classes e testes de acessibilidade na CI.
- Medir o progresso: porcentagem de telas migradas, quantidade de valores arbitrários no código, tamanho do bundle.
Algumas armadilhas:
- Over-engineering: criar variações que ninguém pediu. Comece com o necessário.
- Design system sem dono: sem responsáveis, ele apodrece. Precisa de governança leve, mas clara.
- Classificação obsessiva: não gaste tempo demais discutindo se algo é molécula ou organismo. A hierarquia é um guia, não uma lei.
Conclusão
Um design system escalável é a soma de pequenas decisões consistentes: tokens que centralizam os valores no @theme, camadas atômicas que organizam os componentes, variantes tipadas com cva e acessibilidade embutida nas peças básicas. O Tailwind entrega a velocidade e o CSS enxuto; o Atomic Design impede que essa velocidade vire bagunça. O retorno aparece em rapidez de entrega, em segurança para mudar e em uma experiência coerente para o usuário. O investimento inicial é real, mas ele se paga a cada tela que deixa de ser escrita do zero.