Repository Wiki
Brandon030722/ark-ui-skill

迭代循环：证据锁定与文案收敛

迭代循环（Iterate with an evidence lock）是 Ark UI 工作流中处理"反复打磨"类需求的核心机制：当用户说界面"丑、太暗、文案太密"时，每一轮修改都必须先锁定一个可引用的官方证据模式（evidence lock），再对持久文案做收敛（copy convergence），并以同视口前后截图作为接受或回滚的唯一裁判。它把主观审美争论转换为"是否更接近引用证据"的可验证判断。

Purpose and Scope

本页覆盖 SKILL.md 中 "Iterate with an evidence lock" 章节定义的完整循环：触发条件、证据锁定、文案三分类与视觉归属（single visual owner）、单轮最小变更预算、空间回收、前后对比与回滚判据、以及非持久化 QA 入口的要求。同时覆盖与该循环配套的验收项（Validate 清单中与文案密度、图标化控件相关的条目）和审计脚本入口。

以下内容有意留给兄弟页面，本页只做交叉引用：

  • family / depth 双轴的选型规则与"设计契约锁定"本身 → 见核心工作流的契约章节（SKILL.md 的 "Lock the design contract"）。
  • 四档应用深度（minimal/moderate/complex/maximal）的完整评分标准 → 见 references/depth-levels.md。
  • 五个 family 的具体配方与 family×depth 适配矩阵 → 见 references/recipes.md 与 references/family-depth-matrix.md。
  • 证据的采集方法（如何用分析器研究新的官方页面并写入台账）→ 本页在"扩展点"中只给出命令入口，完整方法见 references/source-ledger.md 与 references/frontend-evidence.md。
  • 合规红线（不得复制的受保护素材）→ 见 references/legal.md。

Overview

这个循环解决的是 UI 打磨阶段最容易失控的三类问题：

  1. 审美漂移：每轮"再改一点"逐渐偏离原始视觉语言，最终变成无证据的赛博朋克堆砌。对策是每一轮在改代码之前先"报名"主 family、应用深度和 source ledger 中的精确公共模式。
  2. 文案噪音：为了显得"技术感"而复制粘贴状态、遥测、协议名。对策是把所有持久文案强制分类为 decision / changing state / explanation，并给每个数据分配唯一视觉归属。
  3. 不可复现的验收：凭记忆或猜测的状态判断好坏。对策是同视口前后截图 + 编译、交互、对比度、截图四项检查全部通过才允许进入下一轮。

关键概念：

概念含义
evidence lock（证据锁定）每轮修改前明确指出的 family、depth、以及 source ledger 中的精确公共模式；变更只允许在该证据族内发生
文案三分类decision（决策数据）、changing state（变化状态）、explanation（解释性内容）
视觉归属每个持久数据只能有一个界面元素"拥有"它；同类可比值归候选卡片，附加上下文归 dossier
单轮变更预算每轮只改一个共享 token 家族 + 一个 depth 行为 + 一个代表屏
非持久 QA 入口为难以触达的状态添加的确定性入口，必须显式抑制存档写入与删除，不得改变生产时序

Architecture

整个循环由六步构成一个带硬性回滚出口的闭环：

Loading diagram...

各环节的职责与设计意图：

  • Trigger（触发）：循环只在用户明确要求"反复打磨"或给出"丑 / 太暗 / 文案太密"这类反馈时启动；一次性交付不进入该循环，避免过度设计。
  • Lock（证据锁定）：把审美争议转换为证据引用。锁定后所有变更都被约束在该证据族内——例如纯黑发闷时，只允许提升既有 neutral token 或 stage lighting，不允许发明新渐变。
  • Inventory + Owner（文案收敛）：先分类再归属，两步缺一不可。分类决定"留不留"，归属决定"放在哪"；同一指标禁止同时出现在候选卡片和 dossier 两处。
  • Change（单轮最小变更）：把每轮 diff 控制在可归因的范围内，使第 5 步的对比能明确归因到本轮改动。
  • Capture + Verdict（裁判）：同视口前后对比是唯一的接受判据；四类失败信号（未更接近证据、可读性下降、出现碰撞、真实机制更难找到）任意一条命中即回滚。
  • Gate + QA（验收与可测性）：只有四项检查通过才允许重复；难以触达的状态通过非持久 QA 入口暴露，保证截图证据来自真实状态而非猜测。

核心规则详解

1. 触发条件与入口

SKILL.md 第 52–55 行定义了循环的进入条件——这不是一个无条件套用的流程，而是针对特定反馈信号的定向响应：

Use this loop when the user asks for repeated refinement or says the interface is ugly, too dark, or too text-heavy

设计意图：把"反复打磨"和"一次性实现"区分开。一次性实现走 Implement 章节；只有当用户表达持续不满（丑、太暗、太密）时才进入本循环，因为此时最容易出现无证据的自由发挥。

2. 证据锁定（Evidence Lock）的具体含义

每一轮修改代码之前必须先声明三件事：主 family、应用深度、以及 source ledger 中精确的公共模式。台账 (references/source-ledger.md) 按三个置信度等级组织证据：

等级定义
Direct在渲染后的官方页面或其公开加载的生产 CSS/JS 中直接观察到
Supported由官方/认证公司渠道或官方招聘站点陈述
Inference由重复的直接观察推导出的解释；不是公司声明

锁定之所以可行，是因为台账为每个 family 记录了可直接引用的 token 证据，例如：

- Arknights current CSS: dominant `#000`, `#fff`, `#18d1ff`; Bender, Oswald, Novecento Sans Wide, Source Han Sans; masks, mix-blend overlays, 7rem section labels, orientation-specific layout. - Endfield CSS: dominant `#191919`, `#fff`, `#fffa00`; optional `#00ffa2`; Gilroy, Space Grotesk, Novecento Sans Wide; clip paths, yellow load wipe, vertical rail, large identifiers.

Source: source-ledger.md

这样"纯黑太闷"的改进路径就被钉死：优先提升既有 neutral token 或 stage lighting，而不是新增渐变、辉光或新 accent。若确需借鉴第二个 family，规则是只借一个受约束的单一特征，绝不合并其完整色板或装饰系统。

3. 文案三分类与视觉归属

这是循环中最细的一组规则。首先把持久文案分为三类并给出处置：

  • decision（决策数据）：保持可见。
  • changing state（重复状态）：压缩。
  • explanation（可选解释）：移入显式、可访问的 details 折叠层。

然后执行视觉归属规则：每个持久数据有且只有一个视觉拥有者。可比值归候选卡片；dossier 只拥有附加上下文；同一指标禁止两处重复。以下是从规则文本中摘取的代表性归属约束（按屏幕类型）：

屏幕类型归属规则
通用删除仅枚举下方可见区块的摘要——那是重复导航而非规则内容
程序化手势可用紧凑符号映射（如 hand → rear → front），但精确值、前置条件、停止条件、例外必须留在可见文本中
36–42 px 状态条一行可读 label + value 优于两层过小文字
即时解决文案只归一个拥有者（通常是决策头或提交动作），不得同时出现在 header、explainer、footer
过渡/结果屏状态 dossier 拥有当前值，报告拥有叙事结果与下一个解锁；禁止为填充空间镜像 dossier 的遥测
路由/拓扑屏图拥有选择，顶部 HUD 拥有可比运行值，底部 rail 只拥有所选摘要与显式动作
预提交详情层一个 run-state dossier + 独立的 target / mechanic / risk / outcome facets；不加重复 dossier 的通用"run check"卡

配套的两条硬性底线（SKILL.md 第 73–75 行）：

Copy reduction must not collapse decision UI into unlabeled icons. Keep comparable numbers and explicit action verbs. In a 36–42 px status chip, prefer one readable label + value line over two undersized text tiers.

Source: SKILL.md

设计意图：收敛的目标是"去掉重复"，而不是"去掉信息"。图标化、删除标签、缩小字号都是收敛的假捷径，会被这条底线直接否决。

4. 单轮最小变更与空间回收

每轮只允许改三样东西：一个共享 token 家族、一个 depth 行为、一个代表屏。这条预算约束服务两个目的：

  • 第 5 步的同视口对比才能把效果归因到本轮改动（diff 可归因）。
  • 防止一轮之内 family 与 depth 双轴同时漂移。

针对两类常见视觉抱怨，规则给出了证据内的替代路径：

  • 纯黑发闷：先在所选证据 family 内提升 neutral token 或 stage lighting；不得发明渐变、辉光或新 accent。
  • 插图背景过饱和：用同一证据锁定的 neutral wash 约束它，而不是替换为纯黑或大面积 accent 色块。
  • 模态遮罩：先尝试下一个既有 neutral surface token 加克制的透明度，再考虑改面板或加颜色——遮罩应分层但不把整个视口变成一块平黑。

回收到的空间（步骤 4）必须交给主内容或负空间，不得用装饰性遥测填回。配套的反向禁令（SKILL.md 第 80–81 行）明确禁止为了"显得技术"而制造协议名、系统代号、频道标签、负载表或装饰性遥测。

5. 判据与回滚

第 5–6 步构成循环的验收门槛。四项检查（compile、interaction、contrast、screenshot）全部通过才允许进入下一轮。任何一条失败信号出现即回滚或修订：

  • 结果没有在视觉上更接近引用证据；
  • 可读性下降；
  • 引入碰撞；
  • 真实机制变得更难找到。

对"选择后立即提交"的控件还有一条补充：即使移除了较长的指令性文字，后果也要保留在一条简短状态行或动作标签中（SKILL.md 第 109–110 行）。

6. 非持久 QA 入口

当代表性状态难以自然触达时，规则要求添加一个确定性的、非持久化的 QA 入口，再判断截图（第 111–118 行）。关键定义：

Non-persistent means the harness explicitly suppresses save writes and save deletion, not only that it creates an in-memory object.

即：仅在内存里建对象不算非持久化，必须显式抑制存档写入与删除。对坐标自动化不可靠的场景，QA 入口应暴露精确的模态或确认状态，而不是豁免交互证据。对自动隐藏过渡，QA 入口可以在禁用 auto-hide 的前提下重放正常动画，但不得改变生产时序；必须在过渡 UI 可见时完成捕获与验证。循环的最后一句是"Never optimize from a guessed or stale state"——永不基于猜测或过期状态做优化。

Usage Examples

完整迭代循环源文本

循环的全部六步定义在 SKILL.md 的 "Iterate with an evidence lock" 章节，以下是节选（步骤 1 与步骤 2 的开头）：

markdown
1## Iterate with an evidence lock 2 3Use this loop when the user asks for repeated refinement or says the interface 4is ugly, too dark, or too text-heavy: 5 61. Name the primary family, application depth, and exact public pattern from the source ledger 7 before changing code. If a second family is useful, borrow one constrained 8 trait only; do not merge its full palette or decoration system. 92. Inventory persistent copy as `decision`, `changing state`, or `explanation`. 10 Keep decision data visible, compress repeated state, and move optional 11 explanation behind an explicit, accessible details affordance. 12 Assign every persistent datum one visual owner: comparable values belong to 13 candidate cards, while a focus dossier owns only additional context. Do not 14 repeat the same metric in both places.

Source: SKILL.md

这两步是循环的"准入"部分：步骤 1 建立证据锁，步骤 2 的前半段做分类、后半段做归属。注意归属规则紧跟在分类之后——先决定"留不留"，再决定"放哪里"。

单轮变更预算与空间回收

markdown
13. Change one shared token family, one depth behavior, and one representative screen per pass. 2 When pure black feels flat, first lift neutral tokens or stage lighting within 3 the chosen evidence family; do not invent gradients, glow, or a new accent. 4 For a modal shade, try the next existing neutral surface token at restrained 5 opacity before altering the panel or adding a color. The shade should separate 6 layers without turning the full viewport into a flat black field. 74. Preserve the recovered space. Give it to primary content or negative space 8 instead of filling it with decorative telemetry.

Source: SKILL.md

这两条是循环的"预算"部分。注意"纯黑发闷"这条规则把改进路径写成了一条有先后的决策链：既有 neutral token / stage lighting → 下一个既有 neutral surface token（克制透明度）→ 才轮到改面板或加色。这解释了为什么迭代循环能守住 family 一致性——它把最常见的美学冲动都映射到了证据内的既有资源。

验收判据与非持久 QA 入口

markdown
15. Capture before and after at the same viewport. Revert or revise if the result 2 is not visibly closer to the cited evidence, reduces legibility, introduces 3 collisions, or makes a truthful mechanic harder to find. 46. Repeat only after compile, interaction, contrast, and screenshot checks pass. 5 ... 6 If a representative state is difficult to reach, add a deterministic, 7 non-persistent QA entry before judging screenshots. Non-persistent means the 8 harness explicitly suppresses save writes and save deletion, not only that it 9 creates an in-memory object.

Source: SKILL.md

第 6 步的四项检查是循环出口的门槛；QA 入口定义则确保难以触达的状态也能拿到真实截图证据，而不是被豁免。

循环配套的验收条目

Validate 清单中有两条与文案收敛直接对应：

markdown
17. For text-density passes, confirm that removed copy is redundant or remains 2 available through a visible, keyboard-accessible details control. 38. Confirm every icon-only control is a familiar secondary action or has an 4 accessible name. Purchase, commit, destructive, and state-comparison actions 5 retain visible verbs and values even in compact layouts.

Source: SKILL.md

第 7 条是文案收敛的验收（删掉的必须是冗余，或仍可通过键盘可达的 details 访问）；第 8 条是图标化底线（购买、提交、破坏性、状态对比动作必须保留可见动词与值）。

审计脚本中的相关检查

循环中"禁止装饰性遥测/雷达"的偏好被固化进了 scripts/audit-ark-ui.mjs 的启发式检查：

javascript
check(/@media[^{]*(?:prefers-reduced-motion)/.test(css), 'Reduced-motion behavior is defined.', 'Add a prefers-reduced-motion rule for loops, transitions, and reveal effects.', 'error');

Source: audit-ark-ui.mjs

Configuration Options

迭代循环本身不引入可配置项——它是一组流程约束，而非组件。与循环相关的"参数"实际上是循环之前就已锁定的两轴选择，这些选择在循环内是只读的：

参数取值循环中的角色
familyark / endfield / exa / popucom / corporate步骤 1 中必须先声明；循环内不得切换，只能"借一个受约束特征"
depth1 minimal / 2 moderate / 3 complex / 4 maximal步骤 1 中必须先声明；单轮只允许改"一个 depth 行为"
证据模式source ledger 中的 Direct / Supported / Inference 条目每轮引用的精确公共模式；判据"更接近引用证据"的参照物
状态条尺寸参考36–42 px触发"一行 label + value 优于双层小字"规则的宽度区间

API Reference

迭代循环没有可调用的代码 API；其"接口"是两个命令行工具，在循环的第 6 步（验收）和证据补充时使用：

node scripts/audit-ark-ui.mjs <html-or-css-path>

参数：

  • <html-or-css-path>（string，必需）：要审计的 HTML 或 CSS 文件路径。

行为： 启发式检查无障碍/响应式缺失与常见模仿套路（含 reduced-motion 缺失等 error 级检查），对应循环四项检查中的静态部分。

Source: SKILL.md

python3 scripts/analyze-css-evidence.py <css-url-or-file>

参数：

  • <css-url-or-file>（string，必需）：公开 CSS 的 URL 或本地文件路径。

行为： 从公开 CSS 中提取颜色、字体、动效、几何证据。用于循环中发现现有台账不足以支撑某轮引用时补充新证据；新证据需记录页面 URL、资产 URL、检索日期、观察到的框架、颜色、字体与可复用模式，并区分直接观察与推断。

Source: SKILL.md

Failure Modes, Edge Cases & Concurrency

失败模式与回滚路径

循环对四类失败信号给出了明确的处理（回滚或修订本轮）：

失败信号判定来源处理
未在视觉上更接近引用证据步骤 5 同视口前后截图对比回滚或修订
可读性下降contrast 检查 + 截图检查回滚或修订
引入碰撞截图检查（裁切、文字碰撞）回滚或修订
真实机制更难找到截图检查（诚实机制可见性）回滚或修订

设计意图：四条信号里有三条是"可测量"的（对比度、碰撞、视觉相似度），第四条"真实机制可见性"是为了防止收敛把决策界面变成看不懂的图标墙——这与图标化底线共同构成防退化护栏。

边界情形

  • 规则/档案/参考视图本身就是显式详情层：这类视图应优化为扫描与分组，不得为了匹配持久 HUD 的密度而删除必要规则。这条规则防止收敛逻辑误伤本来就以"信息密度"为目的的屏幕。
  • 仅枚举下方区块的摘要：直接删除，定性为"重复导航"而非规则内容。
  • 自动隐藏过渡的截图取证：QA 入口可禁用 auto-hide 重放动画，但不得改变生产时序，且必须在过渡 UI 可见时完成捕获与验证。
  • 坐标自动化不可靠：改为通过 QA 入口暴露精确的模态/确认状态，而不是豁免交互证据——即不允许"静态推断行为"。
  • 借鉴第二 family：只允许借一个受约束特征；完整合并色板或装饰系统被禁止。

一致性约束（每次变更的原子性）

Implement 章节的一条约束在循环中同样适用：重命名 starter 的类名、ID、data 属性或 ARIA 目标时，必须在同一次修改中更新所有 JavaScript 选择器与引用——"一个样式完好但 DOM 接线断裂的页面不算完成"。这与单轮最小变更预算一起，构成循环的两条一致性约束：diff 可归因（小预算）且接线完整（同趟更新）。

Performance & Operational Notes

  • 每轮成本可控：单轮预算（一个 token 家族 + 一个 depth 行为 + 一个代表屏）保证每轮的工作量与风险都有上界，回滚成本也低。
  • 截图成本前置：要求同视口前后截图意味着迭代节奏受截图工具约束；对难以触达状态用 QA 入口提前消除"截图不到"的阻塞。
  • 验证顺序固定：compile → interaction → contrast → screenshot，四项通过才可重复。Validate 章节还要求在桌面与竖屏宽度渲染，检查裁切、碰撞、焦点顺序、激活态与 reduced-motion 行为，并在浏览器中实际操作主控件、检查运行时错误——明确禁止"仅从静态标记推断行为"。
  • 复检新鲜度：source ledger 标注研究时间为 2026-07-20（Asia/Shanghai），并注明"对时效敏感的声明需先复检在线来源"。做时间敏感的引用前应先复核。

Extension Points

  • 补充新证据：当现有台账不足以支撑某轮引用时，用 analyze-css-evidence.py 研究新的公开页面，并把观察结果按 Direct / Supported / Inference 分级记录进 references/source-ledger.md。分级本身就是扩展点——新证据必须能落到三档之一才能被引用。
  • family 借用：跨 family 借用是受控扩展点——单一受约束特征可以借，色板与装饰系统整体不可借。
  • depth 局部例外：Validate 第 11 条允许最密屏幕比所选 depth 高出至多一个局部档、主屏幕不低于所选档，但必须记录有意的局部例外——这是在循环内做局部偏离的唯一合法通道。
  • QA 入口扩展：可为任何难触达状态添加确定性 QA 入口，前提是显式抑制存档写入与删除、不改变生产时序。

Tests

循环的"测试"形态是 Validate 清单与审计脚本：

  • scripts/audit-ark-ui.mjs：对 HTML/CSS 做启发式检查，flag 缺失无障碍/响应式与常见模仿套路；与循环相关的 error 级检查包括 reduced-motion 规则缺失（动效循环/过渡/reveal 必须有 prefers-reduced-motion 处理）与响应式媒体查询缺失。
  • Validate 第 3 条：桌面与竖屏双宽度渲染检查。
  • Validate 第 4 条：浏览器实际操作主控件并检查运行时错误。
  • Validate 第 7–8 条：文案收敛的验收（冗余删除或 details 可达；图标化底线）。
  • Validate 第 9–10 条：对照 depth 评分判断 shell 变换、stage 层级、组件覆盖、状态仪表、动效与响应式重组（而非元素计数），并核对最密/最疏屏幕与所选档位的偏差。

Sources

(2 files)
(root)
SKILL.md
references
source-ledger.md