Oil UI
Playbook de cenário · Renovação de projeto existente

Renovação de UI em projetos existentes: atualize apps React e web com segurança

Gerar uma demo do zero é fácil; renovar um app em produção sem quebrar contratos de API, validação de formulários ou estado de URL é onde prompts únicos de IA falham. O caminho seguro é travar primeiro sua lógica de negócio inegociável, seguir um escopo passo a passo de renovação, percorrer a tarefa real contando cliques e extrair um DESIGN.md compartilhado a partir da sua primeira tela finalizada.

Pontos principais

Trave as invariantes de negócio primeiro

liste payloads de API, parâmetros de rota e handlers de formulário que o agente não deve tocar.

Renove em três etapas claras

a Etapa 1 remove ruído de bordas e cores, a Etapa 2 evolui layout e estados ausentes e a Etapa 3 condensa cadeias de modais em várias páginas.

Ponto-chave 3

Verifique a usabilidade contando cliques — reduzir um ciclo de 8 cliques em página de detalhe para 2 ações em lote inline supera qualquer maquiagem superficial.

Ponto-chave 4

Assim que sua tela principal passar na revisão, salve seus tokens, escala tipográfica e espaçamento no DESIGN.md para que cada rota irmã combine.

Cliques para concluir
2passos
Transições de página
0páginas
Risco de retrabalho
Zero saltos · prévia dividida + lote e desfazer em 1 clique
Ramo · Correspondência
Fila sem resposta (3)
06 out
08 out
09 out
2 selecionados
CONTEXTO DA MENSAGEM

Zhou Yu · Livraria Xiaoman

Feira do livro de outono e cartões de sócio

Último envio
06 out · Proposta preliminar entregue
Status
Aguardando resposta do cliente
“A prévia da feira do livro de outono e dos cartões de sócio está pronta para revisão. Com a confirmação esta semana, mantemos a próxima etapa no prazo.”
Instale o Oil UI Pro para o fluxo completo de diagnóstico e renovação em 3 etapas
npx github:oil-oil/oil-cli install oil-ui-pro

Para testar painéis básicos de direção e limpeza anti-slop em uma única tela primeiro, execute npx skills add oil-oil/oil-ui para a Skill gratuita.

Três etapas de renovação de UI: escolha seu raio de impacto

Equipes costumam hesitar em deixar um agente de código tocar telas de produção porque um prompt vago como "deixe esta página mais bonita" pode embaralhar props de componentes ou apagar filtros que funcionam. No Oil UI (e especificamente no fluxo de projetos existentes do Oil UI Pro), as renovações seguem três etapas explícitas:

As três etapas de renovação de projetos existentes no Oil UI
EtapaQuando usarO que mudaO que fica intacto
Etapa 1: Limpar ruído visualO fluxo funciona, mas bordas, tamanhos de fonte, espaçamento e cores parecem poluídos ou datadosEscala tipográfica, subtração de bordas, alinhamento, contenção de cores e limpeza de cardsEstrutura DOM, rotas, hooks de estado e todo fluxo de interação
Etapa 2: Evoluir layout e estadosA hierarquia visual é plana, ações principais ficam escondidas ou faltam estados de carregamento/vazio/erroHierarquia de seções, proporções multicoluna, breakpoints responsivos e estados completos de UIContratos de API de backend, lógica de negócio e navegação entre páginas
Etapa 3: Refazer fluxos truncados e extrair DESIGN.mdUsuários clicam por modais empilhados ou telas fragmentadas para concluir tarefas básicasConsolidação de etapas, edição inline, redesign da tela principal e DESIGN.md para todo o repositórioModelo de domínio subjacente e regras de integridade de dados

Quatro passos para renovar uma aplicação em produção com segurança

Seja renovando um app de revisão de contratos (como MOQI na galeria), um rastreador de sprints (Relay), um cliente de e-mail (Post) ou um fluxo de checkout (Pinch Checkout), siga uma sequência controlada:

  1. Capture a tela atual e execute um diagnóstico anotado

    Faça o agente capturar primeiro a página em execução e listar defeitos visuais e de interação numerados (por exemplo: três botões de cor primária competindo no cabeçalho, uma tabela de 12 colunas cortada em 1280px ou caixas brutas de alerta no erro).

  2. Renove uma tela principal primeiro

    Não mexa em vinte rotas de uma vez. Escolha a única tela onde os usuários passam mais tempo, compare 2 a 3 direções de renovação com dados reais e fixe a vencedora.

  3. Percorra a tarefa completa do usuário e conte cliques

    Clique e digite pelo fluxo real no navegador — filtrando, enviando, provocando um erro de validação e recuperando. Confirme que tarefas frequentes exigem menos passos do que antes.

  4. Extraia o DESIGN.md e replique para páginas irmãs

    Depois que a tela principal passar na revisão visual, faça o agente gravar a paleta de superfícies, escala tipográfica, densidade de tabelas e regras anti-slop em DESIGN.md e aplique essa especificação pelo restante do app.

Modelo de prompt para renovar uma tela existente

Use esta estrutura no Claude Code, Codex ou Cursor para evoluir uma tela em produção protegendo a lógica da aplicação:

Modelo de prompt de renovação de UI em projeto existente
Use o Oil UI para renovar [caminho da rota ou componente, ex.: app/billing/page.tsx] neste projeto.
- Comportamento a preservar estritamente: Mantenha intactos todos os [consultas de dados, parâmetros de filtro na URL, regras de validação de formulário e handlers de envio/exportação] existentes. Não remova nenhum campo do domínio.
- Problemas atuais a corrigir: [ex.: toda seção parece um card idêntico com borda; colunas da tabela quebram mal; faltam estados de filtro vazio e pagamento com falha].
- Etapa de renovação: [Escolha: Etapa 1 limpar ruído / Etapa 2 evoluir layout e estados / Etapa 3 refazer fluxo e extrair DESIGN.md].
Comece capturando e diagnosticando a tela atual ao vivo, proponha direções e verifique a página finalizada em 1440×900 e 390×844.

Listar os comportamentos preservados logo no primeiro item evita regressões acidentais.

Exemplos funcionais e prompts da galeria

Explorar coleção →
Oil UI Pro

Renove apps em produção com segurança usando o Oil UI Pro

Prompts vagos de redesign costumam quebrar filtros e handlers de formulário que funcionam. O Oil UI Pro diagnostica sua tela ao vivo pelas capturas primeiro, renova em três etapas controladas, conta cliques ao longo da tarefa real e extrai um DESIGN.md para todo o repositório ($19.99 pagamento único).

Explorar o Oil UI Pro →
Copiar prompt de instalação do Pro
npx github:oil-oil/oil-cli install oil-ui-pro

Perguntas frequentes

Devo definir tokens CSS globais primeiro ou renovar uma tela real primeiro?

Renove uma tela representativa primeiro. Arquivos abstratos de tokens escritos no vácuo raramente sobrevivem ao contato com densidade real de tabelas e estados de formulário. Aperfeiçoar uma tela principal com dados reais torna natural extrair tokens precisos para o DESIGN.md.

Posso renovar um app legado de forma incremental sem reescrever widgets de terceiros?

Sim. Uma passagem de Etapa 1 ou Etapa 2 pode reorganizar a grade da página, tipografia, espaçamento e estados ao redor enquanto deixa widgets complexos incorporados intactos até você estar pronto para substituí-los.

Como verifico se um redesign realmente melhorou a usabilidade?

Confira duas coisas: primeiro, borre o texto para confirmar que a ação principal e os estados de exceção se destacam estruturalmente; segundo, conclua a tarefa principal do usuário no navegador e verifique se contagem de cliques, busca por rolagem e recuperação de erros estão mais rápidas que antes.

Onde o DESIGN.md fica guardado depois de extraído?

Mantenha o DESIGN.md na raiz do repositório ou na pasta docs/. Sempre que você ou alguém do time construir um novo recurso no Claude Code, Codex ou Cursor, aponte o agente para o DESIGN.md para que as novas telas sigam o sistema estabelecido.

Guias relacionados

Guia de UI no Cursor e Windsurf ↗Corrigindo UI genérica de IA ↗Revisão às cegas em tela real ↗