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 的公共外壳，或 utils 的 tooltip/overlay，就像第 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 推导）。需要精确色调时再定义完整的族。

……或者在开放 map 里预先定义（Sass）

若使用 Sass，请在引入这个包之前用 $hub-accents-extra 扩展开放的强调色 map。只有 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）

一个用于局部主题化的混入：只把改动以 map 传进去，它就按规范名称输出变量。挂在每个令牌下的一切——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 的开放 map，整个族由对 map.keys($hub-accents) 的 @each 推导而来。所以加一个颜色（或者九个）是统一的，也没有样板代码：map 里的每个键都会自动获得自己的族。

// 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 变量就能完成换主题和新增强调色。map 加混入是内部机制，向这个包贡献代码时才有用。

结构层 · 令牌实时预览

除了颜色，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-*

混入与样式

ds 的 Sass API：消费规范令牌的辅助工具——不写死间距，也不写死颜色。用命名空间引入：@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、间距、尺寸、定位、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（四边）

按轴的 padding · .px-* / .py-*

Margin · .m-1…5（放在参照框里看）

按轴的 margin · .mx-* / .my-*

响应式 · .col-md-6 · .d-lg-none · .p-sm-3

移动优先的变体（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); }

速查表