criterio

Quickstart · Cómo funciona · El gate · Los 6 ejes · Skills · Limitaciones

Tu agente no falla por falta de capacidad. Falla por falta de criterio. Cuando le pides "una landing moderna", te entrega la mediana estadística de todo lo que vio en su entrenamiento. Esa mediana tiene nombre: Inter, indigo, radio 16px, hero centrado, tres cards con icono.

criterio no te da UI bonita. Te da un contrato verificable que el agente lee antes de escribir la primera línea de componente — y un gate que falla con exit 1 cuando el contrato se rompe.

[!NOTE] Cero dependencias. Cero build. Cero API keys. Un solo requisito: Node 18+. Todo lo que hace son scripts de Node y archivos de texto que tu agente lee.

El antes / después

Mismo prompt, mismo modelo, mismo día. Lo único que cambia es si existe un contrato.

Fuente:   Inter 400/600
Acento:   #6366F1 + gradiente a #8B5CF6
Fondo:    #FFFFFF sobre #F9FAFB
Radios:   16px en TODO
Hero:     centrado, headline 60px, un CTA
Cuerpo:   3 cards con icono
Motion:   fade 500ms en todo
Copy:     "Build the future of work"

Fuente:   display + use_for[] / avoid_for[]
Acento:   tu hex, con nombre; hue [235-285]
          bloqueado salvo excepción
Radios:   máx 3 valores — regla numérica
Densidad: un número 1-5 con justificación
Motion:   4 duraciones nombradas; props
          de reflow prohibidas
Copy:     avoid_words[] con ~25 frases

🔩 Cómo funciona

No es magia ni un modelo más listo. Es un archivo que el agente no puede ignorar y un script que lo verifica. Cuatro pasos, y el tercero es el que hace el trabajo.

El problema

Los tells son siempre los mismos y ya están documentados:

• Inter o Roboto — "Inter or Roboto font (never anything with personality)", en la lista de prg.sh. 925studios lo dice de Inter en particular: "the default font in nearly every AI design tool, component library, and website builder".
• Acento morado/indigo, casi siempre con gradiente a azul.
• Hero centrado con un CTA, y debajo tres features en cajas con icono.
• Esquinas redondeadas en todo, con el mismo radio.
• Sombras sutiles de opacidad 0.1, idénticas en cada superficie.
• Copy vago: "Build the future of work", "all-in-one platform", "scale without limits".

La causa raíz es de corpus, no de gusto. Adam Wathan se disculpó públicamente en X (agosto 2025) por haber hecho que cada botón de Tailwind UI — la librería de componentes de pago, no Tailwind CSS core — fuera bg-indigo-500 cinco años atrás, "leading to every AI generated UI on earth also being indigo".

[!TIP] El modelo no elige morado porque el morado sea bueno. Lo elige porque es estadísticamente común en el corpus. Te está dando la mediana, y la mediana no es una decisión.

→ Detalle completo y fuentes en docs/01-por-que-todo-se-ve-igual.md

🚀 Quickstart

Tres comandos. No hay paso 4.

# 1 · Trae criterio a tu proyecto (no instala nada global, no toca tu package.json)
npx degit Carlos-Dominguez-faber/criterio .criterio

# 2 · Entrevista de 8 preguntas → escribe brand.json, voice.json, motion.json,
#     brand.css y COMPONENT_RULES.md
node .criterio/scripts/init.mjs

# 3 · Verifica que tu contrato no tenga slop. Exit 0 = pasa · exit 1 = qué arreglar
node .criterio/scripts/gate.mjs

Y el paso que no es comando:

[!IMPORTANT] Abre Claude Code y dile: "Lee brand.json y COMPONENT_RULES.md antes de escribir cualquier componente." Ese es el mecanismo entero. El contrato solo funciona si el agente lo lee primero.

node scripts/test.mjs
#  ✔ las 4 plantillas parsean como JSON
#  ✔ la fórmula de contraste WCAG da 21:1 en negro sobre blanco
#  ✔ los 5 presets generan contratos que pasan su propio gate
#  ✔ el gate FALLA con el indigo #8B5CF6 y con transition: all
#
#  PASS — 17 ok, 0 fallando

Qué acabas de generar

Ese brand.css no es una lista plana de colores. Sale en tres niveles, y las referencias van en un solo sentido — así cambias la marca en un lugar y baja hasta el último botón:

→ Por qué tres niveles y no uno, en docs/03-design-tokens-en-3-niveles.md

📐 Los 6 ejes y los 5 presets

Los adjetivos no son verificables. "Que se vea moderno" no significa nada. Seis números del 1 al 5, cada uno con una frase que lo justifica, sí.

density · expression · geometry · warmth · editoriality · materiality

Las marcas de referencia son calibración, no objetivo. Sirven para que dos personas discutan si expression: 4 es demasiado, que es exactamente la conversación que "hazlo moderno" impide tener.

→ Los 6 ejes explicados uno por uno en docs/02-los-6-ejes.md

🚦 El gate

node .criterio/scripts/gate.mjs corre checks binarios contra tu contrato. Sin LLM, sin red, sin ambigüedad. Exit 0 pasa, exit 1 falla.

Salida real del check de hue cuando pones #6366F1 como primary:

[FAIL] Zona de hue restringida restricted_hues
     real:     primary=#6366F1 (Indigo) → hue 239° · arquetipo Caregiver
     esperado: hue fuera de [235, 285] o excepcion explicita

     El hue 239° cae en la zona morado/indigo, que es el default
     estadistico de todo modelo. Elige un primary fuera de [235, 285].
     Si el morado es una decision real y no una inercia, declara el
     arquetipo "Magician" o agrega "purple_as_primary" a
     brand.archetype.allowed_behaviors — y justifica por que.

────────────────────────────────────────────────────────────────────────
FAIL — 6/8 checks. Falla: forbidden_colors, restricted_hues.

Arregla el contrato y vuelve a correr el gate. Exit 1.

Los 8 checks, todos binarios y sin opinión:

[!WARNING] El check 6 es el que separa un linter de un contrato: valida coherencia entre dos archivos (brand.json × voice.json), no valores sueltos. El check 7 convierte una regla de performance en un dato verificable. Eso es el punto entero: el buen gusto no se pide, se testea.

→ Los 8 checks, uno por uno, en skills/design-audit/references/checklist.md · la implementación vive en scripts/lib/checks.js

🧩 Las 3 skills propias

Escritas desde cero, MIT, en español. Viven en skills/ y se copian a ~/.claude/skills/.

La diferencia con los auditores de terceros: hallmark audit y /impeccable audit juzgan tu UI contra su criterio. design-audit la juzga contra tu contrato. Esa es la distinción que hace que el alumno aprenda a decidir en vez de a obedecer.

🔗 Recursos curados de terceros

criterio enlaza, nunca copia. Cero código ajeno vendorizado en este repo — así la atribución queda clara, la licencia intacta y nada envejece en dos semanas.

Más los recursos de navegador sin instalación (NameThatUI, Kinetics) y —lo más importante— qué dejamos fuera y por qué.

→ Todo el detalle en curated/README.md · comandos comentados en curated/install.sh

✅ Checklist de cierre

Al terminar cualquier build, pega esto en Claude Code:

Revisa la UI que acabas de escribir contra estas 10 preguntas.
Responde cada una con SÍ/NO y, si es NO, con el fix concreto en una línea.

1.  ¿Cada color que usaste está en brand.json? ¿Alguno tiene hue entre 235 y 285?
2.  ¿Cuántas familias tipográficas hay en pantalla? ¿Alguna se usó en un contexto
    que su avoid_for[] prohíbe?
3.  ¿Cuántos valores de border-radius distintos existen? ¿Más de 3?
4.  ¿El texto de cuerpo pasa 4.5:1 de contraste contra su fondo real?
5.  ¿Hay jerarquía visual más allá de "texto más grande = título"?
6.  ¿Alguna transición anima width, height, padding, margin, top, left, right o
    bottom? Esas causan reflow.
7.  ¿Las entradas usan ease-out y las salidas ease-in? ¿Algún feedback de
    interacción pasa de 200ms?
8.  ¿Existe una regla de prefers-reduced-motion?
9.  ¿El copy contiene alguna palabra de voice.json avoid_words[]?
10. ¿Los inputs tienen indicador de campo requerido y estado de error visible?

→ Versión larga, con el porqué de cada pregunta, en checklists/ui-review.md → Cómo se ve un prompt de UI que sí funciona: checklists/prompt-anatomy.md

⚖️ Limitaciones honestas

Esta sección es la que separa un regalo serio de una promesa inflada. Léela antes de instalar nada.

No te va a dar buen gusto. criterio hace que tus decisiones sean explícitas y consistentes. Si eliges mal los seis ejes, vas a obtener una UI consistentemente mala. El contrato amplifica criterio; no lo sustituye.

No elimina el AI slop. Lo reduce. El gate atrapa lo numéricamente verificable: hues, contrastes, conteos de radios y de fuentes, props inseguras animadas. No atrapa un layout aburrido ni una idea perezosa. Nadie que te prometa "elimina el slop" te está diciendo la verdad.

📜 Créditos y licencia

criterio es MIT. Copyright (c) 2026 Carlos Domínguez.

Todo lo que está en skills/, scripts/, templates/, presets/, docs/ y checklists/ está escrito desde cero para este repo.

Nada de curated/ está copiado aquí. Crédito completo a sus autores, cada uno bajo su propia licencia:

• hallmark — Nutlope (Hassan El Mghari) / Together AI · MIT
• skills (7 skills de animación e interfaz) — Emil Kowalski · MIT
• impeccable — Paul Bakaus · Apache-2.0
• frontend-design — Anthropic · repo anthropics/skills, sin SPDX estándar declarado
• ui-skills — Julien Thibeaut (@ibelick) · MIT
• interface-design — @Dammyjay93 · MIT
• web-animation-skills — iart-ai · MIT declarada en el hub iart-ai/motion-skills
• NameThatUI — Argo · gratuito, uso vía navegador
• Kinetics — ckissi (familia Colorion) · MIT
• cuelume — Daniel Belyi · MIT

Fuentes citadas y sus precisiones — incluida la de Tailwind UI vs Tailwind CSS core, el estatus del formato de design tokens como especificación del Community Group del W3C (no estándar W3C), y que Theo está archivado mientras el equivalente vivo es Style Dictionary — están en docs/99-fuentes.md.

👑 Comunidad

criterio salió de una clase de Imperio Agéntico, la comunidad de educación técnica en IA y automatización donde enseño La Forja: la metodología de desarrollo multi-agente con Claude Code de la que este repo es un pedazo.

Si algo de aquí te falla, te sobra o te falta, ábreme un issue. El repo mejora con los casos reales de quien lo usa.