Introducción y filosofía de Impeccable

Bienvenido al primer capítulo de este curso “de 0 a hero” sobre Impeccable. Si alguna vez le pediste a un agente de IA que construyera una landing page, un dashboard o un formulario y el resultado te pareció… correcto pero genérico, sin alma, como si lo hubieras visto mil veces antes, este curso es para ti. Impeccable existe precisamente para romper ese molde. En este capítulo vamos a entender qué es, qué problema resuelve, cuál es su filosofía y qué piezas componen el framework. No instalaremos nada todavía (eso lo veremos en el siguiente capítulo); aquí construimos los cimientos conceptuales para que todo lo demás tenga sentido.

¿Qué es Impeccable?

Impeccable es una design skill (una habilidad de diseño) para agentes de IA de coding. En lugar de ser una librería que importas en tu código o un componente de UI, es una capa de guía y vocabulario que se instala junto a tu agente —Claude Code, Cursor, GitHub Copilot, Codex, Gemini CLI y otros— para que produzca interfaces frontend de calidad de producción, con decisiones de diseño comprometidas y un nivel de detalle excepcional.

Fue creado por Paul Bakaus (usuario pbakaus en GitHub), se distribuye bajo licencia Apache 2.0 y está publicado en npm como el paquete impeccable. El repositorio oficial vive en github.com/pbakaus/impeccable.

La idea central es simple pero poderosa: los agentes de IA ya saben escribir HTML, CSS y JavaScript correctos. Lo que les falta no es capacidad técnica, sino criterio de diseño y un contexto compartido. Impeccable les da exactamente eso: un lenguaje común para hablar de jerarquía, ritmo visual, tipografía, color y movimiento, además de reglas concretas sobre qué hacer y qué evitar.

El propio skill se describe a sí mismo de forma muy directa:

“Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft.”

Es decir: código real que funciona, decisiones de diseño comprometidas (no tibias) y una artesanía excepcional.

El problema: el “AI slop” en el diseño

Para entender por qué Impeccable es necesario, primero hay que nombrar el problema. En la comunidad se le llama AI slop: esa estética genérica, repetitiva y sin intención que producen los modelos cuando se les pide diseñar una interfaz.

¿Por qué ocurre? Porque casi todos los modelos fueron entrenados con las mismas plantillas de SaaS. Han visto millones de páginas que se parecen entre sí, y por defecto convergen hacia ese promedio estadístico. El resultado es un diseño que técnicamente está “bien”, pero que carece de personalidad y que cualquier persona con ojo entrenado reconoce al instante como “hecho por IA”.

Impeccable identifica de forma explícita un catálogo de estos anti-patrones recurrentes. Estos son los más característicos:

• La fuente Inter para absolutamente todo (y otras tipografías sobreutilizadas como Arial o las fuentes del sistema por defecto).
• Gradientes de morado a azul (el famoso purple-to-blue) como recurso visual comodín.
• Cards anidadas dentro de cards (card-within-card), creando capas innecesarias de contenedores.
• Texto gris sobre fondos de color, que casi siempre rompe el contraste y se ve desvaído.
• Tiles de iconos con esquinas redondeadas colocados encima de cada encabezado, de forma mecánica.
• Easing de tipo bounce o elastic, un movimiento que se siente anticuado.
• Negro y gris puro sin tinte, neutros planos que se ven fríos y sin carácter.
• Bordes laterales de color en cards y alertas (side-tab borders).
• Glows oscuros y resplandores decorativos sin propósito.
• Touch targets pequeños y padding apretado que perjudican la usabilidad.
• Saltos en la jerarquía de encabezados (pasar de un h1 a un h4) y problemas de longitud de línea.

Cada uno de estos puntos parece menor por separado, pero juntos forman la firma inconfundible del AI slop. Impeccable los trata como señales medibles y, como veremos, muchos de ellos son detectados de forma automática.

La filosofía: vocabulario y contexto compartido

La propuesta de Paul Bakaus no es imponer un único estilo “correcto” ni convertir todo en otra plantilla más. Es justo lo contrario. La filosofía de Impeccable es dar a los agentes un vocabulario y un contexto compartido para que produzcan trabajo más variado e intencional.

La diferencia es sutil pero fundamental. Una plantilla te da un resultado fijo; un vocabulario te da la capacidad de tomar decisiones. Cuando el agente entiende conceptos como “nivel de compromiso del color” (de restrained a drenched), “ritmo de espaciado”, “ejes contrastantes en la tipografía” o “curvas de easing exponenciales”, deja de copiar el promedio y empieza a elegir con criterio.

Para que esas elecciones sean coherentes con tu proyecto y no genéricas, Impeccable introduce dos archivos de contexto que estudiaremos en detalle en el capítulo 3:

• PRODUCT.md — captura el contexto de tu producto: audiencia, brand lane (el carril o personalidad de marca), tono de voz.
• DESIGN.md — documenta tu sistema de diseño: colores, tipografía, componentes y convenciones.

Con ese contexto en mano, el agente diseña para tu producto, no para “un SaaS cualquiera”. Esa es la esencia de Impeccable: mover el trabajo desde los defaults de plantilla hacia decisiones deliberadas y propias.

Además, el skill incorpora reglas de diseño concretas que actúan como barandillas. Algunos ejemplos del propio SKILL.md:

• Color: el texto de cuerpo exige un contraste mínimo de 4.5:1; el texto grande, 3:1. El gris sobre fondos de color debe ser un tono más oscuro del propio matiz del fondo, nunca un gris lavado.
• Tipografía: limitar la longitud de línea del cuerpo a 65–75 caracteres (ch); usar text-wrap: balance en h1–h3; evitar emparejar fuentes demasiado similares.
• Layout: variar el espaciado para crear ritmo; usar flexbox para una dimensión y grid para dos; emplear escalas semánticas de z-index.
• Movimiento: que sea intencional, con ease out de curvas exponenciales, y que respete siempre prefers-reduced-motion.

Y, de forma complementaria, una lista de prohibiciones absolutas que el agente debe reconocer y rechazar: bordes laterales de color de más de 1px, texto con gradiente vía background-clip: text, glassmorphism como decoración por defecto, la plantilla del “héroe métrico” (un número gigante con una grilla de estadísticas), grillas de cards idénticas repetidas hasta el infinito, los eyebrows en mayúsculas diminutas sobre cada sección, los marcadores numerados de sección (01/02/03) como andamiaje por defecto, y el texto que se desborda de su contenedor en cualquier breakpoint.

¿Qué incluye Impeccable?

Impeccable es un paquete compacto pero completo. Estas son sus piezas principales:

• 1 skill (/impeccable): la interfaz de comandos a través de la cual se invoca todo.
• 23 comandos: un vocabulario de diseño unificado para planificar, revisar, refinar, mejorar y adaptar interfaces.
• 44 reglas detectoras deterministas: detección de anti-patrones sin necesidad de LLM ni API key. Son comprobaciones puramente algorítmicas, rápidas y reproducibles.
• Live browser iteration: un modo de variantes visuales (/impeccable live) que permite iterar directamente en el navegador, seleccionando elementos en vivo.
• Hooks por proveedor: manifiestos nativos para cada agente —Claude Code, GitHub Copilot, Codex y Cursor— que integran Impeccable en su ciclo de vida.

La versión del skill documentada en el repositorio al momento de escribir este curso es la 3.8.0.

Cómo se invocan los comandos

Todos los comandos siguen la misma sintaxis dentro de tu agente:

/impeccable <comando> <target>

Donde <comando> es la acción y <target> es lo que quieres trabajar (una página, una sección, una feature). Algunos ejemplos reales tomados de la documentación:

/impeccable audit blog
/impeccable critique landing
/impeccable polish settings
/impeccable harden checkout
/impeccable bolder this hero section

El detector, en cambio, se ejecuta desde la terminal como un CLI independiente, sin pasar por el agente:

npx impeccable detect src/
npx impeccable detect index.html
npx impeccable detect https://example.com
npx impeccable detect --json .

Veremos el detector a fondo en el capítulo 4.

Visión general de las categorías de comandos

Los 23 comandos se organizan en categorías según su propósito. No vamos a profundizar aquí —cada grupo tiene su propio capítulo—, pero conviene tener el mapa completo desde el principio. Esta tabla es tu brújula para el resto del curso:

Categoría	Comandos	Para qué sirven
Planificación	craft, shape, document, extract, init	Planear la UX/UI antes de escribir código, documentar el sistema existente y extraer tokens reutilizables
Revisión	critique, audit, polish	Evaluar el diseño: heurísticas de UX, comprobaciones técnicas (accesibilidad, performance, responsive) y pulido final
Refinamiento	bolder, quieter, distill, harden	Ajustar la intensidad de un diseño: amplificarlo, calmarlo, reducirlo a su esencia o endurecerlo para producción
Mejora	layout, typeset, colorize, animate, delight, overdrive, onboard	Trabajar la estructura visual, la tipografía, el color, el movimiento y los momentos de deleite
Contenido y adaptación	clarify, adapt, optimize	Mejorar el texto de la interfaz, adaptar a distintos dispositivos y optimizar el rendimiento
Iteración	live	Modo de variantes visuales en el navegador

A esto se suman los comandos de gestión: pin y unpin (para crear atajos directos, por ejemplo /impeccable pin audit genera un /audit independiente) y hooks (para activar, desactivar o consultar el estado de los hooks).

El recorrido del curso seguirá este mapa: planificación en el capítulo 5, revisión en el capítulo 6, refinamiento en el capítulo 7, estructura visual en el capítulo 8, movimiento y deleite en el capítulo 9, contenido y adaptación en el capítulo 10, el modo live en el capítulo 11 y los hooks y la configuración de equipo en el capítulo 12.

El flujo general de Impeccable

¿Cómo encajan todas estas piezas en la práctica? El recorrido típico empieza por establecer el contexto (init genera PRODUCT.md y DESIGN.md), continúa con la invocación de comandos según lo que necesites, y se apoya en dos mecanismos de control de calidad: el detector determinista y los hooks que lo integran en el ciclo de vida de tu agente. El siguiente diagrama resume esa relación:

flowchart TD
    A[npx impeccable install] --> B[/impeccable init/]
    B --> C[Contexto de diseño<br/>PRODUCT.md + DESIGN.md]
    C --> D{¿Qué necesitas?}
    D -->|Planificar| E[craft · shape · document · extract]
    D -->|Revisar| F[critique · audit · polish]
    D -->|Refinar| G[bolder · quieter · distill · harden]
    D -->|Mejorar| H[layout · typeset · colorize · animate · delight]
    D -->|Adaptar| I[clarify · adapt · optimize]
    D -->|Iterar en vivo| J[live]
    E --> K[Código frontend]
    F --> K
    G --> K
    H --> K
    I --> K
    J --> K
    K --> L[Detector: 44 reglas deterministas<br/>npx impeccable detect]
    K --> M[Hooks por proveedor<br/>Claude Code · Cursor · Copilot · Codex]
    L --> N[Diseño intencional, sin AI slop]
    M --> N

La gracia del diseño de Impeccable es que el detector funciona sin API key: es código que analiza tu HTML/CSS y marca los anti-patrones de forma objetiva. Los hooks, por su parte, hacen que esas comprobaciones se ejecuten automáticamente en el momento adecuado del flujo de tu agente, sin que tengas que recordar lanzarlas a mano.

¿Para quién es este curso y cómo está estructurado?

Este curso está pensado para desarrolladores frontend, diseñadores que escriben código y cualquiera que trabaje con agentes de IA de coding y quiera que el resultado deje de parecer una plantilla genérica. No necesitas ser experto en diseño: precisamente la idea es que Impeccable te aporte el vocabulario que quizás aún no tienes.

Tampoco necesitas conocimientos previos de Impeccable —partimos de cero—. Sí ayuda estar cómodo con la terminal, con npx y con tu agente de IA favorito (los ejemplos usarán la sintaxis /impeccable común a todos ellos).

El curso avanza de forma progresiva, de lo conceptual a lo práctico:

1. Introducción y filosofía (este capítulo): el porqué de Impeccable.
2. Instalación y configuración: cómo ponerlo a funcionar.
3. El contexto de diseño: init, PRODUCT.md y DESIGN.md.
4. El detector: las 44 reglas deterministas.
5. a 10. Los comandos, agrupados por categoría.
6. Live browser iteration: el comando live.
7. Hooks, configuración avanzada y workflow de equipo.

Cada capítulo construye sobre el anterior y enlaza con los siguientes, de modo que al final tendrás una visión completa: desde la primera instalación hasta integrarlo en el flujo de un equipo.

Resumen

Impeccable es una design skill para agentes de IA de coding, creada por Paul Bakaus, con licencia Apache 2.0 y disponible en npm como impeccable. Su razón de ser es combatir el AI slop: esa estética genérica y repetitiva —fuente Inter para todo, gradientes morado-a-azul, cards anidadas, texto gris sobre color, neutros sin tinte, easing anticuado— que producen los modelos entrenados con las mismas plantillas de SaaS. Su filosofía no es imponer un estilo, sino dar a los agentes un vocabulario y un contexto compartido (a través de PRODUCT.md y DESIGN.md) para producir trabajo más variado e intencional. El framework incluye 1 skill, 23 comandos (invocados como /impeccable <comando> <target> y agrupados en planificación, revisión, refinamiento, mejora, contenido e iteración), 44 reglas detectoras deterministas que funcionan sin API key, live browser iteration y hooks por proveedor. En el resto del curso recorreremos cada una de estas piezas con ejemplos concretos.

Siguiente: Instalación y configuración inicial