@icen.ai/ui 0.9.0 → 0.11.0

package/docs/spec/design-philosophy.md

@@ -0,0 +1,189 @@
+# Icen 设计哲学（Design Philosophy）
+
+> 本文件是 icen 设计系统的**美学宪法**：不只规定"值是多少"，更规定"为什么"。
+> 工程契约（类名/事件/守卫）在 `AGENTS.md`；本文件回答的是设计判断题——当两个实现都合法时，选哪个。
+> 读者：组件作者、消费方设计师、以及要写第七套预设的人。
+
+---
+
+## 0. 元原则（八条，按优先级排序）
+
+1. **诚实呈现**：不装饰不确定，不隐藏不确定。加载有骨架、截断有省略号、权限缺失打码并给申请口——UI 永远如实反映数据与系统状态。
+2. **单一事实源**：任何设计决策只有一个权威出处。颜色/圆角/间距/时长/字体全部 token 化；组件不写死任何设计值。
+3. **语义先于字面**：组件消费语义 token（`--icen-token-accent`），不消费原始色值。语义层的存在让"换肤"成为改语义映射，而不是改组件。
+4. **几何同心**：嵌套圆角共圆心（内圆角 = 外圆角 − 间距）。视觉上的"不对齐"比"没设计"更廉价。
+5. **克制动效**：动效是语义（抬升=可及、脉冲=活动、渐隐=去权），不是装饰。所有动画 ≤320ms，`prefers-reduced-motion` 归零，触屏无 hover 漂浮。
+6. **密度弹性**：同一组件在紧凑管理台与宽松营销页都成立。密度是连续标尺（`--icen-density-*`），不是两套断点。
+7. **无障碍底线是设计的一部分**：AA 对比度是硬约束（accent 明度三档由此而来）、焦点环永可见、状态不只靠颜色传达（图标/文字/形状冗余编码）。
+8. **明暗同构**：dark 不是反色，是同一空间换了灯光。同一组件在两态下结构、节奏、层级完全一致，只有"光照"变化。
+
+正交轴：**主题配色 × 原语 × 明暗 × 密度** 四个轴自由组合，任何一轴的切换不应破坏其它轴的决策。现代同时是默认原语与默认主题的名字；另有中式、苏式、像素三套原语。
+
+---
+
+## 1. 色彩
+
+### 1.1 语义纪律
+- 语义色只有五个：success 绿 / warning 黄 / error 红 / info 蓝 / accent 品牌色。语义色不表达装饰，只表达含义；装饰用中性层（fill-1/2、line-soft）。
+- 中性阶梯是界面骨架：`bg → bg-soft → surface → surface-strong`（明度递进），`text → text-muted → text-faint`（注意力递减），`line-soft → line → line-strong`（分隔强度递进）。三级皆有意图：soft 是"分区"、line 是"边界"、strong 是"结构"。
+- 派生色一律 `color-mix()` 从 token 现场推导（`accent-subtle = accent 14%`），不写死第二个色值——单一事实源在色彩上的体现。
+
+### 1.2 accent 明度三档
+| 档 | 角色 | 用于 |
+|---|---|---|
+| `accent` 亮档 | 品牌色 | 图标、边框、数据可视化等纯图形面 |
+| `accent-strong` | 承文本填充 | 实心按钮/选中态等「accent 底 + on-accent 字」的面（AA 硬达标） |
+| `accent-text` | 浅底文字 | 链接、弱强调文本 |
+
+`--icen-token-on-accent` 是填充上的文字色：浅色模式多为白字深底；深色模式翻转为亮底深字（Material You 夜间惯例）。**承文本填充面禁止消费 accent 亮档**（守卫红线的设计理由：2.96:1 的品牌脸事故）。
+
+### 1.3 业界参照
+GitHub Primer 的语义色纪律、Radix Colors 的阶梯尺、Stripe 的"深档承文本"按钮。六套主题共享同一语义骨架；主题改变配色，原语决定几何、材质、排版与动效。
+
+---
+
+## 2. 几何（圆角与线）
+
+### 2.1 圆角六档职责
+| 档 | 现代默认值（随 design-radius 联动） | 职责 |
+|---|---|---|
+| `xs` | 5px | 微型件内角：复选框、菜单项、日期格、小标签 |
+| `sm` | 8px | 控件：按钮、输入框、选择器 |
+| `md` | 10px | 内嵌块、大控件 |
+| `lg` | 14px | 卡片、面板、菜单与 popover |
+| `xl` | 20px | 弹窗与页面级展示面 |
+| `full` | 999px | **胶囊语义专用**（跑道形） |
+
+### 2.2 同心圆法则（Concentric Corners，取法 Apple HIG）
+嵌套圆角必须共圆心：**`R_inner = R_outer − gap`**（gap = 两层间距/padding）。
+
+```css
+.card { border-radius: var(--icen-radius-lg); padding: 12px; }
+.card .thumb { border-radius: calc(var(--icen-radius-lg) - 12px); } /* 同心 */
+```
+
+- 同心结果小于 0 时内层**直角**（0），不要出现 1–3px 的"近似圆角差"——那是视觉噪声。
+- `calc()` 不保档位时允许，但外层必须 token。
+- 守卫强制：禁裸 999px、禁撞档裸值（6/8/10/12/16）、微构件裸值须登记。
+
+### 2.3 胶囊与正圆的区分
+- `full`（999px 跑道形）只给**胶囊语义件**：pill / badge / chip / switch 轨道与拇指 / 进度与 slider 轨道 / 分段控件。胶囊的水平拉伸语义是"可延展的容器"。
+- `50%` 只给**几何正圆**：avatar、状态点、图标底。正圆的语义是"点"，不是"容器"。
+- **容器永不用 full**：跑道形卡片是业余信号。modal/popover/panel/card 走 xs–xl 档。
+
+### 2.4 线的角色
+线（hairline）优先于阴影：能用 1px `line-soft` 分区就不用投影分隔。阴影只表达"海拔"（浮起），不表达"边界"。`dashed` 线表达"待定/可投放"（拖放区、占位）。
+
+---
+
+## 3. 深度与海拔
+
+四层模型（从低到高）：`canvas（页面底）→ panel/sidebar（分区）→ card/control（内容件）→ overlay（浮层）`。
+
+- 每个海拔有对应的 surface 色 + 阴影档（`shadow-card → shadow-elevated → shadow-overlay`）+ 可选 glow。
+- **dark 模式减影加光**：深色下阴影不可见，海拔靠 surface 明度阶梯 + glow（accent-glow 微光）表达。直接复用浅色阴影是 dark 模式最常见的败笔。
+- 浮层才投影。页面内静态件只用线与 surface 差分层。
+- 参照：Fluent 的 elevation 分层、Material 3 的 tonal elevation（我们不用 tint 叠层，用明度阶梯+glow）、Linear 的克制。
+
+## 4. 动效
+
+- 三档时长：`tx-fast`（≈120–160ms，微反馈：hover/按压）、`tx-normal`（≈200–240ms，状态切换：展开/切换）、`tx-slow`（≤320ms，入场/大位移）。UI 反馈永不超 320ms——超过即动画，不是反馈。
+- 缓动选型：进场 `ease-out`（快入慢停，回应感）、退场略快于进场、循环脉冲用 `ease-in-out`。
+- 语义映射：`translateY(-N)` 抬升 = 可交互/可及；`pulse` 脉冲 = 进行中活动；`fade` = 出现/消失；`pop-in` = 新内容到达。
+- 红线：`prefers-reduced-motion` 下全部压 0ms；`pointer: coarse` 下关 hover 抬升；`forced-colors` 保留焦点环。
+- 参照：Material 的 emphasized easing、Apple 的弹簧哲学（CSS 里以 ease-out 近拟）、业界动效疲劳的教训（Stripe/Linear 的动效时长都极短）。
+
+## 5. 字体排印
+
+- 三族分工：`--icen-font-body`（界面与 prose）/ `--icen-font-mono`（代码、标识、需要等宽的数字）/ `--icen-font-heading`（标题）。现代的 body 与 heading 默认使用系统无衬线；像素原语决定自己的排版。数值对齐优先使用 tabular-nums，无需把所有界面文字改为等宽。
+- **CJK 纪律**：小字号中文不走宋体/通用 monospace 回退（糊）；中文正文 ≥12px；数据用 tabular-nums。
+- 字号/行高由 density token 出（`--icen-density-font-size-*`），组件不写死字号。
+- 行长纪律：prose 60–75 字符；表单标签与控件同行（水平表单）或顶置（纵向表单）二选一不混用。
+- 参照：IBM Plex 的"工程感人文"、Apple SF 的中性、iA 的行长研究。
+
+## 6. 密度
+
+- 密度是连续标尺不是断点：`--icen-density-space-*` / `--icen-density-font-size-*` / `--icen-density-input-height-*` 三族联动。
+- 档位语义：`compact`（管理台/数据密集型）/ `normal`（默认）/ AI 族另有 `summary`（压淡次要信息，纯 CSS 实现）。
+- compact 是"信息密度"，不是"缩小"——触控底线 40px 在任何档都不破（触屏守卫）。
+- 参照：Carbon 的 density 系统、Salesforce 的 compact 变体。
+
+## 7. 图标
+
+- 线性图标族：`viewBox="0 0 24 24"`、stroke currentColor、stroke-width 2（通用）/ 1.5（kb 族细线）、圆头线帽。
+- **尺寸契约**：图标 svg 必须自带 `width/height` 属性或有 CSS 类尺寸约束——无尺寸 svg 在 CSS 失效时会失控（默认 300×150）。这是血泪条款。
+- `xmlns` 必备（DOMParser XML 严格解析的空命名空间陷阱——svg-parse 单点已兜底，作者仍应写全）。
+- 图标不携带文字意义（旁边必有文本或 aria-label）；状态图标用语义色。
+
+## 8. 材质与预设哲学（六套预设的人格）
+
+| 预设 | 材质隐喻 | 气质 | 关键决策 |
+|---|---|---|---|
+| **modern** 现代 | 瓷面 × 柔光 | 清透、精确、安静 | 中性瓷白、冷蓝动作、冷调石墨夜间；独立校准 |
+| **dongyun** 东韵 | 绢本 × 青瓷 × 沉墨 | 温润、疏朗、克制 | 宣纸暖白与低饱和青瓷，细边界和轻微纸面层次 |
+| **jugou** 巨构 | 混凝土 × 搪瓷 × 氧化铁 | 坚实、纪念性、结构感 | 石灰白与炭黑承重，深朱红只标记关键动作 |
+| **piano** 钢琴 | 象牙琴键 × 乌木 × 大漆 | 精致、对比、仪式感 | 高对比黑白骨架、金棕点缀（金底乌木字是 AA 设计）、漆面冷反光 glow |
+| **monet** 莫奈 | 睡莲 × 水面柔光 | 静谧、通透、含蓄 | 蓝绿水面的柔光层叠，紫调只作含蓄点缀；取自莫奈《睡莲》 |
+| **vangogh** 梵高 | 麦田 × 星空 × 杏花 | 浓烈、厚涂、浪漫 | 高饱和黄蓝对撞；粉底深字（杏花气质）——亮色承深字而非白字 |
+
+每套预设都必须是**完整 token 面**（12 base + glow + derived + semantic + fill + shadow + outline + depth + scrollbar），不是改六个色——换预设 = 换材质，不是换滤镜。新增预设的完整清单见 `colors.css` 头注释与本文件 §11。
+
+## 9. 原语（与配色主题独立）
+
+- **现代 modern**（默认）：连续几何、系统排版、轻盈材料、双层柔影。
+- **中式 chinese**：低曲率轮廓、宋体展示字、舒展行距、纤细边线与浅淡纸面投影；小字号和密集信息仍用无衬线。
+- **苏式 soviet**：方正体块、凝练展示字、清楚结构线、定向投影与短促反馈；力量来自比例而非装饰符号。
+- **像素 pixel**：整数网格、中英文点阵、实色材料、直角与阶梯投影、机械按压。
+- 现代同时是一套独立的瓷白＋冷蓝主题。六个主题均可与四套原语组合。
+- 最新架构、种子与配方以 `design-primitives.md` 为准。
+
+## 10. 业界对标矩阵（我们取法谁，以及不抄什么）
+
+| 维度 | 取法 | 不抄 |
+|---|---|---|
+| 圆角同心 | Apple HIG concentric corners | iOS 超大圆角泛滥（圆角过敏） |
+| 语义色 | GitHub Primer | Material 的 60+ 语义角色（学习成本爆炸） |
+| 明度阶梯 | Radix Colors 12 步 | 不强制 12 步——三级有意图的阶梯够用 |
+| 海拔分层 | Fluent / Material tonal | Material 3 的 tonal overlay tint（污染品牌色） |
+| 动效 | Material emphasized + Linear 克制 | 弹簧物理库的过度弹性（UI 不是玩具） |
+| 密度 | Carbon / Salesforce | Salesforce 的三档断点跳跃（我们要连续标尺） |
+| 暗色 | Apple Dark Mode 重打光 | 简单反相/降亮度 |
+| 主题架构 | Radix Themes / shadcn token 面 | CSS-in-JS 运行时主题（性能与闪烁） |
+| 无障碍 | Shopify Polaris 的"内建而非选配" | 事后补钉式 a11y |
+
+## 11. 统一覆盖架构（消费方怎么改我们）
+
+三层覆盖面，从轻到重：
+
+**① 旋钮面（改几个变量）**——90% 定制只需动少数旋钮：
+
+```css
+/* 你的样式表（无层，恒赢库的三层 @layer） */
+:root {
+  --icen-token-accent: #5b6ee1;          /* 品牌色换档（strong/text 建议同步） */
+  --icen-token-accent-strong: #4353c8;
+  --icen-token-accent-text:  #3a49b8;
+  --icen-radius-md: 6px;                 /* 全局圆角基准降一档 */
+}
+```
+
+高频旋钮清单：`accent 三档` / `radius 六档` / `--icen-density-*` 三族 / 字体三族 / `tx-*` 动效三档 / `--icen-token-text-muted|faint`。文档站「定制」页的主题工作台可在线调这些旋钮并生成这段 CSS。
+
+**② 预设作者面（写新一套）**：在 `themes.json` 新增完整明暗色板与材料参数，运行 `bun run colors`；运行时、站点与导出自动同步。要求：明暗双面完整、accent 三档实测 AA、语义五色齐备、depth 阶梯完整。
+
+**③ 正交组合面**：`<html data-icen-preset="dongyun" data-icen-theme="dark" data-icen-style="chinese">` + 容器级 `data-icen-density="compact"`——四轴自由组合。
+
+兜底纪律：`@layer icen.tokens/base/components` 保证消费方无层样式恒赢；Tokens Studio / Figma Variables 导出（`bun run design-tokens`）让设计稿与代码同值。
+
+## 12. 红线（违反 = 守卫/评审必打回）
+
+1. 组件写死颜色/圆角/间距/字号/时长（绕过 token）。
+2. 承文本填充面消费 `accent` 亮档（必须 `accent-strong`）。
+3. 容器用 `full` 跑道形圆角；正圆用 999px（应 50%）或反之。
+4. 嵌套圆角不共圆心且无豁免注释。
+5. 动效超 320ms / 无 reduced-motion 归零 / 触屏 hover 漂浮。
+6. 图标 svg 无尺寸契约、缺 xmlns。
+7. dark 模式直接复用浅色阴影（不打光改明度阶梯）。
+8. 语义五色之外发明第六种"语义色"。
+9. 状态只靠颜色传达（无图标/文字/形状冗余）。
+10. 截断不声明（裸 nowrap 无省略号是文本 bleed 事故的同义词）。

package/docs/spec/design-primitives.md

@@ -0,0 +1,196 @@
+# 设计原语与「现代」
+
+现代（modern）是 ICEN UI 的第一套完整设计方案。它把材料、字体、几何、密度、光影与反馈组织成同一套规则：内容安静，操作轻盈。它不宣称在主观审美上胜过某个平台；验收对象是可读性、层次、定制成本与真实交互品质。
+
+## 启用
+
+```css
+@import '@icen.ai/ui/tokens.css';
+@import '@icen.ai/ui/base.css';
+@import '@icen.ai/ui/components/btn.css';
+```
+
+```html
+<html lang="zh-CN" data-icen-preset="modern">
+```
+
+明暗继续使用 `data-icen-theme="dark"`；去掉这个属性就是亮色。支持 SSR，把属性在首屏直接写入 HTML 即可，无需客户端初始化。若产品跟随系统，在自己的首屏主题脚本中解析系统偏好。`data-icen-preset` 必须挂在 html，body portal 的菜单与弹窗才能继承同样的原语。
+
+主题与原语是独立轴：`data-icen-preset` 选择配色主题，`data-icen-style` 选择原语。现代同时是默认主题和默认原语；另有中式、苏式、像素三套原语。共六套主题：现代、东韵、巨构、钢琴、莫奈、梵高；modern 为默认原语。
+
+## 四层结构
+
+1. **作者种子** `--icen-design-*`：品牌色、表面、文字、几何、节奏、字体、材料参数。
+2. **语义映射**：推导已有 `--icen-token-* / --icen-radius-* / --icen-density-*`，让现有组件受益。
+3. **材料角色**：content / chrome / floating，共享边缘、实面和阴影配方。
+4. **组件适配**：按钮、输入、分段选择、菜单、弹窗等，处理仅靠变量无法表达的细节。
+
+现代主题为中性瓷白＋冷蓝，独立校准，不继承其它主题的配色。
+
+代码真相：`src/tokens/themes.json` 是全部主题的明暗配色与材料参数，`colors.css` 是生成的语义映射；`src/tokens/design.css` 是原语的几何与光影配方；`src/components/material.css` 是材料与组件规则；`src/behaviors/design.ts` 是可选的品牌编译 API。材料规则随 tokens.css 进入 icen.components layer，单组件按需引入同样成立，不要求导入全量 ui.css。不写属性时也默认使用现代。
+
+## 材料
+
+```html
+<article data-icen-material="content">正文、表格、表单</article>
+<nav data-icen-material="chrome">导航和工具栏</nav>
+<aside data-icen-material="floating">临时操作</aside>
+```
+
+| 角色 | 背景 | 光与影 | 用途 |
+| --- | --- | --- | --- |
+| content | 不透明 | 轻边界，不投影 | 阅读与编辑 |
+| chrome | 不透明 | 顶部微光 | 导航与操作 |
+| floating | 不透明 | 接触影＋环境影＋顶部微光 | 临时面板 |
+
+布局、定位和内边距归业务页面。材料不携带固定宽高，不强行让所有内容成为卡片。`data-icen-material` 的通用外轮廓使用 lg 圆角；需要贴边的站栏可由布局覆盖。
+
+modern 的内容、操作与临时面板始终使用不透明表面，不启用背景模糊。`glass-*` 参数保留供自有材料和既有品牌配方兼容使用；不会让 modern 的标准操作面变成玻璃。`prefers-reduced-transparency: reduce` 与 `<html data-icen-transparency="reduced">` 继续提供跨原语的实面降级。
+
+## 修改与新增品牌
+
+简单微调只写 CSS，消费方无 layer 的样式优先于库：
+
+```css
+:root[data-icen-preset="modern"] {
+  --icen-design-radius: 12px;
+  --icen-design-glass-blur: 16px;
+}
+```
+
+任何合法的新名字都可以复用配方。它默认继承现代种子；独立品牌建议提供完整明暗文字与表面色，并按需求替换语义色。
+
+```css
+:root[data-icen-preset="my-brand"] {
+  --icen-design-accent: #244f87;
+  --icen-design-accent-strong: #244f87;
+  --icen-design-accent-text: #244f87;
+  --icen-design-on-accent: #ffffff;
+  --icen-design-radius: 12px;
+}
+:root[data-icen-preset="my-brand"][data-icen-theme="dark"] {
+  --icen-design-accent: #aac9f1;
+  --icen-design-accent-strong: #aac9f1;
+  --icen-design-accent-text: #aac9f1;
+  --icen-design-on-accent: #18283f;
+}
+```
+
+更完整的品牌可以用可选 API 编译 CSS，适用于构建时、SSR 或浏览器。它要求两套明暗基础色，验证正文/辅助文字/链接在 canvas 与 surface 上、按钮标签在 accent 上都至少达到 4.5:1。颜色接受不透明的六位 hex，避免无法确定合成背景的对比度估计。
+
+```ts
+import { createDesign, mountDesign, setDesign } from '@icen.ai/ui/behaviors/design';
+
+const brand = createDesign({
+  name: 'my-brand', radius: 12, space: 4, controlHeight: 40,
+  fontSize: 14, glassOpacity: 86, glassBlur: 18,
+  light: {
+    canvas: '#f5f6f8', surface: '#ffffff',
+    ink: '#202124', muted: '#616671',
+    accent: '#244f87', onAccent: '#ffffff',
+  },
+  dark: {
+    canvas: '#15171b', surface: '#25282e',
+    ink: '#f2f4f7', muted: '#aeb5c2',
+    accent: '#aac9f1', onAccent: '#18283f',
+  },
+});
+
+// 构建时：把 brand.cssText 写入自己的品牌样式表。
+// 浏览器：也可动态挂载，支持可选 CSP nonce；卸载函数只移除这份样式。
+const unmount = mountDesign(brand);
+setDesign(brand.name);
+// 恢复现代主题：setDesign(null); unmount();
+```
+
+`createDesign` 不自动改写作者颜色；对比度不够时抛错。工作室里的颜色选择器会演示按明暗分别调节色调的做法，导出的是处理后的真实配方。`mountDesign` 的参数应来自可信作者代码；它不是用于渲染任意终端用户 CSS 的安全沙箱。CSP 不允许内联样式时使用静态 CSS；需要内联时可传 `mountDesign(brand, nonce)`。
+
+## 作者旋钮
+
+| 名称（均以 --icen-design- 开头） | 现代亮 / 暗默认 | 意义 |
+| --- | --- | --- |
+| canvas / surface | #f5f6f8 / #fff；#15171b / #25282e | 页面与内容面 |
+| ink / muted | #202124 / #616671；#f2f4f7 / #aeb5c2 | 正文与辅助字 |
+| accent / on-accent | #0062cc / #fff；#89b9ff / #10223c | 动作与按钮文字 |
+| success / warning / error / info | 明暗各有独立值，见源码 | 语义色 |
+| radius | 10px | 六档轮廓的共同起点 |
+| space | 4px | 布局节奏单位 |
+| control-height | 34px | 标准操作高度（density compact 28 / comfortable 38） |
+| font-size / font | 13px / 系统无衬线 | 界面阅读基准；中文下限 12px |
+| glass-opacity / glass-blur | 84% / 24px；90% / 24px | 自有材料的兼容参数，modern 标准组件不消费模糊 |
+| shadow-color / shadow-strength | 中性灰 11%；黑 28% | 接触影与环境影 |
+| light / highlight-strength | 白 70%；白 9% | 表面边缘光 |
+| edge-strength | 12% / 14% | 材料边界 |
+| motion | 1 | 动效比例，0 为静止 |
+
+CSS 作者可以直接覆盖全部种子；类型 API 暴露常用旋钮，并对数值范围进行检查。需要新材料配方时，用自有 data 属性消费既有语义 token，或扩展材料文件中的角色；无需复制每个组件。
+
+## 现代的具体判断
+
+- **文字**：界面系统无衬线；代码单独等宽；数据才使用 tabular-nums。取消全局 Numeric Math 混排。正文阅读可在业务排版中提高到 16px。
+- **几何**：xs/sm/md/lg/xl 为 5/8/10/14/20px，从共同基准推导。控件 8px、卡片与面板 14px、弹窗 20px；贴合内外轮廓同心，独立控件保留自身半径。分段选择内角扣掉外壳 padding 与边框。
+- **密度**：normal / compact / comfortable 改变间距和控件高度，不缩小文字；嵌套密度可恢复 normal。触摸环境控件至少 44px。KB 行内操作使用 `--icen-density-item-height`（normal 28 / compact 24 / comfortable 32px），嵌套密度重新计算字号角色。
+- **反馈**：hover 以中性变化为主，主要动作用品牌色；键盘焦点始终明确。按压轻缩放，减少位置漂移。
+- **选择**：分段选择使用中性表面和接触影，不把每次选择都变成品牌强调。
+- **光照**：暗色保留遮挡阴影，降低高光并重新设置边缘，避免照搬亮色投影。
+- **降级**：不支持 backdrop-filter、减少透明、减少动效、高对比度模式都有明确路径。
+
+## 验收与边界
+
+工作室 `/modern/` 使用库的真实 CSS 与行为，不是图片。三个场景覆盖资料保存、开关、资料搜索、新建笔记、菜单 portal、弹窗和本地对话反馈；不连接真实账户或 AI 服务。配方编译 API、DOM 生命周期与浏览器用例见 `tests/{unit,dom}/design.test.ts` 和 `tests/e2e/design.pw.ts`。
+
+框架、用户字体和背后内容可能改变最终阅读效果；品牌作者仍应在目标系统与复杂背景中检查。任何“极其优雅”或“胜过 Apple”的判断都需要人的实际使用评审，本实现不以测试通过冒充审美结论。
+
+## 像素原语
+
+`<html data-icen-preset="modern" data-icen-style="pixel">`。顶部原语菜单可独立切换现代／中式／苏式／像素。
+
+像素采用 4px 网格、12px 原生中英文点阵、24/36/48px 标题、直角、2px 轮廓、2/4/8px 阶梯投影、机械按压和局部排线。内容与浮层都不透明，所有颜色继承当前主题；不附加 CRT 扫描线或闪烁。代码见 `src/tokens/pixel.css`，适配见 material.css。Fusion Pixel Font 按 OFL 1.1 本地分发，版本、校验和与上游许可证见 `src/fonts/README.md`。
+
+运行时使用 `setPrimitive("pixel")`；自建原语先 `registerPrimitive("brand-shape")`，再用 `[data-icen-style="brand-shape"]` 覆盖几何、字体、光影参数。主题仍单独由 setTheme({preset:...}) 选择。
+
+现代实现以内容／操作分层、同心几何、文字可读性为准则；使用稳定实面、细边与接触影建立空间。
+
+## 中式与苏式原语
+
+**中式 chinese** 从宋式器物的比例与书卷的疏朗出发：纤细边界、低曲率轮廓、宋体标题、舒展行距和浅淡投影。表单正文保留清楚的界面字体；标题负责书写气息，操作保持安静而明确。推荐与宣纸、青瓷、朱砂组成的「东韵 dongyun」主题搭配。
+
+**苏式 soviet** 从构成主义与纪念建筑的结构出发：方正轮廓、有分量的字重、清楚的分区和定向投影；主次通过比例与结构线建立。推荐与石灰岩、炭黑、氧化红组成的「巨构 jugou」主题搭配。
+
+```ts
+setTheme({ preset: 'dongyun' });
+setPrimitive('chinese');
+// 两轴分别控制；保留东韵配色也可以切换苏式几何。
+setPrimitive('soviet');
+```
+
+两套原语的几何与排版分别位于 `src/tokens/chinese.css`、`src/tokens/soviet.css`，组件适配位于 `src/components/material-chinese.css`、`src/components/material-soviet.css`。与现代、像素相同，随 tokens.css 分发；切换不会强制修改当前配色与明暗，首屏恢复、跨页面与跨标签页使用同一持久化状态。
+
+## 六套主题的校准
+
+| 主题 | 日间 | 夜间 | 材料取向 |
+| --- | --- | --- | --- |
+| 现代 | 瓷白、清晰冷蓝 | 冷调石墨、浅蓝动作 | 清透、柔光，弱化边框 |
+| 东韵 | 宣纸、青瓷与朱砂 | 深墨、温润玉色 | 纸与瓷的细腻层次，疏朗而克制 |
+| 巨构 | 石灰岩、炭黑与氧化红 | 深炭、暖石与朱红 | 厚重实色，清楚的结构层次 |
+| 钢琴 | 象牙白、乌木字、克制金棕 | 黑漆、香槟金 | 清晰边缘与细薄反光 |
+| 莫奈 | 青灰水面、睡莲绿 | 深潭蓝绿、微光紫意 | 低反光、柔光，紫调含蓄 |
+| 梵高 | 麦色画布、钴蓝动作 | 深蓝、星光金 | 保留暖冷对照，控制大面积饱和度 |
+
+每套显式配置 bg / surface / raised 三层，正文／辅助／次要文字、文字强调和四类语义色在三层均验证 4.5:1；按钮另验 accentStrong × onAccent。图形强调、按钮填充、文字强调分别配置，使用原语或更换主题不会混淆其职责。
+
+原始目录可通过 `@icen.ai/ui/tokens/themes.json` 读取。编辑本仓库主题先改目录，再运行 `bun run colors`；CSS 构建和 DTCG 导出也会确保生成文件新鲜。自定义品牌 API 会自动补齐强调色三个角色，手写 CSS 时应明确同时配置这三档。
+
+## 操作符号与显隐节奏
+
+界面图标采用同一套原创 SVG 光学网格。DOM、SSR 和 CSS mask 读取同一份路径，避免图标字体受平台字形、基线和字重影响。共享入口：
+
+```ts
+import { createIcon, iconHTML } from '@icen.ai/ui/kit/icon';
+button.append(createIcon('close')); // button 自己提供 aria-label
+const html = iconHTML('check', { size: 16, label: '已完成' });
+```
+
+次要操作占用稳定的命中槽位，通过 opacity 和轻微缩放出现；不会推开内容。键盘 focus-within 与 hover 等价，触屏没有 hover 时持续可见。主要入口与关键状态持续可见。多动作控件分别保留展开和清除槽位，不能通过重复末端 padding 把图标挤入文字区。级联面板按列扩展并限制在视口内，内部滚动不得带动文档。
+
+图形保持克制、可辨认和对齐；参考 [Apple 的按钮设计指引](https://developer.apple.com/design/human-interface-guidelines/buttons) 中关于跨尺寸一致性的原则。具体 SVG 路径是本库自己的绘制，不依赖平台字体。