design-system

设计系统

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

适用场景

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

Token 架构

加载：references/token-architecture.md

三层结构

Primitive (raw values)
       ↓
Semantic (purpose aliases)
       ↓
Component (component-specific)

示例：

/* Primitive */
--color-blue-600: #2563EB;

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

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

脚本路径

本 Skill 及其 references/ 中的脚本路径，均相对于包含本 SKILL.md 的目录，而非项目目录：scripts/<file> 指本 Skill 自己的 scripts/ 目录，../<skill>/scripts/<file> 指与其一同安装的同级子 Skill。请基于该目录构建完整路径（Claude Code 在加载 Skill 时会将其报告为 Skill 的基础目录），并将工作目录保持在项目根目录。这些脚本会相对于项目根目录读写项目文件，例如 docs/brand-guidelines.md、assets/design-tokens.json 或 src/。

快速开始

生成 Token：

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

校验用法：

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

参考文档

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

组件规范模式

属性	默认	悬停	激活	禁用
Background	primary	primary-dark	primary-darker	muted
Text	white	white	white	muted-fg
Border	none	none	none	muted-border
Shadow	sm	md	none	none

脚本

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

模板

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

集成

与 brand： 从品牌色彩/排版中提取基础 Token 与 ui-styling： 组件 Token → Tailwind 配置

Skill 依赖： brand、ui-styling 主要 Agent： ui-ux-designer、frontend-developer

幻灯片系统

基于设计 Token + Chart.js + 上下文决策系统的品牌合规演示文稿。

事实来源

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

幻灯片搜索（BM25）

# Basic search (auto-detect domain)
python scripts/search-slides.py "investor pitch"

# Domain-specific search
python scripts/search-slides.py "problem agitation" -d copy
python scripts/search-slides.py "revenue growth" -d chart

# Contextual search (Premium System)
python scripts/search-slides.py "problem slide" --context --position 2 --total 9
python scripts/search-slides.py "cta" --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. Parse goal/context
        ↓
2. Search slide-strategies.csv → Get strategy + emotion beats
        ↓
3. For each slide:
   a. Query slide-layout-logic.csv → layout + break_pattern
   b. Query slide-typography.csv → type scale
   c. Query slide-color-logic.csv → color treatment
   d. Query slide-backgrounds.csv → image if needed
   e. Apply animation class from slide-animations.css
        ↓
4. Generate HTML with design tokens
        ↓
5. Validate with slide-token-validator.py

模式打断（Duarte 脉冲）

优质演示文稿会在不同情绪之间交替切换以保持参与度：

"What Is" (frustration) ↔ "What Could Be" (hope)

系统会在 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/[email protected]/dist/chart.umd.min.js"></script>

<canvas id="revenueChart"></canvas>
<script>
new Chart(document.getElementById('revenueChart'), {
    type: 'line',
    data: {
        labels: ['Sep', 'Oct', 'Nov', 'Dec'],
        datasets: [{
            data: [5, 12, 28, 45],
            borderColor: '#FF6B6B',  // Use brand coral
            backgroundColor: 'rgba(255, 107, 107, 0.1)',
            fill: true,
            tension: 0.4
        }]
    }
});
</script>

设计令牌合规

/* CORRECT - uses token */
background: var(--slide-bg);
color: var(--color-primary);
font-family: var(--typography-font-heading);

/* WRONG - hardcoded */
background: #0D0D0D;
color: #FF6B6B;
font-family: 'Space Grotesk';

参考实现

包含所有功能的完整示例:

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

命令

/slides:create "10-slide investor pitch for ClaudeKit Marketing"

最佳实践

1. 组件中切勿使用原始十六进制颜色值,始终引用令牌
2. 语义层支持主题切换(浅色/深色)
3. 组件级令牌支持按组件自定义
4. 使用 HSL 格式以便控制透明度
5. 为每个令牌记录其用途
6. 幻灯片必须导入 design-tokens.css,并且只使用 var()