前言
没有万能的可视化按钮
当你让 Claude 构建一个 HTML 页面时，质量往往不在于「让它更好看」，而在于被调用的 skill。ClaudeKit 没有把可视化功能合并成一个万能命令，而是拆分为多个小 skill，每个 skill 处理的范围相当窄。最常见的混淆是把所有 skill 视为同一类，结果架构文档看起来像落地页，产品 UI 又像内部文档。
今天的内容使用一张定位地图，围绕思维编排和界面执行两个轴展开，再应用到一个真实问题：完整可视化一个 plan 文件。在第 03 部分，费用审批应用的示例 plan 会真实运行；截图保留作为凭证，prompt 可直接 copy-paste 复用。
读示例前的一个说明：在 ClaudeKit 中，preview、frontend-design、stitch、tech-graph、show-off 都是通过自然语言调用的 skill（prompt-driven），不是有 flag 可以手动输入的 CLI 命令。
当文章提到 flag 时，指的是 skill 在内部自动运行的脚本的 flag，不是与 slash command 一起手动输入的参数。一个例外是 preview 的生成 flag，如 --explain、--diagram、--slides、--html，因为它们是调用该 skill 语法的一部分。
还有一点会在第 02 部分详谈：从稳定版 engineer@v2.20.0 起，--html 不再是 preview 专属，/ck:brainstorm 和 /ck:plan 都接受它。
01
定位地图：/ck:preview vs /ck:frontend-design
这两个 skill 经常被混淆，因为都能输出好看的 HTML，都关注排版和色彩，都有防止千篇一律的规则。区别在于输出契约：preview 生成的是供团队理解、对照和决策的文档；frontend-design 生成的是用户可以像使用产品一样交互的 UI。
/ck:preview：可视化编排
当需要预览文件/目录，或在 /ck:plan、/ck:debug 之后快速构建说明文档时使用。它是 topic、git 上下文、explanation、slides、diagram 或 dashboard review 的中转站。
/ck:frontend-design：界面执行
当目标是为终端用户创建完整 UI 时使用。它在有设计来源时表现最佳：截图、示例流程视频，或详细的描述。
/ck:preview --html --explain "博客 i18n 管线：从 HTML 源经 JSON 到 4 个 locale 路由"
/ck:preview --html --slides "Astro + Turborepo monorepo 架构"
/ck:preview --diff HEAD~3preview 的 style 理念是一致性。它从预定义的固定 preset 列表中选择风格，并在多次生成之间轮换以避免字体和调色板重复。HTML 滚动页面有 6 个 preset：Blueprint、Editorial、Paper-Ink、Terminal Mono、Swiss Clean、Warm Signal。幻灯片有另外 4 个 preset：Midnight Editorial、Warm Signal、Terminal Mono、Swiss Clean。附带一条强制规则：它生成的每个 HTML 页面必须有 light/dark 主题切换，且必须是 <body> 的第一个子元素。没有切换则未完成。
/ck:frontend-design 用 HTML/Tailwind 复刻这张截图里的 UI [+ 附图]
/ck:frontend-design 订单管理仪表盘，高密度数据行。DESIGN_VARIANCE=4, VISUAL_DENSITY=8frontend-design 的 style 理念走向相反：差异化。默认 DESIGN_VARIANCE=8，目标是不让两个设计看起来相同。有三个Design Dials可以直接在 prompt 中声明以进行控制。
| Dial | 默认 | 低 | 高 |
|---|---|---|---|
DESIGN_VARIANCE |
8 | 对称、居中 | 非对称、masonry、刻意留白 |
MOTION_INTENSITY |
6 | 仅 hover/active | 滚动触发动效、spring 动画 |
VISUAL_DENSITY |
4 | 大 whitespace，干净 | 小 padding、等宽数字、cockpit 风格 |
快速路由表
| 输入 | 调用 | 原因 |
|---|---|---|
| 一个需要向团队解释的 topic | preview --html --explain "<topic>" |
输出是可读文档，含 Mermaid |
| 一个需要演示的 topic | preview --html --slides "<topic>" |
幻灯片引擎，viewport 自适应 |
| 一个 git 范围 / PR | preview --diff <ref> |
Review dashboard，读取真实 git 数据 |
| 一个需要与代码对照的 plan | preview --plan-review <plan> |
将 plan 与实际 codebase 对比 |
| 一个 UI 的截图/视频 | frontend-design + 附件 |
复现工作流 |
| 一段 UI 描述 + Design Dials | frontend-design |
构建生产级 UI |
两个 skill 并不互斥。它们处于同一开发循环的不同阶段：preview 检验思维部分，例如 plan 是否与 codebase 一致，流程是否清晰，diff 的 blast radius 有多大；frontend-design 构建和检验产品的 aesthetic 部分。
02
卫星 skill 体系
第 01 部分的两个核心轴并不孤立。围绕它们有一组辅助 skill，按三类能力划分。掌握这些分组可以更准确地调用 skill，也更容易在出问题时调试。
/ck:ui-ux-pro-max 定义布局、排版、间距、调色板和 UX guideline。这是 frontend-design 的必要基础。
/ck:tech-graph 输出发布级 SVG/PNG；/ck:mermaidjs-v11 保证 markdown 架构图的语法正确。
/ck:markdown-novel-viewer 负责阅读体验；/ck:show-off 打包 brief、内容、HTML、截图和 showcase。
/ck:brainstorm 和 /ck:plan 现在接受 --html，在 markdown 文件之外再输出一份可直接在浏览器打开的 HTML 页面。
分组 1：设计智能
/ck:ui-ux-pro-max 是设计智能引擎。它是 frontend-design 的必要基础，因为每个工作流都会先激活它，同时也被推荐用于 preview --slides。底层是一个在大型 CSV 数据集上的 BM25 搜索引擎：包含众多风格、数百种调色板、字体配对、产品类型、UX guideline、图表类型。它在生成代码之前先定义设计 token 体系，如布局、排版、间距。
需要记住的优先级规则：当 ui-ux-pro-max 的推荐与 anti-slop rules 冲突时，例如建议使用 Inter 字体或紫色调色板，anti-slop rules 优先，除非用户明确要求。
分组 2：架构图化
/ck:tech-graph 用于输出发布质量的架构图。该 skill 生成清晰的 SVG 和 PNG，可插入文章、幻灯片或交付文档。支持 8 种风格：Flat Icon、Dark Terminal、Blueprint、Notion Clean、Glassmorphism、Claude Official、OpenAI Official、Dark Luxury。调用方式是用自然语言描述系统和期望的风格。skill 会在内部自动运行 generate-diagram.sh 脚本来验证 SVG 并导出 PNG。
/ck:mermaidjs-v11 是文本形式架构图的语法验证器。适合快速构建嵌入内部 markdown 的 flowchart、sequence、state diagram，同时确保符合 Mermaid v11 语法。preview 每次生成 Mermaid 时都会调用该 skill。这是一个纯 reference skill，也可以单独使用。
三个 diagram skill 的边界相当清晰：diagram 是独立图片文件需要在其他地方使用，就用 tech-graph；diagram 嵌入 markdown，就用 mermaidjs-v11；diagram 存在于一个 HTML 说明页面内，就用 preview --diagram。
分组 3：展示与阅读体验
/ck:markdown-novel-viewer 是 preview view 模式背后的服务器。它将 markdown 渲染成专用阅读页面：衬线字体、暖色背景、限制宽度，适合长文档。一个容易被忽视的亮点是它支持在阅读页面内渲染 Mermaid，包括 flowchart、sequence、gantt、mindmap，支持 theme-aware 和全宽切换。
/ck:show-off 是从 brief 到 social asset 的端到端 pipeline。一个常见误解：show-off 不会自动扫描 repo 中的现有 asset 并汇集成 gallery。它运行一个 self-contained 的 mission：research/fact-check、撰写双语内容、激活 frontend-design 构建 HTML、运行 Puppeteer 多比例截图，然后输出 showcase。frontend-design 只是其中一个步骤。
第 4 组：Brainstorm 与 plan 导出为 HTML
直到不久前，--html 几乎只和 preview 绑定。从稳定版 engineer@v2.20.0（随 ClaudeKit CLI 4.5.0 发布）起，brainstorm（权衡想法与方案的 skill）和 plan（拟定实施计划的 skill）也接受同一个 flag。这两个 skill 过去只返回 markdown 文本，如今还能输出一份可直接在浏览器阅读和分享的 HTML 页面。
/ck:brainstorm --html 先写好 markdown，再增加一份杂志风格的 HTML 页面：相同的决策与证据，但更清晰地呈现最关键的取舍、假设和最终建议。这份 HTML 是可直接打开的独立页面，方便发给没参加讨论的人。
/ck:plan --html 更进一步：主要产物是 plan.html，一个可交互的 plan 页面，可逐个点开 phase、在弹窗里查看每一步的细节，并附可选的技术示意图。对本文值得注意的一点：在生成 HTML 之前它会调用 /ck:frontend-design，因此也走一遍 ui-ux-pro-max 的 design intelligence 流程。HTML 页面只在 plan 通过 red-team 复盘与 validation 校验之后才生成，因此反映的是最终的 plan。
/ck:brainstorm --html "为博客选择 i18n 同步机制：build-time inject
vs runtime fetch vs content collection"
/ck:plan --html "为整个博客新增第 5 个 locale（ko），从 i18n JSON 到现有的 4 条路由"实用要点：brainstorm 和 plan 并不与 preview 竞争。preview 仍是从一个 topic 或 git context 快速生成说明文档的方式；而 brainstorm 和 plan 上的 --html 把 HTML 页面附在该会话产出的那份 brainstorm 或那份 plan 本身上，而不是另写一份说明。
03
案例研究：完整可视化一个 plan 文件
问题：有一个 plan 文件。目标是完整可视化：系统架构、示意界面、运行流程。没有单一 skill 能完整处理，因为问题跨越两个独立的能力组：解释与架构图以及真实 UI mockup。
案例研究使用的 plan 是一个内部费用审批应用：6 个实体（Employee、ExpenseClaim、LineItem、Approval、Payment、AuditLog），一个 5 状态的状态机，5 个 UI surface。plan 的实体和动作足够明确，skill 可以据此推导工作流、架构和 UI。
有一点需要澄清以正确使用：preview --explain 和 preview --diagram 接收一个topic 字符串，不会自动解析 plan 文件。正确的语法是 flag 在 topic 之前：/ck:preview --diagram "<描述>"，而不是 /ck:preview <path> --diagram。
方案 1：快速通道（2 条命令）
适合需要快速验证想法、接受草稿版本时使用。
/ck:preview --html --explain "报销审批应用：从 SPA 到 PostgreSQL 共 5 层，
状态机 draft→submitted→under_review→approved→paid，5 个界面"
/ck:stitch "根据 plan 中的 workflow 推断报销审批应用的 UI 屏幕；
在生成前先列出屏幕清单供我审阅"- 命令 1 生成一个自包含 HTML 文件：概览、ASCII 快速预览、Mermaid 架构流程、关键概念。所有内容在一个页面，有主题切换。
- 命令 2 让
stitch从 plan 的功能逻辑中自行推导界面结构。「在生成前先列出 screen list」是最关键的检查点。
方案 2：完整流程（4 个步骤）
完整流程，用于为客户生成设计文档包或项目文档。以下是每个步骤的真实运行结果。
architecture
approval queue
state machine
showcase
步骤 1：使用 tech-graph 生成架构图
/ck:tech-graph 报销审批应用架构图：5 层 Frontend（5 个屏幕）→
API（基于角色）→ Service（ClaimService 拥有 state machine、Approval、Payment、Audit）
→ Data（PostgreSQL）+ Storage（receipts）。Blueprint 风格。skill 按 Blueprint preset 编写 SVG：点阵背景、等宽字体、青色 accent。然后验证并导出发布级 PNG。结果有清晰的 5 个层级，箭头路由不穿过方框，底部有状态机标注，ClaimService 以绿色高亮因为它持有状态机，AuditService 为橙色。
步骤 2：使用 frontend-design 生成详细界面
/ck:frontend-design 报销审批应用的 Approval Queue 界面（桌面端，dev-tool 风格）。
侧边栏导航 + 主从布局：左侧待审批 claim 列表，右侧 line item 明细 + approve/reject
按钮。按状态着色的徽章。DESIGN_VARIANCE=4, VISUAL_DENSITY=8结果保持了重要的 anti-slop 规则：避免 Inter/Roboto，使用带色调的深黑而非纯黑，只用一个金色 accent，master-detail 布局而非三等分 card，copy 更真实，包含多样化姓名和自然的非整数，如 $1,247.30 而非整数。under_review / submitted 徽章按状态机进行颜色编码。
步骤 3：使用 preview --html --slides 生成工作流演示
/ck:preview --html --slides "一笔 expense claim 的生命周期：employee 创建并提交 → manager
审批 → accountant 付款，附带 state machine 和 3 个 guardrail"幻灯片 viewport 自适应，使用 Midnight Editorial preset：衬线字体、金色 accent、深海军蓝。该风格与步骤 1 的 Blueprint 截然不同，符合多输出之间变换 aesthetic 的规则。幻灯片有进度条、页码和主题切换。以下是暗色主题的标题幻灯片和亮色主题的状态机幻灯片，展示切换效果。
步骤 4：使用 show-off 汇总与展示
/ck:show-off 展示页 "Expense Approval — 可视化档案"，将架构图
（步骤 1）、Approval Queue 界面（步骤 2）和 workflow 幻灯片（步骤 3）整合为带
导航锚点的 section，直接在浏览器打开、无需服务器。show-off 是最终的汇总步骤。它将架构图和 UI 界面整合成一个 self-contained 的 HTML 页面。在本案例研究中，图片以 base64 嵌入，只需打开一个文件即可运行。页面有导航锚点、标注所用 skill 的 footer 和主题切换。直接在浏览器中打开，无需服务器。
Token 成本。4 步流程消耗的 token 相当可观，因为每个 tech-graph/frontend-design/preview/show-off 都是单独生成输出的一次 pass。如果只需要一个足够用于审阅方向的版本，回到方案 1 即可。
04
技术区分：/ck:frontend-design vs /ck:stitch
在构建 UI 的步骤，即上述步骤 2 或命令 2 中，决策关键在于是否已有设计来源，或者需要 Claude 自行推导。
/ck:frontend-design 是复现
当已有设计资源来源时使用：Figma 设计稿、示例截图，或具体的交互流程。skill 以来源为真值严格复现，用真实 HTML/Tailwind 构建。
/ck:stitch 是推导
当没有设计样本时使用。skill 通过从功能逻辑推导布局来填补 UI 空白，基于工作流的名词和动词。
| 场景 | Skill | 本质 |
|---|---|---|
| 有截图/Figma/mockup 可参考 | frontend-design |
精确复现 |
| 只有工作流描述，自行推导 UI | stitch |
推导与组合 |
让 AI 自行推导界面的 3 个重要注意事项
- 生成前先确定 screen 列表。如果跳过此步，AI 容易自行生成超出范围的附加界面，既消耗 token 又稀释主流程。
- 一开始就声明 Design Dials。在第一次调用中明确设置
DESIGN_VARIANCE、VISUAL_DENSITY、MOTION_INTENSITY，以免各界面的 aesthetic 风格偏差。 - 保留 anti-slop guard。阻断默认的 Roboto/Inter 字体、模板化的紫蓝渐变、整齐划一的三卡布局、霓虹光效、「John Doe」和 Latin 占位符。
两者的一个共同提示：它们能拦截假 copy，如「John Doe」、整数、陈词滥调，但真实的 copy 仍需人工撰写或审核。skill 不会自行编造准确的领域内容。
05
准备工作与注意事项
在将多个 skill 串联成链之前，应先检查依赖。所有 skill 都在 ClaudeKit 内，但运行环境仍有各自的部分：tech-graph 需要导出 SVG/PNG 的二进制文件（rsvg-convert），stitch 需要对应服务的 API key/配额，show-off 需要能运行 Puppeteer 的环境来截图。缺少某一环节就容易遇到难以预料的错误：图片导出失败、任务中途挂起，或日志只给出非常笼统的提示。提前检查可以省去大量排查时间。
- 为
show-off/tech-graph/stitch输入 flag 时当作 CLI 命令使用。它们是 prompt-driven，flag 属于内部脚本。 - 以为
show-off会自动扫描现有 asset。需要将 asset 传入 mission，skill 不会自行查找。 - 调用
preview --diagram <path-to-plan>。它接收 topic 字符串，不读取文件；flag 在 topic 之前。 - 让
stitch直接生成而未先确定 screen list。结果容易出现多余界面，浪费 token。 - 忘记幻灯片的 preset（4 个）与 HTML 页面的 preset（6 个）不同。Blueprint/Paper-Ink 没有幻灯片版本。
- 用
frontend-design绘制说明文档。输出的 aesthetic 通常对阅读目的来说过于厚重。
小结
按输出目的选择
思维 → preview。
产品 → frontend-design。
独立文件 → tech-graph。
嵌入 markdown → mermaidjs-v11。
在 HTML 页面内 → preview --diagram。
有 → frontend-design。
没有 → stitch。
show-off 是 self-contained 的 pipeline。
按顺序组合：tech-graph + frontend-design/stitch + preview --slides + show-off。
内部说明 → preview/preview --slides。
UI 评审 → frontend-design/stitch。
交给别人看 → show-off。
brainstorm → brainstorm --html。
plan → plan --html。
ClaudeKit 的可视化模块没有万能按钮，但按角色来看也并不复杂。它围绕编排和执行两个轴展开。先确定输出要服务什么用途：内部说明、UI 评审，还是打包后交给别人看。然后根据所需输出类型选择对应的卫星 skill。当问题跨越多个能力组时，按第 03 部分真实运行过的案例顺序组合使用，而不是强迫一个 skill 做另一个 skill 的工作。