Redline: Feedback Visual de UI para Claude Code

O Problema

Você está revisando uma aplicação web em execução. Um título tem a cor errada, um preço precisa ser atualizado, um label de botão está incorreto. O fluxo tradicional: abrir o DevTools, encontrar o elemento, anotar a classe CSS, pesquisar na base de código, localizar o arquivo, fazer a alteração. Repetir para cada problema. Se você trabalha com um designer ou product owner, eles fazem screenshot da página, desenham setas no Figma ou em um PDF, e você gasta tempo mapeando o feedback visual de volta para o código-fonte.

Queríamos algo mais rápido: apontar, escrever o que está errado, deixar um agente de IA corrigir.

O que o Redline faz

Redline é um skill para Claude Code com dois modos:

• /redline setup instala um overlay leve de anotação em qualquer projeto web (React, Vue, Svelte, HTML puro, Tauri)
• /redline arquivo.json lê um arquivo de anotação e corrige todos os problemas anotados na base de código

O overlay roda inteiramente no navegador, não requer dependências npm e funciona com qualquer framework. O arquivo de anotação é um JSON simples que o Claude Code lê para localizar elementos e aplicar correções.

Setup

Executar /redline setup no Claude Code faz três coisas:

1. Detecta o tipo do projeto e o ponto de entrada HTML (verifica index.html, src/index.html, public/index.html, app/layout.tsx, etc.)
2. Copia um dev/annotation-overlay.js autocontido para o projeto
3. Adiciona uma tag script dev-only antes de </body>

<!-- Redline: dev-only annotation overlay -->
<script data-dev-only src="/dev/annotation-overlay.js"></script>

O arquivo do overlay é commitado no repositório para que toda a equipe possa usá-lo. Os arquivos de saída das anotações vão para .claude/redline/, que está no gitignore.

Demo Passo a Passo

Vamos percorrer um ciclo completo de anotação usando uma página demo simples de loja.

A Página Original

Aqui está nosso ponto de partida — uma listagem limpa de produtos com três cards:

Ativando o Overlay

Pressione Cmd+Shift+A (Mac) ou Ctrl+Shift+A (Windows/Linux). Uma barra de ferramentas aparece no topo da página com ferramentas de desenho: Select, Arrow, Circle/Box, Text e Freehand.

Anotando Elementos

Clique em um elemento com a ferramenta Select para destacá-lo, depois digite seu feedback. Por exemplo, clicando no título e digitando "make text blue":

Você também pode desenhar setas apontando para elementos, circular áreas de interesse ou colocar labels de texto. Cada ferramenta de desenho automaticamente solicita um comentário para que a IA saiba o que corrigir.

Múltiplas Anotações

Continue anotando. Aqui marcamos cinco mudanças: uma mudança de cor no título, um fundo roxo para o primeiro card, uma correção de preço, uma correção de texto e uma mudança no label do botão:

Finalizando e Salvando

Pressione Cmd+Shift+A novamente ou clique em Done. O overlay salva um arquivo JSON na pasta Downloads e copia o nome do arquivo para a área de transferência. O JSON captura cada anotação com seu seletor CSS, comentário, metadados do elemento e posição:

Aplicando as Correções

Cole o nome do arquivo no Claude Code:

/redline home-2026-03-10-16-47.json

Claude lê o JSON, mapeia cada seletor para o arquivo-fonte, interpreta o comentário e aplica a correção. O resultado:

Todas as cinco anotações foram processadas e aplicadas ao index.html em uma única passagem.

Como Funciona por Dentro

O overlay tem aproximadamente 600 linhas de JavaScript vanilla que carrega o Fabric.js de um CDN para desenho em canvas.

Detecção de Elementos

Quando você clica no canvas, o overlay precisa saber qual elemento DOM está por baixo. Ele temporariamente esconde o canvas e a barra de ferramentas, chama document.elementFromPoint() e depois os restaura:

function getElementUnderPoint(x, y) {
  var canvasWrapper = fabricCanvas.wrapperEl;
  canvasWrapper.style.pointerEvents = 'none';
  if (toolbarEl) toolbarEl.style.pointerEvents = 'none';
  var element = document.elementFromPoint(x, y);
  canvasWrapper.style.pointerEvents = prevWrapper;
  if (toolbarEl) toolbarEl.style.pointerEvents = prevToolbar;
  return element;
}

Geração de Seletor CSS

Para informar ao Claude Code exatamente qual elemento foi anotado, o overlay gera um seletor CSS único. Ele percorre a árvore DOM para cima, coletando nomes de tags e nomes de classes. Quando irmãos compartilham a mesma tag e classe, adiciona :nth-child() para desambiguação:

function getCssSelector(el) {
  if (el.id) return '#' + CSS.escape(el.id);
  const parts = [];
  let current = el;
  while (current && current !== document.body) {
    let seg = current.tagName.toLowerCase();
    if (current.className) {
      const classes = current.className.trim().split(/\s+/);
      seg += '.' + classes.map(c => CSS.escape(c)).join('.');
    }
    if (current.parentElement) {
      var siblings = Array.from(current.parentElement.children)
        .filter(s => s.tagName === current.tagName
          && s.className === current.className);
      if (siblings.length > 1) {
        var idx = Array.from(current.parentElement.children)
          .indexOf(current) + 1;
        seg += ':nth-child(' + idx + ')';
      }
    }
    parts.unshift(seg);
    current = current.parentElement;
  }
  return parts.join(' > ');
}

Isso produz seletores como div.card:nth-child(2) > div.price, que são precisos o suficiente para o Claude encontrar o elemento correto mesmo em padrões de componentes repetidos.

Ferramentas de Desenho com Comentários Vinculados

Cada ferramenta de desenho (seta, círculo, caixa, mão livre) solicita um comentário após o término do desenho. O comentário é armazenado junto com o elemento DOM mais próximo. Para setas, o elemento sob a ponta da seta é usado como alvo. Para círculos e caixas, o centro da forma determina o elemento alvo. Essa vinculação é o que torna as anotações acionáveis — Claude Code sabe tanto o que mudar quanto onde mudar.

O JSON de Anotação

A saída final é um arquivo JSON simples:

{
  "view": "/",
  "url": "http://localhost:8099/",
  "timestamp": "2026-03-10T16:49:37.583Z",
  "annotations": [
    {
      "type": "select",
      "selector": "div.card:nth-child(1) > h2",
      "comment": "make text blue",
      "tagName": "H2",
      "text": "Wireless Headphones"
    },
    {
      "type": "arrow",
      "comment": "make background purple",
      "nearSelector": "div.card:nth-child(1) > button.btn-primary"
    }
  ]
}

Cada tipo de anotação carrega contexto suficiente para a IA localizar e corrigir o elemento: o seletor CSS, o comentário descrevendo a mudança, o nome da tag, classes e uma prévia do texto.

Como o Claude Code Processa Anotações

Quando você executa /redline arquivo.json, o skill:

1. Encontra o arquivo em ~/Downloads/ (o local padrão de download do navegador)
2. Lê as anotações e agrupa por arquivo-fonte
3. Para cada anotação, pesquisa a base de código por seletor, nomes de classes e conteúdo de texto para encontrar o arquivo de componente ou estilo
4. Interpreta o comentário e aplica a correção mínima
5. Despacha agentes paralelos para anotações que mapeiam para arquivos diferentes

Comentários ambíguos como "fix this" ou "ugly" são sinalizados no resumo em vez de serem adivinhados. Após o processamento, você recebe um resumo do que foi corrigido e do que precisa de esclarecimento.

Decisões de Design

Algumas escolhas que fizemos durante o desenvolvimento:

• Sem dependências npm. O overlay carrega Fabric.js de um CDN. Sem etapa de instalação, sem configuração de build, funciona em qualquer projeto.
• Download pelo navegador para todas as plataformas. Inicialmente tentamos escrever arquivos diretamente no disco usando a API de filesystem do Tauri, mas simplificamos para downloads padrão do navegador. Isso funciona de forma idêntica em webviews Tauri e navegadores normais.
• Nome do arquivo na área de transferência. Após salvar, o nome do arquivo é copiado para a área de transferência. Você cola no Claude Code como /redline arquivo.json. Sem buscar caminhos.
• Setup separado do processamento. /redline setup é um comando único. /redline arquivo.json é o fluxo diário. O modo de processamento nunca verifica se o overlay está instalado — ele simplesmente lê o arquivo e corrige o código, mantendo o uso de tokens baixo.
• Agnóstico a framework. O overlay é JavaScript puro injetado via tag script. Não importa se você usa React, Vue, Svelte ou uma página HTML estática.

Obter o Skill

Redline está disponível como skill para Claude Code em seedr.toolr.dev/skills/redline. Instale, execute /redline setup no seu projeto e comece a anotar.