design-system

设计系统

令牌架构、组件规范、系统化设计、幻灯片生成。

使用场景

• 设计令牌创建
• 组件状态定义
• CSS变量系统
• 间距/排版比例
• 设计到代码交接
• Tailwind主题配置
• 幻灯片/演示文稿生成

令牌架构

加载：references/token-architecture.md

三层结构

原始（原始值）
       ↓
语义（用途别名）
       ↓
组件（组件特定）

示例：

/* 原始 */
--color-blue-600: #2563EB;

/* 语义 */
--color-primary: var(--color-blue-600);

/* 组件 */
--button-bg: var(--color-primary);

快速开始

生成令牌：

node scripts/generate-tokens.cjs --config tokens.json -o tokens.css

验证使用：

node scripts/validate-tokens.cjs --dir src/

参考

主题	文件
令牌架构	references/token-architecture.md
原始令牌	references/primitive-tokens.md
语义令牌	references/semantic-tokens.md
组件令牌	references/component-tokens.md
组件规范	references/component-specs.md
状态与变体	references/states-and-variants.md
Tailwind集成	references/tailwind-integration.md

组件规范模式

属性	默认	悬停	激活	禁用
背景	primary	primary-dark	primary-darker	muted
文本	white	white	white	muted-fg
边框	none	none	none	muted-border
阴影	sm	md	none	none

脚本

脚本	用途
generate-tokens.cjs	从JSON令牌配置生成CSS
validate-tokens.cjs	检查代码中的硬编码值
search-slides.py	BM25搜索 + 上下文推荐
slide-token-validator.py	验证幻灯片HTML的令牌合规性
fetch-background.py	从Pexels/Unsplash获取图片

模板

模板	用途
design-tokens-starter.json	包含三层结构的入门JSON

集成

与品牌集成： 从品牌颜色/排版中提取原始值
与UI样式集成： 组件令牌 → Tailwind配置

技能依赖： brand, ui-styling
主要代理： ui-ux-designer, frontend-developer

幻灯片系统

使用设计令牌 + Chart.js + 上下文决策系统生成符合品牌规范的演示文稿。

数据源

文件	用途
docs/brand-guidelines.md	品牌标识、语气、颜色
assets/design-tokens.json	令牌定义（原始→语义→组件）
assets/design-tokens.css	CSS变量（在幻灯片中导入）
assets/css/slide-animations.css	CSS动画库

幻灯片搜索（BM25）

# 基本搜索（自动检测领域）
python scripts/search-slides.py "投资者推介"

# 领域特定搜索
python scripts/search-slides.py "问题煽动" -d copy
python scripts/search-slides.py "收入增长" -d chart

# 上下文搜索（高级系统）
python scripts/search-slides.py "问题幻灯片" --context --position 2 --total 9
python scripts/search-slides.py "行动号召" --context --position 9 --prev-emotion frustration

决策系统CSV

文件	用途
data/slide-strategies.csv	15种演示结构 + 情感弧线 + 微趋势节拍
data/slide-layouts.csv	25种布局 + 组件变体 + 动画
data/slide-layout-logic.csv	目标 → 布局 + break_pattern标志
data/slide-typography.csv	内容类型 → 排版比例
data/slide-color-logic.csv	情感 → 颜色处理
data/slide-backgrounds.csv	幻灯片类型 → 图片类别（Pexels/Unsplash）
data/slide-copy.csv	25种文案公式（PAS、AIDA、FAB）
data/slide-charts.csv	25种图表类型及Chart.js配置

上下文决策流程

1. 解析目标/上下文
        ↓
2. 搜索slide-strategies.csv → 获取策略 + 情感节拍
        ↓
3. 对每张幻灯片：
   a. 查询slide-layout-logic.csv → 布局 + break_pattern
   b. 查询slide-typography.csv → 排版比例
   c. 查询slide-color-logic.csv → 颜色处理
   d. 查询slide-backgrounds.csv → 如果需要图片
   e. 应用slide-animations.css中的动画类
        ↓
4. 使用设计令牌生成HTML
        ↓
5. 使用slide-token-validator.py验证

模式打破（Duarte Sparkline）

高级演示在情感之间交替以保持参与度：

"现状"（沮丧）↔ "未来可能"（希望）

系统在1/3和2/3位置计算模式打破。

幻灯片要求

所有幻灯片必须：

1. 导入 assets/design-tokens.css - 单一数据源
2. 使用CSS变量：var(--color-primary)、var(--slide-bg)等
3. 使用Chart.js绘制图表（非纯CSS条形图）
4. 包含导航（键盘箭头、点击、进度条）
5. 内容居中对齐
6. 专注于说服/转化

Chart.js集成

<script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.1/dist/chart.umd.min.js"></script>

<canvas id="revenueChart"></canvas>
<script>
new Chart(document.getElementById('revenueChart'), {
    type: 'line',
    data: {
        labels: ['9月', '10月', '11月', '12月'],
        datasets: [{
            data: [5, 12, 28, 45],
            borderColor: '#FF6B6B',  // 使用品牌珊瑚色
            backgroundColor: 'rgba(255, 107, 107, 0.1)',
            fill: true,
            tension: 0.4
        }]
    }
});
</script>

令牌合规性

/* 正确 - 使用令牌 */
background: var(--slide-bg);
color: var(--color-primary);
font-family: var(--typography-font-heading);

/* 错误 - 硬编码 */
background: #0D0D0D;
color: #FF6B6B;
font-family: 'Space Grotesk';

参考实现

包含所有功能的工作示例：

assets/designs/slides/claudekit-pitch-251223.html

命令

/slides:create "为ClaudeKit Marketing创建10张幻灯片的投资者推介"

最佳实践

1. 绝不在组件中使用原始十六进制值 - 始终引用令牌
2. 语义层支持主题切换（亮/暗）
3. 组件令牌支持每个组件的自定义
4. 使用HSL格式进行透明度控制
5. 记录每个令牌的用途
6. 幻灯片必须导入design-tokens.css并仅使用var()