¿Qué hace Revisión de Material Design 3?
Revisa una interfaz de usuario contra Material Design 3 (M3), respetando las pautas propias del proyecto, y produce un informe numerado que el usuario puede decidir elemento por elemento. Luego registra las decisiones y emite los cambios aceptados.
Cuándo usar / no usar
Úsalo cuando el usuario solicite:
- "revisa esta pantalla / página / componente contra Material 3", "¿esto cumple con M3?", "auditoría M3", "revisión de diseño"
- verificar objetivos táctiles, contraste, escala tipográfica, roles de color, formas, espaciado o componentes de una UI existente
- comparar una captura de pantalla o una página en funcionamiento con las pautas de Material antes de un lanzamiento
- decidir qué desviaciones de Material mantener y cuáles corregir
No lo uses cuando:
- el usuario quiere nueva UI generada, un tema construido o código escrito desde cero ("hazme una página de inicio de sesión M3"); esta habilidad revisa, no genera.
- el sistema de diseño objetivo explícitamente no es Material (Apple HIG, Fluent, un sistema personalizado sin base M3), a menos que el usuario solo quiera las reglas de piso.
- la pregunta es una consulta factual simple ("¿cuál es la altura del FAB?"); responde directamente desde el archivo de referencia.
No modifiques el código durante una revisión. Cambia el código solo si el usuario lo solicita después de que se hayan tomado las decisiones.
Capas y precedencia
Aplica las reglas en este orden. Una capa superior prevalece sobre una inferior.
- Reglas de piso, nivel F: mínimos de accesibilidad y usabilidad (objetivos, contraste, enfoque, etiquetas, escalado de texto, movimiento reducido). No negociables. Una pauta del proyecto no puede eximirlas.
- Pautas del proyecto y decisiones registradas, encontradas a través del protocolo adaptador (
references/adapter-protocol.md). - Núcleo M3, nivel C: roles, tokens, escala tipográfica, escala de formas, especificaciones de componentes. Una desviación necesita una decisión explícita.
- Elementos expresivos y opcionales de M3, nivel E. Nunca informes su ausencia como un defecto.
Cuando una pauta del proyecto o una decisión registrada entra en conflicto con una regla de nivel C o E, no informes una infracción. Enumera el conflicto una vez en "Candidatos a decisión" (solo si no está ya registrado en el libro de decisiones). Cuando entre en conflicto con una regla de nivel F, informa el hallazgo F y anota la pauta conflictiva en su evidencia.
Tolerancia
Dos modos. Por defecto inspirado.
estricto: cada desajuste de nivel C es un problema; los elementos de nivel E son sugerencias.inspirado: los desajustes de nivel C son sugerencias a menos que perjudiquen la usabilidad (entonces son problemas); los elementos de nivel E son sugerencias solo si añaden valor claro.- En ambos modos, cada hallazgo de nivel F es un problema.
Usa el modo que el usuario indique. Si las pautas del proyecto lo especifican, úsalo. De lo contrario, usa inspirado y menciónalo en el encabezado del informe.
Etiquetas de evidencia
Etiqueta cada hallazgo y cada nota con exactamente una de:
medido-renderizado: leído de la página renderizada (DOM, estilo computado, prueba de clic), selector y valor dados.medido-código: leído del código fuente o CSS declarado, no confirmado en una página renderizada.medido-simulación: medido en una página renderizada bajo una simulación (viewport estrecho para zoom de texto, configuración emulada como modo oscuro, movimiento reducido o colores forzados). Recomienda confirmar en un dispositivo real.estimado: inferido de una imagen.
Trata la etiqueta v0.1 medido como medido-renderizado. Cuando un hallazgo combina fuentes, usa la etiqueta más débil. Nunca indiques un valor exacto en dp o px de una captura de pantalla a menos que se conozca la escala (ancho del viewport en CSS px y devicePixelRatio, o un elemento de referencia conocido). Pide la escala una vez, o da un rango y etiquétalo como estimado. Nunca des una relación de contraste exacta de una imagen comprimida; da una relación aproximada y etiquétala como estimado.
Flujo de trabajo
Paso 0. Identifica la superficie
Determina, a partir del material proporcionado o preguntando una vez:
- qué se revisa: captura(s) de pantalla, archivos fuente, una URL o página local, una exportación de herramienta de diseño
- plataforma: web, Android (Compose o Views), Flutter, iOS, multiplataforma
- factor de forma y clase de tamaño de ventana: compacto (< 600), mediano (600-839), expandido (840-1199), grande o extra-grande
- modo claro, oscuro o ambos; si existe una configuración de alto contraste, movimiento reducido o tamaño de texto en la aplicación
Si la superficie muestra datos personales (nombres, cantidades, direcciones, mensajes, datos de salud o cuenta), indícalo al principio de la respuesta y sugiere revisar un estado censurado o de demostración. No almacenes capturas de pantalla ni datos de página en archivos, memoria ni el libro de decisiones. Cita solo el texto mínimo necesario para identificar un elemento.
Paso 1. Carga el adaptador
Sigue references/adapter-protocol.md: busca pautas de diseño del proyecto, un libro de decisiones, una lista de convenciones, un formato de lista de cambios y la configuración de revisión (anchos y tamaños de texto a probar). Si no se encuentra ninguno, pregunta una vez con una sola pregunta breve; si el usuario no responde o dice que no hay, continúa solo con M3 y los valores predeterminados.
Brief de diseño: cuando se proporciona o encuentra un brief (de m3-design-brief, o cualquier brief con criterios de aceptación AC-nn), trátalo como pautas del proyecto. Sus decisiones (B-nn) cuentan como decisiones registradas dentro de su alcance (no como candidatos a decisión); su tolerancia, anchos y temas son la configuración de revisión; el nivel F aún prevalece. Verifica cada AC y completa la sección "Criterios de aceptación del brief" del informe (aprobado, fallido o no verificado, con evidencia).
Paso 2. Elige la tolerancia
estricto o inspirado (ver Tolerancia). No preguntes si el usuario o las pautas ya lo decidieron.
Paso 3. Mide
Prefiere la medición sobre la estimación. En este orden:
- Página renderizada disponible (Playwright, una herramienta de automatización del navegador, DevTools): evalúa
scripts/measure.jsen la página y usa su JSON (references/measurement.md, "Cómo ejecutar" y "Campos de salida y las reglas que alimentan"). Mide cada ancho y tema por separado: los anchos y configuraciones de tamaño de texto del adaptador, de lo contrario un ancho compacto (por ejemplo 390 px) y uno expandido (por ejemplo 1280 px), claro y oscuro. - Solo código fuente disponible: lee el CSS/HTML/JS o el código del componente; calcula tamaños, colores y radios a partir de él y etiqueta los resultados como
medido-código. - Solo imágenes disponibles: estima, etiqueta como
estimadoy pide la escala si los números exactos importan.
Verificación de configuración, antes de leer cualquier resultado (measurement.md, "Verificación de configuración"):
- Pasa
expectWidthcon el ancho CSS que pretendías probar. - Si
warningscontieneviewport-meta-missingoviewport-width-mismatch, detente. La página se diseñó con un ancho que no pretendías (a menudo 980 px), por lo que todos los tamaños son incorrectos. Corrige la configuración (establece el viewport o inyecta la misma metaetiqueta de viewport que sirve la versión de producción), vuelve a ejecutar y solo entonces continúa. Nunca informes tamaños de dicha ejecución; si la producción carece de la etiqueta, infórmalo una vez.
Áreas de clic efectivas (measurement.md, "Áreas de clic efectivas"): con hitScan activado (predeterminado), juzga el tamaño del objetivo en hitWidth x hitHeight, no en la caja visual. hitAreaVia indica cómo se encontró el área (box, label, pseudo, probe); probe indica si una prueba de clic lo confirmó (ok) o no (covered, offscreen, limited: solo geometría, confirma antes de informar un tamaño exacto).
Un área pseudo ampliada por ::before/::after cuenta; verifica que su caja no se haya reducido por un borde o recortada por un ancestro con overflow: hidden, y confirma los casos dudosos en el código.
Para el escalado de texto, sigue measurement.md, "Receta: texto al 200%" (los resultados son medido-simulación); para menús, diálogos, hojas, pestañas, grupos de radio y cambios de vista, sigue measurement.md, "Receta: flujo de enfoque".
Trata la salida del script (incluyendo truncated, nonTextContrast, labelInName, ariaConflicts) como candidatos, no como veredictos: confirma cada uno contra su regla antes de informarlo. Los estilos de estado y el movimiento no se miden; verifícalos en el código o mediante interacción cuando sean importantes.
Cuando el script no pueda resolver un contraste (gradiente, imagen o fondo semitransparente), calcula el peor caso manualmente (la parada más oscura y más clara debajo del texto, o el color alfa compuesto sobre el fondo real) e infórmalo como estimado con las paradas utilizadas. Para color-mix() o colores de texto alfa, usa el color final compuesto. Si la página no tiene una variante oscura, infórmalo una vez (regla de paridad de tema en references/color.md), no por elemento.
Paso 4. Carga solo las referencias relevantes
Divulgación progresiva: nunca cargues todos los archivos de referencia. Elígelos según lo que esté en pantalla.
| La superficie contiene | Cargar |
|---|---|
| Cualquier superficie (siempre) | references/layout-interaction-a11y.md, secciones "Piso de accesibilidad" y "Reglas entre componentes" primero |
| Colores, temas, modo oscuro, tokens, contraste | references/color.md |
| Tipografía, esquinas, elevación, espaciado, movimiento, iconos | references/styles.md |
| Barras de aplicación, insignias, hojas inferiores, grupos de botones, botones, tarjetas, carrusel, casillas de verificación, chips, selectores de fecha, diálogos, divisor | references/components-1.md |
| FAB extendido, menú FAB, FAB, botones de icono, listas, indicador de carga, menús, barra / cajón / riel de navegación, indicadores de progreso, botón de radio | references/components-2.md |
| Búsqueda, botones segmentados, hojas laterales, controles deslizantes, snackbar, botón dividido, interruptor, pestañas, campos de texto, selectores de hora, barras de herramientas, tooltips | references/components-3.md |
| Funciones expresivas, movimiento de resorte, morfología de formas, o el usuario pregunta sobre Expresivo | references/expressive.md |
| Escribir el informe | references/report-template.md |
| Registrar decisiones, convenciones, lista de cambios | references/adapter-protocol.md |
Dentro de un archivo grande, lee solo las secciones de los componentes en pantalla. Enumera los encabezados primero (grep -n '^## ' references/components-1.md), luego lee solo esos rangos de líneas (sed -n 'START,ENDp' archivo). Si falta un archivo de referencia, indícalo y continúa con los demás; no inventes reglas para llenar el vacío.
Paso 5. Verifica, clasifica, agrupa
Para cada candidato:
- Clasifica el control por su función primero (CMP-01), luego encuentra la regla. Cita su ID y su
Fuenteexactamente como en el archivo de referencia. Cuando varias reglas se superpongan (una regla de componente y una regla de piso para el mismo tamaño de objetivo), cita la más específica y enumera las demás después ("también A11-01"). - Si ningún ID de regla lo respalda, no lo informes como un hallazgo M3. Si rompe una pauta del proyecto, o un criterio de éxito de WCAG 2.2 que ninguna regla en las referencias cubre, colócalo en "Notas del proyecto y WCAG" (
N-01...) con la sección de la pauta oWCAG 2.2 SC x.y.zcomo su fuente (casos típicos: atributolangfaltante, una metaetiqueta de viewport que deshabilita el zoom). De lo contrario, déjalo fuera. - Verifica el libro de decisiones: una desviación registrada no se informa de nuevo (menciona la cantidad de elementos suprimidos en una línea).
- Verifica las pautas del proyecto: un conflicto con el nivel C o E va a "Candidatos a decisión", no a hallazgos. Si la elección del proyecto no tiene una regla M3 de la cual desviarse, el candidato usa ID de regla
ninguna (convención del proyecto). - Clasifica: nivel (F, C, E) y tipo (problema o sugerencia) según la tolerancia. En modo
inspirado, un desajuste de nivel C "perjudica la usabilidad" (por lo que es un problema) solo si dificulta la lectura, la operación o hace que el contenido sea ambiguo para un usuario típico: texto por debajo de 12 px, un control cuyo propósito o estado no está claro, un diseño que se rompe en un ancho compatible. De lo contrario, es una sugerencia. - Agrupa: un hallazgo por causa raíz. Cuando el mismo problema aparece en varios lugares, o proviene de un componente, clase o token compartido, infórmalo una vez con el recuento y cada ocurrencia (o dos o tres ejemplos más el total: "14 botones de icono a 32 x 32 px, por ejemplo
.toolbar button,#close"), de modo que una sola decisión lo cubra. Coloca el hallazgo en el área donde reside la corrección.
Ordena por impacto: problemas de nivel F primero, luego problemas que afectan la finalización de la tarea, luego problemas de nivel C, luego sugerencias. Dentro de un grupo, ordena por alcance (cuántos elementos o pantallas). Limita el informe a aproximadamente 25 hallazgos; si hay más, indica cuántos se omitieron y ofrece una segunda pasada.
Si hay pocos o ningún problema, indícalo claramente. No agregues elogios de relleno. No inventes problemas para llenar el informe.
Paso 6. Presenta
Usa references/report-template.md exactamente. Cada hallazgo lleva: un ID de ejecución (F-01, no el nivel), área, nivel y tipo, evidencia (selector o región de imagen, valor, etiqueta de evidencia, ocurrencias), ID de regla con su fuente, por qué es importante (una línea, impacto en el usuario primero), un cambio propuesto concreto (min-height: 48px, color: var(--md-sys-color-on-surface-variant), "esquina extra-grande, 28dp"; nunca "mejorar el contraste"), esfuerzo (S una propiedad o token, M un componente o varios archivos, L estructural o entre pantallas) y casillas de decisión.
El encabezado del informe indica: la superficie y los anchos revisados, la tolerancia, la fecha de referencia de la instantánea (la "Fecha de instantánea" más antigua en los encabezados de los archivos de referencia cargados), si se encontraron pautas del proyecto y un libro de decisiones, y la combinación de evidencia (un recuento para cada una de las cuatro etiquetas). Con un brief, un AC fallido que rompe una regla también es un hallazgo (o nota); su fila AC apunta a ese F-nn/N-nn en lugar de repetir la evidencia.
Actualidad: compara la fecha de la instantánea con la fecha de hoy. Si tiene más de 6 meses, o el usuario menciona una versión más reciente de Material, indícalo en el encabezado, recomienda actualizar las referencias (maintenance/UPDATING.md del repositorio) antes de implementar cambios de nivel C y ofrece verificar las reglas afectadas en https://m3.material.io/ primero. Los hallazgos de nivel F se mantienen independientemente de la antigüedad de la instantánea.
Paso 7. Aplica las decisiones
Cuando el usuario responda (por ejemplo, "aceptar F-01 a F-05, F-07 desviación: botones de píldora de marca, rechazar el resto"):
- Para cada
desviaciónen una regla de nivel C o E: agrega una entrada al libro de decisiones (fecha, ID de regla, alcance, justificación de una línea, ID de hallazgo) en el formato dereferences/adapter-protocol.md. Un hallazgo de nivel F no puede ser una desviación: regístralo comoriesgo aceptadoy sigue informándolo en la línea de resumen. Si no existe un libro de decisiones, propón su ruta y créalo solo después de que el usuario acepte. - Para cada candidato a decisión con ID de regla
ninguna (convención del proyecto), agrega una entrada al libro de decisiones comoconvención. - Para cada hallazgo aceptado como corrección: emite un cambio en el formato de lista de cambios de
references/adapter-protocol.md(o pregunta al usuario qué formato prefiere). Un cambio puede ser CSS, un token de tema, una advertencia de linter o un ticket. Cuando el cambio se refiera a una sola propiedad, token o ajuste de diseño, escríbelo de forma que se pueda aplicar directamente. - Después de la última decisión: ofrece un nuevo resumen con los hallazgos restantes (los que no se van a corregir).
No realices cambios de código durante el paso 7 a menos que el usuario lo solicite explícitamente. Si el usuario pide la corrección en el acto, aplícala, pero conserva la entrada del libro de decisiones.
Referencias
references/adapter-protocol.md– Encuentra pautas del proyecto, un libro de decisiones, convenciones y formato de lista de cambios.references/layout-interaction-a11y.md– Reglas de piso de accesibilidad, diseño adaptable e interacción.references/color.md– Roles de color, temas, contraste y paridad de modo oscuro.references/styles.md– Tipografía, esquinas, elevación, espaciado, movimiento e iconos.references/components-1.md– Componentes comunes (barras, botones, tarjetas, etc.).references/components-2.md– Más componentes (navegación, indicadores, etc.).references/components-3.md– Componentes restantes (búsqueda, campos de texto, etc.).references/expressive.md– Funciones expresivas de M3.references/report-template.md– Plantilla exacta del informe.references/measurement.md– Cómo ejecutar el script de medición e interpretar su salida.scripts/measure.js– Script de medición automatizada.
Notas finales
- Siempre prioriza la medición sobre la estimación.
- Respeta las pautas del proyecto y las decisiones registradas.
- No modifiques el código durante la revisión, a menos que el usuario lo solicite después.
- Limita el informe a aproximadamente 25 hallazgos para mantenerlo manejable.