实现规范与代码约定

本页定义 Ark UI 技能在"实现"阶段的全部代码约定与工程规范：设计契约（风格族 × 应用深度）如何落到根属性与令牌层、壳层与舞台如何用 CSS Grid 搭建、动效与响应式遵循哪些规则、以及哪些内容被明确禁止复制。所有规范均来自仓库内 SKILL.md、README.md 与 references/frontend-evidence.md 的可验证条文。

Purpose and Scope

本页覆盖以下内容：

设计契约的代码化：data-ark-theme / data-ark-depth 根属性约定，以及 React 侧的 theme / depth 接口约定。
令牌层规范：语义化 CSS 自定义属性（--ark-ink、--ark-signal 等）的组织方式，以及家族轴与深度轴为何必须分离。
实现模式库：来自 references/frontend-evidence.md 的七个可复用实现模式（主题令牌、边框仪表化壳层、遮罩揭示、分区标题、CSS/SVG 纹理、渐进动效、响应式朝向）。
工程行为规范：SKILL.md 的 Implement 条目、证据锁迭代循环、Avoid 禁令与 Validate 验收清单。

以下主题刻意留给兄弟页面：

四档深度的完整评分细则与验收维度 → 见 3.x「应用深度分级」页（对应 references/depth-levels.md）。
共享视觉语法（构图、色彩、排版、几何性格）→ 见 references/design-language.md 相关页面。
五个风格族的具体配方 → 见 references/recipes.md 与 references/family-depth-matrix.md 相关页面。
来源与合规（clean-room 边界、许可证核查）→ 见 references/source-ledger.md / references/legal.md 相关页面。
审计脚本的技术实现 → 见脚本页（scripts/audit-ark-ui.mjs）。

Overview

Ark UI 是一套基于公开设计证据、采用 clean-room 方法实现的界面工作流（见 README.md）。它的实现规范建立在两条互相独立的选择轴之上：

风格族：ark、endfield、exa、popucom、corporate，决定界面的视觉性格。
应用深度：minimal、moderate、complex、maximal，决定这种性格覆盖到什么程度。

代码约定的核心目标是正交性：风格族控制色彩、字体、几何和动效性格；深度控制壳层改造、舞台层数、组件覆盖、状态仪表、动效编排和响应式重构（README.md）。因此 endfield + minimal 与 endfield + maximal 共享同一套识别语言，但视觉饱和度完全不同（SKILL.md）。

两条轴都被明确写入规范："Treat family and depth as orthogonal axes"（SKILL.md）。这条原则贯穿所有下游约定：组件选择器保持语义化、令牌按家族切换、深度以独立属性驱动覆盖行为。

关键约束：深度 ≠ 内容密度

规范反复强调："Depth measures implementation coverage and orchestration, not content density"（SKILL.md）。提高深度允许增加有意义的图层、响应式重构和状态感知动效，但绝不允许：

伪造遥测数据
重复文案
额外颜色
缩小必需文本
削弱无障碍性

同样，README.md 的代码约定段落明确写道："深度增加不等于增加假数据、随机 HUD、额外颜色或无意义动画"（README.md）。

Architecture

实现规范在代码层面的落点是一个三层结构：根属性契约层 → 令牌层 → 组件/壳层，并由脚本层做验证。下图为真实结构：

Loading diagram...

分层意图解释：

契约层是唯一允许"选择家族/深度"的地方。规范要求"Represent the contract with root attributes when practical … Keep component selectors semantic so either axis can change independently"（SKILL.md）。这样切换家族或深度时不需要改组件代码。
令牌层承担家族与深度的解耦：[data-ark-theme="…"] 块只写颜色/字体等家族令牌；[data-ark-depth="…"] 块只写覆盖行为变量（阴影、图层不透明度等）。
组件/壳层永远引用语义令牌，不写字面色值。references/frontend-evidence.md 的模式 1 明确要求 "Keep component selectors independent from literal family colors"。
验证脚本层是规范的执行器：审计脚本标记缺失的无障碍/响应式与常见模仿陈词滥调；截图脚本在真实 390×844 视口复验并在横向溢出时返回失败（README.md）。

契约表达规范

静态页面：根属性

静态页面必须在根元素上声明两条轴（README.md）：

html

<html data-ark-theme="endfield" data-ark-depth="complex">

React：组件接口

React 侧使用 theme 与 depth 两个 props 表达同一条契约（README.md）：

jsx

<ArkShell theme="endfield" depth="complex" />

捆绑资源说明中确认了这两个入口的一致性："Starter and React assets expose data-ark-depth / depth alongside the existing family selector"（SKILL.md）。也就是说原生起步件用 data-ark-depth，React 件用 depth prop，两者最终都落到同一套深度驱动的 CSS 变量上。

实现前置：锁定契约

规范要求在改代码之前先陈述一个紧凑契约（SKILL.md）：

Before changing code, state a compact contract: family, depth, evidence pattern, and what the primary screen must let the user do.

契约包含四要素：风格族、深度、证据模式（引用来源台账中的具体公开模式）、主屏幕必须让用户完成什么任务。这四要素一旦陈述，就成为后续所有实现决策的仲裁依据——证据锁迭代循环（见下文）第一步就是复述这条契约。

令牌层规范

家族令牌：语义化自定义属性

模式 1 给出的标准写法是在根属性上切换家族，令牌用语义化名称（references/frontend-evidence.md）：

css

[data-ark-theme="endfield"] {
  --ark-ink: #191919;
  --ark-paper: #f2f2f0;
  --ark-signal: #fffa00;
  --ark-state: #00ffa2;
}

四个令牌的语义分工：

令牌	语义	用途
`--ark-ink`	墨色（前景/结构）	文本、边框、直线、结构元素
`--ark-paper`	纸色（背景）	页面底色、面板底色
`--ark-signal`	信号强调色	该家族的主强调（如 endfield 的信号黄）
`--ark-state`	状态色	状态反馈（激活、成功、聚焦等）

assets/tokens/ark-ui.tokens.json 提供五个证据派生家族的完整令牌参考，且使用安全的回退字体栈（SKILL.md）。规范要求 "Use assets/tokens/ark-ui.tokens.json as a reference, then rename tokens to match the target project"（SKILL.md）——即令牌命名应对齐目标项目的既有命名体系，而不是强行注入 --ark-* 前缀。

深度令牌：独立根属性

深度变量放在另一个根属性上，只控制覆盖行为与编排强度，不碰家族调色板（references/frontend-evidence.md）：

css

[data-ark-depth="minimal"] {
  --ark-stage-layer-opacity: .18;
  --ark-instrument-shadow: none;
}

[data-ark-depth="complex"] {
  --ark-stage-layer-opacity: .68;
  --ark-instrument-shadow: .4rem .4rem 0 color-mix(in srgb, var(--ark-ink), transparent 86%);
}

注意两处细节：

--ark-instrument-shadow 使用 color-mix(in srgb, var(--ark-ink), transparent 86%)——阴影颜色派生自家族墨色令牌而不是独立色值。这保证换家族时阴影自动跟随，是"组件选择器不依赖字面色值"的具体体现。
minimal 档把舞台图层不透明度压到 .18 且关闭仪表阴影；complex 档提到 .68 并启用错位硬阴影。同一份组件代码通过变量完成两档表现切换。

深度实现的反模式警示

规范明确反对为每个深度复制整页："Avoid duplicating whole pages for each depth; prefer variables, optional bounded decoration, shared component variants, and state-driven composition"（references/frontend-evidence.md）。优先级排序为：变量 > 有边界的可选装饰 > 共享组件变体 > 状态驱动组合。

壳层与舞台布局规范

模式 2：边框仪表化壳层

规范用 CSS Grid 而不是大量视口特定的绝对定位值来搭建壳层（references/frontend-evidence.md）：

css

.ark-shell {
  min-block-size: 100svh;
  display: grid;
  grid-template-columns: 4.5rem minmax(0, 1fr);
  grid-template-rows: 4.5rem minmax(0, 1fr);
}
.ark-rail { grid-row: 1 / -1; }
.ark-topbar { grid-column: 2; }
.ark-stage { grid-column: 2; min-width: 0; }

设计意图解读：

min-block-size: 100svh 使用动态视口单位，避免移动端地址栏导致的 100vh 溢出。
侧栏固定 4.5rem 列 + 主区 minmax(0, 1fr)：minmax(0, 1fr) 中的 0 防止内容撑破网格列，配合 .ark-stage { min-width: 0 } 是标准的长内容防溢出组合。
.ark-rail { grid-row: 1 / -1 } 让侧栏贯穿整列高度，形成"边框仪表"的视觉框架。
绝对定位只允许出现在有边界的舞台内部用于艺术导演："Use absolute positioning only inside a bounded stage for art direction."

动效规范

模式 3：遮罩揭示

生产站点反复使用遮罩与裁剪路径。重建该行为时必须保持可访问内容仍在 DOM 中（references/frontend-evidence.md）：

css

.ark-reveal {
  clip-path: inset(0 100% 0 0);
  transform: translateX(-12px);
  transition: clip-path .65s cubic-bezier(.22,.8,.2,1), transform .65s;
}
.ark-reveal[data-visible="true"] {
  clip-path: inset(0);
  transform: none;
}

关键点：内容默认就在 DOM 里（clip-path 只是视觉裁剪，不像 display:none 会移出无障碍树），由 data-visible 属性驱动过渡，JS 只负责翻转这个布尔属性。缓动统一用 cubic-bezier(.22,.8,.2,1) 这类克制的减速曲线。

模式 6：渐进动效优先级

规范给出明确的实现技术优先级（references/frontend-evidence.md）：

IntersectionObserver 用于区块揭示（进入视口才触发）。
CSS transitions 用于直接交互（hover、focus、属性切换）。
requestAnimationFrame 仅用于 CSS 无法表达的运动。
暂停离屏媒体与循环动画。
prefers-reduced-motion 媒体查询禁用持续运动。

prefers-reduced-motion 是硬性要求，四档深度全部适用："四档深度都必须保持真实数据、清晰主任务、键盘可用、可见焦点、可读对比度、响应式布局和 prefers-reduced-motion"（README.md）。

动效的语义规范同样明确："Use motion to reveal hierarchy: masked slide, clipped wipe, restrained pulse, or directional drift. Honor prefers-reduced-motion"（SKILL.md）——动效只用于揭示层级，允许的形式是遮罩滑动、裁擦、克制脉冲、方向漂移四类。

语义结构规范

模式 4：分区标题与规则元数据

大型标题、编号、横线必须拆成独立元素，避免把文字烘焙进图片（references/frontend-evidence.md）：

html

<header class="ark-section-title">
  <p class="ark-kicker">FIELD OPERATIONS / 01</p>
  <h2>Signal Archive</h2>
  <span class="ark-rule" aria-hidden="true"></span>
</header>

三个结构角色：

元素	角色	备注
`ark-kicker`	小号大写英文微标签 + 大型编号	纯装饰性规则线需 `aria-hidden="true"`
`h2`	主标题	保持为真实文本，供读屏与搜索使用
`ark-rule`	1px 分隔规则线	无语义，必须标注 `aria-hidden`

微标签的双语规范："Pair Chinese or primary labels with short uppercase English micro-labels only when it clarifies hierarchy"（SKILL.md）——仅在能澄清层级时才配对，不强制双语。

模式 5：CSS/SVG 纹理

装饰纹理必须自造而非复制官方素材（references/frontend-evidence.md）：

css

.ark-grid {
  background-image:
    linear-gradient(rgb(255 255 255 / .08) 1px, transparent 1px),
    linear-gradient(90deg, rgb(255 255 255 / .08) 1px, transparent 1px);
  background-size: 4rem 4rem;
}

半网点或图表类艺术则用内联 SVG，并遵循三个属性约定：currentColor 取色（跟随上下文墨色）、低不透明度、pointer-events:none（不拦截交互）。

这与 SKILL.md 的几何规范一致："Prefer CSS/SVG geometry, gradients, rules, masks, and original abstractions over copied game art"，以及 "Use square or very small-radius geometry, 1px rules, cropped edges, strong negative space, and intentional asymmetry"（SKILL.md）。

响应式规范

模式 7：朝向感知断点

官方站点包含大量纵向特定规则而不仅是宽度断点，规范要求两者并用（references/frontend-evidence.md）：

css

@media (max-width: 760px), (orientation: portrait) {
  .ark-shell { grid-template-columns: 1fr; grid-template-rows: auto 1fr auto; }
  .ark-rail { position: static; grid-row: 3; flex-direction: row; }
}

这条规范同时给出了规范性的迁移方式：Converting side rails to compact top/bottom navigation on portrait screens; do not merely scale the desktop composition（SKILL.md）。窄屏不是把桌面构图整体缩小，而是把侧栏改造成紧凑的顶部/底部导航。上例中 .ark-rail 从纵向满高列变成 grid-row: 3 的横向行，正是这个迁移的落地写法。

另一个禁令："Avoid locking html overflow unless implementing a tested, keyboard-accessible section scroller"（references/frontend-evidence.md）——锁死页面滚动风险极高，除非实现了经过测试且键盘可用的区块滚动器。

生产环境建议

references/frontend-evidence.md 的 Production recommendations 段给出框架层面的落地建议（references/frontend-evidence.md）：

React/Next.js：视觉家族放 CSS Modules 或令牌层，不要把每个坐标内联到 JSX。
Vue/Svelte：沿用同样的语义化组件边界，无框架特定行为要求。
静态/活动页：以展示为主时优先无依赖 HTML/CSS/JS。
在项目支持范围内使用 svh、dvh、clamp()、容器查询与逻辑属性。
大型媒体懒加载；用 picture、AVIF/WebP、显式尺寸与合适的 object-position。
文本保持为文本。官方营销页有时用图片做标题艺术，生产应用不应重复这个无障碍取舍。
仅预加载首屏实际用到的展示字体；优先可许可的开放字体或系统回退。
全屏区块需要真实的路由与焦点管理策略。
在桌面与纵向断点添加视觉回归截图。

技术栈与证据边界

references/frontend-evidence.md 的 Observed stacks 表记录了公开站点直接观察到的技术指纹（置信度均为 high）：React 18.2 生产运行时（企业站）、Next.js App Router（Endfield v4、POPUCOM v2）、CSS Modules + 哈希类名、Swiper 运行时、Umi 生产包（Monster Siren Records）等。

证据边界的规范表述（references/frontend-evidence.md）：

They do not expose a licensed source repository. Treat bundle analysis as implementation evidence, not permission to redistribute the bundles.

The code in assets/ is an original clean-room implementation based on high-level observations. It is not Hypergryph source code.

同时禁止从营销站点推断公司内部游戏 UI 技术栈。

实现流程规范（SKILL.md Implement 条目）

SKILL.md 的 Implement 段是实现的完整检查清单（SKILL.md），逐条如下：

#	条目	意图
1	从语义内容与任务层级出发，用视觉语法暴露状态、导航与优先级	结构先行，装饰服从信息
2	复用项目既有组件与令牌；否则复制 `assets/starter-vanilla/` 或用 `assets/react/ArkUI.jsx` + `ark-ui.css`	不重复造轮子，尊重宿主项目
3	重命名起步件的类、ID、data 属性或 ARIA 目标时，必须在同一遍里更新所有 JS 选择器与引用	"A styled page with broken DOM wiring is not complete"
4	用 `ark-ui.tokens.json` 作参考，随后重命名令牌对齐目标项目	令牌命名权归宿主项目
5	尽量用根属性表达契约：`data-ark-theme` + `data-ark-depth`	两轴可独立切换
6	优先 CSS/SVG 几何、渐变、规则线、遮罩与原创抽象，而非复制游戏美术	clean-room 边界
7	保持一个主导强调色；次强调只作为状态或产品家族信号	"Keep one dominant accent"
8	中文或主标签配短大写英文微标签，仅当能澄清层级	克制双语
9	方形或极小圆角几何、1px 规则线、裁切边缘、强留白、有意不对称	几何性格
10	动效用于揭示层级：遮罩滑动、裁擦、克制脉冲、方向漂移；尊重 `prefers-reduced-motion`	动效语义化
11	刻意构建响应式：纵向屏把侧栏改为紧凑顶部/底部导航，不是缩放桌面构图	重构而非缩放
12	保留键盘可达、可见焦点、可读对比度、语义控件与有意义的 alt 文本	无障碍底线

其中第 3 条尤为关键——它是本套规范里少见的把"样式完成但 JS 接线断裂"明确判定为未完成的条文。

证据锁迭代循环

当用户要求反复打磨或抱怨界面"丑、太暗、文字太多"时，使用六步证据锁循环（SKILL.md）：

Loading diagram...

循环中几条最重要的子规范：

单一视觉归属原则：可比较的数值归候选卡片，焦点档案只拥有补充上下文；同一指标不得在两处重复出现。
中性令牌优先调色："When pure black feels flat, first lift neutral tokens or stage lighting within the chosen evidence family; do not invent gradients, glow, or a new accent"（SKILL.md）。模态遮罩先尝试下一个既有中性表面令牌配克制不透明度，而不是改面板或加新色。
图标按钮的底线：纯图标控件必须是熟悉的次要操作或有可访问名称；购买、提交、破坏性、状态比较类操作即使在紧凑布局也保留可见动词与数值（SKILL.md）。
确定性 QA 入口：难以触达的代表状态需要一个确定性、非持久的 QA 入口。非持久意味着测试装置显式禁止存档写入与存档删除，而不只是创建内存对象；自动隐藏过渡可通过该入口以禁用自动隐藏的方式重启正常动画，但不得改变生产时序（SKILL.md）。

禁止事项（Avoid）

SKILL.md 的 Avoid 段是实现的负向清单（SKILL.md）：

不得复制 Hypergryph、Arknights、Endfield、Rhodes Island、Monster Siren 等受保护的标志、角色美术、主视觉、UI 截图或 CDN 资源（除非用户有权利并明确提供）。
不得再分发生产包或官方站点观察到的专有/许可不明的字体。
不得声称重建代码是 Hypergryph 源码。
不得添加没有信息角色的随机六边形、终端噪声、扫描线、故障效果、霓虹渐变或密集 HUD 装饰。
不得仅因为青、信号黄、水青、品红、橙、柠檬绿出现在不同产品中就把它们混进一个界面。
不得把主内容藏在启动屏、自动播放音频或仅悬停可达的控件后面。
不得把 maximal 解读为随机 HUD 噪声、伪造系统码、永续运动或每个组件都加装饰的许可。
不得靠删除标签、状态、聚焦提示、前置条件或必要说明来实现 minimal。

references/frontend-evidence.md 的 What not to copy 段补充了不可复制清单（references/frontend-evidence.md）：哈希生产 CSS/JS 包、标志与主视觉与角色 PNG 与视频与二维码与年龄分级标识与专有图标表、许可不明的内嵌字体、私有 API 端点与鉴权逻辑与令牌与遥测、压缩后的类名与精确布局坐标。后者被明确归类为"implementation artifacts, not a design system"。

验证规范（Validate）

SKILL.md 的 Validate 段定义了实现完成的十条判定（SKILL.md）：

运行目标项目的测试、lint 与构建。
运行捆绑的启发式审计脚本：
bash
node "$CODEX_HOME/skills/ark-ui/scripts/audit-ark-ui.mjs" <html-or-css-path>
在桌面与纵向宽度渲染，检查裁剪、文字碰撞、焦点顺序、激活态与减动效行为。
在浏览器中实际操作主要控件并检查运行时错误——不得仅凭静态标记推断行为。
确认每个装饰元素要么支持分组、方向、状态，要么支持世界构建。
确认来源：官方生产证据被引用、第三方代码经过许可核查、输出代码为原创或正确归属。
文本密度优化时，确认被删文案是冗余的，或仍可通过可见的、键盘可达的 details 控件获取。
确认每个纯图标控件是熟悉的次要操作或具有可访问名称。
将代表屏对照 references/depth-levels.md 中所选深度评判——评的是壳层转换、舞台层数、组件覆盖、状态仪表、动效与响应式重构，不是原始元素数量。
确认最密屏不超过所选深度一个局部级别，主屏不低于该深度；记录有意的局部例外。

配套的截图复验命令与移动端行为（README.md）：

bash

node "$CODEX_HOME/skills/ark-ui/scripts/audit-ark-ui.mjs" <html-or-css-path>
node "$CODEX_HOME/skills/ark-ui/scripts/capture-showcases.mjs" --mobile
python3 "$CODEX_HOME/skills/.system/skill-creator/scripts/quick_validate.py" "$CODEX_HOME/skills/ark-ui"

截图脚本默认以 1440×900 重建五张 complex 档样例；--mobile 会以真实 390×844 设备视口复验，并在出现横向溢出时返回失败（fail-fast，把响应式回归变成构建失败信号）。

起步资产选择规范

实现时的资产选择顺序（SKILL.md）：

资产	用途
`assets/starter-vanilla/`	无依赖响应式演示与起点
`assets/react/`	可移植 React 壳层、面板、主题切换器与 CSS
`assets/tokens/ark-ui.tokens.json`	五个证据派生主题族的令牌参考（安全回退字体栈）
`assets/showcases/`	五个可检查的原创 complex 档样例，带四档深度控制
`assets/promo/`	可编辑宣传构图与八张横竖版 PNG
`scripts/scaffold-ark-ui.py`	把起步件复制到新的或空的目标位置

规范同时规定阅读顺序：实现或代码审查时必读 references/frontend-evidence.md（本页主要内容来源）；做多家族对比或家族特定的深度行为时加读 references/family-depth-matrix.md（SKILL.md）。

配置参考

根属性/接口的有效取值（来自 README.md 与 SKILL.md）：

契约轴	载体	取值	说明
风格族	`data-ark-theme` / `theme`	`ark`, `endfield`, `exa`, `popucom`, `corporate`	默认只用一个主族；确需混合最多两个，主族控制壳层/排版/主色，次族只提供一种受控的仪表、强调色或插画行为（README.md）
应用深度	`data-ark-depth` / `depth`	`minimal`, `moderate`, `complex`, `maximal`	未指定时的默认：生产力/产品界面 `moderate`，游戏邻接或展示型界面 `complex`，且动手前说明假设（README.md）

深度语义速览（SKILL.md）：

档位	键名	中文	实现覆盖
1	`minimal`	极简	令牌、字体、几何 + 一个强状态提示
2	`moderate`	中等	家族壳层 + 一个受控纹理/仪表层 + 克制揭示动效
3	`complex`	复杂	多区壳层、分层舞台、广组件覆盖、协调仪表
4	`maximal`	极繁	定制区块构图、状态驱动仪表、跨完整重导演响应式系统的协调动效

混合家族的受限借用规则在迭代循环中再次收紧："If a second family is useful, borrow one constrained trait only; do not merge its full palette or decoration system"（SKILL.md）。

失败模式与边界情况

已识别的失败模式

失败模式	规范条款	后果
样式完成但 JS 选择器未同步更新	Implement 第 3 条	判定为未完成（"A styled page with broken DOM wiring is not complete"）
靠删除标签/状态/聚焦提示达成 `minimal`	Avoid 最后一条	无障碍回归
用假遥测、伪造系统码回填回收空间	迭代循环第 4 条 / Avoid	违反"深度 ≠ 内容密度"契约
锁死 `html` overflow	响应式规范	除非实现经过测试且键盘可用的区块滚动器
同一指标在候选卡与档案两处重复	单一视觉归属原则	冗余信息架构
纯黑显得平淡时发明渐变/辉光/新强调色	迭代循环第 3 条	应先抬升中性令牌或舞台光照
把压缩类名与精确坐标当作设计系统	What not to copy	复制了实现伪影而非设计语言

状态触达难题的处理

难以触达的代表状态（如模态、确认框、自动隐藏过渡）不允许靠猜测截图优化。规范要求确定性 QA 入口 + 非持久约束（显式禁止存档写入与删除）+ 不改变生产时序（SKILL.md）。坐标自动化不可靠时，通过该 QA 入口暴露精确的模态或确认状态，而不是放弃交互证据。

并发与一致性考量

本规范主要面向前端实现，未涉及服务端并发。与并发最相关的条款是：坐标自动化不可靠时优先暴露确定性状态入口（避免对时间敏感的竞态），以及自动隐藏过渡的 QA 入口"必须以禁用自动隐藏的方式重启正常动画、不得改变生产时序"——这条把 QA 路径与生产时序解耦，防止测试钩子污染真实行为。

扩展点

规范的扩展方式集中在三处：

令牌层扩展：新增家族时按 [data-ark-theme="…"] 块提供同套语义令牌（--ark-ink / --ark-paper / --ark-signal / --ark-state），组件层零改动。
深度层扩展：新增深度档位时在 [data-ark-depth="…"] 块定义覆盖变量，遵循"变量 > 有界装饰 > 组件变体 > 状态组合"的优先级。
证据扩展：研究新的官方页面时运行 scripts/analyze-css-evidence.py，把页面 URL、资产 URL、获取日期、观察到的框架、颜色、字体与可复用模式记入 references/source-ledger.md，并区分直接观察与推断（SKILL.md）。

深度分级完整规范（references/depth-levels.md）— 四档评分细则、第 3 档参考标尺与验收维度，见兄弟页「应用深度分级」
共享视觉语法（references/design-language.md）— 构图、色彩、排版、几何的共享语法
风格族配方（references/recipes.md）与家族×深度矩阵（references/family-depth-matrix.md）
来源与合规（references/source-ledger.md / references/legal.md）— clean-room 边界与许可证核查
SKILL.md — 核心工作流与触发规则
README.md — 安装、调用示例与验证命令
references/frontend-evidence.md — 七个可复用实现模式的原始出处