设计契约与任务决策
Ark UI 技能把每一次 UI 任务收敛为一份可复核的 设计契约（design contract）：先从五个证据化的风格族中选定唯一一个 family，再独立选定一个 depth（1 极简 / 2 中等 / 3 复杂 / 4 极繁），并连同证据模式与"主屏必须让用户完成什么"一起陈述出来，然后才允许改动代码。本页说明契约的构成、任务决策的规则链、默认值与询问策略，以及契约在代码中的落点。
Purpose and Scope
本页覆盖（目录路径 3-core-workflow/3.1-design-contract）：
- 双轴模型：
family × depth = visual contract的语义与正交性。 - 任务决策链：从勘察目标项目、选族、选深度，到"Lock the design contract"的完整顺序。
- 决策规则与默认值：显式深度保留、措辞映射、产品类型默认深度、何时才提问。
- 契约的代码表示：
data-ark-theme/data-ark-depth根属性约定。 - 验证侧的契约回查：audit 脚本与深度比对如何把契约变成验收标准。
本页有意不覆盖以下兄弟主题（它们有自己的页面）：
- 四级深度的完整评分细则、complex 级校准基线与验证记分卡 → 见
references/depth-levels.md（深度等级页）。 - 风格族的视觉语法与配方 → 见
references/design-language.md与references/recipes.md。 - 族 × 深度的交叉适配矩阵 → 见
references/family-depth-matrix.md。 - 证据采集、出处与合法边界 → 见
references/source-ledger.md与references/legal.md。 - 迭代精修的"证据锁"循环细节 → 见核心工作流下的迭代页。
Overview
README 用一句话定义了这套技能的契约本质：
上图是这套技能的设计契约：先选择一个风格族，再独立选择实施深度。深度衡量的是壳层、舞台、组件、状态、动效与响应式的覆盖程度，不是页面中堆放了多少内容。
Source: README.md
为什么要契约化？ SKILL.md 开篇即说明动机：用文档化的视觉与实现证据来构建原创界面，"而不是模糊的'赛博punk'式提示"（not from vague "cyberpunk" prompting）。契约的存在把一次主观的视觉任务拆成两个可审计的正交决策，从而：
- 防止风格平均化 —— 明确禁止"把每个产品平均成一种风格"，避免五族配色（青、信号黄、水色、品红、橙、酸绿）混入同一界面。
- 把"做多少"与"什么味道"解耦 ——
endfield + minimal与endfield + maximal共享身份但不共享视觉饱和度，两轴可以独立变更。 - 给验证提供判据 —— 契约中的
depth直接成为后续 Validate 阶段的比对基准（"按所选深度判断壳层变换、舞台层级、组件覆盖、状态仪表、动效与响应式重排——而非原始元素数量"）。
典型使用场景：设计/实现/审计/重构 Hypergryph 风格相邻的落地页、仪表盘、菜单、HUD 式面板、设计系统、HTML/CSS/JS/React 组件，以及双语技术界面与视觉 QA——凡要求"带这一族相似度但不抄袭受保护的 logo 与美术"的请求。
Architecture
下图是任务决策到契约锁定的完整管线（对应 SKILL.md 的 "Start here" 七步 + "Lock the design contract" 一节）。虚线右侧的证据层只在需要时读取——设计语言与深度细则必读，recipes 只读所选族，family-depth-matrix 只在多族对比或族特有深度行为时读取，frontend-evidence 只在实现或代码审查时读取。
分层解读：
- 任务决策阶段严格发生在改代码之前：勘察 → 两次独立选择 → 契约陈述。
Inspect同时为两轴提供输入（现有 tokens 决定族如何映射，任务密度与产品类型决定深度）。 - 证据层是契约的引用来源——契约里必须写明"证据模式（evidence pattern）"，即本次将依据
references/source-ledger.md中的哪条公开模式；读取范围被刻意收窄（只读所选族的 recipes），以控制上下文成本并防止跨族污染。 - 执行层把契约写进代码（根属性），再用
scripts/audit-ark-ui.mjs与深度记分卡回查；不达标则回到契约重新评估，而不是在实现层随手加装饰。
双轴模型：family × depth = visual contract
契约的核心公式来自深度细则文档：
family × depth = visual contract
Source: references/depth-levels.md
两轴职责被明确划分，这是整个体系可组合的根基：
| 轴 | 决定什么 | 不决定什么 |
|---|---|---|
| family（风格族） | 调色板、字体排印、壳层语法、几何语言、动效性格 | 实施的完备程度、装饰数量 |
| depth（应用深度） | 语法对产品的改造完备度：壳层覆盖、舞台分层、组件处理、状态仪表、动效协同、响应式重排 | 配色方案、品牌身份、产品气质 |
关键约束（直接写入细则）：
Depth is not copy density, number of cards, color count, or permission to invent telemetry. Every level preserves semantic hierarchy, truthful data, keyboard access, readable contrast, reduced motion, and the user's product identity. Source: references/depth-levels.md
即：提高深度永远不是加内容、加颜色、编造假遥测的许可证；语义层级、真实数据、键盘可达、可读对比度、reduced-motion 与用户产品身份在每一级都必须保留。
五个风格族（family 轴的合法取值）
1- `ark`: black/white/cyan industrial information system.
2- `endfield`: white/charcoal/signal-yellow technical field system.
3- `exa`: midnight/white/aqua cosmic-archival system with serif contrast.
4- `popucom`: blue/yellow/orange playful platform system.
5- `corporate`: black/white/acid-lime restrained studio identity.Source: SKILL.md
选择规则是"选一个族"，并明确"不要把每个产品平均成一种风格"（do not average every product into one style）。
四级应用深度（depth 轴的合法取值）
1- `1 / minimal / 极简`: family identity through tokens, type, geometry, and one strong state cue.
2- `2 / moderate / 中等`: family shell plus one controlled texture/instrument layer and restrained reveal motion.
3- `3 / complex / 复杂`: multi-zone shell, layered stage, broad component coverage, and coordinated instrumentation.
4- `4 / maximal / 极繁`: bespoke section compositions, state-driven instrumentation, and coordinated motion across a fully re-art-directed responsive system.Source: SKILL.md
四级的官方速查（稳定键 / 变换目标 / 典型用途）：
| 等级 | 稳定键 | 变换目标 | 典型用途 |
|---|---|---|---|
| 1 极简 | minimal | 身份层 | 现有产品 UI、工具、密集编辑器 |
| 2 中等 | moderate | 壳层与舞台层 | 生产级仪表盘、门户、落地页 |
| 3 复杂 | complex | 全系统重构 | 游戏相邻应用、启动器、运营控制台 |
| 4 极繁 | maximal | 定制体验系统 | 旗舰展示、标题屏、活动微站 |
Source: references/depth-levels.md
核心流程：改代码之前锁定契约
SKILL.md 的 "Lock the design contract" 一节给出了契约的定义与交互形态：
1Before changing code, state a compact contract: `family`, `depth`, evidence pattern,
2and what the primary screen must let the user do. Treat family and depth as
3orthogonal axes: `endfield + minimal` and `endfield + maximal` share identity
4but not visual saturation.
5
6When the user asks to choose, present the four numbered levels with one
7recommended level based on product type. Keep family selection and depth
8selection as separate decisions instead of showing a large cross-product matrix.Source: SKILL.md
要点拆解：
- 契约四要素：
family、depth、evidence pattern（引用的公开证据模式）、主屏任务（主屏必须让用户完成什么）。第四项是可用性锚点，防止深度升级后主操作反而更难找到。 - 呈现方式：用户请技能代选时，展示四个编号层级并基于产品类型给出一个推荐层级；族选择与深度选择保持两个独立决策，不要展示一个大型的族×深度交叉矩阵（交叉矩阵另有文档，仅在多族对比时按需读取）。
- 时序约束："Before changing code"——契约是第一道闸门，未陈述契约即开始编码属于违规流程。
决策时序图
决策规则与默认值（depth 选择规则链）
深度细则文档把 depth 的选择固化为五条规则：
- Honor an explicit level or its Chinese/English alias.
- Map "克制、轻量、几乎不改布局" to
minimalormoderate; map "完整重构、游戏化、华丽但可用" tocomplex; map "展示级、沉浸式、每屏独立编排、极繁" tomaximal. - When unspecified, use
moderatefor productivity/product UI andcomplexfor game-adjacent, campaign, or showcase UI. State the assumption before editing. - Ask a short question only when depth materially changes schedule, asset production, performance, or architecture.
- A screen may vary locally by one level when task density requires it. The shell and representative primary screen determine the product's declared level.
Source: references/depth-levels.md
设计意图解读：
- 规则 1（显式优先）：SKILL.md 对应条目表述为 "If the user specifies a depth, preserve it."——用户的选择不可被"优化"。
- 规则 2（措辞映射）：把中文/英文口语化描述映射到稳定键，避免枚举式追问。
- 规则 3（默认 + 声明假设）：默认深度按产品类型二分——生产力/产品 UI 用
moderate，游戏相邻/活动/展示 UI 用complex；关键是编辑前要说出假设，而不是默默决定。 - 规则 4（最小提问）：只有当深度会实质改变日程、素材生产、性能或架构时才问一个短问题——这与 SKILL.md 的 "Ask only when the depth would materially change scope or rework" 一致。
- 规则 5（局部 ±1 级弹性）：单屏可因任务密度局部浮动一级，但产品的声明等级由壳层与代表性主屏决定。这解释了 Validate 阶段的两个对称检查：最密屏不得超出所选深度一级以上，主屏不得低于所选深度。
契约的代码表示（根属性约定）
实现层把契约物化为两个根属性，使任一轴都能独立变更而不触碰组件选择器：
- Represent the contract with root attributes when practical:
`data-ark-theme="endfield"` and `data-ark-depth="complex"`.
Keep component selectors semantic so either axis can change independently.Source: SKILL.md
契约落地配套的代码资产（SKILL.md "Bundled code" 节确认）：
assets/starter-vanilla/：无依赖响应式起点。assets/react/ArkUI.jsx+assets/react/ark-ui.css：可移植 React 壳层、面板与主题切换器。assets/tokens/ark-ui.tokens.json：五个证据化主题族（安全回退字体栈）。assets/showcases/：五个可检视的 complex 级原创样例，带四级深度控制。- Starter 与 React 资产在既有族选择器之外同时暴露
data-ark-depth/depth。
Source: SKILL.md
设计意图：属性放在根节点而非散落在组件上，意味着"换族"或"调深度"是一次属性值的变更；组件选择器保持语义化（.nav、.composer），族/深度差异由根属性作用域下的 token 层吸收。这与 assets/react/ark-ui.css、assets/react/ArkUI.jsx 的实现一致。
语义优先的实现约束
契约之后的第一批实现规则（节选）：
1- Start from semantic content and task hierarchy. Use the visual grammar to
2 expose state, navigation, and priority.
3- Reuse project components and tokens when present. Otherwise copy
4 `assets/starter-vanilla/` or use `assets/react/ArkUI.jsx` with
5 `assets/react/ark-ui.css`.
6- Prefer CSS/SVG geometry, gradients, rules, masks, and original abstractions
7 over copied game art.
8- Keep one dominant accent. Treat secondary accents as state or product-family
9 signals.Source: SKILL.md
这些规则是契约在执行层的守门条款：语法用于暴露状态、导航与优先级（不是装饰），主色只有一个，次强调色只承担状态或族信号。
契约红线（Avoid 清单中的契约相关条目）
契约不只是"选了什么"，还包含不可做什么。以下红线直接约束双轴：
| 红线 | 针对的轴 | 说明 |
|---|---|---|
| 不因五族配色并存就混用青/信号黄/水色/品红/橙/酸绿于同一界面 | family | 族选择是唯一的 |
不把 maximal 解释为随机 HUD 噪声、假系统码、永动或每组件装饰的许可 | depth（4） | 高深度仍需信息角色 |
不用删除标签、状态、焦点提示、前置条件或必要说明来实现 minimal | depth（1） | 低深度不等于删语义 |
| 不加无信息角色的随机六边形、终端噪声、扫描线、glitch、霓虹渐变、密集 HUD 装饰 | 两轴通用 | 防伪风格套路 |
| 不把主内容藏在开屏、自动音频或仅悬停可访问的控件后 | 可用性底线 | 契约中的"主屏任务"保底 |
Source: SKILL.md
失败模式、边界与一致性
- 契约缺失即失败：流程要求契约发生在 "Before changing code" 之前；跳过契约直接编码意味着后续验证没有判据。
- 轴耦合失败：把
family的视觉饱和度与depth绑定（认为选endfield就必须maximal）违反正交性；endfield + minimal与endfield + maximal同身份不同饱和度。 - 深度误读失败：把深度理解为内容密度/卡片数/颜色数，导致用假遥测、重复文案填满空间——被规则显式禁止。
- 提问时机失败：对每个请求都追问深度会造成决策疲劳；规则链要求先默认并声明假设，仅在实质影响范围时提问。
- 局部漂移失败：单屏超过所选深度一级以上，或主屏低于所选深度，都会在 Validate 第 9/10 步被记分卡拦下；有意例外必须记录在案。
- 跨族借用的边界：迭代循环允许在需要第二个族时"只借一个受限特征"（one constrained trait），不允许合并其完整配色或装饰系统——契约中的族字段保持唯一。
验证与运维（契约如何被检查）
Validate 阶段的两条直接把契约变成验收标准：
- 运行打包的启发式审计（无障碍/响应式缺失与常见模仿套路告警）：
bash
node "$CODEX_HOME/skills/ark-ui/scripts/audit-ark-ui.mjs" <html-or-css-path> - 第 9/10 步按所选深度比对代表性屏幕：判断壳层变换、舞台层级、组件覆盖、状态仪表、动效与响应式重排——而非原始元素数量；确认最密屏不超过所选深度一级以上、主屏不低于所选深度，并记录有意局部例外。
Source: SKILL.md
运维侧相关脚本（SKILL.md "Bundled code" 节）：
| 脚本 | 在契约语境中的角色 |
|---|---|
scripts/scaffold-ark-ui.py | 把 starter 复制到新/空目标，保证契约起点干净 |
scripts/audit-ark-ui.mjs | 启发式检查契约红线（可达性、响应式、模仿套路） |
scripts/analyze-css-evidence.py | 为新页面采集证据，扩充契约引用的 evidence pattern 库 |
scripts/capture-showcases.mjs | 在桌面与竖屏 CDP 视口渲染五个样例，横向溢出即失败 |
新增官方页面研究时，要求把页面 URL、资产 URL、抓取日期、观察到的框架、颜色、字体与可复用模式记录进 references/source-ledger.md，并区分直接观察与推断——这保证契约中引用的 evidence pattern 可追溯。
使用示例
示例 1：契约四要素的陈述形态
来自 "Lock the design contract" 的规范表述——改代码前给出的紧凑契约应包含这四项：
Before changing code, state a compact contract: `family`, `depth`,
evidence pattern, and what the primary screen must let the user do.Source: SKILL.md
示例 2：契约写入根属性
data-ark-theme="endfield" data-ark-depth="complex"
Source: SKILL.md
实现 assets/react/ArkUI.jsx 的主题切换器即围绕这一约定工作：切族只改 data-ark-theme，调深度只改 data-ark-depth/depth，组件选择器保持语义化，两轴互不干扰。
示例 3：代选深度时的呈现规则
When the user asks to choose, present the four numbered levels with one
recommended level based on product type.Source: SKILL.md
即：展示 1/2/3/4 四个编号层级，并依据产品类型（生产力 → moderate；游戏相邻/展示 → complex）给出单一推荐，而不是抛出族×深度大矩阵让用户自己组合。
配置选项
本页语境下的"配置"是契约输入参数，而非传统键值配置：
| 参数 | 取值 | 默认 | 说明 |
|---|---|---|---|
family | ark / endfield / exa / popucom / corporate | 由勘察与用户语境推断 | 唯一选择；禁止多族平均 |
depth | 1/minimal/极简、2/moderate/中等、3/complex/复杂、4/maximal/极繁 | 生产力 UI → moderate；游戏相邻/展示 UI → complex | 用户显式指定则保留；接受中英文别名 |
| evidence pattern | references/source-ledger.md 中的公开模式 | 按所选族 | 契约四要素之一 |
| 主屏任务 | 自然语言描述 | — | 主屏必须让用户完成什么；验证主操作可发现性的锚点 |
data-ark-theme | 字符串（族键） | 取决于所选资产 | 根属性，表示 family 轴 |
data-ark-depth / depth | minimal/moderate/complex/maximal | 取决于所选资产 | 根属性/prop，表示 depth 轴 |
相关链接
- SKILL.md — 契约定义（"Lock the design contract"）、Start here 决策链、Avoid 红线与 Validate 流程
- references/depth-levels.md — 双轴模型、选择规则、四级深度定义
- README.md — 契约的一句话总述
- references/family-depth-matrix.md — 族特有深度适配（多族对比时读取）
- assets/react/ark-ui.css / assets/react/ArkUI.jsx — 契约根属性的可执行实现