共享视觉语法

共享视觉语法（Shared Visual Grammar）是 Ark UI 技能中所有风格族共用的底层设计规则集：它定义了「舞台 + 仪表化」「编辑性层级」「单一信号色」等六条构图原则，以及排印、色彩语义角色、几何纹理、动效节奏与组件级语法，由 references/design-language.md 规范文档承载，并通过 assets/react/ark-ui.css 的 CSS 自定义属性与 assets/react/ArkUI.jsx 的组件层落地。

目的与范围（Purpose and Scope）

本页是 Ark UI 设计语言参考的第一篇，覆盖跨风格族共享的那部分语法——即无论选择 ark、endfield、exa、popucom 还是 corporate，都必须遵守的构图、排印、色彩、几何、动效与无障碍规则，以及这些规则在代码中的具体实现（token 层与组件层）。

本页有意不覆盖以下主题，它们属于兄弟页面：

应用深度四档规范（minimal / moderate / complex / maximal 的完整标尺与验收维度）：规范位于 references/depth-levels.md。本页只解释 data-ark-depth 属性如何作为 token 开关存在。
五个风格族的配方差异（每个族专属的品牌、控件形制、氛围）：规范位于 references/recipes.md。本页只说明语义色角色表中的各族取值。

换言之：本页回答「所有 Ark UI 输出共享什么」；族配方回答「每个族如何变形」；深度规范回答「语法覆盖到什么程度」。

概述（Overview）

README.md 将仓库的关键参考文件索引为三层：references/depth-levels.md（完整四档规范）、references/design-language.md（共享视觉语法）、references/recipes.md（五种风格族配方）。共享视觉语法是中间那一层——它是把「鹰角系产品族相似感」抽象为可执行规则的核心资产。

规范文档开宗明义地指出设计意图（WHY）：

The recurring Hypergryph family resemblance is not a single palette. It is a way of composing information and illustration.

也就是说，风格族之间的「家族相似性」不来自某个具体调色板，而来自组织信息与插画的方式。这条判断决定了整个语法的形态：它几乎不锁定具体 hex 值（色彩一节明确要求「Use semantic roles rather than copying every sampled hex」），而是锁定关系——大面积与小字号的共存关系、中性面与信号色的配比关系、舞台与仪表的从属关系。

SKILL.md 对技能使用者的指令进一步说明了这套语法的消费方式：「Start from semantic content and task hierarchy. Use the visual grammar to expose state, navigation, and priority.」——即先有语义内容与任务层级，再用视觉语法去暴露状态、导航与优先级，而不是先画装饰。

架构（Architecture）

共享视觉语法在仓库中的实现分为三层：规范层（人读的规则）、token 层（CSS 自定义属性 + 属性选择器）、组件层（React 组件封装语义结构）。

Loading diagram...

各层职责与设计意图：

规范层（references/design-language.md）：唯一的「真理来源」。它以规则 + 验收问题的形式描述语法，不绑定任何实现技术。这保证同一套语法既能落到 CSS/React，也能落到纯 HTML 启动模板（assets/starter-vanilla/），还能指导从零生成的新页面。
Token 层（assets/react/ark-ui.css）：把规范中的数值规则转译为 CSS 自定义属性。关键设计是正交双轴：data-ark-theme（风格族）与 data-ark-depth（应用深度）是两个独立的属性开关，任意组合有效——这正是 README.md 所说「风格族决定视觉性格，应用深度决定覆盖程度」的机制化表达。
组件层（assets/react/ArkUI.jsx）：只负责语义 HTML 结构与无障碍属性（aria-current、aria-pressed、aria-expanded、role="group"），几乎不包含视觉逻辑。视觉全部由 token 层的类选择器驱动，保证「换族 = 换属性值」而不是「换组件」。

该页面之外的两个消费面：assets/starter-vanilla/index.html 使用 ark-* 类名体系（如 ark-lede、ark-title-solid、ark-title-outline）实现同一语法的无构建版本；assets/showcases/ 提供 ark、corporate、endfield、exa、popucom 五个族的完整落地示例。

六条共享语法原则

references/design-language.md 的 Shared grammar 一节给出六条原则，这是整个语法的总纲：

#	原则（原文）	机制化解读
1	Stage plus instrumentation（舞台 + 仪表化）	让全出血图片、抽象场景或大型排印区充当舞台；把导航、状态、动作、元数据停靠在边缘，像仪表一样「测量」舞台。对应组件层的顶栏 + 边栏 + 状态条结构。
2	Editorial hierarchy（编辑性层级）	一个超大展示语句与微标签、索引、时间戳、双语说明共存；限制「中间尺寸的填充文字」。对应排印规则中的极端字号策略。
3	System fiction（系统虚构）	导航与元数据要像虚构世界中的操作系统，但必须映射到真实产品任务。这是 `arkThemeProfiles` 中 `OPERATION / 07`、`ROUTE VERIFIED` 等虚构文案的来源。
4	Asymmetric balance（不对称平衡）	强烈的左/右或上/下重量，由细线、负空间与次级轨道补偿。对应桌面构图中的 60/40、70/30 主内容分栏。
5	Controlled accent（受控强调）	绝大多数表面保持中性，一种信号色承担选中、进度与主动作。对应色彩一节的语义角色模型。
6	Layered flatness（分层扁平）	深度来自遮罩、裁切、半透明黑、细线、混合模式与文字叠压——而非带光泽的卡片。对应几何纹理一节的负半径默认值。

六条原则的设计意图是可检验性：规范末尾的 Quality bar（验收七问）逐条回扣这些原则，例如「Is the composition asymmetric yet balanced?」直接对应原则 4，「Are the signal color and display typography restrained enough to remain powerful?」对应原则 5。

排印语法

规范观察到的生产字体族包括 Source Han Sans、Source Han Serif、Bender、Oswald、Novecento Sans Wide、Gilroy、Space Grotesk、Trajan、Sumerhan 等，但明确指出其中若干存在专有或再分发条款不清的问题，因此规定「Use safe substitutes unless the project already licenses the observed face」。token 层将其落为五个安全字体栈：

css

--ark-display:"Arial Narrow","Roboto Condensed","DIN Condensed",sans-serif;
--ark-ui:"Space Grotesk","IBM Plex Sans",system-ui,sans-serif;

Source: ark-ui.css

规范层完整的角色—字体栈对照表（CJK UI、Condensed display、Technical Latin、Archival serif、Monospace data）见 references/design-language.md 的 Typography 一节；值得注意的一个族级覆盖是 Ex Astris 会在 token 层把展示字体换成衬线：

css

.arkR-shell[data-ark-theme="exa"]{--ark-ink:#080914;--ark-paper:#f3f2ef;--ark-signal:#46f6e6;--ark-state:#925dff;--ark-display:"Noto Serif SC","Source Han Serif SC",serif}

Source: ark-ui.css

数值规则（规范原文）：展示标题紧排 line-height: .82–.95、letter-spacing: -.02em 到 -.08em；微标签开排 letter-spacing: .08em–.18em；索引、计时器、坐标使用表格数字（tabular numerals）；中文正文保持正常字距与舒适行高。组件层的 arkR-sectionTitle h2 是这些数值的直接实现：

css

.arkR-sectionTitle h2{margin:0;font:900 clamp(3rem,7vw,7rem)/.84 var(--ark-display);letter-spacing:-.065em;text-transform:uppercase}

Source: ark-ui.css

注意 clamp(3rem,7vw,7rem) 与 /.84 的组合：clamp 保证极端字号在窄视口收缩但不失控，行高 0.84 落在规范区间 .82–.95 内偏紧的一端，与 .arkR-sectionTitle p 的 letter-spacing:.12em 微标签形成「编辑性层级」的极端对比。

色彩语法：语义角色而非采样值

色彩一节的核心约束是「Use semantic roles rather than copying every sampled hex」——四个角色名固定，各族只填值：

角色	含义	使用约束
Ink	主墨色（前景/深表面）	深色舞台、主动作底色
Paper	纸色（中性表面）	占据 75% 以上的构图面积
Signal	信号色	仅用于激活态、进度、选中导航与一个主动作
State（可选）	次级状态色	如在线指示灯 `arkR-online i`

token 层用 CSS 自定义属性实现这四个角色，默认值即 Endfield 族：

css

.arkR-shell {
  --ark-ink:#191919; --ark-paper:#f2f2f0; --ark-signal:#fffa00; --ark-state:#00ffa2;

Source: ark-ui.css

规范层给出的五族取值对照：Ark（#080a0b / #f4f6f6 / #18d1ff，状态 #c8eb21）、Endfield（#191919 / #f2f2f0 / #fffa00，状态 #00ffa2）、Ex Astris（#080914 / #f3f2ef / #46f6e6，状态 #925dff）、POPUCOM（#141414 / #fffdf4 / #ffcc1a，状态 #3994ff）、Corporate（#050505 / #f3f3f3 / #f3ff00，无状态色）。

其余色彩硬性规则：

中性表面占构图 75% 以上。
信号色不得作为浅底上的长正文文字色。
图像舞台上的浮层优先使用透明黑（.45–.88），而非玻璃质感白卡——这是「分层扁平」原则在色彩上的体现。
即便参考站点把文字烘焙进图片，真实文本仍须通过 WCAG 对比度检验。

几何、纹理与动效语法

几何的默认答案是「零」：Default radius: 0; allowed functional radius: 2–4px，只有 POPUCOM 例外可用药丸与大圆角控件。token 层把它做成族级变量，且 Ex Astris 明显越过了功能圆角的范围（--ark-family-radius:2rem），对应其「环状控制」的家族性格：

css

.arkR-shell[data-ark-theme="ark"]{--ark-family-radius:0;--ark-family-rule:rgb(24 209 255/.22)}
.arkR-shell[data-ark-theme="exa"]{--ark-family-radius:2rem;--ark-family-rule:rgb(0 251 236/.22)}
.arkR-shell[data-ark-theme="popucom"]{--ark-family-radius:1.35rem;--ark-family-rule:rgb(58 93 173/.28)}

Source: ark-ui.css

方向性线索使用 45° 切角、窄斜线、角括号与裁切楔形；clip-path 用于揭示与剪影而非把每个容器都做不规则。纹理须为原创 CSS/SVG 生成的半调、点阵、纸纹或图解线（低透明度）。混合模式仅在文字保持可读且存在回退时使用。图标优先自绘线性图标或统一开源图标集，线宽 1.5–2px。

动效按时长分三档，这是本语法最「参数化」的部分：

时长档	用途
180–350ms	直接交互反馈
500–900ms	区块揭示
1.6–2.4s	克制的注意力循环

位移约束：UI 反馈移动 4–16px，更大位移仅保留给整区块转场；steps() 仅用于类精灵动画或数据跑马灯；禁止对所有状态变化只做透明度渐隐（「Never rely on opacity-only fading for every state change」）——这与分层扁平原则一致，鼓励方向或裁切。无障碍落点是 token 层的全局短路：

css

@media(prefers-reduced-motion:reduce){.arkR-shell *, .arkR-shell *:before,.arkR-shell *:after{animation-duration:.001ms!important;animation-iteration-count:1!important;transition-duration:.001ms!important}}

Source: ark-ui.css

组件语法

规范层的 Components 一节定义六类构件的行为约定，组件层逐一对应：

规范约定	组件层实现
Rail navigation：固定边栏、图标 + 紧凑标签 + 信号条 + 可选索引；激活态不得只靠颜色区分	`ArkShell` 渲染 `.arkR-rail`，激活项同时有 `is-active` 类（ink 底 + 白字 + 左侧信号条）与 `aria-current="page"`
Section title：大紧排标题 + `NN / NN` + 双语小副题 + 延伸入负空间的细线；装饰归伪元素/SVG	`ArkSectionTitle` 输出 `<p>kicker / index</p><h2>…</h2><span aria-hidden>` 三段结构
Technical panel：单强边、头部代码、正文、状态行；避免四边圆角卡片外壳	`ArkPanel` 输出 `.arkR-code` → `h3` → `.arkR-panelBody`，`data-tone="ink"` 反转表面
Action button：Ark/Endfield 方形 + 左信号条；Ex Astris 胶囊；POPUCOM 药丸 + 粗描边 + 位移阴影	`ArkButton` 统一输出 `.arkR-button`，形制差异全部由族选择器施加
Media grid：封面主导、统一裁切比、克制悬停浮层	由 showcase 页实现（`assets/showcases/`）
Status strip：沿边缘放置版本/连接态/坐标/进度，使用真实信息，不得编造无意义遥测	`ArkShell` 顶栏的 `arkR-online` 状态行

「Status strip 不得编造数据」这一条与 System fiction 原则构成一对张力：虚构的是世界观文案（OPERATION / 07），不虚构的是数据本身。arkThemeProfiles 是这种张力的直接体现：

jsx

export const arkThemeProfiles = {
  ark: { brand: 'TERRA INDEX', code: 'OPERATION / 07', status: 'SHIFT ACTIVE' },
  endfield: { brand: 'FIELD RELAY', code: 'LOGISTICS / 04', status: 'ROUTE VERIFIED' },
  exa: { brand: 'WIND ATLAS', code: 'JOURNEY / 03', status: 'RECORD ALIGNED' },
  popucom: { brand: 'PRISM PLAZA', code: 'PARTY ROOM / 204', status: '2 OF 4 READY' },
  corporate: { brand: 'STUDIO INDEX', code: 'PROJECTS / 05', status: 'PORTFOLIO OPEN' },
};

Source: ArkUI.jsx

核心流程：一个组合请求如何在系统中落地

下图展示从选择风格族/深度到最终渲染的完整控制流。关键点在于：切换族或深度不触碰任何组件代码，只改写两个 data 属性，随后所有视觉差异由 CSS 属性选择器级联完成。

Loading diagram...

深度轴的 token 定义（四档）：

css

.arkR-shell[data-ark-depth="minimal"]{--ark-depth-rule:12%;--ark-depth-panel-min:15rem;--ark-depth-shadow:0 0 0 transparent}
.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%)}
.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%)}
.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: ark-ui.css

设计意图说明：--ark-depth-rule 控制边线「墨色浓度」百分比——数值越低，细线越接近透明，即深度规范中「语言覆盖程度」的直接量纲；阴影从无到 9px 9px 0 且在 maximal 档掺入信号色，正好复现「分层扁平」原则里「深度来自补偿元素而非光泽卡片」的硬阴影语言。maximal 档还有一条装饰性增强：

css

.arkR-shell[data-ark-depth="maximal"] .arkR-topbar{background-image:repeating-linear-gradient(90deg,transparent 0 31px,rgb(255 255 255/.07) 31px 32px)}

Source: ark-ui.css

使用示例

示例一：构建带默认语法的页面外壳

ArkShell 是语法的主要入口。默认 theme = 'endfield'、depth = 'complex'，未传入 brand/code/status 时回退到 arkThemeProfiles 的虚构文案：

jsx

export function ArkShell({
  brand,
  code,
  status,
  theme = 'endfield',
  depth = 'complex',
  nav = [],
  activeId,
  onNavigate,
  children,
}) {
  const [menuOpen, setMenuOpen] = useState(false);
  const profile = arkThemeProfiles[theme] || arkThemeProfiles.endfield;

  useEffect(() => setMenuOpen(false), [activeId]);

  return (
    <div className="arkR-shell" data-ark-theme={theme} data-ark-depth={depth}>

Source: ArkUI.jsx

注意 arkThemeProfiles[theme] || arkThemeProfiles.endfield：无效族名静默回退到 Endfield，而不是抛错——这是技能面向生成式使用场景（LLM 产出任意属性值）时的容错选择。

示例二：激活态不得只靠颜色的实现

边栏导航项同时使用类名切换、左侧信号条、白字与 aria-current 四重手段表达激活态，满足规范「Active state must work without color alone」：

jsx

<button
  key={item.id}
  type="button"
  className={item.id === activeId ? 'is-active' : undefined}
  aria-current={item.id === activeId ? 'page' : undefined}
  onClick={() => onNavigate?.(item.id)}
>
  <span>{String(index + 1).padStart(2, '0')}</span>{item.label}
</button>

Source: ArkUI.jsx

String(index + 1).padStart(2, '0') 生成 01、02 形式的索引，配合边栏的 writing-mode:vertical-rl 竖排呈现，直接兑现 Rail navigation 中「optional index」与「compact label」的约定。

示例三：编辑性层级的语义结构

ArkSectionTitle 用三段语义结构实现「大标题 + 编号 + 延伸细线」，装饰性的细线放在 aria-hidden 的空 <span> 上：

jsx

export function ArkSectionTitle({ index = '01', kicker, children }) {
  return (
    <header className="arkR-sectionTitle">
      <p>{kicker} / {index}</p>
      <h2>{children}</h2>
      <span aria-hidden="true" />
    </header>
  );
}

Source: ArkUI.jsx

这体现了规范「Keep title content semantic HTML; decoration belongs in pseudo-elements/SVG」的分工：屏幕阅读器读到的是 kicker / 01 与标题文本，视觉细线由 CSS 的 .arkR-sectionTitle>span{height:1px;background:var(--ark-ink)} 绘制。

示例四：纯 HTML 路径（无构建依赖）

SKILL.md 给出的另一实现路径是复制 assets/starter-vanilla/。其标题区展示了同一语法的类名体系（ark-title-solid / ark-title-outline 双段式展示标题、ark-lede 导语）：

html

<h1><span class="ark-title-solid" data-copy="title">FRONTIER</span><br /><span class="ark-title-outline" data-copy="titleAccent">/ SIGNAL</span></h1>
<p class="ark-lede" data-copy="lede">A fictional operations interface built from an evidence-based visual grammar: edge instrumentation, one signal color, bilingual-scale hierarchy, and original technical geometry.</p>

Source: index.html

这一段自我描述恰好概括了本页主题：edge instrumentation（原则 1）、one signal color（原则 5）、bilingual-scale hierarchy（原则 2）、original technical geometry（原创性约束）。

配置选项（Token 属性参考）

ArkShell 通过两个 data 属性驱动整棵视觉树，二者正交、可任意组合：

属性 / 选项	类型	默认值	取值	说明
`data-ark-theme`	属性（经由 `ArkShell` 的 `theme` prop）	`'endfield'`	`ark` / `endfield` / `exa` / `popucom` / `corporate`	风格族：覆写 `--ark-ink/paper/signal/state`、`--ark-display`、`--ark-family-radius`、`--ark-family-rule` 及族专属选择器
`data-ark-depth`	属性（经由 `depth` prop）	`'complex'`	`minimal` / `moderate` / `complex` / `maximal`	应用深度：覆写 `--ark-depth-rule`（12%/18%/24%/34%）、`--ark-depth-panel-min`（15–26rem）、`--ark-depth-shadow`

Token 层公开的自定义属性汇总：

Token	类型	默认值（endfield + complex）	用途
`--ark-ink`	color	`#191919`	主墨色 / 深表面
`--ark-paper`	color	`#f2f2f0`	中性纸面
`--ark-signal`	color	`#fffa00`	唯一信号色
`--ark-state`	color	`#00ffa2`	次级状态色（在线指示等）
`--ark-display`	font stack	`"Arial Narrow","Roboto Condensed","DIN Condensed",sans-serif`	展示标题字体（exa 族覆写为衬线）
`--ark-ui`	font stack	`"Space Grotesk","IBM Plex Sans",system-ui,sans-serif`	界面与正文
`--ark-depth-rule`	百分比	`24%`	细线墨色浓度（深度量纲）
`--ark-depth-panel-min`	length	`22rem`	技术面板最小高度
`--ark-depth-shadow`	shadow	`5px 5px 0`（含 ink 透明 86%）	面板硬阴影
`--ark-family-radius`	length	`2px`（endfield）	族级圆角（exa `2rem`、popucom `1.35rem`、其余 `0`）
`--ark-family-rule`	color	`rgb(25 25 25/.24)`	族级细线色调

API 参考

`ArkShell({ brand, code, status, theme, depth, nav, activeId, onNavigate, children })`

语法的外壳组件，渲染顶栏 + 边栏 + 主区。

参数：

brand (string, 可选)：品牌名，缺省取 arkThemeProfiles[theme].brand
code (string, 可选)：头部代码（如 OPERATION / 07），缺省取 profile
status (string, 可选)：状态条文案，缺省取 profile
theme (string, 默认 'endfield')：写入 data-ark-theme
depth (string, 默认 'complex')：写入 data-ark-depth
nav (Array of { id, label }, 默认 [])：边栏导航项
activeId (string, 可选)：当前激活项 id；变化时自动关闭移动端菜单（useEffect）
onNavigate (function, 可选)：onNavigate?.(item.id) 点击回调
children (ReactNode)：主区内容

返回： JSX 元素。抛出： 无——未知 theme 回退到 endfield，不抛错。

`ArkSectionTitle({ index, kicker, children })`

参数： index (string, 默认 '01')；kicker (string)；children (ReactNode, 标题文本)。

`ArkPanel({ code, title, tone, action, children })`

参数： code (string)；title (string)；tone ('paper' | 'ink', 默认 'paper')——'ink' 反转为深色表面；action (ReactNode, 可选, 渲染于面板底部)；children (ReactNode, 正文)。

`ArkButton({ primary, className, ...props })`

参数： primary (boolean, 默认 false)——附加 is-primary；其余 props 透传给原生 <button>。

`ArkThemePicker({ value, onChange })` / `ArkDepthPicker({ value, onChange })`

role="group" 按钮组，选中项带 aria-pressed="true"。分别枚举 arkThemes（五族）与 arkDepths（{ value, level, label } 四档，label 形如 3 / Complex）。

导出的常量

arkThemes: ['ark', 'endfield', 'exa', 'popucom', 'corporate']
arkThemeProfiles: 五族的 { brand, code, status } 虚构文案档案
arkDepths: 四档 { value, level, label }（level 1–4）

失败模式、边界与并发

无效主题名：arkThemeProfiles[theme] || arkThemeProfiles.endfield 静默回退；CSS 端未知 data-ark-theme 时所有族覆写选择器不命中，保持 .arkR-shell 基础定义（即 endfield 视觉）。
无效深度名：data-ark-depth 的四个选择器均不命中，回落到基础行的 complex 取值（--ark-depth-rule:24% 等）。
窄视口 / 竖屏：(max-width:760px),(orientation:portrait) 媒体查询把网格从 4.5rem 1fr / 4.5rem minmax(0,1fr) 压为单列 3.8rem 1fr/1fr，隐藏 arkR-online，显示 arkR-menu 抽屉按钮；边栏改为 position:fixed 由 data-open 控制显隐，激活信号条从左侧竖条变为底部横条。这对应规范 Portrait 一节「recompose, do not scale down」的硬性要求。
菜单状态与导航联动：activeId 变化即 setMenuOpen(false)，避免竖屏切换导航后抽屉滞留。
焦点可见性：.arkR-shell button:focus-visible,.arkR-shell a:focus-visible{outline:2px solid var(--ark-signal);outline-offset:3px} 实现规范「2px signal outline plus offset」。
并发性：整层无网络/存储副作用，纯渲染 + useState，天然并发安全；无竞态路径。

性能与操作注意

token 层全部使用原生 CSS 自定义属性与属性选择器，切换族/深度的开销是一次 style 失效与重排，无 JS 循环、无运行时样式注入。
color-mix(in srgb, …, transparent X%) 被大量用于派生细线与阴影色，避免为每族维护成对 hex；依赖现代浏览器支持。
响应式断点只有两个（760px 竖屏、reduced-motion），没有中间断点；规范要求竖屏「重构」而非缩放，因此断点跨度大是刻意为之。
原创性是硬约束：纹理须为生成的 CSS/SVG，不得复制专有资产（字体、图标、插画）。规范 Quality bar 第 7 问「Is the output original and free of copied proprietary assets?」即此约束的验收形式。

扩展点

新增风格族：三步——在 arkThemes 与 arkThemeProfiles 增加条目；在 CSS 增加一组 [data-ark-theme="…"] 覆写（色彩四角色 + --ark-family-radius/rule，必要时覆写 --ark-display）；如需形制差异，追加族专属选择器（参照 popucom 对 .arkR-panel/.arkR-button 的 2px 描边 + 位移阴影覆写）。
新增深度档：在 arkDepths 增加条目并补一条 [data-ark-depth="…"] token 覆写；注意 --ark-depth-rule 是语言覆盖度的量纲，应保持单调递增。
新增组件：遵循现有分工——组件层只写语义结构 + ARIA，视觉一律落在 ark-ui.css 的类选择器里消费 var(--ark-*)。
换实现栈：assets/starter-vanilla/ 证明同一语法可以在无构建环境下用类名体系复刻；新栈只需忠实映射角色 token 与六原则。

验收（Quality bar）

references/design-language.md 末尾给出七个验收问题，可作为任何输出的最终检查表：

信息架构是否在装饰被注意到之前就已可读？
是否有一个族明确主导设计？
每一根线、代码、标签和动画是否都有角色？
构图是否不对称却平衡？
信号色与展示排印是否克制到依然有力？
竖屏布局看起来是重构过而不是缩小过？
产出是否原创、不含复制的专有资产？

共享视觉语法

目的与范围（Purpose and Scope）

概述（Overview）

架构（Architecture）

六条共享语法原则

排印语法

色彩语法：语义角色而非采样值

几何、纹理与动效语法

组件语法

核心流程：一个组合请求如何在系统中落地

使用示例

示例一：构建带默认语法的页面外壳

示例二：激活态不得只靠颜色的实现

示例三：编辑性层级的语义结构

示例四：纯 HTML 路径（无构建依赖）

配置选项（Token 属性参考）

API 参考

`ArkShell({ brand, code, status, theme, depth, nav, activeId, onNavigate, children })`

`ArkSectionTitle({ index, kicker, children })`

`ArkPanel({ code, title, tone, action, children })`

`ArkButton({ primary, className, ...props })`

`ArkThemePicker({ value, onChange })` / `ArkDepthPicker({ value, onChange })`

导出的常量

失败模式、边界与并发

性能与操作注意

扩展点

验收（Quality bar）

相关链接

Sources

共享视觉语法

目的与范围（Purpose and Scope）

概述（Overview）

架构（Architecture）

六条共享语法原则

排印语法

色彩语法：语义角色而非采样值

几何、纹理与动效语法

组件语法

核心流程：一个组合请求如何在系统中落地

使用示例

示例一：构建带默认语法的页面外壳

示例二：激活态不得只靠颜色的实现

示例三：编辑性层级的语义结构

示例四：纯 HTML 路径（无构建依赖）

配置选项（Token 属性参考）

API 参考

ArkShell({ brand, code, status, theme, depth, nav, activeId, onNavigate, children })

ArkSectionTitle({ index, kicker, children })

ArkPanel({ code, title, tone, action, children })

ArkButton({ primary, className, ...props })

ArkThemePicker({ value, onChange }) / ArkDepthPicker({ value, onChange })

导出的常量

失败模式、边界与并发

性能与操作注意

扩展点

验收（Quality bar）

相关链接

Sources

`ArkShell({ brand, code, status, theme, depth, nav, activeId, onNavigate, children })`

`ArkSectionTitle({ index, kicker, children })`

`ArkPanel({ code, title, tone, action, children })`

`ArkButton({ primary, className, ...props })`

`ArkThemePicker({ value, onChange })` / `ArkDepthPicker({ value, onChange })`