lksnmnn/product-ui

Product UI

Una aplicación es una superficie de trabajo: las personas vuelven a ella para realizar un trabajo. Cada elemento se gana su lugar al servir a ese trabajo. El objetivo es la familiaridad ganada: una persona que domina las herramientas de esta categoría confía en cada control a simple vista, y la interfaz desaparece en la tarea.

Estas reglas valen para cualquier aplicación. Lo específico de un proyecto —dispositivos objetivo, sistema de diseño, componentes, dirección, desviación conocida— vive en el archivo de proyecto; construye a partir de él. Antes de dar por terminada una pantalla, ejecuta review.md.

El archivo de proyecto

Búscalo en este orden: una ruta nombrada en CLAUDE.md o AGENTS.md, luego .claude/product-ui.md. Cuando no exista, crea .claude/product-ui.md a partir de templates/project.md antes de la primera construcción:

1. Encuentra el sistema de diseño: archivos de tokens (propiedades personalizadas CSS, un tema Tailwind, un JSON de tokens), la biblioteca de componentes (en-repo components/ui, shadcn, MUI, Radix, …), archivos de story.
2. Enumera los bloques de construcción que necesita una pantalla (andamiaje de página, tabla, campo de formulario, estado vacío, diálogo, notificación, …) con sus rutas. Marca cada uno que falte como faltante; nunca inventes una ruta.
3. Anota la desviación que viste en el camino: lugares donde el código rompe alguna regla a continuación.
4. Pregunta al usuario por los dispositivos objetivo por aplicación y quién posee el lenguaje visual (un equipo de diseño, o los desarrolladores). Sugiere objetivos a partir de la intención de la aplicación.

Escribe solo lo que verificaste. Apunta CLAUDE.md al archivo para que sesiones posteriores lo encuentren.

Cuando el proyecto no tenga dirección visual y la superficie no deba verse genérica, ejecuta primero el skill design-direction; este registra su resultado en el mismo archivo.

Propósito primero

Antes del diseño, escribe en una línea cada uno:

• el trabajo que sirve la pantalla y la persona que lo realiza;
• la primera lectura: lo único que miran cuando se abre la pantalla;
• la acción principal y con qué frecuencia la repiten;
• los dispositivos objetivo: teléfono, tableta, portátil, pantalla grande, del archivo de proyecto.

Cada región de la pantalla se asigna a una de esas líneas. Una región que no se asigna a ninguna se elimina.

Contenido real

Construye y evalúa con contenido con forma de producción: nombres reales de longitud realista, el título más largo plausible, 0, 1, 7 y 500 elementos, un valor opcional faltante, una traducción un 30% más larga que el inglés. "John Doe", "Acme Inc", "Lorem ipsum", "Item 1" y números redondos ocultan todos los problemas de diseño y son lo primero que hace que una pantalla parezca generada. Cuando los datos del dominio sean desconocidos, pide una muestra o deriva una del esquema.

Cada tamaño

Una pantalla está optimizada para su dispositivo principal y funciona en cualquier otro punto de ruptura con las mismas características. Cada tamaño recibe el patrón que le corresponde, no una copia comprimida del escritorio: una barra lateral se convierte en un cajón o carril de iconos, una tabla se convierte en una lista apilada, un panel dividido se convierte en una página con un paso atrás, hover se convierte en un control visible, una barra de herramientas densa se convierte en un menú desbordante. Una característica que desaparece por debajo de un punto de ruptura es un hallazgo.

Nada se desplaza lateralmente en un ancho objetivo: ni la página, ni una lista dentro de su propio contenedor. Las columnas de texto libre (nombres, títulos, correos electrónicos, nombres de archivo) se encogen y truncan con el texto completo al pasar el ratón; solo una cuadrícula realmente ancha (una matriz, una línea de tiempo) puede desplazarse, y lo indica.

En monitores grandes, el contenido mantiene una medida legible: los bloques de texto se mantienen por debajo de ~75 caracteres por línea, los formularios mantienen su ancho de columna, y una tabla puede crecer mientras sus columnas de texto libre toman el espacio.

Navegación

• La navegación global enumera las secciones de la aplicación y permanece igual en cada pantalla.
• Una sección con sus propias subáreas puede agregar una capa local (una segunda columna o pestañas). Cada capa muestra solo su propio nivel: ninguna capa repite las entradas de otra, y dos entradas nunca comparten una etiqueta.
• El ámbito —qué organización, espacio de trabajo o cuenta en la que actúa la pantalla— se establece con un selector, mostrado una vez.
• Cada página está a lo sumo a dos opciones de la navegación global, y la navegación local permanece visible en el dispositivo principal.
• El chrome por encima del primer control se mantiene pequeño: una miga de pan nunca repite el título de la página debajo de ella.
• Una aplicación con más de un puñado de secciones o muchos registros ofrece una búsqueda de salto a cualquier lugar (⌘K / Ctrl+K) que encuentra páginas y registros por nombre o id pegado.

Densidad

• Muestra el conjunto de trabajo de una vez. Una lista que una persona escanea o compara es una tabla con una fila por elemento; una cuadrícula de tarjetas es para pocos elementos cuya imagen o vista previa es el contenido.

• La altura de la fila sigue al contenido: filas de una línea 36–44px, una fila con una segunda línea o una miniatura hasta 64px; el relleno nunca ocupa más altura que el contenido.

• El espacio entre elementos relacionados es menor que el espacio entre grupos, por lo que la agrupación se lee solo por el espaciado.

• Cada elemento en una fila se gana su lugar. Prueba cada uno:

  • tarea: sirve para encontrar, comparar, abrir o actuar sobre el elemento, para el trabajo de esta pantalla;
  • borrar: eliminarlo pierde algo que la persona necesita; de lo contrario, se va, o se mueve a la vista de detalle;
  • redundancia: no repite ninguna columna, filtro activo o encabezado de página;
  • autoexplicativo: se lee sin hover, tooltip o leyenda, y un estado es una palabra, nunca solo color;
  • orden: lo que identifica primero el elemento, luego los hechos que la gente compara, las acciones al final.

  Un hecho faltante también es un hallazgo: cuando las personas abren elemento tras elemento para comparar un valor, ese valor pertenece a la fila.

• Una línea por fila por defecto. Los hechos secundarios se colocan en su propia columna o en una segunda línea atenuada, nunca en un tooltip que la persona debe pasar el ratón para comparar.

• Los encabezados, descripciones y texto de ayuda son tan cortos como lo permite el trabajo. Una descripción de página que repite el título se elimina.

• El espacio en blanco separa grupos; nunca rellena una pantalla escasa para que parezca llena.

• Un recuadro (borde, fondo, sombra) marca algo sobre lo que la persona actúa como una unidad. La agrupación sola se hace con espacio o una regla; una tarjeta dentro de una tarjeta es un hallazgo.

Jerarquía

• Una acción principal por vista, visualmente principal, en la parte superior derecha de su ámbito (encabezado de página o encabezado de panel). Las acciones secundarias son outline o ghost; las destructivas van al final.
• Cada tamaño, espacio, color y radio proviene del sistema de diseño de la superficie y se mantiene dentro de él. Un valor arbitrario (text-[10px], p-[13px], un hex sin procesar) es un hallazgo; la solución es el paso más cercano, o un nuevo token cuando ningún paso encaja.
• El peso y el color llevan la jerarquía antes que el tamaño.
• El color lleva significado: el acento marca la acción principal, la selección y el estado. El color de estado aparece solo donde existe un estado.
• Los iconos acompañan a una etiqueta donde aceleran el reconocimiento (navegación, acciones frecuentes) y están solos solo para acciones universales (cerrar, buscar, más) con un nombre accesible. Un icono en cada botón, encabezado o tarjeta es decoración.
• Un valor de solo lectura se muestra como texto, nunca como una entrada.
• Un control que el rol del espectador no puede usar está oculto, decidido por la misma capacidad que el servidor verifica. Cuando saber que la acción existe importa, se muestra deshabilitado con la razón ("Solo los administradores pueden invitar").
• El texto nombra lo que la gente reconoce, no la infraestructura detrás: ningún nombre de proveedor o pipeline a menos que la audiencia trabaje directamente con ellos. La navegación no enumera ninguna característica no construida o desactivada.

Texto

El texto de la interfaz es parte del diseño y la señal más rápida de una pantalla generada.

• Un botón dice lo que hace, como verbo y su objeto: "Invitar miembro", "Exportar CSV". Nunca "Enviar", "Aceptar", "Haz clic aquí", "Comenzar" dentro de una aplicación.
• El botón de confirmación repite el verbo de la pregunta: "¿Eliminar 3 archivos?" → "Eliminar archivos".
• Minúscula inicial para cada etiqueta, encabezado y botón. Sin signos de exclamación, sin "Oops", sin "Exitosamente", sin "Por favor".
• La retroalimentación indica el resultado en los términos de la persona: "Factura enviada a finance@…", no "Operación completada exitosamente".
• Un estado vacío dice qué pertenece aquí y cómo llega aquí, en una o dos oraciones sencillas. Sin ingenio, sin relleno de ilustración, sin "No hay nada que ver aquí".
• Sin voz de marketing dentro de una herramienta: elimina "sin interrupciones", "sin esfuerzo", "potente", "desbloquear", "acelerar", "mágico", "con IA" y cualquier oración que elogie el producto.
• Un término por concepto en toda la aplicación; el glosario vive en el archivo de proyecto.
• Los números, fechas y unidades siguen un formato por aplicación; los recuentos usan el plural correcto ("1 archivo", "2 archivos").

Listas y tablas

• Números alineados a la derecha con tabular-nums; texto alineado a la izquierda.
• Las marcas de tiempo usan un formato fijo por aplicación, nunca el valor predeterminado de la configuración regional del navegador, y nunca se truncan. Las pantallas de monitoreo emparejan la hora relativa ("hace 3 min") con la absoluta al pasar el ratón, o viceversa.
• Los encabezados nombran la columna en una o dos palabras; los encabezados ordenables ordenan al hacer clic.
• La búsqueda, filtros, orden, página y el elemento abierto viven en la URL, para que una vista sobreviva a la recarga, al botón atrás y a un enlace compartido.
• Una fila es un enlace real a su elemento: toda la fila lo abre, y Cmd-clic abre una nueva pestaña.
• Cada referencia en una fila —una persona, una organización, un trabajo, un id— enlaza a su propia página.
• Las acciones por fila se ubican al final de la fila en una columna estable, visibles en reposo; como mínimo se muestran en pantallas táctiles. Un control que requiere clics mientras está invisible es un error.
• El trabajo en lote obtiene casillas de verificación de selección, un seleccionar todo y una barra de acciones por lote cuando la persona maneja elementos en lotes.
• Paginación o windowing más allá de ~50 filas; el recuento siempre es visible. Un filtro que limita el conjunto (un rango de mes) reemplaza la paginación cuando se muestra el límite.
• Los chips de filtro pueden llevar recuentos; entonces duplican como el resumen de la página.

Formularios

• Etiquetas sobre los campos, una columna, en el orden en que la persona piensa sobre los datos.
• Validar al salir del campo y al enviar; el error se sitúa debajo de su campo y dice cómo solucionarlo.
• Los valores predeterminados son la respuesta más común. Los campos opcionales se marcan como opcionales, los obligatorios no se marcan.
• El botón de enviar en un formulario de creación o acción permanece habilitado. El envío de entrada no válida enfoca el primer campo no válido y muestra cómo solucionarlo debajo de ese campo.
• Guardar en un formulario de edición puede permanecer deshabilitado hasta que algo cambie, ya que nada espera ser guardado; una vez que algo cambia, está habilitado, se aplica la regla anterior, y una sugerencia de "Cambios sin guardar" junto a él muestra el estado.
• Un guardado por vista. Salir con cambios sin guardar pregunta primero.
• Un control está deshabilitado mientras su propia acción está pendiente, para que no pueda dispararse dos veces.
• Un formulario corto o un solo campo se edita en línea; un diálogo es para una tarea enfocada que no debe perder su contexto.
• Las entradas usan el tipo correcto y autocomplete (email, tel, one-time-code, …) para que los teléfonos muestren el teclado correcto y los navegadores las completen.
• Un activador de carga de archivos es un botón enfocable que abre el selector y también acepta arrastrar y soltar.
• Una página que configura lo que dibuja otra superficie (una incorporación, una marca, una plantilla) muestra una vista previa de esa superficie junto a sus ajustes.

Acciones y retroalimentación

• Una acción con camino de retorno (restaurar, desarchivar, reactivar) se ejecuta inmediatamente y ofrece deshacer, sin confirmación adicional. Un interruptor es su propio deshacer y necesita solo retroalimentación inmediata.
• Una acción sin camino de retorno recibe una confirmación que nombra lo que se pierde ("Eliminar 3 documentos"). Una acción que parece reversible pero no tiene reverso se trata como irreversible hasta que exista el reverso.
• Cada acción responde dentro de 100ms: actualización optimista, estado pendiente en el control, o un esqueleto donde caerá el contenido.
• El trabajo que lleva más de unos segundos se ejecuta en segundo plano con progreso visible y sobrevive a la navegación.
• Los errores dicen qué sucedió y qué hacer a continuación, junto a donde sucedió.

La matriz de estados

Cada vista incluye todos sus estados, diseñados, no predeterminados:

Estado	Forma
carga	un esqueleto en el diseño que tomará el contenido
vacío	dice qué pertenece aquí y ofrece la acción para agregarlo
filtrado-vacío	dice que el filtro no coincidió con nada y ofrece limpiarlo
parcial	las partes que cargaron se renderizan; la parte fallida muestra su propio error, nunca un cero
sin acceso	dice quién puede ver esto y cómo obtener acceso, y ofrece una salida
error	qué falló, un reintento, el resto de la pantalla aún usable
lleno	el contenido real a volumen realista, incluidos nombres largos y muchas filas

Cada control interactivo tiene default, hover, focus-visible, active, disabled y pending.

En un panel de control, cada mosaico y gráfico posee sus estados: una lectura fallida muestra su propio error, nunca un cero o un gráfico vacío. Un panel de control se abre en lo que necesita atención, no en una fila de tarjetas métricas; un número aparece solo con la comparación que lo hace significativo (objetivo, último período) y una definición en la que el equipo está de acuerdo. Los gráficos siguen el skill dataviz cuando está instalado.

Accesibilidad y temas

• El texto del cuerpo cumple con 4.5:1 de contraste, el texto grande y los límites de control 3:1, en cada tema. El gris atenuado sobre gris es la falla más común.
• El foco siempre es visible y nunca se recorta; el anillo de foco está diseñado, no se elimina el predeterminado del navegador.
• Cada control tiene un nombre accesible; un botón solo de icono recibe aria-label. Puntos de referencia (nav, main) y un h1 por página.
• El texto se redimensiona al 200% y el diseño se mantiene.
• Cuando la aplicación admite un tema oscuro, está diseñado: sus propios pasos de superficie y un acento reajustado, no colores invertidos. Revisa cada pantalla en ambos.

Ergonomía

• La tarea principal se completa desde el teclado: el orden de tabulación sigue el orden de lectura, Enter envía, Escape cierra, el foco vuelve a donde vino.
• Los objetivos de clic son de al menos 24×24px, los frecuentes más grandes, 44px en pantalla táctil; el área de impacto cubre toda la fila o etiqueta, no solo el icono.
• Las acciones frecuentes se sitúan cerca de lo que afectan. La distancia y los clics

…

[truncado para traducción]