frontend-design-writer

Packaged Knowledge Snapshot

This packaged copy includes local note snapshots for portability. When the original Obsidian absolute path is unavailable, use the packaged snapshot instead:

• /Users/kunkun/note/01-AI工程/AI设计与前端/01-认知框架/AI前端设计认知框架.md -> references/packaged-knowledge/AI前端设计认知框架.md
• /Users/kunkun/note/01-AI工程/AI设计与前端/01-认知框架/主语言是设计的第一原则.md -> references/packaged-knowledge/主语言是设计的第一原则.md
• /Users/kunkun/note/01-AI工程/AI设计与前端/01-认知框架/六维：形色字构质动是网站试吃的机械骨架.md -> references/packaged-knowledge/六维：形色字构质动是网站试吃的机械骨架.md
• /Users/kunkun/note/01-AI工程/AI设计与前端/02-执行方法/AI 前端动效盲区与采访补偿.md -> references/packaged-knowledge/AI 前端动效盲区与采访补偿.md
• /Users/kunkun/note/01-AI工程/AI设计与前端/02-执行方法/动效文档两层：MOTION-SPEC vs 实现 prompt 集.md -> references/packaged-knowledge/动效文档两层：MOTION-SPEC vs 实现 prompt 集.md
• /Users/kunkun/note/01-AI工程/AI设计与前端/02-执行方法/深度采访双轮：产品设计师视角的横切机制.md -> references/packaged-knowledge/深度采访双轮：产品设计师视角的横切机制.md
• /Users/kunkun/note/01-AI工程/AI设计与前端/02-执行方法/视觉锚定三件套：代价结构与资产生成双路径.md -> references/packaged-knowledge/视觉锚定三件套：代价结构与资产生成双路径.md

Frontend Design Writer

这个 skill 在做什么

把前端阶段 1-4 的所有产出（主语言、六维试吃数据、双轮采访记录、视觉锚定三件套、资源选型）压缩成三份 Agent 可执行的交付文件。核心过程是三轮写作，不是从 §1 顺着写到 §14。

在阶段化流程里的位置

本 skill 贯穿阶段 1-7（见 [[AI前端设计认知框架]]），是所有其他前端 skill 的汇总写手：

阶段1 前轮采访 ─┐
阶段2 六维试吃 ─┤
阶段3 后轮采访 ─┼─→ design.md 初稿 → 定稿
阶段4 视觉锚定 ─┘    ↓
                    §12 §13 §14 引用视觉锚定三件套
                    ↓
阶段6 代码实现 ──── Pre-flight 外显化读本文件
                    ↓
阶段7 迭代微调 ──── review 反写回本文件

kun 15 段分工：

• §0-§11：原 12 段（主语言 + token + Agent prompt guide + motion spec + interview）
• §12 Moodboard Prompt（视觉锚定 A）：引用 knowledge/design-docs/visual-anchors/moodboard-prompt.md
• §13 Page Mockup Prompt（视觉锚定 B）：引用 knowledge/design-docs/visual-anchors/mockup-*.md
• §14 Motion Prompts（视觉锚定 C + 动效微观层）：引用 knowledge/design-docs/visual-anchors/motion-frames/ 和 knowledge/design-docs/motion-prompts/

何时进入本 skill

要进：

• 阶段 2 试吃六维刚完成，knowledge/design-docs/ 下已有调研产出，需要落成 design.md 初稿
• 阶段 3 后轮采访完成，design.md 定稿
• 阶段 4 视觉锚定三件套选定后，§12-§14 引用段落要更新
• 阶段 7 迭代微调收敛的 token/motion/Tweak 要反写回 design.md
• 用户说"写 DESIGN.md" / "把调研结果转成交付文件" / "生成设计文件"
• 项目迭代后需要更新 DESIGN.md（已有旧版，需要根据新调研或新决策刷新）

不要进：

• 还没有调研产出 → 先走 frontend-design-research
• 还没做双轮采访（产品边界模糊） → 先走 frontend-interview-dualround
• 整个项目 knowledge/ 骨架从零搭 → 先走 req-suite:project-spec
• 生成某个核心动效的微观实现 prompt（LoadingScreen 风格） → 走 frontend-motion-prompt-writer
• 派生 Moodboard / 示意图 / 帧序列图 → 走 frontend-visual-reference
• 纯代码实现任务 → 走开发实现剧本
• 只改一个颜色值或字号 → 直接编辑对应文件

知识库依赖

本 skill 只是"写作剧本"，方法论住在下面这几份笔记里，不复制。

文件	用途	何时读
/Users/kunkun/note/01-AI工程/AI设计与前端/03-交付契约/DESIGN.md 写作与分发手册.md	kun 15 段完整模板 + 三轮写作顺序 + CLI 双路径 + 字数预算	启动必读
/Users/kunkun/note/01-AI工程/AI设计与前端/03-交付契约/DESIGN.md 格式与七层框架的位置.md	为什么拆三份、和 alexpate/Stitch 的关系	用户问"为什么要三份文件"时读
/Users/kunkun/note/01-AI工程/AI设计与前端/01-认知框架/AI前端设计认知框架.md	阶段化流程总图（本 skill 的定位）	启动时扫阶段总表
/Users/kunkun/note/01-AI工程/AI设计与前端/01-认知框架/主语言是设计的第一原则.md	主语言的 5 问验证法 + 通道分工	Round 1 写 §0 时读
/Users/kunkun/note/01-AI工程/AI设计与前端/01-认知框架/六维：形色字构质动是网站试吃的机械骨架.md	六维骨架——把调研产出挂到六维下	Round 2 组织 token 时读
/Users/kunkun/note/01-AI工程/AI设计与前端/02-执行方法/视觉锚定三件套：代价结构与资产生成双路径.md	§12-§14 的内容来源	写 §12-§14 时读
/Users/kunkun/note/01-AI工程/AI设计与前端/02-执行方法/动效文档两层：MOTION-SPEC vs 实现 prompt 集.md	§10 宏观 vs §14 微观 prompt 的分层	写 §10 和 §14 时读
/Users/kunkun/note/01-AI工程/AI设计与前端/02-执行方法/AI 前端动效盲区与采访补偿.md	动效量化语法 + 双向性约束	Round 3 写 §10 时读
/Users/kunkun/note/01-AI工程/AI设计与前端/02-执行方法/深度采访双轮：产品设计师视角的横切机制.md	§11 Interview 的采访来源结构（双轮）	写 §11 时读

启动时只拉第一份，其他按触发条件读。

前置检查

进入写作前先确认五个前提（§12-§14 的前提非强制，等视觉锚定完成后回来补）：

前提	检查方式	缺失时怎么办
前轮采访完成	design.md §0-§1 目标与主语言有值，来自 dualround 前轮	路由到 frontend-interview-dualround 前轮
六维调研产出存在	knowledge/design-docs/ 下有六维试吃记录或等价 DESIGN-CONTEXT.md	路由到 frontend-design-research
主语言已定义	Main Language 段非空，且是动词句式不是形容词	路由回 frontend-design-research 主语言步骤
后轮采访完成（定稿时）	架构 / section / 文案调性 / 交互路径四类有答案	路由到 frontend-interview-dualround 后轮
动效素材存在	motion 记录有至少 1 条量化语法条目（工具型可近空但要显式"动效极简"声明）	路由回 frontend-design-research 动效采访

§12-§14 视觉锚定引用段的前提（阶段 4 完成后回填）：

• §12 Moodboard 选定 → 回填 moodboard-prompt.md 路径
• §13 完整网页示意图产出 → 回填 mockup-*.md 路径
• §14 帧序列 + 实现 prompt 到位 → 回填 motion-frames/ 和 motion-prompts/ 索引

执行顺序：四轮写作（原三轮 + Round 4 视觉锚定回填）

Round 1 定调 → Round 2 量化 → Round 3 组装 → Round 4 视觉锚定引用（§12-§14）

不要从 §1 顺着写到 §14。顺着写的常见失败：先写 §4 组件，发现没有 §0 主语言指导就不知道按钮应该 sharp 还是 round。

Round 1-3 覆盖原 12 段（§0-§11），Round 4 在阶段 4 完成后回填 §12-§14 三段视觉锚定引用——不是一次性写完 15 段，是分两次。

---

Round 1：定调（§0 + §7 + §11）

目标：先建叙事透镜，后面所有 token 取舍被它约束。这一轮不写任何 hex 值。

§0 Main Language（30-50 行，最重要）

• One-Sentence Narrative：动词句式，不是形容词。"滚动时混沌收敛为有序" ✓，"高级极客感" ✗
• Time Dimension：用户从打开到离开经历什么变化（初始状态 / 中段 / 终态）
• Channel Assignments：8 个通道（动效/字体/布局/背景/颜色/文案/细节/交互）各承载什么
• Intentional Rejections：为了主语言清晰，主动放弃什么
• Anchor Reference：哪个已有作品体现了类似主语言

§7 Do's and Don'ts（20-30 行）

• Do 8-10 条：写清楚参数，不写抽象原则
• Don't 8-10 条：列出反模式和它会破坏什么

§11 Interview & References（20-40 行）

• Visual Thesis Source：主语言从用户哪段话追问出来
• Anti-References：明确不想要的方向 + 理由
• Validation Log：留空，后续迭代填写
• Open Questions：尚未拍板的事项

---

Round 2：Token 量化（§2 + §3 + §5 + §6 + §8）

目标：从 DOM 量化数据机械提取。这是机械劳动，可选 npx getdesign 起手。

§2 Color Palette & Roles（30-50 行）

• 按 Background Surfaces / Text & Content / Brand & Accent / Status / Border 五类分组
• 每个颜色必须有语义名 + hex + 用途描述

§3 Typography Rules（40-60 行）

• Font Family + OpenType features
• Hierarchy 表：Role / Font / Size / Weight / Line Height / Letter Spacing / Notes
• 覆盖 Display XL 到 Mono 至少 10 个层级
• Principles 3-5 条非显然规则

§5 Layout Principles（20-30 行）

• Spacing System（base unit + scale）
• Grid & Container（max width + hero + feature sections）
• Whitespace Philosophy
• Border Radius Scale

§6 Depth & Elevation（15-25 行）

• 5-6 级 elevation 表（Level 0 到 Level 5）
• Shadow Philosophy

§8 Responsive Behavior（20-30 行）

• Breakpoint 表（5 档）
• Touch Targets
• Collapsing Strategy（字号/nav/卡片/间距各自怎么缩）
• Image Behavior

CLI 起手式：如果时间紧，先跑 npx getdesign@latest add <气质最近的站> 拿到 Stitch 9 段骨架，再用调研的 DOM 量化数据逐段校正。

---

Round 3：组装（§1 + §4 + §9 + §10）

目标：把 Round 1+2 的材料组装成 Agent 可执行的形式。这是创造性劳动。

§1 Visual Theme & Atmosphere（15-25 行）

• 一段主叙事描述（250-400 字）
• Key Characteristics 6-10 条

§4 Component Stylings（60-100 行，最长的段）

• Buttons（Primary / Ghost / Icon / Pill 各自 default/hover/focus 三态参数）
• Cards & Containers
• Inputs & Forms
• Badges & Pills
• Navigation
• Image Treatment

§9 Agent Prompt Guide（30-50 行，DESIGN.md 最有价值的一段）

• Quick Color Reference（7-8 个常用颜色快速查表）
• Example Component Prompts（至少 5 条覆盖 hero / card / badge / nav / special）
• Iteration Guide（3-7 条 Agent 迭代时的不变量）

§10 Motion Spec（40-80 行，最难写的段）

• Motion Philosophy（动效在主语言里扮演什么角色）
• Global Rules（双向性默认、Easing 库、Duration 库、Stagger）
• Core Motion Catalog（用量化语法 [触发] → [主体] → [变化] → [时序]）
• Layer Hierarchy（多动效共存时的优先级）
• Motion Don'ts
• Source（每条动效的采访来源）

§10 是 MOTION-SPEC.md 给 Agent 的压缩版，两份内容应同步。

---

Round 4：视觉锚定引用（§12 + §13 + §14，阶段 4 完成后）

目标：把视觉锚定三件套（由 frontend-visual-reference 产出）+ 动效微观 prompt（由 frontend-motion-prompt-writer 产出）的路径索引进 design.md。这一轮只写引用+元信息，不复制正文。

§12 Moodboard Prompt（8-15 行）

• Prompt 文件路径：knowledge/design-docs/visual-anchors/moodboard-prompt.md
• 状态：draft / generating / locked（选定哪张）
• 选定版本：v1 / v2 / v3
• 核心要素清单一行概述（色板 / 材质 / 符号族 / 字体 / UI 片段 / 反例）

§13 Page Mockup Prompt（10-20 行）

• 主页 prompt 文件：knowledge/design-docs/visual-anchors/mockup-home.md
• 子页 prompt 文件清单：mockup-{feature/pricing/...}.md
• 每个 mockup 的状态：draft / locked
• 生成顺序说明（先主页 → OK → 子页，单线）

§14 Motion Prompts（15-30 行）

• 帧序列 prompt 目录：knowledge/design-docs/visual-anchors/motion-frames/
• 实现 prompt 目录：knowledge/design-docs/motion-prompts/
• 核心动效组件清单表格：

  | 组件 | 帧序列 prompt | 实现 prompt | 状态 |
  | LoadingScreen | motion-frames/loading.md | motion-prompts/LoadingScreen.md | locked |
  | Hero 入场 | motion-frames/hero-entry.md | motion-prompts/HeroEntry.md | draft |
  

• §14 vs §10 分工提示：§10 宏观清单（人读），§14 微观 prompt 索引（Agent 写代码时读）

---

产出规格

三份文件写入项目 knowledge/design-docs/：

DESIGN-LANGUAGE.md（给人读，低频更新）

内容	来源
一句话主叙事（动词）	Round 1 §0
时间维度	Round 1 §0
8 个通道各自角色	Round 1 §0
"不做什么"清单 + 理由	Round 1 §0 + §7
参考锚点	Round 1 §0
采访溯源	Round 1 §11

项目第一周定完就锁。后续迭代不动这份。

DESIGN.md（给 Agent 读，kun 15 段，高频更新）

400-600 行。格式见上方四轮写作的 §0-§14 完整结构。前 9 段保持与 Stitch / getdesign CLI 生态兼容，§10-§14 是 kun 版差异化段。

Frontmatter：

---
status: signal
last_updated: YYYY-MM-DD
source: frontend-design-writer skill
---

MOTION-SPEC.md（人+Agent 并读，中频更新）

内容	来源
每个核心动效的量化语法	调研阶段 motion-spec.md + Round 3 §10
双向性约定	动效采访
层级关系	动效采访
反例清单	动效采访
采访来源	动效采访记录

DESIGN.md 的 §10 是本文件给 Agent 的压缩版，两份同步维护但各服务不同读者。

小项目合并规则：小项目 / 原型可以把三份合成单份 DESIGN-CONTEXT.md，但要保留三段结构（主语言段 + token 段 + 动效段），不退回到"一段话模糊描述"。

---

CLI 快速路径

时间紧或原型阶段的简化流程：

1. 跑 npx getdesign@latest add <气质最近的站>（30 秒拿到 Stitch 9 段骨架）
2. 手写 §0 Main Language（哪怕只有 2-3 行，也比没有强）
3. 手写 §10 Motion Spec（哪怕只有 3 条核心动效的量化语法）
4. 跳过 §11
5. 在文件头标注 ## ⚠️ Fast-path delivery — 缺少完整动效采访和参考溯源

CLI 的三个硬限制（始终记住）：

• 没有主语言（§0 空）→ 做出来的网站像"XX 风格的皮肤"，没有自己叙事
• 没有动效（§10 空）→ 静态像，动起来像 PPT
• 没有反向追溯（§11 空）→ 只能照搬不能灵活迁移

项目类型裁剪

项目类型	写哪几段	大约行数	说明
小项目 / 原型	§0 + §2 + §3 + §9	~80 行	剩下让 Agent 自由发挥
工具型 / 应用型	§0 + §2 + §3 + §4(重) + §5 + §8(压缩) + §9 + §12 + §13	~250 行	§4 最重，§10/§14 近空（工具型跳过动效帧序列），§8 桌面优先
单页 landing	§0 + §1 + §4 + §9 + §10 + §12 + §13 + §14	~350 行	§10/§14 是关键，展示型动效决定品质
完整品牌站	全 15 段	400-600 行	标准流程

完成标准

初稿（Round 1-3，§0-§11）：

• 三份文件都已写入 knowledge/design-docs/
• DESIGN.md 的 §0 主语言是动词句式（不是"高级""极客"这类形容词）
• DESIGN.md 的 §9 Agent Prompt Guide 有至少 5 条 Example Component Prompts
• DESIGN.md 的 §9 Agent Prompt Guide 可直接复制到生成 prompt 使用
• MOTION-SPEC.md 每条核心动效有量化语法 [触发] → [主体] → [变化] → [时序]
• MOTION-SPEC.md 每条核心动效标注采访来源
• 展示型项目核心动效标明双向性约定（禁止 whileInView + once: true）
• §11 Interview 记录前轮 + 后轮双轮采访来源
• 三份文件都有 status: signal frontmatter
• 用户确认主语言和动效约束无歧义

定稿（Round 4，§12-§14 回填，阶段 4 完成后）：

• §12 Moodboard Prompt 路径就位，locked 版本已选定
• §13 Page Mockup Prompt 主页 + 所需子页都有文件路径
• §14 Motion Prompts 核心动效清单表格填满（组件 / 帧序列路径 / 实现 prompt 路径 / 状态）
• §14 和 §10 分工提示存在（避免 Agent 把宏观清单和微观 prompt 混淆）

与其他 skill / 剧本的边界

场景	走谁
已定稿项目的二开 / 增量扩展（反写 §4 / §5 / §9 / §14 增量条目 + 追加 §15 迭代日志）	frontend-iteration-planner（场景 C 入口；完成后回本 skill 做增量反写）
产品边界模糊，需要前轮/后轮采访	frontend-interview-dualround（阶段 1 前轮 / 阶段 3 后轮）
还没做六维调研	frontend-design-research（阶段 2）
派生 Moodboard / 示意图 / 帧序列图	frontend-visual-reference（阶段 4）
某个核心动效组件要生成 LoadingScreen 风格的微观实现 prompt	frontend-motion-prompt-writer（§14 实现 prompt 的具体内容生成器）
整个项目 knowledge/ 骨架从零搭	req-suite:project-spec（搭到占位后移交本 skill）
已有三份交付文件，要写代码实现	开发实现剧本（读本 skill 产出的文件作为约束），同时挂 frontend-anti-slop-gate
实现后发现"感觉不对"要评审	frontend-design-review（阶段 7）
只改一个颜色 / 字号	直接编辑对应文件
项目收尾要把开发中调过的动效回灌	回到 frontend-design-research 跑汇总采访，再回本 skill 更新 §10 / §14