风格族 × 深度矩阵

风格族 × 深度矩阵（family × depth matrix）是 Ark UI 技能的核心设计契约：它规定五个风格族（ark、endfield、exa、popucom、corporate）在四档应用深度（minimal、moderate、complex、maximal）下各自应当如何处理壳层、内容所有者、舞台分层、状态仪表与响应式重编排，防止"换皮不换骨"或"所有族长成一个样子"。

目的与范围

本页是设计语言参考中的矩阵总览页，覆盖以下内容：

• 矩阵的定位与使用方式（两轴模型 family × depth = 视觉契约）
• 五个风格族 × 四档深度的完整规则矩阵（每族每档的壳层、内容、仪表要求）
• 各族的内容测试（content test）与跨族校验清单
• 深度选择规则、默认值与实现契约中的稳定键（data-ark-depth / depth）
• 常见失效模式（族同质化、纯装饰式升级等）

以下相关主题有意留给兄弟页面，本页只做引用：

• 每个风格族的详细配方（调色板、字体、几何、动效细节）：见 references/recipes.md
• 四档应用深度的通用评分标准与校验记分卡：见 references/depth-levels.md
• 共享视觉语法（层级、可读性、焦点规则）：见 references/design-language.md
• React 组件完整 API 与前端实现证据：见 references/frontend-evidence.md

概述

Ark UI 的整个设计模型建立在一条两轴等式上：family × depth = visual contract（风格族 × 深度 = 视觉契约）。其中：

• **风格族（family）**控制界面的视觉性格：调色板、排版、壳层语法、几何与动效性格。它回答"这套界面看起来像谁"。
• **应用深度（depth）**控制这种性格覆盖到什么程度：壳层覆盖、舞台分层、组件处理、状态仪表、动效协同与响应式重艺术指导。它回答"这种性格渗透到系统的多深"。

Source: README.md

深度衡量的是壳层、舞台、组件、状态、动效与响应式的覆盖程度，不是页面中堆放了多少内容。深度也不是文案密度、卡片数量、颜色数量，或发明遥测数据的许可——每一档都必须保留语义层级、真实数据、键盘访问、可读对比度、减弱动效支持与用户的产品身份（见 references/depth-levels.md）。

典型用例：

• 多族对比：需要在两个风格族之间做取舍，或验证切换族后构图确实改变。
• 族内深度适配：确定某个族（如 endfield）在 minimal 与 maximal 下分别该做到什么程度。
• 审查与验收：用跨族校验清单判定产出是否"换族未换构图"或"换深度却改了内容语义"。

按 SKILL.md 的工作流约定，只有当任务涉及多族比较或族特有的深度行为时才需要读取矩阵文件本身：

For multi-family comparisons or family-specific depth behavior, also read references/family-depth-matrix.md。

Source: SKILL.md

架构：两轴模型

矩阵的整体结构是两个正交的选择轴汇聚为一个视觉契约。风格族轴有五个可选值，深度轴有四个可选值，两者独立选择、互不决定：

设计意图在于：先按产品语义选族，再按实现覆盖选深度。矩阵文件开头明确警告了最常见的误用：

Choose a family from product semantics, then choose a depth from implementation coverage. Do not make every family use the Endfield rail, grid, and readout. At complex, every family needs a complete shared component system, but its shell, stage, content owner, instrumentation, and motion remain family-specific.

Source: references/family-depth-matrix.md

换句话说：complex 档要求每个族都交付完整的共享组件系统（导航、输入、对话框、菜单、代码/数据表面、状态等），但壳层、舞台、内容所有者、状态仪表与动效必须保持族特异性——组件系统的完整性是深度要求，视觉语法不可互相借用。

矩阵摘要：五个族的三个锚点

矩阵为每个族定义了三个不变锚点——内容所有者（这一族真正展示的信息主体）、壳层签名（辨识这一族的壳层构件）、complex 档的标志性仪表：

Source: references/family-depth-matrix.md

这张摘要表是整张矩阵的"目录"：内容所有者决定该族的内容测试（任何不服务于内容所有者的装饰都应删除），壳层签名决定各族在换族时必须改变的构图部分，**Complex 档仪表则是该族在系统级重构时的标志性状态区域。

矩阵单元的结构

矩阵中的每一个单元格（某个族在某个深度下的规则）都遵循相同的字段结构：

四个维度随深度递增而扩张（minimal 只触及识别层，maximal 触及全套舞台与转场编排），而内容测试在所有深度下恒定成立——它是族的底线约束，不是深度选项。这就是为什么同一族在不同深度下仍能被识别为同一族：内容所有者与壳层签名不变，变化的只是覆盖广度。

核心矩阵：五族 × 四档

以下内容逐族展开矩阵原文中的每条规则，并补充设计意图说明。

Ark（黑边壳层 × 青色状态）

Ark 族的内容所有者是"当前作战或所选档案"，视觉性格建立在黑色边缘壳层与青色激活规则之上。

• minimal：保留现有壳层；加入紧凑层级、黑/白中性系统、一条青色选中规则与显式焦点。
• moderate：引入一个黑边坞站、索引化区块标签，以及蓝图线条或去饱和媒体二选一（不得同时使用）。
• complex：协同编排作战舞台、档案、新闻/存档列表、导航、对话框、代码/数据与响应式边缘停靠。使用两到四层结构，例如遮罩媒体、蓝图规则、大号标识符与状态基线。
• maximal：分别为作战、干员、世界与媒体模式做独立艺术指导，同时保留黑边壳层与青色状态语法。
• 内容测试：删除任何不改变决策或不指向真实记录的代码、坐标或仪表。

Source: references/family-depth-matrix.md

注意 moderate 档"蓝图线条或去饱和媒体，二选一"的措辞——这是矩阵中典型的克制条款：中等深度的舞台分层只允许一组装饰系统，防止在未达到 complex 的协同编排能力前就堆叠多层。

Endfield（浅色导轨 × 黄色楔块）

Endfield 族的内容所有者是"当前外勤任务或后勤计划"。

• minimal：保留现有壳层；加入技术字体、米白/炭黑 token、一个黄色动作标记与方形焦点。
• moderate：添加浅色导轨或黑色工具坞站（其一），外加一个分段的现场层。
• complex：协同编排后勤/现场舞台、路线矩阵、动作条、任务状态、对话框、代码/数据与响应式重构，使用两到四层工程化结构。
• maximal：分别为建造、探索、干员与报告模式做独立艺术指导，由真实任务状态驱动。
• 内容测试：黄色标记动作或选择；它永远不能成为普通长文本的背景色。

Source: references/family-depth-matrix.md

黄色楔块是 Endfield 的状态语法核心。矩阵把"黄色沦为装饰背景"列为该族的典型失效模式——亮色必须是可操作语义（动作/选中），而不是排版手段。

Ex Astris（午夜舞台 × 档案导轨）

Ex Astris 族（exa）的内容所有者是"旅程、主体或档案记录"。

• minimal：保留壳层；引入衬线叙事对比、午夜中性色与一个水色焦点。
• moderate：添加纤细档案导轨，外加一个安静的环或遮罩滚动条。
• complex：协同编排旅程舞台、主体档案、编年表、公告、标签页与响应式轨道重构。使用两到四层，如星点、环、遮罩地平线与档案带。
• maximal：为旅程、角色、世界与公告模式分别赋予独特星群与由所选记录驱动的区块转场。
• 内容测试：虚构字形只能是装饰；每个旅程、时间戳、名称与动作必须保持可读。

Source: references/family-depth-matrix.md

这一族的特有风险是"装饰性字形侵蚀可读性"——矩阵明确要求虚构符号退居装饰层，真实数据（旅程、时间戳、名称、动作）始终占据可读性优先级。

POPUCOM（点阵深帽 × 圆角亮场）

POPUCOM 族的内容所有者是"组队就绪度或所选挑战"。

• minimal：保留壳层；引入友好的粗重字体、一个圆角主操作与一个有功能含义的队友/类别色。
• moderate：添加深色点阵帽、错位阴影与一组浮动形状。
• complex：协同编排组队就绪度、挑战预览、玩家角色、大厅操作、奖励/状态与响应式堆叠。使用两到四层趣味结构并配以简短的弹跳/滚动反馈。
• maximal：为大厅、挑战、装扮与奖励模式提供各自独立的趣味构图，其颜色响应真实选择。
• 内容测试：每个亮色都必须代表玩家、谜题、状态或动作；长文案放在安静表面上。

Source: references/family-depth-matrix.md

Corporate（半透明页头 × 单色媒体）

Corporate 族的内容所有者是"项目、角色或工作室陈述"。

• minimal：保留壳层；引入单色层级与一条酸性青柠激活规则。
• moderate：添加半透明深色页头、图像主导的分栏与安静的项目元数据。
• complex：协同编排项目序列、工作室陈述、角色类别、媒体、行动号召与响应式编辑回流。最多使用两个持久装饰层。
• maximal：构建定制的项目叙事与转场。不得为了凑层数而添加 HUD 仪表。
• 内容测试：作品、角色或陈述必须始终大于界面装饰。

Source: references/family-depth-matrix.md

Corporate 族是矩阵中最强调克制的族：即使在 complex 档，持久装饰层也被限制为最多两个；maximal 档的反向条款（不为凑层数加 HUD）直接对应跨族校验第 4 条"拒绝纯装饰式升级"。

深度轴：四档的转化目标

深度轴的定义来自 references/depth-levels.md，矩阵在此通用标准之上叠加族特异规则。

Source: references/depth-levels.md

深度选择规则

选择深度时的五条规则（references/depth-levels.md L23-L29）：

1. 尊重用户显式给出的档位或其中/英文别名。
2. 把"克制、轻量、几乎不改布局"映射到 minimal 或 moderate；"完整重构、游戏化、华丽但可用"映射到 complex；"展示级、沉浸式、每屏独立编排、极繁"映射到 maximal。
3. 未指定时，生产力/产品类 UI 默认 moderate，游戏向、活动页或展示类 UI 默认 complex；编辑前声明该假设。
4. 仅当深度会实质影响排期、资产制作、性能或架构时才提问。
5. 单个屏幕可以因任务密度在本地偏离一档；壳层与代表性主屏决定产品声明的档位。

SKILL.md 工作流第 4 步与此一致：

If the user specifies a depth, preserve it. Otherwise default to moderate for productivity/product UI and complex for game-adjacent or showcase UI; state the assumption.

Source: SKILL.md

实现契约：稳定键

代码中用稳定键同时声明族与深度，两条通道（HTML 数据属性 / React props）语义等价：

Source: references/depth-levels.md

Source: references/depth-levels.md

SKILL.md 对资源端的说明确认了这套契约的落点：

Starter and React assets expose data-ark-depth / depth alongside the existing family selector.

Source: SKILL.md

核心校验流：跨族校验

矩阵的最后一节给出了四条跨族校验，这是验收阶段的核心流程——通过"换族固定深度"与"换深度固定族"两组交换实验来验证契约是否真正成立：

四条校验原文（references/family-depth-matrix.md L65-L70）：

1. 固定深度切换风格族时，构图——而不只是颜色——必须改变。这条规则直接对应摘要表中每个族独立的壳层签名：如果换族后只是换了调色板而导轨、网格、读出器都一样，就违反了矩阵的第一条使用警告。
2. 固定族切换深度时，内容与可访问名称必须保持稳定，而覆盖广度、分层、动效与响应式重艺术指导发生变化。深度改变的是"语法渗透的广度"，不是"语义本身"——这就是为什么 endfield + minimal 与 endfield + maximal 使用同一种设计语言，前者只调整基础识别层，后者重构整套舞台、状态和动效系统。
3. 在 complex 档，必须包含完整导航、一个主操作、一个有意义的状态区域、共享控件、焦点、减弱动效与竖屏重构。
4. 在 maximal 档，要求状态驱动构图与性能回退。拒绝纯装饰式升级。

complex 档的校准基准

complex 档有一个匿名系统级重构参考基准（references/depth-levels.md L78-L87），用于防止 complex 与 maximal 的边界模糊：

• 它转化了顶栏、侧栏、主现场、编辑器、对话框、代码/数据表面、选择、焦点与状态遮罩。
• 主舞台组合了工程网格、方向扇区、校准圆环、边缘刻度、大号标识符与受控的信号黄锚点。
• 它使用独立的壳层/内容/遮罩规则，并处理响应式与减弱动效。
• 它低于 maximal 的原因：主要屏幕没有各自获得定制艺术指导、仪表主要是结构性的而非由实时产品状态驱动、动效克制而非跨区块编排。

关键告诫：不要把"装饰比参考基准更多"当作第 4 档的唯一判据。maximal 需要更深的状态集成、定制构图、响应式编排与性能回退。

族内深度递进对比

以 Endfield 为例展示深度递进如何叠加（各档规则均来自矩阵原文）：

这张图展示了矩阵最核心的结构性质：深度是覆盖广度的递进，内容测试是横向恒定的约束。四个深度档依次扩展壳层与舞台的覆盖范围，但族的内容测试（黄色语义）在所有档位上一致生效。

失效模式与边界情况

矩阵针对每个族都内置了对应的失效模式条款，汇总如下：

另有一个整体边界条款（README.md L47-L48）：默认只使用一个主风格族；确需混合时最多组合两个，由主风格控制壳层、排版和主要色彩，次风格只提供一种受控的仪表、强调色或插画行为。

扩展点

• 新增风格族：矩阵结构天然可扩展——新族需要提供三锚点（内容所有者、壳层签名、complex 档仪表）、四档深度规则与一条内容测试，并通过四条跨族校验（尤其是校验 1：构图必须与现有五族可区分）。
• 新增深度档：理论上可扩展，但现有四档已覆盖从"识别层"到"定制体验系统"的完整光谱；maximal 档的性能回退条款（向 complex 降级）实际上把降档作为扩展手段。
• 本地档位偏移：校验规则第 5 条允许单屏因任务密度在本地偏离一档，壳层与代表性主屏决定产品声明档位——这是矩阵内置的弹性机制。

相关链接

• references/family-depth-matrix.md — 矩阵源文件
• references/depth-levels.md — 四档深度通用标准、选择规则与校验记分卡
• references/recipes.md — 五个风格族的详细配方
• references/design-language.md — 共享视觉语法
• assets/readme/family-depth-map.zh-CN.svg — 族 × 深度可视化图（设计契约图示）
• SKILL.md — 技能工作流（第 4 步深度默认值、第 5 步矩阵读取时机）
• README.md — 项目总览与两轴模型说明