项目概览
Ark UI 是一套基于公开设计证据、采用 clean-room（净室）方法实现的界面设计与前端工作流技能（Codex Skill）。它以 风格族 × 应用深度 两条互相独立的正交选择轴，为网页与游戏邻接界面提供可复现的视觉语言与实施流程，同时严格规避对任何受保护素材的复制。
目的与范围
本页面是 ark-ui-skill 仓库的入口概览，覆盖以下内容：
- 项目的定位、clean-room 证据方法与法律边界
- 仓库整体结构：
SKILL.md工作流、references/规范、assets/可运行产物、scripts/工具链 - 核心概念：五种风格族与四档应用深度的正交双轴模型
- 从"锁定设计契约 → 实施 → 证据锁定迭代 → 验证"的完整工作流
ark-ui.tokens.json中的主题、深度、排版、几何与动效令牌体系- 安装方式与调用示例
以下主题由兄弟页面深入展开，本页仅做导向：
- 共享视觉语法与设计语言细节 → 见「设计语言」页（对应
references/design-language.md） - 四档深度的完整评分规范与验收卡 → 见「应用深度规范」页（对应
references/depth-levels.md） - 各风格族的具体配方 → 见「风格族配方」页（对应
references/recipes.md） - 风格族 × 深度的交叉规则 → 见「风格族深度矩阵」页（对应
references/family-depth-matrix.md） - 前端实现证据与代码审查 → 见「前端实现证据」页（对应
references/frontend-evidence.md） - 来源账本与法律合规 → 见「来源账本」页（对应
references/source-ledger.md与references/legal.md）
概述
Ark UI 解决的核心问题是：把"想要类似 Hypergryph（鹰角）系产品的界面气质"这种模糊提示，转化为可执行、可验收、可追溯的设计决策。其方法不是凭空想象"赛博朋克"风格，而是：
- 从公开页面归纳证据：颜色、字体、几何、动效、构图规律被记录在来源账本中；
- 用双轴模型锁定契约：先选一个风格族（
ark/endfield/exa/popucom/corporate），再独立选一档应用深度（minimal/moderate/complex/maximal）； - 以原创几何与令牌实现：优先使用 CSS/SVG 几何、渐变、蒙版与共享令牌，而不是复制游戏美术；
- 以证据锁定迭代与审计脚本验证：每次改动对照引用的证据模式，最终通过无障碍、响应式与反俗套审计。
关键理念是：风格族决定界面的视觉性格，应用深度决定这种性格覆盖到什么程度。例如 endfield + minimal 与 endfield + maximal 使用同一种设计语言，但前者只调整基础识别层，后者会重构整套舞台、状态和动效系统。
本项目不是相关游戏或厂商的官方项目，不包含受保护的标志、角色立绘、宣传图或生产环境代码；仓库内所有代码与样例均为原创或已做许可检查。
架构
仓库是一个自包含的 Codex 技能包：SKILL.md 是触发与工作流入口，references/ 提供规范文档，assets/ 提供可运行的起始代码、React 组件、令牌与展示样例，scripts/ 提供脚手架、审计、证据分析与截图工具。agents/openai.yaml 为代理配置。
分层设计意图说明：
- 入口层：
SKILL.md用 YAML frontmatter 声明技能名ark-ui与长描述（决定何时触发），正文则是完整工作流。代理只需读它即可获得所有指针。 - 规范层：把"怎么选"与"怎么判"从工作流中剥离，按需加载——例如实现深度 3 时才读取
depth-levels.md作为标尺，多风格对比时才读取family-depth-matrix.md，避免上下文膨胀。 - 资产层：提供可直接复用的落地物——无依赖原生起始模板、可移植 React 壳层、五族令牌 JSON、五个可检查的复杂档样例。
- 工具层：脚手架负责"从零开始"，审计脚本负责"完成后把关"，证据分析脚本负责"研究新官方页面"，截图脚本负责"渲染验证与宣传图再生成"。
核心概念：正交双轴模型
五种风格族
| 键名 | 风格定位 | 视觉特征 | 适合场景 |
|---|---|---|---|
ark | 工业信息系统 | 近黑与白为主体，青色信号，直线导轨、方形控件和斜向切口 | 战术面板、运营控制台、媒体门户、游戏菜单 |
endfield | 现场工程系统 | 米白与炭黑为主体，信号黄强调，分区舞台、长引导线、校准刻度和大型编号 | 建设、物流、数据工具、工业产品和高对比技术界面 |
exa | 宇宙档案系统 | 午夜蓝黑、白色与水青色，衬线标题、圆形仪表、轨道细线和星图节点 | 叙事档案、文化编辑、天文工具、角色资料和沉浸式产品页 |
popucom | 明快协作系统 | 蓝、黄、橙与暖白，圆角胶囊、粗描边、错位阴影和轻快反馈 | 协作工具、趣味引导、家庭向游戏、活动页和启动流程 |
corporate | 克制的工作室系统 | 黑白灰为主体，酸性黄绿色点缀，干净矩形、单色媒体和安静过渡 | 作品集、招聘页、工作室介绍和媒体展示 |
选择规则来自 SKILL.md：优先根据产品任务选择风格族，而不是只按喜欢的颜色选择。默认只使用一个主风格族；确需混合时最多组合两个，由主风格控制壳层、排版和主要色彩，次风格只提供一种受控的仪表、强调色或插画行为——"不要把所有产品平均成一个风格"。
四档应用深度
| 等级 | 键名 | 中文 | 舞台层数 | 组件覆盖 | 动效 | 响应式 |
|---|---|---|---|---|---|---|
| 1 | minimal | 极简 | 0-1 | critical（关键组件） | direct-only（仅直接反馈） | safe-stack（安全堆叠） |
| 2 | moderate | 中等 | 1-2 | shared-major（共享主组件） | reveal-and-direct（揭示+直接） | shell-adaptation（壳层适配） |
| 3 | complex | 复杂 | 2-4 | full-shared-system（完整共享系统） | coordinated-families（协调动效族） | full-recomposition（完全重构） |
| 4 | maximal | 极繁 | 4-6 | state-specific（状态特定） | section-choreography（逐段编排） | mode-specific-composition（按模式重导演） |
深度规范的核心约束：深度衡量的是实现覆盖与编排程度，不是内容密度。提高深度可以增加有意义的层、响应式重构与状态感知动效，但绝不允许假遥测、重复文案、额外颜色、更小的必要文字或更弱的可访问性。若用户未指定深度，默认规则是：生产力/产品界面用 moderate，游戏邻接或展示型界面用 complex，并在动手前说明假设。
核心工作流
SKILL.md 定义了从接到任务到交付的完整流程。下图展示实际控制流与关键决策点：
1. 入口检查
SKILL.md 的"Start here"步骤要求先检查目标项目的框架、视口、既有令牌与用户内容，再选择风格族——这一顺序保证了设计与项目现状（而非凭空偏好）对齐。
2. 锁定设计契约
在改代码之前，必须先声明一个紧凑契约：family、depth、证据模式（来自来源账本的确切公开模式），以及主屏幕必须让用户完成什么。契约将两条轴视为正交：endfield + minimal 与 endfield + maximal 共享身份但视觉饱和度完全不同。当用户要求代选时，展示四个编号级别并按产品类型推荐一个，而不是展示庞大的交叉矩阵。
3. 实施要点
- 从语义内容和任务层级出发，用视觉语法暴露状态、导航与优先级；
- 优先复用项目已有组件与令牌；否则复制
assets/starter-vanilla/或使用assets/react/ArkUI.jsx+assets/react/ark-ui.css； - 重命名起始模板的类名、ID、data 属性或 ARIA 目标时，必须在同一轮更新所有 JavaScript 选择器——"一个样式完好但 DOM 接线断裂的页面不算完成"；
- 以
assets/tokens/ark-ui.tokens.json为参考，然后将令牌重命名以匹配目标项目； - 实际落地时用根属性表示契约：
data-ark-theme="endfield"与data-ark-depth="complex"，并保持组件选择器语义化，使任一轴都能独立改变； - 优先使用 CSS/SVG 几何、渐变、规则线、蒙版与原创抽象，而不是复制的游戏美术；
- 保持一个主导强调色，次强调只作为状态或产品族信号；
- 方形或极小圆角几何、1px 规则线、裁切边缘、强负空间与有意不对称；
- 动效用于揭示层级（蒙版滑入、裁切擦除、克制脉冲、方向漂移），并尊重
prefers-reduced-motion； - 响应式布局有意构建：竖屏时把侧导轨转为紧凑的顶部/底部导航，而不是简单缩放桌面构图；
- 保留键盘可达、可见焦点、可读对比度、语义控件与有意义的替代文本。
4. 证据锁定迭代
当用户要求反复打磨，或说界面"丑、太暗、文字太多"时，使用六步循环（节选自 SKILL.md）：
- 在改代码前，先指明主风格族、应用深度与来源账本中的确切公开模式；若第二族有用，只借一种受约束的特征，不合并其完整调色板或装饰系统；
- 把持久文案归类为"决策 / 变化状态 / 解释"，保持决策数据可见、压缩重复状态、把可选解释放到显式的可访问折叠件后面——每个持久数据只有一个视觉所有者；
- 每轮只改一个共享令牌族、一个深度行为、一个代表性屏幕；当纯黑显得扁平，先在所选证据族内提升中性令牌或舞台光照，而不是发明渐变、辉光或新强调色；
- 保住回收的空间，交给主要内容或负空间，而不是用装饰性遥测填满；
- 在相同视口下捕获前后对比，若结果未明显接近引用证据、降低可读性、引入碰撞或让真实机制更难找到，则回滚或修改；
- 只有编译、交互、对比度与截图检查通过后才重复。
一个有代表性的细节约束（来自第 2 步）：在 36–42 px 的状态芯片里，倾向一行可读的 label + value，而不是两行过小的文字层级；过渡横幅只拥有其主题/状态与一个即时动作或结果，持久 HUD 数值留在 HUD——不得为了"显得技术"而制造协议名、系统代码、信道标签、负载表或装饰性遥测。
令牌体系与数据模型
assets/tokens/ark-ui.tokens.json 是五个风格族与四档深度的配置参考，采用 design tokens 社区格式。其顶层结构为 themes（按风格族分组）、depths（按深度分组）、typography、geometry、motion。
每个主题共享同一组键，保证任一轴可独立替换：
1{
2 "endfield": {
3 "ink": "#191919",
4 "paper": "#f2f2f0",
5 "signal": "#fffa00",
6 "state": "#00ffa2",
7 "accentAlt": "#00ffa2",
8 "muted": "#888888",
9 "panel": "rgba(25, 25, 25, 0.84)",
10 "shell": "pale-rail-charcoal-dock",
11 "stage": "calibration-route-matrix",
12 "radius": "2px"
13 }
14}Source: ark-ui.tokens.json
设计意图解析：
ink/paper是双色主体（深墨与纸色），signal是该族的主信号色，state表达状态，accentAlt是受控的备选强调，muted用于弱化信息；panel使用带透明度的半透明面板色（如rgba(25, 25, 25, 0.84)），使分层舞台可以叠加而不完全遮挡；shell与stage是命名构图原语而非颜色——例如 endfield 的pale-rail-charcoal-dock（米白导轨+炭黑坞）与calibration-route-matrix（校准路线矩阵），它们把"这一族如何组织壳层与舞台"编码为可引用的标识符；radius直接体现各族的几何性格：ark/corporate为0px（硬直角），endfield为2px（极小圆角），exa/popucom为999px（胶囊）。
共享排版、几何与动效令牌对所有族生效：
1{
2 "geometry": {
3 "rule": "1px",
4 "radiusTechnical": "2px",
5 "radiusFunctional": "4px",
6 "railDesktop": "72px",
7 "topbarDesktop": "72px"
8 },
9 "motion": {
10 "direct": "240ms",
11 "reveal": "650ms",
12 "attention": "1800ms",
13 "ease": "cubic-bezier(.22,.8,.2,1)"
14 }
15}Source: ark-ui.tokens.json
这些共享令牌解释了视觉语法中"1px 规则线、72px 桌面导轨/顶栏、240ms 直接反馈、650ms 揭示动效"等具体数值的来源。字体栈使用安全回退（"Noto Sans SC", "Source Han Sans SC", "PingFang SC", sans-serif 等），因为仓库明确不复现官方站点上授权不明的专有字体。
五族与四档深度可用下面的实体关系图概括（令牌结构即数据模型）：
使用示例
安装技能
git clone https://github.com/Brandon030722/ark-ui-skill.git "$CODEX_HOME/skills/ark-ui"Source: README.md
已经存在旧版本时，先备份自己的改动，再在该目录执行 git pull。安装后可直接在任务中写 $ark-ui 调用。
调用示例
使用 $ark-ui，以 endfield 风格、2 级中等深度重构这个后台。Source: README.md
使用 $ark-ui，把这个游戏启动器做成 ark + complex；保留现有信息架构。Source: README.md
使用 $ark-ui，做 exa + maximal 的展示页，但正文阅读区最多保持 moderate。Source: README.md
第三条示例展示了一个重要用法：深度可以在同一页面内按区域分级——展示页整体取 maximal，但正文阅读区最多 moderate，防止阅读可用性被展示级编排牺牲。
代码约定：静态页面
<html data-ark-theme="endfield" data-ark-depth="complex">Source: README.md
代码约定：React
<ArkShell theme="endfield" depth="complex" />Source: README.md
两种约定的共同意图：把契约放在根属性 / 组件属性上，而不是散落在各组件的类名里，从而让"族"与"深度"两条轴可以独立切换。起始模板与 React 资产都在既有族选择器之外额外暴露 data-ark-depth / depth。
技能触发的 YAML frontmatter
1---
2name: ark-ui
3description: "Design, implement, audit, or refactor web and game-adjacent interfaces using an evidence-based Hypergryph visual language with two independent choices: product family and application depth (1 minimal, 2 moderate, 3 complex, 4 maximal). ..."
4---Source: SKILL.md
frontmatter 的 description 决定技能何时被自动触发：覆盖 Hypergryph/Arknights/Endfield/Rhodes Island、工业科幻、双语技术界面等请求词，以及落地页、仪表盘、菜单、类 HUD 面板、设计系统、HTML/CSS/JS/React 组件与视觉 QA 等任务类型。
配置与工具链
脚本工具一览
| 脚本 | 用途 | 用法 |
|---|---|---|
scripts/scaffold-ark-ui.py | 把起始模板复制到新的或空的目标目录 | 实现前先脚手架化 |
scripts/audit-ark-ui.mjs | 启发式审计：标记缺失的无障碍/响应式问题与常见模仿俗套 | node .../audit-ark-ui.mjs <html-or-css-path> |
scripts/analyze-css-evidence.py | 从公开 CSS 提取颜色、字体、动效与几何证据 | python3 .../analyze-css-evidence.py <css-url-or-file> |
scripts/capture-showcases.mjs | 以精确桌面（1440×900）与可选移动（390×844）CDP 视口渲染五个样例，横向溢出时失败 | node .../capture-showcases.mjs --mobile |
scripts/capture-promos.mjs | 从原始展示截图再生成整套社交宣传图（八张横竖版 PNG） | node .../capture-promos.mjs |
验证命令
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"Source: README.md
完整验证清单（来自 SKILL.md 的 Validate 节）
- 运行目标项目的测试、lint 与构建；
- 运行自带启发式审计脚本；
- 在桌面与竖屏宽度渲染，检查裁切、文字碰撞、焦点顺序、激活态与减弱动效行为；
- 在浏览器中实际操作主要控件并检查运行时错误，不要仅从静态标记推断行为；
- 确认每个装饰元素都支撑分组、方向、状态或世界观构建之一；
- 确认来源：官方生产证据已被引用、第三方代码已做许可检查、输出代码为原创或正确署名；
- 对文字密度轮次，确认被删除的文案是冗余的，或仍可通过可见、可键盘访问的折叠控件获取；
- 确认每个仅图标控件是熟悉的次级操作或有可访问名称；购买、提交、破坏性与状态对比操作即便在紧凑布局中也保留可见动词与数值；
- 将代表性屏幕对照所选深度评判：壳层转换、舞台层数、组件覆盖、状态仪表、动效与响应式重构——不是原始元素计数；
- 确认最密的屏幕不超过所选深度一个局部等级，主屏幕不低于所选深度；记录有意的局部例外。
研究新的官方页面
当任务需要新页面或账本未覆盖的产品时，检查公开页面及其加载的 CSS/JS，用分析器处理 URL 或已下载的 CSS，然后把页面 URL、资产 URL、获取日期、观察到的框架、颜色、字体与可复用模式记录进 references/source-ledger.md，并区分直接观察与推断。
失败模式、边界与禁止事项
SKILL.md 的 Avoid 节定义了整个技能的边界红线：
- 不得将 Hypergryph、Arknights、Endfield、Rhodes Island、Monster Siren 或其他受保护的标志、角色美术、主视觉、UI 截图或 CDN 资产复制进交付物，除非用户拥有权利并显式提供；
- 不得再分发生产包或官方站点上观察到的专有/许可不明字体；
- 不得声称重构代码是 Hypergryph 源码；
- 不得在无信息角色的情况下添加随机六边形、终端噪声、扫描线、故障、霓虹渐变或密集 HUD 装饰；
- 不得仅因为这些颜色出现在不同产品中，就把青、信号黄、水青、品红、橙和柠黄组合进同一界面；
- 不得把主内容藏在启动屏、自动播放音频或仅悬停可达的控件后面；
- 不得把
maximal解释为随机 HUD 噪声、假系统代码、永久动效或每个组件都加装饰的许可； - 不得通过删除标签、状态、焦点提示、前置条件或必要解释来实现
minimal。
深度边界的量化验收规则（Validate 第 10 条）提供了"偏离契约"的可判定判据：最密屏幕超出所选深度不超过一个局部等级、主屏幕不低于所选深度。
运维与扩展点
- 再生成宣传素材：
assets/promo/保存可编辑源文件，assets/promo/output/是八张（4 横版 1600×900 + 4 竖版 1080×1350）成品 PNG；运行capture-promos.mjs可从真实样例截图重新生成。 - 扩展新风格族：路径是"研究新官方页面 →
analyze-css-evidence.py提取证据 → 记录进source-ledger.md→ 在ark-ui.tokens.json增加同构主题键 → 在recipes.md增加配方"，而不是凭印象调色。 - 适配目标项目令牌命名：规范明确要求把
ark-ui.tokens.json作为参考后重命名令牌以匹配目标项目，避免把技能内部命名强加给宿主项目。 - QA 入口约定：当代表性状态难以触达时，添加确定性、非持久的 QA 入口——"非持久"指测试装置显式抑制存档写入与存档删除，而不仅是创建内存对象；对于自动隐藏的过渡，QA 入口可在禁用自动隐藏的情况下重启正常动画，但不得改变生产时序。
相关链接
- SKILL.md — 核心工作流与触发规则
- README.md — 中文使用说明与文件清单
- assets/tokens/ark-ui.tokens.json — 主题/深度/排版/几何/动效令牌
- assets/react/ArkUI.jsx 与 assets/react/ark-ui.css — 可移植 React 壳层
- assets/showcases/ 等五个样例 — 各族复杂档可检查实现
- 兄弟页面：设计语言、应用深度规范、风格族配方、风格族深度矩阵、前端实现证据、来源账本（分别对应
references/下同名文档）