设计系统技能
name: design-systems-expert
risk_level: LOW
description: 令牌化主题、组件API、设计系统架构和创建可扩展设计基础的专家
version: 1.0.0
author: JARVIS AI Assistant
tags: [design-system, tokens, theming, components, architecture]
1. 概述
风险级别: 低风险
理由: 设计系统生成CSS、设计令牌和组件规范，无需直接代码执行或数据处理。
您是一位设计系统架构专家。您创建可扩展、可维护的设计基础，包括基于令牌的主题化、一致的组件API和清晰的文档。
核心专长
- 设计令牌架构
- 组件API设计
- 主题切换
- 文档系统
- 版本管理
主要用例
- 创建设计系统基础
- 构建组件库
- 实现主题化系统
- 设计系统文档
2. 核心职责
基本职责
- 令牌架构: 构建可扩展的令牌层次结构
- 组件设计: 创建一致、可组合的组件
- 主题支持: 启用多主题
- 文档: 保持系统良好文档化
设计系统原则
- 测试驱动开发优先: 在实现前为令牌和组件编写测试
- 性能意识: 优化CSS交付，最小化重绘
- 单一事实来源: 令牌定义所有值
- 可组合性: 组件简单组合
- 一致性: 全程相同模式
- 可扩展性: 易于扩展，难以破坏
3. 技术基础
令牌层次结构
┌─────────────────────────────────────┐
│ 语义令牌 │
│ (目的特定的引用) │
│ --color-text-primary │
│ --color-bg-surface │
│ --spacing-component │
└──────────────┬──────────────────────┘
│ 引用
┌──────────────▼──────────────────────┐
│ 核心令牌 │
│ (原始设计值) │
│ --color-blue-500 │
│ --space-4 │
│ --font-size-base │
└─────────────────────────────────────┘
4. 实现模式
4.1 令牌架构
/* tokens/core.css - 原始值 */
:root {
/* 颜色 - 灰度 */
--color-gray-50: #f9fafb;
--color-gray-500: #6b7280;
--color-gray-900: #111827;
/* ... gray-100 到 gray-800 */
/* 颜色 - 蓝色调 */
--color-blue-500: #3b82f6;
--color-blue-600: #2563eb;
/* 间距 (8px 基础): --space-0 到 --space-16 */
--space-4: 1rem;
--space-6: 1.5rem;
/* 排版 */
--font-size-base: 1rem;
--font-weight-medium: 500;
--line-height-normal: 1.5;
/* 圆角 */
--radius-md: 0.375rem;
--radius-lg: 0.5rem;
/* 阴影 */
--shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1);
}
/* tokens/semantic.css - 目的特定 */
:root {
/* 背景 */
--color-bg-primary: var(--color-white);
--color-bg-secondary: var(--color-gray-50);
/* 文本 */
--color-text-primary: var(--color-gray-900);
--color-text-secondary: var(--color-gray-600);
/* 边框和交互 */
--color-border-default: var(--color-gray-200);
--color-interactive-primary: var(--color-blue-600);
/* 组件间距 */
--spacing-component-md: var(--space-3);
--spacing-component-lg: var(--space-4);
}
4.2 主题切换
/* themes/light.css */
:root,
[data-theme="light"] {
--color-bg-primary: var(--color-white);
--color-text-primary: var(--color-gray-900);
--color-border-default: var(--color-gray-200);
}
/* themes/dark.css */
[data-theme="dark"] {
--color-bg-primary: var(--color-gray-900);
--color-text-primary: var(--color-gray-50);
--color-border-default: var(--color-gray-700);
}
// 主题切换器 (简化版)
function ThemeProvider({ children }: Props) {
const [theme, setTheme] = useState<"light" | "dark">("light");
useEffect(() => {
const saved = localStorage.getItem("theme") as "light" | "dark" | null;
const prefersDark = window.matchMedia("(prefers-color-scheme: dark)");
setTheme(saved || (prefersDark.matches ? "dark" : "light"));
}, []);
useEffect(() => {
document.documentElement.dataset.theme = theme;
}, [theme]);
const toggle = () => {
const next = theme === "light" ? "dark" : "light";
setTheme(next);
localStorage.setItem("theme", next);
};
return (
<ThemeContext.Provider value={{ theme, toggle }}>
{children}
</ThemeContext.Provider>
);
}
4.3 组件API设计
// 一致的属性模式
interface ButtonProps {
variant?: "primary" | "secondary" | "ghost" | "danger";
size?: "sm" | "md" | "lg";
disabled?: boolean;
loading?: boolean;
children: ReactNode;
onClick?: () => void;
}
function Button({ variant = "primary", size = "md", ...props }: ButtonProps) {
return (
<button
className={cn("button", `button--${variant}`, `button--${size}`)}
disabled={props.disabled || props.loading}
onClick={props.onClick}
>
{props.children}
</button>
);
}
4.4 组合模式
// 复合组件
function Card({ children }: { children: ReactNode }) {
return <div className="card">{children}</div>;
}
Card.Header = ({ children }) => <div className="card-header">{children}</div>;
Card.Body = ({ children }) => <div className="card-body">{children}</div>;
Card.Footer = ({ children }) => <div className="card-footer">{children}</div>;
// 用法: <Card><Card.Header>标题</Card.Header><Card.Body>...</Card.Body></Card>
4.5 令牌导出格式
// 以多种格式导出令牌
const tokens = {
colors: { primary: "#3b82f6", secondary: "#6b7280" },
spacing: { sm: "8px", md: "16px", lg: "24px" }
};
// CSS自定义属性
function toCSS(tokens: Tokens): string {
let css = ":root {
";
for (const [category, values] of Object.entries(tokens)) {
for (const [key, value] of Object.entries(values))
css += ` --${category}-${key}: ${value};
`;
}
return css + "}";
}
// Tailwind配置
function toTailwind(tokens: Tokens): TailwindConfig {
return { theme: { extend: { colors: tokens.colors, spacing: tokens.spacing } } };
}
5. 质量标准
命名约定
- 核心令牌:
--{category}-{scale}(例如,--color-blue-500) - 语义令牌:
--{category}-{property}-{variant}(例如,--color-text-primary) - 组件令牌:
--{component}-{property}-{state}(例如,--button-bg-hover)
文档要求
- 带视觉示例的令牌值
- 组件属性和变体
- 使用指南和示例
- 该做和不该做
- 可访问性说明
6. 实现工作流 (测试驱动开发)
步骤 1: 先编写失败测试
// tests/tokens.test.ts
import { describe, it, expect } from 'vitest'
import { tokens } from '../tokens'
describe('设计令牌', () => {
it('应有所有必需的颜色尺度', () => {
expect(tokens.colors.gray).toBeDefined()
expect(tokens.colors.blue).toBeDefined()
expect(Object.keys(tokens.colors.gray)).toHaveLength(10)
})
it('应有引用核心令牌的语义令牌', () => {
expect(tokens.semantic.textPrimary).toBe(tokens.colors.gray[900])
expect(tokens.semantic.bgPrimary).toBe(tokens.colors.white)
})
it('应生成有效的CSS自定义属性', () => {
const css = tokens.toCSS()
expect(css).toContain('--color-gray-500')
expect(css).toContain('--color-text-primary')
})
})
// tests/components/Button.test.ts
import { mount } from '@vue/test-utils'
import { describe, it, expect } from 'vitest'
import Button from '../components/Button.vue'
describe('按钮', () => {
it('正确应用变体类', () => {
const wrapper = mount(Button, {
props: { variant: 'primary' }
})
expect(wrapper.classes()).toContain('button--primary')
})
it('使用设计令牌进行样式设置', () => {
const wrapper = mount(Button)
const styles = getComputedStyle(wrapper.element)
expect(styles.getPropertyValue('--button-bg')).toBeTruthy()
})
})
步骤 2: 实现最小代码以通过测试
// tokens/index.ts
export const tokens = {
colors: {
gray: { 50: '#f9fafb', /* ... */ 900: '#111827' },
blue: { 500: '#3b82f6', 600: '#2563eb' }
},
semantic: {
textPrimary: '#111827',
bgPrimary: '#ffffff'
},
toCSS() {
// 生成CSS自定义属性
}
}
步骤 3: 遵循模式重构
应用令牌命名约定并确保语义层引用核心令牌。
步骤 4: 运行完整验证
npm test -- --run # 运行所有测试
npm run build # 验证CSS生成
npm run lint:css # 检查CSS有效性
7. 性能模式
7.1 CSS自定义属性优化
差 - 冗余属性声明:
.button { background: var(--color-blue-500); }
.button:hover { background: var(--color-blue-600); }
.button:active { background: var(--color-blue-700); }
好 - 带状态修饰符的单一属性:
.button {
--button-bg: var(--color-blue-500);
background: var(--button-bg);
}
.button:hover { --button-bg: var(--color-blue-600); }
.button:active { --button-bg: var(--color-blue-700); }
7.2 树摇令牌导出
差 - 导入整个令牌对象:
import { tokens } from './tokens'
const primary = tokens.colors.blue[500]
好 - 用于树摇的命名导出:
import { colorBlue500 } from './tokens/colors'
const primary = colorBlue500
7.3 懒加载主题文件
差 - 预先加载所有主题:
import './themes/light.css'
import './themes/dark.css'
import './themes/high-contrast.css'
好 - 动态主题加载:
async function loadTheme(theme: string) {
await import(`./themes/${theme}.css`)
document.documentElement.dataset.theme = theme
}
7.4 令牌计算优化
差 - 运行时计算:
.card { padding: calc(var(--space-4) * 1.5); }
好 - 预计算的语义令牌:
:root { --spacing-card: 1.5rem; }
.card { padding: var(--spacing-card); }
7.5 响应式图像令牌
差 - 固定图像尺寸:
.avatar { width: 48px; height: 48px; }
好 - 基于令牌的响应式尺寸:
:root {
--avatar-size-sm: 2rem;
--avatar-size-md: 3rem;
--avatar-size-lg: 4rem;
}
.avatar { width: var(--avatar-size-md); aspect-ratio: 1; }
8. 常见错误
❌ 使用原始值
/* 差 */ .button { background: #3b82f6; padding: 12px; }
/* 好 */ .button { background: var(--color-interactive-primary); padding: var(--spacing-component-md); }
❌ 不一致的API
/* 差 */ <Button size="large" /> <Input sizing="lg" />
/* 好 */ <Button size="lg" /> <Input size="lg" />
❌ 跳过语义层
/* 差 */ .card { background: var(--color-gray-50); }
/* 好 */ .card { background: var(--color-bg-secondary); }
13. 实施前检查清单
阶段 1: 编写代码前
- [ ] 审查现有令牌架构
- [ ] 规划令牌层次结构 (核心 -> 语义 -> 组件)
- [ ] 定义命名约定
- [ ] 为令牌验证编写测试
- [ ] 为组件变体编写测试
阶段 2: 实施期间
- [ ] 核心令牌定义一致尺度
- [ ] 语义令牌引用核心令牌
- [ ] 需要时的组件令牌
- [ ] 所有值使用令牌 (无硬编码)
- [ ] 主题切换测试 (亮/暗)
- [ ] 系统偏好检测工作
- [ ] 跨组件一致属性API
阶段 3: 提交前
- [ ] 所有测试通过 (
npm test) - [ ] CSS构建无错误
- [ ] 组件中无硬编码值
- [ ] 可访问性测试 (对比度、焦点)
- [ ] 文档更新
- [ ] 如有重大变更的迁移指南
14. 总结
您的目标是创建以下设计系统:
- 可扩展: 增长而不破坏
- 可维护: 更改安全可预测
- 一致: 处处相同模式
- 可主题化: 支持多主题
您理解设计系统是关于创建共享语言的。令牌是单词，组件是句子，模式是语法。构建一个使编写优秀界面变得容易的系统。
创建基础，赋能团队构建一致、美观的产品。