四档应用深度标尺
四档应用深度标尺（1 minimal / 2 moderate / 3 complex / 4 maximal）是 Ark UI 技能中与"风格族"正交的第二条设计轴：它衡量一套视觉语法被实现到何种覆盖度与编排度，而不是内容密度或装饰数量。本页是该标尺的权威参考，对应仓库中的 depth-levels.md 规范文件。
Purpose and Scope
本页完整覆盖以下内容：
- 双轴模型：
family × depth = visual contract，风格族与应用深度如何独立选择。 - 选择规则：用户显式指定、语义映射、默认假设、何时追问，以及局部层级浮动规则。
- 四档定义：每一档的目标、允许的壳层/舞台/组件/状态/动效/响应式行为。
- 第 3 档参考标尺（Complex-level calibration）：一个匿名化的系统级重构参照，用于锚定
complex与maximal的分界。 - 实现契约：稳定键（stable keys）、根属性（
data-ark-depth）、族变量与深度变量的分离。 - 六轴校验记分卡：评审时如何判断当前实现落在哪一档。
- 升档与降档流程：如何安全地增加或移除一层系统。
以下主题有意留给兄弟页面，本页只做交叉引用：
- 五个风格族各自的配方（palette、typography、shell grammar），见风格族配方页。
- 每个风格族在四档深度下的具体壳层、内容与仪表规则，见"风格族 × 深度矩阵"页（
references/family-depth-matrix.md）。 - 前端实现的完整证据模式（网格壳层、状态仪表、动效），见前端实现证据页（
references/frontend-evidence.md）。 - 共享视觉语法（ink/paper/signal、几何、栅格），见设计语言共享语法页（
references/design-language.md）。
Overview
Ark UI 的核心工作流要求在动手改代码之前锁定一个紧凑的设计契约：family（风格族）、depth（应用深度）、证据模式，以及主屏幕必须让用户完成什么任务。风格族与应用深度被刻意设计为正交的两条轴：endfield + minimal 和 endfield + maximal 共享同一身份，但视觉饱和度完全不同（见 SKILL.md）。
深度标尺的关键立场是：深度衡量的是实现覆盖度与编排度，而非内容密度。提高深度可以增加有意义的图层、响应式重构和状态感知动效，但绝不允许：伪造遥测数据（fake telemetry）、重复文案、增加颜色、缩小必要文字、削弱无障碍性（见 SKILL.md）。每一档都必须保留语义层级、真实数据、键盘可达、可读对比度、减弱动效支持（prefers-reduced-motion）以及用户自己的产品身份（见 depth-levels.md）。
典型使用场景：
| 场景 | 默认深度 | 依据 |
|---|---|---|
| 生产效率型 / 产品型 UI，用户未指定深度 | moderate | 选择规则第 3 条 |
| 游戏相邻、活动页、展示型 UI，用户未指定深度 | complex | 选择规则第 3 条 |
| 已有产品只做换肤，不希望改动布局 | minimal | "克制、轻量、几乎不改布局"的语义映射 |
| 旗舰展示、标题屏、活动微站 | maximal | "展示级、沉浸式、每屏独立编排、极繁"的语义映射 |
Architecture
双轴模型：family × depth = visual contract
深度不是一个独立样式表，而是与风格族变量分离的第二组变量。族变量拥有 ink、paper、signal、type、geometry 等视觉字符；深度变量拥有图层不透明度/数量、仪表覆盖率、动效可用性、可选装饰可见性（见 depth-levels.md）。两组变量通过根属性组合：
这一分离的设计意图非常明确：换深度不得改变语义内容或可访问名称。规范建议优先使用 CSS 变量、根 data 属性和共享组件变体，而不是为每个深度复制一套平行页面（见 depth-levels.md 与 frontend-evidence.md）。
四档递进与六轴评审结构
四个层级不是"装饰数量梯度"，而是六个评审维度上的覆盖度梯度。记分卡的每一轴都按四档给出判据，四个取值恰好对应 1/2/3/4 档（见 depth-levels.md）：
双轴模型与选择规则
选择规则（Selection rules）
规范给出了五条顺序执行的规则（见 depth-levels.md）：
- 尊重用户显式给出的层级或其中英文别名（
1/minimal/极简、2/moderate/中等、3/complex/复杂、4/maximal/极繁）。 - 语义映射：把"克制、轻量、几乎不改布局"映射到
minimal或moderate；把"完整重构、游戏化、华丽但可用"映射到complex；把"展示级、沉浸式、每屏独立编排、极繁"映射到maximal。 - 未指定时：生产效率/产品 UI 默认
moderate，游戏相邻、campaign 或展示 UI 默认complex，且必须在编辑前陈述该假设。 - 只有当深度会实质影响排期、素材生产、性能或架构时才追问一个简短问题。
- 单个屏幕可以在任务密度需要时局部浮动一个层级；产品声明的层级由壳层和代表性主屏幕决定。
这与 SKILL.md 中的工作流一致：第 3 步独立于第 2 步选择风格族，第 4 步处理用户指定、默认值与追问时机。审查阶段还有一条配套约束：最密的屏幕不得超过所选深度一个局部层级，主屏幕不得低于所选深度，且有意为之的局部例外必须记录（见 SKILL.md）。
选择流程
四档定义详解
1 / minimal / 极简（Identity layer）
极简档的目标是身份层：保留既有信息架构和大部分组件结构，只把家族身份注入高价值表面（见 depth-levels.md）：
- 保留现有信息架构与大多数组件结构。
- 应用家族 tokens、字阶层级、圆角/规则线语法、焦点态，以及一个强选择/操作提示。
- 每屏使用 0 或 1 个持久装饰系统，例如安静的规则栅格或一个裁切标识。
- 动效仅限直接交互反馈；避免环境循环（ambient loops）与全区块编排。
- 只重构高价值表面：壳层、主操作、激活态导航、输入/composer、一个代表性面板。
- 验收直觉：成品应当"先读作产品、其次才读作家族"。
典型用途：既有产品 UI、工具类应用、高密度编辑器（见 depth-levels.md）。
2 / moderate / 中等（Shell and stage layer）
中等档的目标是壳层与舞台层（见 depth-levels.md）：
- 在有用处重组壳层：rail/topbar、操作条、stage/content 分割，或节标题系统。
- 使用 1–2 个连贯的舞台图层，例如"网格 + 方向规则线"、"图像水洗 + 元数据轨"，或"轨道 + 档案遮罩"。
- 覆盖共享控件与主要面板，低优先级工具表面仍贴近原生惯例。
- 使用一种 reveal 动效族 + 直接交互反馈；至多允许一个克制的注意力循环。
- 竖屏导航与主操作需要重组，但不需要为每个 section 做定制美术方向。
- 验收直觉：家族身份已不可误认，但内容仍占构图主体。
典型用途：生产环境仪表盘、门户、落地页。
3 / complex / 复杂（System-wide reconstruction）
复杂档的目标是系统级重构（见 depth-levels.md）：
- 把整个壳层改造为多个操作分区，带刻意的非对称与边缘仪表。
- 在代表性屏幕上使用 2–4 个协调的舞台系统：工程网格、方向扇区、标定装置、超大标识、有界纹理或图像遮罩。
- 完整样式化共享组件集：导航、composer/输入、对话框、菜单、代码/数据表面、状态态、焦点、选中和滚动行为。
- 协调 2 个以上动效族，例如 load/reveal 与 state/attention，并提供减弱动效等价物。
- 桌面与竖屏布局重新美术方向，而不是等比缩放。
- 每个持久仪表必须有真实的分组、方向、状态或世界观角色；中性表面仍占主导。
- 验收直觉：体验读起来是"被重构的系统"，而非"换肤的皮肤"。
典型用途：游戏相邻应用、启动器、运营控制台。
4 / maximal / 极繁（Bespoke experiential system）
极繁档的目标是定制体验系统（见 depth-levels.md）：
- 为主要 section 或模式构建定制构图，但保留一个全局壳层语法。
- 仅在舞台能支撑的地方使用 4–6 个连贯视觉图层；按层级分配而非填满每个空隙。
- 仪表必须状态驱动：路由、模式、进度、选择、媒体或已验证数据改变构图。
- 把 section 过渡、遮罩、艺术图层与控件反馈协调为一个动效系统；提供同等清晰的静态减弱动效构图。
- 为桌面、竖屏、短宽（short-wide）和减弱动效状态分别重构插画、排版、导航与操作位置。
- 显式预算性能、加载、对比度与注意力分散；在低功耗或内容密集屏幕降级到
complex。 - 验收直觉：体验可以很华丽，但主操作与当前状态仍然比装饰更快被找到。
典型用途：旗舰展示、标题屏、活动微站。
四档对照总表
| 属性 | 1 minimal | 2 moderate | 3 complex | 4 maximal |
|---|---|---|---|---|
| 稳定键 | minimal | moderate | complex | maximal |
| 转化目标 | 身份层 | 壳层与舞台层 | 系统级重构 | 定制体验系统 |
| 壳层 | 保留原生结构 | 有用之处重组 | 多分区系统级 | 按模式定制 |
| 舞台图层 | 0–1 个持久装饰系统 | 1–2 个连贯图层 | 2–4 个协调系统 | 4–6 个（按层级分配） |
| 组件覆盖 | 仅高价值表面 | 共享主控件 | 完整共享组件集 | 状态特定变体 |
| 状态仪表 | 一个强选择提示 | 分组状态 | 系统级真实状态 | 改变构图的实时状态 |
| 动效 | 仅直接反馈 | reveal 族 + ≤1 注意力循环 | ≥2 协调动效族 | section 级编排 |
| 响应式 | 安全堆叠 | 壳层适配 | 完整重新美术方向 | 模式特定构图 |
| 典型用途 | 既有产品/工具/密集编辑器 | 仪表盘/门户/落地页 | 游戏相邻/启动器/控制台 | 旗舰展示/标题屏/微站 |
第 3 档参考标尺（Complex-level calibration）
规范为 3 / complex 提供了一个匿名化的系统级重构参照，用于消除"多复杂才算第 3 档"的主观性（见 depth-levels.md）。该参照：
- 转化了 topbar、sidebar、主战场、composer、对话框、代码/数据表面、选中态、焦点态与状态覆盖层。
- 主舞台组合了工程网格、方向扇区、标定圆环、边缘刻度、大标识与受控的 signal 黄色锚点。
- 使用相互分离的壳层/内容/覆盖规则，并带响应式与减弱动效处理。
- 它低于
maximal的原因：主要屏幕并未各自获得定制美术方向；仪表大多是结构性的而非由实时产品状态驱动；动效克制而非跨 section 编排。
最重要的一条反模式警告：不要用"装饰比参照多"作为第 4 档的唯一判据。maximal 需要更深的状态集成、定制构图、响应式编排和性能回退，而不是更多装饰。
实现契约（Implementation contract）
稳定键与根属性
规范要求在代码中使用稳定键（stable keys），HTML 侧通过根属性表达契约，React 侧通过组件 props 表达：
<html data-ark-theme="endfield" data-ark-depth="complex">Source: references/depth-levels.md
<ArkShell theme="endfield" depth="complex" />Source: references/depth-levels.md
SKILL.md 的实现规范要求：尽可能用根属性表达契约（data-ark-theme="endfield" 与 data-ark-depth="complex"），并保持组件选择器语义化，使任一轴都能独立变化（见 SKILL.md）。React starter 与原生 starter 资产都在家族选择器旁暴露了 data-ark-depth / depth（见 SKILL.md）。
深度变量与族变量的分离
前端证据文档给出了推荐写法——深度放在独立的根属性上，深度改变的是覆盖度与编排，而不是家族调色板（见 frontend-evidence.md）：
1[data-ark-depth="minimal"] {
2 --ark-stage-layer-opacity: .18;
3 --ark-instrument-shadow: none;
4}
5
6[data-ark-depth="complex"] {
7 --ark-stage-layer-opacity: .68;
8 --ark-instrument-shadow: .4rem .4rem 0 color-mix(in srgb, var(--ark-ink), transparent 86%);
9}Source: references/frontend-evidence.md
注意深度变量（--ark-stage-layer-opacity、--ark-instrument-shadow）引用的是族变量 --ark-ink——这正是双轴分离的实现形式：深度控制"用多强"，族决定"用什么颜色"。
React starter 中的深度梯度
React 资产把四档实现为一组具体的深度变量梯度（见 ark-ui.css）：
1.arkR-shell[data-ark-depth="minimal"]{--ark-depth-rule:12%;--ark-depth-panel-min:15rem;--ark-depth-shadow:0 0 0 transparent}
2.arkR-shell[data-ark-depth="moderate"]{--ark-depth-rule:18%;--ark-depth-panel-min:18rem;--ark-depth-shadow:2px 2px 0 color-mix(in srgb,var(--ark-ink),transparent 90%)}
3.arkR-shell[data-ark-depth="complex"]{--ark-depth-rule:24%;--ark-depth-panel-min:22rem;--ark-depth-shadow:5px 5px 0 color-mix(in srgb,var(--ark-ink),transparent 86%)}
4.arkR-shell[data-ark-depth="maximal"]{--ark-depth-rule:34%;--ark-depth-panel-min:26rem;--ark-depth-shadow:9px 9px 0 color-mix(in srgb,var(--ark-signal),transparent 42%)}Source: assets/react/ark-ui.css
这组梯度展示了一个重要细节：maximal 的阴影不再引用 --ark-ink 而是引用 --ark-signal——深度提升到最高档时，仪表从"结构性的墨色阴影"升级为"信号色锚点"，这与第 4 档"状态驱动仪表"的定义一致。组件层面（如 .arkR-rail）则消费这些变量（--ark-depth-rule 控制规则线不透明度），使壳层外观随深度整体变化（见 ark-ui.css）。
六轴校验记分卡（Validation scorecard）
在代表性视口上按六条轴审查实现（见 depth-levels.md）：
| 轴 | 第 1 档判据 | 第 2 档判据 | 第 3 档判据 | 第 4 档判据 |
|---|---|---|---|---|
| Shell transformation 壳层转化 | 保留原生结构 | 有用之处重组 | 系统级转化 | 按模式定制 |
| Stage layering 舞台分层 | 无 / 一层 | 一至两层 | 二至四层连贯系统 | 四至六层 |
| Component coverage 组件覆盖 | 仅关键控件 | 共享主控件 | 完整共享组件集 | 状态特定变体 |
| State instrumentation 状态仪表 | 选择提示 | 分组状态 | 系统级真实状态 | 改变构图的实时状态 |
| Motion coordination 动效协调 | 仅直接反馈 | reveal + 直接 | 多个协调动效族 | section 级编排 |
| Responsive recomposition 响应式重构 | 安全堆叠 | 壳层适配 | 完整重新美术方向 | 模式特定构图 |
两条关键的判读纪律：
- 层级是整体判断（holistic judgment）。不要机械地平均分数，也不要为了拉高某轴分数而添加装饰性元素。
- 失败条件：如果额外深度降低了任务清晰度、真实状态可见性、可访问性或超出产品性能预算，该层级即判定失败。
审查流程（SKILL.md）要求把代表性屏幕与所选深度逐轴对比，判断的是壳层转化、舞台图层、组件覆盖、状态仪表、动效与响应式重构——不是原始元素数量。截图验证脚本进一步从工程上固化了这些不变量：四档深度都必须保持真实数据、清晰主任务、键盘可用、可见焦点、可读对比度、响应式布局和 prefers-reduced-motion，且 --mobile 模式下出现横向溢出即失败（见 README.md）。
升档与降档（Escalation and reduction）
规范把深度调整定义为增删"缺失系统"的受控流程，而不是加装饰或删元素（见 depth-levels.md）：
降档的保留清单必须始终成立：导航、状态、主操作、焦点、标签与内容不可被移除。禁止通过隐藏必要信息或把文字缩小到低于舒适阅读尺寸来"模拟极简"——这是极简档最常见的反模式。
Failure Modes、边界情况与一致性约束
以下红线在规范中被反复强调，任何一档都不例外：
| 反模式 | 违反的不变量 | 出处 |
|---|---|---|
| 为提升档位添加伪造遥测（fake telemetry） | 真实数据 | SKILL.md L35、depth-levels.md L21 |
| 复制文案、增加颜色来"显深" | 深度≠内容密度/颜色数 | SKILL.md L35 |
| 缩小必要文字尺寸 | 可读对比度 | depth-levels.md L121 |
| 隐藏必要信息来"降档" | 极简不可牺牲可用性 | depth-levels.md L121 |
| 只做等比缩放不做竖屏重组 | 响应式重构 | depth-levels.md L64 |
| "装饰比参照多"就自评第 4 档 | maximal 需状态集成 + 定制构图 + 编排 + 回退 | depth-levels.md L87 |
| 换深度时改动语义内容或可访问名称 | 双轴正交性 | depth-levels.md L103 |
| 为每个深度复制整套平行页面 | 应使用变量 + 共享变体 | frontend-evidence.md L63 |
边界情况的处理规则：
- 局部浮动：单屏可因任务密度浮动一个层级，但壳层与代表性主屏幕决定产品声明层级（选择规则第 5 条）。审查时需确认最密屏幕不超过所选深度一个局部层级、主屏幕不低于所选深度，并记录有意例外。
- 低功耗/内容密集屏幕：
maximal档显式要求预算性能、加载、对比度与注意力，并在这些约束吃紧时降级到complex（depth-levels.md L75）。 - 减弱动效：第 3 档要求 reduced-motion 等价物；第 4 档要求提供"同等清晰的静态构图"（depth-levels.md L63, L73）。
- 多族场景：家族选择与深度选择保持为两个独立决策；需要对比多个族或族特定深度行为时才读
references/family-depth-matrix.md（SKILL.md L25）。
Extension Points
标尺本身提供了三类扩展入口：
- 稳定键扩展：任何新项目只要沿用
data-ark-depth="minimal|moderate|complex|maximal"四个稳定键与--ark-*深度变量命名，即可复用同一套正交契约。tokens 建议参考assets/tokens/ark-ui.tokens.json后重命名以匹配目标项目（SKILL.md L42-L43）。 - 深度变量扩展：深度变量集合（图层不透明度/数量、仪表覆盖率、动效可用性、装饰可见度）可以按项目需要增加新维度，只要保持"深度变量不改变族调色板"的边界（depth-levels.md L101）。
- 族特定深度行为：某个风格族在特定档位的特殊规则应写入
references/family-depth-matrix.md，而不是修改本标尺，保证标尺保持族无关（family-agnostic）。
Related Links
- references/depth-levels.md — 本页对应的完整四档规范源文件。
- SKILL.md — 核心工作流、契约锁定与审查步骤。
- references/frontend-evidence.md — 深度变量的前端实现证据与推荐写法。
- assets/react/ark-ui.css — React starter 中四档深度变量的参考实现。
- README.md — 仓库总览、"四档深度"章节与截图验证约束。
- 风格族选择与五族配方、共享视觉语法、风格族 × 深度矩阵等主题见对应兄弟页面。