Convenciones

Calidad

Los guardianes automáticos que mantienen todo alineado.

Un design system se cuida solo o se deshace solo. Cada regla que importa tiene un guardián: una prueba que corre con bin/rails test y que falla con un mensaje que dice qué arreglar y dónde. Así el componente 51 sale igual que los otros 50 sin que nadie lo revise a ojo.

Los guardianes

La columna «estado» mira el disco al pintar la página: un guardián en camino aparece como activo el día que llega su prueba.

GuardiánQué vigilaEstado
Fichas del catálogo test/components/ui/catalog_test.rb Cada ficha completa: categoría conocida, demo, tagline, archivos que existen en carpetas permitidas, YAML sin trampas, status: válido, pattern: y keyboard:. Que «estable» sea verdad lo comprueba la app que usa la gema, con Ui::Catalog.app_usages sobre sus vistas. Activo
Páginas del catálogo test/controllers/ui_controller_test.rb Que abran el índice, cada ficha (con su escenario y sus pestañas de código) y cada página de Sistema. Activo
Cada componente test/components/ui/*_component_test.rb Lo que pinta cada pieza: su ARIA, sus variantes y sus estados. Hoy 47 de 47 componentes tienen la suya. Activo
Contraste test/eclipse_ui/contrast_test.rb Mide en Chromium los 22 pares de config/eclipse_ui/contrast.yml en 14 escenarios (cada personalidad y theme.css, en claro y oscuro) y falla si alguno baja de 4.5:1. Sin navegador se salta en tu máquina, pero en CI falla. Activo
Tokens test/eclipse_ui/tokens_test.rb Prohíbe en los componentes y sus CSS los colores sueltos (hex, gray-*, white, black), [var(--color-*)] donde hay utilidad, text-[Npx], rounded sin sufijo y las sombras de Tailwind. Las excepciones viven en Ui::Guardrails::ALLOWED, cada una con su motivo. Activo
Íconos test/components/ui/icon_component_test.rb El set único de Ui::Icons: un nombre que no existe falla con una sugerencia, y ningún <svg> se pega a mano en componentes ni demos (los gráficos animados van en su lista). Activo
Descargas test/eclipse_ui/kit_test.rb Lo que se descarga de Personalidades: eclipse-ui.css sin nada de Tailwind, cada theme.css igual al que se copia, shadcn.css con lo que de verdad pinta el motor (medido en Chromium) y DESIGN.md nombrando solo tokens y clases que existen. Activo
Vocabulario test/components/ui/vocabulary_test.rb Ui::Vocabulary: los alias de tono, variante y tamaño, y que un valor desconocido falle en desarrollo y pruebas. Activo
Estilo de Ruby .rubocop.yml RuboCop omakase en todo el Ruby: bin/rubocop. Activo

El guardián de tokens, contado hoy

Recorre los 127 archivos de app/components/ui y de los CSS de componentes cada vez que abres esta página, con las mismas reglas que la prueba. Lo que no está en la lista de excepciones hace fallar bin/rails test.

ReglaFuera de reglaPermitidasEn su lugar
hex 0 5 un token: bg-primary, text-foreground…
paleta 0 0 bg-card, bg-muted, bg-destructive/10…
sombra de Tailwind 0 0 shadow-subtle, shadow-elevated o shadow-[var(--shadow-md)] (siguen el dial)
texto en px 0 0 la escala: text-3xs … text-base
rounded sin sufijo 0 0 rounded-sm (sigue el dial de redondez)
token a mano 0 0 la utilidad con nombre: bg-muted en lugar de bg-[var(--color-muted)]
color con nombre 0 0 var(--color-…)
rgb/hsl fijo 0 0 var(--color-…) o color-mix con un token

Las excepciones, y por qué

Cada una dice qué la justifica. Si el motivo deja de existir, la prueba pide quitarla.

ArchivoReglaPor qué
components/ui/color_field_component.rb hex Dato, no estilo: el blanco contra el que se calcula el contraste WCAG del color elegido.
components/ui/color_field_component.rb hex Dato: la tinta de carbón contra la que se calcula el contraste.
components/ui/color_field_component.rb hex Texto de ejemplo del campo hex (lo que la persona escribiría).
components/ui/color_field_component.html.erb hex Valor inicial del <input type=color> nativo, que solo acepta hex.
assets/tailwind/eclipse_ui/date_range_picker.css hex Una máscara solo lee el alfa: el color no se ve.

Cómo correrlos

Todo corre local y sin servicios: la base de pruebas y, para el contraste, el Chromium que ya usa el repo.

Terminal

# Todo el sistema: componentes, fichas, páginas y contraste
bin/rails test test/components test/controllers/ui_controller_test.rb test/eclipse_ui

# Solo las fichas (rápido: córrelo cada vez que edites un .yml)
bin/rails test test/components/ui/catalog_test.rb

# Un componente
bin/rails test test/components/ui/slide_to_confirm_component_test.rb

# Estilo del Ruby que tocaste
bin/rubocop app/components/ui test/components/ui
  • Cuándo: antes de cada commit que toque app/components/ui, una ficha, un CSS de eclipse_ui o una personalidad.
  • CI corre la suite completa con CI=true: ahí ningún guardián se puede saltar.
  • Lo que las pruebas no ven (cómo se siente un resorte, si un texto suena a Eclipse) va en la lista de abajo.

Cuando uno falla

  • Lee el mensaje completo. Cada guardián dice la ficha, el archivo o el par de colores, y qué cambiar («dice estable pero ninguna vista usa Ui::…», «entrecomilla el nombre de la prop»).
  • Arregla la causa, no el guardián. Si una regla de verdad no aplica, la excepción va en su lista con el motivo al lado, en el mismo cambio, para que se revise.
  • Si falla algo que no tocaste, probablemente es trabajo en curso de alguien más: avísale en lugar de borrarlo.

Antes de dar por terminado un componente

La revisión que ninguna prueba hace por ti. Si una línea no se cumple, el componente no está.

API

  • Usa los nombres del vocabulario: tone:, variant:, size:, slots with_*, eventos componente:verbo.
  • Acepta **attrs en la raíz y suma class:; normaliza tono, variante y tamaño con Ui::Vocabulary, así un valor desconocido falla en desarrollo.
  • Si es de dominio, recibe el modelo y no consulta; si es un control, manda su valor con name: o form: + attribute:.

Visual

  • Solo tokens, la escala de texto, radios con nombre y sombras del dial; íconos del set.
  • Se ve bien en carbón claro y oscuro, eclipse y umbra, y a 375px sin scroll horizontal.
  • La demo usa contenido real de estudio y luce en la tarjeta de 330px y en el escenario grande.

Movimiento

  • Lo que se arrastra, sigue al cursor o cambia de forma usa eclipse_ui/spring; lo demás, duraciones y curvas con nombre.
  • Con movimiento reducido y con el dial en 0 se queda quieto y sigue funcionando.

Accesibilidad

  • El patrón de su ficha está completo: roles, estados ARIA y todas sus teclas.
  • Pasa las listas de teclado y lector de pantalla.
  • Sin JavaScript queda algo usable.

Contenido

  • Sus textos por defecto siguen la voz de Eclipse: tú, mayúscula de oración, botones con verbo.

Entrega

  • Ficha con status: beta, pattern: y keyboard:; su prueba propia; los guardianes en verde y RuboCop limpio.
  • La consola del navegador sin errores en la ficha y en el índice.
  • docs/GUI.md al día si agregaste un componente, un token o un parámetro del vocabulario.