Eclipse UI

El problema

Un estudio de barre y un box de HIIT no deberían verse iguales, pero en Eclipse lo único que cambiaba de una instancia a otra era el color de marca. Las vistas escribían sus colores a mano: en las 17 vistas públicas había 442 referencias sueltas a variables ([var(--color-…)]), 207 clases de la paleta de Tailwind (gray-500, white…) y 48 íconos pegados como <svg>. Cambiar la voz o la forma de un estudio significaba editar vista por vista, en cada instancia.

Además, la marca de base, un dorado (#a3946b), se usaba como texto y como fondo de botones: medía entre 2.7 y 3.0:1, y WCAG AA pide 4.5:1. En cinco páginas, axe encontró 58 elementos con contraste insuficiente.

Lo que necesitaba era un sistema que separara dos cosas: lo que todo estudio merece por igual y lo que hace a cada uno distinto.

La idea: base y personalidad

La base es lo que no cambia de un estudio a otro, y si un componente rompe una de estas garantías, no está terminado: accesible de verdad (contraste AA medido, foco visible, teclado completo, movimiento reducido respetado); solo tokens y escalas, nunca un color o un tamaño suelto; jerarquía por capas y bordes de 1 px, con la sombra reservada para lo que flota; movimiento físico; integrado con Rails (los controles mandan su valor con name:, funcionan con Turbo y con el form builder), y un código que es de quien lo usa, sin cajas negras.

La personalidad es lo que decide cada estudio, en cinco rasgos:

Los rasgos se mueven con 27 diales que caben en un bloque de theme.css. El motor deriva lo demás: la paleta, los hover, el texto que va sobre la marca, las capas, las sombras, los radios y las duraciones. Partí de seis personalidades pensadas para tipos de estudio distintos, y cada una es un punto de partida, no un tema cerrado:

Llevar una a un estudio es copiar su bloque a theme.css y mover los diales que haga falta. Todo lo demás se realinea solo.

Los guardianes: que la base no dependa de la memoria

Un sistema que promete contraste AA en cualquier combinación de diales no puede revisarse a ojo. Así que la base tiene guardianes que corren con las pruebas:

• Contraste. Una lista de 22 pares de texto y superficie (config/eclipse_ui/contrast.yml) se mide en un navegador real en las seis personalidades y en el theme.css del estudio, en claro y en oscuro: 308 mediciones en 0.6 s. Las mide un navegador porque el motor deriva los colores con color-mix(in oklab) y oklch(from …), y reimplementar eso en Ruby sería una segunda copia del motor que tarde o temprano diría otra cosa que la pantalla. Si un estudio elige una marca con la que algún texto deja de leerse, la prueba dice cuál.
• Tokens. Ocho reglas recorren cada componente y su CSS y fallan, con archivo y línea, si aparece un hex, un color de la paleta de Tailwind, una sombra que no sigue el dial, un tamaño de texto en px, un rounded sin escala o una variable escrita a mano donde hay una utilidad con nombre.
• Catálogo. Cada componente tiene ficha, demo, props, patrón ARIA y teclado. Una pieza solo puede decir "estable" si una vista real de la app la usa.

El contraste dejó de ser una decisión estética: la marca como texto usa text-primary-text, un tono derivado que pasa AA en todas las personalidades (mínimo 5.7:1), y el texto sobre un botón de marca se elige solo (6.0:1 sobre el dorado).

Física sin React

Los componentes con vida suelen venir de librerías de React. Eclipse es Rails con Stimulus, así que escribí la física desde cero: spring.js son 127 líneas sin dependencias, con un integrador de paso fijo (1/240 s) que se comporta igual en una pantalla de 60 Hz que en una de 120 Hz.

• Cinco ajustes con nombre en lugar de duraciones: snappy llega al 1 % de su destino en 300 ms (botones, indicadores), gentle en 550 ms (pestañas, diálogos) y responsive en 192 ms, con un rebote de 0.9 % que se reserva para los regresos y las pilas de avisos.
• Conserva la velocidad. Si el destino cambia a medio camino (un arrastre, un botón magnético que sigue al cursor), el resorte no reinicia: sigue desde donde iba. Esa es la diferencia entre algo que se siente físico y algo que se siente animado.
• Obedece al estudio y a la persona. El dial de ritmo (--eui-motion) escala el tiempo de todos los resortes y de las transiciones CSS, y con prefers-reduced-motion todo salta al final.

Hoy la usan 34 controladores de Stimulus: deslizar para reservar, dígitos que ruedan, pestañas con pastilla, modales que se asientan, avisos que se arrastran.

En la app real: el sitio público de la demo

La prueba de fuego fue vestir el sitio público completo de la demo con los componentes: navegación, pie, avisos, confirmaciones, portada, horario, clase, precios, contacto, acceso, registro, cuenta y Nosotros. Las capturas usan la misma base de datos en las dos versiones; solo cambia el código.

Lo que cambió en el código de las vistas públicas:

Lo que cambió en accesibilidad (axe 4.10, WCAG 2.1 AA, en portada, horario, clase, precios y acceso, en escritorio y modo claro):

El pie fue lo último en caer: sus etiquetas y créditos usaban text-faint, a 3.66:1 sobre negro, y el propio sistema dice que text-faint no es para texto que haya que leer. Ahora usan text-muted-foreground. En el teléfono y en modo oscuro, axe todavía marca etiquetas pequeñas del horario y de la clase con ese mismo tono (de 3.4 a 4.3:1); es lo siguiente que hay que alinear.

De sistema interno a producto

Eclipse UI nació dentro de Eclipse. Para que sirviera fuera de la app, tenía que dejar de ser parte de ella.

• Su propio repositorio. Separé Eclipse UI de la app en su propio repositorio, como gema de Rails (eclipse_ui). Eclipse la usa como una copia de solo lectura que se actualiza con un comando (bin/update_eclipse_ui), y unas pruebas impiden editarla dentro de la app. El pack de reservas (clase, horario, paquetes, reservación…) se quedó en Eclipse: es su ventaja frente a otros softwares para estudios.
• De documentación a página de producto. El sitio público pasó de ser documentación a ser página de producto, bajo la idea "Que tu app no se vea hecha por IA". Arriba, la misma página cambia sola entre las seis personalidades. El movimiento se puede pausar (WCAG 2.2.2) y no arranca solo si la persona pide movimiento reducido. Debajo siguen el catálogo, Sistema y Personalidades: una exportación estática con las demos funcionando sin servidor, que no publica el código de los componentes, solo cómo se usan.
• Fuera de Rails. Desde el sitio se descarga gratis, sin cuenta: el motor en un solo CSS (eclipse-ui.css) y, por personalidad, su theme.css, su shadcn.css y su DESIGN.md.
• El shadcn.css se mide. Lleva los valores de shadcn/ui medidos en un navegador real sobre el motor y convertidos a OKLCH. La razón es la misma que con el contraste: medir lo que pinta la pantalla en lugar de reimplementar el motor.
• El DESIGN.md es para la IA. Son instrucciones para que un agente de IA (Claude Code, Cursor) aplique la personalidad en cada pantalla: qué tokens usar, qué reglas seguir y qué haría que la app se viera hecha por IA.

Lo que aprendí

• Nombrar los rasgos fue más útil que agregar diales. Con "voz, forma, color, aire y ritmo", un dueño de estudio puede decir qué quiere cambiar sin hablar de CSS, y cada pedido cae en un dial concreto.
• Un guardián vale más que una regla en un documento. Las reglas de tokens y de contraste corren con las pruebas: un componente que las rompe no pasa, lo haya escrito una persona o una IA.
• La guía también es para la IA. La misma guía (docs/GUI.md) y unas instrucciones para el agente que escribe la UI hacen que el código nuevo salga ya con tokens, con física y accesible.
• Un design system interno se vuelve producto cuando sirve fuera de su app. Y hoy quien más necesita una personalidad de diseño es quien construye con IA.

Lo que sigue: llevar el panel del estudio (lo que el dueño usa todos los días) a Eclipse UI y probar en Safari y Firefox reales.

Cómo se midió: las capturas y axe 4.10.3 corrieron en Chromium con Playwright, a 1440 × 900 y 390 × 844, contra el commit 99cdd64 (antes de Eclipse UI) y contra main, con la misma base de datos. El conteo del código corre las reglas de Ui::Guardrails sobre las mismas vistas públicas en los dos commits (17 archivos antes; 19 después, porque dos parciales salieron de ellas). Los tiempos de los resortes simulan spring.js con su propio integrador y un recorrido de 100 px.

Relacionado

• Caso de estudio de Eclipse →
• Cómo construyo →