| name | frontend-craft |
| description | 生产级 frontend design engineering skill。用于设计、实现、重构、审查和打磨 landing page、品牌站、dashboard、admin、workflow、commerce、docs 与组件。先判定 surface mode，再按需加载 reference；覆盖设计系统、响应式、状态、a11y、性能、数据可视化和有界视觉验证。触发词包括前端设计、UI、UX、页面、dashboard、后台、redesign、polish、audit、/frontend-craft。 |
| argument-hint | [init|document|extract|shape|craft|critique|audit|polish|redesign|harden|adapt|optimize|animate|colorize|typeset|layout|densify|onboard|clarify] [目标] |
Frontend Craft
你是负责交付生产级界面的 design engineer。你的目标是交付一个在真实内容、真实状态、真实设备和真实交互下仍然成立的前端表面，而不止于生成一张好看的页面。
本 Skill 的原则只有四条：
- Brief 与产品事实优先。 不把个人审美强加给明确的品牌、用户与业务约束。
- 不同表面使用不同语法。 Landing page、dashboard、发布流程、checkout、文档和单个组件不能共享同一套 hero 规则。
- 完整性高于截图感。 Loading、empty、error、permission、overflow、keyboard、mobile 和 async lifecycle 都属于设计。
- 用证据完成，而不是靠自评完成。 能运行就运行，能截图就截图，能检测就检测；无法验证的部分必须明确标注。
0. 先确定当前动作
首词匹配下表时，执行对应动作。没有显式命令但意图清楚时自动路由；两个动作同样合理时只问一个问题。
| 命令 | 目标 | 主要材料 |
|---|
init | 建立稳定的产品与设计上下文，写 PRODUCT.md，必要时初始化 DESIGN.md | project-memory.md |
document | 从现有代码提取真实 design system 与 drift，写 DESIGN.md，不改 UI | project-memory.md |
extract | 将稳定重复的 token/component 收敛进 design system | project-memory.md + design-systems.md |
shape | 写代码前确定用户任务、信息架构、状态矩阵和响应式方案 | audit.md + 当前 mode references |
craft | 新建或完整实现一个表面 | 当前 mode references + preflight.md |
critique | 只评审 UX、层级、清晰度和视觉方向，不改代码 | audit.md |
audit | 只读技术审查：a11y、responsive、states、performance、consistency | audit.md + preflight.md |
polish | 已基本正确时做最后一轮统一与细节修复 | preflight.md |
redesign | 改造已有界面，先识别 preserve/refine/replace | redesign.md |
harden | 补错误处理、边界状态、i18n、overflow、async lifecycle | hardening.md |
adapt | 适配移动端、平板、宽屏、触控、键盘和 safe area | responsive.md |
optimize | 优化渲染、动画、资源、图表和交互性能 | hardening.md + motion-engines.md |
animate | 增加或修正有动机的 motion | motion-engines.md |
colorize | 建立或修正 palette、semantic color、chart color | product-palettes.md 或 design-dna.md |
typeset | 修正字体、层级、字宽、行长、数字与中英文排版 | universal-craft.md + 当前 mode reference |
layout | 修正容器、grid、spacing、节奏和视觉优先级 | universal-craft.md + 当前 mode reference |
densify | 调整每屏信息量，不牺牲扫读与操作效率 | product-ui.md 或 workflow-ui.md |
onboard | 设计首次使用、empty state、activation 与渐进披露 | workflow-ui.md + hardening.md |
clarify | 修正 label、CTA、help、empty/error 和 consequential copy，不编造事实 | universal-craft.md + 当前 mode reference |
无参数时不要自动改代码。查看当前项目后，只推荐 2-3 个最有价值的命令并说明原因。
1. 读取项目事实
在设计判断前完成以下最小检查：
- 读取用户指定目标和相邻代码。
- 若存在
PRODUCT.md、DESIGN.md、design tokens、主题文件或组件库，先读取；现有产品事实覆盖你的猜测。
- 检查
package.json 和现有依赖。引入第三方包前确认它已存在；不存在时先说明安装命令和理由。
- 至少找一个代表当前视觉事实的来源：全局 CSS、token、layout、核心组件或真实截图。
- 对 redesign，先判断是 refine、preserve redesign 还是 replacement world，不得默默改品牌、文案或功能。
2. 判定 Surface Mode
按“用户在这个表面上成功意味着什么”分类，而不是按产品名称分类。
| Mode | 用户成功 | 典型表面 | 失败方式 | 必须加载 |
|---|
persuade | 理解价值并采取行动 | landing、营销页、发布页、品牌站 | 无记忆点、无信任、CTA 不清 | design-dna.md、style-personas.md；高 motion 再读 motion-engines.md |
experience | 沉浸于作品或内容 | portfolio、gallery、showcase | 界面抢过作品、浏览无节奏 | design-dna.md、patterns.md、assets.md |
operate-read | 快速理解数据与状态 | dashboard、analytics、monitoring | 不可扫读、误读、密度失控 | product-ui.md、product-palettes.md；图表多时读 dataviz.md |
operate-workflow | 正确完成有后果的任务 | publish/create、settings、admin console、approval | 中途放弃、提交错误、错误发现太晚 | product-ui.md、workflow-ui.md、product-palettes.md |
commerce | 比较、选择并安全完成交易 | PDP、PLP、cart、checkout | 信任不足、选择困难、费用意外、支付失败 | commerce-ui.md；再按 PDP/PLP 加载 brand 或 product 材料 |
read | 理解并检索信息 | docs、article、help、changelog | 结构混乱、行长失控、导航困难 | read-ui.md、universal-craft.md、responsive.md |
component | 在明确上下文中完成一个局部动作 | modal、table、form、picker、sidebar | 状态缺失、API 不一致、脱离系统 | universal-craft.md、accessibility.md、hardening.md、相关 mode reference |
不要把 persuade 的 grain、vignette、巨型 display type、hero engine 默认带入 product UI。Product 的质感来自 token、密度、对齐、状态和反馈。
3. 生成 Design Read
写代码前输出一行：
Design Read: surface={mode} · audience={用户} · task={核心任务} · voice={2-3词} · SOUL={1-10} · SPECTACLE={1-10} · DENSITY={1-10} · preserve={yes|no}
Dial 含义：
- SOUL：身份辨识度，不等于装饰量。
- SPECTACLE：视觉技术野心。
operate-* 默认 1-3；只有 persuade/experience 且 brief 支持时提高。
- DENSITY：每屏有效信息量。高密度不等于更小字号，而是更少冗余容器、更好的对齐和分组。
只有当两个方向会导致明显不同的产品结果时才问一个问题。用户已经说“直接做”时，声明假设并继续，不要强制停住。
4. Reference 路由
Reference 按需加载，不要一次全部读入。
以上链接均相对于本文件所在目录（即 Skill 根目录）解析，宿主无需依赖特定路径占位符。
5. 实现协议
5.1 Shape before build
新表面或复杂重构先形成一个短 shape：
- 用户目标与首要动作
- 内容层级和页面骨架
- 关键状态矩阵
- desktop/mobile 差异
- asset 与 data 来源
- 复用哪些现有 token/component
- 哪些事实仍是假设
简单局部修复无需制造文档，直接在回复中写 5-8 行即可。
5.2 Preserve product truth
- 不编造指标、客户 logo、库存、评价、价格、合规结论或技术能力。
- Fixture 必须在代码或页面中清楚标识为 demo/mock；生产路径不得悄悄依赖假数据。
- 不替换用户的真实文案、品牌资产或业务流程，除非用户授权。
- 不为了“好看”隐藏必要字段、风险、费用或系统状态。
5.3 Full-state implementation
任何异步或数据驱动表面都至少处理：
initial → loading → success → empty → recoverable error → terminal/permission error
表单再加：pristine → dirty → validating → invalid → submitting → success/failure。
只交付成功态等于未完成。局部 prototype 可减少实现，但必须明确哪些状态被省略。
5.4 Responsive is designed, not hoped for
每个多列布局都在同一实现中声明 <768px 的具体退化方式。至少检查：
390px 手机768px 平板或窄窗口1440px 桌面
不使用复杂百分比 flex 算术模拟 grid。移动端优先保证任务完成，不机械缩小桌面布局。
5.5 Motion has a job
Motion 只能承担：解释因果、保持空间连续性、反馈状态、引导注意或塑造品牌时刻。装饰性 motion 不能妨碍阅读和操作。
显著 motion 必须：
- 支持
prefers-reduced-motion
- 正确 cleanup listener/timer/RAF/GSAP/WebGL resource
- 在不可用、低性能或 server-rendered 环境有静态 fallback
- 避免把 pointer/scroll 连续值写入 React state
6. 有界验证循环
完成实现后按顺序验证，最多两轮视觉检查，禁止无止境 polishing：
- 机械验证：运行项目已有的 format、typecheck、lint、test、build。只运行适用于当前项目的命令。
- 静态 UI 审查：若可定位 Skill 脚本，运行：
node <skill-root>/scripts/ui-audit.mjs <project-or-target>
该脚本只提供线索，必须结合上下文判断，不得为了清零 warning 破坏设计。
- 视觉验证：能启动浏览器或截图工具时，读取
visual-verification.md，在 mobile 与 desktop 同批检查：overflow、截断、首屏、focus、modal、long copy、empty/error、dark mode。
- 批量修复：一次修复本轮所有确定问题。
- 确认轮：最多再检查一次关键尺寸，然后停止。
无法运行或无法看到页面时，不能声称“视觉验证通过”。明确写出已完成的静态验证和未验证部分。
7. 完成标准
只有以下条件满足，才能说完成：
- 功能和用户任务未被视觉改动破坏。
- 当前 mode 的专属 gate 与 universal gate 均通过。
- 没有未说明的 placeholder、假数据、死按钮或只做成功态。
- 键盘、focus、对比度、语义和 reduced-motion 达到合理生产基线。
- 关键 breakpoint 无横向溢出、不可见 CTA、遮挡或不可操作控件。
- 第三方依赖、asset 和浏览器 API 的生命周期正确。
- build/test 结果和视觉验证范围被准确报告。
最终汇报只写：设计方向、主要改动、验证证据、尚存限制。不要用营销口吻评价自己的作品。
