docs: spec do redesign do front-end (React + design system)

2026-08-08 19:02:25 -03:00
1 parent 37270eab02
commit 2c16ffa2c0
@@ -0,0 +1,138 @@
+# 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).