Principios

  1. 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.
  2. 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.
  3. 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.
  4. Menos es más. Una acción primaria por vista. Radios moderados. Sombras solo para lo que flota. Nada de cajas dentro de cajas.
  5. 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

Activo Nuevo

Atención

Tu plan vence en 3 días.

Escribe un correo válido.

Texto normal con un enlace y texto secundario.

Oscuro

Activo Nuevo

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-muted cumple 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, pon data-angela-theme en 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 metadatos

      Espaciado

      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-16

      Forma 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.

      sm
      md
      lg

      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.

      elevation-1
      elevation-2
      elevation-3

      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:contrast lo 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: more y forced-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/js carga 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/js añ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

      1. Busca el elemento o la API nativa. Si no existe, consulta el patrón en las WAI-ARIA Authoring Practices.
      2. Escribe el CSS en packages/angela/src/components/, dentro de @layer angela.components, con una clase base y atributos data-* para variantes. Valores por defecto en :where().
      3. Usa solo tokens. Si necesitas un color nuevo, añádelo a la receta en src/palette.js con sus pares de contraste.
      4. Propiedades lógicas, :focus-visible, estados :disabled/aria-disabled, forced-colors y prefers-reduced-motion.
      5. JS solo si el HTML no basta: en src/js/, sin dependencias, seguro en SSR y con prueba en Vitest.
      6. Documenta ejemplos, API y notas de accesibilidad en docs/src/data/components.js.
      7. Prueba con teclado, lector de pantalla, zoom al 200 %, 320 px de ancho, alto contraste y movimiento reducido.