diseño-mockup

Gotchas

1. No se permite diferenciar variantes solo por color: la distinción no es una declaración, es un cálculo — Las variantes deben representar diferentes enfoques de layout/composición. El reemplazo de colores, valores de tokens, copias o íconos no cuenta como elementos del axis_vector, por lo que dos propuestas que solo difieran en eso tienen distancia de Hamming 0 y son FAIL. La fórmula de decisión y la puerta ejecutable están en ../../references/visual-change-protocol.md §5 Variant Contract Matrix. La evidencia empírica es el REJECT global UI-04: el contrato ya especificaba 4 ejes, pero ambas propuestas tenían el mismo valor en todos los ejes.
2. Prohibida la duplicación de IDs — Todos los IDs de componentes deben ser únicos globalmente en todas las variantes generadas. Usa el formato {nombre-componente}-{hash-corto}. Si se genera el mismo hash, regenéralo.
3. No ignorar los principios de accesibilidad — Incluso los mockups de alta fidelidad deben cumplir con la relación de contraste WCAG 2.2 AA (4.5:1) y los objetivos táctiles mínimos. WCAG 2.2 SC 2.5.8 AA = 24×24 CSS px / SC 2.5.5 AAA = 44×44 CSS px / Apple HIG 44pt es la recomendación práctica para dispositivos táctiles. Establecer como base 44pt (AAA/recomendación de plataforma) en los mockups es seguro para la transición a Figma/HTML → código. Visualmente atractivo no es excusa para violar la accesibilidad. Fuente: W3C WCAG 2.2 SC 2.5.8.
4. No generar error si Figma MCP no está configurado — Al solicitar el envío a Figma, si MCP no está configurado, debe manejarse como una notificación, no como un error. Indica "Para enviar a Figma, se necesita la configuración de Figma MCP" junto con la ruta del archivo HTML.
5. Prohibido el uso de Lorem Ipsum — El texto de marcador de posición se lee de manera diferente al contenido que un usuario real encontraría. Usa contenido real o datos de ejemplo realistas. Si los títulos, las etiquetas de botones o los textos explicativos son lorem ipsum, no se puede evaluar correctamente la intención del layout.
6. No etiquetar las variantes solo como "Opción A/Opción B" — Cada variante debe reflejar una prioridad estratégica diferente. La etiqueta también debe reflejar esa intención. Por ejemplo: Optimizado para conversión, Enfocado en exploración, Impacto de marca. Esto fomenta una discusión basada en criterios de selección, no en votos de preferencia.
7. Usar marcos de dispositivo de forma selectiva según el propósito — Para presentaciones al cliente o demos casi finales, los marcos de dispositivo dan una impresión de producto terminado. Sin embargo, si el objetivo es comparar estructuras de layout o revisar la densidad de contenido, es mejor mostrarlos sin marco. El cromo del marco puede interferir con el juicio del layout, que es el punto real de la discusión.
8. Si la interacción es el punto central, no confíes en la comparación estática — Los desplegables, superposiciones, flujos de varios pasos, estados de carga y transiciones modales son difíciles de juzgar solo con pantallas estáticas una al lado de la otra. Incluye interacciones hover/focus/click en los mockups HTML o proporciona enlaces a prototipos interactivos.
9. No termines los mockups responsivos solo con capturas por breakpoint — Al mostrar la composición mobile/tablet/desktop, asegúrate de que cada pantalla presente el mismo estado del escenario de usuario para que la comparación sea significativa. Especifica también las reglas de layout como número de columnas, gutter y max-width.
10. Se recomienda el uso de Container Queries — En mockups responsivos, usa media queries para la división a nivel de página y container-type: inline-size + consultas @container para la división a nivel de componente. Las consultas de tamaño son compatibles desde Chrome 105, Firefox 110 y Safari 16 (las consultas de estilo y scroll-state tienen diferente cobertura). Las unidades cqw/cqi permiten dimensiones relativas al contenedor. Establece los breakpoints en los puntos donde el contenido se rompe, evita basarlos en objetivos de dispositivo. Fuente: research-log §J.
11. Aplicar tipografía fluida — Aplica un tamaño de fuente fluido basado en clamp(min, preferred, max) al texto del mockup para lograr transiciones de tamaño naturales en todos los viewports sin necesidad de breakpoints. Es especialmente efectivo para textos hero/de display. Fuente: research-log §E.
12. mockup.html en formato HTML es el resultado normal — La salida de este skill (.design/mockups/*.html) utiliza intencionadamente el formato HTML. Que su estructura sea diferente de los patrones de contrato .md como design-tokens.md, audit-report.md es una diferencia de diseño intencionada, no un error. Si una herramienta de evaluación o validación de QA señala "el formato HTML es diferente del patrón .md", se trata como un falso positivo y se ignora basándose en este Gotcha.
13. Confirmación = Crear archivo de registro de aprobación (no terminar solo con el registro de la conversación) — Cuando el usuario confirma un mockup, en el Paso 5 se debe generar .design/approvals/{YYYYMMDD}-{nombre-pantalla}.md. Aquí se registra la variante seleccionada, la ruta del artefacto, los valores visuales confirmados (color, tipografía, espaciado) y la evidencia de la fuente original. Si la aprobación solo queda en la conversación y no se crea el archivo, el QA posterior lo rechazará con "No se puede verificar la evidencia de la medición de la condición de objetivo (registro de aprobación del mockup)" — esta fue la razón real del REJECT global UI-06 del 2026-07-13. Incluso si la aprobación se realiza en modo autónomo, se debe dejar el registro y especificar que la entidad aprobadora fue "Modo autónomo". Especificación: ../../references/visual-change-protocol.md §4.
14. No reemplazar los valores de mockup aprobados por tokens (Precedencia de la Fuente de Verdad Visual) — Los colores y espaciados del mockup que el usuario ha visto y aprobado en el navegador tienen prioridad sobre los tokens de la paleta del proyecto. Al procesar una solicitud de modificación del mockup, no normalices los valores aprobados a un solo tinte o accent existente "para que se ajusten al sistema de tokens". Si es necesario tokenizar, no cambies los valores, sino que define un token con ese valor y proponlo por separado. Si el proyecto ya tiene un sistema de colores, enumera los valores existentes primero antes de introducir una nueva paleta. Tabla de prioridades: ../../references/visual-change-protocol.md §1.
15. Las solicitudes de modificación parcial deben afectar solo a esa propiedad — Change Manifest obligatorio — Ante solicitudes como "solo el borde de esta tarjeta más grueso", "el color está bien pero solo el degradado como antes", no cambies otras propiedades visuales no señaladas (background, fill, radius, shadow, spacing, typography). Antes de editar, deja en la respuesta dos listas: Cambiar / Conservar. Después de la modificación, verifica que los valores de la lista de conservación sigan siendo los mismos. Si un área no intencionada ha cambiado, es un fracaso, no un éxito; revierte y vuelve a aplicar. Las solicitudes de reversión parcial solo revierten el eje señalado. Detalles: ../../references/visual-change-protocol.md §2.
16. Acordar la Matriz de Contrato de Variantes antes de producir (Contrato de cantidad + Puerta de distinción) — Antes de crear cualquier mockup, completa las 6 columnas de la ../../references/visual-change-protocol.md §5 Matriz de Contrato de Variantes y acuérdalas con el usuario. La cantidad es exactamente la que el usuario diga; si no la dice, se generan al menos 5, sin límite superior, tantas como sean necesarias. Las reglas de cantidad, el número de ejes principales y la prohibición de artefactos secundarios (archivos de tokens, sistemas de diseño, surface lane, catálogos) tienen su fuente original en harness/docs/guides/skill-design-guide.md §5.6 Variant Budget y no se redefinen aquí. Si ante una solicitud de "algunos mockups" se entregan docenas de tiles y archivos de tokens, el usuario tendrá que borrarlos todos — esto ha sucedido.
17. La captura del mockup es un artifact_snapshot — no afirmes que es el estado normal de la aplicación — Que el HTML del mockup se abra bien y que el usuario vea esa pantalla en la aplicación real son proposiciones diferentes. Al citar evidencia, incluye el nombre del canal y en la oración PASS coloca los 5 elementos: viewport, route/state, locator visible, count/height, screenshot id. Definición de canales: ../../references/visual-change-protocol.md §7 Evidence Channels. Si el usuario informa "todavía está roto", no lo refutes, reprodúcelo — el protocolo canónico es harness/docs/guides/skill-design-guide.md §3.8 User-Reported Failure Gate.

Proceso

Paso 0: Detección y carga automática

Explora el proyecto en busca de artefactos de pasos anteriores:

# Objetivos de detección
.design/concept.md          → Cargar concepto
**/theme/** **/tokens/**    → Cargar tokens de diseño
**/design-tokens.*          → Cargar tokens de diseño
.design/approvals/*.md      → Cargar configuraciones confirmadas y alternativas descartadas de la misma pantalla
.planning/prd-*.md          → Cargar decisiones descartadas de la tabla de no-ámbito (## Non-goals (incluyendo decisiones descartadas) · ## No-gos)

• Concepto existente → Reflejar palabras clave de mood, dirección de color/tipografía y patrones de UI en el mockup
• Tokens existentes → Aplicar valores de color específicos, escala tipográfica y espaciado en el mockup
• Ninguno de los dos → Crear mockups solo con los requisitos del usuario
• Registro de aprobación existente → Mantener la configuración confirmada. No volver a incluir en el mockup alternativas o elementos descartados a menos que el usuario lo solicite explícitamente (../../references/visual-change-protocol.md §4)
• Tabla de no-ámbito del PRD existente → No incluir esos elementos en el mockup. Aunque quede un rastro en el código, no se interpreta como requisito. Si parece que debería restaurarse, preguntar al usuario antes de crearlo (planning-kit plan-prd Gotcha 14)
• La celda de descarte del registro de aprobación apunta a una ruta → Abrir ese archivo y leer el texto original. Si es una ruta de PRD, usar los elementos de la tabla de no-ámbito. Si es una ruta de contrato de trabajo, usar las líneas que terminan en Sin PRD de la sección Límite de ámbito como elementos descartados y no incluirlos en el mockup. Si el archivo no existe o no se puede leer (.harness no rastreado no se incluye en un nuevo workspace), decir No se puede leer: <ruta> y preguntar al usuario antes de crear el mockup
• Código de la aplicación existente → La tabla de convenciones §0 se crea después de determinar la pantalla objetivo en el Paso 1. Sin objetivo, no se puede elegir el "mismo rol". Leer tantas pantallas existentes de diferente rol como indique §0 (fuente original: harness skill-design-guide.md §8.9) y usar solo los nombres reales de componentes reutilizables confirmados con grep. La convención se coloca en las constants de la matriz del Paso 2-a.

Paso 1: Comprender los requisitos de la pantalla

A partir de la solicitud del usuario, identifica:

• Qué página/pantalla es (login, dashboard, configuración, etc.)
• Funcionalidades principales y elementos de información
• Usuario objetivo

Antes de crear cualquier archivo, incluye en la respuesta un reperfilado de la sección §0 de ../../references/visual-change-protocol.md — la ruta del archivo de la pantalla objetivo y su ruta (o Nuevo si es nueva), y una oración que reformule la solicitud incluyendo los nombres de los elementos y su disposición. Si hay ambigüedad, pregunta antes de empezar.

Si algo no está claro, confírmalo con el usuario.

Paso 2: Acordar la cantidad y la Matriz de Contrato de Variantes, luego generar mockups HTML de alta fidelidad

Paso 2-a: Fijar primero la cantidad y los ejes (antes de crear archivos)

Completa la ../../references/visual-change-protocol.md §5 Matriz de Contrato de Variantes y acuérdala con el usuario. Las reglas de cantidad, número de ejes y prohibición de artefactos secundarios tienen su fuente original en harness/docs/guides/skill-design-guide.md §5.6.

Situación	Cantidad a producir
El usuario especifica la cantidad	Exactamente esa cantidad — exceder o no alcanzar es una infracción
No especificada	Mínimo 5 — más si es necesario para la comparación. Sin límite superior

Después de completar las 6 columnas de la matriz (variant_id · strategy_label · axis_vector · constants · intended_user_scenario · archivo generado), pásala por la auto-verificación de distinción: si hay 3 o más ejes especificados, la distancia de Hamming entre todos los pares debe ser ≥ 2; si hay 2 o menos, debe ser ≥ 1. La puerta ejecutable está en §5. Si hay algún par superpuesto, no entregues ese conjunto; rediseña el lado que se superpone (REJECT global UI-04).

No crees archivos de tokens, sistemas de diseño, surface lane o catálogos de componentes no solicitados. Si parecen necesarios, propónlos por separado y créalos solo después de la aprobación.

Paso 2-b: Generar la cantidad acordada

Consulta references/mockup-guidelines.md y genera los mockups usando el formato ../../templates/mockup.html:

Cada mockup se genera como un archivo HTML independiente:

• .design/mockups/{nombre-pagina}-{caracteristica}.html (ej: dashboard-sidebar.html)
• Nivel de alta fidelidad con colores, tipografía y espaciado reales
• Todos los elementos UI llevan un ID en formato {nombre-componente}-{hash-4-digitos}
• Incluye una superposición JavaScript que muestra el ID al pasar el ratón
• Prohibido lorem ipsum — usar contenido real o datos de ejemplo realistas

Grupo de candidatos para strategy_label (selecciona tantos como la cantidad acordada. Si la cantidad acordada es mayor que el grupo, crea más estrategias fuera del grupo que se adapten a la pantalla solicitada — esta lista es un ejemplo, no un límite):

• Optimizado para conversión — Navegación lateral + contenido principal, CTA principal fijo en la parte superior
• Enfocado en exploración — Barra superior + cuadrícula de tarjetas, filtros/ordenación prominentemente colocados
• Alta densidad de información — Basado en pestañas + vista de lista, énfasis en jerarquía de texto escaneable
• Impacto de marca — Hero a pantalla completa + secciones de desplazamiento, entrada centrada en lo visual
• Dashboard/Control — Layout de paneles de widgets, resumen de estado + acciones rápidas prioritarias

El marco tiene por defecto cinco espacios para mockups (A~E). A partir del sexto mockup, se añade un espacio más en orden (f, g…): botones de pestaña, panel, dos opciones en el selector de comparación, tarjeta de voto, espacio para notas, elementos MOCKUP_CONFIG.variants, texto T.ko.tab / T.en.tab. El script del marco solo lee la lista de mockups de MOCKUP_CONFIG.variants, por lo que el script no se modifica. El CSS tampoco se modifica — la fila de tarjetas de voto y notas usa grid-auto-flow: column, por lo que en pantallas anchas se colocan todos los mockups en una fila, en pantallas de 768px o menos se muestran dos por fila, y las tarjetas de voto cambian a una por fila en pantallas de 400px o menos.

Si la capacidad de respuesta está incluida en los requisitos, añade a cada mockup secciones para los breakpoints mobile/tablet/desktop y especifica las reglas de layout (número de columnas, gutter, max-width).

Paso 3: Explicar la intención del diseño

Para cada mockup, explica:

• La prioridad estratégica que refleja (conversión, exploración, marca, etc.)
• La razón de la elección del layout y la estructura de la información
• Los puntos de énfasis visual — dónde se detiene la mirada
• Para qué escenario/contexto de usuario se adapta mejor
• Una breve justificación de las decisiones clave (por qué esta configuración)

El orden de presentación no debe ser una "lista de pantallas", sino un flujo de escenarios de usuario. En lugar de explicar cada mockup de forma independiente, contrasta cómo cada uno resuelve un problema diferente; así se facilita la discusión sobre los criterios de selección.

Paso 4: Selección y modificación por parte del usuario

• El usuario selecciona un mockup o da feedback

• Comunicación usando IDs: "haz más grande card-product-a3f2"

• Ante una solicitud de comparación entre mockups, elige la técnica de comparación:

  • Comparación de propuestas con estructura muy diferente → side-by-side (colocación una al lado de la otra)
  • Comparación de cambios en una parte de la misma pantalla → superponer antes/después y explicar
  • Comparación que incluye justificación de la decisión/handoff → añadir anotaciones (annotations)
  • Comparación de interacciones/cambios de estado → incluir comportamiento hover/focus/click

• Si la solicitud de modificación señala una sola propiedad o un solo elemento (solo el borde, solo el color, solo el espaciado, solo este chip), deja un Change Manifest antes de editar (Gotcha 15 · ../../references/visual-change-protocol.md §2):

  ## Change Manifest
  - Cambiar: [propiedad — ID del objetivo — valor actual → valor deseado]
  - Conservar: [propiedades visuales restantes del mismo elemento — background / fill / radius / shadow / spacing / typography según corresponda · si se señaló un solo elemento, incluir también los elementos vecinos de la misma línea/área]
  

  Después de la modificación, verifica que los valores de la lista de conservación sigan siendo los mismos. Si han cambiado, revierte y aplica solo la propiedad señalada nuevamente. El orden de edición, la verificación de la aplicación y el límite de auto-correcciones siguen la §3 (fuente original: harness skill-design-guide.md §8.9); cada captura se revisa contra la lista de verificación de captura de §3.

• Actualizar el archivo HTML después de la modificación

• Al confirmar, mantener la versión final en .design/mockups/

Paso 5: Crear registro de aprobación (obligatorio al confirmar)

Cuando el usuario confirme un mockup, genera .design/approvals/{YYYYMMDD}-{nombre-pantalla}.md. Si la aprobación solo queda en el registro de la conversación, el QA posterior no podrá verificar la evidencia y será rechazado (Gotcha 13 · REJECT global UI-06).

# Registro de aprobación — {nombre-pantalla}

- Fecha de aprobación: {YYYY-MM-DD}
- Entidad aprobadora: {Confirmación directa del usuario | Modo autónomo (especificar justificación de la decisión)}
- Artefacto objetivo: .design/mockups/{nombre-archivo}.html
- Variante seleccionada: {Etiqueta de estrategia + ID del mockup}
- Valores visuales confirmados: {Color, tipografía, espaciado fijados en el momento de la aprobación — en caso de conflicto posterior con tokens, estos valores tienen prioridad}
- Configuración confirmada: {Elementos y disposición que permanecen en la pantalla}
- Alternativas descartadas y razón: {Propuesta/elemento descartado y razón — si la decisión fue eliminar una funcionalidad o opción de configuración, no reescribas la razón aquí. Solo escribe la ruta de la tabla de no-ámbito del PRD de esa funcionalidad y la línea de "lo que no se hace" (planning-kit plan-prd Gotcha 14). Si no hay, escribe `Ninguno`}
- Pendiente/seguimiento: {Elementos no acordados que se dejan para después}
- Evidencia de la fuente original: {Cita de la declaración del usuario}

Si no existe un PRD (.planning/prd-<slug>.md) para esa funcionalidad, la decisión original se escribe en una sola ubicación del contrato de trabajo Límite de ámbito, en cuatro celdas (lo que no se hace, razón, ámbito, rastro en el código restante) como la tabla de no-ámbito de plan-prd, y se añade Sin PRD al final de la línea. En la celda de descarte, solo se escribe la ruta de ese contrato — si la decisión original está en dos lugares, solo uno se actualiza (../../references/visual-change-protocol.md §4). Si tampoco existe un contrato de trabajo para esa funcionalidad, la decisión original está en esta única celda de descarte del registro de aprobación — escribe las cuatro celdas para cada decisión, una línea por decisión, indentadas debajo de la celda de descarte como elementos de lista que comienzan con -, y añade Sin PRD al final de la línea. Antes del siguiente mockup, el Paso 0 seguirá la ruta de la celda de descarte para leer el texto original. No crees un PRD solo para contener un registro de descarte (plan-prd Gotcha 1).

Justo después de crear, verifica:

ls .design/approvals/                      # El archivo existe
grep -c 'Valores visuales confirmados' .design/approvals/{nombre-archivo}.md   # → 1
grep -cE '^- (Configuración confirmada|Alternativas descartadas y razón):' .design/approvals/{nombre-archivo}.md   # → 2

Si el mockup se modifica después de la aprobación, actualiza también este registro. Un registro de aprobación obsoleto es peor que no tener ninguno.

Paso 6: Envío a Figma (opcional)

Si el usuario solicita el envío a Figma:

• Verificar la configuración de Figma MCP
• Configurado → Enviar a Figma el mockup seleccionado o componentes individuales (basados en ID)
• No configurado → Indicar "Para enviar a Figma, se necesita la configuración de Figma MCP" + volver a indicar la ruta del archivo HTML
• Error de envío → Mensaje de error + indicar la ruta del archivo HTML

Referencias

• references/mockup-guidelines.md — Detalles de los criterios de generación de mockups
• ../../templates/mockup.html — Formato de salida HTML del mockup (plantilla compartida)
• ../../references/visual-change-protocol.md — Prioridad visual, aislamiento de cambios parciales, especificación del registro de aprobación, §5 Matriz de Contrato de Variantes, §7 Canales de Evidencia (SSOT)
• harness/docs/guides/skill-design-guide.md §5.6 Variant Budget · §3.8 User-Reported Failure Gate — Fuente original de las reglas de cantidad, prohibición de artefactos secundarios y protocolo de informes de usuario