---
id: generate-documentation
agent: ux-design-expert
title: Gerar a documentação da pattern library
inputs: [design-system, componentes, tokens]
outputs: [pattern library documentada, índice navegável, File List atualizada]
elicit: false
modes: [interactive, yolo]
---

# Gerar a documentação da pattern library

**Objetivo:** transformar o design system construído (tokens, átomos, moléculas, organismos) em uma
pattern library documentada e navegável — cada componente com uso, anatomia, variantes e regras de a11y.

**Pré-condições:**
- O design system existe (`*setup` rodou) e há ao menos um componente construído. Se não há nada
  construído, **pare** — não documento o vazio.
- Os componentes a documentar estão em produção e passaram no checklist de qualidade (testes + a11y).
  Documento o que está pronto, não o rascunho.

## Passos

1. **Inventario o que existe** no design system: tokens, átomos, moléculas, organismos. Cada um vira
   uma entrada na pattern library. Cruzo com a story/spec para garantir que documento só o real.
2. **Documento os design tokens primeiro** — a fundação: cor, tipografia, espaçamento, raio. Mostro o
   nome do token, o valor e onde se aplica. Tokens são o vocabulário; vêm antes dos componentes.
3. **Para cada componente, escrevo a ficha:**
   a. **anatomia** — partes e props do componente;
   b. **variantes** — cada variante com exemplo visual/código e o token que a alimenta;
   c. **quando usar / quando não usar** — a regra que evita uso errado;
   d. **a11y** — comportamento de foco, teclado, semântica e contraste garantido.
4. **Puxo os exemplos do código real**, não invento snippet. Cada exemplo reflete o componente como
   ele existe — doc que diverge do código é pior que nenhuma doc.
5. **Monto o índice navegável** organizado por nível Atomic (tokens → átomos → moléculas → organismos),
   com links cruzados (uma molécula referencia os átomos que a compõem).
6. **Verifico a cobertura:** todo componente em produção tem ficha; nenhuma ficha referencia componente
   inexistente. Sinalizo lacunas em vez de inventar.
7. **Salvo a pattern library** no destino do design system, **atualizo a File List** da story e faço
   **commit local** (conventional commit com o id da story). **Nunca** `git push` — delego a publicação
   (ex.: deploy do site da pattern library) ao @devops.

## Critério de pronto (DoD)

- [ ] Todos os tokens documentados (nome, valor, aplicação)
- [ ] Todo componente em produção tem ficha: anatomia, variantes, uso/não-uso, a11y
- [ ] Exemplos puxados do código real — nenhum snippet inventado
- [ ] Índice navegável por nível Atomic, com links cruzados
- [ ] Nenhuma ficha referencia componente inexistente
- [ ] File List atualizada e commit local feito (sem `git push`)

## Falha / recuperação

- **Um componente não passou no checklist de qualidade (a11y/testes)** → não documento como "pronto";
  marco como pendente e sinalizo, ou aguardo ele ficar pronto.
- **A doc diverge do código** (exemplo desatualizado) → corrijo a doc para refletir o código; nunca o
  contrário sem story.
- **Encontro componente sem story/spec por trás** → sinalizo como dívida de rastreabilidade em vez de
  legitimar via doc.
- **Publicação/deploy do site da pattern library** → delego ao @devops; eu gero a doc, ele sobe.