ng-hub-ui-ds

Что это и зачем нужно

Её задача — привести к одному виду и связать переменные стилей во всех библиотеках семейства. Каждая библиотека оформляется переменными --hub-*, но не определяет их: она их потребляет. Этот пакет — единственный источник истины, который их соединяет, так что:

• Одна палитра питает panels, forms, calendar, board… одновременно.
• Вы меняете тему один раз (один токен), и изменение доходит до всего семейства.
• Тёмный режим и 8 тем готовы и переключаются одним атрибутом.
• Вы используете её и в своём собственном CSS, поэтому ваш интерфейс совпадает с компонентами.

Связывание раскатывается библиотека за библиотекой: ниже, в разделе семейство, показано состояние интеграции каждой. Ищете полный каталог токенов? Он в справочнике токенов.

Первые шаги

Весь путь: что установить, что и где импортировать и каким механизмом пользоваться для каждого изменения. У ds нет зависимостей (чистый CSS/SCSS), и он ничего не выводит, пока вы его не импортируете.

1 · Установить

ds — это основа; добавьте те библиотеки семейства, которыми пользуетесь. Ни одна из них не определяет палитру — все потребляют токены ds.

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

2 · Импортировать — один раз, в корне и в этом порядке

/* 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); }

Работает и без Sass: у каждого файла есть скомпилированный двойник .css — @import 'ng-hub-ui-ds/styles/tokens/hub-tokens.css'; — или через angular.json:

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

3 · Изменять — какой механизм для чего

4 · И остальные библиотеки

С загруженными токенами настраивать больше нечего: каждая ng-hub-ui-* читает --hub-sys-* и сама меняет тему вслед за вашими переопределениями. Кроме того, каждый компонент открывает хуки --hub-<компонент>-* для тонкой настройки, а некоторые библиотеки приносят собственные файлы стилей, подключаемые один раз рядом с токенами — точный путь описан в README каждой из них (например, общий каркас forms или tooltip/overlay из utils, как в блоке шага 2). Состояние интеграции каждой библиотеки — в разделе семейство.

Архитектура: два слоя

Золотое правило: компоненты ссылаются только на токены sys; sys указывают на ref. Изменение sys меняет тему; изменение ref правит базовую палитру.

Семантические цвета · темы вживую

Набор открытый: 9 вариантов по умолчанию (5 цветных + 4 нейтральных) плюс те, что добавите вы. Каждый акцент открывает единообразное семейство ролей — subtle, border-subtle, emphasis и контрастную пару on. Переключите тему и посмотрите, как перекрашивается вся палитра.

Соберите свою тему · меняйте только базовые цвета

Задайте только базовый цвет каждого семантического семейства. Остальное (subtle, border-subtle, emphasis, on) выводится автоматически через color-mix / relative color — а компоненты ниже перекрашиваются вживую, и это и есть общая связка в действии.

.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);
}

Семейство · состояние интеграции

Всё семейство читает эти токены. Значок говорит, связана ли библиотека с --hub-sys-* (тогда она меняет тему вместе с дизайн-системой) или ещё ожидает (займёмся ею позже). Нажмите на любую, чтобы посмотреть её примеры.

Как это изменить

1. Переопределить токен (CSS) — основной путь

Каждое значение — это CSS-переменная, поэтому смена темы умещается в одну строку и каскадом уходит во всё семейство:

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

2. Добавить собственный акцент

Определите семейство --hub-sys-color-<имя>, и компоненты, принимающие семантический вариант, подхватят его без изменений. Попробуйте прямо здесь:

: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 (остальное компоненты выведут через color-mix). Определяйте семейство целиком, когда нужны точные оттенки.

… или задайте его заранее в открытой карте (Sass)

Если вы используете Sass, расширьте открытую карту акцентов перед подключением пакета — через $hub-accents-extra. Пересобирается только ds — никогда не библиотеки — и каждый новый вариант получает полное семейство (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. Создать собственную тему

[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. …или всё сразу через hub.theme() (Sass)

Единственный миксин частичной темизации: передайте ему только изменения в виде карт, и он выведет переменные под каноническими именами. Всё, что висит на каждом токене — псевдонимы sys, семейства ролей, утилиты, компоненты — пересчитается само по цепочке var():

@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: как это устроено внутри

Семейства семантических цветов не пишутся вручную: набор акцентов — это открытая карта с !default, а семейство выводится через @each по map.keys($hub-accents). Поэтому добавить один цвет (или девять) — единообразно и без шаблонного кода: каждый ключ карты получает своё семейство автоматически.

// 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);
  }
}

В большинстве случаев трогать SCSS не нужно: переопределения CSS-переменных хватает и для смены темы, и для новых акцентов. Карта и миксин — внутренняя механика, полезная, если вы вносите вклад в пакет.

Структурный слой · токены вживую

Помимо цвета ds задаёт канонический структурный слой: шкалу отступов (--hub-ref-space-*), размеры и доли (--hub-sys-size-*), сетку (--hub-sys-grid-columns, жёлобы) и семантическую шкалу gap (--hub-sys-gap-*). Всё, что ниже, нарисовано на этих переменных.

Шкала отступов · --hub-ref-space-0…7

Шкала gap · --hub-sys-gap-0…5

Доли ширины · --hub-sys-size-*

Сетка auto-fit + ширины контейнера

/* 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-*

Миксины и стили

Sass-API ds: помощники, которые потребляют канонические токены — без зашитых отступов и цветов. Импортируются с пространством имён: @use 'ng-hub-ui-ds' as hub. Файлы утилит собраны из этих же миксинов, поэтому изменить или расширить поведение — значит завести свой класс на миксине. Каждая демонстрация ниже построена на настоящем миксине; полный каталог — в конце.

У каждого миксина есть равнозначная утилита; демонстрации ниже используют настоящий класс ds (.cluster, .stack…) — эта страница не применяет миксины повторно.

@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

Полный каталог

Утилиты

Подключаемые по желанию классы поверх того же слоя, с именами, в точности совпадающими с Bootstrap — прямая замена, но не подключайте эти файлы И глобальный Bootstrap в одном документе. Три файла: layout (display/flex, grid, spacing, sizing, position, helpers — эти разделы), text (раздел «Текст») и surfaces (раздел «Поверхности»). Демонстрация использует настоящие классы:

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

Полный набор утилит display и flexbox с точной номенклатурой Bootstrap. Демонстрации используют настоящие классы ds.

justify-content · .justify-content-* — главная ось

align-items · .align-items-* — поперечная ось

flex-direction · .flex-column

flex-fill / flex-grow-0 — растягивать и фиксировать

Адаптивность · .flex-md-row · .align-items-md-center

У всего семейства flex есть варианты по брейкпоинтам. Колонка на телефоне, центрированная строка начиная с md — измените размер окна:

Вертикальный разделитель · .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>

Колонки, ширины и отступы

Сетка из 12 колонок (.row + .col-1…12 + .offset-1…11, управляемая --hub-sys-grid-columns), ширины и направленные padding/margin. Каждая демонстрация использует настоящие утилиты.

Колонки · .row + .col-N

Смещения · .offset-N

Ячейка начинается на дорожке n + 1 той же сетки (grid-column-start); с брейкпоинтом — .offset-md-8, а .offset-md-0 возвращает автоматическое размещение.

Ширины · .w-25 / 50 / 75 / 100 / auto

Padding · .p-1…5 (все 4 стороны)

Padding по осям · .px-* / .py-*

Margin · .m-1…5 (внутри опорной рамки)

Margin по осям · .mx-* / .my-*

Адаптивность · .col-md-6 · .d-lg-none · .p-sm-3

Mobile-first варианты (sm 576 · md 768 · lg 992 · xl 1200 · xxl 1400) для display, колонок и смещений, отступов, gap и всего семейства flex (.flex-md-row, .justify-content-md-center, .align-items-md-start, .order-lg-*…). Измените размер окна — эти ячейки описаны как .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>

Текст

Утилиты типографики и текста с точной номенклатурой Bootstrap, построенные на типографских миксинах (hub.font-size(), hub.font-weight(), hub.text-color()…): каждое значение разрешается в токены, поэтому переопределение токена меняет тему и у утилит — а с миксинами вы заводите собственные варианты.

Размер · .fs-1…6 · заголовки · .h1…6

.fs-* меняет только размер; .h1…6 применяет всю типографику заголовка (размер + жирность + плотный интерлиньяж + отступ) без семантики — <div class="h5"> читается как <h5>:

Насыщенность · .fw-* · начертание · .fst-italic

Выравнивание · .text-start / .text-center / .text-end

Transform · оформление · семейство

Табличные цифры · .font-tabular-nums

Пропорциональные цифры дают каждой цифре свою ширину, поэтому 1 уже, чем 0, и единицы двух сумм оказываются в разных местах. Колонку с деньгами читают сравнением сверху вниз: посмотрите, где стоит десятичный разделитель с каждой стороны.

Усечение · .text-truncate

Интерлиньяж · .lh-1 / .lh-sm / .lh-base / .lh-lg

Цвета · .text-primary … .text-muted

Прозрачность текста · .text-opacity-* · ссылки · .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(); }

Поверхности

Фоны, рамки, радиусы, тени и прозрачность с точной номенклатурой Bootstrap, построенные на миксинах поверхностей (hub.bg(), hub.text-bg(), hub.radius(), hub.shadow()…) и токенах --hub-sys-color-* / --hub-sys-radius-* / --hub-sys-shadow-*.

Фоны · .bg-* и .bg-*-subtle

Фон + гарантированный контраст · .text-bg-*

Рамки · .border · .border-{variant} · .border-1…5

Радиусы · .rounded-0…3 · .rounded-pill · .rounded-circle

Тени · .shadow-sm / .shadow / .shadow-lg

Прозрачность · .opacity-* (элемент) · .bg-opacity-* (только фон)

// 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/inset, overflow, order, float, видимость, z-index, object-fit и взаимодействия — плюс поведенческие помощники (.visually-hidden, .stretched-link, .ratio-*, .clearfix). Всё с точной номенклатурой Bootstrap.

Позиция · .position-* + .top/.start/.translate-middle

Пропорции · .ratio .ratio-16x9

Overflow · взаимодействие · боковые отступы

Кольцо фокуса · .focus-ring

Кольцо фокуса, управляемое токенами --hub-sys-focus-ring-* — нажмите или используйте Tab:

Доступность · .visually-hidden

В этом абзаце есть текст, скрытый визуально, но озвучиваемый программами чтения с экрана: только для вспомогательных технологий (посмотрите DOM, чтобы его увидеть).

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

Мосты к другим системам

Подключаемые по желанию миксины, связывающие hub с тем фреймворком, который уже есть. Нулевая цена, если вы их не вызываете. Два направления через $mode: adopt (hub перенимает тему хоста) и project (hub проецирует свою тему на хост).

@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); }

Краткий справочник