bootstrap-utility-api

Bootstrap 6 ユーティリティ API

Bootstrap が提供するすべてのユーティリティクラスは、1 つの Sass マップ $utilities から生成されます。各エントリには、クラスのファミリーごとに、設定するプロパティ、受け付ける値、生成するバリアントが記述されています。ユーティリティをカスタマイズするには、CSS を書くのではなく、このマップを編集します。

ワークフロー

• 手順 1：生成の仕組みを理解する
• 手順 2：ユーティリティ定義を読む
• 手順 3：ユーティリティを追加する
• 手順 4：デフォルトのユーティリティを変更、名前変更、または削除する
• 手順 5：レスポンシブ、状態、印刷、ダークのバリアントを生成する
• 手順 6：カスタムプロパティと高度なセレクターを使って値を組み合わせる
• 手順 7：生成される CSS を削減する
• 手順 8：Bootstrap 自体にユーティリティを追加する
• 手順 9：検証する

---

手順 1：生成の仕組みを理解する

scss/utilities/_api.scss が生成の全工程を担います。

@include generate-utility-at-properties($utilities);

@layer utilities {
  @include generate-utilities-loop($utilities, $breakpoints);
}

作業を始める前に、知っておくべき重要な点が 3 つあります。

• ユーティリティはカスケードレイヤーの最後に配置されるため、!important を使わなくてもコンポーネントのスタイルに優先します。important: true を指定したグループだけが !important を追加します。
• **@property の登録はレイヤーの外で行われます。**ユーティリティが設定するカスタムプロパティ（--bg、--fg、--bc、--rounded-size、…）はすべて syntax: "*"; inherits: false で登録されるため、.border-inverse を適用しても、組み合わせた値が子孫要素に漏れません。カスタムプロパティを設定する新しいユーティリティも、自動的にこの処理の対象になります。
• マップは bootstrap ではなく config モジュールで設定します。$utilities は scss/_config.scss で宣言され、scss/_utilities.scss（@use "config" as * で config を読み込みます）でのみ 値が追加 されます。間違ったモジュールを設定するとエラーになります。

// Does NOT work — "This variable was not declared with !default in the @used module."
@use "bootstrap/scss/bootstrap" with (
  $utilities: (…)
);

// Works — configure config first, then load Bootstrap
@use "bootstrap/scss/config" with (
  $utilities: (…)
);
@use "bootstrap/scss/bootstrap";

同じことは、_config.scss にあるすべての変数（$radius、$spacers、$breakpoints、$zindex-levels）にも当てはまります。bootstrap.scss が転送するパーシャルで宣言された変数（$root-tokens、$colors、$blue）は、bootstrap で直接設定できます。

---

手順 2：ユーティリティ定義を読む

グループはマップです。最も簡単な形式では、2 つのキーが必要です。

"overflow": (
  property: overflow,
  values: auto hidden visible scroll,
),

generate-utility() によって検証されるすべてのオプションは次のとおりです。

キー	必須	説明
property	はい	プロパティ名、スペース区切りのプロパティ名リスト、またはプロパティと値のペアのマップ
values	はい	リスト（クラスのサフィックスは値と同じ）またはマップ（キーがサフィックスになります。null キーの場合はサフィックスを省略します）
class	いいえ	プロパティ名の代わりに使うクラス名
selector	いいえ	class（デフォルト）、attr-starts、または attr-includes
child-selector	いいえ	子孫セレクター。詳細度をゼロにするため :where() で囲みます
variables	いいえ	出力するカスタムプロパティ。静的な値のマップ、またはそれぞれにユーティリティの値が設定されるリスト
state	いいえ	生成する疑似クラスのバリアント（例：hover focus）
responsive	いいえ	ブレークポイントごとにクラスを生成します（デフォルトは false）
print	いいえ	print: が先頭に付くクラスを生成します（デフォルトは false）
dark	いいえ	prefers-color-scheme: dark 内に dark: が先頭に付くクラスを生成します（デフォルトは false）
important	いいえ	!important を追加します（デフォルトは false）
enabled	いいえ	false にすると、定義を残したまま出力を抑制します（デフォルトは true）

ジェネレーターは処理を進めながら検証するため、誤りをすぐに見つけられます。property または values がない場合は致命的な @error になり、responsive がブール値以外の場合も致命的な @error になります。キー名に誤字がある場合は、有効なキーの一覧を示す @warn が出ます。

---

手順 3：ユーティリティを追加する

マップは Bootstrap のデフォルト設定とマージされるため、新しい定義だけを渡します。

@use "bootstrap/scss/config" with (
  $utilities: (
    "cursor": (
      property: cursor,
      class: cursor,
      responsive: true,
      values: auto pointer grab,
    ),
  )
);
@use "bootstrap/scss/bootstrap";

これにより、.cursor-auto、.cursor-pointer、.cursor-grab に加え、.sm:cursor-* から .2xl:cursor-* までのクラスが生成されます。

値の形式によってクラス名が決まります。

// List — suffix is the value itself: .cursor-pointer
values: auto pointer grab,

// Map — keys become suffixes: .tint-brand
values: (brand: var(--purple-500), muted: var(--gray-200)),

// null key — no suffix at all: .shout
values: (null: uppercase),

---

ステップ 4：デフォルトのユーティリティを変更、名前変更、または削除する

マージは浅い処理です。既存のグループキーを指定すると、そのグループ全体が置き換えられます。残りを省略してオプションを1つだけ上書きすると、明確なエラーになります —

// Errors: "Utility is missing required `property` key"
"overflow": (
  responsive: true,
  values: visible hidden scroll auto,
),

そのため、scss/_utilities.scss から定義全体をコピーし、変更を加えてください。

@use "bootstrap/scss/config" with (
  $utilities: (
    // Make overflow responsive
    "overflow": (
      property: overflow,
      values: auto hidden visible scroll,
      responsive: true,
    ),
    // Remove a family entirely
    "width": null,
    // Rename .ms-* to v4-style .ml-*: drop the original, add a replacement
    "margin-start": null,
    "margin-start-alias": (
      property: margin-inline-start,
      class: ml,
      responsive: true,
      values: (0: 0, 1: var(--spacer-1), 2: var(--spacer-2), auto: auto),
    ),
  )
);
@use "bootstrap/scss/bootstrap";

最後のグループにある CSS トークンに注目してください。config を設定するファイルからは、Bootstrap の Sass メンバーを参照できません。$spacers、$negative-spacers、map-merge-multiple() などのヘルパーはまだスコープ内にないため、値を CSS トークン（スペーサーのスケールに連動する var(--spacer-2) など）またはリテラルとして再記述してください。

定義をコピーせずに既存のファミリーを拡張するには、同じ class を再利用する新しいグループを登録します。

"width-extra": (
  property: width,
  class: w,
  responsive: true,
  values: (10: 10%, 15: 15%),
),

これにより、Bootstrap の .w-25 … .w-100 に .w-10 と .w-15 が追加されます。元のグループを変更する Bootstrap の更新後もそのまま利用できるため、通常はこちらの方法がおすすめです。

定義をマップ内に表示したままにしたい場合（共有設定でグループを文書化しつつ、意図的に無効にする場合など）は、null ではなく enabled: false を使用してください。

---

ステップ 5：レスポンシブ、状態、印刷、ダークのバリアントを生成する

v6 では、インフィックスやサフィックスではなくプレフィックスを使用します。4種類すべてのバリアントをベースクラス名と組み合わせられます。

オプション	生成されるクラス	備考
responsive: true	.md:cursor-pointer	$breakpoints のキーごとに1回処理され、CSS では .md\: として記述されます
state: hover focus	.hover:cursor-pointer	セレクターは .hover\:cursor-pointer:hover です
print: true	.print:d-none	@media print 内に記述されます
dark: true	.dark:bg-black	@media (prefers-color-scheme: dark) 内に記述されます

responsive と state は組み合わせられ、.md:hover:cursor-pointer が生成されます。各バリアントによって生成される CSS が増えるため、グローバルではなくグループごとに有効化してください。

---

ステップ 6：カスタムプロパティと高度なセレクターで値を組み立てる

色関連のユーティリティの多くは、プロパティを直接設定しません。ローカルのカスタムプロパティを割り当ててから使用します。これにより、不透明度の設定や合成が可能になります。

"tint": (
  property: (
    "--tint": null,
    "background-color": var(--tint),
  ),
  class: tint,
  values: (brand: var(--purple-500)),
),

プロパティマップ内の null 値は「ユーティリティの値を受け取る」ことを意味し、それ以外のエントリーは記述どおりに出力されます。上記からは次のように生成されます。

.tint-brand {
  --tint: var(--purple-500);
  background-color: var(--tint);
}

関連する仕組み：

• variables は追加のカスタムプロパティを出力します。マップの場合、グループ内の各クラスに静的な値が設定されます。リストの場合、各プロパティがユーティリティの値を受け取ります。
• プロパティマップとマップ値。 property がマップで、values のエントリー自体がプロパティ名をキーとするマップの場合、各プロパティはそれぞれ独自の値を選択します。異なる値で複数の関連プロパティを設定するグループに便利です。
• selector: attr-starts / attr-includes はクラスではなく [class^="…"] / [class*="…"] を対象にし、class キーが必要です。Bootstrap はこれを使い、.ratio-16x9 から --ratio を介して aspect-ratio に値を渡します。
• child-selector はルールを :where() で囲みます。たとえば :where(.stack-gap-1 > *) のようになります。詳細度がゼロなので、子要素自身のスタイルが引き続き優先されます。

カスタムプロパティ名は Sass ではプレフィックスなしで記述します。Bootstrap の dist および CDN の CSS では PostCSS が --bs- を追加するため、ソースを自分でコンパイルすると、プレフィックスなしのままになります。

---

ステップ 7：生成される CSS を削減する

ユーティリティは Bootstrap の CSS の中で最も大きな割合を占めます。削減するにはマップを編集するのが最も手軽です。

1. コンポーネントが不要な場合は、ユーティリティのみのエントリーポイントから始めます。

   @use "bootstrap/scss/config" with ($utilities: (…));
   @use "bootstrap/scss/bootstrap-utilities";
   

2. ミニファイやパージ処理に頼るのではなく、使わないグループを null（または enabled: false）に設定します。

3. 1つのブレークポイントでしか使わないグループでは responsive をオフにします。レスポンシブグループは自身のコピーが6つ生成されます。

4. グループ全体を削除するのではなく、必要なステップが少数の場合は values マップを絞り込みます。

Lightning CSS やパージ処理を含む全体像については、最適化を参照してください。

---

ステップ 8：Bootstrap 自体にユーティリティを追加する

プロジェクトではなくフレームワークにユーティリティを追加する場合：

1. $utilities マップ内の関連するグループの近くにグループを追加し、// scss-docs-start utils-<name> / // scss-docs-end utils-<name> マーカーで囲みます。
2. ユーティリティが不透明度やテーマカラーと連携する必要がある場合は、カスタムプロパティを介して合成することを優先し、リテラル値ではなく既存のトークン値（$spacers、$util-opacity、theme-color-refs()）を再利用します。
3. site/src/content/docs/utilities/ 内の対応するページに、<ScssDocs name="utils-<name>" file="scss/_utilities.scss" /> を使って定義を表示する形でドキュメントを追加します。ページを新規作成した場合は、site/data/sidebar.yml にもエントリーを追加します。
4. フィクスチャーマップを使ってジェネレーターミックスインを直接呼び出す scss/tests/utilities/_api.test.scss にテストを追加します。
5. npm run css を実行します。その css-docs ステップで、ドキュメントが読み込む dist/css/bootstrap-utilities.metadata.json が再生成されるため、変更と一緒にコミットします。

---

ステップ 9：検証する

1. npm run css-lint を実行し、続いて npm run css を実行します。
2. コンパイル済み CSS で、エスケープされたバリエーション（\.md\\:cursor-pointer）も含め、想定したクラスを Grep し、削除したものが残っていないことを確認します。
3. 新しいカスタムプロパティがファイル先頭の @property ブロックに表示されていることを確認します。見つからない場合、そのユーティリティでは property または variables を介して割り当てられていません。
4. Sass の出力で、未知のキーに関する @warn 行を確認します。オプションの入力ミスが気付かれないまま無視されていることを、最もすばやく判別できます。
5. ブラウザーで詳細度を確認します。ユーティリティは !important を使わず、レイヤーの順序だけでコンポーネントのスタイルを上書きできる必要があります。