Design system do zero: tokens, componentes e governança

1. Fundamentos de um Design System

Um design system é um conjunto integrado de princípios, padrões e artefatos reutilizáveis que orientam a criação de produtos digitais. Seus objetivos principais são três: consistência (experiência uniforme em todas as telas), escalabilidade (crescimento controlado do ecossistema de componentes) e eficiência (redução do retrabalho entre design e desenvolvimento).

É fundamental distinguir três conceitos frequentemente confundidos:
- Style Guide: documento estático com regras visuais (cores, tipografia, espaçamentos)
- Pattern Library: coleção de componentes de interface reutilizáveis
- Design System: sistema vivo que combina style guide + pattern library + processos de governança + documentação interativa

Criar um design system do zero é recomendado quando a organização possui necessidades específicas não atendidas por soluções prontas (Material Design, Ant Design, Chakra UI), como requisitos de acessibilidade avançados, identidade visual muito particular ou necessidade de integração com sistemas legados.

2. Tokens de Design: a Base Atômica

Tokens são as menores unidades de decisão de design. Eles seguem uma hierarquia em três níveis:

Global tokens — valores brutos, sem contexto semântico:

--color-blue-500: #3B82F6
--color-red-500: #EF4444
--spacing-4: 16px
--font-size-lg: 18px

Alias tokens — mapeiam tokens globais para contextos semânticos:

--color-primary: var(--color-blue-500)
--color-error: var(--color-red-500)
--spacing-container: var(--spacing-4)
--font-size-body: var(--font-size-lg)

Component tokens — específicos para componentes:

--button-bg: var(--color-primary)
--button-padding: var(--spacing-container)
--button-text-size: var(--font-size-body)

Estratégia de nomenclatura recomendada: usar o padrão [categoria]-[propriedade]-[variante] com hífens, em minúsculas. Para versionamento, armazene tokens em arquivos JSON ou YAML, com versionamento semântico nos pacotes publicados.

Exemplo de arquivo de tokens (formato JSON):

{
  "global": {
    "color": {
      "blue": { "500": "#3B82F6" },
      "red": { "500": "#EF4444" }
    },
    "spacing": { "4": "16px" }
  },
  "alias": {
    "primary": "color.blue.500",
    "error": "color.red.500"
  },
  "component": {
    "button": {
      "bg": "alias.primary",
      "padding": "spacing.4"
    }
  }
}

3. Construção de Componentes: do Atômico ao Organismo

A metodologia atômica organiza componentes em quatro níveis:

Átomos — elementos básicos indivisíveis:

// Botão primitivo
<button class="btn btn--primary">Clique aqui</button>

Moléculas — combinação de átomos:

// Campo de busca (input + botão + ícone)
<div class="search-field">
  <input type="text" class="input" />
  <button class="btn btn--icon">
    <span class="icon icon--search"></span>
  </button>
</div>

Organismos — seções complexas:

// Card de produto (imagem + título + preço + botão)
<div class="product-card">
  <img src="produto.jpg" class="product-card__image" />
  <h3 class="product-card__title">Produto X</h3>
  <span class="product-card__price">R$ 99,90</span>
  <button class="btn btn--primary">Comprar</button>
</div>

Templates — layouts que posicionam organismos.

Para criar variantes, utilize props ou atributos de dados:

<button class="btn" data-size="small" data-variant="outline">
  Salvar
</button>

4. Documentação e Consumo com Ferramentas Modernas

Storybook é a ferramenta padrão para documentação viva. Cada componente deve ter sua própria história (story) demonstrando todos os estados possíveis:

// Exemplo de story para botão
export const Primary = () => <Button variant="primary">Primary</Button>
export const Disabled = () => <Button disabled>Disabled</Button>
export const Loading = () => <Button loading>Carregando</Button>

Para versionamento, utilize semantic release com commits padronizados (feat, fix, breaking). Publique o pacote via npm ou em um monorepo com ferramentas como Nx ou Turborepo.

Estrutura de pacote recomendada:

@empresa/design-system/
├── tokens/
│   └── index.json
├── components/
│   ├── Button/
│   │   ├── Button.tsx
│   │   ├── Button.stories.tsx
│   │   └── Button.test.tsx
│   └── index.ts
├── package.json
└── README.md

5. Governança e Manutenção do Sistema

A governança garante que o sistema evolua de forma controlada. Estabeleça:

Processo de revisão:
1. Proposta (issue ou RFC) descrevendo necessidade
2. Aprovação do comitê de design system
3. Implementação com testes
4. Revisão de código por pares
5. Homologação visual (Chromatic/Percy)
6. Publicação com changelog

Papéis definidos:
- Designer líder: define tokens e padrões visuais
- Desenvolvedor mantenedor: implementa e revisa componentes
- Comitê de governança: aprova mudanças e define prioridades

Estratégia de depreciação:

// Versão 1.0 — componente ativo
// Versão 1.1 — adiciona depreciação (log warning)
console.warn('ButtonLegacy será removido na v2.0. Use Button');

// Versão 2.0 — remove componente

6. Testes e Garantia de Qualidade

Testes visuais com Chromatic ou Percy capturam regressões visuais automaticamente:

// Chromatic storybook addon
import { storiesOf } from '@storybook/react';
storiesOf('Button', module)
  .add('Primary', () => <Button variant="primary">Salvar</Button>)

Testes unitários com Jest + Testing Library:

test('renderiza botão com texto', () => {
  render(<Button>Clique</Button>);
  expect(screen.getByText('Clique')).toBeInTheDocument();
});

Testes de acessibilidade com axe-core:

test('botão não tem violações de acessibilidade', async () => {
  const { container } = render(<Button>Acessível</Button>);
  const results = await axe(container);
  expect(results).toHaveNoViolations();
});

Validação de tokens automatizada com scripts que verificam conformidade com o design spec:

// Script de validação
const tokens = require('./tokens.json');
const expectedColors = ['primary', 'secondary', 'error'];
expectedColors.forEach(color => {
  if (!tokens.alias[color]) {
    console.error(`Token alias "${color}" ausente`);
  }
});

7. Adoção e Escalabilidade no Time

Plano de migração em fases:
1. Fase 0: Setup do design system (tokens, componentes básicos)
2. Fase 1: Componentes críticos (botões, inputs, cards) — time piloto
3. Fase 2: Componentes de página (headers, modais, tabelas)
4. Fase 3: Substituição gradual de código legado

Treinamento e onboarding:
- Workshop inicial de 2 horas sobre tokens e componentes
- Documentação interativa no Storybook com playground
- Exemplos reais de uso em projetos

Métricas de sucesso:
- Redução de 40% no tempo de desenvolvimento de novas telas
- Aumento de 90% na consistência visual (medido por auditoria visual)
- Reuso de 70% dos componentes entre diferentes produtos

Referências