风格族与深度选择指南

本页解释 ark-ui-skill 中"双轴选择模型"的完整决策机制：如何从产品语义选定一个风格族（family），如何独立地选定应用深度（depth），以及两者如何组合成一份可执行的视觉契约（family × depth = visual contract）。

Purpose and Scope

本页覆盖：

• 双轴模型的概念定义：family 与 depth 是正交的两条轴，必须分开决策，不得合并展示为一张大的交叉矩阵。
• 五个风格族（ark / endfield / exa / popucom / corporate）的定位、内容所有者、外壳签名与 complex 级仪表。
• 四级深度（1 / minimal / 极简 到 4 / maximal / 极繁）各自的转化目标、组件覆盖、舞台分层与动效编排要求。
• 选择规则（含中文语义别名映射与默认值假设）、complex 级校准基准、六轴验证评分表、升级/降级策略。
• 实现契约：data-ark-theme 与 data-ark-depth 根属性如何让两条轴独立变化。

本页不覆盖以下内容（留给兄弟页面）：

• 各风格族的完整视觉语言与调色规则——见设计语言参考（references/design-language.md）。
• 具体族的配方与落地方案——见 references/recipes.md。
• 前端实现证据（CSS 变量拆分、组件选择器约定）——见 references/frontend-evidence.md。
• 溯源、资产与法务决策——见 references/source-ledger.md 与 references/legal.md。

Overview

ark-ui-skill 的核心方法论是：不要凭"赛博朋克"式的模糊提示词做界面，而是从已记录的视觉与实现证据出发，先锁定两个独立选择，再动手改代码。

1. 风格族（family） 决定调色板、字体、外壳语法（shell grammar）、几何与动效性格。它是产品的"身份"。
2. 应用深度（depth） 决定这套语法以多大的完整度转化产品：外壳覆盖范围、舞台（stage）分层、组件处理、状态仪表化、动效编排与响应式重排。它是实现的"覆盖广度与编排强度"。

关键在于：深度不是文案密度、卡片数量、颜色数量，也不是发明遥测数据的许可。 每一级都必须保留语义层级、真实数据、键盘可达性、可读对比度、减弱动效（reduced motion）支持与用户自己的产品身份。

SKILL.md 在 "Start here" 中将这两步明确为独立决策：

Source: SKILL.md

Architecture

双轴模型的架构关系如下：两个候选值集合分别汇入 family 轴与 depth 轴，二者相乘得到视觉契约，最终以根属性（data-ark-theme + data-ark-depth）与分离的变量体系落地。

设计意图说明：

• 正交分解：endfield + minimal 与 endfield + maximal 共享身份但不共享视觉饱和度。将两条轴拆开，意味着换深度不需要重写族变量，换族不需要重排深度行为。
• 变量所有权：family 变量只拥有墨色（ink）、纸面（paper）、信号色（signal）、字体与几何性格；depth 变量只拥有层透明度/数量、仪表化覆盖、动效可用性与可选装饰可见性。这种所有权划分是"任一轴可独立变化"的实现基础。
• 契约先行：SKILL.md 要求在改代码之前先声明一份紧凑契约——family、depth、证据模式（evidence pattern）、以及主屏必须让用户完成什么。

核心机制 1：选择规则与中文语义映射

references/depth-levels.md 的 "Selection rules" 定义了深度轴的确定性决策路径：

1. 若用户显式给出某个等级（或其中/英文别名），必须尊重该等级。
2. 中文语义映射：
   • "克制、轻量、几乎不改布局" → minimal 或 moderate
   • "完整重构、游戏化、华丽但可用" → complex
   • "展示级、沉浸式、每屏独立编排、极繁" → maximal
3. 未指定时的默认假设：生产力/产品类 UI 用 moderate；游戏相邻、活动页或展示类 UI 用 complex。必须在动手编辑前声明这个假设。
4. 只有当深度会实质影响排期、资产产出、性能或架构时才提问。
5. 单个屏幕可以因任务密度在局部上下浮一级；但外壳与代表性主屏决定产品声明的等级。

family 轴的选择规则同样来自产品语义而非视觉偏好——matrix 中的 "Primary content owner" 列就是选择依据：产品的主要内容是"当前作战/选中档案"（Ark）、"外勤任务/物流计划"（Endfield）、"旅程/主题/档案记录"（Ex Astris）、"队伍就绪度/挑战"（POPUCOM）还是"项目/角色/工作室声明"（Corporate）。

Source: family-depth-matrix.md

一个关键反模式来自 matrix 的警告："Do not make every family use the Endfield rail, grid, and readout."——族决定的是组合方式，不是把同一套轨道/网格/读出条刷成不同颜色。

核心机制 2：四级深度详解

Source: depth-levels.md

1 / minimal / 极简

• 保留既有信息架构与大部分组件结构。
• 应用族令牌、字体层级、圆角/分隔线语法、焦点态，以及一个强选择/动作提示。
• 每屏 0–1 套常驻装饰系统（如安静的分隔网格或一个裁切的大标识）。
• 动效仅限直接交互反馈；避免环境循环与全区块编排。
• 只重塑高价值表面：外壳、主操作、激活导航、输入/编写器、一个代表性面板。
• 结果应当"先读出产品，其次读出族"。

2 / moderate / 中等

• 在有用的地方重组外壳：轨道/顶栏、动作条、舞台/内容分栏或区块标题系统。
• 使用一到两个连贯的舞台层，例如"网格 + 方向性分隔线"、"图像水洗 + 元数据轨道"或"轨道 + 档案遮罩"。
• 覆盖共享控件与主要面板，低优先级工具面保持接近原生惯例。
• 一套 reveal 动效族 + 直接交互反馈；至多一个克制的注意力循环。
• 竖屏导航与主操作重组，但不必每个区块都做定制美术。
• 族已无可争议，但内容仍占据构图主体。

3 / complex / 复杂

• 把整个外壳转化为多个作业分区，带刻意的非对称与边缘仪表。
• 代表屏上使用 2–4 套协同的舞台系统：工程网格、方向扇区、校准装置、超大标识、有界纹理或图像遮罩。
• 塑形完整共享组件集：导航、编写器/输入、对话框、菜单、代码/数据面、状态、焦点、选中与滚动行为。
• 协调两套以上动效族（如 load/reveal 与 state/attention），并提供 reduced-motion 对等版本。
• 桌面与竖屏是"重新美术排布"而非仅缩放。
• 每个常驻仪表必须有真实的分组、方向、状态或世界观职责；中性面仍占主导。
• 体验读起来是"重构的系统"，不是"换肤"。

4 / maximal / 极繁

• 为主要区块/模式构建定制组合，同时保留一套全局外壳语法。
• 仅在舞台支持处使用 4–6 层连贯视觉层；按层级分布而非填满每个空隙。
• 仪表状态驱动：路由、模式、进度、选中、媒体或经验证的数据会改变构图。
• 区块过渡、遮罩、美术层与控件反馈作为一个动效系统协调；提供同等清晰的静态 reduced-motion 组合。
• 为桌面、竖屏、短宽与 reduced-motion 分别重排插画、字体、导航与动作位置。
• 显式预算性能、加载、对比度与注意力分散；低功耗或内容密集屏降级到 complex。
• 可以惊艳，但主操作与当前状态必须比装饰更快被找到。

核心机制 3：family × depth 矩阵的逐族深度要求

矩阵文件为每个族给出了每个深度层级的具体行为。以下以 Ark 与 Endfield 为例（完整内容见源文件）：

Source: family-depth-matrix.md

注意 moderate 行中的互斥约束（"either blueprint lines or desaturated media—not both"）——深度等级同时是预算约束，不只是加法清单。每个族还带一条 "Content test"（内容测试）作为否决条件：例如 POPUCOM 要求"每个亮色必须代表玩家、谜题、状态或动作；长文案放在安静表面上"；Corporate 要求"作品、角色或声明永远大于界面装饰件"。

核心流程：决策与落地顺序

流程要点（对应 SKILL.md 的 "Start here" 与 "Lock the design contract"）：

• 族与深度分开决策：当用户要求给出选项时，呈现四个编号深度等级并按产品类型推荐一个，"Keep family selection and depth selection as separate decisions instead of showing a large cross-product matrix."
• 契约先行：在改任何代码之前口头锁定 family、depth、证据模式与主屏任务。
• 阅读路径有条件分支：基础三份文档 + 所选族 recipes；只有跨族对比或族特定深度行为才读 matrix。

实现契约与代码示例

根属性用法

Source: depth-levels.md

Source: depth-levels.md

实现约束：

• 保持族变量与深度变量分离。族变量拥有 ink、paper、signal、type 与几何性格；深度变量拥有层透明度/数量、仪表化覆盖、动效可用性与可选装饰可见性。
• 改变深度不得改变语义内容或可访问名称。
• 优先使用 CSS 变量、根 data 属性与共享组件变体，而非为每个深度复制平行的整页实现。

深度变量分层（来自前端证据）

references/frontend-evidence.md 进一步给出深度如何只通过变量改变覆盖与编排而不动调色板的证据，例如：

Source: frontend-evidence.md

同一文件强调："Keep component selectors independent from literal family colors."（组件选择器不得耦合具体族的字面色值），并建议避免为每个深度复制整页，优先使用变量、有界可选装饰、共享组件变体与状态驱动组合。

配置选项参考

family 轴候选值

depth 轴候选值

阅读路径配置（SKILL.md "Start here"）

失败模式、边界与否决条件

跨族交叉检查（矩阵文件的三条否决规则）

1. 保持深度不变切换族：组合（而不仅是颜色）必须改变。
2. 保持族不变切换深度：内容与可访问名称必须稳定，只有覆盖、分层、动效与响应式重排变化。
3. complex 级最低门槛：必须包含完整导航、一个主操作、一个有意义的状态区、共享控件、焦点、减弱动效与竖屏重排。
4. maximal 级门槛：要求状态驱动组合与性能回退；拒绝纯装饰性升级。

深度误判的典型失败模式

complex 级校准基准

depth-levels.md 提供一个匿名化的系统级重构参考用于校准 level 3：它转化顶栏、侧栏、主舞台、编写器、对话框、代码/数据面、选中、焦点与状态遮罩；主舞台组合工程网格、方向扇区、校准圆、边缘刻度、大标识与克制的信号黄锚点；使用分离的 shell/content/overlay 规则并处理响应式与 reduced-motion。它低于 maximal 的原因被明确列出：主要屏幕没有各自获得定制美术方向、仪表主要是结构性的而非由实时产品状态驱动、动效克制而非跨区块编排。

性能与运营注意点

• 性能预算显式化（maximal）：性能、加载、对比度与注意力分散必须在方案中显式预算；低功耗或内容密集屏应降级到 complex。
• reduced-motion 对等：complex 需要两套以上动效族的 reduced-motion 对等版本；maximal 需要提供同等清晰的静态组合。
• 验证评分表是整体判断：六轴（外壳转化、舞台分层、组件覆盖、状态仪表、动效编排、响应式重组）不可机械平均，也不得为提分而加装饰。"如果额外深度降低了任务清晰度、真实状态可见性、可达性或超出产品性能预算，该等级即判定失败。"
• 迭代锁（SKILL.md "Iterate with an evidence lock"）：每轮只改"一个共享令牌族、一个深度行为、一个代表性屏幕"；纯黑显得扁平时应先在证据族内提升中性令牌或舞台光照，而不是发明渐变、发光或新强调色。

扩展点

• 新增风格族：向 matrix 的族表增加一行（Primary content owner / Shell signature / Complex-level instrument），并为 minimal→maximal 四级各写一条行为与一条 Content test；同时更新 SKILL.md 的族清单与 recipes。
• 新增深度等级：需同步更新 depth-levels.md 的等级表、每级详述、六轴评分表描述，以及 frontend-evidence.md 中对应的 [data-ark-depth="..."] 变量块。
• 局部密度浮动的产品化：选择规则第 5 条允许单屏局部上下浮动一级，是实现"同一产品内按任务密度差异化"的官方扩展点。
• QA 状态入口：SKILL.md 迭代章节要求为难以触达的代表性状态提供确定性、非持久化（显式抑制存写与存删）的 QA 入口，可在不改生产计时的前提下重启带自动隐藏的过渡动画用于截图验证。

相关链接

• SKILL.md — 入口工作流：检查项目 → 选族 → 选深度 → 锁契约 → 实现 → 证据锁迭代
• references/depth-levels.md — 深度轴完整评分细则、实现契约与升级/降级策略
• references/family-depth-matrix.md — 每族每深度的具体行为与跨族否决检查
• references/frontend-evidence.md — 根属性与深度变量的前端实现证据
• references/design-language.md — 族级视觉语言（详见兄弟页面）
• references/recipes.md — 每族落地配方（详见兄弟页面）