139 lines
7.2 KiB
Markdown
139 lines
7.2 KiB
Markdown
# 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).
|