name: 主题化组件 description: 提供设计令牌系统和主题框架，用于跨所有组件实现一致、可定制的UI样式。涵盖完整的令牌分类（颜色、排版、间距、阴影、边框、动画、z索引）、主题切换（CSS自定义属性、主题提供者）、RTL/i18n支持（CSS逻辑属性）和可访问性（WCAG对比度、高对比度主题、减少动画）。这是所有组件技能引用的基础样式层。用于主题化组件、实现亮/暗模式、创建品牌样式、自定义视觉设计、确保设计一致性或支持RTL语言。
设计令牌与主题系统
全面的设计令牌系统，为所有组件技能提供基础样式架构，支持品牌定制、主题切换、RTL支持和一致的视觉设计。
概述
设计令牌是所有视觉设计决策的单一真相来源。此技能提供：
- 完整的令牌分类：7个核心类别（颜色、排版、间距、边框、阴影、动画、z索引）
- 主题切换：亮/暗模式、高对比度、自定义品牌主题
- RTL/i18n支持：CSS逻辑属性用于自动支持从右到左的语言
- 多平台导出：CSS变量、SCSS、iOS Swift、Android XML、JavaScript
- 组件集成：技能链式架构，确保所有组件样式一致
关键架构原则：
组件技能（行为 + 结构）→ 使用令牌进行所有视觉样式
设计令牌（样式变量） → 定义颜色、间距、排版
主题文件（令牌覆盖） → 亮、暗、品牌特定值
快速开始
在组件中使用令牌
步骤1：在组件中引用令牌：
.button {
background-color: var(--button-bg-primary);
color: var(--button-text-primary);
padding-inline: var(--button-padding-inline);
padding-block: var(--button-padding-block);
border-radius: var(--button-border-radius);
transition: var(--transition-fast);
}
步骤2：主题自动应用：
<!-- 亮主题 -->
<html data-theme="light">
<button class="button">主要按钮</button>
</html>
<!-- 暗主题（相同组件，不同外观） -->
<html data-theme="dark">
<button class="button">主要按钮</button>
</html>
无需代码更改 - 主题切换是自动的！
基本主题切换
function setTheme(themeName) {
document.documentElement.setAttribute('data-theme', themeName);
localStorage.setItem('theme', themeName);
}
function toggleTheme() {
const current = document.documentElement.getAttribute('data-theme');
setTheme(current === 'dark' ? 'light' : 'dark');
}
// 页面加载时加载保存的主题
setTheme(localStorage.getItem('theme') || 'light');
令牌分类（7个核心类别）
1. 颜色令牌
3层层次：原始 → 语义 → 组件
/* 原始（9色阶） */
--color-blue-500: #3B82F6;
/* 语义（基于用途） */
--color-primary: var(--color-blue-500);
--color-success: var(--color-green-500);
--color-error: var(--color-red-500);
/* 组件特定 */
--button-bg-primary: var(--color-primary);
完整颜色系统： 参见 references/color-system.md
2. 间距令牌
4px基础比例：
--space-1: 4px; --space-2: 8px; --space-4: 16px;
--space-6: 24px; --space-8: 32px; --space-12: 48px;
/* 语义 */
--spacing-sm: var(--space-2); /* 8px */
--spacing-md: var(--space-4); /* 16px */
--spacing-lg: var(--space-6); /* 24px */
3. 排版令牌
--font-sans: 'Inter', -apple-system, sans-serif;
--font-mono: 'Fira Code', monospace;
--font-size-sm: 14px;
--font-size-base: 16px;
--font-size-lg: 18px;
--font-weight-normal: 400;
--font-weight-semibold: 600;
--font-weight-bold: 700;
4. 边框与圆角令牌
--border-width-thin: 1px;
--border-width-medium: 2px;
--radius-sm: 4px;
--radius-md: 8px;
--radius-lg: 12px;
--radius-full: 9999px;
5. 阴影令牌
--shadow-sm: 0 2px 4px rgba(0, 0, 0, 0.07);
--shadow-md: 0 4px 8px rgba(0, 0, 0, 0.1);
--shadow-lg: 0 8px 16px rgba(0, 0, 0, 0.12);
--shadow-focus-primary: 0 0 0 3px rgba(59, 130, 246, 0.3);
6. 动画令牌
--duration-fast: 150ms;
--duration-normal: 200ms;
--ease-out: cubic-bezier(0, 0, 0.2, 1);
--transition-fast: all var(--duration-fast) var(--ease-out);
减少动画支持：
@media (prefers-reduced-motion: reduce) {
:root { --transition-fast: none; }
}
7. Z-Index令牌
--z-dropdown: 1000;
--z-modal-backdrop: 1040;
--z-modal: 1050;
--z-tooltip: 1070;
主题架构
亮/暗主题
/* themes/light.css */
:root {
--color-primary: #3B82F6;
--color-background: #FFFFFF;
--color-text-primary: #1F2937;
}
/* themes/dark.css */
:root[data-theme="dark"] {
--color-primary: #60A5FA;
--color-background: #111827;
--color-text-primary: #F9FAFB;
}
自定义品牌主题
:root[data-theme="my-brand"] {
--color-primary: #FF6B35;
--font-sans: 'Poppins', sans-serif;
--radius-md: 12px;
}
完整主题指南： 参见 references/theme-switching.md
CSS逻辑属性（RTL支持）
使用逻辑属性自动支持RTL语言：
| 物理（避免） | 逻辑（使用） |
|---|---|
margin-left |
margin-inline-start |
padding-right |
padding-inline-end |
text-align: left |
text-align: start |
/* 正确 - 在RTL中自动翻转 */
.button {
padding-inline: var(--button-padding-inline);
margin-inline-start: var(--spacing-sm);
}
完整RTL指南： 参见 references/logical-properties.md
组件集成
所有组件技能使用此命名约定：
--{component}-{property}-{variant?}-{state?}
示例：
--button-bg-primary
--button-bg-primary-hover
--input-border-color-focus
--chart-color-1
组件使用令牌进行所有样式：
.button {
background-color: var(--button-bg-primary);
border-radius: var(--button-border-radius);
}
主题更改自动更新所有组件。
完整集成指南： 参见 references/component-integration.md
可访问性
WCAG 2.1 AA 合规
- 正常文本：最小对比度4.5:1
- 大文本（18px+）：最小对比度3:1
- UI组件：最小对比度3:1
高对比度主题
:root[data-theme="high-contrast"] {
--color-primary: #0000FF;
--color-text-primary: #000000;
/* 7:1对比度（WCAG AAA） */
}
减少动画
@media (prefers-reduced-motion: reduce) {
:root {
--duration-fast: 0ms;
--transition-fast: none;
}
}
完整可访问性指南： 参见 references/accessibility-tokens.md
平台导出（样式字典）
将令牌转换到任何平台：
JSON令牌 → 样式字典 → CSS变量
→ iOS Swift
→ Android XML
→ JavaScript
npm run build-tokens
完整设置指南： 参见 references/style-dictionary-setup.md
W3C令牌格式
{
"color": {
"primary": {
"$value": "#3B82F6",
"$type": "color"
}
}
}
脚本
# 从基础颜色生成颜色比例
python scripts/generate_color_scale.py --base "#3B82F6"
# 验证令牌结构
python scripts/validate_tokens.py
# 检查WCAG对比度比例
python scripts/validate_contrast.py
# 构建所有平台
npm run build-tokens
参考资料
核心系统：
references/color-system.md- 完整颜色比例和语义references/typography-system.md- 字体比例和字体references/spacing-system.md- 间距比例和节奏
实现：
references/theme-switching.md- 亮/暗模式、自定义主题references/component-integration.md- 技能如何使用令牌references/logical-properties.md- RTL支持模式
工具与可访问性：
references/style-dictionary-setup.md- 多平台构建references/accessibility-tokens.md- WCAG合规
关键要点
- 设计令牌是基础 - 所有视觉样式从令牌流
- 3层层次 - 原始 → 语义 → 组件令牌
- 7个核心类别 - 颜色、间距、排版、边框、阴影、动画、z索引
- 内置主题切换 - 亮、暗、高对比度、自定义品牌
- 自动RTL支持 - CSS逻辑属性支持从右到左语言
- 可访问性优先 - WCAG合规、减少动画、高对比度
- 被所有技能引用 - 每个组件技能使用设计令牌
渐进披露： 此SKILL.md提供概述和快速开始。详细文档在 references/ 目录中。
技能链式架构： 参见 SKILL_CHAINING_ARCHITECTURE.md