eduardopin/design-reference

design-reference — una interfaz que se vuelve referencia, no plantilla

Una interfaz es referencia cuando alguien que conoce el tema la reconoce como hecha para este producto y por alguien en la cima del campo. El enemigo es lo predeterminado: lo que cualquier modelo produciría para cualquier resumen similar.

0. Las reglas del proyecto

El primer paso de cualquier pieza renderizada — pantalla, componente, documento HTML, Artifact, PDF, presentación, diagrama (cloud-diagram), banner — es el barrido del sistema de diseño del proyecto, una vez por proyecto por sesión:

python3 -I ~/.claude/skills/design-reference/scripts/sweep.py <root>         # resumen
python3 -I ~/.claude/skills/design-reference/scripts/sweep.py <root> --css   # :root con --ds-*

Lee la especificación escrita (DESIGN.md, docs/design*), los tokens (tailwind.config.*, CSS con :root/@theme, *.tokens.json), el tema de componentes, package.json, components.json, enlaces de Storybook y Figma, y devuelve el veredicto: proyecto (la pieza usa sus tokens) o neutral (la paleta neutral del equipo). --css emite --ds-bg --ds-surface --ds-fg --ds-fg-2 --ds-accent --ds-border --ds-font-display --ds-font-body --ds-font-mono y el bloque oscuro; las plantillas del equipo leen esas variables. --json devuelve el hallazgo completo. Precedencia en conflicto: especificación > tokens > componentes. Un sistema por página. Di en una línea qué sistema usa la pieza y dónde se encontró. Una marca de cliente o terceros: pregunta primero. Detalles en references/design-system-sweep.md.

Luego lee los componentes compartidos que usará la nueva pantalla. El resumen y el mundo visual ya comprometido vencen cualquier gusto tuyo y cualquier regla aquí. Refinar preserva identidad, copia y comportamiento; rediseñar reemplaza todo el mundo visual — nunca pules la apariencia que fue descartada. Una skill de diseño propia del proyecto (.claude/skills/) gana sobre esta.

Sin un DESIGN.md el proyecto no es necesariamente greenfield: la evidencia está en el código y las pantallas existentes, no en el nombre del archivo.

1. Modo de superficie (decide todo lo que sigue)

Elige según la superficie solicitada, no por el producto:

Modo	Éxito del visitante	Ejemplos	Qué rige
Persuadir	decide y actúa	página de aterrizaje, precios, campaña	atención, prueba, llamada a la acción — el diseño es el producto
Operar	completa una tarea	app, dashboard, admin, editor, ajustes	escaneabilidad, consistencia, expectativa nativa; la marca vive en el detalle
Leer	entiende algo	docs, artículo, changelog, ayuda	estructura para la comprensión, luego comodidad de lectura
Experimentar	está dentro de la obra	portafolio, galería, museo, showcase	la obra lidera desde el primer pliegue; la interfaz se retira

La página de aterrizaje de una herramienta es Persuadir; la documentación de una marca de moda es Leer; el recorrido de un museo es Experimentar.

2. Dirección antes del código (dos pases, obligatorio)

Pase 1 — plan compacto, antes de abrir cualquier archivo de código:

• Sujeto: una frase: para quién es, cuál es el trabajo único de esta pantalla y qué en el mundo de este sujeto (materiales, instrumentos, vocabulario, artefactos) puede convertirse en una elección visual.
• Color: 4–6 valores nombrados (hex u oklch), con el rol semántico de cada uno.
• Tipografía: 2+ roles — una cara display con carácter usada con moderación, una cara complementaria para cuerpo, una cara utilitaria para datos si es necesario. Nunca el par que usarías en cualquier otro proyecto.
• Layout: concepto en una oración + wireframe ASCII. Compara dos alternativas.
• Firma: el único elemento por el que se recordará la pantalla. Toda la audacia va allí; el resto permanece tranquilo y disciplinado.
• Movimiento: un momento orquestado, o ninguno. Dilo.

Pase 2 — autocrítica. Para cada elemento, pregúntate: "¿produciría esto para un resumen similar de otro producto?" Si es sí, es un default, no una elección — reescríbelo y di qué cambió. Solo después empieza a codificar, derivando cada color y tipo de letra del plan.

Los tres looks que la IA produce por defecto hoy: (1) crema #F4F1EA + una serifa de alto contraste + terracota; (2) casi-negro + un acento ácido (verde lima o bermellón); (3) una página de estilos de líneas finas, radio cero, columnas densas. Todos legítimos si el resumen los pide. Donde el eje es libre, no gastes la libertad en ellos.

Para un catálogo de estilos, paletas y pares tipográficos con búsqueda local, usa ui-ux-pro-max (python3 scripts/search.py "<dominio> <producto>"); es un motor de referencia, no un director de arte — la decisión sigue siendo tuya.

3. Los tokens son la fuente de verdad

• Tres capas: primitivo → semántico → componente. Un componente nunca lee un primitivo o un hex crudo; lee --color-surface-raised, no --gray-100.
• Formato: W3C DTCG 2025.10 (tokens.json) cuando el proyecto tiene un pipeline; de lo contrario, propiedades personalizadas CSS en :root con modo oscuro en @media (prefers-color-scheme: dark) y [data-theme].
• Color en oklch cuando sea posible; contraste medido (APCA o WCAG), no estimado.
• Un tema oscuro es un mapeo de luminancia, no una inversión.
• Cuando termines, si el proyecto no tiene DESIGN.md, ofrece generar uno (tokens en YAML + la razón de cada valor en prosa) — es lo que mantiene la siguiente sesión coherente con esta.

Escala, especificación de componentes (variantes, tamaños, estados con prioridad, anatomía) y notas sobre shadcn/Tailwind/modo oscuro: references/tokens-and-components.md. Para generar el sistema completo en DTCG + CSS/Tailwind: sumi:tokens.

4. Construcción

• Stack y componentes: los del proyecto. shadcn/Tailwind → references/tokens-and-components.md y la documentación en vivo a través de context7; un diseño que viene de Figma → figma:figma-design-to-code (MCP) o la skill local del proyecto (por ejemplo implement-from-figma, refactor-frontend-component); escribir en Figma → figma:figma-use.
• Móvil nativo: respeta la plataforma (HIG / Material) antes que la marca.
• Un diagrama de arquitectura cloud o infraestructura (AWS, OCI, GCP, Azure, Cloudflare): cloud-diagram, siempre. Es la skill de diseño para la tarea; copia su kit (el template.html en las referencias de esa skill) y mide con su render.sh. Sin mermaid, cajas genéricas o iconos de imagen externos.
• Contenido real desde el principio: prueba copia corta, mediana y muy larga; estado vacío; carga; error; sin permiso. Lorem placeholder es un defecto.
• La copia es material de diseño: un control dice lo que sucede ("Guardar cambios", no "Enviar"); el mismo verbo desde el botón hasta el toast; un error dice lo que pasó y cómo salir; vacío es una invitación a actuar; voz activa, mayúscula de oración.
• CSS: cuidado con la especificidad que se anula a sí misma (.section × .cta), transition: all nunca, solo transform/opacity animan por defecto.
• Las superficies del navegador también son diseño: selección de texto, cursor, scrollbar, foco, subrayado, números tabulares. Temátizalos desde la paleta — es la señal más barata de que la página fue construida.

Compañero de ejecución de UI de producto

Para UI de producto nativa o responsiva, usa la skill mobile-design-studio disponible como el único compañero de diseño opcional: unidades de implementación pequeñas, ergonomía móvil (objetivos táctiles, áreas seguras, teclado, escalado de texto, retroceso), comprobaciones de estado/recuperación y evidencia de plataforma. design-reference sigue siendo la única fuente de dirección de diseño: reutiliza su resumen aprobado, tokens y componentes; no ejecutes un segundo proceso de branding/dirección ni crees archivos de tokens duplicados. Lee solo la referencia del compañero necesaria para la unidad actual. No es la ruta para presentaciones, arte, carteles o diagramas cloud; esos mantienen sus skills dedicadas.

Resuelve el directorio del compañero desde la ruta de inventario original de la skill seleccionada, nunca desde una caché de prompt generada o una instalación asumida ~/.claude. Si el compañero está ausente o es solo manual, no lo anuncies ni lo auto-cargues; continúa con el método del proyecto. Las skills del proyecto y los prerrequisitos obligatorios de plataforma/Figma (por ejemplo, la visión general de Expo, React Native y Figma design-to-code/use) aún aplican; no son direcciones de diseño competidoras opcionales. Mantén el techo de dos skills de diseño: este método más un compañero, nunca una pila adicional de Sumi/UI style.

5. Piso de calidad (verificado en el resultado, no en la intención)

Lee references/quality-floor.md inmediatamente antes de editar UI. Los puntos no negociables:

• Contraste ≥ 4.5:1 (texto), ≥ 3:1 (grande); texto secundario sobre una superficie coloreada teñida del propio tono de esa superficie, nunca gris.
• Foco visible en todo lo interactivo; nunca eliminar un contorno sin un reemplazo.
• Objetivo táctil ≥ 44×44 (nativo) / 24×24 CSS px (web), 8px entre objetivos.
• prefers-reduced-motion respetado; animación interrumpible; nada iniciado por teclado anima.
• Responsivo hasta 320px sin scroll horizontal; áreas seguras en layout de sangría completa.
• Imagen con dimensiones declaradas; fuente con font-display; lista larga virtualizada.
• Estados: hover, activo, foco, deshabilitado, carga, error, vacío — todos.
• Cero emojis como iconos; iconos de una librería, un trazo, un peso.

Inspección en rondas limitadas, no en un bucle: construye todo, captura escritorio y móvil juntos (captura de pantalla a través del navegador cuando hay uno), arregla todo en un lote, confirma con como máximo una ronda más, detente. La QA abierta quema el dinero del dueño haciendo peor lo que sumi:audit hace mejor.

6. Movimiento con reglas (Emil Kowalski)

1. ¿Debería animarse? 100+ veces/día (atajo, paleta) → nunca. Decenas/día (hover, navegación de lista) → reducir drásticamente. Ocasional (modal, cajón, toast) → estándar. Raro (onboarding, celebración) → puede deleitar.
2. Un propósito declarado: continuidad espacial, indicación de estado, explicación, retroalimentación, evitar un corte abrupto. "Se ve bonito" no es un propósito para algo visto con frecuencia.
3. Easing: entrada/salida → ease-out fuerte cubic-bezier(0.23, 1, 0.32, 1); mover/morfar en pantalla → ease-in-out cubic-bezier(0.77, 0, 0.175, 1); hover/color → ease; movimiento constante → linear; cajón iOS → cubic-bezier(0.32, 0.72, 0, 1). Nunca ease-in en UI.
4. Duración: botón 100–160ms; tooltip 125–200ms; dropdown 150–250ms; modal/cajón 200–500ms; UI siempre < 300ms excepto marketing.
5. Nada aparece de la nada: scale(0.95) + opacity 0, no scale(0). Un popover escala desde su disparador (transform-origin); un modal permanece centrado. :active con scale(0.97). Una entrada idéntica en cada sección es un antipatrón; un momento creado no lo es.

7. Arte, lienzo y trabajo creativo

Cuando la solicitud es un póster, portada, pieza gráfica, arte generativo, visual 3D o "algo hermoso sin resumen de UI", el método cambia: primero una filosofía visual (un movimiento nombrado en 1–2 palabras + 4–6 párrafos sobre espacio, color, material, escala, ritmo, composición), luego la ejecución. La referencia al tema es sutil — quienes lo saben lo sienten, los demás ven una composición magistral. 90% visual, 10% texto. Nada sale del margen, nada se superpone.

Superficie	Herramienta
PNG/PDF estático (póster, arte, portada)	vendor/canvas-design (Anthropic)
Arte generativo 2D, campos de flujo, partículas	vendor/algorithmic-art (p5.js, semilla reproducible, sliders)
3D / shader / escena interactiva	three.js (r160+), GLSL ShaderMaterial; siempre dispose() y eliminación de listeners al desmontar
Pieza para redes sociales / anuncio / banner / impresión	references/identity-and-pieces.md (tamaños, área segura, llamada a la acción) + HTML capturado en el tamaño exacto
Diapositivas	slides
Diagrama de arquitectura cloud	cloud-diagram
Guía de marca, paleta, reglas de logo	references/identity-and-pieces.md; voz de marca y copia → writing
Mockup de logo, icono, identidad generado por IA	design (claudekit: scripts de generación con una API, necesita una clave)
Variantes lado a lado en un lienzo infinito	Plugin superdesign (de pago; necesita inicio de sesión — decisión del dueño)
Imagen/video generado	sumi:generate o los MCP de imagen configurados

Nunca copies el trabajo de un artista identificable; cita la influencia, crea el tuyo propio. Fuentes: descarga y auto-aloja una con los caracteres correctos; la fuente del sistema "más cercana" es un fracaso, no un fallback.

8. Auditar y arreglar lo que ya existe

• Puntuación rápida con correcciones principales: sumi:roast. Auditoría completa (heurística, cognitiva, flujo): sumi:audit. Accesibilidad WCAG 2.2 AA: sumi:a11y. Lista de verificación web (a11y, formularios, movimiento, tipografía, rendimiento, i18n): references/quality-floor.md §B, salida como archivo:línea.
• Arreglar código UI generado: sumi:fix. Revisión de movimiento: una tabla | Antes | Después | Por qué |, una fila por hallazgo.
• Nunca cargues más de dos skills de diseño en la misma sesión: las descripciones compiten y el contexto se hincha sin mejorar la respuesta.

9. Entrega

Modo             [Persuadir | Operar | Leer | Experimentar]
Dirección        [sujeto · paleta nombrada · par tipográfico · firma · movimiento]
Lo que era default [lo que reescribiste en la autocrítica y por qué]
Tokens           [archivo y capas; ¿DESIGN.md generado/actualizado?]
Piso             [cada comprobación de §5 con el valor medido, no "ok"]
Estados          [lista de los estados implementados]
Capturas         [escritorio + móvil, si el entorno lo permite]
Pendiente        [activos que solo el dueño puede proporcionar; decisiones que son suyas]