diff --git a/docs/superpowers/specs/2026-08-08-frontend-redesign-design.md b/docs/superpowers/specs/2026-08-08-frontend-redesign-design.md new file mode 100644 index 0000000..caeaf0b --- /dev/null +++ b/docs/superpowers/specs/2026-08-08-frontend-redesign-design.md @@ -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//`): + - 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).