# PRD — Layout do TUI com experiência similar ao OpenCode

## Rastreabilidade
- Orquestração: Precisamos que o layout em si do TUI tenha uma experiência similar à do OpenCode
- Slug: `precisamos-que-o-layout-em-si-do-tui-tenha-uma-experiencia-similar-a-do-opencode`
- Documento: PRD (Product Requirements Document)
- Risco: **medium** (`00-risk-classification.md`, fator `external_dependency`)
- Código impactado: `src/tui/ui.rs`, `src/tui/app.rs`, `src/tui/event.rs`, `src/tui/mod.rs`, `src/tui/loader.rs` (+ novo módulo de tema e novo módulo de palette)
- Subfluxo de design: `design-interview` (concluído), `experience-design`, `information-architecture`
- Etapa anterior: `01-idea.md`
- Estado: draft — **aguardando checkpoint humano**

## Resumo
Reformular a camada de apresentação e o modelo de entrada do SDD cockpit (TUI) para uma experiência **minimalista no estilo OpenCode**: borderless por padrão, conteúdo centrado com respiro, acento primário único, listas agrupadas por seção com barra de seleção full-width, **home com logo figlet**, e um **command palette flutuante** como porta de entrada das ações. O motor SDD (etapas, checkpoints, providers, persistência, rastreabilidade) permanece intacto — muda só como o usuário vê e dispara as ações.

Escopo confirmado no design-interview: **overhaul completo das 11 telas** · **estética + command palette** · **minimalista com telemetria sob demanda**.

## Objetivos
- **O-1**: Substituir a estética de painéis com `Borders::ALL` por um layout borderless/minimalista, centrado, com um sistema de tema central e acento primário único.
- **O-2**: Entregar uma **home/launcher** fiel à referência do OpenCode: logo figlet, versão, lista de comandos em colunas e input com `>`.
- **O-3**: Introduzir um **command palette** (overlay flutuante sobre fundo escurecido) com busca fuzzy e atalhos, capaz de disparar todas as ações principais do fluxo.
- **O-4**: Tornar o default de cada tela **minimalista**, movendo telemetria densa (tokens, routing por etapa, limites, budget) para overlays/expansão sob demanda.
- **O-5**: Reestilizar as 11 telas (`ProviderSetup`, `OrchestrationList`, `NewOrchestration`, `StageBoard`, `Running`, `Viewer`, `Checkpoint`, `RefinementPrompt`, `ErrorPanel`, `Help`, `Summary`) com o tema central.
- **O-6**: Garantir **degradação graciosa** em terminais estreitos/sem truecolor e **zero regressão** funcional.

## Não objetivos
- Não alterar o fluxo SDD, a ordem das etapas nem as regras de `can_navigate` (`stage.rs`).
- Não mudar contratos de artefatos, schemas (`schemas/artifact-sections.json`) ou a persistência em `docs/<slug>/`.
- Não trocar a stack de TUI (continua ratatui 0.29 + crossterm 0.28).
- Não adicionar suporte a mouse, temas customizáveis pelo usuário ou modo claro (follow-up).
- Não reescrever o motor de providers (`runner.rs`) nem a contabilização de tokens — apenas onde/como são exibidos.

## Usuários
- **U-1 — Operador SDD (primário)**: engenheiro/tech lead que roda o fluxo no terminal fora do editor/agent. Precisa de foco na ação corrente e acesso rápido a comandos.
- **U-2 — Avaliador (secundário)**: alguém vendo a camada SDD pela primeira vez; a home é o primeiro contato e precisa transmitir qualidade.

## Princípios de experiência (experience-design)
- **P-1 Calma**: um foco por tela; espaço negativo é recurso, não desperdício. Sem bordas competindo com conteúdo.
- **P-2 Acento único**: uma cor primária (estilo pêssego/laranja do OpenCode) para seleção e ação; o resto em neutros (branco/cinza). Cor carrega significado, não decora.
- **P-3 Hierarquia por peso e alinhamento**: nome em destaque, metadado esmaecido à direita, atalho em coluna alinhada — em vez de bordas para separar.
- **P-4 Descoberta progressiva**: o essencial sempre visível; o denso a um atalho de distância (palette/expansão).
- **P-5 Teclado em primeiro lugar**: toda ação tem atalho; o palette é a rede de segurança para quem não memorizou.
- **P-6 Resiliência**: nunca quebrar o layout — degradar com elegância quando faltam cores/largura/glifos.

## Arquitetura da informação (information-architecture)
- **Camada 0 — Casco persistente**: header minimalista (contexto + rota de provider) e footer (hint de ação à esquerda · modelo/rota à direita), inspirados no rodapé "enter send … modelo" do OpenCode.
- **Camada 1 — Tela de etapa/contexto**: conteúdo centrado e minimalista da tela ativa (home, lista, board, viewer, checkpoint…).
- **Camada 2 — Overlays flutuantes**: command palette, seletor de provider/modelo e painel de telemetria — modais centrados sobre fundo escurecido, com título à esquerda e `esc` à direita.
- **Mapa de comandos do palette** (mínimo): nova orquestração, abrir orquestração, trocar provider/modelo, executar/abrir etapa, aprovar checkpoint, regenerar artefato, editar no $EDITOR, alternar telemetria, ajuda, sair.

## Requisitos

### Requisitos funcionais
- **RF-01 — Tema central**: criar um módulo de tema (ex.: `src/tui/theme.rs`) com tokens de cor (primário, neutro-forte, neutro-fraco, sucesso, alerta, erro, fundo-overlay), e helpers de estilo (seleção full-width, cabeçalho de seção, label/valor). Toda a renderização passa a consumir o tema.
- **RF-02 — Borderless por padrão**: remover `Borders::ALL` como padrão; usar espaçamento, alinhamento e títulos/regras sutis. Bordas só onde agregam (ex.: caixa de input, contorno fino do overlay).
- **RF-03 — Barra de seleção full-width**: listas (`OrchestrationList`, `StageBoard`, `ProviderSetup`, palette) destacam o item selecionado com faixa de largura total no acento primário, substituindo `▸`/`▶`.
- **RF-04 — Home/launcher**: nova tela inicial com logo figlet "SDD" (ou equivalente), versão, e lista de comandos em colunas (comando em acento · descrição neutra · atalho esmaecido), com input `>` e footer de rota.
- **RF-05 — Command palette**: overlay flutuante acionável por atalho global (ex.: `/` ou `Ctrl+K`), com campo de busca fuzzy, lista de comandos agrupada/filtrável, navegação por `↑/↓`, execução por `Enter`, fechamento por `Esc`. Cada item mostra rótulo + atalho.
- **RF-06 — Telemetria sob demanda**: uso de tokens, tabela de roteamento por etapa, limites e budget saem do default do `StageBoard`/`Checkpoint`/`Running` e passam a um overlay/expansão acionável (ex.: tecla `t` ou item do palette "Telemetria").
- **RF-07 — Listas agrupadas**: o seletor de provider/modelo exibe modelos agrupados por seção (cabeçalho colorido), tags à direita (ex.: estado de auth, "free"/budget), e marcador no item ativo, espelhando o "Select model".
- **RF-08 — Footer/rodapé consistente**: hint de ação contextual à esquerda e rota provider/modelo à direita em todas as telas.
- **RF-09 — Overlays escurecem o fundo**: ao abrir palette/seletor/telemetria, o conteúdo de trás é atenuado (dim) para foco, como no OpenCode.
- **RF-10 — Paridade de ações**: nenhuma ação hoje disponível por tecla pode ser perdida; toda ação existente continua acessível (por tecla e/ou pelo palette).

### Regras de negócio
- **RN-01**: o palette e os overlays são camada de apresentação/entrada; **não** alteram a máquina de estados nem `can_navigate`. Uma ação inválida no contexto (ex.: aprovar etapa sem artefato) é bloqueada com a mesma regra de domínio atual e mensagem clara.
- **RN-02**: checkpoints humanos continuam obrigatórios (PRD, Tech Spec, Refinement quando o risco exigir, Merge). Nenhuma mudança de UI pode auto-aprovar etapa.
- **RN-03**: minimalismo não pode esconder informação **crítica de decisão** de checkpoint (artefato, critério, provider/rota) — essa permanece visível; só telemetria de consumo vai para sob demanda.
- **RN-04**: o tema deve ter fallback de 16 cores quando truecolor não estiver disponível; ausência de glifos não pode produzir layout quebrado.
- **RN-05**: idioma PT-BR com acentos preservados em toda copy de interface; ASCII apenas em identificadores/atalhos/paths.

### Não funcionais
- **NF-01 Performance**: render permanece fluido; sem custo perceptível de redraw (manter a abordagem de funções puras de desenho de `ui.rs`).
- **NF-02 Compatibilidade**: funciona nas larguras 40/80/120 cobertas pelos testes atuais; sem panic em nenhuma tela/overlay.
- **NF-03 Acessibilidade de terminal**: contraste suficiente entre acento e fundo; não depender só de cor para estado (usar também peso/símbolo/posição).
- **NF-04 Manutenibilidade**: estilos centralizados no tema; telas não definem cores literais ad-hoc.

## Critérios de aceite
Escritos em Gherkin (ver skill `bdd-gherkin`).

```gherkin
Funcionalidade: Home/launcher estilo OpenCode

  Cenário: Primeira tela exibe identidade e comandos
    Dado que abro o TUI sem orquestração ativa
    Quando a home é renderizada
    Então vejo um logo figlet centralizado e a versão do SDD
    E vejo uma lista de comandos em colunas (comando, descrição, atalho)
    E vejo um campo de input iniciado por ">"
    E o rodapé mostra a rota de provider/modelo à direita

  Cenário: Home degrada em terminal estreito
    Dado um terminal com largura 40
    Quando a home é renderizada
    Então o conteúdo permanece legível e sem panic
    E o logo é simplificado ou omitido sem quebrar o layout
```

```gherkin
Funcionalidade: Command palette

  Cenário: Abrir o palette e filtrar comandos
    Dado que estou em qualquer tela do TUI
    Quando aciono o atalho do command palette
    Então um overlay flutuante abre centralizado sobre o fundo escurecido
    E há um campo de busca com foco
    E ao digitar parte do nome de um comando a lista é filtrada por fuzzy match

  Cenário: Executar um comando pelo palette
    Dado que o command palette está aberto com comandos filtrados
    Quando seleciono "Nova orquestração" e pressiono Enter
    Então o palette fecha
    E a ação correspondente é disparada (mesmo efeito da tecla atual)

  Cenário: Ação inválida no contexto é bloqueada
    Dado que a etapa atual ainda não tem artefato gerado
    Quando seleciono "Aprovar checkpoint" no palette
    Então a ação é recusada com a mesma regra de domínio atual
    E vejo uma mensagem explicando o bloqueio
    E nenhum estado de etapa é alterado

  Cenário: Fechar o palette
    Dado que o command palette está aberto
    Quando pressiono Esc
    Então o overlay fecha e o fundo volta ao normal
    E permaneço na mesma tela de antes
```

```gherkin
Funcionalidade: Estética minimalista e tema central

  Cenário: Telas sem bordas densas por padrão
    Dado que navego pelas 11 telas do TUI
    Então nenhuma usa "Borders::ALL" como moldura padrão de conteúdo
    E a seleção em listas aparece como barra full-width no acento primário
    E o acento primário é o mesmo em todas as telas

  Cenário: Seletor de provider agrupado por seção
    Dado que abro o seletor de provider/modelo
    Então os modelos aparecem agrupados por seção com cabeçalho colorido
    E o item ativo tem um marcador
    E tags de estado (auth/budget) aparecem alinhadas à direita
```

```gherkin
Funcionalidade: Telemetria sob demanda

  Cenário: Default minimalista no board de etapas
    Dado que abro uma orquestração no StageBoard
    Então a tela mostra a etapa, seu estado e a ação principal
    E não mostra por padrão tabela de roteamento, limites ou uso de tokens

  Cenário: Expandir telemetria
    Dado que estou no StageBoard
    Quando aciono o comando/atalho de telemetria
    Então um overlay exibe uso de tokens, roteamento por etapa, limites e budget
    E ao fechá-lo volto ao default minimalista
```

```gherkin
Funcionalidade: Sem regressão funcional

  Cenário: Fluxo e checkpoints preservados
    Dado o novo layout aplicado
    Quando percorro Ideia → PRD → Tech Spec → ... → Memória
    Então os checkpoints humanos continuam obrigatórios e funcionais
    E a persistência de artefatos em docs/<slug>/ permanece inalterada

  Cenário: Testes de render passam
    Dado as larguras 40, 80 e 120
    Quando executo "cargo test"
    Então os testes de render de todas as telas e overlays passam sem panic
```

## Métricas
- **M-1 (sucesso de design)**: 11/11 telas migradas para o tema central; 0 ocorrências de `Borders::ALL` como moldura padrão de conteúdo (verificável por grep + revisão visual).
- **M-2 (cobertura do palette)**: 100% das ações hoje acessíveis por tecla também acionáveis pelo palette (checklist de paridade RF-10).
- **M-3 (minimalismo)**: telemetria ausente do default em `StageBoard`/`Checkpoint`/`Running`; acessível em ≤ 1 atalho.
- **M-4 (robustez)**: `cargo test` verde, incluindo testes de render em 40/80/120 e novos testes de overlay; 0 panics.
- **M-5 (fidelidade)**: revisão visual (`visual-review`) aprova home e seletor contra as referências do OpenCode no checkpoint de merge.

## Riscos
- **R1 (external_dependency / NF-02, NF-03)**: terminais variam em truecolor/largura/glifos. **Mitigação**: tema com fallback 16-cores; logo figlet com versão reduzida; testes em 40/80/120.
- **R2 (regressão visual)**: `ui.rs` tem 1484 linhas e testes de snapshot de render. **Mitigação**: introduzir tema sem mudar contrato das funções de render; estender testes `renders_all_screens_no_panic` para overlays.
- **R3 (complexidade de input)**: palette adiciona estado e roteamento de teclas em `app.rs`/`event.rs`. **Mitigação**: modelar palette como overlay com estado próprio e captura de teclas isolada; mapa de comandos declarativo.
- **R4 (informação escondida)**: operadores podem sentir falta de budget/limites. **Mitigação**: descoberta explícita (hint no footer + item fixo no palette "Telemetria").
- **R5 (escopo grande)**: overhaul completo é a opção de maior esforço. **Mitigação**: Tech Spec deve sequenciar (tema → casco → home → palette → telas → telemetria) para entregas incrementais verificáveis.

## Próxima etapa
Tech Spec (`03-techspec.md`): arquitetura do módulo de tema, modelo de estado do palette/overlays, contratos de render, plano de implementação incremental e estratégia de testes. **Checkpoint humano obrigatório após a Tech Spec.**
