design-prim

Skill: design-prim

design（锁定一套贯穿始终的设计系统）+ prim（规范、标准 impeccable，不杂乱）。

一次整合：orca-onboard（省略——太重了，hallmark 已在 Step 0 自动扫描 token）+ playwright-verify + impeccable（bundle doyourmagic/impeccable）+ hallmark（设计底线 + slop-test）+ qc-uiux（资深评审 4 项，使用确定性引擎 visual-qa）。不重写这些 skill 的逻辑——只按正确顺序调用，并指定正确目标。

付出过代价的陷阱——运行前请阅读： /impeccable document 会生成 DESIGN.md，其中照搬 代码中现有的 token/颜色/字体（它描述现状，不会提出任何新方案）。如果先调用此命令，再让 hallmark redesign 读取，Hallmark Step 0 Pre-flight 会将 DESIGN.md 视为已锁定的系统， 并覆盖其他所有内容——这就把需要清理的 slop token 又锁死了，只在上面做些细枝末节的调整。 这就是之前版本的这个 skill“跑完后页面却没有变好”的原因：它以为自己锁定的是一套新系统， 实际上锁定的却是旧系统。清理 slop 的流程中不要调用 /impeccable document。

WHAT

目的和上下文

• Purpose： 在接入任意项目时清理 UI/UX slop——先截取 before，让 hallmark redesign 生成它自己的新设计系统，然后通过 slop-test 测量并修复，再运行 /impeccable audit/critique、/qc-uiux，直到问题清理干净或用完 2 轮。
• Trigger（何时使用）：
  • 刚接手一个陌生项目（onboard），需要让 UI 达到一致标准，不露出 AI-slop 的痕迹。
  • 已有多个零散的 view/屏幕，各处风格不一，需要锁定一套统一系统。
  • 用户说“清理 slop”、“精简项目 UI”、“统一整个项目的 UI 标准”、“onboard 后清理 UI”、“design prim”、“/design-prim”。
• Non-goals： 仅需修改一个小型 component 时不要使用（直接使用 hallmark component-scope）；需要深入理解 UI 之外的架构/business logic 时也不要使用（应使用完整的 orca-onboard，而非此 skill）。不重写所调用 skill 的逻辑。

心智模型

impeccable 已安装？→ view/route → before 图片 → PRODUCT.md（背景信息，不含旧 token）→ hallmark redesign（新 design.md，唯一生成代码的步骤）→ 3 层测量（slop-test · impeccable audit/critique · qc-uiux）+ after 图片 → 根据 finding 表修复，最多 2 轮 → 已知限制。

输入和输出约定

	Field	Required?	意义
In	目标项目（root + router/pages）	是	所有聊天命令的运行位置
In	app 在 <base-url> 运行	/qc-uiux 和图片所需	与 playwright-verify 相同
In	希望保留的有效 design.md/DESIGN.md	否	仅当用户希望保留旧系统，并在 brief 中明确说明时使用
Out	PRODUCT.md + 新的 design.md + 已重新设计的代码	是	由 /impeccable init 和 hallmark 生成
Out	每个 view 的 before/after 图片 + 3 层测量结果	是	证明“变得更好”，而非空洞的分数
Out	最终报告	是	第 2 轮后仍未解决的 finding 记为 known limitation

规则和能力

• RULE-01 (MUST)：0→6 步顺序不可颠倒：步骤 4 是唯一生成/修改代码的步骤；步骤 3 只提供背景信息，步骤 5–6 只负责测量 和修复——如果停在步骤 3，或者只运行步骤 5 而未执行步骤 4/6，就视为“让界面变 好”这项工作尚未完成，即使已经有分数报告也不例外。
• RULE-02 (MUST)：步骤 3–6 是 聊天命令（/impeccable ...，hallmark 是 skill），不是 shell 命令——不要输入到 终端。
• RULE-03 (MUST)：除非用户需要理解 UI 范围之外的架构/business logic，否则不要自行重新加入 orca-onboard。
• RULE-04 (MUST)：如果 impeccable 已全局安装（而非安装在项目中）→ 在运行步骤 3 之前卸载/重新安装到正确的 scope， 避免混入其他项目的 artifact（参见 dym-impeccable-install-into-your-project 中的陷阱 2）。
• Capabilities：读取目标项目的 route 结构；通过聊天调用其他 UI skill（而非 shell）；运行无头浏览器进行截图/测量；编写目标项目的 UI 代码（仅限重新设计/修复步骤）。

失败边界

• 停在步骤 3，或只运行了步骤 5 而未到步骤 4/6 → 即使有分数，“美化”工作也尚未完成（RULE-01）。
• <base-url> 上的应用无法运行 → 无法截图，也无法运行 /qc-uiux：状态为受阻，并告知用户。
• 第 2 轮后仍有发现项 → 标记为部分完成，记录已知限制，不要无限重复。
• 若在重新设计前误运行了 /impeccable document → 旧的混乱设计系统会被锁定：状态为失败，删除该 DESIGN.md，然后重新设计。

HOW

主要工作流

W01–W07 对应下面的步骤 0–6。

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	确定性	目标项目根目录	检查 .claude/skills/impeccable/；若不存在，则通过 hub 安装	impeccable 已就绪	已存在 → 跳过；全局安装 → B01
W02	确定性	router/pages	列出 view/route	view 列表	—
W03	执行	view + <base-url>	使用 playwright-verify 截取改造前的画面	改造前截图	应用无法运行 → 受阻
W04	判断	目标项目对话	/impeccable init → PRODUCT.md（不要用 document）	产品背景	—
W05	执行	根目录 + PRODUCT.md 摘要	在项目根目录上用 hallmark 的 redesign verb	design.md + 新代码	想保留旧系统 → B02
W06	确定性	已重新设计的 view	进行 3 层测量 + 截取改造后的画面	发现项 + 改造后截图	仍有 P0/P1 / gate 未通过 / 需要修复 → W07
W07	执行	发现项	按发现项类型表修复，然后重复 W06	无问题	第 2 轮后 → 已知限制

各步骤详情（W01–W07 的事实依据）： 0. 检查前提条件——目标项目中是否已安装 impeccable？ 检查目标项目根目录中是否存在 .claude/skills/impeccable/（之前安装留下的产物）。已存在 → 跳过此步，不要重复安装。不存在 → 调用 /dym-impeccable install-into-your-project（通过 hub，让它自行在 3 个位置之一找到正确版本——同级目录的 npx skills add、项目 bundle，或 .claude/skills/——不要硬编码 framework repo 的 bundle 路径，因为目标项目不一定有它）。 执行该文件时要记住这个陷阱：始终使用 npx impeccable install -y --scope=project --providers=claude，不要输入 --help。

1. 列出视图/路由——使用 Explore agent，或直接 grep 目标项目的 router/pages 配置。无需单独的 skill，也无需 orca-onboard。

2. 拍摄当前状态（before）——使用 playwright-verify 截取每个视图的画面，留作第 5 步比较。

3. 产品背景（不是旧 token）——在目标项目的聊天中输入：/impeccable init → 生成 PRODUCT.md（用户、用途、限制、语气）。这是对 hallmark redesign（动词）静默执行、不询问受众/用例/语气的补充输入——调用第 4 步时，将 PRODUCT.md 摘要粘贴到 brief 中。不要运行 /impeccable document（参见上文的陷阱）。

4. 真正的重新设计——这是唯一会生成新代码的步骤。 在项目根目录（路由目录路径，不是单个文件）上调用 skill hallmark，使用动词 redesign → 进入 hallmark 的多页面流程：它会自动扫描现有 tokens/品牌，自行选择 genre/macrostructure/theme，自行在根目录编写专属的 design.md，然后按该体系重建每个页面。如果项目已有有效的 design.md/DESIGN.md（不是第 3 步刚禁止的 document 版本），且用户想要保留该体系而不是重新编写，请在 brief 中明确说明。

5. 重新扫描并比较——对每个重新设计的视图，执行 3 层检查（各层不能互相替代）： a. hallmark 自行评分 slop-test（生成前的六轴检查 + 58 项 gate，已在第 4 步的 Build 中运行）。 b. /impeccable audit <view>（P0–P3：a11y、性能、主题、响应式、反模式）和 /impeccable critique <view>（层级、IA、认知负荷）。 c. /qc-uiux <view>（应用必须正在运行——<base-url> 与 playwright-verify 相同）——给出资深专家的 4 项评估结论（accessibility · visual-hierarchy · consistency · antipattern）；其中可测量的部分（WCAG 对比度、点击目标、几何重叠/错位）通过 visual-qa 引擎确定性运行（测量实际 rect，不读取静态 CSS）→ 得出 PASS 或需要修复的结论。 使用 playwright-verify 重新截图（after），与第 2 步的 before 图片并排放置——这是“更漂亮”的证据，而不是空泛的分数。

6. 修复循环——仍有 P0/P1 finding、slop-test gate 失败，或 /qc-uiux 判定需要修复 → 使用对应命令修复，不要从头重新设计：

   Finding 类型	使用以下方式修复
   a11y（对比度、点击目标、缺少 label）	/impeccable harden <view>
   性能（加载、渲染、动画）	/impeccable optimize <view>
   主题（视图间 token 不一致）	/impeccable polish <view>——如果整个体系都不一致，则返回 hallmark audit <view>
   响应式（断点、触摸区域）	/impeccable adapt <view> <context>
   反模式/认知负荷/IA 混乱	/impeccable distill <view> 或 clarify <view>（文案）
   具体的 slop-test gate 失败	直接根据 hallmark/references/slop-test.md 中对应的 gate 修复，无需 /impeccable
   qc-uiux 的 visual-hierarchy/consistency（LLM 目测，不可测量）	按对应项使用 /impeccable distill/polish <view>——qc-uiux 只指出最严重的问题并给出修复方法，不会自动修复
   qc-uiux 中可测量的 a11y/antipattern（visual-qa 引擎：对比度/点击目标/重叠/错位）	与上面的 a11y/反模式行相同——同一个问题会被两个工具同时发现

   每轮修复后都重新执行第 5 步。**最多 2 轮。**第 2 轮后仍有 finding → 在最终报告中明确记为已知限制，不要无限重复。

分支

ID	类型	守卫条件	行为	跳过 / 失败	重新汇合
B01	恢复	impeccable 已全局安装（而非安装在项目中）	在步骤 3 之前按正确的作用域卸载/重新安装（RULE-04）	—	W04
B02	用户可选	项目中有有效的 design.md/DESIGN.md（不是 document 生成的版本），且用户想要保留	在重新设计简报中明确说明要保留该系统	—	W06
B03	恢复	仍有 P0/P1 问题、slop-test 门禁失败，或 /qc-uiux 要求修改	按步骤 6 的表格修复，然后重新运行步骤 5	超过 2 轮 → 已知限制	W06

验证与停止条件

三个独立的测量层（58 项门禁的 slop-test、/impeccable audit+critique、/qc-uiux 中可通过 visual-qa 引擎测量的部分）；任何一层都不能替代其他层。最终证据是 before/after 图片对。达到干净状态或完成 2 轮修复后停止。

示例

• 正向： 在包含 6 个路由的管理项目上运行“/design-prim” → 已有 impeccable（跳过步骤 0）→ 6 个视图的 before 图片 → PRODUCT.md → hallmark redesign 生成新的 design.md → 第 1 轮 /qc-uiux 报告 1 个视图的对比度未通过 → /impeccable harden <view> → 第 2 轮通过，附带 before/after 图片的报告。
• 边界/失败： Agent 在步骤 3 调用 /impeccable document，之后才进行重新设计 → design.md 锁定了旧的 slop token，页面“跑完了却没有变好看” → 违反已记录的陷阱，丢弃该 DESIGN.md，并从步骤 3 开始通过 /impeccable init 重新运行。