entr034labs/ui-declutter

Declutter de UI

Edita una interfaz para que cada palabra y adorno esté ahí para la persona que la usa. Las pantallas generadas tienden a explicarse a sí mismas: una etiqueta sobre el título, una frase debajo, una pista junto al botón. Cada adición parece inofensiva, y juntas entierran las tres palabras que el usuario vino a buscar.

El objetivo es una pantalla que sirva a su usuario. No es una pantalla que evite parecer generada. La diferencia importa cuando una regla y la necesidad del usuario discrepan: la necesidad del usuario gana, y lo dices en el informe.

Objetivo: el archivo, carpeta o componente que el usuario nombró. Si no nombró ninguno, usa los archivos de interfaz modificados en esta conversación. Si no hay ninguno, pregunta.

Alcance: copia, acciones, estados, contenido inventado, decoración y gráficos. La superficie visual (reglas X1 a X4) solo se incluye cuando el usuario lo solicita, en palabras o con --surface.

Paso 1: di quién está en esta pantalla

Antes de leer una sola cadena, escribe una línea:

Quién: un jugador en medio de una misión que presionó Esc. Haciendo: decidiendo si volver, cambiar una configuración o reiniciar.

Esta línea es contra lo que juzgas todo. Sin ella, las reglas siguientes se aplican como una coincidencia de patrones, y una coincidencia de patrones elimina los requisitos de contraseña junto con el relleno. Un visitante por primera vez en una página de precios necesita más palabras que un usuario diario de una tabla de administración. Un juego puede llevar texto de sabor que un formulario de impuestos no puede.

Si el código no te dice quién es el usuario, infiérelo del producto y establece la inferencia. Pregunta solo si dos lecturas plausibles llevarían a ediciones diferentes.

Paso 2: la prueba

Para cada pieza de texto visible y cada elemento decorativo, pregúntate:

Sin esto, ¿esa persona dudaría, cometería un error o se sorprendería de lo que sucede después?

• No → elimínalo.
• No, pero alguien lo necesita en otro lugar → muévelo. Un hecho para desarrolladores va en un comentario de código. Un hecho que algunos usuarios buscan va en un tooltip o en la documentación. Un nombre que solo la tecnología de asistencia necesita va en aria-label.
• Sí, pero está mal dicho → reescríbelo, usando solo hechos que puedas encontrar en el código, el contenido o la conversación.
• Sí → consérvalo y déjalo en paz.

Las reglas que siguen son las formas comunes en que las pantallas generadas fallan esta prueba. Te ayudan a detectar candidatos rápidamente. Cuando una pantalla falla la prueba de una manera que ninguna regla nombra, la prueba sigue aplicándose. Cuando una regla señala algo que pasa la prueba, consérvalo.

Texto que merece una oración completa

Estos pasan la prueba casi siempre. No los acortes a una etiqueta ni los elimines:

• Restricciones que el usuario debe cumplir: reglas de contraseña, tipos y tamaños de archivo aceptados, formatos de fecha y número, límites de caracteres.
• Consecuencias: lo que elimina una acción destructiva o irreversible, lo que cobra un pago y cuándo, lo que concede un permiso, quién verá algo una vez compartido.
• Errores: qué salió mal y qué hacer a continuación.
• Estados vacíos: qué pertenece aquí y cómo agregar el primero.
• Texto de consentimiento, legal y regulatorio. Nunca edites su redacción. Infórmalo si parece incorrecto.
• Instrucciones para una tarea que el usuario realiza raramente y no puede deshacer.

Reglas

Los IDs son estables. Cítalos en el informe.

Copia

• C1. Etiquetas de ceja. Texto pequeño en mayúsculas o con espaciado sobre un encabezado ("CARACTERÍSTICAS", "CÓMO FUNCIONA", "OPERACIÓN EN PAUSA" sobre "PAUSADO"). El encabezado ya nombra la sección, así que elimina la ceja. Si la ceja es la mejor línea (texto de sabor en un juego, un término propio del producto), promuévela para que sea el encabezado y elimina el genérico. Uno de los dos, nunca ambos.
• C2. Numeración decorativa. "01 02 03", "01 // Características", prefijos "§" y "//". Elimínalo a menos que el orden sea real y el usuario lo siga, como en pasos de pago o una guía de instalación.
• C3. Reflejo de subtítulo. Una oración debajo de cada encabezado, una descripción debajo de cada elemento del menú ("Configuración: Actualiza tu configuración"). Conserva una solo cuando indique un hecho que el encabezado no indica.
• C4. Narración. Texto de ayuda y subtítulos que describen lo que el elemento visiblemente es o hace ("Haz clic en el botón de abajo para comenzar", "Esta tarjeta muestra tu actividad reciente"). Elimínalo.
• C5. Notas de implementación filtradas. Texto sobre cómo funciona la pantalla internamente, o un requisito del prompt renderizado como copia: "Reanudar recaptura el mouse", "(se actualiza en tiempo real)", "(impulsado por IA)", "Los datos se almacenan en caché durante 5 minutos". El usuario no actúa sobre ello. Muévelo a un comentario de código, o elimínalo.
• C6. Cadenas de estado. Hechos encadenados con "·" o "|" ("12 elementos · Actualizado hace 2m · Sincronizado · v2.1"). Conserva el hecho sobre el que el usuario actúa. Pon los demás donde se necesiten, o elimínalos.
• C7. Señales duplicadas. Una etiqueta que repite el marcador de posición, el icono, el texto del botón o el encabezado de la sección. Conserva uno. Para campos de formulario, conserva la etiqueta visible: un marcador de posición desaparece al escribir y no es un nombre accesible.
• C8. Eslóganes. "Una. Gran. Cosa.", "Construido de manera diferente.", "Envía más rápido. Piensa menos." Reescríbelo como una oración que nombre la cosa y lo que hace, si la fuente te da esos hechos. De lo contrario, márcalo para el propietario.
• C9. Encabezados de sección genéricos. "Por qué elegirnos", "Todo lo que necesitas", "Construido para equipos como el tuyo". Un encabezado que podría estar en la página de cualquier producto no dice nada sobre este. Renómbralo por lo que contiene la sección, o elimina el encabezado si el contenido se sostiene sin él.
• C10. Sobrecarga de pistas. Tooltips en controles que ya tienen una etiqueta de texto, chips de atajos de teclado en cada acción, avisos "Consejo:" y "Pro tip", marcas de entrenamiento en una pantalla común. Conserva una pista donde el control es ambiguo (un botón de solo icono) o el atajo es la forma principal de usarlo.

Acciones

• A1. Etiquetas de acción vagas. "Comenzar", "Saber más", "Enviar", "Continuar", "Aceptar", "Haz clic aquí". Un botón dice lo que sucede cuando se presiona: un verbo y un objeto cuando el verbo solo es ambiguo ("Crear cuenta", "Exportar CSV", "Enviar invitación"). "Continuar" y "Siguiente" están bien dentro de un flujo por pasos.
• A2. Una acción, varios nombres. "Eliminar" en una pantalla, "Borrar" en la siguiente y "Papelera" en el menú para la misma operación, o "Iniciar sesión" junto a "Iniciar sesión". Elige el término que el proyecto usa más y aplícalo en todas partes en el objetivo. Cuando dos términos nombran operaciones diferentes (eliminar de una lista versus borrar permanentemente), deja ambos.
• A3. Diálogos de confirmación. "¿Estás seguro?" con "Aceptar" y "Cancelar". El título nombra la acción y su objeto ("¿Eliminar 3 proyectos?"), el cuerpo indica la consecuencia si la hay ("Esto también elimina sus 14 tareas. No puedes deshacer esto."), y el botón de confirmación repite el verbo ("Eliminar proyectos"). Una confirmación en una acción que se deshace trivialmente es en sí misma desorden: márcala para el propietario.

Estados

El texto de carga, éxito, vacío y error es donde se acumula el relleno, porque nadie mira esos estados al revisar una pantalla. Lee references/states.md antes de editar cualquiera de ellos: dice lo que cada estado debe contener, que es más que lo que hay que eliminar.

• S1. Relleno de carga. "¡Aguanta!", "Calculando números…", "Solo un momento mientras preparamos las cosas". Nombra lo que se está cargando solo si la espera es lo suficientemente larga para leerlo. De lo contrario, un spinner o esqueleto solo.
• S2. Relleno de éxito. "¡Guardado exitosamente!", "Tus cambios se han guardado correctamente." Indica el resultado en la menor cantidad de palabras que lo transmitan ("Guardado", "Invitación enviada a [email protected]"). Si la pantalla ya muestra el resultado, no hay toast.
• S3. Relleno de estado vacío. "¡Nada aquí todavía!", "Parece que aún no has creado ningún proyecto. ¡Comienza creando tu primer proyecto!" Di qué va aquí y da la única acción que lo agrega.
• S4. Errores vagos o cursis. "¡Vaya! Algo salió mal", "Ocurrió un error. Inténtalo de nuevo más tarde." Di qué falló y qué puede hacer el usuario. Si el código no puede saber qué falló, dilo claramente y da la opción de reintentar.

Contenido inventado

• F1. Prueba inventada. Recuentos de usuarios, cifras de tiempo de actividad, calificaciones de estrellas, testimonios con nombre y cargo, filas de logotipos "Confiado por", "Visto en". Si el proyecto no tiene una fuente para ello, es una afirmación falsa en una página publicada. No lo reescribas en una afirmación falsa más pequeña. Elimínalo y enuméralo en el informe para que el propietario pueda proporcionar lo real.
• F2. Datos de marcador de posición en pantallas publicadas. "Juan Pérez", "Acme Corp", lorem ipsum, direcciones ejemplo.com, servicios de avatar predeterminados. En fixtures, pruebas e historias esto está bien. En una pantalla publicada, infórmalo como una tarea. No puedes proporcionar datos reales.

Decoración

• D1. Insignias sin estado. "NUEVO", "EN VIVO", "IA", "Beta", "Pro", "Popular" agregados por sabor. Conserva una insignia solo cuando refleje algo que la aplicación rastrea.
• D2. Puntos de estado. Puntos pulsantes o de colores junto al texto. Conserva solo cuando estén vinculados a un estado real, y dale un nombre accesible.
• D3. Emojis e iconos decorativos. En encabezados, botones, etiquetas y elementos de lista. Elimínalos. Un icono se queda cuando es el control (un botón de icono con un aria-label) o cuando transmite un significado que el texto no transmite.

Gráficos y paneles

• V1. Títulos que nombran el tipo de gráfico. "Gráfico de barras de ingresos mensuales" se convierte en "Ingresos mensuales". Indica el hallazgo en su lugar ("Los ingresos se duplicaron desde marzo") solo si los datos que tienes frente a ti lo muestran.
• V2. Instrucciones de lectura. "Cada barra representa un mes", "Pasa el cursor para más detalles". Elimínalo.
• V3. Decirlo dos veces. Una codificación por cantidad. Un KPI con una flecha, un porcentaje, la palabra "arriba" y una oración que reformula los tres conserva el número y una comparación.
• V4. Andamio que compite con los datos. Marcos del gráfico, líneas de cuadrícula oscuras o densas, bordes de eje gruesos, 3D, sombras y brillos en las marcas. Elimínalo, o adelgaza lo que debe quedarse a una línea fina. Mismo tipo de gráfico, mismos datos, mismos colores de serie.
• V5. Leyenda donde funciona una etiqueta directa. Con cuatro series o menos y espacio para etiquetarlas, nombra cada serie al final de su línea o junto a su barra y elimina la leyenda.

Superficie (solo cuando se solicite)

Lee references/surface.md primero. Comienza con una verificación de intención de diseño que decide si estas reglas se aplican en absoluto: un juego, una página de marketing o un layout editorial con tipografía deliberada no es un defecto que deba normalizarse.

• X1. Degradados y brillos. Degradados de tono a tono en superficies y botones, texto degradado, brillos de color, manchas de color borrosas.
• X2. Espaciado fuera de escala. Valores únicos como mt-[13px] o gap: 7px donde los hermanos usan la escala.
• X3. Pesos pesados en UI en ejecución. 800 y 900 en texto del cuerpo, etiquetas, celdas de tabla y controles. Los encabezados de visualización están fuera del alcance.
• X4. Movimiento decorativo. transition-all, tarjetas que escalan al pasar el cursor, rebotes y bucles que no explican nada.

Para el estilo a nivel de cadena en lo que conserves o reescribas (mayúsculas/minúsculas, puntuación, palabras de relleno, consistencia), lee references/writing.md. Para pares de antes y después trabajados, incluyendo casos donde la edición correcta es conservar el texto, lee references/examples.md cuando no estés seguro de hasta dónde recortar.

Barreras de protección

• Nunca agregues un hecho. Una reescritura usa lo que está en el código, los archivos de contenido, los datos o la conversación. "Las ediciones se sincronizan en segundos" es una afirmación del producto, y no sabes que sea cierta. Si la reescritura honesta necesita un hecho que no tienes, elimina la línea o enumérala como una tarea para el propietario. Esta es la regla que se rompe más fácilmente, porque un específico inventado se lee mejor que la línea vaga que reemplaza.
• Cambia solo el texto visible y los elementos decorativos. Deja en paz la lógica, los datos, los colores, la tipografía y la estructura del layout. Las excepciones son el andamio del gráfico bajo V4 y las reglas de superficie cuando se solicite.
• Conserva los nombres accesibles. Nunca elimines aria-label, alt, title en botones de icono, o texto solo para lectores de pantalla. Si el texto visible que eliminaste era el único nombre accesible, muévelo a aria-label.
• Edita el texto en su origen. Las cadenas de archivos i18n, props, fixtures o un CMS se editan allí, o se informan. No codifiques un reemplazo en el componente. Cuando cambies una cadena en un archivo de locale, enumera los otros locales como tareas; no los traduzcas tú mismo a menos que se te solicite.
• Limpia después de un corte. Elimina el contenedor que ahora está vacío y el margen o espacio que existía solo para el elemento eliminado.
• Deja una pantalla limpia en paz. Si nada falla la prueba, no cambies nada.
• Sigue el proyecto. Donde el proyecto tenga su propia guía de voz, glosario, tokens o sistema de diseño, corrige hacia esos y no hacia los valores predeterminados de este skill.

Procedimiento

Rastrea estos pasos:

- [ ] 1. Quién y haciendo: una línea
- [ ] 2. Contar: python3 scripts/count_tells.py <objetivo>      (agrega --surface si se solicita)
- [ ] 3. Mirar: captura de pantalla si puedes
- [ ] 4. Leer cada cadena visible y adorno en cada estado; aplicar la prueba; etiquetar fallos con un ID de regla
- [ ] 5. Veredicto: pesado, ligero o ninguno
- [ ] 6. Editar
- [ ] 7. Contar de nuevo, mirar de nuevo
- [ ] 8. Informe

scripts/ está en la carpeta de este skill. Ejecuta el script con su ruta completa.

Contar. count_tells.py es un pase de expresiones regulares sobre el código fuente. Encuentra candidatos y da un número antes y después para los patrones que tienen una firma de código. No puede ver C3, C4, C5, C7, A2, V3 ni nada que dependa del significado, y marca usos legítimos. Trata su salida como una lista de lugares para mirar. Un conteo que no llegue a cero está bien cuando lo que queda se conserva a propósito.

Mirar. El código fuente oculta lo que el usuario ve: qué cadenas aparecen juntas, qué viene de los datos, qué hace una eliminación al layout. Si tienes un navegador o herramienta de captura de pantalla, captura la pantalla antes y después. Si no tienes ninguno, python3 scripts/screenshot.py <url-o-archivo-html> <salida.png> lo hace donde Playwright está instalado. Revisa la imagen después para espacios huérfanos, un encabezado que perdió su jerarquía y controles que se movieron. Si no puedes renderizar la pantalla, dímelo en el informe.

Leer cada estado. La vista predeterminada es una fracción de la interfaz. Busca en el objetivo ramas de carga, vacío, error, éxito y deshabilitado, toasts, diálogos y validación.

…

[truncado para traducción]