UX Playbook
Construye una interfaz de usuario que sea correcta para el negocio, fácil de usar y consistente. Mantine proporciona los componentes; este playbook te dice cuándo usar cada uno, qué estados necesita una pantalla y cómo verificar el resultado. Lee solo las páginas que tu tarea necesite.
Precedencia
Cuando las fuentes discrepen, gana la de mayor rango:
- Requisitos de negocio: la especificación, el ticket o la instrucción del responsable. Nunca los cambies en silencio.
- Las reglas propias del producto:
AGENTS.md/CLAUDE.md, sus documentos de UX y diseño, sus componentes existentes. - Este playbook.
- La documentación y valores por defecto de Mantine.
Si 2 y 3 discrepan, sigue 2. Si crees que 2 o 1 están mal, síguelos de todas formas y plantea una propuesta de UX.
Antes de trabajar en la interfaz, busca las reglas de UX del producto (busca en los docs del repositorio "UX", "UI", "diseño", "panel"). Si no hay ninguna, redáctalas con la plantilla de brief de producto y propón el borrador en el plan o PR, etiquetando cada suposición como [Assumption].
Elige el nivel
| Nivel | El cambio | Qué haces |
|---|---|---|
| S | Cambio pequeño en una pantalla existente: un campo, un botón, un mensaje, una columna | Lee la página del componente que tocas. Ejecuta su lista de verificación. Toma capturas de pantalla si el diseño cambió. |
| M | Una nueva pantalla, diálogo o formulario, o un cambio grande en uno | Escribe primero una especificación de UX corta. Constrúyela. Haz la verificación visual. Autoevalúate con la rúbrica. |
| L | Un nuevo flujo entre pantallas, una nueva área de funcionalidad o un cambio en la navegación | Haz una nota de investigación con 2 o 3 opciones. Construye la opción segura, A. Luego trata cada pantalla como nivel M. |
Detalles y entregables para cada nivel: flujo de trabajo.
Encuentra la página
| Estás decidiendo … | Lee |
|---|---|
| Estructura de página, jerarquía, espaciado, diseño responsivo | decisiones/layout |
| Botones, primario vs secundario, botones de icono, menús de acción | decisiones/actions |
| Modal vs Drawer vs Popover vs en línea, tooltips | decisiones/overlays |
| Navegación de la app, pestañas, migas de pan, steppers, paginación, enlace vs botón | decisiones/navigation |
| Tablas, listas, tarjetas, etiquetas de estado, fechas, texto largo | decisiones/data-display |
| Toasts, alertas, banners, mensajes en línea | decisiones/feedback |
| Qué entrada usar para una elección: checkbox, switch, radio, control segmentado, select, combobox, chips | decisiones/selection |
| Formularios, etiquetas, validación, campos obligatorios | patrones/forms |
| Botones de guardar, autoguardado, cambios sin guardar | patrones/saving |
| Nada que mostrar aún, sin resultados | patrones/empty-states |
| Esperando datos o a que termine un trabajo | patrones/loading |
| Opciones avanzadas, "mostrar más", detalles a demanda | patrones/progressive-disclosure |
| Presentar una funcionalidad, primer uso, sugerencias | patrones/feature-onboarding |
| Backend caído, sin conexión, fallo parcial, permiso faltante | patrones/degraded-experiences |
| Eliminar, restablecer, revocar, sobrescribir | flujos/destructive-actions |
| Etiquetas, texto de botones, texto de error, texto de estado vacío | redacción |
| Teclado, foco, etiquetas, contraste, ARIA | accesibilidad |
| Consultar una API de Mantine, tokens de tema, versiones | mantine |
| La razón detrás de una regla | principios |
Siempre
- Usa los componentes existentes del producto y de Mantine antes de escribir los tuyos propios. Usa un componente por tarea.
- Dale a cada vista de datos sus estados de carga, vacío y error. Dale a cada acción un estado pendiente y un resultado.
- Mantén una acción principal por vista. Las acciones secundarias son más discretas. Las acciones poco frecuentes van en un menú.
- Una acción que no está disponible en este momento permanece visible y explica por qué, en texto que el usuario pueda alcanzar con teclado y
táctil, no solo en un tooltip. Prefiere un aspecto inactivo (
data-disabled) al atributodisabled, y nunca deshabilites un botón de envío: actions. - Confirma o permite deshacer cualquier cosa que destruya datos. Nunca pierdas la entrada del usuario en un error.
- Cada entrada tiene una etiqueta visible. El significado nunca se transmite solo por el color. Todo es accesible mediante teclado.
- Verifica el resultado en ancho de teléfono y ancho de escritorio, en modo claro y oscuro: verificación visual.
- Los ejemplos aquí usan cadenas literales en inglés. Usa la internacionalización (i18n) del producto en su lugar.
Cuando creas que podría ser mejor
Puedes, y debes, proponer flujos y componentes mejores. La regla es construye el valor predeterminado seguro, adjunta la propuesta:
- Construye lo que pide la especificación, usando los patrones de aquí.
- Agrega tu idea como una propuesta de UX en el plan o PR, en el formato fijo.
- Detente y pregunta antes de construir solo cuando la especificación perdería datos, expondría un secreto, bloquearía a un usuario que depende de un teclado o lector de pantalla, o se contradice a sí misma.
Reporte
Cierra cada tarea de interfaz de usuario con una sección de Notas de UX en el PR o informe:
## Notas de UX
- Nivel: M — nueva pestaña "Mods"
- Estados: carga ✓ vacío ✓ error ✓ deshabilitado-con-razón ✓
- Capturas de pantalla: 1280 claro/oscuro, 390 claro/oscuro (adjuntas)
- Rúbrica: todo correcto; n/a: destructivo (ninguno)
- Suposiciones: [Assumption] la lista de mods es corta (< 50), por lo tanto sin paginación
- Propuestas de UX: 1 (ver abajo)