angela · documentación
Guía de diseño
Las reglas visuales y de accesibilidad de angela: color, tipografía, espaciado, forma, movimiento y cómo crear componentes nuevos.
Principios
- La plataforma primero. Antes de escribir un componente, busca el elemento nativo:
<dialog>,popover,<details>, validación de formularios,focusgroup. El CSS lo viste; el JS solo completa lo que falta. - Accesibilidad no negociable. WCAG 2.2 AA es el mínimo, no la meta. Todo se prueba con teclado, lector de pantalla, zoom al 200 %, alto contraste y movimiento reducido.
- El color comunica, no decora. El color solo indica intención o estado (marca, éxito, aviso, peligro, información) y nunca va solo: siempre con texto, ícono o forma.
- Menos es más. Una acción primaria por vista. Radios moderados. Sombras solo para lo que flota. Nada de cajas dentro de cajas.
- Móvil primero. Sin scroll horizontal en la página, objetivos táctiles de 44 px en pantallas táctiles, y diseños que se adaptan al espacio.
Color
Toda la paleta se calcula en OKLCH a partir de dos números por rol: el tono (0–360) y elcroma (0–0.2). Cada token tiene una luminosidad fija para claro y otra para oscuro, por eso el contraste no depende del tono que elijas: está verificado para cualquier tono y cualquier croma hasta 0.2.
:root {
--angela-brand-h: 262; --angela-brand-c: 0.17;
--angela-neutral-c: 0.012; /* el tono neutro sigue al de marca */
--angela-success-h: 150; --angela-warning-h: 65;
--angela-danger-h: 25; --angela-info-h: 235;
}Prueba tu paleta
Mueve los controles: se aplica a este recuadro, que parte de los valores por defecto de angela. Abajo ves los componentes en claro y en oscuro a la vez y el contraste real de los pares clave.
Claro
Atención
Tu plan vence en 3 días.
Escribe un correo válido.
Texto normal con un enlace y texto secundario.
Oscuro
Atención
Tu plan vence en 3 días.
Escribe un correo válido.
Texto normal con un enlace y texto secundario.
Contraste en claro
Contraste en oscuro
Tu CSS
Roles y tokens
Los componentes no usan colores sueltos: usan tokens semánticos. Las superficies y el texto derivan del rol neutral; cada rol de color tiene siete tokens. Un componente con tono lee --tone-* ydata-tone elige el rol.
Superficies y texto
- --color-canvas
- --color-surface
- --color-surface-sunken
- --color-surface-hover
- --color-text
- --color-text-muted
- --color-border
- --color-border-strong
- --color-focus
Marca brand
- --color-brand-solid
- --color-brand-solid-hover
- --color-brand-on-solid
- --color-brand-subtle
- --color-brand-subtle-hover
- --color-brand-border
- --color-brand-text
Neutral neutral
- --color-neutral-solid
- --color-neutral-solid-hover
- --color-neutral-on-solid
- --color-neutral-subtle
- --color-neutral-subtle-hover
- --color-neutral-border
- --color-neutral-text
Éxito success
- --color-success-solid
- --color-success-solid-hover
- --color-success-on-solid
- --color-success-subtle
- --color-success-subtle-hover
- --color-success-border
- --color-success-text
Aviso warning
- --color-warning-solid
- --color-warning-solid-hover
- --color-warning-on-solid
- --color-warning-subtle
- --color-warning-subtle-hover
- --color-warning-border
- --color-warning-text
Peligro danger
- --color-danger-solid
- --color-danger-solid-hover
- --color-danger-on-solid
- --color-danger-subtle
- --color-danger-subtle-hover
- --color-danger-border
- --color-danger-text
Información info
- --color-info-solid
- --color-info-solid-hover
- --color-info-on-solid
- --color-info-subtle
- --color-info-subtle-hover
- --color-info-border
- --color-info-text
Reglas de uso
solid+on-solid: la acción principal. Una por vista.subtle+text: fondos teñidos (avisos, etiquetas, botones soft).border: bordes que delimitan un control (contraste ≥ 3:1).--color-border(neutral) es solo decorativo: separadores y contornos de tarjetas.text-mutedcumple 4.5:1 en todas las superficies: úsalo para texto secundario, nunca para información crítica.- Para cambiar un token concreto, sobrescríbelo en
:root. Para tematizar una zona, pondata-angela-themeen el contenedor y redefine allí las variables--angela-*. - Para fijar el esquema en una zona (p. ej. un bloque de código siempre oscuro), usa
data-scheme="dark".
Tipografía
Fuente del sistema (--font-body) para rendimiento y familiaridad, y monoespaciada del sistema para código. Los tamaños grandes son fluidos. Interlineado de lectura 1.55 y medida máxima de 68 caracteres.
--fs-4xlTítulo de página--fs-3xlTítulo de sección--fs-2xlSubtítulo--fs-xlEncabezado menor--fs-lgTexto destacado--fs-mdTexto de lectura (16px)--fs-smControles y texto secundario--fs-xsEtiquetas y metadatosEspaciado
Escala en múltiplos de 4 px. La distancia entre una etiqueta y su control siempre es menor que la distancia entre grupos.
--space-1--space-2--space-3--space-4--space-5--space-6--space-8--space-12--space-16Forma y elevación
Radios moderados: --radius-lg en contenedores (tarjetas, diálogos, popovers) y --radius-md en controles. --radius-full solo para avatares, puntos de estado e interruptores.
La sombra solo indica que algo flota sobre la página. Todo componente elevado lleva además borde, porque en modo de alto contraste las sombras desaparecen.
Movimiento
- Duraciones cortas:
--duration-fast(120 ms) para estados y--duration-normal(200 ms) para entrar y salir. - Solo se animan opacidad, desplazamientos pequeños y tamaño. Nada que parpadee ni se mueva solo.
- Los desplazamientos y escalas van dentro de
@media (prefers-reduced-motion: no-preference); con movimiento reducido solo queda un fundido breve. - Las animaciones nunca retrasan el foco ni la interacción con teclado.
Compromisos de accesibilidad
- Contraste: texto ≥ 4.5:1 y bordes de controles, foco e indicadores ≥ 3:1, en claro y oscuro (
pnpm check:contrastlo verifica en todos los tonos). - Foco: siempre visible con
:focus-visible, anillo de 2 px y separación de 2 px. - Teclado: todo se opera con Tab, Mayús+Tab, Enter, Espacio, Esc y flechas donde el patrón lo pide.
- Objetivos: 40 px de alto en controles (44 px en pantallas táctiles), por encima de los 24 px de WCAG 2.5.8.
- Nombres: cada control tiene un nombre accesible que incluye su texto visible.
- Estado: nunca solo con color. Errores con texto e ícono; pestañas con subrayado; página actual con barra lateral.
- Preferencias del sistema:
prefers-color-scheme,prefers-reduced-motion,prefers-contrast: moreyforced-colors. - Idiomas: propiedades lógicas (
inline/block) para que todo funcione en escritura de derecha a izquierda.
Soporte de navegadores
Objetivo: Baseline “ampliamente disponible”. Las características más nuevas se usan como mejora progresiva, con una alternativa que mantiene el componente usable:
- Invoker Commands y Popover:
@angela-ui/angela/jscarga polyfills solo si el navegador no los tiene. - Anchor Positioning: sin soporte, el popover se muestra como hoja inferior.
- focusgroup: sin soporte,
<angela-tabs>implementa las flechas y el tabindex itinerante. - closedby="any": sin soporte,
@angela-ui/angela/jsañade el cierre al hacer clic fuera. - accent-color, field-sizing, interpolate-size, animaciones de salida: sin soporte se ve el control nativo, el textarea no crece solo o la transición es instantánea. Nada se rompe.
Cómo crear un componente nuevo
- Busca el elemento o la API nativa. Si no existe, consulta el patrón en las WAI-ARIA Authoring Practices.
- Escribe el CSS en
packages/angela/src/components/, dentro de@layer angela.components, con una clase base y atributosdata-*para variantes. Valores por defecto en:where(). - Usa solo tokens. Si necesitas un color nuevo, añádelo a la receta en
src/palette.jscon sus pares de contraste. - Propiedades lógicas,
:focus-visible, estados:disabled/aria-disabled,forced-colorsyprefers-reduced-motion. - JS solo si el HTML no basta: en
src/js/, sin dependencias, seguro en SSR y con prueba en Vitest. - Documenta ejemplos, API y notas de accesibilidad en
docs/src/data/components.js. - Prueba con teclado, lector de pantalla, zoom al 200 %, 320 px de ancho, alto contraste y movimiento reducido.