---
id: setup-design-system
agent: ux-design-expert
title: Inicializar a estrutura do design system
inputs: [design tokens, story/spec de design system]
outputs: [estrutura Atomic Design inicializada, docs/design-system/]
elicit: false
modes: [interactive, yolo]
---

# Inicializar a estrutura do design system

**Objetivo:** criar o esqueleto do design system seguindo Atomic Design (átomo → molécula →
organismo → template → página), já cabeado aos design tokens, para que cada componente novo nasça
consistente e sem valor hardcoded.

**Pré-condições:**
- Os design tokens já existem (`extract-tokens` rodou) em `docs/design-system/tokens/`. Sem
  tokens, **pare**: estrutura sem fonte de verdade vira hardcode disfarçado.
- Existe story/spec que pede o design system. Sem rastro, elicito — não invento arquitetura.
- A decisão de stack de frontend (framework/bibliotecas) já é da Aria (@architect). Se ainda não
  houver, **delego a decisão técnica** antes de cabear a estrutura a um framework.

## Passos

1. **Confirmo a stack** decidida pelo @architect (ex.: framework de componente, formato de estilo).
   Eu não escolho stack sozinha — trago a lente de UX e uso a decisão dele.
2. **Crio a árvore Atomic Design** em `docs/design-system/`:
   - `tokens/` (já existente, da extração)
   - `atoms/` (componentes atômicos)
   - `molecules/` (composições de átomos)
   - `organisms/` (composições de moléculas)
   - `templates/` e `pages/` (estrutura de layout)
   - `docs/` (pattern library gerada depois)
3. **Cabeio os tokens** ao ponto de entrada do design system (import/registro dos tokens como fonte
   de cor/espaçamento/tipografia), de forma que nenhum componente futuro precise de hex solto.
4. **Defino as convenções mínimas**: padrão de nomenclatura, estrutura de cada componente
   (componente + teste + tokens + a11y), e o índice de exportação. Documento isso num `README` da
   pasta para quem construir depois seguir.
5. **Crio o checklist de qualidade do componente** como referência (passa em WCAG AA, usa só tokens,
   tem teste) apontando para `accessibility-wcag-checklist` — todo átomo nasce contra esse critério.
6. **Registro os arquivos criados** na File List da story.
7. **Roteio.** Estrutura pronta habilita `build-component` e `compose-molecule`. Integração na
   aplicação além do design system é do @dev; subida é do @devops.

## Critério de pronto (DoD)

- [ ] Árvore Atomic Design criada em `docs/design-system/` (atoms → pages + docs)
- [ ] Tokens cabeados como fonte única; nenhum ponto exige valor hardcoded
- [ ] Convenções de nomenclatura/estrutura e índice de exportação documentados no README
- [ ] Checklist de qualidade do componente referenciado (a11y + tokens + teste)
- [ ] Stack confirmada com o @architect (não decidida por mim); File List atualizada

## Falha / recuperação

- **Tokens ausentes** → HALT; volto à `extract-tokens` antes de montar a estrutura.
- **Stack de frontend indefinida** → delego a decisão à Aria (@architect) e pauso o setup até ter a
  resposta — não escolho framework sozinha.
- **Estrutura já existe parcialmente** → não sobrescrevo; reconcilio com o que há e registro o que
  foi adicionado, sem destruir trabalho anterior.