@gyyxds/zy-ui 0.0.0-stage → 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## Unreleased
+
+- `ZyMegaMenu` 面板里的二级菜单在没有 `desc`（描述行）时，图标与名称改为垂直居中，行高由 56.5 收到 36（图标 30 → 24、上内距 9 → 6）；有描述时排版不变。
+- `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` 对齐。
+- `ZyInput` / `ZySelect` 的 `raised`（键帽凸起形态）补上组件页舞台：实色主题下多一节「键帽凸起」，输入框与选择器各两颗（可输入 / 可清空、单选 / 可搜索），文案与代码片段齐全；图纸主题不出现（`raised` 在 A 里是空操作）。样式与展示板 `is-raised` 逐值一致（白键面 + `0 4px 0` 底座 + 落地影 + 两侧白弧），深色档同形不同光。
+- 修复键帽主题（`solid`）复选框**未勾选**时方框看不见：原先只把描边设为透明、再补一道白色顶光，白色键面落在白卡片上就整颗消失。现在未选态是**空槽**（`--zy-slot-face` 槽底 + `--zy-slot-shadow-sm` 内阴影 + `--zy-slot-line` 描边），与单选框、输入框同一个坑；深色档同样成立。`checkmark` / `tick` 两个变体不受影响。展示板复选框补了「未选」样本。
+- **新增 `ZyMegaMenu`（导航 + 大面板）**：`items` 数据驱动，面板支持 `grid` / `list` / `groups` 三种布局，也可用 `#panel-<key>` 整块接管；`v-model:open` 受控开合；键盘可达（↓ 进面板、Escape 关闭并把焦点还给触发器）；`#brand` / `#actions` 插槽。没有对应的 Element 组件，属自研件。组件数 27 → 28。
+- 深色色板换成方案稿那一套：`tokens/dark.css` 收成**两套材质共用的深色板**（品牌字 `#5aa6e4` / 键面 `#2876af`、储能、危险、警示、信息、焦点环、Element `--el-color-*` 桥接），`theme/basic.css` 增 §0.1「图纸 · 夜」（中性石墨纸 `#0f1014` / 纸片 `#1b1d23`、发丝线与控件线分档、表格栏头、实心按钮深档渐变），`theme/solid.css` 只留键帽的材质值。深色下 A 的实心按钮白字 2.78 → 4.88、角标 2.65 → 5.19、实心标签 2.0–2.7 → 4.86–5.19。
+- `ZyButton` 的 `effect="fill"`（实色键帽 / 悬停扩散）改为**只在键帽主题成立**：图纸主题下不渲染键帽层，`effect="fill"` 自动按 `press` 渲染；标题栏 / 舞台 / 参数表同步标注「仅键帽主题」，组件页在图纸主题下不再出现「实色按钮」舞台。
+- 移除 `ZyButton` 的 `effect="outline"`（描边展开）与 `hoverLabel` prop：悬停即把文案换成「已展开 / 已删除」，在点击发生前就宣告结果，对危险操作是错误的状态承诺；描边语义已由 `plain` / `dashed` 承担，按压与图标动效由 `press` / `sweep` 承担。`effect` 现为 `'press' | 'sweep' | 'fill'`。
+- 同步移除组件页「描边按钮」舞台、`button:outline` 片段、`solid` 主题里的 `.is-outline` 选择器与相关文档说明。
+
+## 0.1.0
+
+- 建立 Element Plus 二次封装组件库基础。
+- 新增 `basic` / `solid` 两套主题入口与 `data-zy-theme` 主题契约。
+- 新增 `ZyPagination`、`ZyPanel`、`ZyDatePicker`、`ZyTimePicker`。
+- 新增实验性 `ZySlideVerify`。
+- 增加发布产物、真实消费方、主题运行时和视觉回归检查。

package/CONTRIBUTING.md

@@ -0,0 +1,102 @@
+# Zy UI 贡献规范
+
+## 先判断产物类型
+
+- 有 props / events / slots，供业务项目 `import`：组件。
+- 一段可复制的 HTML / CSS（可选原生 JS）：动效片段。
+- 两者不能互相冒充。新增内容前先确认归属。
+
+组件库改造规范见 [docs/ui-library-refactor-spec.md](docs/ui-library-refactor-spec.md)。
+
+## 本地开发
+
+```bash
+npm ci
+npm run dev
+```
+
+文档站默认运行在 Vite 输出地址。组件实现放在 `src/zy/<name>/`，每个组件目录必须有：
+
+- `Zy<Name>.vue`
+- `index.ts`
+- 需要样式资产时放在同目录
+
+## 新增或修改组件
+
+提交前至少完成：
+
+1. 组件实现与入口。
+2. `src/zy/index.ts` 导出与全局注册。
+3. `src/mocks/element-demos.ts` 演示。
+4. `src/mocks/element-components.ts` API 文档。
+5. 两套主题下的状态检查。
+6. 键盘、禁用、加载、错误、弹层等适用状态。
+7. 视觉基线更新并经过人工审核。
+8. README / 规范中的组件数量和说明同步。
+
+## 主题约束
+
+- 主题属性：`html[data-zy-theme="basic|solid"]`。
+- 明暗属性：`html[data-zy-color-scheme="light|dark"]`。
+- 组件优先消费 `--zy-*` 语义令牌。
+- 主题层不得引用展示板专用类名或站点专属变量。
+- 不得依赖组件内部 `.el-*` 子结构作为公共 API。
+- 深色当前统一回退 `basic`，不要在深色中单独叠加 `solid` 材质。
+
+## 提交前验证
+
+```bash
+npm run check:registry
+npm run check:snippets
+npm run lint
+npm run test
+npm run build
+npm run build:lib
+npm run check:consumer
+```
+
+主题运行时与视觉回归需要先启动站点：
+
+```bash
+npm run preview -- --port 4173
+npm run check:theme-runtime
+npm run check:visual
+```
+
+只有确认视觉变化符合设计后，才允许执行：
+
+```bash
+npm run check:visual:update
+```
+
+## 版本与发布
+
+- 使用 Changesets 描述变更。
+- patch：样式或类型修复。
+- minor：向后兼容的新组件 / 新能力。
+- major：删除或改变公共 API、主题默认值、组件 DOM 契约。
+- `prepublishOnly` 会重新构建并校验发布产物。
+
+```bash
+npm run changeset
+npm run version
+npm run release
+```
+
+`npm run release` 先跑 `node scripts/check-release-env.mjs`（registry / 登录 / 版本是否已发 / 有无待发 changeset），体检不过直接退，不会再白跑一遍构建。
+
+
+发布前必须确认：
+
+- 包 scope 与私有 registry 已配置。
+- 当前账号不是唯一发布人。
+- CHANGELOG 和迁移说明完整。
+- `npm pack` 产物可由非作者安装。
+
+## 组件 RFC
+
+大型组件或破坏性改动先提交 RFC。模板位于 `.gitlab/issue_templates/component-rfc.md`。
+
+## 浏览器支持
+
+见 [docs/browser-support.md](docs/browser-support.md)。如业务需要旧 WebView，必须先评估 `color-mix()`、`:has()` 与 CSS 自定义属性的降级。

package/README.md

@@ -1,3 +1,371 @@
-# Temporary Holding Version
+# Zy UI 组件库 · MotionVault
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+基于 **Vue 3 + TypeScript + Vite** 的 Element Plus 二次封装组件库，配套一套**可直接复制粘贴**的动效片段与文档站。组件带 props / 事件 / 插槽并随包发布；动效片段只在文档站复制使用，不进包。
+
+| 属性 | 说明 |
+| --- | --- |
+| 包名 | `@gyyxds/zy-ui` |
+| 技术栈 | Vue 3、TypeScript、Element Plus |
+| 构建工具 | Vite 8（库模式）+ vue-tsc |
+| 模块格式 | 仅 ESM（`"type": "module"`），无 CJS 产物 |
+| 组件数 | 28 |
+| 动效片段 | 57（零依赖、零 JS） |
+
+## 先说清楚：两套产物，别混
+
+> **动效页（`/animations/:id`）里的 HTML / CSS 是「即时复制粘贴」用的片段，不属于发布的组件库。**
+> 它们没有 npm 导出路径、不进 `dist/zy-ui`、也不能 `import`；正确用法是在文档站复制三栏代码，粘到自己页面里跑。
+
+| | 组件库（`src/zy/`） | 动效片段（`src/effects/<key>/`） |
+| --- | --- | --- |
+| 是什么 | 有 props / 事件 / 插槽的 Vue 组件 | 可直接复制的 HTML + CSS（可选原生 JS） |
+| 怎么用 | `npm i @gyyxds/zy-ui` 后 `import` | 文档站动效页复制三栏代码，粘贴即用 |
+| 运行时依赖 | vue、element-plus（均为 peerDependency） | 零依赖 |
+| 是否发布 | 进 lib 构建（`dist/zy-ui/`） | 不进任何构建产物 |
+
+判断标准一句话：**要 API 就是「组件」，要粘贴就是「动效」。**
+
+## 功能特性
+
+- 28 个组件，全部是 Element Plus 的二次封装或同构重绘，`type` / `size` / `v-model` / 事件写法与 Element 保持一致
+- 多个组件带一组 `effect` 微动效：按钮 `press` / `sweep` / `fill`，输入框 `underline` / `gradient` / `brutalist`，选择器 `underline` / `gradient` …
+- 两套材质主题 × 深浅两档，四组配色互不回退：图纸（`basic`）与实色键帽（`solid`）
+- 设计令牌随包发布（`--zy-*`），覆盖语义令牌即可换肤，无需改组件代码
+- TypeScript 类型声明随包发布；ESLint 0 警告门槛、Vitest 单测、消费方冒烟检查
+- 57 个零依赖动效片段，复制即用（见上文说明，不属于包内容）
+
+## 组件列表（28 个）
+
+### 基础（3）
+
+| 组件 | 说明 |
+| --- | --- |
+| `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` |
+
+### 表单（12）
+
+| 组件 | 说明 |
+| --- | --- |
+| `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` 与各档文案；事件：成功 / 失败 / 刷新 |
+| `ZyDatePicker` / `ZyTimePicker` | 触发框与弹层形态重绘，API 照 Element |
+
+### 数据（7）
+
+| 组件 | 说明 |
+| --- | --- |
+| `ZyCard` | `shadow`（always / hover / never）、`hoverFill`（悬停铺色，可传颜色） |
+| `ZyTag` | `effect`：`dark` / `light`（默认）/ `plain` / `fill`（实色键帽，仅键帽主题；图纸下退回浅底，可关闭时关闭图标跟字色） |
+| `ZyBadge` | 等宽数字不跳宽；`effect`：`''` / `ping`（扩散圈） |
+| `ZyProgress` | 轨道 + 蓝绿渐变填充 |
+| `ZyTable` | 台账式表格，`lines`（all / row）控制网格线；数据与列走插槽 / Element 透传 |
+| `ZyTree` | 引导线 + 折角接线 + 写实节点图标；`folderIcon` / `folderOpenIcon` / `fileIcon` |
+| `ZyPagination` | 纸面按钮 / 中性键帽页码 + 跳页输入框 |
+
+### 反馈（2）
+
+| 组件 | 说明 |
+| --- | --- |
+| `ZyAlert` | 左侧 3px 语义强调条 / 语义键块，标题留语义色 |
+| `ZyDialog` | `v-model` 开合；`title` / `width` / `icon` / `appendToBody` / `closeOnClickModal`（默认 false）/ `destroyOnClose` |
+
+### 布局（4）
+
+| 组件 | 说明 |
+| --- | --- |
+| `ZyDivider` | `contentPosition`：left / center / right |
+| `ZySpace` | 纯布局件，`direction` 等间距控制 |
+| `ZyPanel` | 通用容器：有 `title` 分标题栏 + 正文，无 `title` 通体白面 |
+| `ZyMegaMenu` | 数据驱动导航：`items`（有 `panel` = 下拉，无 `panel` + `href` = 普通链接）、`brand`；受控开合 `v-model:open`；`#panel-<key>` 接管面板内容 |
+
+## 动效片段（57 个，复制即用，不发布）
+
+- 分类（`src/mocks/families.ts`）：基础 / 按钮 / 表单 / 数据 / 反馈 / 导航 / 布局 / 动效。
+- 每个片段一个目录，三件套 + 一份配置：
+
+```
+src/effects/switch-burst/
+  snippet.html         纯标记，无 Vue 语法
+  snippet.css          自包含样式，每个 var() 都带字面量兜底
+  snippet.scoped.css   站内渲染用（由 snippet.css 派生，别手改）
+  snippet.js           可选；确实需要脚本时才有（当前 57 个全部零 JS）
+  meta.ts              舞台与文档配置：scale / doc（棋盘底等可选字段）
+```
+
+- 复制出去能直接用：`var(--fx-x, 兜底)` 保留兜底值、片段自带 `box-sizing` 兜底、`<span />` 这类只对 Vue 模板块成立的写法已补成标准 HTML。
+- 片段与主题解耦（令牌走 `--fx-*`），所以在文档站切换主题不会改变动效页的观感。
+
+## 安装使用
+
+```bash
+npm i @gyyxds/zy-ui element-plus
+```
+
+`vue` 与 `element-plus` 是 peerDependency，需由业务项目自己安装；组件内部直接使用 `El*`，**不需要**先全局注册 Element Plus。
+
+```ts
+// main.ts —— 顺序：Element 样式 → 本包组件样式 → 主题材质
+import { createApp } from 'vue'
+import ElementPlus from 'element-plus'
+import 'element-plus/dist/index.css'
+import '@gyyxds/zy-ui/style.css'
+import '@gyyxds/zy-ui/theme/solid.css' // 浅色默认；要图纸语言改用 theme/basic.css
+
+import App from './App.vue'
+
+createApp(App).use(ElementPlus).mount('#app')
+```
+
+导出路径（对应 `package.json` 的 `exports`）：
+
+| 路径 | 内容 |
+| --- | --- |
+| `@gyyxds/zy-ui` | 组件库入口（全局 install + 全部具名导出） |
+| `@gyyxds/zy-ui/style.css` | 组件样式 + 设计令牌（`dist/zy-ui/zy-ui.css`） |
+| `@gyyxds/zy-ui/theme/basic.css` | 主题 A「基础用法 / 图纸」材质层 |
+| `@gyyxds/zy-ui/theme/solid.css` | 主题 B「实色键帽」材质层 |
+
+三种引入方式：
+
+```ts
+// ① 全局注册
+import ZyUi from '@gyyxds/zy-ui'
+app.use(ZyUi) // 之后模板里直接写 <ZyButton /> <ZyInput /> …
+
+// ② 按需引入（推荐，tree-shaking 生效，只打进用到的组件）
+import { ZyButton, ZyInput } from '@gyyxds/zy-ui'
+
+// ③ 单组件注册（组件自带 install，对齐 Element 的做法）
+import { ZyButton } from '@gyyxds/zy-ui'
+app.use(ZyButton)
+```
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { ZyButton, ZyInput } from '@gyyxds/zy-ui'
+
+const keyword = ref('')
+</script>
+
+<template>
+  <ZyInput v-model="keyword" placeholder="搜索组件…" clearable />
+  <ZyButton type="primary" effect="press">提交</ZyButton>
+</template>
+```
+
+使用约定：
+
+- 未显式声明的 Element props / 事件按 Vue 的 attribute 透传，落到内部 `El*` 上。
+- 具名插槽原样转发给内部 Element 组件（如 `<ZyButton><template #icon>…</template></ZyButton>`），默认插槽由各组件自己安排位置。
+- 自定义组件（`ZySwitch` / `ZyCodeInput` / `ZyDialog` / `ZyCheckboxGroup` / `ZyRadioGroup`）用 `defineModel`，`v-model` 直接可用；`ZySlideVerify` 走事件。
+- 图标属性传字符串时按本库内置图标名解析（`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;
+}
+```
+
+常用令牌：`--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`（只在该主题下定义）。
+
+## 本地调试
+
+### 1. 安装依赖
+
+```bash
+npm install
+# 或 yarn install --ignore-engines（@changesets/cli 要求 yarn ≥ 4.5，本机 yarn 1.x 需跳过引擎检查）
+```
+
+Node.js 需 ≥ 20.19（Vite 8 要求）。
+
+### 2. 启动开发服务
+
+```bash
+npm run dev
+```
+
+该命令会先跑 `check:registry` 与 `check:snippets` 两项校验，再启动 Vite（默认端口 **5173**，`host: true` 便于局域网访问）。
+
+### 3. 访问文档站
+
+浏览器打开 [http://localhost:5173](http://localhost:5173)。
+
+| 路由 | 内容 |
+| --- | --- |
+| `/components/:id` | 组件页：左树右文 + 舞台 + API 属性表 |
+| `/animations/:id` | 动效页：左舞台（底色两档可切）+ 右只读代码面板（HTML / CSS / JS 分栏），复制即用 |
+
+顶栏可切材质（图纸 / 键帽）与深浅；`?theme=dark&zyTheme=basic` 之类的查询参数可固定主题，方便截图与分享。
+
+### 4. 常用命令
+
+| 命令 | 作用 |
+| --- | --- |
+| `npm run dev` | 文档站（前置跑 registry + snippets 校验） |
+| `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: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`），互不覆盖。
+
+### 5. 业务项目直接引用本仓库（`file:` 依赖）
+
+业务项目里写 `"@gyyxds/zy-ui": "file:../motion-vault-components"` 时，**不会**跑本仓库的 `prepare` / `prepublishOnly`，装的就是仓库里现成的 `dist/zy-ui`。所以改了组件后要手动重建一次：
+
+```bash
+# 本仓库：改了 src/zy 之后都要跑一遍（约 30 秒，跑完 lint / 测试再打更稳）
+npm run build:lib
+
+# 业务项目：file: 依赖是软链，重建后产物已经生效，下面这步一般不需要；
+# 只有 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`）。
+- 单页调试用 `npm run dev`（文档站）最快；`file:` 链路是给「在自己的业务页面里验证」用的。
+- 样式三件套别漏：Element 样式 → `@gyyxds/zy-ui/style.css` → 一份主题 CSS（`theme/basic.css` 或 `theme/solid.css`）。
+
+
+### 6. 收录新内容
+
+**新组件**
+
+1. 实现放 `src/zy/<Name>/`（含 `index.ts`），并在 `src/zy/index.ts` 追加导出
+2. 组件文档条目写进 `src/mocks/element-components.ts`
+3. 首页计数同步 `src/mocks/components.ts` 的 `COMPONENT_TOTAL`
+
+**新动效**
+
+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` 追加一条
+
+## 发布到 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）
+npm run build:lib
+
+# 2. 登录 npm（须为 gyy-xds 或 @gyyxds 组织成员；浏览器完成认证）
+npm login --registry=https://registry.npmjs.org/
+
+# 3. 确认当前登录账号
+npm whoami --registry=https://registry.npmjs.org/
+
+# 4. 发布（scoped 包须加 --access public；按提示完成 2FA 验证）
+npm publish --access public --registry=https://registry.npmjs.org/
+```
+
+要点：
+
+- `prepublishOnly` 会在 publish 前自动重跑一遍 `build:lib`；产物已确认最新时可用 `--ignore-scripts` 跳过重复构建。
+- 账号开启 2FA 后，publish 会要求浏览器授权或验证器一次性验证码（EOTP）。
+- 发布后用 `npm view @gyyxds/zy-ui version` 确认上架；新包首次发布后 registry 生效可能有短暂延迟，404 不代表失败。
+- 正式变更走 Changesets：`npm run changeset` → `changeset version` → `npm run release`（`release` 会先跑 `check:release-env` 体检）。
+- 要让业务项目验证发布产物，可先跑 `npm run check:consumer`（`npm pack` → 空项目安装 → 类型检查 → 构建）。
+
+## 目录结构
+
+```
+src/zy/                    # 组件库源码（只有这部分会进发布产物）
+├── button/                # 每个组件一个目录：index.ts 导出 + Zy*.vue 实现
+├── input/ select/ …
+├── styles/
+│   ├── tokens/            # primitives → semantic → element → dark 四层令牌
+│   └── 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 …）
+tests/                     # Vitest 单测 + 视觉回归基线
+docs/                      # 设计规范、迁移与发布文档
+
+dist/site/                 # 站点产物（npm run build）
+dist/zy-ui/                # 库产物（npm run build:lib，进包）
+```
+
+## 浏览器支持
+
+现代浏览器。样式用到 `color-mix()`、`:has()`、嵌套与 CSS 自定义属性，旧 WebView / IE 需先评估降级方案，详见 [浏览器支持](docs/browser-support.md)。
+
+## 团队协作
+
+- [贡献规范](CONTRIBUTING.md)
+- [主题规范](docs/theme/README.md)
+- [从 Element Plus 迁移](docs/migration-from-element.md)
+- [改造规范与进度](docs/ui-library-refactor-spec.md)
+- [发布检查清单](docs/release-checklist.md)
+- [组件 Owner 约定](docs/component-ownership.md)
+- [变更日志](CHANGELOG.md)

package/dist/zy-ui/alert/ZyAlert.vue.d.ts

@@ -0,0 +1,26 @@
+type __VLS_Props = {
+    title?: string;
+    type?: 'success' | 'warning' | 'info' | 'error';
+    description?: string;
+    closable?: boolean;
+    showIcon?: boolean;
+};
+declare var __VLS_10: string, __VLS_11: any;
+type __VLS_Slots = {} & {
+    [K in NonNullable<typeof __VLS_10>]?: (props: typeof __VLS_11) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    title: string;
+    type: "success" | "warning" | "info" | "error";
+    description: string;
+    closable: boolean;
+    showIcon: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

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

@@ -0,0 +1,54 @@
+export declare const ZyAlert: import("../utils/withInstall").SFCWithInstall<{
+    new (...args: any[]): import("vue").CreateComponentPublicInstanceWithMixins<Readonly<{
+        title?: string;
+        type?: "success" | "warning" | "info" | "error";
+        description?: string;
+        closable?: boolean;
+        showIcon?: boolean;
+    }> & Readonly<{}>, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, import("vue").PublicProps, {
+        title: string;
+        type: "success" | "warning" | "info" | "error";
+        description: string;
+        closable: boolean;
+        showIcon: boolean;
+    }, false, {}, {}, import("vue").GlobalComponents, import("vue").GlobalDirectives, string, {}, any, import("vue").ComponentProvideOptions, {
+        P: {};
+        B: {};
+        D: {};
+        C: {};
+        M: {};
+        Defaults: {};
+    }, Readonly<{
+        title?: string;
+        type?: "success" | "warning" | "info" | "error";
+        description?: string;
+        closable?: boolean;
+        showIcon?: boolean;
+    }> & Readonly<{}>, {}, {}, {}, {}, {
+        title: string;
+        type: "success" | "warning" | "info" | "error";
+        description: string;
+        closable: boolean;
+        showIcon: boolean;
+    }>;
+    __isFragment?: never;
+    __isTeleport?: never;
+    __isSuspense?: never;
+} & import("vue").ComponentOptionsBase<Readonly<{
+    title?: string;
+    type?: "success" | "warning" | "info" | "error";
+    description?: string;
+    closable?: boolean;
+    showIcon?: boolean;
+}> & Readonly<{}>, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, {
+    title: string;
+    type: "success" | "warning" | "info" | "error";
+    description: string;
+    closable: boolean;
+    showIcon: boolean;
+}, {}, string, {}, import("vue").GlobalComponents, import("vue").GlobalDirectives, string, import("vue").ComponentProvideOptions> & import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps & (new () => {
+    $slots: {
+        [x: string]: ((props: any) => any) | undefined;
+    };
+})>;
+export default ZyAlert;

package/dist/zy-ui/badge/ZyBadge.vue.d.ts

@@ -0,0 +1,37 @@
+type __VLS_Props = {
+    /** 角标值：数字超过 max 显示 max+，字符串原样显示 */
+    value?: number | string;
+    /** 数字上限，超过显示 max+（只对数字生效） */
+    max?: number;
+    /** 只显示小红点，不显示数字 */
+    isDot?: boolean;
+    /** 隐藏角标 */
+    hidden?: boolean;
+    /** 角标底色语义 */
+    type?: 'primary' | 'success' | 'warning' | 'info' | 'danger';
+    /** value 为 0 时是否显示（对齐 Element，默认显示） */
+    showZero?: boolean;
+    /** 微动效：'' 基础（等宽数字，9 → 10 宽度不跳）/ ping 角标后补一圈同色扩散圈，放大淡出 */
+    effect?: '' | 'ping';
+};
+declare var __VLS_8: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_8) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    type: "primary" | "success" | "warning" | "info" | "danger";
+    effect: "" | "ping";
+    value: number | string;
+    max: number;
+    isDot: boolean;
+    hidden: boolean;
+    showZero: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};