@gyyxds/zy-ui 0.0.2 → 0.0.3

package/CHANGELOG.md

@@ -2,7 +2,18 @@
 
 ## Unreleased
 
+- **站点瘦身：回归组件库与组件文档本身**。移除动效页（`/animations`）、效果详情页、收藏页与 `src/effects/**` 片段体系，连同 `mocks/families.ts` / `mocks/catalog.ts` / favorites store / `PreviewHost` / `GlassCard` / `GlassButton` / `FilterChip` 一并删除；旧地址与未知路由统一回落首页。组件库公共 API 不变。
+- **首页改为展示设计方案**：`/` 现在按「两根轴 → 四种组合 → 两套色板 → 设计原则 → 判据 → 落地清单」展示 `docs/theme` 的方案；四种组合可点击切换整站材质与光照。色板与文案的单一事实源迁到 `src/mocks/theme-design.ts`，四张展示板读同一份数据。
+- 校验脚本收敛：`check:registry` 只校验组件注册表 ↔ 实现文件、`COMPONENT_TOTAL` 与 `--zy-*` 令牌完整性；移除 `check:snippets` 与 `sync:scoped`（片段体系已下线），CI 同步。
+- **首页改用四张背景图**：`basic` / `solid` × 浅色 / 深色各一张 `1920 × 1200` PNG（`src/assets/backgrounds/`），按主题切换铺满视口，代替原来的页面渐变；左上阅读区保持近纯色，图纸的弧线 / 网格与键帽的挤出体只压在页边，生成脚本为 `scripts/gen_home_backgrounds.py`。
+- 修复 `ZyMegaMenu` 在实色主题下一级选中与悬停不一致的问题：悬停、选中、展开统一为同一枚凸起的品牌键（不使用内凹槽，也不再为展开单独按下），开合只由箭头方向表示；图纸主题原本就是浅底常亮，行为不变。
+- **顶栏导航改为胶囊滑行**：四个栏目不再铺轨道，选中胶囊直接浮在顶栏上，复用 `ZyRadioGroup` 分段按钮组的 400ms 回弹曲线与 320ms 品牌光晕；顶栏移到路由外，切栏目时不再重建，胶囊从上一格滑过去，同栏目内换组件页不闪。深色胶囊 / 字色另调，当前栏目补 `aria-current="page"`。
+- **站点品牌文案统一为「智云UI」**：顶栏、页面标题、页脚、关于页、MegaMenu 示例与主题展示板里的 MotionVault 字样全部替换。主题存储键（`motionvault-theme` / `motionvault-zy-theme`）与仓库路径保持不变，避免已有访客的主题选择丢失。
+- **主题页改为当前实现的真实演示**：`/theme` 用材质 / 光照两根轴的开关、9 颗真实 `ZyButton`（press / sweep / fill）、4 个材质验收样本（`raised`、`fill`、`hover-fill`）和品牌色 / 圆角令牌覆盖，替换原先手写按钮与站点变量样板；覆盖片段含深浅两档与悬停 / 按下派生令牌，可一键复制。
+- 修正 README / AGENTS 的深色换肤示例：`html.dark` 的权重低于 `dark.css` 的 `html.dark[data-zy-theme]`，示例改用 `html.dark[data-zy-theme]` 并注明加载顺序。
+- 文档更新：README / AGENTS / CONTRIBUTING / `docs/theme/README.md` / `dark-mode-design.md` 按新范围重写；删除已过时的 `docs/SPEC.md`。
 - `ZyMegaMenu` 面板里的二级菜单在没有 `desc`（描述行）时，图标与名称改为垂直居中，行高由 56.5 收到 36（图标 30 → 24、上内距 9 → 6）；有描述时排版不变。
+- `ZyMegaMenu` 新增选中态 `active`（一级项 key）/ `activeLink`（二级链接标题）：选中项沿用悬停那套底色常亮，一级和二级都不再随指针离开或面板收起消失；不传这两个 prop 时点击链接自动记下，并回传 `update:active` / `update:activeLink`。
 - `ZyTag` 的 `effect="fill"` 与 `ZyButton` 对齐：图纸主题里没有实色键帽这一档，切到图纸时自动退回 Element 的浅底标签；组件页的「实色标签」舞台同样只在键帽主题下出现。
 - 修复 `ZyTag` 在 `effect="fill"` + `closable` 时关闭图标与实色面同色、默认看不见的问题：关闭图标改跟标签字色（`--el-tag-text-color`），悬停不再被 Element 强制成「白图标 + type 色圆底」，改为压暗到挤出底座色，键盘焦点环也跟着字色走。
 - 发布流程补前置体检：`npm run release` 现在先跑 `scripts/check-release-env.mjs`，检查 registry、账号登录、该版本是否已发布、有无待发 changeset；不通过直接退出并给出补法（原来要先跑完 40 秒构建，再在 `changeset publish` 上撞 `ENEEDAUTH`）。同时把 `.changeset/config.json` 的 `access` 从 `restricted` 改回 `public`，与 `package.json` 的 `publishConfig` 对齐。

package/CONTRIBUTING.md

@@ -2,11 +2,11 @@
 
 ## 先判断产物类型
 
-- 有 props / events / slots，供业务项目 `import`：组件。
-- 一段可复制的 HTML / CSS（可选原生 JS）：动效片段。
-- 两者不能互相冒充。新增内容前先确认归属。
+- 有 props / events / slots，供业务项目 `import`：组件（`src/zy/`）。
+- 组件的用法与设计依据：文档页（`src/views/`、`src/mocks/`）与设计规范（`docs/theme/`）。
+- 动效片段体系已于 2026-10 下线；组件内的 `effect` 微动效属于组件 API，不单独建产物。
 
-组件库改造规范见 [docs/ui-library-refactor-spec.md](docs/ui-library-refactor-spec.md)。
+组件库改造规范见 [docs/ui-library-refactor-spec.md](docs/ui-library-refactor-spec.md)，主题设计见 [docs/theme/README.md](docs/theme/README.md)。
 
 ## 本地开发
 
@@ -34,6 +34,14 @@ npm run dev
 7. 视觉基线更新并经过人工审核。
 8. README / 规范中的组件数量和说明同步。
 
+## 新增或修改设计 / 首页
+
+1. 主题名、立场、两档色板、材质解剖、原则与判据改 `src/mocks/theme-design.ts` —— 首页 `/` 与四张展示板共用这一份，不要在两处各写一份。
+2. 令牌改 `src/zy/styles/tokens/`，材质改 `src/zy/styles/themes/`；主题层只消费 `--zy-*`。
+3. 同步 `docs/theme/README.md`（推导与数值）并跑 `node docs/theme/tools/contrast.mjs`。
+4. 首页结构改 `src/views/HomeView.vue`，保持「两根轴 → 四种组合 → 两套色板 → 原则 → 判据／落地」的信息顺序。
+5. 视觉有变化时先人工确认，再 `npm run check:visual:update`。
+
 ## 主题约束
 
 - 主题属性：`html[data-zy-theme="basic|solid"]`。
@@ -41,13 +49,12 @@ npm run dev
 - 组件优先消费 `--zy-*` 语义令牌。
 - 主题层不得引用展示板专用类名或站点专属变量。
 - 不得依赖组件内部 `.el-*` 子结构作为公共 API。
-- 深色当前统一回退 `basic`，不要在深色中单独叠加 `solid` 材质。
+- 深浅色在当前材质内切换（`solid` 深色 = 「键帽 · 夜」），不要回退到另一套材质，也不要在深色中叠加 `solid` 材质。
 
 ## 提交前验证
 
 ```bash
 npm run check:registry
-npm run check:snippets
 npm run lint
 npm run test
 npm run build

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 @gyyxds/zy-ui contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,8 @@
-# Zy UI 组件库 · MotionVault
+# Zy UI 组件库 · 智云UI
 
-基于 **Vue 3 + TypeScript + Vite** 的 Element Plus 二次封装组件库，配套一套**可直接复制粘贴**的动效片段与文档站。组件带 props / 事件 / 插槽并随包发布；动效片段只在文档站复制使用，不进包。
+基于 **Vue 3 + TypeScript + Vite** 的 Element Plus 二次封装组件库，配套一套**组件文档 + 设计规范站**（智云UI）。
+
+组件带 props / 事件 / 插槽，随包发布；文档站与展示板不发布，它们是这套组件的用法说明与设计依据。
 
 | 属性 | 说明 |
 | --- | --- |
@@ -9,21 +11,25 @@
 | 构建工具 | Vite 8（库模式）+ vue-tsc |
 | 模块格式 | 仅 ESM（`"type": "module"`），无 CJS 产物 |
 | 组件数 | 28 |
-| 动效片段 | 57（零依赖、零 JS） |
-
-## 先说清楚：两套产物，别混
+| 设计主题 | 2 套材质（图纸 / 键帽）× 2 档光照（浅 / 深） |
 
-> **动效页（`/animations/:id`）里的 HTML / CSS 是「即时复制粘贴」用的片段，不属于发布的组件库。**
-> 它们没有 npm 导出路径、不进 `dist/zy-ui`、也不能 `import`；正确用法是在文档站复制三栏代码，粘到自己页面里跑。
+## 仓库里有什么
 
-| | 组件库（`src/zy/`） | 动效片段（`src/effects/<key>/`） |
+| | 组件库（`src/zy/`） | 文档与设计站（`src/views/`、`docs/theme/`） |
 | --- | --- | --- |
-| 是什么 | 有 props / 事件 / 插槽的 Vue 组件 | 可直接复制的 HTML + CSS（可选原生 JS） |
-| 怎么用 | `npm i @gyyxds/zy-ui` 后 `import` | 文档站动效页复制三栏代码，粘贴即用 |
-| 运行时依赖 | vue、element-plus（均为 peerDependency） | 零依赖 |
-| 是否发布 | 进 lib 构建（`dist/zy-ui/`） | 不进任何构建产物 |
+| 是什么 | 有 props / 事件 / 插槽的 Vue 组件 | 组件的用法文档 + 两套材质的设计方案 |
+| 怎么用 | `npm i @gyyxds/zy-ui` 后 `import` | 浏览器打开站点；设计推导见 `docs/theme/` |
+| 是否发布 | 进 lib 构建（`dist/zy-ui/`） | 不进包，只作为站点与设计资料 |
+
+> 2026-10 站点瘦身：动效页（`/animations`）、收藏页（`/favorites`）与片段体系已下线，仓库回归「组件库 + 组件文档 + 设计规范」。
+> 组件自带的 `effect` 微动效（按压缩放、色块扫入、实色键帽等）仍在组件库内，属于组件 API 的一部分。
 
-判断标准一句话：**要 API 就是「组件」，要粘贴就是「动效」。**
+站点产物与库产物分开放：
+
+```
+dist/site/     # 文档站（npm run build）
+dist/zy-ui/    # 组件库（npm run build:lib，进包）
+```
 
 ## 功能特性
 
@@ -31,16 +37,18 @@
 - 多个组件带一组 `effect` 微动效：按钮 `press` / `sweep` / `fill`，输入框 `underline` / `gradient` / `brutalist`，选择器 `underline` / `gradient` …
 - 两套材质主题 × 深浅两档，四组配色互不回退：图纸（`basic`）与实色键帽（`solid`）
 - 设计令牌随包发布（`--zy-*`），覆盖语义令牌即可换肤，无需改组件代码
-- TypeScript 类型声明随包发布；ESLint 0 警告门槛、Vitest 单测、消费方冒烟检查
-- 57 个零依赖动效片段，复制即用（见上文说明，不属于包内容）
+- 首页是设计方案本身：两根正交的轴、四种组合、两套色板、原则与判据；点色卡即可切换整站主题
+- TypeScript 类型声明随包发布；ESLint 0 警告门槛、Vitest 单测、消费方冒烟检查与视觉回归
 
 ## 组件列表（28 个）
 
+分类与文档站一致（`src/mocks/element-components.ts`）。
+
 ### 基础（3）
 
 | 组件 | 说明 |
 | --- | --- |
-| `ZyButton` | `type` / `plain` / `round` / `dashed` / `circle` 对齐 Element。`effect`：`press`（按压缩放，默认）/ `sweep`（左侧图标块 + 色块扫入）/ `fill`（实色键帽 + 悬停扩散，仅键帽主题，图纸主题下自动按 `press` 渲染） |
+| `ZyButton` | `type` / `plain` / `round` / `dashed` / `circle` 对齐 Element。`effect`：`press`（按压缩放，默认）/ `sweep`（左侧图标块 + 色块扫入）/ `fill`（实色键帽 + 悬停中心扩散，**仅键帽主题**，图纸主题下自动按 `press` 渲染） |
 | `ZyIcon` | 内置 SVG 图标，`name` 取 `src/assets/icons/` 的文件名（如 `btn-search`）；`size` / `label` / `spin` |
 | `ZyLoading` | 纯 div + CSS，不基于 Element。`type`：`dots` 点环 / `line` 心电描线 / `text` 故障字 / `bar` 跳球柱形；`color` / `speed` / `width` / `height` / `label` |
 
@@ -48,13 +56,13 @@
 
 | 组件 | 说明 |
 | --- | --- |
-| `ZyInput` | `effect`：`focus`（默认）/ `underline` / `gradient` / `brutalist`；另有 `label` 浮动标签与 `raised` 键帽凸起形态 |
-| `ZyCodeInput` | 验证码输入。`length` / `status`（idle / error / success）/ `size` / `mask` / `caret` / `disabled`，`v-model` + `complete` 事件 |
+| `ZyInput` | `effect`：`focus`（默认，描边转主色）/ `underline`（下划线扫过）/ `gradient`（渐变边）/ `brutalist`；另有 `label` 浮动标签、`raised` 键帽凸起形态 |
+| `ZyCodeInput` | 验证码输入。`length` / `status`（idle / error / success）/ `size` / `mask` / `caret` / `disabled`；`v-model` + `complete` 事件 |
 | `ZySelect` | `effect`：`focus` / `underline` / `gradient`；其余 API 照 Element |
 | `ZyCheckbox` / `ZyCheckboxGroup` | `effect`：`''` / `checkmark` / `tick`；Group 用 `v-model` 收集选中值 |
 | `ZySwitch` | 自研全息开关（不基于 Element）：扫描线 / 粒子 / 三环自转；`v-model` + `activeText` / `inactiveText` / `label` / `disabled` |
 | `ZyRadio` / `ZyRadioGroup` / `ZyRadioButton` | 选中态辉光圆点 + 过冲弹跳；`effect`：`''` / `underline` |
-| `ZySlideVerify` | 滑块拼图验证（内置插画底图）。`gap` / `tolerance` / `image` / `darkImage` / `showRefresh` 与各档文案；事件：成功 / 失败 / 刷新 |
+| `ZySlideVerify` | 滑块拼图验证（内置插画底图《缺口光谱》）。`gap` / `tolerance` / `image` / `darkImage` / `showRefresh` 与各档文案；事件：成功 / 失败 / 刷新 |
 | `ZyDatePicker` / `ZyTimePicker` | 触发框与弹层形态重绘，API 照 Element |
 
 ### 数据（7）
@@ -62,12 +70,12 @@
 | 组件 | 说明 |
 | --- | --- |
 | `ZyCard` | `shadow`（always / hover / never）、`hoverFill`（悬停铺色，可传颜色） |
-| `ZyTag` | `effect`：`dark` / `light`（默认）/ `plain` / `fill`（实色键帽，仅键帽主题；图纸下退回浅底，可关闭时关闭图标跟字色） |
+| `ZyTag` | `effect`：`dark` / `light`（默认）/ `plain` / `fill`（实色键帽，**仅键帽主题**；图纸主题下自动退回浅底；`closable` 时关闭图标跟标签字色） |
 | `ZyBadge` | 等宽数字不跳宽；`effect`：`''` / `ping`（扩散圈） |
-| `ZyProgress` | 轨道 + 蓝绿渐变填充 |
+| `ZyProgress` | 轨道 + 蓝→绿渐变填充 |
 | `ZyTable` | 台账式表格，`lines`（all / row）控制网格线；数据与列走插槽 / Element 透传 |
 | `ZyTree` | 引导线 + 折角接线 + 写实节点图标；`folderIcon` / `folderOpenIcon` / `fileIcon` |
-| `ZyPagination` | 纸面按钮 / 中性键帽页码 + 跳页输入框 |
+| `ZyPagination` | 纸面按钮 / 中性键帽页码，跳页输入框 |
 
 ### 反馈（2）
 
@@ -85,22 +93,49 @@
 | `ZyPanel` | 通用容器：有 `title` 分标题栏 + 正文，无 `title` 通体白面 |
 | `ZyMegaMenu` | 数据驱动导航：`items`（有 `panel` = 下拉，无 `panel` + `href` = 普通链接）、`brand`；受控开合 `v-model:open`；`#panel-<key>` 接管面板内容 |
 
-## 动效片段（57 个，复制即用，不发布）
+## 设计系统：两套语言 × 两档光照
 
-- 分类（`src/mocks/families.ts`）：基础 / 按钮 / 表单 / 数据 / 反馈 / 导航 / 布局 / 动效。
-- 每个片段一个目录，三件套 + 一份配置：
+站点首页（`/`）展示的就是这套方案，数据源在 `src/mocks/theme-design.ts`；完整推导、逐组件增量与对比度体检在 [`docs/theme/README.md`](docs/theme/README.md)。
 
-```
-src/effects/switch-burst/
-  snippet.html         纯标记，无 Vue 语法
-  snippet.css          自包含样式，每个 var() 都带字面量兜底
-  snippet.scoped.css   站内渲染用（由 snippet.css 派生，别手改）
-  snippet.js           可选；确实需要脚本时才有（当前 57 个全部零 JS）
-  meta.ts              舞台与文档配置：scale / doc（棋盘底等可选字段）
-```
+### 两根正交的轴
+
+| 轴 | 根属性（设在 `<html>` 上） | 取值 | 默认 |
+| --- | --- | --- | --- |
+| 材质主题 | `data-zy-theme` | `basic`（图纸）/ `solid`（实色键帽） | `solid` |
+| 光照 | `data-zy-color-scheme` + `html.dark` class | `light` / `dark` | `light` |
 
-- 复制出去能直接用：`var(--fx-x, 兜底)` 保留兜底值、片段自带 `box-sizing` 兜底、`<span />` 这类只对 Vue 模板块成立的写法已补成标准 HTML。
-- 片段与主题解耦（令牌走 `--fx-*`），所以在文档站切换主题不会改变动效页的观感。
+两轴自由组合：深浅色在**当前选中的材质**内切换，不会把 `solid` 折叠回 `basic`。
+
+### 四种组合
+
+| 组合 | 一句话 | 主要落点 |
+| --- | --- | --- |
+| A · 图纸 / 浅色 | 白纸 + 发丝线 + 6px 方角，一张纸压一张纸 | `src/zy/styles/themes/basic.css` |
+| A · 图纸 / 深色 | 同一张纸，夜里开了一盏台灯：只换光，不加厚度 | `basic.css` §0.1 + `tokens/dark.css` |
+| B · 键帽 / 浅色 | 白键摆在灰桌上：凸起靠底座，凹槽靠内阴影 | `src/zy/styles/themes/solid.css` |
+| B · 键帽 / 深色 | 同一张桌关了顶灯：顶光收薄、落影加重，厚度一分不减 | `solid.css` §0.1 / §0.2 |
+
+两套语言只换材质，不动寸法：同一组件在两套主题下的高度差为 0（键高走 `box-shadow`，不进盒模型）。
+
+### 判据
+
+1. 正文 ≥ 4.5:1、控件边界 ≥ 2.4:1、分层 ≥ 1.1:1。
+2. 主题不得改变形状、尺寸、圆角与位移方向。
+3. 深色只换光照：不给 A 加厚度，也不去掉 B 的白弧与底座。
+4. 字色跟着面走：面亮配墨、面深配白；同一语义允许在两档里给不同答案。
+
+`node docs/theme/tools/contrast.mjs` 会逐对验算这四张板的色板。
+
+### 首页展示什么
+
+| 区块 | 内容 |
+| --- | --- |
+| 抬头 | 两套语言的立场、两根轴、28 个组件 / 2 套材质 / 2 档光照 |
+| 四种组合 | 2 × 2 卡片，点任意一格把整站切到那套材质与光照 |
+| 两套色板 | A / B 各一段，浅色与深色并排印出令牌名、用途与实际值 |
+| 设计原则 | 两条语言各自的层级、只换材质、两档光照、字色跟面走 |
+| 判据 | 对比度与尺寸的硬门槛 |
+| 落地 | 令牌、材质层、展示板与对比度工具的位置 |
 
 ## 安装使用
 
@@ -132,7 +167,9 @@ createApp(App).use(ElementPlus).mount('#app')
 | `@gyyxds/zy-ui/theme/basic.css` | 主题 A「基础用法 / 图纸」材质层 |
 | `@gyyxds/zy-ui/theme/solid.css` | 主题 B「实色键帽」材质层 |
 
-三种引入方式：
+两个主题 CSS 可同时引入，由根元素属性决定谁生效。
+
+### 三种引入方式
 
 ```ts
 // ① 全局注册
@@ -161,7 +198,7 @@ const keyword = ref('')
 </template>
 ```
 
-使用约定：
+### 使用约定
 
 - 未显式声明的 Element props / 事件按 Vue 的 attribute 透传，落到内部 `El*` 上。
 - 具名插槽原样转发给内部 Element 组件（如 `<ZyButton><template #icon>…</template></ZyButton>`），默认插槽由各组件自己安排位置。
@@ -169,44 +206,39 @@ const keyword = ref('')
 - 图标属性传字符串时按本库内置图标名解析（`ZyIcon` / `ZyTree` 等）；`ZyButton` 的 `icon` 目前只在 `sweep` 下解析字符串，`press` / `fill` 请按 Element 规则传组件或走 `#icon` 插槽。
 - 不要依赖组件内部 `.el-*` 子结构与内部类名：只有 props / 事件 / 插槽 / `--zy-*` 令牌是稳定契约。
 
-## 主题
-
-主题与明暗是两根独立的轴，都设在 `<html>` 上：
+## 主题与令牌
 
 ```html
 <html data-zy-theme="solid" data-zy-color-scheme="light"></html>
 ```
 
-| 轴 | 属性 | 取值 | 默认 |
-| --- | --- | --- | --- |
-| 材质主题 | `data-zy-theme` | `basic`（图纸）/ `solid`（实色键帽） | `solid` |
-| 明暗 | `data-zy-color-scheme` + `html.dark` class | `light` / `dark` | `light` |
-
-- 两套材质各有深浅两档，切换深浅不会把当前材质换成另一套。
 - 业务侧开深色：给 `<html>` 加 `dark` class 即可（`data-zy-color-scheme` 是语义标记）。
-- 两个主题 CSS 可以同时引入，由根属性决定谁生效。
-
-两套材质说的是什么：
-
-- **`basic` 基础用法（图纸）**：信息优先。纸白面 + 1px 发丝描边 + 极轻双层影，6px 方角；层级靠描边与留白，不靠厚度。
-- **`solid` 实色键帽（实物）**：能按的件是凸的（实色面 + 深一档挤出边 + 两侧白弧 + 落地影），装东西的件是凹的（内阴影）；按下必然下沉。只改材质，不改形状与尺寸。
-
-换肤：覆盖语义令牌即可，不要动组件内部结构。
+- 换肤覆盖语义令牌，不要动组件内部结构：
 
 ```css
+/* 业务侧换肤：覆盖语义令牌 */
 :root {
   --zy-brand: #0066a9;
   --zy-radius: 6px;
   --zy-ease-out: cubic-bezier(0.23, 1, 0.32, 1);
 }
-html.dark {
-  --zy-brand: #3d8fd4;
+/* 深色选择器要与 dark.css 同权重，并让业务 CSS 晚于主题 CSS 加载 */
+html.dark[data-zy-theme] {
+  --zy-brand: #5aa6e4;
 }
 ```
 
-常用令牌：`--zy-brand` / `--zy-green` / `--zy-danger` / `--zy-warning` / `--zy-info`、`--zy-ink` / `--zy-muted`、`--zy-paper`（页面底）/ `--zy-surface`（面）/ `--zy-hairline`（发丝线）、`--zy-radius`（6px）/ `--zy-radius-sm`（4px）/ `--zy-radius-pill`（999px）、`--zy-shadow-card` / `--zy-shadow-float` / `--zy-focus-ring`、`--zy-duration-fast` / `--zy-duration-press`、`--zy-ease-out` / `--zy-ease-soft`、`--zy-font-sans`。键帽主题额外有 `--zy-key-*` / `--zy-slot-*` / `--zy-desk`（只在该主题下定义）。
+`html.dark` 的权重低于 `dark.css` 里的 `html.dark[data-zy-theme='basic' | 'solid']`，单独写会被盖住；`html.dark[data-zy-theme]` 与它同级，后加载即可覆盖。
+
+深色实心件另消费 `--zy-brand-key`（键面），悬停 / 按下走 `--zy-brand-deep` / `--zy-brand-active`；换整套品牌色时一并覆盖，`/theme` 页有可复制片段。
+
+令牌分层固定：`primitives.css`（原始值）→ `semantic.css`（语义值，业务应覆盖这一层）→ `element.css`（Element Plus 映射）→ `dark.css`（深色覆盖）。
 
-## 本地调试
+常用语义令牌：`--zy-brand` / `--zy-green` / `--zy-danger` / `--zy-warning` / `--zy-info`、`--zy-ink` / `--zy-muted` / `--zy-inverse`、`--zy-paper` / `--zy-surface` / `--zy-hairline`、`--zy-radius`（6px）/ `--zy-radius-sm`（4px）/ `--zy-radius-pill`（999px）、`--zy-shadow-card` / `--zy-shadow-float` / `--zy-focus-ring`、`--zy-duration-fast` / `--zy-duration-press`、`--zy-ease-out` / `--zy-ease-soft` / `--zy-ease-overshoot`、`--zy-font-sans`。
+
+键帽主题额外有 `--zy-desk` / `--zy-slot-*` / `--zy-key-*`，只在该主题下定义。组件级微调优先用组件暴露的局部变量，如按钮 sweep/fill 的 `--zy-btn-sweep-clr` / `--zy-btn-fill-clr` / `--zy-btn-fill-hover-clr`。
+
+## 本地开发
 
 ### 1. 安装依赖
 
@@ -215,7 +247,7 @@ npm install
 # 或 yarn install --ignore-engines（@changesets/cli 要求 yarn ≥ 4.5，本机 yarn 1.x 需跳过引擎检查）
 ```
 
-Node.js 需 ≥ 20.19（Vite 8 要求）。
+Node.js 需 `^20.19` 或 `>= 22.12`（Vite 8 要求）。
 
 ### 2. 启动开发服务
 
@@ -223,7 +255,7 @@ Node.js 需 ≥ 20.19（Vite 8 要求）。
 npm run dev
 ```
 
-该命令会先跑 `check:registry` 与 `check:snippets` 两项校验，再启动 Vite（默认端口 **5173**，`host: true` 便于局域网访问）。
+该命令会先跑 `check:registry` 校验组件注册表，再启动 Vite（默认端口 **5173**，`host: true` 便于局域网访问）。
 
 ### 3. 访问文档站
 
@@ -231,87 +263,79 @@ npm run dev
 
 | 路由 | 内容 |
 | --- | --- |
-| `/components/:id` | 组件页：左树右文 + 舞台 + API 属性表 |
-| `/animations/:id` | 动效页：左舞台（底色两档可切）+ 右只读代码面板（HTML / CSS / JS 分栏），复制即用 |
+| `/` | 首页：设计方案（两根轴、四种组合、两套色板、原则与判据） |
+| `/components/:id` | 组件页：左树右文 + 舞台 + 可复制 SFC + API 属性表 |
+| `/theme` | 主题实验室：材质 / 光照切换、真实组件验收、品牌色与圆角令牌覆盖 |
+| `/about` | 关于：项目说明、使用授权、更新日志 |
+
+首页背景是四张 `1920 × 1200` PNG：`basic` / `solid` 两套材质 × 浅色 / 深色两档，分别铺满视口；首页不再使用页面渐变。图片由 `scripts/gen_home_backgrounds.py` 生成，设计与构图说明见 `docs/theme/home-backgrounds.md`。
 
-顶栏可切材质（图纸 / 键帽）与深浅；`?theme=dark&zyTheme=basic` 之类的查询参数可固定主题，方便截图与分享。
+顶栏可切深浅；顶栏菜单是一枚直接浮在顶栏上的胶囊（不铺轨道），复用 `ZyRadioGroup` 分段按钮组的 400ms 回弹节奏，切栏目时胶囊从上一格滑过去，不再重建。材质与光照在首页的四种组合或 `/theme` 切换。`?theme=dark&zyTheme=basic` 之类的查询参数可固定主题，方便截图与分享。
+
+旧地址 `/animations`、`/favorites` 与未知路由都会回到首页。
 
 ### 4. 常用命令
 
 | 命令 | 作用 |
 | --- | --- |
-| `npm run dev` | 文档站（前置跑 registry + snippets 校验） |
+| `npm run dev` | 文档站（前置跑 registry 校验） |
 | `npm run build` | 构建站点 → `dist/site/` |
 | `npm run build:lib` | 构建可发布库 → `dist/zy-ui/`（只含 28 个组件） |
 | `npm run lint` | ESLint 检查（0 警告门槛） |
 | `npm run test` | Vitest 单元测试 |
-| `npm run check:registry` | 动效 key ↔ 目录 ↔ `meta.ts` 三方一致、片段文件齐备、组件数核对 |
-| `npm run check:snippets` | 片段硬规则体检 + scoped 样式同步检查 |
+| `npm run check:registry` | 组件注册表 ↔ 实现文件、站点组件数、令牌完整性 |
 | `npm run check:package` | 校验包导出目标与 `npm pack` 文件清单 |
 | `npm run check:consumer` | 用 `npm pack` 产物在空项目安装、类型检查并构建 |
 | `npm run check:theme-runtime` | 主题运行时校验（需先启动站点） |
 | `npm run check:visual` / `:update` | 视觉回归 / 审核通过后更新基线（需先启动站点） |
-| `npm run sync:scoped` | 由 `snippet.css` 生成 `snippet.scoped.css` |
 | `npm run check:release-env` | 发布前置体检：registry / 登录 / 版本 / 待发 changeset |
 | `npm run changeset` | 记录一次待发布变更 |
 | `npm run release` | 体检 → 构建 → `changeset publish` |
 
-`dev` / `build` / `build:lib` 都已前置跑 `check:registry` 与 `check:snippets`；站点与库产物分开放（`dist/site` 与 `dist/zy-ui`），互不覆盖。
+站点与库产物分开放（`dist/site` 与 `dist/zy-ui`），互不覆盖。
 
 ### 5. 业务项目直接引用本仓库（`file:` 依赖）
 
-业务项目里写 `"@gyyxds/zy-ui": "file:../motion-vault-components"` 时，**不会**跑本仓库的 `prepare` / `prepublishOnly`，装的就是仓库里现成的 `dist/zy-ui`。所以改了组件后要手动重建一次：
+业务项目里写 `"@gyyxds/zy-ui": "file:../motion-vault-components"` 时，**不会**触发本仓库的构建（`prepublishOnly` 只在 `npm publish` 时跑），装的就是仓库里现成的 `dist/zy-ui`。所以改了组件后要手动重建一次：
 
 ```bash
 # 本仓库：改了 src/zy 之后都要跑一遍（约 30 秒，跑完 lint / 测试再打更稳）
 npm run build:lib
 
 # 业务项目：file: 依赖是软链，重建后产物已经生效，下面这步一般不需要；
-# 只有 package.json 的 exports / 版本号变了才重装，换包名或首次接入时也要装一次
+# 只有 package.json 的 exports / 版本号变了才重装
 npm install
 ```
 
-验证是不是跑上了最新的：
-
-```bash
-# 1. 产物时间应该是刚才 build:lib 的时间（dist 被 .gitignore 忽略，但 file: 依赖照样读得到）
-dir node_modules\@gyyxds\zy-ui\dist\zy-ui\zy-ui.js
-
-# 2. 版本号与仓库 package.json 一致（现在是 0.0.1）
-npm ls @gyyxds/zy-ui
-
-# 3. 打开页面确认：控制台无报错，改动的样式 / 行为已生效
-```
-
 几条注意：
 
-- `file:` 依赖是软链，`node_modules/@gyyxds/zy-ui` 指向本仓库根目录；本仓库 `rm -rf dist` 后业务项目会立刻报「找不到入口」，重建就好。
-- 业务项目的 dev server 会缓存 `node_modules/.vite`：重建后没变化就删掉它、重启 dev（`rm -rf node_modules/.vite`）。
+- `file:` 依赖是软链，`node_modules/@gyyxds/zy-ui` 指向本仓库根目录；本仓库删掉 `dist` 后业务项目会立刻报「找不到入口」，重建就好。
+- 业务项目的 dev server 会缓存 `node_modules/.vite`：重建后没变化就删掉它、重启 dev。
 - 单页调试用 `npm run dev`（文档站）最快；`file:` 链路是给「在自己的业务页面里验证」用的。
 - 样式三件套别漏：Element 样式 → `@gyyxds/zy-ui/style.css` → 一份主题 CSS（`theme/basic.css` 或 `theme/solid.css`）。
 
-
-### 6. 收录新内容
+### 6. 新增 / 更新内容
 
 **新组件**
 
 1. 实现放 `src/zy/<Name>/`（含 `index.ts`），并在 `src/zy/index.ts` 追加导出
-2. 组件文档条目写进 `src/mocks/element-components.ts`
-3. 首页计数同步 `src/mocks/components.ts` 的 `COMPONENT_TOTAL`
+2. 文档条目写进 `src/mocks/element-components.ts`（描述、完整 SFC、API 属性表；成族组件共用一页时给 `count`）
+3. 同步 `src/mocks/components.ts` 的 `COMPONENT_TOTAL` 与 README / AGENTS 的组件数
+4. `npm run check:registry` 会拦住「实现了没注册」「注册了不存在」与漏定义的 `--zy-*` 令牌
 
-**新动效**
+**改设计 / 主题**
 
-1. 在 `src/mocks/types.ts` 的 `EFFECT_KEYS` 追加 key
-2. 建 `src/effects/<key>/{snippet.html,snippet.css,meta.ts}`（目录名必须与 key 一致）
-3. `npm run sync:scoped` 生成站内用的 scoped 样式
-4. 在 `src/mocks/families.ts` 的 `effectFamilies` 追加一条
+1. 色板与文案改 `src/mocks/theme-design.ts`（首页与四张展示板共用这一份）
+2. 令牌改 `src/zy/styles/tokens/`，材质改 `src/zy/styles/themes/`
+3. 同步 `docs/theme/README.md` 的推导与数值，跑 `node docs/theme/tools/contrast.mjs`
+4. 视觉有变化时先人工确认，再 `npm run check:visual:update`
 
 ## 发布到 npm
 
 包名 `@gyyxds/zy-ui`，发布地址固定 `https://registry.npmjs.org/`（`publishConfig` 已配 `access: public` + `registry`）。发布账号 **gyy-xds**（@gyyxds 组织），已开启 2FA。
 
 ```bash
-# 1. 打包（前置自动跑 registry / snippets 校验 → vue-tsc → vite lib 构建 → check:package）
+# 1. 打包（前置自动跑 registry 校验 → vue-tsc → vite lib 构建 → check:package）
 npm run build:lib
 
 # 2. 登录 npm（须为 gyy-xds 或 @gyyxds 组织成员；浏览器完成认证）
@@ -343,27 +367,29 @@ src/zy/                    # 组件库源码（只有这部分会进发布产物
 │   └── themes/            # basic.css（图纸）/ solid.css（键帽）/ material.css
 └── index.ts               # 库入口：导出 + install
 
-src/effects/<key>/         # 动效片段（复制即用，不发布）
-src/views/                 # 文档站页面（组件页 / 动效页 / 主题页 / 首页）
-src/components/            # 文档站自身组件（布局、舞台、代码面板）
-src/mocks/                 # 文档数据：组件元信息、动效注册表、演示代码
-src/stores/                # Pinia：主题、收藏
-scripts/                   # 校验与构建脚本（registry / snippets / package / consumer …）
+src/views/                 # 文档站页面：首页（设计方案）/ 组件页 / 主题页 / 关于
+src/components/            # 站点自身组件（布局、舞台、代码面板、UI 小件）
+src/mocks/                 # 站点数据：组件元信息、设计方案、关于页内容
+src/stores/                # Pinia：主题（材质 + 光照）
+src/assets/styles/         # 站点外壳令牌与动效（不影响组件库）
+scripts/                   # 校验与构建脚本（registry / package / consumer / theme-runtime / visual）
 tests/                     # Vitest 单测 + 视觉回归基线
-docs/                      # 设计规范、迁移与发布文档
-
-dist/site/                 # 站点产物（npm run build）
-dist/zy-ui/                # 库产物（npm run build:lib，进包）
+docs/theme/                # 设计规范：两套语言、两档光照、四张展示板、对比度工具
 ```
 
 ## 浏览器支持
 
 现代浏览器。样式用到 `color-mix()`、`:has()`、嵌套与 CSS 自定义属性，旧 WebView / IE 需先评估降级方案，详见 [浏览器支持](docs/browser-support.md)。
 
+## 许可
+
+MIT © 2026 @gyyxds/zy-ui contributors。可自由用于个人与商业项目，保留版权与许可声明即可分发；完整文本见 [LICENSE](LICENSE)。
+
 ## 团队协作
 
 - [贡献规范](CONTRIBUTING.md)
-- [主题规范](docs/theme/README.md)
+- [主题设计规范](docs/theme/README.md)
+- [两档光照推导](docs/theme/dark-mode-design.md)
 - [从 Element Plus 迁移](docs/migration-from-element.md)
 - [改造规范与进度](docs/ui-library-refactor-spec.md)
 - [发布检查清单](docs/release-checklist.md)

package/dist/zy-ui/index.d.ts

@@ -677,10 +677,14 @@ export declare const components: {
         new (...args: any[]): import("vue").CreateComponentPublicInstanceWithMixins<Readonly<{
             items?: import("./mega-menu").MegaMenuItem[];
             open?: string | null;
+            active?: string | null;
+            activeLink?: string | null;
             label?: string;
             brand?: import("./mega-menu").MegaMenuBrand | null;
         }> & Readonly<{
             "onUpdate:open"?: ((value: string | null) => any) | undefined;
+            "onUpdate:active"?: ((value: string | null) => any) | undefined;
+            "onUpdate:activeLink"?: ((value: string | null) => any) | undefined;
             onNavigate?: ((payload: {
                 item: import("./mega-menu").MegaMenuItem;
                 title: string;
@@ -689,6 +693,8 @@ export declare const components: {
             }) => any) | undefined;
         }>, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
             "update:open": (value: string | null) => any;
+            "update:active": (value: string | null) => any;
+            "update:activeLink": (value: string | null) => any;
             navigate: (payload: {
                 item: import("./mega-menu").MegaMenuItem;
                 title: string;
@@ -709,10 +715,14 @@ export declare const components: {
         }, Readonly<{
             items?: import("./mega-menu").MegaMenuItem[];
             open?: string | null;
+            active?: string | null;
+            activeLink?: string | null;
             label?: string;
             brand?: import("./mega-menu").MegaMenuBrand | null;
         }> & Readonly<{
             "onUpdate:open"?: ((value: string | null) => any) | undefined;
+            "onUpdate:active"?: ((value: string | null) => any) | undefined;
+            "onUpdate:activeLink"?: ((value: string | null) => any) | undefined;
             onNavigate?: ((payload: {
                 item: import("./mega-menu").MegaMenuItem;
                 title: string;
@@ -730,10 +740,14 @@ export declare const components: {
     } & import("vue").ComponentOptionsBase<Readonly<{
         items?: import("./mega-menu").MegaMenuItem[];
         open?: string | null;
+        active?: string | null;
+        activeLink?: string | null;
         label?: string;
         brand?: import("./mega-menu").MegaMenuBrand | null;
     }> & Readonly<{
         "onUpdate:open"?: ((value: string | null) => any) | undefined;
+        "onUpdate:active"?: ((value: string | null) => any) | undefined;
+        "onUpdate:activeLink"?: ((value: string | null) => any) | undefined;
         onNavigate?: ((payload: {
             item: import("./mega-menu").MegaMenuItem;
             title: string;
@@ -742,6 +756,8 @@ export declare const components: {
         }) => any) | undefined;
     }>, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
         "update:open": (value: string | null) => any;
+        "update:active": (value: string | null) => any;
+        "update:activeLink": (value: string | null) => any;
         navigate: (payload: {
             item: import("./mega-menu").MegaMenuItem;
             title: string;

package/dist/zy-ui/mega-menu/ZyMegaMenu.vue.d.ts

@@ -4,6 +4,10 @@ type __VLS_Props = {
     items?: MegaMenuItem[];
     /** 受控展开项（v-model:open）；不传则自己管 */
     open?: string | null;
+    /** 当前选中的一级项 key：选中态常亮，不随面板开合消失；不传则点了自己记 */
+    active?: string | null;
+    /** 当前选中的二级链接标题（同一面板内唯一）；不传则点了自己记 */
+    activeLink?: string | null;
     /** 导航区的无障碍名称 */
     label?: string;
     /** 左侧品牌区（也可以整块用 #brand 插槽接管） */
@@ -21,6 +25,8 @@ type __VLS_Slots = {} & {
 };
 declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     "update:open": (value: string | null) => any;
+    "update:active": (value: string | null) => any;
+    "update:activeLink": (value: string | null) => any;
     navigate: (payload: {
         item: MegaMenuItem;
         title: string;
@@ -29,6 +35,8 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {},
     }) => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
     "onUpdate:open"?: ((value: string | null) => any) | undefined;
+    "onUpdate:active"?: ((value: string | null) => any) | undefined;
+    "onUpdate:activeLink"?: ((value: string | null) => any) | undefined;
     onNavigate?: ((payload: {
         item: MegaMenuItem;
         title: string;