Documentation

Documentation

Garantir que todo componente novo ou alterado tenha documentação no Storybook no mesmo ciclo de entrega.

Fluxo Obrigatório

1. Identificar nome do componente e pasta de docs em docs/components/<ComponentName>/.
2. Criar ou atualizar *.stories.js do componente.
3. Criar stories para variantes existentes (quando houver variants).
4. Criar ou atualizar *.docs.mdx.
5. Descrever caso de uso geral do componente e caso de uso por variante.
6. Validar consistência entre stories e implementação real.

Regras para Stories

Aplicar em docs/components/<ComponentName>/<ComponentName>.stories.js:

• Definir title: 'Components/<ComponentName>'.
• Incluir import de CSS base usado no projeto:
  • packages/lets-ui-tokens/dist/letsui.tokens.css
  • packages/styles/dist/letsui.css
• Criar story principal com Template.bind({}) e args padrão.
• Se o componente tiver variantes (variant, size, state etc.), criar uma story por variante relevante.
• Não inventar variantes que não existam no componente.

Regras para Docs MDX

Aplicar em docs/components/<ComponentName>/<ComponentName>.docs.mdx:

• Incluir Meta apontando para o arquivo de stories.
• Documentar uma seção inicial com o caso de uso geral do componente.
• Para cada variante com story dedicada, incluir:
  • título da variante
  • descrição curta de quando usar
  • Canvas da story correspondente
• Incluir Controls da story principal quando fizer sentido.

Caso de Uso (Obrigatório)

Escrever duas camadas de descrição:

• Componente (geral): para que serve e em que contexto usar.
• Variante (story): quando escolher aquela opção em vez das demais.

Manter descrição objetiva, orientada a decisão de uso.

Critérios Adicionais Recomendados

Além dos critérios solicitados, aplicar:

• Cobrir estados críticos em stories (ex.: disabled, error, loading) quando existirem.
• Garantir que nomes de stories sejam claros e consistentes com o design system.
• Evitar divergência entre argTypes, args e API real do componente.
• Remover stories obsoletas quando variantes forem removidas do componente.
• Preservar acessibilidade básica nas demos (semântica e atributos ARIA quando aplicável).

Checklist de Entrega

• Arquivo de stories criado/atualizado.
• Stories de variants existentes criadas.
• Arquivo MDX criado/atualizado.
• Caso de uso geral documentado.
• Caso de uso por variante documentado.
• Sem inconsistência entre documentação e implementação.

Referências

• Ler references/storybook-documentation-patterns.md para template de stories/docs.

Source: mateusvillain/lets-ui — distributed by TomeVault.