ckm:design-system

概览

ckm:design-system 是什么？

ckm:design-system 是一个 design-system 技能，把设计 token 架构、组件规格和演示幻灯片生成组合到一套可复用的工作流中。

它围绕三层 token 模型构建（primitive → semantic → component），并提供配套的参考文档和脚本，用于：

• CSS variable 体系
• 间距与排版刻度
• 组件状态与 variants
• Tailwind 主题配置
• 系统化的幻灯片与 pitch deck 版式

该技能内置有主观预设的数据表和模板，涵盖幻灯片背景、颜色逻辑、文案公式、版式以及叙事策略，同时提供用于生成和校验 tokens 与幻灯片结构的脚本。

适用人群

ckm:design-system 主要面向：

• Design-system 负责人和 UI/UX 设计师：需要清晰的 token 架构和组件规格参考。
• 前端开发和 React/Tailwind 开发者：需要稳定的 token 流程（CSS variables、校验工具、Tailwind 集成思路）。
• 创始人、产品经理和市场人员：经常制作 pitch deck，希望有可复用、品牌一致的幻灯片框架，而不是每次从零开始。

如果你想在 Figma 式的设计思维与可直接实现的 tokens 以及可复用的幻灯片系统之间建立桥梁，这个技能会非常适合。

它能解决什么问题？

ckm:design-system 帮助你：

• 标准化设计 tokens，通过文档化的 primitive → semantic → component 分层结构。
• 从 JSON 生成 CSS tokens，并在代码库中校验它们的使用。
• 规划 Tailwind 主题，并沿用同一套 token 架构。
• 定义组件规格，包括状态与 variants，确保 UI 在不同页面和场景中保持一致。
• 设计品牌一致的演示文稿，利用预设的幻灯片版式、图表推荐、颜色与情绪逻辑以及文案公式。

它让你可以用系统的角度来思考 UI 和幻灯片，而不只是零散的单个产物。

什么时候适合使用 ckm:design-system？

在以下情况中尤其适合：

• 你正在引入或重构一个 design system，并希望有清晰的 token 分层。
• 你需要围绕 token 架构的 CSS variable 和 Tailwind 指引。
• 你希望 自动生成并校验设计 tokens，而不是手动维护。
• 你经常制作 pitch deck、销售演示或产品 Demo，希望有可复用的幻灯片结构。

如果你只需要一个静态 UI 模型，或者完全不使用 tokens 和 CSS variables，这个技能的价值会相对有限。

使用方法

安装与基础配置

1. 安装 ckm:design-system 技能

在你的 Agent/skills 环境中安装该技能：

npx skills add https://github.com/nextlevelbuilder/ui-ux-pro-max-skill --skill design-system

这会从 nextlevelbuilder/ui-ux-pro-max-skill 仓库中拉取 design-system 技能到本地 skills 目录。

2. 浏览核心文件

安装完成后，打开技能目录，从以下文件/文件夹开始：

• SKILL.md – 高层概览、使用场景、token 架构与快速上手命令。
• references/ – 关于 tokens、组件、variants 和 Tailwind 集成的概念性文档。
• data/ – 描述幻灯片背景、颜色逻辑、文案公式、版式、排版和策略的 CSV 文件。
• scripts/ – 用于生成、嵌入和校验 tokens 的工具脚本，以及幻灯片搜索助手。
• templates/design-tokens-starter.json – 定义自有 token 集的起始 JSON 模板。

通过这套结构，你可以快速判断要采用哪些部分：只用 tokens、只用幻灯片，或使用完整系统。

设计你的 token 架构

3. 理解三层 token 模型

SKILL.md 和 references/token-architecture.md 描述了一个三步结构：

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

利用这些参考文件来设计每一层：

• references/primitive-tokens.md – 基础颜色、间距、圆角、排版 primitives。
• references/semantic-tokens.md – 按用途划分的 tokens，如 --color-primary、--surface-elevated、--text-muted。
• references/component-tokens.md – 组件级变量，如 --button-bg、--card-border、--badge-pill-radius。

这种分层有助于：

• 在不重写组件的前提下切换主题。
• 让实现细节（CSS variables、Tailwind 配置）与设计语言始终保持一致。

4. 创建或适配你的 token JSON

使用 templates/design-tokens-starter.json 作为自定义 token 文件的基础。

典型工作流：

1. 将 templates/design-tokens-starter.json 复制到你的项目中并命名为 tokens.json。
2. 先填写 primitive 值（颜色、间距、字体大小）。
3. 将 primitives 映射到 semantic 角色（primary、secondary、surface、border 等）。
4. 将 semantic tokens 映射为各个关键 UI 组件的 component tokens。

可参考：

• references/component-specs.md – 帮助你思考组件如何消费 tokens。
• references/states-and-variants.md – 关于 hover、focus、disabled、error 等状态和变化的设计。

生成与校验 tokens

5. 从 tokens 生成 CSS variables

使用 SKILL.md 中描述的 token 生成脚本：

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

• --config 指向你的 token JSON（如 tokens.json）。
• -o 指定输出的 CSS 文件（如 tokens.css）。

生成的 CSS 文件会把你的 token 集定义为 --custom-properties，可直接在前端工程中引入。

6. 校验代码库中的 token 使用

为确保代码只使用已批准的 tokens，运行 token 校验脚本：

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

它会在指定目录（如 src/）中扫描 token 使用模式，帮助你：

• 找出本应使用 tokens 却被硬编码的数值。
• 识别已废弃或未定义的 tokens。

scripts/ 中的其他校验工具包括：

• html-token-validator.py – 扫描 HTML 中的 token 使用模式。
• slide-token-validator.py – 校验与幻灯片相关场景中的 token 使用。

利用这些工具，可以让 UI 与幻灯片都遵循统一的 design system。

7. 按需嵌入 tokens

如果你的环境需要把 tokens 嵌入文档或 HTML，可以使用：

• scripts/embed-tokens.cjs – 将 tokens 嵌入目标文件。

具体用法可查看脚本中的注释和 SKILL.md，并根据自身环境进行调整。

Tailwind 与实现层注意事项

8. 规划 Tailwind 集成

该技能包含专门的 Tailwind 参考：

• references/tailwind-integration.md – 指导如何将 token 名称和刻度映射到 Tailwind 主题配置中。

可用于：

• 将 primitive/semantic tokens 映射到 Tailwind 的 colors、spacing 和 fontSize 刻度。
• 让 Tailwind utility class 与 token 设计保持一致（例如基于 primitives 推导出的 primary 调色板）。

即便你当前还没使用 Tailwind，这份参考也能帮助你从“可扩展到 utility-first CSS”的角度来规划 token 系统。

构建系统化的幻灯片

虽然该技能的主要类别是 design system，但 ckm:design-system 同样支持结构化的演示设计。

9. 利用幻灯片数据表设计版式与视觉

data/ 目录中包含一些编码了最佳实践的幻灯片模式 CSV 文件：

• data/slide-backgrounds.csv – 按幻灯片类型（hero、vision、team、testimonial、CTA、problem、solution 等）推荐背景图类型、叠加方式和摆放方式。
• data/slide-color-logic.csv – 将情绪（frustration、hope、fear、relief、trust、urgency、curiosity 等）映射到背景样式、文字颜色和强调色使用方式。
• data/slide-typography.csv – 针对不同幻灯片类型给出的排版建议（层级结构、强调方式等）。
• data/slide-layout-logic.csv – 基于叙事目标和情绪驱动的版式模式（hook、problem、solution、proof、traction、CTA、timeline、features 等）。
• data/slide-layouts.csv – 带有 CSS 结构提示的具体版式模式（如网格、左右分栏、hero 结构、动效建议等）。

你可以把这些表格接入自己的流水线（脚本、表格工具或 deck generator），构建由叙事和情绪驱动、而非随意视觉决定的统一幻灯片。

10. 使用成熟公式结构化幻灯片文案

data/slide-copy.csv 提供针对不同幻灯片类型的文案公式，包括：

• AIDA（Attention → Interest → Desire → Action）
• PAS（Problem → Agitate → Solution）
• 4Ps（Promise → Picture → Proof → Push）
• Before-After-Bridge
• QUEST
• Star-Story-Solution

每一行通常包含：

• formula_name 与 keywords
• 结构化的 components
• use_case 与 example_template
• emotion_trigger 与 slide_type

你可以用它们来：

• 引导 Agent 按指定公式生成幻灯片文案。
• 在多个 pitch deck 和销售演示中统一文案风格与结构。

11. 为整套 deck 选择叙事策略

data/slide-strategies.csv 定义了完整的 deck 模式，例如：

• YC Seed Deck
• Guy Kawasaki 10/20/30
• Series A Deck

每种策略包括：

• 推荐的幻灯片数量
• 幻灯片顺序（title、problem、solution、traction、market 等）
• 目标、受众与语气
• 叙事与情绪节奏

借此你可以：

• 为选定策略生成一整套幻灯片大纲。
• 让 design system 与叙事结构保持同步。

12. 使用幻灯片相关脚本

scripts/ 目录中包含若干与幻灯片工作流相关的工具：

• scripts/generate-slide.py – 核心幻灯片生成逻辑（可改造为自有 deck generator 或流水线的一部分）。
• scripts/search-slides.py 和 scripts/slide_search_core.py – 搜索工具，可根据关键词和上下文查找相关幻灯片模式或策略。
• scripts/fetch-background.py – 根据 data/slide-backgrounds.csv 中的指南，从 Pexels/Unsplash 等来源获取背景图片。

这些脚本是可组合的基础模块，你可以按环境和自动化需求选择直接运行或进一步定制。

善用参考文档

13. 把 references 当作实现清单

references/ 文件夹不仅是说明文档，也可在构建设计系统时充当 checklist：

• references/token-architecture.md – 用于检查 primitive/semantic/component 分层是否合理。
• references/primitive-tokens.md – 确保基础 tokens 集合完整。
• references/semantic-tokens.md – 检查每个 semantic token 是否有清晰用途。
• references/component-tokens.md – 将 tokens 映射到实际组件。
• references/component-specs.md – 记录状态、variants、交互和可访问性要点。
• references/states-and-variants.md – 避免遗漏 hover、focus、active、disabled、error、success 等状态。

在设计评审和设计交接过程中使用这些文件，可以更好地对齐设计与开发。

适配你的技术栈

14. 逐步引入

你不需要一次性采用整个技能。常见的渐进式做法包括：

• 仅采用 tokens – 从 templates/design-tokens-starter.json、generate-tokens.cjs 和 validate-tokens.cjs 入手，先搭建 token 流水线。
• 仅采用幻灯片体系 – 使用 data/ 下的 CSV 和 scripts/generate-slide.py 规范你的演示内容，同时沿用现有的 design system。
• 完整引入 – 将 tokens、组件和幻灯片结构结合起来，为产品 UI 与 pitch deck 搭建统一的品牌系统。

优先解决当下最紧急的问题，再逐步扩展到其他模块。

常见问题

ckm:design-system 是 UI kit 还是 design token 引擎？

它本质上是一个 design-system 与 token 架构技能，并额外包含结构化的幻灯片系统。它不是 Figma UI kit，但会提供：

• 一套三层 token 架构
• 用于生成和校验 tokens 的脚本
• 组件规格与状态的参考

你可以在 Figma 或其他设计工具中轻松复用同样的 tokens 和组件。

不使用 Tailwind 或 React 也能用 ckm:design-system 吗？

可以。references/tailwind-integration.md 中的 Tailwind 集成只是一种可选方案。tokens 会被生成为标准 CSS variables，因此你可以在任何技术栈中使用：

• 原生 CSS 或 CSS Modules
• styled-components 或其他 CSS-in-JS 方案
• Web Components 或其他框架中的 design tokens

ckm:design-system 如何帮助做演示？

该技能把幻灯片 deck 视为一个 design system 问题：

• data/slide-layouts.csv 和 data/slide-layout-logic.csv 定义版式模式和 CSS 结构。
• data/slide-backgrounds.csv 和 data/slide-color-logic.csv 将幻灯片类型和情绪映射到视觉风格。
• data/slide-copy.csv 和 data/slide-strategies.csv 提供文案公式和 deck 结构。
• generate-slide.py、search-slides.py 等脚本帮助自动生成与检索。

这样你就可以构建可重复、品牌一致的 deck，而不是一次性拼凑的单页幻灯片。

必须原样使用提供的 CSV 数据吗？

不必。这些 CSV 是 带观点的默认配置，你可以：

• 直接使用，快速搭建 pitch deck。
• fork 并自定义，使之更贴合你的品牌语气和视觉风格。
• 完全替换为自有数据，但沿用同样的脚本模式。

如果我只关心 design tokens，应从哪开始？

如果你的重点是 tokens 与 UI 实现：

1. 阅读 SKILL.md，尤其是 "When to Use" 和 "Token Architecture" 部分。

2. 打开 references/token-architecture.md 以及 primitive/semantic/component 相关参考。

3. 复制 templates/design-tokens-starter.json 并创建你的 tokens.json。

4. 运行：

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

这样即可获得一套可用的 token 流水线，而无需接触幻灯片系统。

ckm:design-system 适合小型项目吗？

可以使用，但它的优势更适用于：

• 有多人共同参与 UI 或 deck 制作
• 需要强调一致性和可扩展性
• 品牌或产品预期会持续迭代

对于一次性的落地页或单次内部汇报，完整系统可能结构略显“重”。你仍然可以单独借用 token 架构或幻灯片文案公式作为轻量级参考。

如何查看该技能包含的全部内容？

在你的技能浏览器或文件管理器中，查看 design-system 技能的完整目录树，重点关注：

• SKILL.md
• data/
• references/
• scripts/
• templates/design-tokens-starter.json

这样可以看到所有嵌套的参考文档和辅助脚本，从而决定要在自己的工作流中集成哪些部分。