theming-components

设计令牌与主题系统

全面的设计令牌系统，为所有组件技能提供基础样式架构，支持品牌自定义、主题切换、RTL 支持和一致的视觉设计。

概述

设计令牌是所有视觉设计决策的唯一事实来源。此技能提供：

1. 完整的令牌分类体系：7 个核心类别（颜色、排版、间距、边框、阴影、动效、z-index）
2. 主题切换：浅色/深色模式、高对比度、自定义品牌主题
3. RTL/i18n 支持：通过 CSS 逻辑属性自动支持从右向左书写的语言
4. 多平台导出：CSS 变量、SCSS、iOS Swift、Android XML、JavaScript
5. 组件集成：技能链式架构，确保所有组件样式一致

关键架构原则：

Component Skills (Behavior + Structure) → Use tokens for ALL visual styling
Design Tokens (Styling Variables)       → Define colors, spacing, typography
Theme Files (Token Overrides)           → Light, dark, brand-specific values

---

快速开始

在组件中使用令牌

步骤 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">Primary Button</button>
</html>


<html data-theme="dark">
  <button class="button">Primary 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');
}

// Load saved theme on page load
setTheme(localStorage.getItem('theme') || 'light');

---

令牌分类体系（7 个核心类别）

1. 颜色令牌

三级层次结构：基础 → 语义 → 组件

/* Primitive (9-shade scales) */
--color-blue-500: #3B82F6;

/* Semantic (purpose-based) */
--color-primary: var(--color-blue-500);
--color-success: var(--color-green-500);
--color-error: var(--color-red-500);

/* Component-specific */
--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;

/* Semantic */
--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

/* Correct - auto-flips in 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 contrast (WCAG AAA) */
}

减少动效

@media (prefers-reduced-motion: reduce) {
  :root {
    --duration-fast: 0ms;
    --transition-fast: none;
  }
}

**完整无障碍指南：**参见 references/accessibility-tokens.md

---

平台导出（Style Dictionary）

将令牌转换为任意平台的格式：

JSON Tokens → Style Dictionary → CSS Variables
                               → iOS Swift
                               → Android XML
                               → JavaScript

npm run build-tokens

**完整设置指南：**参见 references/style-dictionary-setup.md

---

W3C 令牌格式

{
  "color": {
    "primary": {
      "$value": "#3B82F6",
      "$type": "color"
    }
  }
}

---

脚本

# Generate color scale from base color
python scripts/generate_color_scale.py --base "#3B82F6"

# Validate token structure
python scripts/validate_tokens.py

# Check WCAG contrast ratios
python scripts/validate_contrast.py

# Build all platforms
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 标准

---

核心要点

1. 设计令牌是基础 - 所有视觉样式都源自令牌
2. 3 层级结构 - 原始令牌 → 语义令牌 → 组件令牌
3. 7 个核心类别 - 颜色、间距、排版、边框、阴影、动效、z-index
4. 内置主题切换 - 浅色、深色、高对比度、自定义品牌
5. 自动支持 RTL - CSS 逻辑属性支持从右向左书写的语言
6. 无障碍优先 - 符合 WCAG 标准、减少动态效果、支持高对比度
7. 所有技能均引用 - 每项组件技能都使用设计令牌

---

渐进式披露： 此 SKILL.md 提供概览和快速入门。详细文档位于 references/ 目录中。

技能链式调用架构： 请参阅 SKILL_CHAINING_ARCHITECTURE.md