igniteui-angular-theming

Ignite UI for Angular — 主题化技能

描述

此技能介绍如何使用基于 Sass 的主题化系统和 Ignite UI Theming MCP 服务，为 Ignite UI for Angular 应用设置主题。内容涵盖全局主题、调色板、排版、立体效果、组件级主题化、布局控制（间距、尺寸、圆角），以及如何使用 MCP 工具生成代码。

前置条件

• 已安装 igniteui-angular 的 Angular 项目，或供授权用户使用的 @infragistics/igniteui-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. **请用户重新加载编辑器或 Agent 会话，然后停止。**MCP 工具无法加载到正在运行的会话中。
3. **只有用户明确要求时，才可在没有服务的情况下继续。**此时请使用本文件中的手动 Sass 工作流，并将所有未通过 get_component_design_tokens 验证的令牌名称标记为未经验证。

主题化架构

文档：主题化概览 · 调色板 · 排版 · 立体效果

Ignite UI 主题化系统由四大支柱构成：

概念	用途
调色板	色彩系统，包含主色、辅助色、表面色、灰色、信息色、成功色、警告色、错误色系列，每个系列包含 50–900 色阶及 A100–A700 强调色
排版	字体系列、字号比例（h1–h6、副标题、正文、按钮、说明文字、眉题）
立体效果	用于营造视觉层次的 0–24 级盒阴影
Schema	按组件定义的配方，将调色板颜色映射到组件令牌

设计系统

提供四种内置设计系统：

• 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 浅色
igniteui-angular-dark.css	Material 深色
igniteui-fluent-light.css	Fluent 浅色
igniteui-fluent-dark.css	Fluent 深色
igniteui-bootstrap-light.css	Bootstrap 浅色
igniteui-bootstrap-dark.css	Bootstrap 深色
igniteui-indigo-light.css	Indigo 浅色
igniteui-indigo-dark.css	Indigo 深色

所有文件都位于 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 mixin 覆盖单个组件的外观。

传递给组件主题的所有颜色值都必须是调色板令牌，而不能是原始十六进制/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
}

生成一个完整的 Sass 文件，其中包含调色板、排版、阴影层级以及 theme() 混入调用。

步骤 3 — 自定义单个组件

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

然后，为每种颜色使用调色板令牌引用（而非硬编码的十六进制值）：

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"
}

对于品牌专属的精确色阶值，请使用 create_custom_palette，并设置 mode: "explicit"，以完全控制每个色阶。

步骤 5 — 调整布局

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

步骤 6 — 通过 get_color 引用调色板颜色

生成调色板后，使用 get_color 工具获取所需颜色对应的正确 CSS 自定义属性引用（请参阅生成调色板后禁止使用硬编码颜色）：

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)

加载参考数据

使用 read_resource 和以下 URI 获取预设值及文档：

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 生成），所有颜色引用都必须来自调色板令牌；这些令牌以 CSS 自定义属性的形式提供于 :root 上。这适用于所有样式代码：组件主题的 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
}

允许使用原始十六进制值的情况

原始十六进制值仅可用于以下情况：

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. 始终先调用 get_component_design_tokens，再调用 create_component_theme，以了解有效的令牌名称
4. 所有色彩的色板色阶中，50 = 最浅，900 = 最深 — 深色主题也绝不要反转（只有灰色会反转）
5. 表面颜色必须与变体匹配 — light 使用浅色，dark 使用深色
6. 在全局样式中，先使用一次 @include core()，再使用 @include theme()
7. 组件主题在选择器内使用 @include tokens($theme) 来生成 CSS 自定义属性
8. 对于复合组件，请遵循 get_component_design_tokens 返回的完整检查清单 — 使用各自的作用域选择器为每个子组件设置主题
9. 生成色板后不要使用硬编码颜色 — 请参阅生成色板后不要使用硬编码颜色；原始十六进制、RGB、HSL 值仅可用于初始色板种子值

相关技能

• igniteui-angular-components — UI 组件（表单控件、布局、数据展示、反馈/浮层、指令、图表）
• igniteui-angular-grids — 数据网格（平面网格、树形网格、分层网格、轻量网格、透视网格）