prd-grade-fe

prd-grade-fe

下文中的 $SKILL = 此 skill 的基础目录（skill 加载时显示的“Base directory for this skill”；在 framework 仓库中为 skills/prd-grade-fe）。所有脚本和参考资料都随 skill 目录提供，不依赖仓库。

这是一个轻量 Hub。不负责设计规则：审美由 hallmark（skills/hallmark/SKILL.md）负责，确定性规则由 impeccable（npx -y [email protected] detect，硬性固定版本）负责。Hub 负责顺序和阶段间的契约，并提供两个支持 --self-test 的脚本：

文件	作用
scripts/design-sync.py	design.md 是唯一事实来源：将 css :root{} 块转换为 frontmatter YAML（impeccable 会读取）+ tokens.css。发生漂移时，--check 返回码为 1。
scripts/fe-gate.sh	交付前的门禁：断言目标存在 → detect --json → 按语义返回码 0/1/2 → viewport-check.mjs 检查 320/375/414/768。退出码 0 表示通过 · 1 表示 impeccable 错误 · 2 表示发现问题/视口未通过 · 3 表示跳过（缺少 node/网络） · 4 表示目标缺失。
scripts/badge-consistency.py	impeccable 中没有的确定性规则（GH#164）：在同一个文件中，状态徽章（render*Badge/*Status*/*Pill*/span pill）必须使用相同的图标或圆点签名 · rounded-* · token 常量（STATUS_GLASS）；偏离多数的徽章（≥2）→ file:line，fe-gate 将其计为发现问题，返回码为 2。
references/presets/macos-glass.design.md	默认 preset，已通过 detect，返回码为 0；证据见 macos-glass.evidence.md。
references/intake.md	Route A/B/C → design.md。
references/impeccable-audit.md	审计评分标准（5 个维度 /20）· 加固 · 润色，从有来源的内容中提炼。

WHAT

目的和背景

• **目的：**交付一个达到生产标准的前端页面/屏幕，并设置机器门禁——主题锁定到一个 design.md，遵循 hallmark 仅使用 token 构建；只有 fe-gate.sh 通过且 P0 = 0，才能交付。
• 触发条件（何时使用） — 旧版 ## When to use 部分：
  • 用户需要一个用于生产环境的前端页面/屏幕，而不是快速 mockup（快速 mockup → /br 或单独使用 hallmark）。
  • 用户以“使用默认主题”、“这是设计文档”或“做得像这个页面：”的方式提供主题。
  • 项目已有 design.md，需要新增同一设计体系的屏幕并进行门禁检查。
• **非目标：**不是快速 mockup（→ /br 或单独使用 hallmark）；不负责设计规则（审美 = hallmark，确定性规则 = impeccable）；不处理 BR→frame 流程。

心智模型

主题来源（A preset · B 文档 · C URL）→ design.md（唯一事实来源）→ design-sync.py → tokens.css + frontmatter → 仅使用 token 构建（hallmark）→ fe-gate.sh（impeccable detect + badge-consistency + 4 个视口）→ 审计/加固/润色 → 报告。Hub 负责顺序和阶段间的契约；规则由 hallmark/impeccable 负责。

输入和输出契约

	字段	必填？	含义
输入	页面/屏幕 brief	是	要构建的内容
输入	主题来源 A/B/C、受众、使用场景、语气	否	“go ahead”/留空 → 使用 A，并从 brief 推断 2–4 个词，用一句话说明
输入	已有 design.md	否	存在且 --check 返回码为 0 → 复用，跳到阶段 3
输出	已同步的 design.md + tokens.css	是	design-sync.py --check 返回码为 0
输出	带有 design 标记 + critique 的仅使用 token 的 HTML 输出	是	明暗主题切换，footer 使用相对路径
输出	fe-gate.report.json + 8 项报告（阶段 5）	是	只有 fe-gate 退出码为 0 且 P0 = 0 时，才表示“已准备好投入生产”

规则与能力

• RULE-01 (MUST)：不要在此复制 hallmark rubric；修改规则时，应在 hallmark 或 references/impeccable-audit.md（含来源 + sha）中修改。
• RULE-02 (MUST)：绝不要调用 npx impeccable install（3.6.1 版的 install 没有 --help，会直接安装到 $HOME）。--scope 始终使用连写形式（--scope=type）。相信 stdout 中的 JSON，不要相信 stderr（npx 会合并流）。
• RULE-03 (MUST)：修复超过 3 轮后仍有 finding → 随附剩余项表格并直言不讳；或者在 .impeccable/config.json 中添加带理由的 waiver（{"ignores":[...]}），并在报告中说明。不要偷偷忽略。
• RULE-04 (MUST)：缺少 node/网络 → 报告中写明 skipped: <理由>，exit gate ≠ 0。不能有“应该也没问题”这种例外。
• RULE-05 (MUST)：design.md 已存在 → 不要覆盖；切换系统时应 AMEND ## Variants（hallmark design-md 的 no-overwrite policy）。
• RULE-06 (MUST)：修改 skill 时进行自检：python3 $SKILL/scripts/design-sync.py --self-test && python3 $SKILL/scripts/badge-consistency.py --self-test && bash $SKILL/scripts/fe-gate.sh --self-test，然后运行 bash fdk/tools/sync-skill.sh prd-grade-fe。
• 能力：读取/写入项目中的 design 文件和输出；运行用于同步 token 和确定性检测 antipattern 的脚本（固定版本）；控制无头浏览器测量 4 个 viewport；读取 URL/设计文档作为主题来源。

失败边界

• 缺少 node/网络 → skipped: <理由>，gate exit ≠ 0，报告不得声称检查通过（partial）。
• fe-gate rc 1 / 3 / 4 → blocked，停止并记录原因；绝不能将 1/3/4 判为“检查通过”。
• rc 2 且经过 3 轮修复 → partial：随附剩余 finding 表格，或在报告中说明带理由的 waiver。
• design-sync.py --check rc 1（drift）→ 不要继续进入第 3 阶段。
• 用户要求更改主题，但 design.md 已存在 → AMEND ## Variants，不要覆盖。

HOW

Main workflow

步骤	类型	输入	操作	输出/退出	失败/下一步
W01	deterministic	项目	第 0 阶段 pre-flight：ls design.md …、command -v node、design-sync.py --check	系统是否已锁定，是否有 node	已锁定 → B01；没有 node → B02
W02	judgment	brief	第 1 阶段通过一条消息进行访谈（主题来源 · 受众 · 用例 · 语气）	答案或公开说明的推断	—
W03	effect	主题来源	第 2 阶段锁定变量 A/B/C → design.md → design-sync.py && --check	rc 0	rc 1 → 修复 drift
W04	effect	design.md	第 3 阶段依据 hallmark 构建，仅使用 token，在文件开头添加标记	HTML 输出	critique 的评分轴 < 3 → 在 W05 前修复
W05	deterministic	输出	第 4 阶段 gate：fe-gate.sh（≤ 3 轮）→ audit /20 → harden/polish → slop-test → 最后再运行一次 fe-gate	exit 0 + P0 = 0	rc 1/3/4 → blocked；3 轮后 rc 2 → partial
W06	judgment	结果	第 5 阶段交付 + 8 项报告	报告	—

各步骤详情（W01–W06 的真相来源）— 旧版 ## Steps 部分，原文如下：

第 0 阶段 — Pre-flight（不询问机器能自行检测的内容）

ls design.md DESIGN.md tokens.css 2>/dev/null; command -v node && echo node-ok
python3 $SKILL/scripts/design-sync.py --check 2>/dev/null; echo sync-rc=$?

• 有 design.md 且 --check rc 0 → 表示“系统已锁定，沿用”，并跳到第 3 阶段（除非用户要求更改主题 → references/intake.md §“项目已有 design.md 时”）。
• 没有 node → 仍执行第 1–3 阶段，但第 4 阶段会记录 skipped，且报告不得声称检查通过。

第 1 阶段 — 通过一条消息进行访谈（合并 hallmark 的问题，不要追问）

开始构建前，需要了解 4 项信息。你可以回答任意部分，也可以说 “go ahead”：

1. 主题来源 — [A] 默认 macOS glass · [B] 设计文档路径（文件/文件夹）· [C] 目标页面 URL
2. 受众 — 谁会使用，他们已经了解什么？
3. 用例 — 此页面需要引导用户完成的一个操作是什么？
4. 语气 — 选择一个倾向：editorial · brutalist · soft · utilitarian · luxury · playful · technical · austere

若回复“go ahead”或留空 → 选择 A，根据 brief 推断第 2–4 项，并在回复开头用一句话公开说明推断（hallmark Step 1 opt-out protocol）。没有“brief 已足够明确”这种例外：仍要询问，用户可以在两秒内略过。

阶段 2 — 锁定变量（references/intake.md）

• A：cp $SKILL/references/presets/macos-glass.design.md ./design.md，修改首行的项目名称。
• B：阅读文档 → 带有文件:行号来源的 schema 表 → 一个补充问题 → 写入 design.md + § Provenance。
• C：hallmark study <URL>（URL 模式，拒绝列表 + attestation）→ “lock the DNA” → design.md 含 § Provenance + § Notes（节奏盲点、不会沿用的反模式）。
• 然后：python3 $SKILL/scripts/design-sync.py && python3 $SKILL/scripts/design-sync.py --check → 只有 rc 0 才能继续。
• 口头说明 Genre / Macrostructure / Theme（hallmark Step 2.5）。

阶段 3 — 基于 hallmark 构建，系统已锁定

• 使用已锁定的 design.md 运行 hallmark 默认流程（Step 2 macrostructure → 3 ruleset → 5 preview → 6 build）：多样化方向反转（各屏幕必须共用同一套系统）。
• 所有颜色、字体、圆角、动效都通过 tokens.css 中的 var(--…) 设置（hallmark discipline 3）。不使用内联 hex/oklch；如果缺少 token，则将其添加到 design.md 的 :root 块中，然后重新运行 design-sync.py。
• 面向用户的 HTML 输出：通过带标签的切换按钮切换明暗主题 + html[data-theme] + localStorage + 防止 FOUC；适用于紧凑型 13″ 屏幕的字体大小阶梯；页脚填写文件本身的相对路径。
• 文件开头添加标记：`` 和 /* Hallmark · pre-emit critique: P? H? E? S? R? V? */（6 个维度，任何维度 < 3 时都要先修改，再进入阶段 4）。

阶段 4 — Gate（先机器，后人工）

1. bash $SKILL/scripts/fe-gate.sh <output.html …>；查看 antipattern | file:line | snippet 表格和 fe-gate.report.json。
   • badge 与 N 个同类 badge 的模式不一致 这一行 = badge-consistency：按照多数同类 badge 修正不一致的 badge，不要反过来修改多数项。
   • rc 2 → 修复对应 finding（修改 design.md 中的 token → 重新 sync，或修改 markup）→ 重新运行。**最多 3 轮。**记录每轮的 finding 数量，以便写入 report。
   • rc 1 / 3 / 4 → 停止并记录原因。从 1/3/4 都无法达到“干净”状态。
2. 加载 references/impeccable-audit.md：按 5 个维度打分，总分 /20，列出 P0–P3；完成 Harden 清单，然后完成 Polish。P0 必须 = 0。
3. 在输出上运行 hallmark slop-test（skills/hallmark/references/slop-test.md）；如果任何 gate 标红，就进行修复。
4. 所有修改完成后，最后再运行一次 fe-gate.sh（Harden/Polish 修改可能会再次产生 finding）。

阶段 5 — 交付 + report

Report 按以下顺序包含：(1) 阶段 1 的推理/答案；(2) Genre/Macrostructure/Theme + Theme 来源；(3) 6 项 critique；(4) 第 1..n 轮 finding 表及最终 rc；(5) audit 得分 /20 + P0 数量；(6) 4 种 viewport；(7) 相对输出路径；(8) 如有则注明 skipped。只有在 fe-gate exit 0 且 P0 = 0 时，才能写“已准备好投入生产”。

分支

ID	Kind	Guard	行为	Skip / failure	Rejoin
B01	conditional_required	存在 design.md 且 --check rc 0	说明“系统已锁定，直接复用”，跳过 W02–W03	用户要求更改 theme → references/intake.md § "当项目已有 design.md 时"	W04
B02	recovery	没有 node / 网络	仍然完成阶段 1–3；阶段 4 记录 skipped	report 不得声称干净	W06
B03	user_optional	Theme 来源 = B（文档）	带有文件:行号来源的 schema 表 → 一个补充问题 → design.md + § Provenance	—	W03 (sync)
B04	user_optional	Theme 来源 = C（URL）	hallmark study <URL> → “lock the DNA” → design.md + § Provenance + § Notes	—	W03 (sync)
B05	recovery	fe-gate rc 2	修复对应的 finding（修改 design.md 中的 token → sync，或修改 markup）→ 重新运行，最多 3 轮	超过 3 轮 → 连同剩余项表或说明理由的 waiver 一并交付	W05

验证与停止条件

机器关卡：fe-gate.sh exit 0（impeccable detect rc 0 + badge-consistency + 4 个 viewport：320/375/414/768），且 design-sync.py --check rc 0。人工/rubric 关卡：audit 5 个维度，总分 /20，P0 = 0，slop-test 无标红。gate 修复最多 3 轮；所有修改完成后，最后再运行一次 fe-gate。

示例

• 正向： /prd-grade-fe dựng trang danh sách đơn hàng cho app quản lý kho, mặc định theme → 选择 A，将 macos-glass 预设复制为 design.md，同步 rc 0，仅构建 token，fe-gate 第 1 轮 rc 2（2 个发现项）→ 修复 → 第 2 轮退出码 0，P0 = 0 → 生成 8 项报告，标记为“已准备好投入生产”。
• 边界/失败： 机器上没有 node → 仍执行阶段 1–3，fe-gate 退出码 3 → 报告注明 skipped: thiếu node，切勿写“已准备好投入生产”。

调用示例

/prd-grade-fe dựng trang danh sách đơn hàng cho app quản lý kho, mặc định theme
/prd-grade-fe trang pricing, theme lấy từ docs/brand/ (folder)
/prd-grade-fe landing cho sản phẩm X, làm giống https://example.com