Site de destino — propósito, UX e barra de design
A porta de entrada é site/ (Vite + React + Tailwind, apenas escuro), implantado em
vigiles.sh. Esta habilidade é o padrão ao qual cada alteração é submetida. A falha
recorrente que ela existe para impedir: adicionar elementos em vez de removê-los, o que
faz a página parecer confusa e com aparência de modelo genérico ("como Tilda") em vez de moderna.
A única regra acima de todas as outras: quando em dúvida, REMOVA. Design por subtração. Se deletar um elemento não perder significado, delete-o. Uma alteração que adiciona uma caixa, uma legenda, um segundo botão ou uma linha de reasseguramento é suspeita até que se prove necessária.
Propósito (para que serve o site)
- OBJETIVO PRINCIPAL — maximizar a % de visitantes que REALMENTE EXECUTAM
npx vigiles audit. Esta é a ÚNICA métrica de conversão que cada decisão de design serve. O CTA deve ser ÓTIMO (sem atrito, óbvio, sempre acessível). Se uma alteração não ajuda alguém a executar o comando, ela não está ganhando seu lugar. - Público-alvo: desenvolvedores que já vivem em ferramentas de codificação agêntica (Claude Code, Codex, Cursor). Eles são céticos e folheiam rapidamente em um celular.
- O "uau" é o relatório classificado — mostre o resultado, não explique o mecanismo.
- Promessa da porta de entrada: "Lighthouse para sua plataforma de agente" — uma classificação de um comando, configuração zero, nada enviado, de suas habilidades/hooks/subagentes/referências.
- O QUADRO DE DEMO SERVE QUATRO FUNÇÕES DE UMA SÓ VEZ — projete para todas as quatro, não deixe uma
sufocar as outras. (1) INTRODUÇÃO — ensine o que é o vigiles de relance (o relatório
classificado É o argumento de venda). (2) DEMO — notas reais instantâneas com esforço zero (os
chips
FEATUREDincorporados). (3) EXECUTAR NO NAVEGADOR — classifique SEU repositório público ao vivo digitando-o (API anônima do GitHub; apenas público). (4) CÓPIA DO COMANDO para o resto — um repositório privado ou local não pode ser executado no navegador, então o trabalho ali é uma CÓPIA limpa e óbvia denpx vigiles audit(uma transferência de comando, NÃO uma execução falsa no navegador). Duas regras de clareza decorrem e são essenciais: (a) o quadro deve sempre deixar CLARO QUAL repositório é mostrado e se é um EXEMPLO PRÉ-DEFINIDO (um chip) ou SEU PRÓPRIO (digitado)— nunca ambíguo; (b) o caminho do repositório privado é uma funcionalidade de primeira classe, não um pensamento tardio enfiado em uma frase — uma cópia de comando limpa e rotulada, verificada em 390px. Não repita o comando em três linhas empilhadas (o cabeçalho mostrando$ vigiles audit <slug>sobre um chip destacado que já o nomeia é INNFORMAÇÃO DEMAIS — o trabalho do cabeçalho é IDENTIFICAR o repositório classificado + sua fonte, não reimprimir o comando). - CÓPIA: concreto em vez de inteligente, e NUNCA plante uma dúvida que o leitor não trouxe consigo. Duas falhas reais que isso impede: (1) um título inteligente que parece enigmático ("'Válido' não é 'verdadeiro.'") — lidere com a dor concreta ("Configuração válida. Agente quebrado."), deixe os cartões abaixo carregarem a nuance; (2) um FAQ DEFENSIVO que destaca uma fraqueza que o leitor não havia notado ("É estável o suficiente para adotar?" atrai o olhar para um número de versão assustador) — substitua plantadores de dúvida por construtores de confiança que um cético realmente pergunta ("Algo sai da minha máquina?", "Posso classificar um repositório privado?"). Teste cada linha como um cético frio: ela me deixa MAIS ou MENOS propenso a executar o comando? Se menos, corte ou reformule.
- CREDIBILIDADE: o relatório de demonstração mostra APENAS varreduras reais — nunca invente um resultado. A marca é "medido, não afirmado", então um número codificado/falso no relatório envenena retroativamente a confiança em cada descoberta real. Uma provocação BLOQUEADA com MARCADORES HONESTOS (travessão "execute para preencher", sem dígitos) para algo genuinamente impossível de executar aqui (taxa de ativação controlada por modelo) é aceitável — não falsifica NADA. Resultados "fabricados" para algo que a ferramenta realmente calcula NÃO é — mostre o resultado REAL calculado ou mantenha-o como um cartão explicativo honesto FORA do quadro do relatório.
- Reduza o atrito para experimentar: ofereça repositórios OSS populares PREFIXADOS como chips
"classifique este" de um clique, para que um visitante veja um relatório real sem digitar ou ter
um repositório próprio. IMPLANTADO — os chips
FEATUREDemDemoAuditrenderizam relatórios reais instantaneamente. - CADA SUPERFÍCIE DE RESULTADO LEVA UMA FUNCIONALIDADE DE COMPARTILHAMENTO E UM LINK ESTÁVEL.
Uma nota que um leitor não pode entregar a um colega de equipe é um beco sem saída, então:
(1) cada nota completa é um link profundo copiável (
vigiles.sh/?repo=owner/repo#try) que EXECUTA AUTOMATICAMENTE a auditoria ao carregar — a URL É a unidade de compartilhamento; (2) qualquer resultado obtém um compartilhamento de um toque (folha de compartilhamento nativa no celular, copiar link em outros lugares — oShareRowemDemoAudit); (3) o link profundo é o mesmo slug que a entrada/chips usam, então um link compartilhado, um repositório digitado e um chip são resolvidos por um único caminho de código. Uma nova superfície de resultado DEVE carregar ambos. IMPLANTADO — mantenha funcionando. (As regras de reputação sob as quais isso opera — compartilhar é opcional, recusar é gratuito, artefatos de nota, não pessoas — são a regra degate-first-adoptionnoCLAUDE.mdraiz; não as repita aqui.) - Instrumente a conversão: análises no funil (cópias de comando, envios digitados, tentativas
de chip, reclassificações, cliques de compartilhamento). O site está no GitHub Pages, NÃO no
Vercel — então Vercel Analytics NÃO se aplica. Use uma análise leve, amigável à privacidade,
com script tag para hospedagem estática: Plausible / Fathom / GoatCounter. O funil já está
INSTRUMENTADO —
track()(site/src/lib/track.ts) dispara eventosdemo_*e é um não operação seguro até que um provedor esteja conectado. RESTANTE: adicionar a tag de script do provedor emindex.htmle confirmar que os eventos chegam. A análise carrega apenas o tipo de RESULTADO, nunca um slug digitado (o nome de um repositório privado não deve vazar).
Direção — decisões registradas (mantenha atual; é aqui que a DIREÇÃO mora)
As decisões estratégicas por trás do site atual. Atualize esta seção quando uma direção mudar — é o documento de design, não apenas um guia de estilo. Cada uma é uma decisão que custou iteração real para ser alcançada; não desfaça silenciosamente uma.
- O DEMO PADRÃO DEVE MOSTRAR UMA PEGADA — lidere com uma nota baixa real, nunca uma parede de
A's. Os chips
FEATUREDsão uma escala genuína F → C → B → A em repositórios RECONHECÍVEIS (atualmente davila7/claude-code-templates F, disler/claude-code-hooks-mastery C, madappgang B, obra/superpowers A). POR QUE deve ser assim: plugins populares reais majoritariamente classificam A/B no eixo determinístico que o navegador pode executar — as falhas dramáticas (habilidades não disparam, descrições colidem) vivem no nível de taxa de ativação controlada por modelo que o navegador NÃO PODE executar — então um padrão de boa aparência argumenta CONTRA a ferramenta ("está tudo bem, por que preciso disso?"). O padrão deve ser um repositório genuinamente quebrado para que o uau (o relatório) mostre o vigiles pegando algo. Atualizando o padrão de nota baixa (repositórios são corrigidos com o tempo): varra comgit clone https://github.com/<slug>entãonode dist/cli.js audit <dir> --json(NOTA:codeload/api.github.comsão bloqueados por proxy no ambiente de nuvem —git clonevia github.com funciona). Escolha um repositório que seja (a) reconhecível, (b) tenha descobertas OBJETIVAS e corrigíveis em uma linha (ferramenta morta, diretórioskills/invisível, evento de hook morto — não constrangedor por design), para que a nota pública seja justa (o modelo Lighthouse SÃO notas públicas de artefatos públicos). Grave o relatório emsite/src/demo/reports/e conecte-o emFEATURED. Descobertas de nível de modelo permanecem FORA do demo do navegador: é apenas determinístico por design (veja as invariantes do demo no navegador abaixo), então a superfície honesta para elas é a provocaçãoLockedRow, não um resultado fabricado. - NOMES-MAS-NUNCA-EXPLICA é a falha de cópia nº 1 — explique cada conceito ou corte-o. Um visitante frio não sabe o que "linter", "referência", "impor", "especificação" ou um nome de categoria significa. Cada conceito recebe uma explicação em inglês simples no PRIMEIRO uso, ou é cortado. Não mencione jargões (o README antigo aprendeu isso — "DEFINA HARNESS no primeiro uso"; o site regrediu e teve que reaprender isso). Teste cada linha como um usuário frio de Claude Code/Codex que nunca ouviu falar de vigiles.
- INCORPORE ECHOES NO RELATÓRIO — não adicione cartões explicativos separados. O relatório
É o uau. Um conceito que o navegador não pode mostrar (taxa de ativação controlada por modelo,
a referência cruzada do linter que precisa da sua configuração local) é uma linha tracejada
APENAS-CLI DENTRO do relatório (
LockedRow/CliRulesRowemreport-view/src/Report.tsx), não um cartão flutuando abaixo do quadro. Se o site explica o relatório em dois lugares, corte o eco (é por isso que a faixa de cinco categorias Wedge e o cartão "Suas regras → impostas" autônomo foram removidos — o relatório já carrega ambos). - UMA FUNCIONALIDADE DE ENTRADA POR VEZ — Abas Público/Privado, não uma pilha. A entrada do
herói era entrada + legenda "API pública" + transferência de comando privado + linha de
privacidade tudo empilhado (confuso). Agora é abas Público | Privado em
DemoAudit: Público = a caixa de combinação de digitação de repositório ao vivo; Privado = a cópia do comandonpx vigiles audit. Uma funcionalidade de entrada visível por vez. - PROVOCAÇÃO HONESTA, NUNCA DESFOQUE/FAKE (substitui qualquer nota mais antiga "renderize
desfocado"). A linha controlada por modelo usa marcadores de travessão (
recall — · precision —), NÃO números falsos desfocados. Desfoque parece um bug de renderização E um padrão escuro de paywall, e fabricar um número quebra "medido, não afirmado" — duplamente errado perto de uma cópia que zomba de números afirmados. Se uma provocação mais forte for desejada, use um número REAL medido com um rótuloexemplo, nunca um fabricado/desfocado.
Requisitos de UX
- Comando primeiro.
npx vigiles audité a ação universal (funciona em todos os SOs, todos os terminais). É O CTA primário. Todo o resto é secundário. - O deep link do Claude Code (
claude-cli://) é uma melhoria APENAS-DESKTOP, nunca o caminho primário — ele termina silenciosamente em celular / CC Web / desktop-sem-CC. Renderize-o apenas onde pode funcionar; nunca envie um botão que não faz nada. - Seja honesto no celular. Sem botões mortos. Onde uma ação apenas-desktop não puder ser executada, diga claramente e dê a ação real (o comando).
- Uma ação primária por tela. Ações secundárias são quietas — um link de texto ou uma pílula leve, nunca um segundo botão de largura total pesado competindo com o primário.
- Neutro em relação ao harness. Diga "Claude Code ou Codex", não lidere com Claude Code — é um detalhe de implementação, não o título. Não explique demais os internos.
- Baixo atrito + acolhedor. Um navegador superficial deve entender o que é e como experimentá-lo dentro de uma tela, sem ler um bloco de texto.
Barra de design — moderno & minimalista (as regras anti-aglomeração)
Refira-se à sensação de Linear / Vercel / Raycast: escuro confiante, espaço generoso, poucas palavras, um ponto focal claro por seção. NÃO um modelo repleto de recursos.
- Cada elemento deve ganhar seu lugar. Remova qualquer coisa que apenas repita outro (uma legenda repetindo a captura de tela; uma linha de confiança dita duas vezes; um subtítulo redundante).
- Corte qualquer rótulo que outro elemento já IMPLIQUE. Um selo "gratuito e de código aberto" é redundante quando um link GitHub/estrelas está presente; um selo "AUDITAR UM REPOSITÓRIO ESPECÍFICO" acima de um título "Avalie um repositório específico" repete-o. Se o contexto já diz ao leitor, o rótulo é ruído.
- Cada link/CTA é ACIONÁVEL e específico. O leitor deve saber exatamente o que acontece ao clicar. Sem links secundários vagos ou passivos ("Tem Claude Code?…"). Se um caminho secundário não vale uma ação clara e concreta, corte-o (ou mova-o para a navegação, onde um link persistente supera um link de dobra flácido).
- Um ponto focal por seção. O olho deve pousar em uma coisa primeiro.
- Espaço em branco + tipografia sobre caixas. Não empilhe 3+ caixas com borda de largura total; essa repetição é o que parece confuso. Prefira hierarquia de tipo e espaço a bordas. Mas o espaço em branco deve ser intencional — sem vazios de viewport quase vazios.
- Reasseguramento uma vez, em uma linha. Cópia de confiança ("nada enviado") aparece uma vez, compacta — nunca um parágrafo de 3 linhas, nunca repetido por seção.
- Coesão. O herói (selo + título + subtítulo + visual) deve ser lido como UMA ideia, cada parte adicionando informação nova. Se o subtítulo apenas diz o que a captura de tela já mostra, corte-o ou aprimore-o.
- Moderação na cor/ênfase. Um acento, cores de banda semântica que sempre significam algo (bandas de nota). Negrito em uma frase por ponto, não em cada cláusula. Sem confete decorativo de emoji.
- Escala de espaçamento consistente. Não ajuste manualmente margens únicas que lutam contra o ritmo.
Anti-padrões (coisas que deram errado aqui)
- Empilhar entrada + botão grande + linha de confiança de 3 linhas + divisor + comando + legenda + outro botão em uma dobra. (Correção: mantenha ~3 elementos, corte o resto.)
- Uma legenda abaixo da foto do produto repetindo a foto do produto.
- Adicionar um aviso/botão por problema em vez de repensar o fluxo.
- Dois CTAs primários concorrentes (deeplink + comando) sem hierarquia.
- Estruturação primeiro com CC ("executa em seu próprio Claude Code…") como o reasseguramento do título.
- Um fluxo apenas-desktop (o deep link
claude-cli://do Claude Code) deixado visível no celular como um fallback que apenas repete o comando que outra seção já mostra — o mesmo bloconpx vigiles auditem seções consecutivas no telefone. (Correção:hidden sm:blockem toda a seção apenas-desktop; o herói + CTA já carregam isso.)
Demo no navegador (IMPLANTADO — as invariantes a preservar)
O demo ao vivo "classifique qualquer repositório" está CONSTRUÍDO (em DemoAudit.tsx + site/src/demo/):
digite/cole um repositório público ou toque em um chip em destaque, ele busca os arquivos do harness
no lado do cliente e executa o MESMO motor compilado que o CLI faz. As regras abaixo são agora
INVARIANTES a preservar, não direção futura.
- Cada resultado é compartilhável (veja a meta de compartilhamento acima). Uma nota completa
carrega um compartilhamento de um toque + um link profundo estável de execução automática
?repo=. Este é um requisito difícil do demo, não um opcional — não envie uma superfície de resultado sem isso. - No navegador, NÃO hospedado. O cálculo da auditoria é executado inteiramente no LADO DO CLIENTE no navegador do visitante (busca os arquivos do repositório via API do GitHub, executa os detectores puros em JS) → reforça "nada sai da sua máquina"; zero backend/custo.
[truncado para tradução]