bootstrap-customize

Bootstrap 5.3 のカスタマイズ

Bootstrap 5.3 では、Sass 変数、CSS カスタムプロパティ、組み込みのカラーモードを含む包括的なテーマシステムを使って、高度なカスタマイズができます。

カスタマイズ方法

1. CSS 変数（実行時のカスタマイズ）

Bootstrap のドキュメントではこれらを「CSS 変数」（技術的には CSS カスタムプロパティ）と呼んでいます。任意の階層で上書きすれば、再コンパイルせずにスタイルを変更できます。

/* Global override */
:root {
  --bs-primary: #0074d9;
  --bs-primary-rgb: 0, 116, 217;
  --bs-body-font-family: 'Inter', sans-serif;
}

/* Component-level override */
.my-card {
  --bs-card-bg: #f0f0f0;
  --bs-card-border-color: transparent;
}

/* Local scope override */
.custom-button {
  --bs-btn-bg: #custom-color;
  --bs-btn-border-color: #custom-color;
  --bs-btn-hover-bg: #darker-custom;
}

CSS 変数のプレフィックス

Bootstrap をほかのフレームワークと併用するプロジェクトで競合を避けるには、$prefix Sass 変数を使って bs- プレフィックスをカスタマイズします。

$prefix: "myapp-"; // Results in --myapp-primary, --myapp-body-bg, etc.

2. Sass 変数（コンパイル時）

包括的なテーマ設定を行うには、Bootstrap をインポートする前に Sass 変数を上書きします。

// 1. Include functions first
@import "bootstrap/scss/functions";

// 2. Override default variables
$primary: #0074d9;
$secondary: #7fdbff;
$font-family-base: 'Inter', sans-serif;
$border-radius: 0.5rem;
$enable-shadows: true;

// 3. Import Bootstrap
@import "bootstrap/scss/bootstrap";

順序が重要です： 変数は、関数の後、ほかの Bootstrap のインポートより前に設定する必要があります。

カラーシステム

テーマカラー

Sass マップと CSS プロパティで定義された、8 つのデフォルトテーマカラーです。

$theme-colors: (
  "primary":   $primary,
  "secondary": $secondary,
  "success":   $success,
  "info":      $info,
  "warning":   $warning,
  "danger":    $danger,
  "light":     $light,
  "dark":      $dark
);

カスタムカラーの追加

// Add to theme-colors map
$custom-colors: (
  "custom": #900,
  "brand": #1a73e8
);

// Merge with defaults
$theme-colors: map-merge($theme-colors, $custom-colors);

これにより、.bg-custom、.text-brand、.btn-custom など、すべてのユーティリティが生成されます。

ダークモードに対応したカラーの追加

$theme-colors にカラーを追加するだけでは、アラート、バッジ、リストグループの適切なダークモード用スタイルは生成されません。追加のマップでバリエーションを定義してください。

// Light mode variants
$theme-colors-text: map-merge($theme-colors-text, ("custom": #712cf9));
$theme-colors-bg-subtle: map-merge($theme-colors-bg-subtle, ("custom": #e1d2fe));
$theme-colors-border-subtle: map-merge($theme-colors-border-subtle, ("custom": #bfa1fc));

// Dark mode variants
$theme-colors-text-dark: map-merge($theme-colors-text-dark, ("custom": #e1d2f2));
$theme-colors-bg-subtle-dark: map-merge($theme-colors-bg-subtle-dark, ("custom": #8951fa));
$theme-colors-border-subtle-dark: map-merge($theme-colors-border-subtle-dark, ("custom": #e1d2f2));

これらの定義がないと、*-text-emphasis、*-bg-subtle、*-border-subtle のパターンを使うコンポーネントは、ダークモードで正しく表示されません。

カラーの削除

$theme-colors: map-remove($theme-colors, "info", "light");

警告： primary、success、danger のキーは必須であり、削除できません。これらは、リンク、フォームの検証、その他のコンポーネントに関する Bootstrap のコアスタイルで使用されます。削除すると、Sass のコンパイルエラーが発生します。

削除しても安全： secondary、info、warning、light、dark

削除不可： primary、success、danger

カラーモード（ダーク／ライト）

Bootstrap 5.3 には、組み込みのダークモード対応が含まれています。

カラーモードを有効にする

<html> または任意の要素に data-bs-theme 属性を設定します。

<html lang="en" data-bs-theme="light">


<html lang="en" data-bs-theme="dark">


<div data-bs-theme="dark">
  <div class="card">Dark card in light page</div>
</div>

JavaScript による切り替え

const toggleTheme = () => {
  const html = document.documentElement;
  const current = html.getAttribute('data-bs-theme');
  html.setAttribute('data-bs-theme', current === 'dark' ? 'light' : 'dark');
};

// With system preference
const prefersDark = window.matchMedia('(prefers-color-scheme: dark)');
document.documentElement.setAttribute('data-bs-theme',
  prefersDark.matches ? 'dark' : 'light'
);

// Listen for system changes
prefersDark.addEventListener('change', (e) => {
  document.documentElement.setAttribute('data-bs-theme',
    e.matches ? 'dark' : 'light'
  );
});

カラーモードの実装方式

Bootstrap では、カラーモードを切り替えるための 2 つの方式に対応しています。これらは $color-mode-type Sass 変数で制御します。

データ属性方式（デフォルト）

$color-mode-type: data;

HTML 要素の data-bs-theme 属性を使用します。

<html data-bs-theme="dark">

メリット：

• コンポーネントごとにテーマを設定できます
• ユーザー設定でシステム設定を上書きできます
• JavaScript によるテーマ切り替えに対応しています
• ページを再読み込みせずに実行時に切り替えられます

使用する場面： テーマ選択 UI を作成する場合や、個々のコンポーネントを細かく制御する必要がある場合に使用します。

メディアクエリー方式

$color-mode-type: media-query;

prefers-color-scheme メディアクエリーを自動的に使用します。

@media (prefers-color-scheme: dark) {
  /* Dark mode styles applied automatically */
}

メリット：

• システム設定を自動的に検出します
• JavaScript が不要です
• 実装が簡単です
• 実行時のオーバーヘッドがありません

デメリット：

• コンポーネントごとの制御はできません
• ユーザーが UI から設定を上書きできません
• ページ単位のテーマ設定のみが必要です

使用する場面： 手動切り替えを設けずに、システム設定を自動的に検出したい場合に使用します。

カスタムカラーモードのカラー

light と dark 以外に、独自のカラーモードを定義できます。references/sass-variables.md にある [data-bs-theme="blue"] を使用した完全な「ブルーテーマ」の例を参照してください。

モードごとにカラーを上書きします。

// Light mode colors
:root,
[data-bs-theme="light"] {
  --bs-body-bg: #ffffff;
  --bs-body-color: #212529;
}

// Dark mode colors
[data-bs-theme="dark"] {
  --bs-body-bg: #1a1a2e;
  --bs-body-color: #e1e1e1;
  --bs-primary: #6ea8fe;
}

Sass 関数

Bootstrap には、色の操作とアクセシビリティのためのユーティリティ関数があります。

• tint-color($color, $weight) - 白を混ぜて明るくします
• shade-color($color, $weight) - 黒を混ぜて暗くします
• shift-color($color, $weight) - 重みの符号に応じて、自動で明るくするか暗くします
• color-contrast($color) - 背景に対してアクセシブルなコントラストカラーを取得します

// Generate color scale
$primary-light: tint-color($primary, 40%);
$primary-dark: shade-color($primary, 20%);

// Auto-contrast text
.custom-badge {
  background-color: $success;
  color: color-contrast($success); // Returns #fff or #212529
}

// Hover states
.btn-custom:hover {
  background-color: shift-color($brand, 15%);
}

その他の関数：SVG 背景用の escape-svg()、安全な CSS の calc 操作用の add()／subtract() があります。

関数とミックスインの完全なリファレンスは、references/sass-functions-mixins.md を参照してください。

主な Sass 変数

タイポグラフィ

$font-family-base: system-ui, -apple-system, sans-serif;
$font-family-monospace: SFMono-Regular, Menlo, monospace;
$font-size-base: 1rem;
$font-size-sm: $font-size-base * 0.875;
$font-size-lg: $font-size-base * 1.25;
$font-weight-normal: 400;
$font-weight-bold: 700;
$line-height-base: 1.5;
$headings-font-family: null; // Inherits $font-family-base
$headings-font-weight: 500;

余白

$spacer: 1rem;
$spacers: (
  0: 0,
  1: $spacer * 0.25,  // 0.25rem
  2: $spacer * 0.5,   // 0.5rem
  3: $spacer,         // 1rem
  4: $spacer * 1.5,   // 1.5rem
  5: $spacer * 3      // 3rem
);

角丸

$border-radius: 0.375rem;
$border-radius-sm: 0.25rem;
$border-radius-lg: 0.5rem;
$border-radius-xl: 1rem;
$border-radius-xxl: 2rem;
$border-radius-pill: 50rem;

オプションフラグ

$enable-caret: true;
$enable-rounded: true;
$enable-shadows: false;
$enable-gradients: false;
$enable-transitions: true;
$enable-reduced-motion: true;
$enable-smooth-scroll: true;
$enable-grid-classes: true;
$enable-container-classes: true;
$enable-negative-margins: false;
$enable-dark-mode: true;
$color-mode-type: data; // 'data' or 'media-query'

フォーカスリング

Bootstrap 5.3 では、すべてのコンポーネントの :focus スタイルをカスタマイズする変数が用意されています。

$focus-ring-width: .25rem;
$focus-ring-opacity: .25;
$focus-ring-color: rgba($primary, $focus-ring-opacity);
$focus-ring-blur: 0;
$focus-ring-box-shadow: 0 0 $focus-ring-blur $focus-ring-width $focus-ring-color;

コンポーネントのカスタマイズ

ボタンのカスタマイズ

// Global button variables
$btn-padding-y: 0.5rem;
$btn-padding-x: 1rem;
$btn-font-size: 1rem;
$btn-border-radius: $border-radius;

// Per-variant customization via CSS
.btn-primary {
  --bs-btn-bg: #0074d9;
  --bs-btn-border-color: #0074d9;
  --bs-btn-hover-bg: #0063b8;
  --bs-btn-hover-border-color: #005aa3;
  --bs-btn-active-bg: #005aa3;
  --bs-btn-active-border-color: #00518f;
}

カードのカスタマイズ

$card-spacer-y: 1rem;
$card-spacer-x: 1rem;
$card-border-width: 1px;
$card-border-radius: $border-radius;
$card-border-color: rgba(0, 0, 0, 0.125);
$card-bg: $white;
$card-cap-bg: rgba(0, 0, 0, 0.03);

フォームのカスタマイズ

$input-padding-y: 0.375rem;
$input-padding-x: 0.75rem;
$input-font-size: 1rem;
$input-border-radius: $border-radius;
$input-border-color: $gray-400;
$input-focus-border-color: tint-color($primary, 50%);
$input-focus-box-shadow: 0 0 0 0.25rem rgba($primary, 0.25);

コンポーネントのアーキテクチャ

Bootstrap は、コンポーネントのスタイル設定にベース・モディファイアパターンを使用しています。このアーキテクチャを理解すると、既存のコンポーネントをカスタマイズし、シームレスに統合できる新しいコンポーネントを作成しやすくなります。

ベースクラスとモディファイアクラス

コンポーネントはコアとなるスタイルを提供するベースクラスから始まり、モディファイアクラスでバリエーションを追加します。

<button class="btn">Base button</button>


<button class="btn btn-primary">Primary</button>
<button class="btn btn-lg">Large</button>
<button class="btn btn-primary btn-lg">Primary Large</button>

@each ループによるバリエーションの生成

Bootstrap は $theme-colors を反復処理して、カラーのバリエーションを生成します。

// How Bootstrap generates .alert-primary, .alert-danger, etc.
@each $state in map-keys($theme-colors) {
  .alert-#{$state} {
    --#{$prefix}alert-color: var(--#{$prefix}#{$state}-text-emphasis);
    --#{$prefix}alert-bg: var(--#{$prefix}#{$state}-bg-subtle);
    --#{$prefix}alert-border-color: var(--#{$prefix}#{$state}-border-subtle);
  }
}

重要なポイント： $theme-colors に色を追加すると、アラート、ボタン、バッジ、リストグループなどのバリエーションが自動的に生成されます。

バリエーションを備えたカスタムコンポーネント

同じパターンを適用すると、一貫性のあるカスタムコンポーネントを作成できます。

// Base class
.callout {
  padding: var(--bs-callout-padding, 1rem);
  border-left: 4px solid var(--bs-callout-border-color, currentcolor);
  background: var(--bs-callout-bg, transparent);
}

// Generate variants from theme colors
@each $state, $value in $theme-colors {
  .callout-#{$state} {
    --bs-callout-border-color: var(--bs-#{$state});
    --bs-callout-bg: var(--bs-#{$state}-bg-subtle);
  }
}

これにより、.callout-primary、.callout-danger などが生成され、すべてベースの .callout スタイルを継承します。

このパターンに従う button-variant() やその他のミックスインについては、references/sass-functions-mixins.md を参照してください。

カスタムコンポーネントの作成

Bootstrap のミックスインと関数を使って、一貫性のあるコンポーネントを作成します。

.custom-component {
  // Use Bootstrap's spacing
  padding: map-get($spacers, 3);
  margin-bottom: map-get($spacers, 4);

  // Use Bootstrap's colors
  background-color: var(--bs-body-bg);
  color: var(--bs-body-color);
  border: 1px solid var(--bs-border-color);
  border-radius: var(--bs-border-radius);

  // Use Bootstrap's shadows
  @if $enable-shadows {
    box-shadow: $box-shadow-sm;
  }

  // Responsive behavior
  @include media-breakpoint-up(md) {
    padding: map-get($spacers, 4);
  }
}

最適化

Bootstrap の完全版バンドルは大容量です。次の方法を使って、本番バンドルのサイズを削減できます。

Sass インポートの最適化

使用するコンポーネントだけをインポートします。

// Required core
@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/variables-dark";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/root";

// Optional - import only what you use
@import "bootstrap/scss/reboot";
@import "bootstrap/scss/type";
@import "bootstrap/scss/containers";
@import "bootstrap/scss/grid";
@import "bootstrap/scss/buttons";

最小構成のビルド例については、examples/selective-imports.scss を参照してください。

JavaScript インポートの最適化

個々のプラグインをインポートして、Bootstrap JavaScript をツリーシェイクします。

// Instead of importing everything
// import * as bootstrap from 'bootstrap';

// Import only what you need
import Modal from 'bootstrap/js/dist/modal';
import Dropdown from 'bootstrap/js/dist/dropdown';
import Collapse from 'bootstrap/js/dist/collapse';

// Initialize manually
const modal = new Modal('#myModal');

注：一部のプラグインには依存関係があります（例：Dropdown には Popper.js が必要です）。プラグインのドキュメントを確認してください。

PurgeCSS による未使用 CSS の削除

PurgeCSS は、本番ビルドから未使用のスタイルを削除します。

// postcss.config.js
module.exports = {
  plugins: [
    require('@fullhuman/postcss-purgecss')({
      content: ['./src/**/*.html', './src/**/*.js'],
      // Safelist Bootstrap's dynamic classes
      safelist: {
        standard: [/^modal/, /^show/, /^fade/, /^collapse/, /^offcanvas/],
        deep: [/^tooltip/, /^popover/, /^bs-/]
      }
    })
  ]
}

Bootstrap は show、fade、collapsing などのクラスを動的に追加します。必ずこれらのパターンをセーフリストに登録してください。

Autoprefixer の設定

不要なベンダープレフィックスを避けるため、ブラウザーのサポート対象を設定します。

# .browserslistrc
>= 0.5%
last 2 major versions
not dead
not Explorer <= 11

これは Bootstrap のデフォルト設定です。対象ユーザーに合わせて調整してください。

本番環境でのベストプラクティス

圧縮：本番環境では圧縮済みの配布ファイルを使用します。

• bootstrap.min.css（bootstrap.css ではなく）
• bootstrap.bundle.min.js（bootstrap.bundle.js ではなく）

圧縮転送：サーバーで gzip または Brotli を有効にします。

# nginx.conf
gzip on;
gzip_types text/css application/javascript;

ノンブロッキング読み込み：重要でないスクリプトには defer を使用します。

<link rel="stylesheet" href="bootstrap.min.css">


<script src="bootstrap.bundle.min.js" defer></script>

HTTPS：Bootstrap は必ず HTTPS 経由で配信してください。CDN リンクにはセキュアな接続が必要です。また、最新のブラウザーでは混在コンテンツがブロックされる場合があります。

セキュリティに関する考慮事項

コンテンツセキュリティポリシー（CSP）

Bootstrap は、ブラウザー間で一貫したスタイルを適用するため、CSS 内の埋め込み SVG（data: URI）を使用しています。アプリケーションで厳格なコンテンツセキュリティポリシーを設定している場合、一部のコンポーネントが正しく表示されないことがあります。

影響を受けるコンポーネント：

• アコーディオン（折りたたみ／展開アイコン）
• カルーセル（前へ／次へコントロール）
• 閉じるボタン（X アイコン）
• フォームコントロール（チェックボックス、ラジオボタン、スイッチ、検証アイコン）
• ナビゲーションバーのトグル（ハンバーガーアイコン）
• セレクトメニュー（ドロップダウン矢印）

CSP の競合による症状：

• フォームのチェックボックスにチェックマークが表示されない
• アコーディオンに展開／折りたたみアイコンが表示されない
• ナビゲーションバーのハンバーガーメニューが正しく表示されない
• セレクトのドロップダウンに矢印が表示されない

解決策：

1. ローカルアセットに置き換える - escape-svg() 関数を使い、ローカルでホストした SVG ファイルを使用します。

// Custom checkbox with local SVG instead of data: URI
$form-check-input-checked-bg-image: url("/assets/icons/check.svg");

2. CSP を調整する - セキュリティ要件に適している場合は、ポリシーでインライン SVG の data URI を許可します。

3. Bootstrap Icons フォントを使用する - SVG アイコンを Bootstrap Icons のフォント版に置き換えます。

厳格な CSP 環境では、カスタマイズの計画時に Bootstrap の SVG 使用箇所を監査してください。

参照：Bootstrap CSP ドキュメント

追加リソース

参照ファイル

• references/sass-variables.md - Sass 変数の完全なリファレンス
• references/sass-functions-mixins.md - 関数とミックスインの完全なリファレンス

サンプルファイル

• examples/color-mode-toggle.html - システム設定の検出機能を備えた、ダーク／ライトモード切り替えの完全なサンプル
• examples/custom-theme-demo.html - Sass をコンパイルせずに実行時に CSS 変数でテーマを設定するサンプル