ZARK Pincel

Editor visual local para páginas HTML estáticas: você aponta a ferramenta para o arquivo, clica no elemento na própria página e ajusta texto, tipografia, cor e espaçamento. Cada ajuste é gravado no arquivo fonte, na regra CSS que de fato governa aquele elemento e dentro do @media certo — não numa cópia, não num banco de dados, não num style inline.

Ele existe para resolver uma dor específica: ajustar um site gerado por IA custa vários prompts porque a IA não sabe qual elemento você quer mexer. Aqui você mostra clicando.

O que o diferencia

A maioria das ferramentas de edição visual escreve style="font-size: 34px" direto no elemento. Isso funciona na tela e apodrece o arquivo: o CSS deixa de ser a fonte da verdade, o responsivo quebra e ninguém consegue mais editar o projeto à mão.

O ZARK Pincel faz o contrário. Ele lê o CSS da página, descobre qual regra governa o elemento selecionado no breakpoint em que você está olhando, e edita aquela declaração, naquela regra, dentro daquele @media. Isso significa que:

• clamp(), var(), calc() e afins são preservados quando não são o alvo da edição — a ferramenta não "achata" o valor do arquivo inteiro para um pixel fixo;
• a formatação do arquivo (indentação, quebras, comentários, ordem das regras) continua igual — o diff de cada edição mostra só a linha que mudou;
• style inline é o último recurso declarado, nunca a conveniência padrão.

Pré-requisitos

• Node 20 ou mais novo (node --version).
• Chrome ou Chromium instalado. É o único navegador suportado.
• git — opcional, mas fortemente recomendado. É a rede de segurança: com git, cada edição vira um commit e nada é irreversível. Sem git, a ferramenta funciona e avisa, na cara, que suas edições não poderão ser desfeitas.

Instalação e uso

npx zark-pincel caminho/do/index.html

Isso baixa e roda sem instalar nada permanentemente. Se preferir ter o comando sempre à mão:

npm install -g zark-pincel
zark-pincel caminho/do/index.html

Funciona com qualquer HTML estático da sua máquina — não precisa ser um projeto preparado para isso.

O CSS pode estar num bloco <style>, em arquivos .css separados, ou nos dois. Quando um elemento é governado por uma regra do components.css, é nele que a edição é gravada — o index.html não é tocado. Imagens, fontes e as outras páginas do projeto são servidas normalmente, então o que você edita é a sua página como ela é de verdade.

O terminal imprime o endereço local (http://localhost:PORTA) e abre o navegador nele. Deixe o terminal aberto enquanto edita — é ele que grava no arquivo.

Como usar a barra

A barra fica fixa na lateral, fora do fluxo da página, e mostra os controles quando você seleciona algo.

Selecionar. Clique num elemento da página. A barra mostra qual é, qual regra CSS o governa e em qual breakpoint você está.

Navegar pai/filho. Acima dos controles há uma trilha (breadcrumb) com a linhagem do elemento. Clique num ancestral para subir, ou volte para descer. Serve para quando você quer o container e não o texto dentro dele.

Setas ↑ e ↓. Com um elemento selecionado, as setas aumentam e diminuem o valor. Shift dá passo grande (10×), Alt dá passo fino (1/10). Quando as duas vêm juntas, Alt vence.

Ctrl+Z desfaz, Ctrl+Shift+Z refaz. Cada gravação vira um passo; aperte cinco vezes e volte cinco edições. A barra diz o que foi desfeito. Funciona com ou sem git — é a rede de segurança que permite experimentar sem medo.

Uma recusa proposital: se outro programa (um agente de IA, seu editor) mexeu no arquivo depois daquela edição, o desfazer para e avisa em vez de gravar. Voltar ali sobrescreveria o trabalho de quem mexeu. Você perde um desfazer, não perde trabalho — e se desfizer a alteração externa, o Ctrl+Z volta a funcionar sozinho.

Dentro de um campo de texto (a edição direta na página, ou o campo do "Pedir pra IA"), Ctrl+Z é o desfazer normal do navegador. A ferramenta não sequestra a tecla ali.

Duplo-clique para editar texto. Duplo-clique num elemento de texto entra em edição direta na página. Se o elemento contiver outros elementos dentro, a edição é recusada com a explicação — trocar o texto ali apagaria a estrutura interna.

Os grupos. Os controles vêm em quatro blocos colapsáveis: Cor (texto, fundo, borda — já oferecendo as variáveis CSS do próprio projeto como opção), Tipografia, Espaçamento e Pedir pra IA. Um deles abre sozinho conforme o que você clicou: texto abre Tipografia, container abre Espaçamento.

O diálogo de "essa regra atinge N elementos". Se a regra que governa o elemento também governa outros (o caso normal: .card numa página com seis cards), a ferramenta para e pergunta antes de gravar, destacando na tela quem mais seria afetado. Três saídas:

| Saída | Tecla | O que faz | |---|---|---| | mudar todos (N) | 1 | grava na regra original — todos os N elementos mudam juntos | | só este | 2 | cria uma classe modificadora presa a este elemento e grava nela; os outros N−1 ficam intactos | | cancelar | Esc | não grava nada |

Pedir pra IA. Quando o ajuste é maior do que a barra alcança, o botão "Pedir pra IA" gera um contexto cirúrgico do elemento: a linha exata no arquivo fonte, o caminho até ele, o trecho de marcação como está no arquivo (não o outerHTML do DOM) e as regras CSS que o governam. Você recebe o prompt pronto num campo com botão de copiar — cole em qualquer agente. O mesmo pedido também fica gravado em .zark-pincel/pedidos/, o que gasta bem menos token para quem usa um agente na própria pasta do projeto.

A rede de segurança

Com git ligado, cada edição vira um commit, com mensagem descrevendo o que foi mexido (por exemplo pincel: .titulo @(max-width: 640px) font-size). Nada de "salvei dez coisas e agora não sei qual quebrou".

Desfazer uma edição:

git log --oneline     # ache o commit
git revert <hash>     # desfaz só aquele

Se a pasta não for um repositório git, a ferramenta pergunta antes de fazer qualquer coisa:

Esta pasta não é um repositório git.
O ZARK Pincel usa git para você poder desfazer qualquer edição.
Posso rodar "git init" em /caminho/do/projeto? [s/N]

Se você responder não, ele segue funcionando e avisa que as edições não poderão ser desfeitas. Ele nunca cria repositório sem sua confirmação.

Além disso, o servidor guarda um sha do arquivo. Se alguém (você noutro editor, um agente, um git checkout) mudar o arquivo por fora enquanto a barra está aberta, a gravação é recusada com "o arquivo mudou por fora — recarregue a página" em vez de sobrescrever o trabalho do outro.

Limites conhecidos

Estes são limites reais da versão atual, não coisas "que já vão sair":

• Só HTML estático. Site montado por framework ou por passo de build não é suportado — a ferramenta edita o arquivo que você tem, e num projeto com build o arquivo que você tem não é o que vira a página.
• CSS remoto não é editável. Uma folha vinda de CDN ou do Google Fonts não é um arquivo seu; a barra diz quantas ela não enxerga em vez de fingir que viu tudo.
• Folha que não vale para a tela fica de fora. <link media="print"> e afins são servidos ao navegador, mas não recebem edição — mexer ali não mudaria o que você está vendo.
• Elemento criado por JavaScript não é editável. Ele não existe no arquivo fonte, então não há onde gravar. A barra bloqueia a seleção e explica em vez de fingir que salvou.
• Só Chrome/Chromium. Outros navegadores não são testados nem suportados.
• Um arquivo por vez. Não há navegação entre páginas do projeto dentro da ferramenta.

Solução de problemas

O navegador não abriu. A ferramenta pede ao sistema para abrir o endereço no navegador padrão. Se o seu padrão não for o Chrome — ou se nada acontecer —, copie a URL impressa no terminal (http://localhost:PORTA) e cole no Chrome. Funciona igual.

Porta ocupada. O ZARK Pincel escolhe uma porta livre automaticamente a cada execução, então o erro clássico de "porta em uso" não deve aparecer. Se algo parecer travado, é quase sempre uma execução anterior ainda de pé: feche a aba antiga, encerre o processo no terminal (Ctrl+C) e rode de novo — a nova URL será outra.

"conexão perdida com o servidor — recarregue a página". O processo no terminal caiu ou foi encerrado. Nesse estado a barra não grava mais nada (proposital: melhor parar do que fingir que salvou). Confira se o terminal ainda está rodando, suba de novo e recarregue a página.

"o arquivo mudou por fora". Alguém editou o arquivo enquanto a barra estava aberta. Recarregue a página para o servidor reler o arquivo — nenhuma alteração sua ou dele foi perdida.

Créditos

Este projeto vendoriza código de terceiros em third_party/clickdeck/, do projeto ClickDeck, sob licença MIT. A atribuição completa está em third_party/clickdeck/NOTICE.md, junto da licença original em third_party/clickdeck/LICENSE.

Licença

MIT © 2026 ZARK. Ver LICENSE.

Documentação de apoio: como funciona por dentro · por que é assim · contribuindo.