> For the complete documentation index, see [llms.txt](https://kosmos.letras.mus.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kosmos.letras.mus.br/diretrizes-de-interface/product-design-letras.md).

# Product Design · Letras

Repositório de **protótipos e handoffs** do time de design da Letras.

Aqui vivem os fluxos reais do produto: telas, estados, jornadas, com vistas para stakeholders e times de tecnologia.

***

## Estrutura

```
ds/                          # submódulo do Kósmos (Design System), pinado por commit
fluxos/                      # fluxos ativos
  <slug-do-fluxo>/
    meta.yml                 # estado, dono, ds_pin, áreas envolvidas
    telas/
      01-<slug>.html
      02-<slug>.html
    estados/                 # loading, vazio, erro, sem permissão, etc.
    handoff/
      stakeholder.html       # vista navegável para apresentação
      tech.md                # vista estruturada para devs
    learnings.md             # gerado quando arquiva
arquivo/                     # fluxos arquivados, reativáveis
```

## Ciclo de vida de um fluxo

```
draft → review → shipped → archived
```

* **draft** — em construção
* **review** — aberto pra peer review
* **shipped** — handoff entregue pros devs (transição via PR no GitHub, aprovação obrigatória de outro designer)
* **archived** — produto subiu em produção (transição manual, reativável)

## Como começar um fluxo novo

1. `cd fluxos && mkdir <slug-do-fluxo>`
2. No Claude Code, dispare a skill `intake-flow` apontando pro HTML produzido no Claude Design + spec textual livre
3. Skill gera `meta.yml` estruturado, valida componentes via DS, sugere estados a tratar

## Submódulo do DS

O Kósmos vive em [Letras-mus-br/Kosmos](https://github.com/Letras-mus-br/Kosmos) e é referenciado aqui via submódulo git pinado por commit. Isso garante que fluxos arquivados continuem funcionando mesmo se o DS evoluir.

Pra atualizar o pin pra última versão do DS:

```bash
cd ds && git checkout main && git pull
cd .. && git add ds && git commit -m "bump DS pin"
```

(A skill `bump-ds` automatiza isso.)

## Plano e contexto

A arquitetura completa, decisões registradas e roadmap estão documentados no Kósmos:

* [`.claude/PLANO-EVOLUCAO.md`](https://github.com/Letras-mus-br/Kosmos/blob/main/.claude/PLANO-EVOLUCAO.md) — log de decisões
* [`.claude/apresentacao.html`](https://github.com/Letras-mus-br/Kosmos/blob/main/.claude/apresentacao.html) — apresentação visual

## Observação sobre o histórico

Este repositório era originalmente o conteúdo Gitbook do Design System (`.gitbook/`, `componentes/`, `estilos/`, `fundacoes/`, `recursos/`). Esse conteúdo foi removido em **Maio/2026** quando o repositório foi reposicionado como o repo de protótipos. O histórico antigo continua acessível via `git log`.