# Design — Reformulação do Front-end (Transcript)

> Data: 2026-08-08 · Status: aprovado pelo usuário · Escopo: front-end completo, marca intocada

## Contexto

O Transcript é um app desktop Tauri 2 (Windows/Linux) de ditado por voz com transcrição local
(whisper.cpp / sidecar sherpa-onnx) ou via API OpenAI-compatible, inserção automática de texto e
assistente de IA (normalização / engenharia de prompt).

O front-end atual é TypeScript vanilla com DOM imperativo (`src/app.ts`, ~1930 linhas) e CSS puro
(`src/styles.css`, ~35KB, dark glass/acrylic). O usuário considera o resultado final desagradável e
mal distribuído e pediu uma reformulação completa com design system próprio, design book e
reavaliação do encaixe das funcionalidades. O front-end será reescrito por 2-3 agentes especialistas.

## Decisões (consolidadas com o usuário)

| Tema | Decisão |
|---|---|
| Escopo | Janela principal + configurações + overlay de ditado + identidade visual. **Marca/logo/nome intocados.** |
| Stack | **React 19 + Vite + TypeScript** (reescrita completa da camada de UI) |
| Estilo | **Tailwind CSS v4** — tokens do design system em `@theme` |
| Design book | **Storybook 8** (galeria viva de componentes) + **markdown** em `docs/design-book/` (princípios, tokens, diretrizes) |
| Agentes | Fase 1: **concorrência** (3 direções visuais em mockups HTML) → usuário escolhe. Fase 2: **divisão de trabalho** (design system / telas / design book) |
| Tema visual | **Dark-first**; tokens em camadas para suportar tema claro futuro barato |
| Layout | **Compacto expandível**: janela maior com abas (Texto, Histórico, Configurações), painéis expansíveis |
| Backend | Rust/Tauri **intocado**; todos os comandos `invoke` mantêm assinatura atual |

## 1. Arquitetura técnica

### Stack

- React 19, Vite 7 (já presente), TypeScript 5.9 (já presente).
- Tailwind v4: tokens em `@theme` via CSS custom properties; classes utilitárias nos componentes.
- Storybook 8 como projeto irmão (roda no navegador, não interfere no app).
- Vitest + Testing Library para testes de componente/contrato.
- `lucide-static` → `lucide-react` (mesma família de ícones, API React).
- Remover `@hypabolic/pi-hypa` (dependência morta — nenhum uso em `src/`).

### Estrutura de pastas (substitui `src/app.ts` e `src/styles.css`)

```
src/
  main.tsx                  # entry React
  app/
    App.tsx                 # shell: topbar frameless + abas + overlay de ditado
    screens/                # EditorView, HistoryView, SettingsView
    components/             # componentes de tela (composição local)
    state/                  # useDictationMachine, useSettings, useSnapshot
  ui/                       # DESIGN SYSTEM (primitivos reutilizáveis)
    Button.tsx, IconButton.tsx, Field.tsx, Select.tsx, Tabs.tsx,
    Modal.tsx, Pill.tsx, Card.tsx, Waveform.tsx, Kbd.tsx,
    Disclosure.tsx, EmptyState.tsx, Message.tsx, …
    tokens.css              # @theme: cores (dark+light), tipografia, espaço,
                            # raio, sombra, motion, z-index
  lib/
    tauri.ts                # cliente tipado: interface NativeClient → invoke
  styles.css                # base (reset, body, scrollbar, focus)
```

### Infra (Tauri)

- `src-tauri/tauri.conf.json`: janela `resizable: true`, tamanho inicial ~640×520,
  mínimo ~420×360. Overlay de ditado continua **na mesma janela** (seção sobreposta).
- CSP atual já libera `style-src 'unsafe-inline'` — nenhuma mudança necessária para Tailwind.
- Backend Rust: nenhuma mudança funcional.

### Testes

- `src/app.test.ts` atual (DOM vanilla) é **substituído** por testes Testing Library que cobrem os
  mesmos contratos observáveis: fluxo de ditado (estados da máquina), persistência de settings,
  navegação por abas, ações do editor, a11y básica (aria, foco, teclado).

## 2. Fase de concorrência — direções visuais

Três agentes designers rodam em paralelo; cada um entrega, **sem tocar no código real**:

1. **Mockups estáticos em HTML** (arquivos em `design/proposals/<nome>/`):
   - Janela principal em 2 estados (vazio e com texto);
   - Configurações (estrutura de abas);
   - Overlay de ditado em 2 estados (gravando e revisão);
   - Histórico.
2. **Direção estética em tokens CSS**: bloco `:root` com paleta, tipografia, raio, sombra,
   motion + parágrafo de conceito.
3. **Mapa funcionalidade → superfície**: onde cada funcionalidade atual fica na nova interface,
   com racional (ver §4).
4. **3 prós + 3 contras** da proposta.

Critérios de escolha (usuário decide com parecer do agente principal):
coerência com o produto (utilitário rápido: hotkey → fala → insere), legibilidade,
acessibilidade, viabilidade técnica do mapa de funcionalidades.

## 3. Design system

- **Tokens em `@theme`** (Tailwind v4), dark-first com camada light:
  - Cores: bg base/elevada/forte, fg, accent, semânticas (success/warning/danger);
  - Tipografia: escala tipográfica e fontes (herdar família atual Aptos/Segoe UI como base);
  - Espaçamento (base 4px), raio, sombra, motion (duração/easing), z-index, focus ring.
- **Primitivos** (todos documentados no Storybook):
  Button (primary/secondary/ghost/danger × tamanhos), IconButton, Field, Select, TextArea,
  Tabs, Modal, Pill, Card, Waveform, Kbd, Disclosure, EmptyState, Message.
- **Padrão de componente**: props tipadas; variantes limitadas; estados hover/focus/disabled/
  loading; acessibilidade obrigatória (aria, foco visível, navegação por teclado).
- Contrato de tokens e primitivos é **fixado antes** da implementação paralela (fase 2), para
  que os agentes não divirjam.

## 4. Reorganização funcional

| Funcionalidade | Hoje | Proposta |
|---|---|---|
| Hotkey global + ditado | Overlay island | Overlay refeito (waveform, estados claros, revisão inline) |
| Editor + Copiar/Inserir/Salvar/Limpar | Tela única | Aba "Texto", ações contextuais |
| Refinar com IA (normalizar/criar prompt) | Painel fixo | Painel expansível no editor (proposta dos agentes) |
| Histórico de áudios | Disclosure | Aba "Histórico" (lista + baixar último) |
| Diagnóstico | Disclosure | Dentro de Histórico ou ajuda |
| Configurações (5 grupos) | Modal único | Modal com abas (Ditado, Transcrição, Assistente, Áudios) |
| Continuar/Regravar/Expandir | Botões secundários | Reavaliar (ex.: menu de contexto no editor) |

## 5. Design book

- **Storybook 8**: todos os primitivos com variantes, estados, a11y; addon de tokens.
- **Markdown** em `docs/design-book/`: princípios, tabela de tokens (gerada do código),
  diretrizes de uso e contribuição (como adicionar componente/token).

## 6. Qualidade e verificação

- Testes reescritos (contratos de UI), `npm run typecheck`, `npm run build`, build do Storybook.
- Verificação manual: `npm run tauri:dev` — fluxo completo (hotkey global → grava → overlay →
  revisão → inserção) e cada aba/tela.
- Fase final: um agente especialista audita o resultado contra o design book (consistência).

## Fora de escopo (v1)

- Marca/logo/nome do produto.
- Janela separada para o overlay de ditado (multi-window Tauri).
- Tema claro ativo (apenas tokens preparados).
- Mudanças funcionais no backend Rust.
- Histórico de transcrições persistente (roadmap futuro; hoje só áudios recentes).