Theming

El modelo mental

Los componentes nunca traen colores «a fuego»: leen tokens. Hay dos capas — --hub-ref-* (primitivas: escala de espaciado, radios, tipografía) y --hub-sys-* (semánticas: primary, success, danger…). Cada componente cuelga de ellas por la cadena var(). Por eso personalizar el design system re-tona el ecosistema entero, sin tocar cada librería.

• Un acento → toda su familia de rol (-subtle / -emphasis / -on) se recalcula en runtime con color-mix.
• Un token de referencia (un paso de espaciado, un radio) → cada alias, utilidad y componente que lo usa se re-deriva.
• Runtime vs compile-time: colores/spacers/radios/tipografía son variables CSS (runtime, con hub.theme). Los breakpoints y qué pasos de utilidad existen son compile-time (las media queries no admiten var()).

1 · Tus packs en runtime — hub.theme(...)

Importa el ds una vez y pásale solo los overrides que quieras como mapas. El mixin hace @each por dentro y emite los --hub-* canónicos; lo que no pasas conserva el valor base.

@use 'ng-hub-ui-ds' as hub;

// Tu pack de marca
$brand: (
  primary: #0f766e,
  brand:   #14b8a6,
  success: #15803d,
  danger:  #b91c1c
);

:root {
  @include hub.theme(
    $accents: $brand,                          // → --hub-sys-color-*  (familia -subtle/-emphasis/-on por color-mix)
    $space:   (2: 0.375rem, 3: 0.75rem, 4: 1.25rem),  // → --hub-ref-space-*
    $radius:  (md: 0.5rem, lg: 1rem),                 // → --hub-ref-radius-*
    $font-family: (base: 'Inter, system-ui, sans-serif')
  );
}

El resultado: un solo pack re-tona todos los componentes a la vez. Cambia de pack y observa cómo botones, badges y la superficie siguen los mismos tokens (colores y radios):

2 · Compile-time — @use … with (…)

Lo que no puede ser una variable CSS se configura por el sistema de módulos: los breakpoints (regeneran las utilidades responsive con @each $bp in $hub-breakpoints), acentos extra registrados en compilación, o qué pasos existen.

@use 'ng-hub-ui-ds' as hub with (
  $hub-breakpoints:   (sm: 576px, md: 768px, lg: 1200px, xl: 1600px),
  $hub-accents-extra: (brand: #ff6b00)
);

3 · Tu propio bucle sobre los mixins de cada lib

Además del theming global, cada librería expone su mixin hub-<lib>-theme. Recorre tu pack con @each para acuñar variantes por-componente en una sola pasada:

@use 'ng-hub-ui-badges/styles' as badges;

$brand: (teal: #0f766e, sunset: #ff6b00, plum: #7c3aed);

@each $name, $hex in $brand {
  .badge--#{$name} {
    @include badges.hub-badge-theme($accent: $hex);
  }
}

4 · Multi-tema y scoped

hub.theme se puede aplicar en :root, en un bloque [data-theme] o scopeado a cualquier subárbol; compone con los tokens base y con otros temas.

@use 'ng-hub-ui-ds' as hub;

[data-theme='compact'] {
  @include hub.theme(
    $space:  (3: 0.5rem, 4: 0.75rem),
    $radius: (md: 0.25rem)
  );
}

Y por componente

Para ajustar una sola librería en un sitio concreto, cada una documenta su mixin y sus variables en su pestaña Estilos. La referencia completa de tokens vive en Tokens, y el paquete base en Design System.