ng-hub-ui-ds

これは何で、何のためのものか

役割は、ファミリーすべてのライブラリにまたがるスタイル変数をそろえ、つなぐことです。各ライブラリは --hub-* 変数でテーマ付けされますが、それを定義はしません。消費するだけです。このパッケージはそれらを結ぶ唯一の真実の源であり、その結果:

• ひとつのパレットが panels、forms、calendar、board… を同時に養います。
• テーマ変更は一度だけ（トークンひとつ）で、変更がファミリー全体に届きます。
• ダークモードと 8 テーマが用意され、属性ひとつで切り替わります。
• 自分の CSS でも使えるので、あなたの UI がコンポーネントとそろいます。

接続はライブラリ単位で進めています。下のファミリーに、それぞれの統合状況があります。トークンの全一覧をお探しですか。トークンリファレンスにあります。

はじめに

全体の道筋です。何をインストールし、何をどこに読み込み、どの変更にどの仕組みを使うか。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-<component>-* フックを公開し、いくつかのライブラリはトークンの隣で一度だけ読み込む独自のシートを持ちます — 正確なパスは各 README が記しています（たとえば forms の共通クロームや utils のツールチップ/オーバーレイ。手順 2 のブロックにあるとおりです）。各ライブラリの統合状況はファミリーにあります。

アーキテクチャ: 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 変数なので、テーマの変更は 1 行で済み、ファミリー全体にカスケードします。

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

2. 自分のアクセントを足す

--hub-sys-color-<name> のファミリーを定義すると、セマンティックバリアントを受け取るコンポーネントがそのまま拾います。ここで試せます:

: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 付きの開かれたマップで、ファミリーは map.keys($hub-accents) に対する @each で導出されます。だから色を 1 つ（あるいは 9 つ）足す作業は一様で、定型コードがありません。マップのどのキーも自動的に自分のファミリーを得ます。

// 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 は正規の構造レイヤーも定義します。spacing のスケール（--hub-ref-space-*）、サイズと分数（--hub-sys-size-*）、グリッド（--hub-sys-grid-columns、ガター）、そしてセマンティックな gap のスケール（--hub-sys-gap-*）です。以下はすべてこれらの変数を消費して描かれています。

spacing のスケール · --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 です。正規のトークンを消費するヘルパーで、spacing も色も焼き込みません。@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 を両方読み込まないでください。シートは 3 つ。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>

カラム、幅、spacing

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、カラムとオフセット、spacing、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 より細く、2 つの金額の一の位がずれた場所に来ます。金額の列は上下に見比べて読むものです。左右で小数点がどこに来るか見てください。

省略 · .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 · 操作 · 左右の spacing

フォーカスリング · .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 で 2 方向あります。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); }

早見表