Gentle Design

Contrato de Activación

Usa esta habilidad por defecto cada vez que el usuario solicite, en palabras sencillas, un diseño UI, mockup, pantalla, página de aterrizaje o direcciones visuales, o itere sobre artboards dentro de design/. No la uses para implementar código de producción en la pila del proyecto.

Los comandos /gentle:design son atajos opcionales: cada acción también funciona desde una solicitud directa, a través de esta habilidad y la herramienta gentle_design (list, open, stop, implement, handoff).

Reglas Estrictas

• Cada artboard es un único archivo HTML autocontenido: CSS, JS y SVG en línea; solo pilas de fuentes del sistema. Nunca referencies URL externas, CDN, fuentes remotas, imágenes o scripts.
• Usa contenido realista para la audiencia; nada de lorem ipsum ni nombres de relleno.
• Marcado accesible: elementos semánticos y puntos de referencia, contraste WCAG AA, estilos de foco visibles, prefers-reduced-motion respetado para cualquier animación.
• Cuando exista design/system.md, léelo primero y usa solo sus tokens y reglas de componentes; ejecuta la Autoverificación de la sección "Sincronización del sistema de diseño" antes de finalizar cualquier artboard.
• Haz como máximo una pregunta aclaratoria, y solo cuando el resumen carezca del objetivo o del contenido.
• Al iterar, edita solo el artboard objetivo. Nunca reescribas los demás.

Puertas de Decisión

Situación	Acción
Nuevo resumen	Escribe N direcciones claramente diferentes (3 por defecto, o el número solicitado) en un nuevo design/<slug>/
Comentarios sobre un artboard	Edita solo ese archivo; mantén su entrada en el manifiesto, actualiza tradeoff si cambió
"Guardar y probar un enfoque diferente"	Añade un nuevo artboard con el siguiente NN; conserva los anteriores; agrégalo al manifiesto
El usuario quiere ajustar valores (espaciado, color, escala tipográfica)	Agrega controles deslizantes o controles en el artboard más un botón "Copiar como prompt" que copie los valores elegidos como un prompt
design/<slug>/ ya existe para un nuevo resumen	Elige un nuevo slug; nunca sobrescribas otro diseño
Un mensaje lleva comentarios de diseño, o el usuario pide aplicarlos	Sigue "Comentarios del lienzo" más abajo
/gentle:design sync, o el usuario pide capturar el sistema de diseño del proyecto	Sigue "Sincronización del sistema de diseño" más abajo
El usuario pide mostrar, detener o listar diseños, o implementar un artboard	Llama a la herramienta gentle_design (open, stop, list o implement con <slug>/<artboard>); sigue el texto de entrega que devuelve implement, e informa el progreso con action "handoff": status: "in_progress" cuando empieces, status: "implemented" cuando termines, con previewUrl establecido a la URL de loopback de la aplicación en ejecución cuando haya una

Antes de diseñar

Ejecuta esta puerta antes de cada nuevo resumen: llama a la herramienta gentle_design con action: "list", luego:

list reporta	Acción
system.exists false y designSources presente	Ejecuta primero "Sincronización del sistema de diseño", dile al usuario en una línea que sincronizaste el sistema de diseño del proyecto, luego diseña con él
Sin designSources	Omite la sincronización y diseña libremente
system.staleSources presente	Nombra esas fuentes, di que design/system.md puede estar desactualizado y ofrece sincronizar de nuevo antes de diseñar; vuelve a sincronizar solo con la aprobación del usuario, y nunca uses los tokens obsoletos en silencio

Pasos de Ejecución

1. Toma el resumen: objetivo, diseño, contenido, audiencia.
2. Carga gentle-ui-design: lee su SKILL.md y solo las referencias que coincidan con la audiencia, trabajo principal y condición de éxito del resumen. Esta habilidad se encarga de la entrega; aquella de la calidad UX.
3. Elige un slug en kebab-case a partir del resumen.
4. Haz que las direcciones difieran en estructura o estrategia visual, no solo en color. Etiqueta cada una con la compensación (tradeoff) que realiza.
5. Escribe design/<slug>/NN-<name>.html por artboard (01-…, 02-…; nombre en kebab-case).
6. Escribe design/<slug>/design.json:

{
  "title": "Página de precios",
  "brief": "Página de precios para una aplicación de notas dirigida a estudiantes",
  "feature": "odd/tasks/pricing-page.md",
  "artboards": [
    { "file": "01-comparison-table.html", "title": "Tabla comparativa", "tradeoff": "Denso y escaneable; menor atractivo emocional", "width": 1440, "height": 900 },
    { "file": "02-single-plan-hero.html", "title": "Héroe de plan único", "tradeoff": "Enfoque fuerte; oculta diferencias entre planes", "width": 1440, "height": 900 }
  ]
}

7. Establece width/height al viewport previsto del artboard en píxeles CSS; mantén el manifiesto sincronizado con los archivos en cada cambio. Campos: title, brief, feature opcional, y artboards[] con file, title, tradeoff, width, height.
8. Enlace ODD: cuando el diseño provenga de una funcionalidad ODD rastreada (un odd/tasks/<feature>.md existente para el trabajo actual), establece feature a esa ruta y agrega una entrada al ## Log de ese documento nombrando design/<slug>/ y sus artboards. Cuando un artboard de ese diseño se entregue para implementar, la entrada del Log también nombra el artboard elegido (el entregado; list lo reporta como Chosen) y que los otros son alternativas. Para trabajo pequeño no rastreado, omite feature y deja el diseño independiente; nunca crees un documento de funcionalidad solo para enlazarlo.
9. Autoverificación UX, por cada artboard que finalices: pásalo contra las guías de composición y retroalimentación (jerarquía, densidad, retroalimentación) e interfaces adaptativas (pantallas estrechas, acceso a entrada, estados) de gentle-ui-design, y corrige cualquier brecha antes de informar.
10. Después de escribir o cambiar artboards, llama a la herramienta gentle_design con action: "open" y el slug, a menos que el usuario haya dicho que no. Cuando una pestaña del lienzo ya está abierta, la actualiza en lugar de abrir una nueva, así que llámala después de cada cambio. Reporta la URL que devuelve.

Sincronización del sistema de diseño

1. Lee solo, y nunca edites el código fuente del proyecto. Fuentes: propiedades personalizadas CSS (:root, @theme, [data-theme]), la configuración de Tailwind o v4 @theme, carpetas de librerías de componentes, archivos de tokens existentes y las fuentes que declaran.
2. Escribe design/system.md: colores (nombre del token, valor, uso), tipografía, espaciado, radio, sombras y reglas de componentes. Cada entrada nombra su origen path. Registra solo valores encontrados en las fuentes.
3. Escribe design/system.html: un artboard autocontenido, de 1440 px de ancho, que represente esos tokens (muestras de color, escala tipográfica, espaciado, radio, sombras) y los componentes principales, bajo las mismas reglas sin URL externas. El lienzo lo muestra como el primer tablero de cada diseño.
4. Cuando no existan fuentes de diseño, dilo y propón un sistema inicial mínimo para que el usuario lo acepte; nunca presentes valores inventados como tokens del proyecto.
5. Autoverificación, por cada artboard que finalices mientras exista design/system.md: enumera los colores y familias de fuentes que usa el artboard, compáralos con los tokens del sistema y corrige cualquier desviación antes de informar.

Comentarios del lienzo

Los comentarios del lienzo se almacenan en design/<slug>/comments.json; la sesión también los recibe como mensajes que nombran cada id de comentario.

1. Lee los comentarios abiertos con la herramienta gentle_design_comments (action: "list", slug y file opcionales). Sin la herramienta, lee design/<slug>/comments.json y usa las entradas cuyo status sea "open".
2. Aplica cada comentario editando solo el artboard en su file; usa selector y excerpt para encontrar el elemento. Cuando un comentario tenga un screenshot, míralo primero: llega adjunto al mensaje del comentario, o abre design/<slug>/<screenshot> con la herramienta de lectura. Muestra lo que el usuario vio, a menudo una animación transitoria o estado de transición que el artboard estático no muestra.
3. Marca cada comentario aplicado como resuelto con la herramienta (action: "resolve", slug, ids). Sin la herramienta, establece su status a "resolved" y resolvedAt a la hora ISO actual, manteniendo cualquier otra entrada y campo como están. Deja abiertos los comentarios que no aplicaste y di por qué.

El formato de archivo, para agentes que solo tienen acceso a archivos:

{
  "version": 1,
  "comments": [
    { "id": "k3x9p2ab", "file": "02-bold.html", "selector": "body > header > h1", "excerpt": "Envía más rápido", "comment": "Haz el título más corto.", "createdAt": "2026-10-26T10:00:00.000Z", "status": "open", "sentAt": null, "resolvedAt": null },
    { "id": "m7q2w9cd", "file": "02-bold.html", "selector": "#cta", "excerpt": "Inicio", "comment": "El botón salta durante la transición de hover.", "screenshot": ".screenshots/m7q2w9cd.png", "createdAt": "2026-10-26T10:05:00.000Z", "status": "open", "sentAt": null, "resolvedAt": null }
  ]
}

screenshot es opcional: una ruta relativa a la carpeta de diseño, dentro de .screenshots/, presente solo cuando el usuario adjuntó una imagen.

Nunca elimines ni reordenes entradas, y mantén el archivo como JSON válido: el lienzo se niega a sobrescribir un archivo que no puede analizar.

Contrato de Salida

Devuelve: el slug, cada archivo de artboard con su título y compensación, qué archivos cambiaron en esta ronda, los ids de comentarios resueltos en esta ronda y cualquier pregunta abierta. Proporciona la URL del lienzo del paso 10, o menciona que /gentle:design open <slug> muestra el lienzo cuando no lo abriste. Para una sincronización, devuelve las rutas de origen leídas, los recuentos de tokens por grupo y si el sistema es un iniciador propuesto; después de una sincronización automática de "Antes de diseñar", di que se ejecutó e infórmalo de la misma manera.

Referencias

• design/system.md en el proyecto, cuando exista: los tokens de diseño a seguir.
• gentle-ui-design habilidad: guía de calidad UX emparejada con cada artboard.