igniteui-angular-theming

Ignite UI for Angular — テーマ設定スキル

説明

このスキルでは、Sass ベースのテーマ設定システムと Ignite UI Theming MCP サーバーを使用して、AI エージェントが Ignite UI for Angular アプリケーションのテーマを設定する方法を説明します。グローバルテーマ、パレット、タイポグラフィ、エレベーション、コンポーネントレベルのテーマ設定、レイアウト制御（間隔、サイズ、角の丸み）、およびコード生成に MCP ツールを使用する方法を扱います。

前提条件

• igniteui-angular、またはライセンスをお持ちのユーザーの場合は @infragistics/igniteui-angular がインストールされた Angular プロジェクト
• プロジェクトで Sass のサポートが有効になっていること（Angular CLI プロジェクトではデフォルト）

Ignite UI Theming MCP サーバー（必須）

igniteui-theming MCP サーバーは、本番環境ですぐに使えるテーマコード（create_theme、create_palette、create_component_theme、get_component_design_tokens、get_color など）を生成します。すべてのテーマコードにこのサーバーのツールを使用してください。テーマ Sass やコンポーネントのトークン名を記憶だけで記述してはいけません。

ほかの手順に進む前に、 detect_platform を呼び出してサーバーを確認してください。ツールを利用できない場合：

1. 提案するだけでなく、自分で設定してください。 プロジェクトのルートから npx -y igniteui-cli ai-config を実行してください（igniteui-cli がグローバルにインストールされている場合は ig ai-config）。これにより、既存のサーバーエントリを保持しながら、igniteui-theming と igniteui-cli の両方の MCP サーバーが設定され、Agent Skills がコピーされます。使用中のクライアントが対象に含まれない場合は、references/mcp-setup.md を参照してエントリを手動で追加してください。サーバーのコマンドは npx -y igniteui-theming igniteui-theming-mcp です。
2. ユーザーにエディターまたはエージェントのセッションを再読み込みするよう依頼し、その後は停止してください。 実行中のセッションには MCP ツールを読み込めません。
3. ユーザーから明示的に依頼された場合に限り、サーバーなしで続行してください。その場合は、このファイルに記載された Sass の手動ワークフローを使用し、get_component_design_tokens で確認できなかったトークン名すべてに、未検証の印を付けてください。

テーマ設定のアーキテクチャ

ドキュメント： テーマ設定の概要 · パレット · タイポグラフィ · エレベーション

Ignite UI のテーマ設定システムは、次の 4 つの柱で構成されています。

概念	目的
パレット	プライマリ、セカンダリ、サーフェス、グレー、情報、成功、警告、エラーの各色の系統から成る配色システム。それぞれにシェード 50～900 とアクセント A100～A700 があります
タイポグラフィ	フォントファミリー、文字サイズのスケール（h1～h6、サブタイトル、本文、ボタン、キャプション、オーバーライン）
エレベーション	視覚的な奥行きを表現するボックスシャドウのレベル 0～24
スキーマ	パレットの色をコンポーネントのトークンに割り当てる、コンポーネントごとのレシピ

デザインシステム

組み込みのデザインシステムを 4 つ利用できます。

• Material（デフォルト）— Material Design 3
• Bootstrap — Bootstrap に着想を得たデザイン
• Fluent — Microsoft Fluent Design
• Indigo — Infragistics Indigo Design

それぞれにライトとダークのバリエーションがあります（例：$light-material-schema、$dark-fluent-schema）。

ビルトインテーマ

アプリにテーマを適用する最も簡単な方法は、angular.json にビルトインの CSS ファイルを含めることです。

"styles": ["node_modules/igniteui-angular/styles/igniteui-angular.css"]

ライセンス版パッケージのユーザー： パス内の igniteui-angular を @infragistics/igniteui-angular に置き換えてください。

"styles": ["node_modules/@infragistics/igniteui-angular/styles/igniteui-angular.css"]

使用できるビルトイン CSS ファイル：

ファイル	テーマ
igniteui-angular.css	Material Light
igniteui-angular-dark.css	Material Dark
igniteui-fluent-light.css	Fluent Light
igniteui-fluent-dark.css	Fluent Dark
igniteui-bootstrap-light.css	Bootstrap Light
igniteui-bootstrap-dark.css	Bootstrap Dark
igniteui-indigo-light.css	Indigo Light
igniteui-indigo-dark.css	Indigo Dark

すべてのファイルは node_modules/igniteui-angular/styles/ にあります（ライセンス版パッケージの場合は node_modules/@infragistics/igniteui-angular/styles/）。

カスタム Sass テーマ（手動）

重要 — Sass テーマ設定のドキュメント：ユーザーから Sass ベースのテーマの作成や Sass の設定を明示的に依頼された場合は、専用の Sass ドキュメントを参照してください。

• Sass テーマ設定の概要
• Sass の設定
• Sass パレット
• Sass コンポーネントテーマ

styles.scss ファイルを作成し、angular.json に含めてください。

// Open-source package
@use 'igniteui-angular/theming' as *;
// Licensed package — same Sass API, different import path
// @use '@infragistics/igniteui-angular/theming' as *;
$my-palette: palette(
  $primary: #1976d2,
  $secondary: #ff9800,
  $surface: #fafafa,
);

// 2. Typography (optional)
@include typography($font-family: $material-typeface, $type-scale: $material-type-scale);

// 3. Core reset & base styles
@include core();

// 4. Apply theme
@include theme($palette: $my-palette, $schema: $light-material-schema);

ダークテーマでは、暗いサーフェスカラーとダークスキーマを使用してください。

$dark-palette: palette(
  $primary: #90caf9,
  $secondary: #ffb74d,
  $surface: #121212,
);

@include theme($palette: $dark-palette, $schema: $dark-material-schema);

コンポーネントレベルのテーマ設定

ドキュメント： コンポーネントテーマ

コンポーネントテーマ関数と tokens ミックスインを使用して、個々のコンポーネントの外観を上書きします。

コンポーネントテーマに渡す色の値はすべて、生の 16 進数／RGB／HSL 値ではなく、パレットトークンである必要があります。詳しくは、下記のパレット生成後にハードコードされた色を使用しないを参照してください。

@use 'igniteui-angular/theming' as *;

$custom-avatar: avatar-theme(
  $schema: $light-material-schema,
  $background: var(--ig-primary-500),
  $color: var(--ig-primary-500-contrast),
);

igx-avatar {
  @include tokens($custom-avatar);
}

使用可能なトークンの確認

各コンポーネントには、それぞれ独自のデザイントークン（テーマ設定可能な CSS カスタムプロパティ）があります。コンポーネントのテーマを設定する前に、利用可能なトークンを把握する必要があります。MCP ツール get_component_design_tokens を使用して確認してください。

複合コンポーネント

一部のコンポーネント（例：combo、grid、date-picker、select）は複合コンポーネントで、内部に子コンポーネントを含み、それぞれに個別のテーマが必要です。たとえば、date-picker は内部で calendar、flat-button、input-group を使用します。

複合コンポーネントのワークフロー：

1. 親コンポーネント（例：date-picker）に対して get_component_design_tokens を呼び出します
2. 応答には、関連するテーマとスコープセレクターが一覧表示されます
3. 親のセレクターをラッパーとして使用し、各子コンポーネントに対して create_component_theme を呼び出します

レイアウトコントロール

サイズ

ドキュメント： 表示密度／サイズ

--ig-size を使ってコンポーネントのサイズを調整します（値：1 = 小、2 = 中、3 = 大）。

/* Global */
:root {
  --ig-size: 2;
}

/* Component-scoped */
igx-grid {
  --ig-size: 1;
}

間隔

ドキュメント： 間隔

--ig-spacing を使って内部のパディングを調整します（1 = デフォルト、0.5 = コンパクト、2 = ゆったり）。

:root {
  --ig-spacing: 1;
}
.compact-section {
  --ig-spacing: 0.75;
}

角の丸み

--ig-radius-factor を使って境界線の角丸を調整します（0 = 角形、1 = 最大の角丸）。

:root {
  --ig-radius-factor: 1;
}
igx-avatar {
  --ig-radius-factor: 0.5;
}

Theming MCP サーバーの使用

Ignite UI Theming MCP サーバーは、AI を活用したテーマコード生成用のツールを提供します。

ファイルの安全性：生成されたテーマコードを既存のスタイルファイルに適用する場合は、ユーザーが既に設定しているカスタムスタイルを保持できるよう、対象を絞って編集してください。ファイルの内容を丸ごと置き換えてはいけません。環境でファイル書き込みにユーザーの承認が必要ない場合は、書き込む前に変更内容を差分として提示し、確認してもらってください。

必ず次のワークフローに従ってください。

ステップ 1 — プラットフォームを検出する

Tool: detect_platform

package.json から angular を自動検出し、正しいインポートパスを設定します。

ステップ 2 — 完全なテーマを生成する

Tool: create_theme
Params: {
  platform: "angular",
  designSystem: "material",
  primaryColor: "#1976D2",
  secondaryColor: "#FF9800",
  surfaceColor: "#FAFAFA",
  variant: "light",
  fontFamily: "'Roboto', sans-serif",
  includeTypography: true,
  includeElevations: true
}

パレット、タイポグラフィ、エレベーション、および theme() ミックスインの呼び出しを含む、完全な Sass ファイルを生成します。

ステップ 3 — 個々のコンポーネントをカスタマイズする

Tool: get_component_design_tokens
Params: { component: "grid" }

次に、すべての色に パレットトークンの参照（ハードコードした 16 進数値ではなく）を使用します。

Tool: create_component_theme
Params: {
  platform: "angular",
  designSystem: "material",
  variant: "light",
  component: "grid",
  tokens: {
    "header-background": "var(--ig-primary-50)",
    "header-text-color": "var(--ig-primary-800)"
  }
}

ステップ 4 — パレットを生成する

明度が中程度のベースカラーを使用する場合：

Tool: create_palette
Params: {
  platform: "angular",
  primary: "#1976D2",
  secondary: "#FF9800",
  surface: "#FAFAFA",
  variant: "light"
}

ブランド固有の正確なシェード値を使う場合は、各シェードを完全に制御できるよう、mode: "explicit" を指定して create_custom_palette を使用してください。

ステップ 5 — レイアウトを調整する

Tool: set_size     → { size: "medium" }
Tool: set_spacing  → { spacing: 0.75, component: "grid" }
Tool: set_roundness → { radiusFactor: 0.8 }

ステップ 6 — get_color でパレットカラーを参照する

パレットの生成後、必要な色に対応する CSS カスタムプロパティの参照を取得するには、get_color ツールを使用してください（「パレット生成後に色をハードコードしない」を参照）。

Tool: get_color
Params: { color: "primary", variant: "600" }
→ var(--ig-primary-600)

Params: { color: "primary", variant: "600", contrast: true }
→ var(--ig-primary-600-contrast)

Params: { color: "primary", opacity: 0.5 }
→ hsl(from var(--ig-primary-500) h s l / 0.5)

参照データの読み込み

プリセット値とドキュメントには、次の URI を指定して read_resource を使用してください。

URI	内容
theming://presets/palettes	プリセットのパレットカラー
theming://presets/typography	タイポグラフィのプリセット
theming://presets/elevations	エレベーションのシャドウプリセット
theming://guidance/colors/usage	用途ごとのシェード
theming://guidance/colors/roles	セマンティックカラーの役割
theming://guidance/colors/rules	ライト／ダークテーマのルール
theming://platforms/angular	Angular プラットフォーム固有の情報

パレット生成後に色をハードコードしない

これは、テーマ設定における最も重要なルールです。パレットが存在する場合（Sass の palette()、または MCP 経由の create_palette／create_theme による生成）、すべての色の参照には :root の CSS カスタムプロパティとして利用できるパレットトークンを使用する必要があります。これは、コンポーネントテーマの tokens 値、カスタム CSS ルール（color、background、border-color、fill、stroke）、派生値用の Sass 変数、Angular の host バインディング、インラインスタイルなど、すべてのスタイルコードに適用されます。色をハードコードすると、テーマの切り替えができなくなり、パレットの変更時に不整合が生じます。

正しい例：パレットトークン

// All colors come from the theme — respects palette changes and dark/light switching
.sidebar {
  background: var(--ig-surface-500);
  color: var(--ig-gray-900);
  border-right: 1px solid var(--ig-gray-200);
}

.accent-badge {
  background: var(--ig-secondary-500);
  color: var(--ig-secondary-500-contrast);
}

.hero-section {
  // Semi-transparent primary overlay
  background: hsl(from var(--ig-primary-500) h s l / 0.12);
}

誤った例：ハードコードした値

// WRONG — these break when the palette changes and ignore dark/light mode
$primary-color: #00838f; // ✗ hardcoded
$secondary-color: #3d5afe; // ✗ hardcoded
$surface-color: #f0f5fa; // ✗ hardcoded

.sidebar {
  background: $surface-color; // ✗ not a palette token
  color: #333; // ✗ not a palette token
}

生の 16 進数値を使用してよい場合

生の 16 進数値を使用できるのは、次の場合に限ります。

1. palette() の呼び出し — 完全なパレットを生成するための初期シードカラー
2. create_palette／create_theme MCP ツールの入力 — ツールに渡すベースカラー
3. パレットに含めない装飾的な値 — 例：テーマに関係なく意図的に固定する、単発の SVG イラストの色

それ以外はすべて、var(--ig-<family>-<shade>) トークンを使用する必要があります。

よくあるパターン

ライト／ダークテーマの切り替え、スコープ付きテーマ、ライセンス付きパッケージの設定については、references/common-patterns.md を参照してください。すぐに使える Sass パターンが記載されています。

主なルール

1. 既存のスタイルを保持する — テーマコードは既存のスタイルファイルに対する対象を絞った編集として適用し、ユーザーがカスタマイズしたファイルを丸ごと置き換えないでください
2. 必ず最初に detect_platform を呼び出す — MCP サーバーへの接続を確認し、正しいインポートパスを設定します
3. create_component_theme の前に必ず get_component_design_tokens を呼び出す — 有効なトークン名を確認します
4. すべての有彩色で、パレットの色合いは 50 が最も明るく、900 が最も暗いです — ダークテーマでも逆転させないでください（反転するのはグレーだけです）
5. サーフェスカラーはバリアントに一致させる必要があります — light には明るい色を、dark には暗い色を使用します
6. グローバルスタイルでは、@include theme() の前に @include core() を一度だけ使用します
7. コンポーネントのテーマでは、セレクター内で @include tokens($theme) を使用して CSS カスタムプロパティを出力します
8. 複合コンポーネントの場合は、get_component_design_tokens が返すチェックリスト全体に従い、スコープ付きセレクターで各子コンポーネントをテーマ設定します
9. パレット生成後にハードコードした色を使用しないでください — パレット生成後にハードコードした色を使用しないを参照してください。生の hex/RGB/HSL 値を使用できるのは、初期パレットのシード値のみです

関連スキル

• igniteui-angular-components — UI コンポーネント（フォームコントロール、レイアウト、データ表示、フィードバック／オーバーレイ、ディレクティブ、チャート）
• igniteui-angular-grids — データグリッド（フラットグリッド、ツリーグリッド、階層グリッド、グリッドライト、ピボットグリッド）