ng-hub-ui-ds

Was es ist und wofür es da ist

Seine Aufgabe ist es, die Stilvariablen über alle Bibliotheken der Familie hinweg zu vereinheitlichen und zu verdrahten. Jede Bibliothek wird über --hub-*-Variablen thematisiert, definiert sie aber nicht: sie konsumiert sie. Dieses Paket ist die einzige Quelle der Wahrheit, die sie verbindet, sodass:

• Eine einzige Palette panels, forms, calendar, board… gleichzeitig speist.
• Sie einmal umthematisieren (ein Token) und die Änderung die ganze Familie erreicht.
• Dark Mode und 8 Themes bereitstehen, umschaltbar über ein Attribut.
• Sie es auch in Ihrem eigenen CSS verwenden, sodass Ihre UI zu den Komponenten passt.

Die Verdrahtung wird Bibliothek für Bibliothek ausgerollt: weiter unten, unter der Familie, steht der Integrationsstand jeder einzelnen. Sie suchen den vollständigen Token-Katalog? Er steht in der Token-Referenz.

Erste Schritte

Der ganze Weg: was zu installieren ist, was wo importiert wird und welcher Mechanismus zu welcher Änderung gehört. ds hat keine Abhängigkeiten (reines CSS/SCSS) und gibt nichts aus, solange Sie es nicht importieren.

1 · Installieren

ds ist die Basis; fügen Sie die Bibliotheken der Familie hinzu, die Sie nutzen. Keine davon definiert die Palette — alle konsumieren die Tokens von ds.

npm install ng-hub-ui-ds
npm install ng-hub-ui-panels ng-hub-ui-forms …   # the ones you use

2 · Importieren — einmal, in der Wurzel, und in dieser Reihenfolge

/* styles.scss (application root) */

/* 1 · Tokens — ALWAYS, exactly once: the base the whole family consumes */
@use 'ng-hub-ui-ds/styles/tokens/hub-tokens';

/* 2 · Native-element reset — only if your app does not ship one already (Bootstrap Reboot…) */
@use 'ng-hub-ui-ds/styles/base/reset';

/* 3 · Utilities — opt-in: import only the sheets you use
      (Bootstrap-exact names: do NOT load them next to a global Bootstrap) */
@use 'ng-hub-ui-ds/styles/utilities/layout';
@use 'ng-hub-ui-ds/styles/utilities/text';
@use 'ng-hub-ui-ds/styles/utilities/surfaces';

/* 4 · Sheets of their own shipped by some libraries — once, path documented by each README */
@use 'ng-hub-ui-forms/styles' as hub-forms;  // shared forms chrome
@use 'ng-hub-ui-utils/styles/tooltip';       // utils tooltip

/* 5 · Mixins — when you build your own components with the same system */
@use 'ng-hub-ui-ds' as hub;
.page { @include hub.center($max: xl); }

Es geht auch ohne Sass: jede Datei hat ihren kompilierten .css-Zwilling — @import 'ng-hub-ui-ds/styles/tokens/hub-tokens.css'; — oder über angular.json:

"styles": [
  "node_modules/ng-hub-ui-ds/styles/tokens/hub-tokens.css",
  "src/styles.scss"
]

3 · Ändern — welcher Mechanismus für welche Änderung

4 · Und die übrigen Bibliotheken

Mit geladenen Tokens gibt es nichts mehr zu konfigurieren: jedes ng-hub-ui-* liest --hub-sys-* und thematisiert sich mit Ihren Overrides selbst um. Zusätzlich stellt jede Komponente --hub-<komponente>-*-Hooks zur Feinjustierung bereit, und einige Bibliotheken bringen eigene Stylesheets mit, die einmal neben den Tokens importiert werden — den genauen Pfad dokumentiert jede README (etwa das gemeinsame Chrome von forms oder Tooltip/Overlay von utils, wie im Block aus Schritt 2). Der Integrationsstand jeder Bibliothek steht unter der Familie.

Architektur: die zwei Schichten

Goldene Regel: Komponenten referenzieren ausschließlich sys-Tokens; die sys zeigen auf die ref. Ein sys zu ändern thematisiert um; ein ref zu ändern justiert die Basispalette.

Semantische Farben · Themes live

Das Set ist offen: 9 Varianten von Haus aus (5 chromatische + 4 neutrale) plus die, die Sie hinzufügen. Jeder Akzent stellt eine gleichförmige Rollenfamilie bereit — subtle, border-subtle, emphasis und das Kontrastpaar on. Wechseln Sie das Theme und sehen Sie zu, wie sich die ganze Palette umfärbt.

Bauen Sie Ihr Theme · ändern Sie nur die Basisfarben

Definieren Sie nur die Basisfarbe jeder semantischen Familie. Der Rest (subtle, border-subtle, emphasis, on) wird automatisch abgeleitet mit color-mix / relative color — und die Komponenten unten thematisieren sich live um, was die gemeinsame Verdrahtung in Aktion zeigt.

.my-theme {
  /* define ONLY the base colour of each family */
  --hub-sys-color-primary: #6d28d9;

  /* the rest derives at runtime with color-mix / relative color — nothing to maintain */
  --hub-sys-color-primary-subtle:        color-mix(in oklch, var(--hub-sys-color-primary) 12%, var(--hub-sys-surface-page));
  --hub-sys-color-primary-border-subtle: color-mix(in oklch, var(--hub-sys-color-primary) 35%, var(--hub-sys-surface-page));
  --hub-sys-color-primary-emphasis:      color-mix(in oklch, var(--hub-sys-color-primary) 80%, var(--hub-sys-color-ink));
  --hub-sys-color-primary-on:            oklch(from var(--hub-sys-color-primary) clamp(0, (0.62 - l) * 1000, 1) 0 h);
}

Die Familie · Integrationsstand

Die ganze Familie liest diese Tokens. Das Badge sagt, ob eine Bibliothek bereits an --hub-sys-* verdrahtet ist (sie thematisiert sich mit dem Design-System um) oder noch aussteht (wir kümmern uns später darum). Klicken Sie eine an, um ihre Beispiele zu sehen.

Wie man es ändert

1. Ein Token überschreiben (CSS) — der Hauptweg

Jeder Wert ist eine CSS-Variable, also ist Umthematisieren eine Zeile und kaskadiert in die ganze Familie:

:root {
  --hub-sys-color-primary: #7c3aed;
  --hub-sys-color-primary-subtle: #ede9fe;
  --hub-sys-color-primary-emphasis: #5b21b6;
}

2. Einen eigenen Akzent hinzufügen

Definieren Sie eine --hub-sys-color-<name>-Familie, und die Komponenten, die eine semantische Variante akzeptieren, greifen sie unverändert auf. Probieren Sie es hier live aus:

:root {
  --hub-sys-color-brand: #9333ea;
  --hub-sys-color-brand-subtle: #f3e8ff;
  --hub-sys-color-brand-border-subtle: #d8b4fe;
  --hub-sys-color-brand-emphasis: #6b21a8;
}

<!-- in any component that accepts a semantic variant -->
<hub-panel appearance="alert" variant="brand">Brand alert</hub-panel>

--hub-sys-color-brand allein genügt bereits (die Komponenten leiten den Rest mit color-mix ab). Definieren Sie die volle Familie, wenn Sie exakte Farbtöne wollen.

… oder legen Sie ihn in der offenen Map fest (Sass)

Wenn Sie Sass nutzen, erweitern Sie die offene Akzent-Map vor dem Einbinden des Pakets, mit $hub-accents-extra. Neu kompiliert wird nur ds — nie die Bibliotheken — und jede neue Variante bekommt ihre volle Familie (subtle · border-subtle · emphasis · on):

// Add your own variants — this recompiles the ds only, never the libraries.
@use 'ng-hub-ui-ds/styles/tokens/hub-tokens' with (
  $hub-accents-extra: (
    brand:    #ff6b00,
    accent:   #00b8d9,
    tertiary: #9c36b5
  )
);
// brand · accent · tertiary get subtle · border-subtle · emphasis · on automatically.

3. Ein eigenes Theme anlegen

[data-theme='corporate'] {
  --hub-sys-color-primary: #0033a0;
  --hub-sys-surface-page: #fbfcff;
  --hub-sys-text-primary: #0a1f44;
  /* …the rest of the tokens that differ from the base */
}

4. …oder alles auf einmal mit hub.theme() (Sass)

Ein einziges Mixin für partielles Theming: übergeben Sie ihm nur die Änderungen als Maps, und es gibt die Variablen unter ihrem kanonischen Namen aus. Alles, was an einem Token hängt — sys-Aliase, Rollenfamilien, Utilities, Komponenten — leitet sich entlang der var()-Kette von selbst neu ab:

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

/* change ONLY spacing step 3 — gap-3, .p-3, sys-gap-3, components… all move with it */
:root { @include hub.theme($space: (3: 1.25rem)); }

/* or a whole theme, scopeable to [data-theme] or to a subtree */
[data-theme='compact'] {
  @include hub.theme(
    $space: (3: 0.75rem, 4: 1rem),
    $radius: (md: 0.25rem),
    $accents: (primary: #0f766e, brand: #ff6b00)
  );
}

SCSS-Funktionen: wie es innen erzeugt wird

Die semantischen Farbfamilien werden nicht von Hand geschrieben: das Akzent-Set ist eine offene Map mit !default, und die Familie wird über ein @each auf map.keys($hub-accents) abgeleitet. Deshalb ist eine Farbe (oder neun) hinzuzufügen gleichförmig und frei von Boilerplate: jeder Schlüssel der Map bekommt seine Familie automatisch.

// The accent set is an OPEN map with !default — add as many as you want.
$hub-accents: (
  primary: …, secondary: …, success: …, danger: …, warning: …,
  info: …, neutral: …, light: …, dark: …
) !default;

// The family is derived ONCE in :root, iterating EVERY key of the map,
// so any accent you add gets its family for free.
@mixin hub-color-derive() {
  @each $name in map.keys($hub-accents) {
    --hub-sys-color-#{$name}-subtle:   color-mix(in oklch, var(--hub-sys-color-#{$name}) 12%, var(--hub-sys-surface-page));
    --hub-sys-color-#{$name}-emphasis: color-mix(in oklch, var(--hub-sys-color-#{$name}) 80%, var(--hub-sys-color-ink));
    --hub-sys-color-#{$name}-on:       oklch(from var(--hub-sys-color-#{$name}) clamp(0, (0.62 - l) * 1000, 1) 0 h);
  }
}

In den meisten Fällen müssen Sie das SCSS nicht anfassen: das Überschreiben von CSS-Variablen deckt Umthematisieren und neue Akzente ab. Map und Mixin sind die interne Mechanik, nützlich, wenn Sie zum Paket beitragen.

Strukturelle Schicht · Tokens live

Über die Farbe hinaus definiert ds eine kanonische strukturelle Schicht: Spacing-Skala (--hub-ref-space-*), Sizing und Bruchteile (--hub-sys-size-*), Grid (--hub-sys-grid-columns, Gutters) und eine semantische gap-Skala (--hub-sys-gap-*). Alles unten wird gezeichnet, indem diese Variablen konsumiert werden.

Spacing-Skala · --hub-ref-space-0…7

Gap-Skala · --hub-sys-gap-0…5

Breitenbruchteile · --hub-sys-size-*

Grid auto-fit + Container-Breiten

/* Canonical structural tokens (ref → sys) */
gap: var(--hub-sys-gap-3);                  /* spacing scale */
padding-inline: var(--hub-ref-space-4);
max-width: var(--hub-sys-container-max-width-lg);
grid-template-columns: repeat(var(--hub-sys-grid-columns), minmax(0, 1fr));

/* Layout mixins */
@use 'ng-hub-ui-ds' as hub;
.page    { @include hub.center($max: xl); }
.toolbar { @include hub.cluster($gap: 2); }
.cards   { @include hub.grid($min: 16rem, $gap: 3); }

/* Opt-in utilities (Bootstrap naming, 3 sheets) */
@use 'ng-hub-ui-ds/styles/utilities/layout';    // .d-flex .gap-3 .ms-auto .position-* .ratio-*
@use 'ng-hub-ui-ds/styles/utilities/text';      // .fs-3 .fw-bold .text-truncate .text-muted
@use 'ng-hub-ui-ds/styles/utilities/surfaces';  // .bg-* .border .rounded .shadow .opacity-*

Mixins und Styles

Die Sass-API von ds: Helfer, die die kanonischen Tokens konsumieren — ohne eingebackenes Spacing oder Farbe. Sie werden mit Namespace eingebunden, @use 'ng-hub-ui-ds' as hub. Die Utility-Stylesheets sind aus denselben Mixins gebaut, ein Verhalten zu ändern oder zu erweitern heißt also, sich mit dem Mixin die eigene Klasse zu prägen. Jede Demo unten ist aus dem echten Mixin gebaut; der vollständige Katalog steht am Ende.

Jedes Mixin hat eine gleichwertige Utility; die Demos unten konsumieren die echte Klasse von ds (.cluster, .stack…) — diese Seite wendet kein Mixin erneut an.

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

.toolbar { @include hub.cluster($gap: 2); }          // a row that wraps
.feed    { @include hub.stack($gap: 3); }            // a column
.cards   { @include hub.grid($min: 8rem, $gap: 2); } // auto-fit grid
.page    { @include hub.center($max: sm); }          // centred wrapper

Vollständiger Katalog

Utilities

Opt-in-Klassen, die dieselbe Schicht umhüllen, unter Namen, die exakt denen von Bootstrap entsprechen — ein Drop-in-Ersatz, aber laden Sie diese Stylesheets NICHT zusammen mit einem globalen Bootstrap im selben Dokument. Drei Stylesheets: layout (display/flex, grid, spacing, sizing, position, helpers — diese Abschnitte), text (Abschnitt „Text“) und surfaces (Abschnitt „Flächen“). Die Demo nutzt die echten Klassen:

// three opt-in sheets — import only the ones you use
@use 'ng-hub-ui-ds/styles/utilities/layout';    // layout, spacing, position, helpers
@use 'ng-hub-ui-ds/styles/utilities/text';      // typography and text
@use 'ng-hub-ui-ds/styles/utilities/surfaces';  // backgrounds, borders, radii, shadows

<div class="cluster gap-2"> … </div>
<div class="grid-auto gap-2"> … </div>
<div class="w-50">half</div>
<div class="vh-100 min-vh-100">viewport height</div>

Flexbox

Vollständiger Satz an Display- und Flexbox-Utilities, mit der exakten Nomenklatur von Bootstrap. Die Demos nutzen die echten Klassen von ds.

justify-content · .justify-content-* — Hauptachse

align-items · .align-items-* — Querachse

flex-direction · .flex-column

flex-fill / flex-grow-0 — wachsen und fixieren

Responsive · .flex-md-row · .align-items-md-center

Die ganze Flex-Familie hat Varianten je Breakpoint. Spalte auf dem Handy, zentrierte Zeile ab md — ändern Sie die Fenstergröße:

Vertikaler Trenner · .vr

<!-- display + direction / wrap -->
<div class="d-flex flex-wrap gap-2"> … </div>
<div class="d-flex flex-column"> … </div>

<!-- main axis (justify) and cross axis (align) -->
<div class="d-flex justify-content-between align-items-center"> … </div>

<!-- grow / pin -->
<div class="d-flex gap-2">
  <span class="flex-fill">grows</span>
  <span class="flex-grow-0">fixed</span>
</div>

<!-- responsive: a column on mobile, a top-aligned row from md up -->
<div class="d-flex flex-column flex-md-row align-items-md-start"> … </div>

<!-- vertical divider -->
<div class="d-flex gap-3">left <span class="vr"></span> right</div>

Spalten, Breiten und Spacing

Ein 12-Spalten-Raster (.row + .col-1…12 + .offset-1…11, gesteuert von --hub-sys-grid-columns), Breiten und gerichtetes Padding/Margin. Jede Demo nutzt die echten Utilities.

Spalten · .row + .col-N

Offsets · .offset-N

Die Zelle beginnt auf Track n + 1 desselben Rasters (grid-column-start); mit Breakpoint .offset-md-8, und .offset-md-0 setzt auf automatische Platzierung zurück.

Breiten · .w-25 / 50 / 75 / 100 / auto

Padding · .p-1…5 (alle 4 Seiten)

Padding je Achse · .px-* / .py-*

Margin · .m-1…5 (innerhalb eines Bezugsrahmens)

Margin je Achse · .mx-* / .my-*

Responsive · .col-md-6 · .d-lg-none · .p-sm-3

Mobile-First-Varianten (sm 576 · md 768 · lg 992 · xl 1200 · xxl 1400) für Display, Spalten und Offsets, Spacing, Gap und die ganze Flex-Familie (.flex-md-row, .justify-content-md-center, .align-items-md-start, .order-lg-*…). Ändern Sie die Fenstergröße — diese Zellen sind .col-12 .col-md-6 .col-xl-3:

<!-- mobile-first: 1 column → 2 at ≥768px → 4 at ≥1200px -->
<div class="row">
  <div class="col-12 col-md-6 col-xl-3">…</div>
</div>
<div class="d-none d-lg-flex">desktop only</div>
<section class="p-2 p-md-4">padding that grows with the viewport</section>

// breakpoints as a mixin — for any other utility or your own CSS
@use 'ng-hub-ui-ds' as hub;
@include hub.media-breakpoint-up(md) { .sidebar { width: 18rem; } }

<!-- 12-column grid: every row adds up to 12 -->
<div class="row">
  <div class="col-6">col-6</div>
  <div class="col-6">col-6</div>
</div>
<div class="row">
  <div class="col-4">col-4</div>
  <div class="col-4">col-4</div>
  <div class="col-4">col-4</div>
</div>

<!-- offset: .col-4.offset-8 starts on track 9 (offset-{bp}-0 resets it) -->
<div class="row">
  <div class="col-4 offset-md-8">col-4 offset-md-8</div>
</div>

<!-- widths · directional padding and margin -->
<div class="w-50">w-50</div>
<div class="p-3">1rem of padding on all four sides</div>
<div class="px-4 py-2">padding-inline 1.5rem · padding-block .5rem</div>
<div class="mx-3">margin-inline 1rem</div>

Text

Typografie- und Text-Utilities unter der exakten Nomenklatur von Bootstrap, gebaut auf den Typografie-Mixins (hub.font-size(), hub.font-weight(), hub.text-color()…): jeder Wert löst zu Tokens auf, das Überschreiben des Tokens thematisiert die Utilities also um — und mit den Mixins prägen Sie sich eigene Varianten.

Größe · .fs-1…6 · Headings · .h1…6

.fs-* ändert nur die Größe; .h1…6 wendet die komplette Typografie einer Überschrift an (Größe + Fettung + enger Zeilenabstand + Abstand) ohne die Semantik — ein <div class="h5"> liest sich wie ein <h5>:

Schnitt · .fw-* · Stil · .fst-italic

Ausrichtung · .text-start / .text-center / .text-end

Transform · Dekoration · Familie

Tabellenziffern · .font-tabular-nums

Proportionale Ziffern geben jeder Ziffer ihre eigene Breite, eine 1 ist also schmaler als eine 0, und die Einer zweier Beträge landen an verschiedenen Stellen. Eine Geldspalte liest man, indem man nach unten vergleicht: schauen Sie, wo das Dezimaltrennzeichen auf jeder Seite steht.

Kürzung · .text-truncate

Zeilenabstand · .lh-1 / .lh-sm / .lh-base / .lh-lg

Farben · .text-primary … .text-muted

Textdeckkraft · .text-opacity-* · Links · .link-*

// import the sheet once
@use 'ng-hub-ui-ds/styles/utilities/text';

<h2 class="fs-3 fw-semibold">Headline</h2>
<p class="text-muted lh-lg">Secondary copy with generous leading</p>
<span class="text-uppercase fw-medium">label</span>
<td class="text-end font-monospace">1.234,56 €</td>
<p class="text-truncate" style="max-width: 16rem">Truncated with an ellipsis…</p>

// …or mint variants of your own with the mixins
@use 'ng-hub-ui-ds' as hub;
.card__title { @include hub.font-size(4); @include hub.font-weight(semibold); }
.card__meta  { @include hub.text-color(muted); @include hub.text-truncate(); }

Flächen

Hintergründe, Rahmen, Radien, Schatten und Deckkraft unter der exakten Nomenklatur von Bootstrap, gebaut auf den Flächen-Mixins (hub.bg(), hub.text-bg(), hub.radius(), hub.shadow()…) und den Tokens --hub-sys-color-* / --hub-sys-radius-* / --hub-sys-shadow-*.

Hintergründe · .bg-* und .bg-*-subtle

Hintergrund + garantierter Kontrast · .text-bg-*

Rahmen · .border · .border-{variant} · .border-1…5

Radien · .rounded-0…3 · .rounded-pill · .rounded-circle

Schatten · .shadow-sm / .shadow / .shadow-lg

Deckkraft · .opacity-* (Element) · .bg-opacity-* (nur Hintergrund)

// import the sheet once
@use 'ng-hub-ui-ds/styles/utilities/surfaces';

<hub-badge color="success">active</hub-badge>
<div class="bg-warning-subtle border border-warning rounded-3 p-3">notice</div>
<div class="bg-body rounded shadow-lg p-4">raised card</div>

// …or mint variants of your own with the mixins
@use 'ng-hub-ui-ds' as hub;
.card        { @include hub.bg(body); @include hub.radius(lg); @include hub.shadow(sm); }
.card--brand { @include hub.text-bg(brand); }  // any accent of the open map

Position und Helfer

Position/Inset, Overflow, Order, Float, Sichtbarkeit, z-index, object-fit und Interaktionen — dazu die Verhaltens-Helfer (.visually-hidden, .stretched-link, .ratio-*, .clearfix). Alles unter der exakten Nomenklatur von Bootstrap.

Position · .position-* + .top/.start/.translate-middle

Ratio · .ratio .ratio-16x9

Overflow · Interaktion · seitliches Spacing

Fokusring · .focus-ring

Ein Fokusring, gesteuert von den Tokens --hub-sys-focus-ring-* — klicken Sie oder drücken Sie Tab:

Barrierefreiheit · .visually-hidden

Dieser Absatz enthält einen Text, der visuell verborgen, aber von Screenreadern angesagt wird: nur für assistive Technik (inspizieren Sie das DOM, um ihn zu sehen).

<!-- badge positioned over the corner of its container -->
<div class="position-relative">
  …
  <span class="position-absolute top-0 start-100 translate-middle text-bg-danger rounded-pill px-2">9+</span>
</div>

<!-- media at a fixed ratio -->
<div class="ratio ratio-16x9"><iframe src="…"></iframe></div>

<!-- whole card clickable + screen-reader-only text -->
<div class="position-relative">
  <a href="…" class="stretched-link">See more<span class="visually-hidden"> about surfaces</span></a>
</div>

<!-- push with auto margins inside a flex row -->
<nav class="d-flex gap-2"><span>logo</span><a class="ms-auto">login</a></nav>

Brücken zu anderen Systemen

Opt-in-Mixins, die hub mit dem vorhandenen Framework verbinden. Null Kosten, wenn Sie sie nie aufrufen. Zwei Richtungen über $mode: adopt (hub übernimmt das Theme des Hosts) und project (hub projiziert sein Theme auf den Host).

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

/* "I have Bootstrap and I want hub to adopt its palette" */
:root { @include hub.bridge-bootstrap($mode: adopt); }

/* "I want to tint Material and Tailwind with MY hub theme" */
:root { @include hub.bridge-material($mode: project); }
:root { @include hub.bridge-tailwind($mode: project); }

Kurzreferenz