¿Qué hace 21 Grams UI?
Un pase sobre la interfaz de usuario que ya existe. 21 Grams UI (el paquete de UI de la familia 21 Grams) no rediseña el producto ni trae su propio kit de UI. Elimina las marcas de una interfaz construida por IA y aplica un conjunto fijo de reglas a través de los componentes y tokens que el proyecto ya tiene, para que el resultado se vea considerado, se sienta rápido y siga perteneciendo al producto.
Regla cero: usa los componentes propios del proyecto
Cada cambio pasa por lo que el proyecto ya usa. 21 Grams UI nunca construye un conjunto de componentes paralelos.
- Haz un inventario antes de tocar nada. Anota los tokens de diseño o tema (variables CSS, configuración de Tailwind, archivos de tema), la librería de componentes (shadcn/ui, Radix, MUI, Chakra, un kit interno, un sistema de diseño del cliente), el conjunto de iconos, la librería de gráficos y la librería de animación. Registra cómo se llama cada componente compartido y dónde vive.
- Arregla las cosas donde viven. Una regla de botón va al
Buttondel proyecto (un token, una variante, una prop o sus estilos), nunca a una copia única en una sola pantalla. Una regla de color o radio va al token, no a valores hardcodeados. - Nunca agregues un componente cuando ya existe uno para el trabajo, y nunca agregues una dependencia (kit de UI, conjunto de iconos, librería de gráficos o animación) para obtener un efecto de 21 Grams UI. Usa lo que está instalado. Sin una librería de animación, usa transiciones CSS.
- Cuando una pieza falte genuinamente (sin control segmentado, sin interruptor), constrúyela a partir de los primitivos y tokens existentes del proyecto, siguiendo su estructura de archivos y convenciones de nomenclatura. Dilo en el informe.
- Los valores del estilo de la casa son valores predeterminados solo para huecos.
rules/ytokens/tokens.cssproporcionan valores para lo que el proyecto no ha decidido. Mapealos a los tokens del proyecto. Nunca peguestokens.cssjunto a un sistema existente. - La marca sigue siendo del proyecto. Los colores, fuentes, logotipos, estilo de iconos y voz de la marca nunca se reemplazan. 21 Grams UI cambia cómo se usan (contraste, jerarquía, espaciado, movimiento), no qué son.
Precedencia: las palabras del usuario, luego el sistema de diseño y la marca del proyecto, luego el estilo de la casa de 21 Grams UI. Los principios, trucos y oficios de animación se aplican en todas partes, expresados en los componentes propios del proyecto.
Qué hay dentro
- Estilo de la casa. Ocho áreas en
rules/:radius.md(12/8/4 anidados),buttons.md(36px, presión .97),motion.md(suave, desde el activador, sin rebote),type.md(apretado, pocos tamaños),spacing.md(agrupado 4pt),colour.md(un acento, AA),elevation.md(rellenos tonales),copy.md(claro y útil). Más tres archivos de componente:icons.md(un estilo, línea, sólido o duotono, nunca mezclado),charts.md(línea, columna y barras horizontales) ytoggles.md(interruptor y control segmentado). Los valores predeterminados están entokens/tokens.css. - Los 20 principios. Principios de UX y animación en
references/principles.md. - Los 10 trucos de diseño. Detalles de artesanía a nivel CSS en
references/design-hacks.md. - Los 20 oficios de animación. Reglas de movimiento a nivel de implementación (orígenes, duraciones, escalonamiento, presión, arrastre, diseño compartido) en
references/animation-craft.md. - Los 10 trucos de tipografía. Ancho de negrita reservado, recorte de caja de texto, desplazamiento de subrayado, espaciado de superíndices, tipografía fluida para displays, mayúsculas pequeñas para acrónimos, comillas curvas, truncamiento medio, separación silábica automática y títulos con recorte de línea, en
references/typography.md. - Las 20 reglas anti-desastre. Señales de composición y contenido (insignias de relleno, etiquetas redundantes, cursivas aleatorias, mono decorativo, arte abstracto de héroe, características de igual peso, titulares vagos, brillos, alineación óptica, estados de carga) en
references/unslop.md.
Si hay instalado un skill de visualización de datos, cárgalo también siempre que haya un gráfico involucrado.
Flujo de trabajo
- Haz el inventario (regla cero). Si el proyecto no tiene ningún sistema de diseño, dilo y usa los valores predeterminados del estilo de la casa.
- Audita antes de cambiar nada. Revisa la pantalla o componente y enumera los hallazgos agrupados por área (radio … copia), número de principio, número de truco y número de oficio. Usa las listas de verificación al final de
references/principles.md,references/design-hacks.md,references/animation-craft.md,references/typography.md,references/unslop.mdyrules/icons.md. Cada hallazgo obtiene el archivo y la línea, qué está mal, la solución y en qué componente o token existente va la solución. Señala cada lugar donde una regla de 21 Grams UI entre en conflicto con el sistema de diseño del proyecto, para que el usuario decida cuál gana. - Muestra la auditoría al usuario como una lista corta y pregunta antes de aplicar cambios amplios. Las correcciones pequeñas y obvias dentro del alcance solicitado pueden aplicarse directamente.
- Aplica las correcciones en este orden: tokens → componentes compartidos → pantallas. Mantén los diffs limitados a lo que se auditó y en las convenciones propias del proyecto (formato, lint, nomenclatura).
- Verifica en el navegador. Capturas de pantalla de antes y después de cada pantalla cambiada. Verifica hover, presión, foco, carga, error, ambos temas y movimiento reducido. Mide el contraste de botones y texto; no lo calcules a ojo. Para movimiento, graba el antes y el después si es posible. Una página de antes/después con un divisor arrastrable e interacciones funcionales en ambos lados es la forma más clara de revisar una mejora.
- Informa qué cambió por área, principio, truco y oficio, qué componentes y tokens se tocaron, y cualquier cosa que haya quedado sin hacer.
Estilo de la casa de un vistazo (valores predeterminados para huecos)
- Radio 12 contenedores / 8 controles / 4 partes pequeñas, anidados como exterior − padding. Sin píldoras excepto etiquetas e interruptores.
- Botones 36px (32 compactos, 40 prominentes), radio 8, 14/500, un sólido primario, un primario por vista, hover = solo paso de color, presión = paso de color +
scale(.97)150ms, carga mantiene el ancho. - Movimiento: sin rebote en la UI diaria. Menús 220ms de entrada / 175ms de salida desde
scale(.95)en el activador, paneles 240 / 190, entradasease-out, salidasease-in(~80% de la entrada), filas de lista escalonadas 30ms, interacciones frecuentes instantáneas. - Tipografía: las fuentes del proyecto (Geist cuando no hay ninguna). Mono solo para código, nunca etiquetas, cejas, insignias, marcas de tiempo o números (
tabular-numsen la sans alinea las cifras). Tamaños 12/14/16/22/28, pesos 400/500/600, encabezados −0.022em, como máximo cuatro tamaños por pantalla. En móvil, los encabezados suben un paso: sección 18, tarjeta 16. - Enviar chat en móvil es un botón de avión de papel 44×44 solo icono con
aria-label="Enviar". - Espaciado: escala 4pt. Más ajustado dentro de grupos que entre ellos (4 / 6 / 16 / 24–32 / 48). Chevron de selección 12px desde la derecha, padding-right 36px.
- Color: un acento (acciones, foco, selección), colores de estado separados, texto del botón ≥ 4.5:1 en ambos temas con
--on-accentpor tema. - Elevación: las superficies en reposo son un paso de relleno sin borde ni sombra. Solo las capas flotantes obtienen un anillo y sombra. El modo oscuro es más claro por capa.
- Iconos: un estilo por producto, línea, sólido o duotono, y nunca mezclado en un menú, navegación, barra de herramientas, lista o tarjeta. Los estados seleccionados cambian de color, no de estilo de icono. Una librería de iconos, un grosor de trazo, un tamaño por grupo.
- Copia: botones verbo + objeto, errores con causa y solución, mayúscula inicial, sin emojis, sin palabras de hype.
No negociables (de los 20 principios)
- El movimiento de UI iniciado por el usuario es de 120–300ms, y las salidas son aproximadamente el 80% de la entrada. Nunca
linearpara movimiento. - La curva de aceleración coincide con la dirección: entrada
ease-out, salidaease-in, A→B en pantallaease-in-out. Sin sobreimpulso en la UI diaria. - Las interacciones de alta frecuencia (navegación por teclado, resaltado de listas, pestañas en herramientas) son instantáneas.
- Cada entrada es reconocida en menos de 100ms. Usa UI optimista para guardados. Muestra progreso después de 400ms.
- Las áreas de clic miden al menos 44×44 en táctil y 32×32 en escritorio denso, incluso cuando el icono es más pequeño.
- Un foco y una acción principal por vista. Atenúa el contexto cuando algo toma el foco.
- Los números largos están agrupados. Las entradas aceptan formatos desordenados y devuelven el valor limpio.
- Colocación e iconos estándar a menos que haya una razón para no hacerlo.
- Cada estado del componente está diseñado: inactivo, hover, presionado, cargando, éxito, error, deshabilitado.
prefers-reduced-motion: eliminar movimiento, escala y sobreimpulso, mantener un breve cambio de opacidad.
No negociables (de los 10 trucos)
- Radio anidado: interior = exterior − padding.
- Los bordes son alfa (
rgb(0 0 0 / .12)), nunca gris sólido hexadecimal en superficies variadas. - Paletas y degradados en OKLCH (
in oklchen degradados). - El grosor del trazo del icono coincide con el peso del texto adyacente.
- Los desplazadores horizontales se desvanecen en los bordes con una máscara.
- Los intercambios de iconos se funden con
filter: blur(4px). - Modo oscuro: cada capa superior es más clara (página < tarjeta < menú).
- Altura completa en móvil:
dvh/svh, nunca100vhsolo. - Fotos de producto con fondo blanco en tarjetas teñidas:
mix-blend-mode: multiply.
No negociables (de los 10 trucos de tipografía)
- Negrita al pasar el ratón o al seleccionar nunca cambia el diseño (reserva el ancho de la negrita).
- Las etiquetas de una sola línea en botones e insignias están centradas ópticamente (
text-box-trim). - Los subrayados de enlaces evitan los descendentes (
text-underline-offset: 0.2em). Los superíndices no rompen el ritmo de la línea. - Puntuación real en la copia: comillas curvas, apóstrofes, guiones en,
…. - Los nombres que difieren al final se truncan por el medio. Los títulos de tarjetas en cuadrículas están limitados al mismo número de líneas.
No negociables (de los 20 oficios de animación)
- Los popovers y menús crecen desde su activador (
transform-originen el activador), comienzan enscale(.95), nuncascale(0), y salen de vuelta al activador. - Los estados antiguo y nuevo se superponen. Nunca hay un fotograma en blanco entre Guardar y Guardado.
- Los arrastres siguen el puntero 1:1 sin transición mientras se mantienen, y se estiran elásticamente más allá de sus límites.
- Tarjeta → detalle expande el mismo elemento (
layoutIdcompartido / transición de vista), nunca un reemplazo desconectado. - Los controles segmentados y pestañas revelan la etiqueta activa con una máscara que viaja con el indicador.
- Las perillas móviles se estiran aproximadamente un 12% (que conservan el área). El éxito obtiene un pulso.
Señales de IA a eliminar
Estilos de iconos mixtos (una casa sólida junto a una carpeta de contorno, un icono de contorno que se vuelve sólido al seleccionarlo), dos librerías de iconos en una pantalla, emojis usados como iconos, insignias de relleno "NUEVO" sobre titulares, cejas que repiten el encabezado, una palabra en cursiva o mono aleatoria en un titular, etiquetas mono, cejas, insignias, marcas de tiempo o números (mono en mayúsculas "técnico" como // 01 ESTADO), orbes 3D brillantes en lugar del producto real, filas de tarjetas de características iguales, titulares "X, conoce a Y."", bordes degradados brillantes, degradados índigo a violeta, texto degradado, sombras de color brillantes, el mismo radio de 16px en todo (radio interior igual al exterior), botones píldora junto a entradas redondeadas, escala hacia arriba en hover en tarjetas y botones, 300ms ease-in-out en todo, desvanecimiento hacia arriba en la carga de página, p-6 gap-6 uniforme, tarjetas dentro de tarjetas, sombra más borde más radio en cada bloque, grey-500 para todo el texto secundario, emojis en encabezados, y copia como "Desbloquear", "Sobrealimentar", "Sin fisuras" o "¡Ups!".
Créditos
Los principios, trucos y oficios de animación están parafraseados y extendidos a partir de cinco videos cortos de diseño: "20 Principles of UX & Animation", "10 Niche Design Hacks", "20 Ways to Make Beautiful AI Animations", "10 Niche Typography Hacks" y "20 Ways to Unslop AI Designs". Consulta el README para los créditos.