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:

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.
Direção estética em tokens CSS: bloco :root com paleta, tipografia, raio, sombra, motion + parágrafo de conceito.
Mapa funcionalidade → superfície: onde cada funcionalidade atual fica na nova interface, com racional (ver §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).

7.2 KiB Raw Blame History Unescape Escape