joo6077/design-audit

Gotchas

1. No evaluar calidad del código — No evalúes arquitectura, rendimiento ni estilo de código. Solo determina el cumplimiento de principios de diseño.

2. No usar excesivamente FAIL por "token no utilizado" — En proyectos sin sistema de tokens de diseño, no marques FAIL por "token no utilizado". Si no hay un sistema de tokens, recomienda usar la skill design-system con una NOTA.

3. Categoría de accesibilidad obligatoria — Aunque visualmente se vea bien, debes inspeccionar: contraste (WCAG 2.2 AA 4.5:1), objetivos táctiles, indicadores de foco, etiquetas de formulario, nuevos SC de WCAG 2.2 (Focus Not Obscured 2.4.11 AA, Dragging Movements 2.5.7 AA, Accessible Authentication Min 3.3.8 AA). Si se omite, REJECT.

   Criterios de tamaño de objetivo táctil (actualizado 2026-04-11):

   • WCAG 2.2 SC 2.5.8 Target Size (Minimum) — AA = 24×24 CSS px (excepciones: suficiente espaciado / texto en línea / agente de usuario / esencial)
   • WCAG 2.2 SC 2.5.5 Target Size (Enhanced) — AAA = 44×44 CSS px
   • Apple HIG 44pt = recomendación práctica para dispositivos táctiles (guía de plataforma)

   Si en informes anteriores solo se indicaba "44×44pt", el lector podría interpretarlo erróneamente como "requisito WCAG AA". Por lo tanto, se debe diferenciar entre AA/AAA/recomendación de plataforma. Fuente: W3C WCAG 2.2 SC 2.5.8, W3C What's New in WCAG 2.2.

4. Incluir inspección de antipatrones de IA — La categoría de Autenticidad debe incluirse obligatoriamente. Los border-radius uniformes, las paletas genéricas azul-violeta, la repetición de la misma estructura y los efectos decorativos sin propósito son motivos de FAIL.

5. Clasificación de severidad obligatoria — Cada ítem FAIL debe indicar su severidad: Critical (accesibilidad, ética), Major (jerarquía, consistencia), Minor (ajustes menores). Un informe FAIL sin severidad está incompleto.

6. Prohibición de juicios subjetivos — "Se ve bien", "Está aceptable" no son fundamentos válidos. Cada PASS/FAIL debe basarse en los principios y criterios numéricos definidos en audit-criteria.md.

7. Incluir estados/vistas de excepción — No inspecciones solo la vista principal. Si existen en el código estados vacíos, de error, de carga y de datos excesivos/insuficientes, inspecciónalos también.

8. Diferenciar ítems no verificables con código — Para elementos que no se pueden determinar mediante análisis estático (como renderizado en tiempo de ejecución, interacciones reales), márcalos como [Unverified] y proporciona instrucciones para verificación manual.

9. No confundir heurísticas con categorías — Las 10 heurísticas de Nielsen son un marco de perspectiva de evaluación. La determinación real debe realizarse siempre mapeando según los criterios de las 10 categorías de audit-criteria.md (Tipografía, Color, Espaciado, Accesibilidad, Interacción, Movimiento, Jerarquía Visual, Diseño y Rejilla, Diseño Ético, Autenticidad).

10. Auditoría regla por regla: cotejar las 10 categorías antes de declarar finalización — Antes de decidir APPROVE/REJECT, se debe recorrer cada una de las 10 categorías × puntos de control clave de audit-criteria.md e incluir en el informe una tabla con PASS / FAIL / [Unverified] para cada elemento. No agrupes categorías como "no aplica"; indica el motivo. Una auditoría que omite categorías no es una auditoría (corresponde a §3.6 Rule-by-Rule Audit de skill-design-guide).

11. Verificación previa de decidibilidad binaria: comprobar la posibilidad de decisión binaria antes de comenzar la auditoría — Después de definir el alcance de la auditoría, verifica primero si cada posible ítem FAIL es "decidible binariamente solo con código/estilo/tokens". Los elementos que requieran renderizado en tiempo de ejecución, interacción real o comparación con MCP Figma deben clasificarse inmediatamente como [Unverified] y no aprobarse como PASS. Los no verificados se cuentan en dos contadores: invalid_evidence ([Unverified:INVALID] · [Unverified] sin sufijo) cuenta como 0 para fallos normales, 1 permite PASS + advertencia, 2 o más es REJECT incluso sin FAIL individuales. Los [Unverified:ENV] que cumplen los 4 requisitos se cuentan por separado como env_gaps y no se incluyen en el recuento de REJECT; si verified_coverage es inferior a 0.60, es BLOCKED. Esta regla tiene como texto oficial la cláusula "El umbral es 2" de harness/docs/guides/qa-evaluation-guide.md §Canonical Unverified-Evidence Protocol, y no se redefine aquí. Debe tener el mismo valor que la copia de la regla 8 de design-reviewer (corresponde a §3.5 Binary Decidability de agent-design-guide, reflejado en la skill).

12. Puerta de validez de evidencia: "tener evidencia" y "la evidencia demuestra" son cosas diferentes — Mientras que Gotcha 11 trata sobre si se puede obtener evidencia, este ítem trata sobre casos en los que se obtuvo evidencia pero no demuestra nada. Antes de confirmar un PASS, pasa las 4 verificaciones. Si alguna falla, no es PASS sino [Unverified].

    #	Verificación	Ejemplo de fallo (contexto de auditoría)
    1	No vacío	Citar como evidencia una instantánea de 0 bytes, un registro que solo contiene errores
    2	Activación	"Sin violaciones de contraste PASS" cuando hay 0 nodos de texto objetivo para la verificación de contraste
    3	Falsabilidad	Usar como oráculo un grep que produce el mismo resultado para cualquier código
    4	Fuente	Adoptar como evidencia el comentario del implementador "Accesibilidad verificada" o un mensaje de commit

    Determinación de 0 coincidencias — Un grep con 0 resultados tiene dos casos. Solo el 0 intencionado (contar primero el número de archivos objetivo, confirmar que el patrón coincide en otro lugar) es base para PASS. El 0 vacío (ruta incorrecta, archivo vacío, patrón que nunca coincide) es una falla de medición y es [Unverified]. En la declaración de la evidencia, se deben incluir los tres elementos en forma de N archivos objetivo · validación del patrón · 0 coincidencias.

    Regla especial para resultados de renderizado — Una captura de pantalla de pantalla vacía, lista vacía o solo con marcadores de posición no es evidencia de PASS, sino señal de fallo de verificación. Al usar una captura como evidencia, señala el elemento concreto que requiere la condición. Si no se puede señalar, la evidencia es inválida. Para cada captura, consulta la lista de verificación de capturas de ../../references/visual-change-protocol.md §3 (desbordamiento, glifos rotos, chips/insignias y formas de línea, superposición de depuración). Cualquier captura que falle no se usará como evidencia de PASS. Fuente: harness/docs/guides/qa-evaluation-guide.md §Evidence Validity Gate.

13. Auditoría de contraste Antes/Después: cambios en áreas no intencionadas son FAIL — Al auditar cambios (según git diff), no te limites a ver el estado estático; compara el alcance solicitado con el alcance real del cambio. Si la solicitud señalaba un único atributo visual específico (solo borde, solo color, solo espaciado) y el mismo elemento ha cambiado también en background / fill / radius / shadow / spacing / typography, es FAIL Major. Si hay una maqueta aprobada o colores de la aplicación existente y se han reemplazado por tokens del proyecto o la paleta base, es FAIL Major (violación de prioridad). El informe de auditoría se cierra con un bloque EVIDENCE (before / after / proof / área no intencionada). Detalles: ../../references/visual-change-protocol.md.

14. Cobertura de propagación de decisiones: una decisión confirmada aplicada solo a una superficie parcial es FAIL Major — Si existe .design/decisions.yaml, determina la cobertura antes de la auditoría de las 10 categorías (no se añaden categorías — es una verificación de requisito previo). Por cada decision_id con status: approved, recorre required_surfaces[]: (a) si no hay golden ni assertion visible para el usuario, FAIL (b) si solo hay golden pero no hay assertion visible/count/height, FAIL (c) si una superficie falta en excluded_surfaces sin motivo, es una brecha de cobertura y es FAIL. La severidad es Major, o Critical para decisiones de accesibilidad/ética. Las decisiones con status: superseded (reemplazadas) no determinan la posición de la pantalla; solo verifican que superseded_by apunta a otra decisión approved en la misma lista. Si no hay manifest, no es FAIL sino que se reporta como NO_MANIFEST y se excluye del alcance de la auditoría — 0 elementos objetivo no es lo mismo que aprobado. Esquema, regla 4, comprobador ejecutable: ../../references/visual-change-protocol.md §6 Decision Propagation Manifest.

15. Especifica el canal de evidencia: no determines la pantalla de la aplicación con artifact_snapshot — Adjunta el nombre del canal (artifact_snapshot / dom_snapshot / browser_user_visible / device_user_visible) a toda evidencia citada como fundamento. Las declaraciones PASS deben incluir los 5 elementos: viewport · route/state · visible locator · count/height · screenshot/golden id. Si falta alguno, no es PASS sino [Unverified]. Definiciones de canales: ../../references/visual-change-protocol.md §7 Evidence Channels. El protocolo para cuando un informe de fallo de usuario y la auto-evidencia entran en conflicto es el texto oficial de harness/docs/guides/skill-design-guide.md §3.8 · harness/docs/guides/agent-design-guide.md §10, y no se redefine aquí — no refutes las observaciones del usuario con el informe de auditoría.

Proceso

Paso 1: Determinar alcance objetivo y modo

Determina el alcance de la auditoría según la ruta y el modo especificados por el usuario:

• Ruta de archivo → solo ese archivo
• Ruta de directorio → todos los archivos de UI en subdirectorios
• No especificado → archivos de UI modificados recientemente (según git diff)

Modos:

• quick (por defecto) — Inspecciona rápidamente las 10 categorías completas. Se centra en FAIL Critical/Major.
• deep — Inspecciona exhaustivamente estados/vistas de excepción, breakpoints responsivos, modo oscuro y elementos detallados de accesibilidad.

Paso 2: Confirmar categorías de auditoría

Inspecciona las 10 categorías en orden. Puntos de control clave de cada categoría:

Categoría	Puntos de control clave	Criterio de severidad
Tipografía	Consistencia de la escala tipográfica, interlineado (rango por sistema de escritura — fila de relación de interlineado de references/audit-criteria.md), tamaño mínimo de texto 14px (móvil)/16px (web)	Major
Color	Contraste de texto WCAG 2.2 AA 4.5:1, uso de tokens semánticos, mantenimiento del contraste en modo oscuro, verificación de fallback sRGB al usar gama ancha OKLCH/P3. Referencia APCA Lc (informativa): Lc 75~90 para texto principal, Lc 60+ para no texto, Lc <15 es invisible. APCA exige contraste diferencial según tamaño de fuente+grosor, por lo que las fuentes finas requieren mayor contraste. El criterio de determinación es WCAG 2.2 AA; APCA es referencia para WCAG 3.0 WD	Critical (contraste) / Major (token)
Espaciado	Consistencia de la escala de espaciado, objetivo táctil WCAG 2.2 SC 2.5.8 AA ≥24×24 CSS px (AAA SC 2.5.5 = 44×44), jerarquía de márgenes entre grupos/internos	Critical (táctil) / Major (escala)
Accesibilidad	Prohibición de transmitir estado solo con color, indicador de foco, etiquetas de formulario, texto alternativo, WCAG 2.2 SC 2.4.11 Focus Not Obscured (AA), SC 2.5.7 Dragging Movements (AA), SC 3.3.8 Accessible Authentication Min (AA)	Critical
Interacción	Retroalimentación de acciones, indicador de carga, visualización de errores, rutas de cancelación/deshacer, alternativa de un solo puntero para UX solo de arrastre (WCAG 2.2 SC 2.5.7)	Major
Movimiento	Propósito de la animación, duración 200~500ms, soporte de prefers-reduced-motion	Major
Jerarquía Visual	Diferencia de proporción entre título/texto principal/leyenda, énfasis de contraste del contenido clave, separación de grupos mediante márgenes	Major
Diseño y Rejilla	Alineación a la rejilla, consistencia de canalones, estrategia responsive para breakpoints principales, se recomienda container-type: inline-size + @container para responsive a nivel de componente (soporte de consultas de tamaño: Chrome 105 · Firefox 110 · Safari 16). Verificación de Container Queries: confirmar el uso de media queries para ramificaciones a nivel de página y container queries para ramificaciones a nivel de componente. Se recomienda el uso de unidades cqw/cqi y el establecimiento de breakpoints basados en puntos de ruptura de contenido (no en dispositivos objetivo)	Major
Diseño Ético	Ausencia de 12 tipos de patrones oscuros, claridad del consentimiento, simetría de rutas de registro/baja	Critical
Autenticidad	Repetición de la misma estructura 3 veces o más, paleta genérica, decoración sin propósito, copia genérica, inconsistencia con convenciones de pantallas existentes del mismo rol	Minor~Major

Paso 3: Llamar al agente design-reviewer

Utiliza la herramienta Agent para crear un subagente design-reviewer:

Llamada a herramienta Agent:
- subagent_type: design-reviewer
- prompt: "Evalúa los siguientes archivos según principios de diseño en modo [quick|deep]: [lista de archivos objetivo]"

El agente analiza de solo lectura y devuelve resultados PASS/FAIL/[Unverified] por categoría.

Paso 4: Formatear el informe

Organiza los resultados del agente en el formato de templates/audit-report.md.

Cada ítem FAIL debe incluir obligatoriamente:

• Ubicación archivo:línea
• Severidad (Critical / Major / Minor)
• Principio violado (incluyendo fuente)
• Dirección de mejora concreta (nivel independiente de la pila)

Si hay 1 o más elementos [Unverified], incluye el resumen de validez en el informe (Gotcha 12):

## Validez de Evidencia
- Evidencia examinada: {{n}} elementos
- Determinaciones inválidas: {{k}} elementos [ID del elemento — número de verificación fallida — motivo]
- Acumulado de no verificado: `invalid_evidence` {{a}} elementos / `env_gaps` {{b}} elementos / `verified_coverage` {{c}}

Paso 5: Determinación final

• FAIL 0 + invalid_evidence 0 + verified_coverage ≥ 0.60 + L3 10/10 → APPROVE (indica el número de env_gaps)
• 1 o más FAIL en Cobertura de Propagación de Decisiones → REJECT (condición previa independiente de la determinación de las 10 categorías — Gotcha 14. La ausencia de manifest no es FAIL, sino informe NO_MANIFEST)
• Código de salida 2 de la verificación de propagación de decisiones (SCHEMA_ERROR) significa que la forma de entrada es incorrecta y no se pudo determinar, por lo que es REJECT — aunque aparezca violations=0 sin línea FAIL, no se interpreta como aprobado. El código de salida 3 (NO_SURFACE · NO_DECISION) se reporta como 0 elementos objetivo, igual que NO_MANIFEST
• 1 o más FAIL Critical → REJECT (inmediato)
• Solo FAIL Major/Minor → REJECT + lista de mejoras por prioridad
• FAIL 0 pero 2 o más invalid_evidence → REJECT (umbral Gotcha 11)
• FAIL 0, menos de 2 invalid_evidence, verified_coverage = (número de elementos de verificación determinados − env_gaps) / número de elementos de verificación determinados < 0.60 → BLOCKED (insufficient_verified_coverage — ejecuta de nuevo el comando de re-verificación y luego re-audita)
• Incluso con FAIL 0, si la cobertura L3 < 10/10 (hay categorías omitidas de las 10) → REJECT + indicar las categorías restantes (las categorías omitidas son FAIL — regla 11 del revisor)
• FAIL 0, 1 invalid_evidence, verified_coverage ≥ 0.60, L3 10/10 → APPROVE + indicar elementos [Unverified] y métodos de verificación manual

Estructura del informe REJECT:

1. Lista de FAIL Critical (requieren corrección inmediata)
2. Lista de FAIL Major (corrección antes del próximo sprint)
3. Lista de FAIL Minor (mejora recomendada)
4. Elementos [Unverified] (requieren verificación manual — diferenciar [Unverified:ENV] / [Unverified:INVALID])

Si la auditoría es de cambios (según git diff), cierra el informe con un bloque EVIDENCE (Gotcha 13):

## EVIDENCE
- before: [fundamento del estado antes del cambio — archivo:línea o captura]
- after:  [fundamento del estado después del cambio]
- proof:  [comando y salida que respaldan la determinación]
- Área no intencionada: [fundamento de confirmación de ningún cambio / o elementos tratados como FAIL]

Referencias

• references/audit-criteria.md — Detalles de criterios de auditoría por categoría
• templates/audit-report.md — Formato de salida del informe
• ../../references/visual-change-protocol.md — Prioridad de cambios visuales · Aislamiento de cambios parciales · Bloques de evidencia · §6 Decision Propagation Manifest · §7 Evidence Channels (SSOT)
• harness/docs/guides/skill-design-guide.md §3.8 · harness/docs/guides/agent-design-guide.md §10 — Texto oficial del protocolo de prioridad de informes de fallo de usuario
• harness/docs/guides/qa-evaluation-guide.md §Canonical Unverified-Evidence Protocol · §Evidence Validity Gate — Texto oficial del umbral de no verificado y las 4 verificaciones de validez