Dhodraj/ui-design

Diseño de interfaz de usuario

Un agente al que se le pide una pantalla escribe la pantalla. Esta habilidad cierra la brecha a ambos lados de eso. Primero, decidiendo para qué sirve la superficie y cómo debería verse. Luego, averiguando si lo construido hace el trabajo.

Dos reglas gobiernan todo lo siguiente. Nombra el resultado del cliente antes del primer archivo. Conduce el producto en ejecución antes de decir que funciona.

Elige primero la profundidad

El cambio	Etapas
Copia, un color, una propiedad	1, 7, luego mira el resultado
Un componente, un estado	1, 4, 6, 7, 9
Una pantalla, un formulario, un flujo	0 a 10, brevemente
Una nueva superficie, o "hazlo moderno"	0 a 10 en su totalidad, con la etapa 3 aprobada antes de la etapa 7
"Audita esto"	Usa ui-review. No comiences a editar
"Encuéntrame un componente para…"	Usa ui-find

Di qué profundidad elegiste, en una línea, antes de comenzar. Una etapa se omite solo cuando el cambio no puede alcanzar lo que esa etapa protege.

0. Vuelo previo: lee el proyecto antes de preguntar nada

Lee, en este orden, y detente en el primero que resuelva la pregunta:

1. DESIGN.md en la raíz del proyecto. Un sistema de diseño que ya existe tiene prioridad sobre cada valor predeterminado en esta habilidad y sobre tu propio gusto. Síguelo. Donde el trabajo necesite algo que el archivo no cubra, agrega eso al archivo en lugar de inventarlo en una hoja de estilo.
2. PRODUCT.md, README.md, .claude/, un brief existente.
3. La pila, el sistema de estilos y la biblioteca de componentes en uso.
4. La pantalla existente más cercana y las pruebas que la cubren.

Una pantalla que contradice el sistema propio del producto es un hallazgo, no una licencia para iniciar un tercer sistema.

1. El sistema de diseño

references/design-system.md contiene el formato y ambas rutas hacia él.

El proyecto tiene	Haz esto
Un DESIGN.md	Léelo, síguelo y dilo en una línea
Un sistema de diseño real en código: tokens, un archivo de tema, una configuración de Tailwind	Codifícalo en DESIGN.md leyendo los valores del código, nunca adivinándolos
Un producto vivo o una marca sin sistema escrito	Codifícalo a partir de lo real: renderízalo, lee los valores calculados, regístralos
Nada	Escribe uno en la etapa 3, a partir de la dirección que el usuario elija

Nunca escribas un DESIGN.md que establezca valores que el producto no usa. Un sistema codificado es un registro de lo que hay. Un sistema nuevo es una propuesta y se marca como tal hasta que el usuario lo elija.

Protege el archivo antes de construir contra él:

pnpm dlx @google/design.md lint DESIGN.md

Es un paquete publicado real. Detecta referencias rotas de tokens, un primary faltante, tipografía que nunca se definió y cualquier par de color de componente por debajo del umbral de contraste 4.5:1. Corrige lo que informa antes de la etapa 7.

2. El resultado del cliente

references/product-thinking.md contiene el método. El resultado comercial, el cliente y su trabajo, y la versión útil más pequeña. Dos líneas cada uno.

Escribe el resultado como algo observable:

Un despachador con 40 órdenes abiertas puede ver qué orden está atrasada y reasignarla sin salir de la lista.

Luego criterios de aceptación que se puedan verificar cada uno en un navegador. "Se ve bien" no es un criterio. "A 375px, el estado de cada orden y su control de reasignación son accesibles sin desplazamiento horizontal" sí lo es.

Donde no haya evidencia, escribe la suposición y etiquétala. Nunca escribas una persona, una cita o una cifra de conversión que nadie haya producido.

3. Direcciones, y la elección del usuario

references/directions.md contiene el método y el vocabulario.

Presenta tres direcciones, no una. Una sola propuesta es la estética predeterminada del modelo con una justificación. Cada dirección recibe un nombre, el tono de anclaje, el emparejamiento tipográfico, la densidad y lo memorable, en cuatro líneas.

Luego detente y preséntalas al usuario con la herramienta de preguntas interactivas. Esta es una puerta de aprobación: no construyas más allá de ella sobre una suposición. Cuando el usuario dice "tú eliges", elige una, di cuál y por qué en una línea, y continúa.

Con un sí, escribe o actualiza DESIGN.md con los valores reales de la dirección elegida, y pásale el linter.

4. El recorrido y sus estados

references/journey-and-states.md.

Enumera los estados que esta superficie realmente tiene: vacío, un elemento, muchos, el caso real más denso, cargando, fallo parcial, error, sin permiso. Una pantalla construida sobre un solo fixture oculta todos los demás estados, y esa es la razón más común por la que una pantalla terminada falla al contacto con un cliente.

5. Encuentra componentes antes de escribirlos

Ejecuta ui-find, o su script directamente:

node .claude/skills/ui-design/scripts/find-components.js <términos> --limit 15

Busca primero los componentes del propio proyecto. Una segunda implementación de un componente que el producto ya tiene es un defecto. Escribe un componente desde cero solo después de nombrar los candidatos leídos y por qué cada uno no era adecuado.

6. Mock, o el producto real

Pregunta cuál, en una línea, a menos que el usuario ya lo haya dicho. Ambas rutas construyen HTML y CSS reales; la diferencia es dónde aterriza el archivo y a qué está conectado.

Ruta	Cuándo	Dónde va
Mock	Una nueva superficie, un rediseño, una parte interesada que convencer, o el usuario lo pide	Una página independiente en mock/, con los tokens de diseño reales y datos de muestra que digan claramente que son muestra
Directo	Un cambio dentro de un producto vivo, o el usuario dice constrúyelo	Los propios archivos del producto

Un mock se aprueba y luego se reconstruye con los componentes del producto. Dilo antes de construirlo, para que nadie espere que el archivo mock se envíe a producción.

7. Construye

Construye los estados de la etapa 4, no solo el camino feliz. Usa los tokens y componentes del propio producto.

Lee references/gates.md y references/craft.md inmediatamente antes de la primera edición de IU, cada vez, incluso una pequeña.

gates.md es el piso: los valores predeterminados en los que cae cada modelo y qué hacer en su lugar. craft.md es la capa superior. Profundidad como sombra en lugar de borde. Radios concéntricos. Atenuación de salida en menos de 300 ms. Entradas que se disparan una vez y nunca en una interacción repetida. Cifras tabulares. Dos partes de una pantalla conectadas, para que el cliente vea que son una sola cosa.

Construye la pantalla más importante, o la hero, sola y primero. Revísala antes de construir el resto, con ojos nuevos: un subagente sin memoria de las decisiones captura lo que tú no puedes. Luego construye el resto.

8. Ejecútalo y míralo

No es una revisión de código. Inicia la aplicación, ábrela en un navegador y úsala desde el punto de entrada real como lo haría el cliente.

references/playwright.md contiene la mecánica y qué hacer cuando la aplicación no se puede iniciar aquí.

Mira las capturas de pantalla. Leer una lista de archivos no es mirar.

9. Revisa y corrige

Ejecuta ui-review contra lo que construiste. Mide el renderizado en vivo, recorre el recorrido, verifica el resultado contra DESIGN.md y ordena los hallazgos por daño.

Corrige en orden de gravedad. Un cambio que no puedas justificar contra el resultado de la etapa 2 es alcance que nadie pidió. Di lo que dejaste solo y por qué.

Luego references/regression.md: identifica los recorridos que ya funcionaban antes de tocar el código y separa los fallos que causó tu cambio de los fallos que ya estaban allí.

10. Informe

• El resultado del cliente y si se cumple.
• La dirección elegida y por quién.
• Lo que se construyó o cambió, por archivo.
• Lo que se verificó, por qué medios, en qué anchos, en qué estados.
• Lo que no se verificó y por qué.
• Hallazgos corregidos y hallazgos dejados con su motivo.
• Suposiciones que siguen siendo suposiciones.

Honestidad, que tiene prioridad sobre cada etapa anterior

• Nunca reportes una medición que no tomaste o una pantalla que no renderizaste.
• Nombra cada sustituto. Un fixture para datos en vivo, una página estática para la aplicación, una fuente local para la de la marca.
• Cuando la aplicación no se pueda iniciar o alcanzar, dilo y marca cada afirmación de recorrido como no verificada. No describas el código fuente como si lo hubieras visto ejecutar.
• Nunca inventes una métrica, un testimonio, un muro de logotipos o un recuento de clientes. Cuando falte la cifra real, deja una etiqueta con espacio y di que está vacía.
• Un formulario sin nada detrás lo dice claramente. Una página que imprime "Enviado" sin enviar es un defecto, no un marcador de posición.
• Recorrer un recorrido tú mismo encuentra fricción. No mide lo que hacen los clientes.

Qué toma prestada esta habilidad y de dónde

NOTICE lo registra. Las fuentes de los componentes y sus licencias están en sources.json; scripts/check-sources.js valida ese archivo y tests/run.sh prueba los scripts.