← Volver al listado de tecnologías ← Índice de Impeccable

El detector: 44 reglas deterministas

Por: Artiko
impeccabledetectorreglasai-sloplinting

El detector: 44 reglas deterministas

En el capítulo anterior montamos el contexto de diseño con init, PRODUCT.md y DESIGN.md. Ese contexto le dice al agente qué clase de interfaz queremos. Pero hay un problema que ningún archivo de contexto resuelve por sí solo: incluso con buenas instrucciones, un agente de IA tiende a producir interfaces con un “acento” reconocible. Bordes gruesos de color a un lado de las tarjetas, glows oscuros, gradientes morados, la misma tipografía de siempre. A ese conjunto de tics visuales lo llamamos AI slop, y es justo lo que el detector de Impeccable existe para cazar.

Lo interesante es que el detector no es un comando del agente: es una herramienta aparte. Mientras que comandos como /impeccable audit o /impeccable critique razonan con un modelo, el detector es un CLI determinista que aplica 44 reglas mecánicas sobre tu código o sobre una URL. No interpreta, no opina: mide. Y eso le da dos superpoderes que veremos en este capítulo.

El detector es determinista y no necesita API key

La primera característica clave del detector es que no requiere clave de API ni harness de IA. No habla con ningún modelo. Es un linter visual y estructural escrito en JavaScript que puedes correr en cualquier máquina, incluso en CI, sin gastar tokens ni exponer secretos.

La segunda es que es determinista: las mismas 44 reglas, con los mismos umbrales, producen el mismo resultado cada vez. Esto contrasta con los comandos basados en modelo, que pueden variar entre ejecuciones. El detector es el suelo firme sobre el que se apoyan los comandos más creativos.

Se invoca directamente con npx, sin instalación previa obligatoria:

npx impeccable detect src/                   # escanea un directorio
npx impeccable detect index.html             # escanea un archivo HTML
npx impeccable detect https://example.com    # escanea una URL (con Puppeteer)
npx impeccable detect --json .               # salida JSON, ideal para CI
npx impeccable detect --no-config src/       # escaneo crudo, ignora la config

Cuando le pasas una URL, el detector levanta un navegador headless (Puppeteer) para renderizar la página y poder medir colores efectivos, contraste real y geometría de los elementos tal como los ve el usuario. Cuando le pasas archivos locales, analiza el HTML y el CSS estáticos, y para reglas visuales también puede renderizar.

Recuerda: el detector vive en el repo de Paul Bakaus (pbakaus), se publica en npm como impeccable y es Apache 2.0. El CLI detect es independiente del agente, así que puedes adoptarlo aunque todavía no uses los comandos /impeccable.

Los cuatro motores del detector

No todas las reglas se evalúan igual. Algunas miran el texto del código fuente, otras necesitan ver los píxeles renderizados. El detector organiza esto en cuatro motores, y cada regla declara cuál usa:

flowchart TD
    A[npx impeccable detect TARGET] --> B{Tipo de target}
    B -->|archivo o directorio| C[Motor estático HTML/CSS]
    B -->|texto crudo| D[Motor regex]
    B -->|URL https| E[Motor browser Puppeteer]
    C --> F[Motor visual: render y medición]
    E --> F
    D --> G[Colección de hallazgos]
    F --> G
    G --> H{Modo de salida}
    H -->|por defecto| I[Reporte legible en terminal]
    H -->|--json| J[JSON para CI / hooks]

La idea es que cada regla elija el motor mínimo necesario. Una regla de copy no necesita renderizar nada (le basta regex), mientras que detectar un glow oscuro requiere medir la luminancia del fondo y el blur de la sombra (visual/browser).

Qué detecta: dos grandes familias

Las 44 reglas se reparten en dos familias conceptuales:

  1. AI slop: tics visuales y de copy que delatan una interfaz generada por IA sin curaduría humana.
  2. Calidad general de diseño: problemas atemporales de legibilidad, espaciado, accesibilidad y estructura que existirían igual sin IA.

Veamos las categorías concretas, con reglas representativas extraídas de los archivos checks.mjs y antipatterns.mjs del detector. No hace falta memorizar las 44; lo valioso es entender los grupos y reconocer el patrón.

Bordes y sombras (el sello del AI slop)

Esta categoría agrupa los tells más reconocibles de una UI generada por IA.

Tipografía

Color y contraste

Espaciado y layout

Componentes y estructura

Movimiento

Copy (texto y cadencia)

Gradientes y efectos

Reglas del design system (consultan tu DESIGN.md)

Cuando activas detector.designSystem.enabled, el detector cruza tu código contra los tokens documentados en DESIGN.md:

Aquí se cierra el círculo con el capítulo 3: el DESIGN.md que escribiste deja de ser documentación pasiva y se convierte en reglas verificables.

Reglas gated por proveedor

Algunas reglas solo se activan según el proveedor de IA que generó el código, porque son tics específicos de un modelo:

El sistema de ignores inline

Ninguna regla mecánica acierta el 100% de las veces. A veces ese overused-font: Inter es deliberado porque Inter es tu fuente de marca. Para esos casos, el detector ofrece waivers inline: comentarios en el propio archivo que silencian una regla, con un motivo opcional que documenta la decisión.

<!-- impeccable-disable overused-font: documento de marca exportado -->
<div class="brand-doc">...</div>

Hay tres variantes, igual que en un linter clásico:

<!-- impeccable-disable overused-font: motivo -->
<!-- impeccable-disable-line overused-font -->
<!-- impeccable-disable-next-line overused-font -->

El motivo tras los dos puntos es texto libre y queda como rastro de la decisión: cuando alguien revise el código dentro de seis meses sabrá por qué se ignoró. Buena higiene de equipo.

Si quieres ver el resultado crudo, sin honrar los ignores, hay dos flags:

npx impeccable detect --no-inline-ignores src/   # ignora los comentarios de waiver
npx impeccable detect --no-config src/           # ignora toda la configuracion

Configuración del detector

Además de los waivers inline, el detector lee su configuración de .impeccable/config.json (y de .impeccable/config.local.json para overrides locales que no se commitean). Las tres claves clave para controlar el ruido son:

{
  "detector": {
    "ignoreRules": ["bounce-easing", "cream-palette"],
    "ignoreFiles": ["src/legacy/**", "vendor/**"],
    "ignoreValues": {
      "overused-font": [
        { "value": "Inter", "reason": "Fuente oficial de marca" }
      ]
    },
    "designSystem": { "enabled": true }
  }
}

Estas mismas operaciones tienen atajos en el CLI, sin editar el JSON a mano:

npx impeccable ignores list                                       # muestra los ignores activos
npx impeccable ignores add-file "src/legacy/**"                   # agrega un archivo/glob
npx impeccable ignores add-value overused-font Inter --reason "Brand font"

La diferencia entre ignore inline e ignore de config es de alcance y de intención: el inline documenta una excepción puntual junto al código que la justifica; el de config aplica una política transversal a todo el proyecto. Usa inline para lo local y excepcional, y config para lo global y estructural.

Cómo integrar el detector en tu flujo

Hay dos formas de poner el detector a trabajar, y conviene usar ambas.

Manual: como linter bajo demanda

La forma más simple es correrlo tú mismo antes de dar por terminada una pantalla:

npx impeccable detect src/components/PricingCard.tsx

Lo lees, decides qué arreglar y qué silenciar con un waiver, y vuelves a correrlo. En CI lo encadenas con --json para fallar el pipeline cuando aparecen hallazgos nuevos:

npx impeccable detect --json . > impeccable-report.json

Automático: vía hooks del agente

La integración más potente es la que conecta el detector con tu agente de coding. Al instalar Impeccable, el instalador configura hooks nativos del proveedor (Claude Code, GitHub Copilot, Codex, Cursor) que corren el detector automáticamente cuando el agente edita archivos de UI directamente, y le devuelven los hallazgos al agente para que se autocorrija en el momento.

Así, el detector deja de ser un paso manual y se convierte en un guardarraíl permanente: el agente escribe una tarjeta con un side-tab, el hook lo detecta, y el propio agente la corrige antes de que tú la veas. Estos hooks respetan tu .impeccable/config.json y honran los waivers inline por defecto, de modo que el comportamiento automático es coherente con el manual.

sequenceDiagram
    participant A as Agente de coding
    participant H as Hook nativo
    participant D as Detector (CLI)
    participant U as Usuario
    A->>A: Edita archivo de UI
    A->>H: Dispara hook on-edit
    H->>D: npx impeccable detect (respeta config + waivers)
    D-->>H: Hallazgos (JSON)
    H-->>A: Devuelve hallazgos al agente
    A->>A: Autocorrige el AI slop
    A->>U: Entrega UI ya saneada

La configuración fina de estos hooks (hook.enabled, hook.auditLog para logging NDJSON, y el resto del workflow de equipo) la cubrimos en el capítulo 12. Por ahora basta con saber que el detector es la pieza que esos hooks ejecutan.

Resumen

El detector es el corazón determinista de Impeccable: un CLI independiente, sin API key, que aplica 44 reglas mecánicas sobre archivos, directorios o URLs mediante npx impeccable detect. Sus cuatro motores —estático, regex, visual y browser— cubren desde el texto del código hasta los píxeles renderizados con Puppeteer. Las reglas se reparten en dos familias: AI slop (side-tab, dark-glow, ai-color-palette, cream-palette, overused-font, icon-tile-stack, bounce-easing, gradient-text y los tells de copy) y calidad general (line-length, cramped-padding, low-contrast, skipped-heading, tiny-text y más), con reglas extra que validan tu propio DESIGN.md. Cuando una regla se equivoca o la excepción es deliberada, la silencias con ignores inline (impeccable-disable, -line, -next-line) o con la configuración de .impeccable/config.json (ignoreRules, ignoreFiles, ignoreValues). Y lo integras a tu flujo de dos maneras: manualmente como linter en CI, o automáticamente vía los hooks del agente que le devuelven los hallazgos para que se autocorrija.

Con el detector dominado, ya tienes el suelo firme. En el próximo capítulo subimos un nivel: los comandos que sí razonan con un modelo para planificar diseño antes de escribir código.

Siguiente: Comandos de planificación: craft, shape, document, extract

← Volver al listado de tecnologías ← Índice de Impeccable