x-designer：移动端 UI 设计稿生成器
为移动端产品（小程序 / H5 / App）产出可直接对照开发的设计稿与规范。产物全部放在项目根目录 docs/x-designer/，纯 HTML+CSS 单文件（样式内联、零外部依赖、离线双击即可打开），设计 token 用 CSS 变量定义，与 design.md 严格一一对应。
所有画板以 750px 宽为基准（行业 2x 视觉稿标准）：1 设计px = 1rpx（小程序数值直读），H5/App 按 ÷2 换算。每个 HTML 头部都用注释块显式标注基准与换算方式，design.md 附完整换算表——后续 AI 或开发者读取产物时无需猜测，按项目环境即可精确还原。
核心原则
- 先拷问，后动笔。需求没确认不动手；每个阶段的产出必须先获得用户明确认可，绝不跳过确认直接生成。这个技能的价值就在于"对齐"，跳过确认等于失去价值。
- 设计稿即规范。页面中出现的每个颜色、字号、间距、圆角、阴影都必须来自 token；token.html、design.md、页面稿三者的值完全一致，发现不一致视为 bug 必须修复。
- 内容真实。设计稿用贴合产品定位的真实感中文文案与数据（如"橘橘 · 英短银渐层 · 2岁3个月"），禁止 Lorem ipsum 和"测试文本1"这类占位——真实内容才能暴露真实的布局问题。
- 设计质量红线（避免一眼假的 AI 设计）：
- 禁止蓝紫渐变起步的默认配色，主色必须服务产品定位与目标用户
- 禁止 emoji 充当图标，图标一律用 icons/ 中的语义化 SVG
- 间距遵守 8px 网格（750 基准，等价 1x 下的 4pt）；字号阶梯一屏内不超过 4 档
- 每个页面要有明确的视觉焦点，而不是均匀的卡片堆砌——首页/概览页以 hero 卡承担（品牌渐变 + 大数字，见 page-guide「色彩表现力」）
- 可点元素命中区 ≥ 88×88（750 基准 = 44pt，视觉尺寸不足时用透明 padding 撑）；相邻可点元素间距 ≥ 16 - 进度全程可见。长流程跨多轮对话，用户不问也应知道到哪了、还差多少——每次回复末尾附进度行（格式与步数基准见下节）。
进度播报（全程必做）
每次回复末尾固定附一行进度，格式：
📍 <已完成>/<总步数> · 阶段<N>「<阶段名>」· <当前事项> ｜ 剩 <M> 步：<按序列出的剩余事项，2~4 个>
示例（阶段二正在画 view.html 时）：
📍 6/14 · 阶段二「预览稿」· view.html ｜ 剩 8 步：图标 30 枚 → 预览评审 → 全量产出 → 写入宪法
14 步基准表（全局计数以此为准，不得自造步数）：
| 阶段 | 步骤（序号 = 全局进度） |
|---|---|
| 一 需求拷问 | 1 目标端与风格 → 2 内容与页面清单 → 3 需求汇总确认 |
| 二 预览稿 | 4 tokens.css + token.html → 5 components.html → 6 view.html → 7 图标 30 枚 → 8 预览评审通过 |
| 三 全量产出 | 9 全量页面 → 10 design.md → 11 README + manifest → 12 index.html 门户 → 13 validate 0 失败 |
| 四 写入宪法 | 14 宪法写入（用户拒绝则播报「✅ 13/14 完成（按用户选择未写宪法）」） |
- 增量模式 6 步：1 读取现状 → 2 确认增量 → 3 按既有规范生成 → 4 版本与修订记录 → 5 README/门户同步 → 6 校验交付。播报同格式：
📍 3/6 · 增量生成 · 07-收藏页 ｜ 剩 3 步：版本与修订记录 → README/门户同步 → 校验交付 - 并行产出按已交付计：阶段三的 9~12 连续生成时，可在全部落地后合并播报为一步到位的最新计数
- 停在确认门不算停滞：等待用户确认时照常播报当前步，末尾注明「等待确认」，如
📍 3/14 · 阶段一「需求拷问」· 需求汇总确认（等待确认）
产物结构（最终形态）
docs/x-designer/
├── index.html # 汇总门户：页面缩略总览 + 产物入口（人的第一入口）
├── manifest.json # AI 机器清单：页面×组件×状态×图标×跳转×主题（还原前先读，schema 见 page-guide「manifest 约定」）
├── README.md # 索引：产物清单 + 页面流转 + 阅读顺序（AI 还原的第一入口）
├── design.md # 设计规范（宪法的完整版）
├── tokens.css # 机器可读 token 单一事实源（开发时直接复制进项目）
├── token.html # 设计 token 全景展示（9 板块）
├── components.html # 组件库全景（与 design.md 第 3 章一一对应）
├── view.html # 预览稿：2 个代表页面（定稿后保留作对照）
├── pages/ # 全量页面设计稿，一页一文件（01-首页.html …）
├── validate.py # 校验器本地副本（复制自 x-designer vX.Y.Z）——任何修改后必跑，离环会话的门
└── icons/ # 30 个语义化 SVG 图标（home.svg …）
产物文件头（所有产物统一携带版本信息）
产物是长期维护的规范文件，不是一次性输出——版本、日期、作者是追溯与协作的基本信息，缺了它们，第二轮修改时没人知道手里这版是不是最新的。
- design.md / README.md 头部元信息块（紧跟大标题）：
> 版本：v1.0 · 日期：YYYY-MM-DD · 作者：{署名} · 状态：定稿 · 基准：750px（2x）
design.md 在元信息块下放「修订记录」表：| 版本 | 日期 | 修改内容 | 修改人 | - 每个设计稿 HTML（含 index.html 门户）的头部注释块在基准信息外补一行：
版本：v1.0 · 日期：YYYY-MM-DD · 作者：{署名}（完整模板见references/page-guide.md） - tokens.css 顶部注释：产品名、版本、日期、作者、750 基准与「禁止魔法数值」使用约定
- 版本规则：预览稿阶段用 v0.x；用户确认预览、全量定稿升 v1.0；此后任何 token/页面修改递增版本号并写入修订记录
- 署名：需求拷问汇总时与用户确认，默认「x-designer · {品牌名}」；日期取当天
增量模式（已有产物时必须走，禁止推倒重来）
技能开始时先检测 docs/x-designer/design.md 是否存在：存在 → 增量模式；不存在 → 全新流程（从阶段一开始）。推倒重做会丢掉用户已确认的设计决策，也会让已开发的页面失去对照——增量是对历史决策的尊重。
- 读取现状：design.md（元信息、修订记录、token 表、页面清单、图标清单）、tokens.css、pages/ 文件名。当前版本号、命名约定、风格基调一切以产物为准，不要凭印象。
- 确认增量需求（一次性问清再动手）：新增或修改哪些页面；要不要新图标——新图标先补进 icons/ 与 design.md 第 4 章清单，风格与既有图标完全一致；要不要调 token——调 token 影响全部已生成页面，须明确告知成本并让用户拍板。存量产物补暗色（light → dual）属 token 结构调整：
:root增 surface 变量、全部页面补暗色画板与覆盖块、产物升次位版本——同样先告知成本再动手。 - 按既有规范生成：复用同一套 :root 变量、同一骨架；页面命名接续编号（已有 06-xxx 则新增从 07- 起）；端、密度、真实文案的调性与历史页面一致。技能在环的增量会话同时重拷
validate.py本地副本并刷新版本戳（离环修改不刷副本仍可跑旧检查——门不消失只是滞后）。 - 沉淀版本与历史：
- 版本号次位 +1（如 v1.0 → v1.1）；仅修文案错字等微调用补丁位（v1.0.1）
- design.md 修订记录表追加一行：版本 | 日期 | 修改内容（列清新页面/新图标/token 变化及受影响页面）| 修改人
- design.md、tokens.css、README.md 头部版本更新为最新；新页面头部写新版本号；未受影响的旧页面保持原版本不动；系统区标注等产物级标注更新同样不改页面头版本——追溯交给修订记录
- README 页面清单与流转图补入新页面；token 有变时同步宪法速查表（宪法已生效，不重写）
- index.html 门户同步：页面增删/改名时增删对应卡片（缩略图内容随 iframe 自动更新，无需重做）；token 有变时重拷门户内联 :root；门户头部版本随最新版本号 - 校验后交付：
validate.py --expect-pages <新的总页数>，0 失败才交付；新页面的 token 一致性会被自动检查。
阶段一：需求拷问
用户描述想法后，分 2~3 轮确认三组信息（推荐用 AskUserQuestion 分批提问，每批不超过 4 个问题；一次性甩十几个问题会让用户疲劳）：
1. 目标端（决定系统区域约定。画板宽度一律 750px，下表高度为首屏参考，长页面整页铺开自适应）
| 端 | 首屏参考 | 系统区域约定 |
|---|---|---|
| 小程序（微信/支付宝等） | 750×1334 | 画导航栏（标题居中 + 右上角胶囊占位约 174×64）；有 tab 则画 tabBar（高约 98px） |
| H5 / 移动 Web | 750×1624 | 画自定义导航栏；注意回退交互 |
| App（iOS/Android） | 750×1624 | 画状态栏（高约 88px）与底部 Home Indicator 安全区 |
> 系统区域在页面稿中必须带语义标签（系统区 · 配置实现 / 系统区 · 运行时取值），标法与端内默认规则见 references/page-guide.md「语义标签」一节；平台落地对照表随产物 README 3.5 交付。
2. 视觉风格：读 references/style-presets.md，从中挑 3~4 个最匹配产品气质的预设，附一句话特征让用户选；同时确认主色倾向、密度（紧凑/舒展）。同时确认辅色语义（默认建议「贵重/荣誉/会员/高亮点缀」，允许答「无辅色」）与品牌渐变走向（深主色 primary-500→700 / 主辅撞色 primary-500→secondary-500）——二者决定辅色消费场景与 hero 渐变公式（见 page-guide「色彩表现力」）。同时确认主题策略三选一：仅亮色（默认推荐）/ 仅暗色 / 双主题（亮主暗辅）——夜间/户外/沉浸内容型产品推荐暗或双主题，效率工具默认仅亮。主题策略与风格预设解耦（暗夜风 ≠ 自动暗色结构，仍单独确认）。确认暗色或双主题时，token 按暗色结构交付（见 references/token-checklist.md「暗色模式」一节）；双主题需语义分层（背景类颜色走 --color-surface-* 语义 token）。用户说"你定"时，基于产品定位给出推荐并说明理由，请用户点头。
3. 内容与信息架构：产品定位与目标用户、核心功能、页面清单（每页一句话说明，给出建议清单让用户增删）、品牌名（没有就提议 1~2 个让用户选）。
汇总确认：用一张简表汇总（端 / 风格 / 主色 / 主题策略 / 页面清单 / 图标语义方向 / 署名），明确请用户确认。未获确认，不进入阶段二。
阶段二：预览稿（icons/ + tokens.css + token.html + components.html + view.html）
让用户在浏览器里"看见"设计方向——这比任何文字描述都直观。
icons/*.svg（30 个）：参考references/icons-guide.md，按产品语义确定 30 个图标（通用基础 + 品类补充），统一 24×24 viewBox、currentColor、统一描边风格（线性 1.8px 圆头，或与所选风格匹配的面性）；文件本体保持 24 viewBox，在 750 画板中以 48px（2x）尺寸内联使用（<img>引用仅限图标墙展示文件本体，详见 icons-guide）。文件名用语义英文 kebab-case（home.svg、shopping-cart.svg）。tokens.css+token.html：先写tokens.css（:root 变量全集，机器可读的单一事实源，开发时直接复制进项目）；含统计/构成图表的项目按 token-checklist「chart 派生」生成--chart-1..6并跑 validate [15a] 验证通过；token.html内联同一套变量（保持单文件、零外链）做全景展示，包含 9 个板块，每个板块一个标题清晰的展示区：- 色彩：主色色阶、辅助色、功能色（成功/警告/错误/信息）、中性色阶、背景与文字色——色板卡片同时展示 token 名与值；dual 项目在色彩板块后加「暗色对照」区（语义色板亮值→暗值对照，见 token-checklist）
- 字体：字体族、字号×字重×行高阶梯、标题/正文排版示例
- 圆角与边距：圆角阶梯、8px 网格（750 基准）间距阶梯的可视化标尺
- 阴影与层级：sm/md/lg 阴影卡片
- 动画：时长与缓动曲线 + 可交互演示（按钮反馈、元素进出、加载动画）
- 按钮：主/次/文字/禁用 各状态与按压态
- 弹窗：Modal、Toast、ActionSheet、底部抽屉（可点击演示）
- 背景：纯色 / 渐变 / 图案 三类页面背景样例
- 图标墙：30 个图标全部展示（含名称与用途说明）
token 命名与色阶派生规则见 references/token-checklist.md。token.html 版式按 references/doc-template.md 生成（--doc-* 中性画框 + serif 文档头 + sticky 锚点导航）
3. components.html（组件库全景）：与 design.md 第 3 章一一对应的组件展示，分五组，每组一个区块：①基础（标签 Tag、徽标、头像、分割线）②表单（输入框默认/聚焦/错误三态、开关、选择器、步进器）③导航（导航栏、tabBar、分段 Tab）④数据展示（列表项、卡片、进度条、步骤条）⑤反馈与状态（Toast、空状态、骨架屏、加载态）。组件样式只准用 token 变量，每个组件配一句使用说明——让用户在预览阶段就看到全部组件的样子，而不是到 design.md 里读文字。版式按 references/doc-template.md 生成；dual 项目加亮/暗切换按钮（见 doc-template「components.html 版式」暗色切换器）
4. view.html：从页面清单挑 2 个最有代表性的页面（通常是首页 + 一个核心业务页），按真实内容完整排版，同一文件内左右并排展示（dual 按亮/暗分组各一行，版式见 references/doc-template.md「view.html 版式」画板分组横排）。对人阅读友好是硬要求：顶部文件头区（产品名 · 设计预览稿 · 版本 · 日期）+ 页面锚点导航，每个画板配标注条（序号 · 页面名 · 一句话职能）；预览默认按 1x（375 视觉宽）缩放展示、可切 2x 真值——避免桌面直出 750 造成「字体偏大」的错觉。具体见 references/page-guide.md 的「画板与阅读体验」一节。文档层按 references/doc-template.md 生成（评审台定位不变，标注条样式沿用 page-guide）
画板骨架与页面制作规范见 references/page-guide.md。允许少量内联 JS，但仅限演示交互（弹窗开关、tab 切换、动画触发——含入场重播与数字滚动、标注开关），不得引入任何外部资源；页面动效按 references/motion-guide.md 基线执行（必配 S1~S4 + 页型选配）。
停下来评审：把 token.html、components.html、view.html 三个文件的路径告诉用户，并主动用 open 命令帮用户在浏览器打开（30 个图标在 token.html 图标墙查看）。收集意见 → 修改 → 再次确认，循环直到用户明确认可。用户对 token/组件的任何修改都要同步进 tokens.css，阶段三成文时统一落入 design.md。
阶段三：全量产出
预览定稿后：
pages/全量页面：按阶段一确认的页面清单逐一生成，一页一个文件，命名01-首页.html、02-订单列表.html（序号 + 中文名，阅读友好）。view.html 中的 2 页按定稿 token 重制并入 pages/。含数据列表的页面（内容流/列表/搜索结果）必须补「空态 + 加载态」状态画板（同文件追加 artboard，规范见references/page-guide.md「页面状态变体」一节）；双主题项目每页亮色画板后必须补暗色画板（机制见references/page-guide.md「暗色画板」）；动效按references/motion-guide.md执行——必配基线四件（S1~S4）零例外 + 页型选配，validate [14] 卡三零。design.md设计规范，固定结构：
# {产品名} 设计规范
> 元信息：版本 · 日期 · 作者 · 状态 · 基准/端/风格（见「产物文件头」一节）
修订记录表：| 版本 | 日期 | 修改内容 | 修改人 |
## 1. 设计原则（风格关键词与 3~5 条理念）
## 2. 设计 Token（色彩/字体/圆角/边距/阴影/动画，每类一张表：token 名 | 值 | 用途（dual 含暗色主题小节：token | 亮值 | 暗值 | 用途）；附 CSS 变量全集代码块）
## 3. 组件规范（与 components.html 一一对应：用途、样式、状态、使用禁忌；状态描述与 token-checklist「组件状态映射规范」口径一致，禁止页内私造状态色）
## 4. 图标规范（风格约定 + 30 个图标表：文件名 | 语义 | 使用场景）
## 5. 页面与布局约定（页面清单、导航结构、通用布局模板、间距用法（含**纵向堆叠间距约定表**：区块间/卡片间/数值→说明/标题→副标题/图标→文字等常用堆叠的默认 `--space-*`——示例默认值按项目 token 阶梯自定，表外场景先补表再用，禁止堆叠留白靠行高）、每页组件清单与数据字段（含展示格式，模板见 token-checklist；图片位标注比例与内容说明）、文本溢出约定、交互动效约定（场景→token 映射表，模板见 token-checklist））
## 6. 开发落地约定（**750 基准与各端换算表**、字体/行高/动效**双端原生映射**——字号 sp 与 Dynamic Type、行高「附加间距」语义差、缓动贝塞尔两端通用，模板见 token-checklist、运行时行为注记（减少动效/键盘焦点/读屏命名）、CSS 变量全集、命名规范、禁止事项清单、系统区域落地原则——系统能渲染的交给系统、设备相关运行时取值，对照表见 README 3.5）
README.md索引与还原指南：按references/readme-template.md生成——产物清单、双读者阅读顺序（人：index 门户 → token → 组件 → 页面；AI：宪法 → 本 README → tokens.css → design.md → pages）、AI 页面还原指引（还原工作流、各技术栈 token 接入方式、750 换算表、图标接入、系统区域落地对照）、页面流转 sitemap、修订记录。README 是 AI 还原的第一入口，写给编码代理的内容要具体到可直接执行。index.html汇总门户：按references/index-template.md生成——头部 meta（产品/版本/端/风格/主色）、全量页面缩略图总览（iframe 真页面 + CSS 缩放，点击新开原稿）、设计系统四入口与文件链接。门户是人的第一入口，README 是 AI 还原的第一入口；卡片文案直接复用 README 第 4 章页面清单，不新造。manifest.jsonAI 机器清单：按references/page-guide.md「manifest 约定」生成——产品元信息 + 每页 file/name/role/components/states/icons/links；components 取自 design.md 第 5 章「本页组件」列。AI 还原的第一手全貌。
5.5 校验器本地副本：把技能侧 scripts/validate.py 逐字节复制为 docs/x-designer/validate.py，并在 shebang 行后插入一行注释：# 复制自 x-designer vX.Y.Z · 技能源：.claude/skills/x-designer/scripts/validate.py · 技能在环时以技能侧为准（vX.Y.Z 取当前技能版本）——校验器随产物走，未安装本技能的会话同样可校验
校验后再交付：预览确认后若 token 有调整，先同步 tokens.css、token.html、components.html，再运行产物内本地校验器 validate.py（阶段三 5.5 已拷贝）——自动检查产物结构、token 一致性、图标数量与 viewBox、展品页引用内联（<img src="icons/…"> 即 FAIL，图标墙豁免）、页面数量、外链依赖、750 基准注释块、design.md 覆盖全部 token 变量、代码块值与 tokens.css 逐值一致（值级比对）、换算表与修订记录、字号阶梯、门户引用完整性、对比度自检、manifest 完整性（存在、JSON 合法、页数一致、页面/tokens/icons/links 引用存在、modal 链接 dismiss 关闭语义）、阅读层画框（--doc-* 四项检查）、展品裸 z-index（警告）、底部呼吸距离（警告）、贴底件运行语义标注（含 tabbar 页缺「运行时取值/配置实现」标注即失败）、视口单位（警告）、全幅贴底内缩信号（警告）、主题模式（light/dark/dual 校验）、页面动效基线（三零即失败，motion-guide 基线四件）、色彩表现力（chart 几何/分色/辅色消费，警告级）、校验器本地副本（缺失失败）：
python3 docs/x-designer/validate.py docs/x-designer --expect-pages <页面数>
全部通过后，再人工抽查脚本管不了的两件事：页面视觉层次与焦点是否成立；文案是否真实贴合产品。统一走产物内本地副本；技能源是工程侧事实源。
阶段四：写入宪法（必须先询问，不问不写）
向用户说明：写入宪法后，本项目后续所有页面开发都将强制遵守这套设计规范，改样式先改规范。用户同意后执行：
- 判断宪法文件（写入用户所用 AI 编码工具对应的宪法）：
- 本技能运行在 Claude Code → 写CLAUDE.md
- 项目存在AGENTS.md且用户使用 Codex / Cursor 等 → 写AGENTS.md
- 无法判断时直接问用户；目标文件不存在则创建 - 追加写入（保留文件原有内容，在末尾追加）一段「UI 设计宪法」：
- 声明：本项目 UI 开发必须遵守docs/x-designer/design.md，设计稿见docs/x-designer/（入口 index.html）
- 核心 token 速查表（主色、字体族、字号阶梯、圆角、间距基准等关键值）
- 硬性规则：颜色/字号/间距/圆角/阴影一律取自 token CSS 变量，禁止魔法数值；图标只允许使用docs/x-designer/icons/中的 SVG；需要新样式时，先补进 design.md 与 token.html 再使用
- 双主题项目：主题相关颜色一律引用语义 token（--color-bg-*/--color-text-*/--color-surface-*），暗色接入见 design.md 暗色主题小节与 README 3.6
- docs/x-designer/ 的任何修改（页面/token/文档）完成后，必须运行python3 docs/x-designer/validate.py docs/x-designer --expect-pages <页数>，0 失败才算完成；失败项未修复不得视为交付——校验器随产物走，未安装本技能的会话同样必须执行 - 告知用户宪法文件路径与后续开发中的生效方式，完成交付。
参考文件
references/style-presets.md— 10 种风格预设（特征/配色/字体/形制/适用场景），阶段一选风格时必读references/icons-guide.md— 图标规范、30 个基础清单、品类补充、常用 path 示例，阶段二生成图标时必读references/token-checklist.md— token 命名、色阶派生、字体栈、一致性自查，阶段二/三使用references/page-guide.md— HTML 骨架、画板规范、系统区域、图片占位、常见页面类型要点，做任何设计稿页面时必读references/readme-template.md— 产物 README.md 生成模板（含 AI 还原指引、各技术栈 token 接入与换算表），阶段三必读references/index-template.md— 产物 index.html 门户生成模板（头部 meta、缩略图 iframe 实现与卡片规则），阶段三必读references/doc-template.md— token/view/components 文档层版式模板（--doc-* 变量集、serif 文档头、sticky 锚点导航、字号下限 0.75rem），阶段二生成三文件时必读references/motion-guide.md— 页面动效片段库（触发形态、页型 × 动效对照、S1~S9 可照抄片段、与 design.md 5.5 对齐规则），做页面稿动效时必读references/skill-methodology.md— 生成类技能产物可靠性四件套方法论（契约随工件走/结构模板兜底/机器校验卡门/出错点就地注释），迭代本技能或迁移到其他生成类 skill 时必读scripts/validate.py— 产物校验脚本：结构完整性、token 一致性、图标/页面数量、门户引用完整性、外链与 750 基准检查，阶段三交付前必跑
