Construindo um Design System Escalável com React e Tailwind CSS

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 uma SearchBar (input + botão).
  • Organismos: seções completas e relativamente independentes, como um Header, uma DataTable, um LoginForm.
  • 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 como px-4 px-2 no 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 do cva).
  • "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-tailwindcss para 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: button para ações, a para navegação, label ligado ao input.
  • Atributos ARIA apenas quando o HTML nativo não basta (aria-invalid, aria-describedby, role="dialog").
  • Respeito a prefers-reduced-motion, com as variantes motion-reduce: e motion-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 memo quando 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:

  1. Começar pelos tokens: definir o @theme e a convenção de nomes antes de qualquer componente.
  2. Atacar os átomos mais usados (botões, inputs, tipografia), pois eles rendem a maior cobertura.
  3. Migrar por tela, não por componente isolado, trocando o legado pelo novo sistema de forma incremental, com os dois convivendo.
  4. Documentar no Storybook conforme os componentes nascem.
  5. Definir regras de contribuição: quando criar um componente novo, como propor mudanças e quem revisa.
  6. Automatizar a disciplina: ESLint para impedir utilitários fora do padrão, Prettier para ordenar classes e testes de acessibilidade na CI.
  7. 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.