@gyyxds/zy-ui 0.0.1 → 0.0.2

package/README.md

@@ -1,162 +1,371 @@
-# MotionVault / @zy/zy-ui
-
-组件库 + 动效片段库：同一个仓库，两套产物、两套规矩。
-
-> 当前状态：**28 个可发布组件**、**57 个动效片段**。
-
-## 两个东西，别混
-
-| | 组件（`src/zy/`） | 动效（`src/effects/<key>/`） |
-|--|--|--|
-| 是什么 | 有 props / 事件 / 插槽的 Vue 组件 | 一段可直接复制的 HTML + CSS（+ 可选原生 JS） |
-| 怎么用 | `npm i @zy/zy-ui` 后 `import` | 动效页复制三栏 |
-| 运行时依赖 | vue、element-plus | 零依赖 |
-| 发布 | 进 lib 构建 | 不进任何构建产物 |
-
-判断标准一句话：**要 API 就是「组件」，要粘贴就是「动效」。**
-
-## 文档站
-
-```bash
-npm install
-npm run dev        # 顶栏「组件 / 动效」
-```
-
-- `/components/:id` — 组件页：左树右文 + API 属性表
-- `/animations/:id` — 动效页：左舞台（底色两档可切）+ 右仿 VS Code 只读代码面板（HTML / CSS / JS 分栏），复制即用
-
-## 组件：装到业务项目里
-
-组件是 Element Plus 的二次封装（内部直接用 `El*`），所以 `element-plus` 与 `vue` 都是 peerDependency：
-
-```bash
-npm i @zy/zy-ui element-plus
-```
-
-```ts
-// main.ts：Element 的样式 + 本包的组件样式 + 主题材质
-import 'element-plus/dist/index.css'
-import '@zy/zy-ui/style.css'
-import '@zy/zy-ui/theme/solid.css' // 浅色默认；需要图纸语言时改用 theme/basic.css
-```
-
-主题与明暗是两根独立的轴。在 `<html>` 上设置：
-
-```html
-<html data-zy-theme="solid" data-zy-color-scheme="light">
-```
-
-- `data-zy-theme`：`basic`（基础用法 / 图纸）或 `solid`（实色键帽）。
-- `data-zy-color-scheme`：`light` 或 `dark`。
-- 浅色默认 `solid`；深色当前统一使用 `basic` 形态，不叠加键帽材质。
-- 两个主题 CSS 可以同时引入，由根属性决定生效范围。
-
-主题 CSS 的路径：
-
-```ts
-import '@zy/zy-ui/theme/basic.css'
-import '@zy/zy-ui/theme/solid.css'
-```
-
-**全局引入**（和 Element 一样 `app.use`）：
-
-```ts
-import ZyUi from '@zy/zy-ui'
-
-app.use(ZyUi) // 之后模板里可直接写 <ZyButton /> <ZyInput /> …
-```
-
-**按需引入**（只有被引用的组件进包；组件内部自己 import 对应的 Element 组件，不需要先全局注册 Element）：
-
-```vue
-<script setup lang="ts">
-import { ZyButton, ZyInput } from '@zy/zy-ui'
-</script>
-
-<template>
-  <ZyButton type="primary">提交</ZyButton>
-  <ZyInput v-model="keyword" placeholder="Type something..." />
-</template>
-```
-
-用法与 Element 保持一致：`type` / `size` / `round` / `disabled` / `loading`、`v-model`、事件都照 Element 的写法；
-每个组件另外带一组 `effect` 用来选微动效（`ZyButton` 的 `press` / `outline`，`ZyInput` 的 `underline` / `gradient` …）。
-没有显式声明的 Element props 与事件会沿 Vue 的 attribute 透传，落到内部的 `El*` 上。
-具名插槽同样原样转发（`<ZyButton><template #icon>…</template></ZyButton>` 会落到 `ElButton` 的 `#icon`），
-默认插槽由各组件自己安排位置。
-
-换肤：本包自带一份 `:root` 设计令牌（`--zy-brand`、`--zy-radius-pill`、`--zy-ease-out` …），
-在自己的样式里覆盖同名变量即可；深色模式同理。Token 分为原始值、语义值、Element 映射和深色覆盖四层，
-业务侧应优先覆盖语义令牌，不要依赖组件内部 `.el-*` 子结构。
-
-`src/zy/index.ts` 导出的 28 个组件：`ZyBadge`、`ZyButton`、`ZyCodeInput`、`ZyDatePicker`、`ZyInput`、
-`ZySelect`、`ZyCheckbox`、`ZyCheckboxGroup`、`ZySwitch`、`ZyRadio`、`ZyRadioGroup`、
-`ZyRadioButton`、`ZyCard`、`ZyTag`、`ZyProgress`、`ZyAlert`、`ZyDialog`、`ZyDivider`、
-`ZySpace`、`ZyIcon`、`ZyTable`、`ZyTree`、`ZyLoading`、`ZyMegaMenu`、`ZyPagination`、`ZyPanel`、`ZySlideVerify`、`ZyTimePicker`。
-
-## 动效：复制片段
-
-每个动效一个目录，三件套 + 一份配置：
-
-```
-src/effects/switch-burst/
-  snippet.html         纯标记（无 Vue 语法）
-  snippet.css          自包含样式（每个 var() 都带字面量兜底）
-  snippet.scoped.css   站内渲染用：选择器都带 .zy-stage-<key> 前缀（由 css 派生，别手改）
-  snippet.js           可选；确实需要脚本时才有（当前 57 个都是零 JS），站点预览会执行它
-  meta.ts              舞台与文档配置：scale / checker / doc
-```
-
-复制出去为什么能直接用：`var(--fx-x, 兜底)` 保留兜底值、片段自带 `box-sizing` 兜底、
-`<span />` 这类只对 Vue 模板块成立的写法已经补成标准 HTML。
-
-## 收录新内容
-
-**新动效**
-
-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/zy/<Name>/`（含 `index.ts`），并在 `src/zy/index.ts` 追加导出
-2. 组件文档条目在 `src/mocks/element-components.ts`
-3. 首页那句组件计数跟着改 `src/mocks/components.ts` 的 `COMPONENT_TOTAL`
-
-## 脚本
-
-| 命令 | 作用 |
-|--|--|
-| `npm run dev` | 文档站（前置跑两项校验） |
-| `npm run build` | 构建站点 → `dist/site/` |
-| `npm run build:lib` | 构建可发布库 → `dist/zy-ui/`（只含 28 个组件） |
-| `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 lint` | 检查组件、主题状态、脚本与单测代码 |
-| `npm run test` | 运行 Vitest 单元测试 |
-| `npm run check:theme-runtime` | 校验 basic / solid / 深色回退的运行时表现（需先启动站点） |
-| `npm run check:visual` | 核心组件的默认 / hover / active / focus / disabled 视觉回归（需先启动站点） |
-| `npm run check:visual:update` | 审核通过后更新视觉基线 |
-| `npm run changeset` | 记录一次待发布变更 |
-| `npm run release` | 构建并发布到已配置的 registry |
-| `npm run sync:scoped` | 由 `snippet.css` 生成 `snippet.scoped.css` |
-
-`dev` / `build` / `build:lib` 都已前置跑 `check:registry` 与 `check:snippets`。
-站点与 lib 的产物分开放（`dist/site` 与 `dist/zy-ui`），互不覆盖。
-
-## 技术栈
-
-Vite + Vue 3 + TypeScript · Vue Router · Pinia · Element Plus
-
-## 团队协作
-
-- [贡献规范](CONTRIBUTING.md)
-- [浏览器支持](docs/browser-support.md)
-- [从 Element Plus 迁移](docs/migration-from-element.md)
-- [改造规范与进度](docs/ui-library-refactor-spec.md)
-- [发布检查清单](docs/release-checklist.md)
-- [组件 Owner 约定](docs/component-ownership.md)
+# Zy UI 组件库 · MotionVault
+
+基于 **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/badge/ZyBadge.vue.d.ts

@@ -14,14 +14,14 @@ type __VLS_Props = {
     /** 微动效：'' 基础（等宽数字，9 → 10 宽度不跳）/ ping 角标后补一圈同色扩散圈，放大淡出 */
     effect?: '' | 'ping';
 };
-declare var __VLS_7: {};
+declare var __VLS_8: {};
 type __VLS_Slots = {} & {
-    default?: (props: typeof __VLS_7) => any;
+    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: "success" | "warning" | "info" | "primary" | "danger";
+    type: "primary" | "success" | "warning" | "info" | "danger";
     effect: "" | "ping";
-    value: string | number;
+    value: number | string;
     max: number;
     isDot: boolean;
     hidden: boolean;

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

@@ -8,9 +8,9 @@ export declare const ZyBadge: import("../utils/withInstall").SFCWithInstall<{
         showZero?: boolean;
         effect?: "" | "ping";
     }> & Readonly<{}>, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, import("vue").PublicProps, {
-        type: "success" | "warning" | "info" | "primary" | "danger";
+        type: "primary" | "success" | "warning" | "info" | "danger";
         effect: "" | "ping";
-        value: string | number;
+        value: number | string;
         max: number;
         isDot: boolean;
         hidden: boolean;
@@ -31,9 +31,9 @@ export declare const ZyBadge: import("../utils/withInstall").SFCWithInstall<{
         showZero?: boolean;
         effect?: "" | "ping";
     }> & Readonly<{}>, {}, {}, {}, {}, {
-        type: "success" | "warning" | "info" | "primary" | "danger";
+        type: "primary" | "success" | "warning" | "info" | "danger";
         effect: "" | "ping";
-        value: string | number;
+        value: number | string;
         max: number;
         isDot: boolean;
         hidden: boolean;
@@ -51,9 +51,9 @@ export declare const ZyBadge: import("../utils/withInstall").SFCWithInstall<{
     showZero?: boolean;
     effect?: "" | "ping";
 }> & Readonly<{}>, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, {
-    type: "success" | "warning" | "info" | "primary" | "danger";
+    type: "primary" | "success" | "warning" | "info" | "danger";
     effect: "" | "ping";
-    value: string | number;
+    value: number | string;
     max: number;
     isDot: boolean;
     hidden: boolean;

package/dist/zy-ui/button/ZyButton.vue.d.ts

@@ -27,9 +27,9 @@ type __VLS_Slots = {} & {
     default?: (props: typeof __VLS_29) => any;
 };
 declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
-    size: "default" | "small" | "large";
-    type: "" | "success" | "warning" | "info" | "primary" | "danger";
-    effect: "fill" | "press" | "sweep";
+    size: "large" | "default" | "small";
+    type: "primary" | "success" | "warning" | "danger" | "info" | "";
+    effect: "press" | "sweep" | "fill";
     icon: string | Component;
     round: boolean;
     disabled: boolean;