Moddingflow/mejor-diseño

Better Design (Mejor Diseño)

Haz que la tarea solicitada sea clara y procesable: el usuario puede ver dónde está, entiende una acción antes de activarla, recibe un resultado y puede recuperarse de un error. Evalúa la coherencia, expresividad y accesibilidad por separado. No prometas una experiencia de usuario perfecta.

1. Establecer el alcance y la base visual

• Elige un modo: creación, mejora enfocada, auditoría o plan. Mantén las auditorías como solo lectura; no implementes cambios en un plan. No añadas características que el usuario no haya solicitado.
• Establece la plataforma a partir de la solicitud y el proyecto. Solo cuando el contexto esté ausente, utiliza web responsiva, HTML semántico y WCAG 2.2 AA como objetivo inicial.
• Define la matriz real de dispositivos y viewports antes de componer o cambiar una interfaz responsiva. Para un sitio web, incluye los diseños móvil, tableta, escritorio y ultraancho que el producto soporte; para un juego móvil, incluye teléfonos pequeños y típicos, además de tabletas. Las restricciones de diseño y el comportamiento del diseño deben adaptarse a esas superficies, no simplemente encoger una composición de escritorio. Para trabajos en navegador, incluye el zoom del navegador en la matriz porque 75%, 100% y 150% pueden exponer diferentes fallos de recorte, densidad, reflujo e interacción.
• Antes de cualquier trabajo de UI, busca el archivo DESIGN.md del proyecto (en la raíz, docs/, design/ o la ruta indicada en las instrucciones del agente) y léelo por completo. Es la fuente única de valores de interfaz: fuentes, escala tipográfica, roles de color, espaciado, radios, tamaños de componentes, iconos y movimiento. Toma cada valor en código nuevo o modificado de él por rol o nombre de token; nunca lo hagas a ojo, lo redondees o introduzcas un casi-duplicado. Las reglas están en design-md.md.
• Inspecciona la pantalla existente en el runtime actual o a través de capturas actuales confirmadas, luego inspecciona los componentes, tokens, estilos y reglas del proyecto cercanos. La ausencia de DESIGN.md no significa que no haya un sistema de diseño: los tokens de código son entonces el sistema. Preserva el trabajo en curso no relacionado.
• Distingue un defecto de implementación de una solicitud de rediseño. Aborda la causa primero: un orden poco claro, una acción impredecible, mala retroalimentación, pérdida de datos o contenido perdido.
• Toma decisiones en este orden: tarea explícita y restricciones → DESIGN.md y el sistema existente → convenciones de plataforma → tareas del dominio → la línea base configurable de esta skill. La funcionalidad y los requisitos de accesibilidad aplicables se aplican en cada nivel.
• Dirección visual por defecto. Cuando el usuario no nombre ningún estilo visual y el proyecto no tenga DESIGN.md, marca, tokens de código o UI en vivo de la que heredar, construye en el estilo de la casa: ultra minimalista premium en el espíritu de Apple (lienzo negro, Geologica casi blanco en pesos 500 y 340, dos grises, un azul para enlaces y foco, acciones en píldora, superficies separadas por tono, contenido real como el único color). Las reglas y el preset de DESIGN.md listo están en house-style.md; léelo por completo antes de escribir cualquier estilo. Dos malas interpretaciones llevan a los agentes a otro lugar, así que revísalas explícitamente (house-style.md sección 1): el dominio del producto, la industria, la audiencia o el nombre no son una señal visual ("una tostaduría de café", "para desarrolladores"), y los valores predeterminados del andamio no tocados no son un sistema del que heredar (el tema predeterminado de shadcn/ui, la paleta predeterminada de Tailwind, los iniciadores de create-next-app, Vite, Expo, Bootstrap, MUI o Chakra); mapea el estilo de la casa sobre ellos en su lugar. Cuando se aplique, comienza desde el archivo de referencia house-style.html, no desde una página en blanco: toma sus tokens, clases de tipo, navegación, botones, mosaicos y ritmo de secciones (o pórtalos a los componentes de tu stack), luego reemplaza su contenido (house-style.md sección 1). Cualquier señal visual del usuario (colores, estado de ánimo, tema, referencia, marca, estilo de audiencia) lo anula: sigue la solicitud y aplica solo las partes del estilo de la casa que la solicitud deje abiertas y no contradiga. Nunca rediseñes un producto existente con él a menos que se solicite. Los juegos mantienen su propia dirección artística.
• Preserva la marca establecida, la densidad, la composición similar a un juego, editorial o expresiva. No la reemplaces con un CRM gris genérico. Para un conflicto real, elige el ajuste accesible más pequeño y explica la desviación específica.
• Aclara solo las incógnitas que cambien materialmente la decisión; establece suposiciones razonables brevemente. Esta skill no introduce una nueva aprobación o puerta HTML. Los requisitos existentes del proyecto para prototipos, aprobación y compilaciones siguen siendo aplicables.

2. Definir la tarea y un contrato proporcionado

• Describe el escenario principal en lenguaje sencillo y su resultado observable. Recorre: entrada → acción → resultado → error/reintento → volver/cancelar.
• Separa la tarea principal, las acciones secundarias y la ayuda. Elige nombres y patrones familiares para el usuario; mantén la navegación y las ubicaciones de las acciones coherentes en todas las pantallas.
• Una sola corrección necesita solo un breve registro de la decisión cambiada y las comprobaciones. Para un nuevo flujo, escribe un contrato compacto antes de la implementación; es una herramienta de trabajo, no un documento obligatorio para el usuario.
• Usa design-contract.md para la estructura, los valores predeterminados numéricos y las excepciones. El ejemplo JSON ilustra el formato; no lo agregues por completo al proyecto para un cambio pequeño.
• Limita el contrato a la plataforma, los objetivos, el sistema existente, la dirección, los componentes afectados, sus acciones/estados, el comportamiento responsivo y la evidencia de aceptación. Una comprobación planificada no es una comprobación completada.

3. Establecer una dirección artística antes de estilizar

Las reglas negativas solo mueven la salida a la siguiente plantilla más común; el carácter proviene de un proceso. Al crear o rediseñar una superficie cuya identidad es parte de la tarea (marca, página de inicio, portafolio, aplicación de consumo, juego, editorial, lanzador), sigue art-direction.md antes de elegir tokens. Cuando se aplique el estilo de la casa (sección 1), los tokens de paleta, tipo, forma y movimiento provienen de su preset; aún así escribe el concepto, y deja que elija las imágenes, el elemento principal de cada sección y un detalle característico (house-style.md sección 10). De lo contrario:

• Deriva un concepto de una oración del dominio del producto, la audiencia y el contenido — un objeto, lugar o artesanía de ese mundo — no de adjetivos como "moderno, limpio, minimalista". Añade tres cualidades objetivo y tres anti-cualidades concretas.
• Recolecta 3–5 referencias reales (primero las proporcionadas por el usuario; nunca imágenes generadas por IA) y anota para cada una exactamente qué se toma: ritmo, densidad, presentación de números, material, luz.
• Esboza 2–3 direcciones que difieran por su dispositivo principal (tipográfico, liderado por imágenes, estructural), luego elige una con una razón vinculada a la tarea y la audiencia.
• Deriva la paleta y el tipo del concepto: una paleta con un origen declarado y neutros matizados; tres candidatos de tipo y una elección razonada. Planea uno o dos detalles característicos; el grupo opcional en effects-library.md contiene los probados.
• Deriva el carácter del movimiento del mismo concepto: cómo se mueven las cosas en ese mundo (tempo, peso, física, si algo salta) más un detalle de movimiento característico. Paleta, tipo y movimiento deben leerse como una sola voz; consulta motion.md.
• Dentro de DESIGN.md, una marca existente o un sistema de diseño del que se hereda la dirección: tómala de DESIGN.md o exprésala en una oración desde la superficie en vivo, y trabaja dentro de ella. Las herramientas de trabajo densas expresan carácter a través de la precisión y la tipografía de datos; sin sistema y sin señal del usuario toman la escala de aplicación del estilo de la casa y la paleta con la densidad del fallback neutro.
• Registra la dirección en el contrato (direction, incluyendo direction.motion) y planifica las comprobaciones de distinctiveness y motion. Escribe la dirección elegida y sus tokens en DESIGN.md para que las pantallas y sesiones posteriores se construyan a partir de los mismos valores.

4. Construir un sistema coherente de decisiones

• Reutiliza tokens y componentes de DESIGN.md y los tokens de código. Para un sistema nuevo, define roles semánticos para color, tipografía, espaciado, radio, capas y movimiento; luego selecciona variantes de componentes.
• Mantén los conjuntos cerrados para que cada pantalla se construya a partir de las mismas partes: una o dos familias de fuentes, una escala tipográfica escalonada de algunos roles, una escala de espaciado fija, algunos radios y tamaños de componente fijos (por ejemplo, botón sm/md/lg). Mismo rol, mismo valor en cada pantalla. Un valor faltante es una decisión del sistema: añade el rol a DESIGN.md y a los tokens de código en el mismo cambio.
• Crea DESIGN.md a partir de la plantilla al crear una interfaz desde cero (desde el preset de estilo de casa cuando se aplique el estilo de la casa), o cuando un rediseño o un cambio de múltiples componentes no encuentre ninguna; derívalo de los tokens de código en vivo en lugar de inventar valores, y registra las contradicciones en lugar de solucionarlas silenciosamente. No lo crees para una corrección de un solo elemento a menos que se solicite; ofrécelo en una línea. Mantén DESIGN.md y los tokens de código sincronizados dentro de cada cambio que toque cualquiera de ellos.
• La API expresa intención, tamaño, densidad y estado. Preserva las props nativas, la participación en formularios, los enlaces y los nombres accesibles; no requieras onClick en un botón de envío o un enlace con href.
• No ajustes cada elemento con su propio hex, gap, sombra y radio. Cambia un token compartido o variante cuando la causa sea compartida. Las matemáticas de diseño, un borde de 1px, 0, fr, %, calc, aspect-ratio y los valores permitidos del proyecto no son violaciones por sí mismos.
• Elige el tamaño de texto por rol y contenedor.
• Construye la geometría; nunca la coloques a ojo. Sigue layout-geometry.md para cada pantalla, panel y menú de juego, y mide el resultado (sección 8). Arregla una desalineación en su causa (pivotes, anclas, un grupo de diseño faltante, relleno de sprite, métricas de fuente), nunca desplazando un elemento:
  • Intervalos iguales. Los hermanos de un tipo se sientan en un contenedor de diseño (flex/grid gap, grupos de diseño de Unity, contenedores de caja de Godot, cajas de UMG) con un token de espaciado, por lo que cada espacio entre ellos es idéntico. Un espacio diferente debe significar un nuevo grupo y un claro paso hacia arriba en la escala. Escalera de proximidad: dentro de un control < entre elementos < entre grupos ≤ relleno.
  • Líneas compartidas. Los elementos en una fila comparten su parte superior/centro/inferior (alturas mixtas comparten centros); los elementos en una columna y cada etiqueta en una lista de configuraciones comienzan en una línea clave vertical, con los controles en una segunda línea clave. Usa una cuadrícula o una columna de etiquetas fija, nunca desplazamientos por fila. Los conjuntos de botones comparten un tamaño.
  • Contenido dentro de controles pequeños está centrado por su tinta visible (altura de mayúscula, píxeles de icono recortados), no por el cuadro de la línea de fuente o un rect de sprite con relleno; los iconos asimétricos obtienen un desplazamiento óptico declarado integrado en el componente. Los pares de icono + etiqueta usan un token de gap.
  • Espacio para respirar. Nada se desborda ni se sienta en el borde de su contenedor: el relleno es al menos los espacios que contiene, con reserva para la localización más larga, la escala de hover y los anillos de foco; la UI interactiva se mantiene dentro del área segura en cada relación de aspecto compatible. Cuando el contenido no cabe, cambia el diseño, no los márgenes.
• Selecciona la tipografía a través de un proceso, no una lista negra: preselecciona tres familias derivadas del concepto (época, material, voz, densidad de datos), luego elige con una razón declarada. La familia debe ser legible en sus tamaños e idiomas reales y proporcionar los pesos, estilos, numerales, cobertura de glifos (incluyendo cirílico cuando sea compatible) y comportamiento de fallback requeridos. Ninguna familia está prohibida, pero una familia elegida por costumbre es un defecto: intercambiar un valor predeterminado de tendencia (Inter, Uni Sans) por el siguiente (Space Grotesk, DM Sans, Instrument Serif) sin una razón es la misma plantilla. El tipo elegante nunca debe hacer que la interfaz sea más difícil de leer.
• Construye jerarquía a través del dominio y el contraste: un elemento principal por pantalla o sección, una escala tipográfica claramente escalonada (display 3–5× cuerpo en superficies expresivas, pasos más pequeños en herramientas densas), asimetría intencional donde sirva al concepto, y secciones adyacentes que difieran en estructura en lugar de repetir un patrón de bloque.
• La proporción áurea puede informar proporciones, jerarquía, recorte o espacio en blanco cuando mejore la composición, pero es una herramienta visual en lugar de una fórmula obligatoria. Prefiere la tarea real, el contenido, las restricciones responsivas, la legibilidad y el sistema existente siempre que entren en conflicto.
• No conviertas una pantalla principal en un muro de prosa ininterrumpida cuando su contenido pueda entenderse a través de acciones, agrupaciones o anclas visuales. Divide las explicaciones densas en secciones escaneables y combínalas, cuando sea útil, con controles significativos, iconos, ilustraciones, vistas previas, diagramas u otras imágenes relevantes para la tarea. Un panel de control o un área de cuenta, por ejemplo, debe exponer sus secciones principales y próximas acciones en lugar de solo describir lo que un usuario podría configurar. No añadas imágenes decorativas que compitan con la comprensión o creen affordances falsas.
• Usa el color para dar significado y énfasis; no transmitas estado solo con color. Combina información de error/éxito/requerido/seleccionado con texto, un icono, forma, patrón u otra señal no cromática que permanezca visible en escala de grises y para deficiencias de visión del color.
• Verifica el contraste en el par real de primer plano/fondo adyacente después de aplicar opacidad, superposiciones, degradados, imágenes y cada tema requerido; no redondees un resultado cercano al umbral. Cumple al menos 4.5:1 para texto normal e imágenes significativas de texto, y 3:1 solo para texto grande (al menos 24 CSS px regular o 18.5 CSS px negrita). Apunta más alto para tipo delgado, pequeño o inusual.
• Asegura una relación de contraste mínima de 3:1 para la información visual necesaria para identificar un control activo, su foco o estado, y objetos gráficos significativos contra su color adyacente. Se requiere un borde solo cuando es lo que hace identificable al control; cuando se usa para ese propósito, debe cumplir la misma relación de 3:1.

…

[truncado para la traducción]

Nota: El contenido de la sección 4 se ha truncado en el original debido a su extensión. La traducción continúa con la misma estructura y referencias a archivos externos como accessibility.md, motion.md, placeholder.md y effects-library.md.