Communitygithub.com

zernie/vigiles

El propósito, el flujo de UX y el estándar de diseño moderno-minimalista para el sitio de aterrizaje vigiles.sh (site/). Úsalo al diseñar, editar, añadir o revisar cualquier componente, hero, sección o texto de marketing de site/ — léelo ANTES de tocar site/, y contrasta cada cambio contra él. No es para docs/ ni para la aplicación en sí.

¿Qué es vigiles?

Esta skill define el estándar de diseño y UX para el sitio de aterrizaje de vigiles.sh, una herramienta de auditoría para agentes de IA como Claude Code, Codex o Cursor. La skill enfatiza una filosofía de "diseño por sustracción": cuando tengas dudas, elimina elementos en lugar de añadirlos, priorizando la claridad y la modernidad sobre la sobrecarga visual. Su objetivo principal es maximizar la conversión de visitantes en usuarios que ejecuten `npx vigiles audit`, mostrando un reporte graduado como demostración principal. El sitio utiliza Vite, React y Tailwind CSS (modo oscuro), con un demo que se ejecuta completamente en el navegador del cliente para reforzar la privacidad ("nada sale de tu máquina"). Incluye directrices específicas para evitar errores comunes como añadir elementos redundantes o explicar conceptos sin glosarios claros, y establece invariantes para la demo, como la capacidad de compartir resultados mediante enlaces profundos y la honestidad en las demostraciones (sin números falsos).

Compatible con✓Claude Code✓Codex CLI✓Cursor✓Antigravity
npx skills add https://github.com/zernie/vigiles/tree/HEAD/.claude/skills/landing-site

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Sitio de aterrizaje — propósito, UX y estándar de diseño

La puerta de entrada es site/ (Vite + React + Tailwind, solo modo oscuro), desplegado en vigiles.sh. Esta skill es el estándar al que se somete cada cambio. El fallo recurrente que existe para evitar: añadir elementos en lugar de eliminarlos, lo que hace que la página se sienta abarrotada y con plantilla ("estilo Tilda") en lugar de moderna.

La única regla por encima de todas las demás: en caso de duda, ELIMINA. Diseño por sustracción. Si eliminar un elemento no pierde significado, elimínalo. Un cambio que añade un recuadro, un pie de foto, un segundo botón o una línea de tranquilidad es sospechoso hasta que se demuestre necesario.

Propósito (para qué sirve el sitio)

  • OBJETIVO PRINCIPAL — maximizar el porcentaje de visitantes que realmente EJECUTAN npx vigiles audit. Esta es la ÚNICA métrica de conversión a la que sirve cada decisión de diseño. El CTA debe ser EXCELENTE (sin fricción, obvio, siempre accesible). Si un cambio no ayuda a alguien a ejecutar el comando, no está ganando su lugar.
  • Audiencia: desarrolladores que ya viven en herramientas de codificación con agentes (Claude Code, Codex, Cursor). Son escépticos y hojean en un teléfono.
  • El impacto es el reporte graduado — muestra el resultado, no expliques el mecanismo.
  • Promesa de entrada: "Lighthouse para tu arnés de agente" — una calificación de un solo comando, cero configuración, sin nada subido de tus skills/hooks/subagentes/referencias.
  • EL MARCO DE DEMO SIRVE CUATRO TRABAJOS A LA VEZ — diseña para los cuatro, no dejes que uno opaque al resto. (1) INTRODUCCIÓN — enseña qué es vigiles de un vistazo (el reporte graduado ES la presentación). (2) DEMO — calificaciones reales instantáneas con cero esfuerzo (los chips FEATURED precargados). (3) EJECUCIÓN EN EL NAVEGADOR — califica tu repositorio público EN VIVO escribiéndolo (API anónima de GitHub; solo público). (4) COPIA DEL COMANDO para el resto — un repositorio privado o local no se puede ejecutar en el navegador, así que el trabajo allí es una COPIA limpia y obvia de npx vigiles audit (una transferencia de comando, NO una ejecución falsa en el navegador). Dos reglas de claridad se derivan y son fundamentales: (a) el marco siempre debe dejar claro QUÉ repositorio se muestra y si es un EJEMPLO PREDEFINIDO (un chip) o TU PROPIO (escrito) — nunca ambiguo; (b) la ruta de repositorio privado es una funcionalidad de primera clase, no una ocurrencia tardía metida en una oración — una copia de comando limpia y etiquetada, verificada a 390px. No repitas el comando en tres líneas apiladas (el encabezado que muestra $ vigiles audit <slug> encima de un chip resaltado que ya lo nombra es DEMASIADA INFORMACIÓN — el trabajo del encabezado es IDENTIFICAR el repositorio calificado + su fuente, no reimprimir el comando).
  • TEXTO: concreto sobre ingenioso, y NUNCA siembres una duda que el lector no traía. Dos errores reales que esto detiene: (1) un titular ingenioso que se lee como críptico ("'Válido' no es 'verdadero.'") — lidera con el dolor concreto ("Config válida. Agente roto."), deja que las tarjetas debajo lleven el matiz; (2) una FAQ DEFENSIVA que resalta una debilidad que el lector no había notado ("¿Es lo suficientemente estable para adoptarlo?" atrae la atención hacia un número de versión aterrador) — reemplaza los sembradores de dudas con generadores de confianza que un escéptico realmente pregunta ("¿Sale algo de mi máquina?", "¿Puedo calificar un repositorio privado?"). Prueba cada línea como un escéptico frío: ¿me hace MÁS o MENOS probable que ejecute el comando? Si menos, corta o reformula.
  • CREDIBILIDAD: el reporte de demo muestra SOLO escaneos reales — nunca fabriques un resultado. La marca es "medido, no afirmado", así que un número fijo/falso en el reporte envenena retroactivamente la confianza en cada hallazgo real. Una PREVISUALIZACIÓN BLOQUEADA con MARCADORES DE LUGAR HONESTOS (guión largo "ejecutar para llenar", sin dígitos) para algo que genuinamente no se puede ejecutar aquí (tasa de activación controlada por modelo) está bien — no FALSA NADA. Resultados "fabricados" para algo que la herramienta realmente calcula NO lo está — muestra el resultado REAL calculado o mantenlo como una tarjeta explicativa honesta FUERA del marco del reporte.
  • Reduce la fricción para probar: ofrece repositorios OSS populares PRE-RELLENADOS como chips de "califica esto" de un solo clic, para que un visitante vea un reporte real sin escribir ni tener su propio repositorio. IMPLEMENTADO — los chips FEATURED en DemoAudit renderizan reportes reales precargados instantáneamente.
  • CADA SUPERFICIE DE RESULTADOS LLEVA UNA FUNCIONALIDAD DE COMPARTIR Y UN ENLACE ESTABLE. Una calificación que un lector no puede pasar a un compañero de equipo es un callejón sin salida, así que: (1) cada calificación completada es un enlace profundo copiable (vigiles.sh/?repo=owner/repo#try) que EJECUTA AUTOMÁTICAMENTE la auditoría al cargar — la URL ES la unidad de compartir; (2) cualquier resultado obtiene un compartir de un solo toque (hoja de compartir nativa en móvil, copiar enlace en otros lugares — el ShareRow en DemoAudit); (3) el enlace profundo es el mismo slug que usan la entrada/los chips, así que un enlace compartido, un repositorio escrito y un chip resuelven todos a una ruta de código. Una NUEVA superficie de resultado DEBE llevar ambos. IMPLEMENTADO — mantenlo funcionando. (Las reglas de reputación bajo las que opera esto — compartir es opt-in, rechazar es gratuito, los artefactos de calificación no las personas — son la regla gate-first-adoption en el CLAUDE.md raíz; no las repitas aquí.)
  • Instrumenta la conversión: analítica del embudo (copias de comando, envíos escritos, intentos de chip, recalificaciones, clics de compartir). El sitio está en GitHub Pages, NO en Vercel — así que Vercel Analytics NO aplica. Usa una analítica ligera, respetuosa con la privacidad, con etiqueta de script para hosting estático: Plausible / Fathom / GoatCounter. El embudo ya está INSTRUMENTADO — track() (site/src/lib/track.ts) dispara eventos demo_* y es un no-op seguro hasta que se conecte un proveedor. RESTANTE: añade la etiqueta de script del proveedor a index.html y confirma que los eventos lleguen. La analítica lleva solo el tipo de RESULTADO, nunca un slug escrito (el nombre de un repositorio privado no debe filtrarse).

Dirección — decisiones registradas (mantén actual; aquí es donde vive la DIRECCIÓN)

Las decisiones estratégicas detrás del sitio actual. Actualiza esta sección cuando una dirección cambie — es el documento de diseño, no solo una guía de estilo. Cada una es una decisión que costó iteración real alcanzar; no deshagas una en silencio.

  • LA DEMO POR DEFECTO DEBE MOSTRAR UN FALLO — lidera con una calificación baja real, nunca un muro de A's. Los chips FEATURED son una escala genuina F → C → B → A en repositorios RECONOCIBLES (actualmente davila7/claude-code-templates F, disler/claude-code-hooks-mastery C, madappgang B, obra/superpowers A). POR QUÉ debe ser así: los plugins populares reales principalmente califican A/B en el eje determinista que el navegador puede ejecutar — los fallos dramáticos (las skills no se disparan, las descripciones chocan) viven en el nivel de tasa de activación controlada por modelo que el navegador NO PUEDE ejecutar — así que un valor predeterminado de aspecto limpio ARGUMENTA EN CONTRA de la herramienta ("todo está bien, ¿por qué necesito esto?"). El valor predeterminado debe ser un repositorio genuinamente roto para que el impacto (el reporte) muestre a vigiles detectando algo. Actualizar el valor predeterminado de calificación baja (los repositorios se corrigen con el tiempo): barre con git clone https://github.com/<slug> luego node dist/cli.js audit <dir> --json (NOTA: codeload/api.github.com están bloqueados por proxy en el entorno de nube — git clone a través de github.com funciona). Elige un repositorio que sea (a) reconocible, (b) tenga hallazgos OBJETIVOS y corregibles con una línea (herramienta muerta, directorio skills/ invisible, evento de hook muerto — no vergonzoso por diseño), para que la calificación pública sea justa (el modelo de Lighthouse SON calificaciones públicas de artefactos públicos). Hornea el reporte en site/src/demo/reports/ y conéctalo en FEATURED. Los hallazgos del nivel de modelo se quedan FUERA de la demo del navegador: es solo determinista por diseño (ver las invariantes de la demo en el navegador a continuación), así que la superficie honesta para ellos es la previsualización LockedRow, no un resultado fabricado.
  • NOMBRES-PERO-NUNCA-EXPLICA es el error de texto #1 — glosa cada concepto o elimínalo. Un visitante frío no sabe qué significa "linter", "referencia", "aplicar", "especificación" o un nombre de categoría. Cada concepto recibe una glosa en español sencillo en el PRIMER uso, o se elimina. No menciones jerga (el README anterior aprendió esto — "DEFINE ARNÉS en el primer uso"; el sitio retrocedió y tuvo que reaprenderlo). Prueba cada línea como un usuario frío de Claude Code/Codex que nunca ha oído hablar de vigiles.
  • PLIEGA LOS ECOS EN EL REPORTE — no añadas tarjetas explicativas independientes. El reporte ES el impacto. Un concepto que el navegador no puede mostrar (tasa de activación controlada por modelo, la referencia cruzada del linter que necesita tu configuración local) es una fila discontinua SOLO-CLI DENTRO del reporte (LockedRow / CliRulesRow en report-view/src/Report.tsx), no una tarjeta flotando debajo del marco. Si el sitio explica el reporte en dos lugares, corta el eco (por eso se eliminaron la tira de cinco categorías Wedge y la tarjeta independiente "Tus reglas → aplicadas" — el reporte ya lleva ambas).
  • UNA FUNCIONALIDAD DE ENTRADA A LA VEZ — pestañas Público/Privado, no una pila. La entrada del héroe era entrada + pie de foto "API pública" + transferencia de comando privado + línea de privacidad todo apilado (abarrotado). Ahora son pestañas Público | Privado en DemoAudit: Público = el cuadro combinado de escribir un repositorio en vivo; Privado = la copia del comando npx vigiles audit. Una funcionalidad visible a la vez.
  • PREVISUALIZACIÓN HONESTA, NUNCA DIFUMINAR/FAKE (reemplaza cualquier nota anterior de "renderízalo difuminado"). La fila controlada por modelo usa marcadores de posición de guión largo (recall — · precision —), NO números falsos difuminados. El difuminado se lee como un error de renderizado Y un patrón oscuro de muro de pago, y fabricar un número rompe "medido, no afirmado" — doblemente incorrecto cerca de un texto que se burla de los números afirmados. Si alguna vez se desea una previsualización más fuerte, usa un número REAL medido con una etiqueta example, nunca uno fabricado/difuminado.

Requisitos de UX

  • Comando primero. npx vigiles audit es la acción universal (funciona en todos los sistemas operativos, todos los terminales). Es EL CTA principal. Todo lo demás es secundario.
  • El enlace profundo de Claude Code (claude-cli://) es una MEJORA SOLO DE ESCRITORIO, nunca la ruta principal — termina silenciosamente sin salida en móvil / CC Web / escritorio sin CC. Renderízalo solo donde pueda funcionar; nunca envíes un botón que no hace nada.
  • Sé honesto en móvil. Sin botones muertos. Cuando una acción de solo escritorio no se pueda ejecutar, dilo claramente y da la acción real (el comando) en su lugar.
  • Una acción principal por pantalla. Las acciones secundarias son discretas — un enlace de texto o una píldora ligera, nunca un segundo botón pesado de ancho completo compitiendo con el principal.
  • Neutral respecto al arnés. Di "Claude Code o Codex", no lideres con Claude Code — es un detalle de implementación, no el titular. No expliques en exceso los internos.
  • Baja fricción + acogedor. Un hojeador debe entender qué es y cómo probarlo dentro de una pantalla, sin leer un muro de texto.

Estándar de diseño — moderno y minimalista (las reglas contra la sobrecarga)

Referencia la sensación de Linear / Vercel / Raycast: oscuro seguro, espacio generoso, pocas palabras, un punto focal claro por sección. NO una plantilla llena de características.

  • Cada elemento debe ganarse su lugar. Elimina cualquier cosa que solo repita otra (un pie de foto que repite la captura de pantalla; una línea de confianza dicha dos veces; un subtítulo redundante).
  • Corta cualquier etiqueta que otro elemento ya IMPLIQUE. Una insignia de "gratuito y de código abierto" es redundante cuando hay un enlace de GitHub/estrellas; una insignia "AUDITA UN REPOSITORIO ESPECÍFICO" encima de un encabezado "Califica un repositorio específico" lo repite. Si el contexto ya le dice al lector, la etiqueta es ruido.
  • Cada enlace/CTA es ACCIONABLE y específico. El lector debe saber exactamente qué sucede al hacer clic. Sin enlaces secundarios vagos o pasivos ("¿Tienes Claude Code?..."). Si una ruta secundaria no vale una acción clara y concreta, córtala (o muévela a la navegación, donde un enlace persistente supera a un enlace débil en el pliegue).
  • Un punto focal por sección. El ojo debe aterrizar en una cosa primero.
  • Espacio en blanco + tipografía sobre recuadros. No apiles 3+ recuadros con bordes de ancho completo; esa repetición es lo que se lee como abarrotado. Prefiere jerarquía tipográfica y espacio a los bordes. Pero el espacio en blanco debe ser intencional — tampoco vacíos de viewport casi vacíos.
  • Tranquilidad una vez, en una línea. El texto de confianza ("nada subido") aparece una vez, compacto — nunca un párrafo de 3 líneas, nunca repetido por sección.
  • Cohesión. El héroe (insignia + titular + subtítulo + visual) debe leerse como UNA idea, cada parte añadiendo información nueva. Si el subtítulo solo dice lo que la captura de pantalla ya muestra, córtalo o agudízalo.
  • Moderación en color/énfasis. Un acento, colores de banda semánticos que siempre signifiquen algo (bandas de calificación). Negrita una frase por punto, no cada cláusula. Sin confeti emoji decorativo.
  • Escala de espaciado consistente. No ajustes manualmente márgenes únicos que rompan el ritmo.

Anti-patrones (cosas que han salido mal aquí)

  • Apilar entrada + botón grande + confianza de 3 líneas + divisor + comando + pie de foto + otro botón en un pliegue. (Solución: mantén ~3 elementos, corta el resto.)
  • Un pie de foto debajo de la foto del producto repitiendo la foto del producto.
  • Añadir un aviso/botón por problema en lugar de repensar el flujo.
  • Dos CTAs principales competidores (enlace profundo + comando) sin jerarquía.
  • Encuadre primero-CC ("se ejecuta en tu propio Claude Code...") como la tranquilidad titular.
  • Un flujo solo de escritorio (el enlace profundo claude-cli:// de Claude Code) dejado visible en móvil como alternativa que solo repite el comando que otra sección ya muestra — el mismo bloque npx vigiles audit en secciones consecutivas en el teléfono. (Solución: hidden sm:block toda la sección de solo escritorio; el héroe + CTA ya lo llevan.)

Demo en el navegador (IMPLEMENTADO — las invariantes a mantener)

La demostración en vivo "califica cualquier repositorio" está CONSTRUIDA (en DemoAudit.tsx + site/src/demo/): escribe/pega un repositorio público o toca un chip destacado, obtiene los archivos del arnés en el lado del cliente y ejecuta el MISMO motor compilado que la CLI. Las reglas a continuación son ahora INVARIANTES a preservar, no dirección futura.

  • Cada resultado es compartible (ver el objetivo de compartibilidad arriba). Una calificación completada lleva un compartir de un solo toque + un enlace profundo ?repo= estable que se ejecuta automáticamente. Este es un requisito estricto de la demostración, no un buen tener — no envies una superficie de resultados sin él.
  • En el navegador, NO hospedado. El cómputo de la auditoría se ejecuta completamente en el LADO DEL CLIENTE en el navegador del visitante (obtiene los archivos del repositorio a través de la API de GitHub, ejecuta los detectores puros en JS) → refuerza "nada sale de tu máquina"; cero backend/costo. El único "hospedaje" es la entrega de archivos estáticos en GitHub Pages. Cada resultado se calcula desde cero — no hay almacenamiento en caché del lado del servidor, no hay identificación del visitante.
  • Solo determinista — sin tasa de activación controlada por modelo en el navegador. El motor en el navegador ejecuta solo los detectores que son puramente estáticos (linter de archivos, detección de estructura, cruce de nombres). Los hallazgos de tasa de activación requieren llamadas a la API del modelo desde la CLI de un usuario — no ocurren aquí. La fila de tasa en el reporte renderizado siempre está bloqueada (LockedRow) con marcadores de posición de guión largo — nunca un número inventado. Los detectores controlados por modelo nuevos se añaden solo al binario de la CLI; si se desea una superficie en el navegador, debe ser a través de una LockedRow honesta, no una fila falsa.
  • API anónima de GitHub — sin token = límite de tasa. La demo usa la API no autenticada de GitHub (api.github.com sin encabezado Authorization). El límite de tasa es bajo (~60 solicitudes/hora por IP). Para repositorios grandes o muchos visitantes en la misma IP, esto falla con un error 403/429. La solución actual es mostrar un mensaje "Inténtalo de nuevo en un minuto" — no hay una solución de token del lado del servidor. Si el límite de tasa se convierte en un bloqueo, la opción preferida es silenciar la solicitud fallida y degradar elegantemente a la copia del comando, NO añadir una entrada de token.
  • Los chips FEATURED están horneados estáticamente — actualiza cuando los repositorios cambien. Los reportes de ejemplo están en site/src/demo/reports/ y se importan estáticamente. Cuando un repositorio destacado se actualiza (nuevo commit, hallazgos cambiados), vuelve a generar su reporte con git clone + cli audit (ver la sección de Dirección) y actualiza el archivo JSON. El chip en FEATURED_REPOS (site/src/demo/config.ts) apunta al slug del repositorio; la ruta del reporte coincide. No dejes chips rotos apuntando a reportes faltantes.
  • La URL ?repo= se aplica en la carga — los enlaces profundos se comparten con alegría. Cuando un visitante llega con ?repo=owner/repo, la demostración AUTOMÁTICAMENTE enfoca ese repositorio (sin animación de escritura, sin demora) y ejecuta la auditoría tan pronto como esté lista. Esto significa que una calificación compartida se reproduce instantáneamente. No rompas este flujo: probar cada enlace profundo manualmente antes de enviar.

Pila técnica (para referencia — no traduzcas)

  • Vite + React + Tailwind CSS (modo oscuro, darkMode: 'class').
  • Sin enrutador del lado del servidor — página estática única; el enrutamiento es solo hash (?repo= para enlace profundo de demostración).
  • Sin autenticación — toda la lógica es pública; no hay inicio de sesión, no hay backend.
  • El motor CLI compilado (vigiles-engine) se importa como un paquete JS del lado del cliente (tree-shaken, solo los detectores deterministas).
  • GitHub API (api.github.com) para obtener archivos de repositorio; sin token, límite de tasa por IP.
  • Despliegue: GitHub Pages (rama gh-pages, construido desde site/ con npm run build). Sin Vercel, sin Netlify, sin Cloudflare.
  • Analítica: Plausible / Fathom / GoatCounter (próximamente — etiqueta de script en index.html necesaria).

Notas finales de la skill

Esta skill es la autoridad final para cualquier cambio en site/. Si una solicitud de cambio contradice una regla aquí, la solicitud necesita una justificación que modifique la skill primero.

Archivos clave referenciados:

  • site/src/demo/DemoAudit.tsx — el componente de demostración del navegador
  • site/src/demo/config.ts — repositorios destacados y configuración
  • site/src/demo/reports/ — reportes de ejemplo horneados
  • site/src/lib/track.ts — sistema de eventos de analítica
  • report-view/src/Report.tsx — el componente de reporte compartido

Comandos para actualizar reportes horneados:

git clone https://github.com/<slug> /tmp/vigiles-report-<slug>
node dist/cli.js audit /tmp/vigiles-report-<slug> --json > site/src/demo/reports/<slug>.json

Skills relacionados