@ptengine/design-components 0.5.3 → 0.6.0

package/COMPONENTS-DESIGN-SYSTEM.md

@@ -0,0 +1,329 @@
+# PT Components Design System — 组件设计规范
+
+> **真值源**：本文件。对外发布的 `llms.txt` 由本文件派生 —— 改这里必须同步它（见文末「本文件的生长规则」）。
+> **怎么装、怎么用、有哪些组件** → [README.md](./README.md)
+> **代码约定与协作流程** → [CLAUDE.md](./CLAUDE.md)
+
+---
+
+## 0 这份文件管什么，不管什么
+
+本库服务**多个产品**，不专属于任何一个。由此得出三条边界：
+
+- **只写「产品无关」的规范** —— 组件的结构、交互状态、可访问性、token 的槽位与语义、
+  尺度刻度。判据是一句话：
+
+  > 把这条规则里的产品名换成另一个产品，还成立吗？
+  > **成立 → 属于本文件；不成立 → 属于那个产品自己的设计文件。**
+
+- **不写任何单一产品的品牌取值与产品级模式** —— 具体品牌色值、品牌渐变、信息架构、
+  页面模板、领域交互，一律归各产品自己的设计文件（如 `apps/x/design.md`）。
+- **依赖单向**：产品的设计文件引用本文件；**本文件不引用、也不受任何产品设计文件约束**。
+  本库仓内不得出现指向某个产品仓文件的规范性引用。
+
+**token 是这条边界的接口**：本库定义槽位存在、它在哪些组件的哪些态上生效；
+产品决定它取什么值。换个产品换一套值就换了皮，本库一行不改。
+
+---
+
+## Token 的硬规矩
+
+- **唯一数据源是 `src/styles/tokens.css`** —— 三层嵌套（③ shadcn 别名 → ② PTEngine
+  语义层 → ① 原语层纯通道三元组）。透明度只在语义层以 `var(--pt-x) / a` 表达，
+  明暗差异只在语义层覆盖。`tailwind.preset.js` 定义 Token → Tailwind 颜色键映射。
+  完整说明见 `tokens.css` 文件头注释。
+- **尺度一律写 px 硬值，不用 `rem`** —— `rem` 会被宿主根字号缩放。本库要挂到不同宿主上，
+  宿主的根字号不受我们控制（apps/x 就是 14px），用 `rem` 会让同一个组件在不同产品里
+  大小不一。圆角、字号、控件高度、间距全部适用。
+- **缺档就加档，不写任意值** —— 需要一个刻度上没有的数，是加档位，不是就地写
+  `rounded-[18px]` / `text-[15px]`。就地写会让每处各写各的数，刻度失效。
+
+---
+
+## 品牌视觉基调
+
+可以概括成「**克制、编辑感、内容优先**」——让整个界面看起来冷静、不吵：
+
+- **近黑文字 + 暖灰中性色为绝对主体**，界面安静、不抢内容。文字灰阶全部由同一个
+  近黑原语（`--pt-black`）配不同透明度得来（strong 90% / standard 70% / weak 40%），
+  面与描边走 neutral 色阶与黑色低透明度叠加。
+- **彩色是稀缺资源、按功能发放，而不是用来装饰**。品牌绿只给 Brand 场景（`bg-brand`）、
+  语义色只表达状态（success / danger / warning / information / AI 角色 Token）、
+  chart 色板只给数据。没有功能含义的地方不出现彩色。
+- **大字号标题 + 充足留白建立层级**，而非靠色块、分隔线与阴影。字阶见下方
+  Typography；Card / 表单控件等根元素无阴影也是同一原则的落地。
+
+新增组件或调整 variant 时先对照这三条：一个改动如果让界面「变吵」了
+（多了一种装饰性颜色、多了一层非浮层阴影、层级靠色块而非字阶），方向就是错的。
+
+---
+
+## 交互状态规范（新组件接入必读）
+
+交互反馈统一走「状态层 State Layer」+ 中性交互 Token，**禁止**沿用 shadcn 官方的
+替换式写法（`hover:bg-primary/90`、`hover:bg-*/80` 等）。拷官方组件进来时按此适配：
+
+| 官方写法 | 本库写法 | 说明 |
+|---|---|---|
+| `hover:bg-primary/90` / `hover:bg-*/80` | 变体类里加 `state-layer` | hover 在原样式上叠加 `--pt-interaction-hover`，active 自动叠加 `--pt-interaction-press`（定义见 `tailwind.preset.js`） |
+| `hover:bg-accent hover:text-accent-foreground`（outline/ghost 等） | `state-layer` | 同上，文字色不再切换 |
+| `focus:bg-accent` / `data-[highlighted]:bg-accent`（菜单项、下拉选项） | **保留原写法** | Radix 键盘高亮机制依赖 focus/highlighted 态；`--accent` 已指向 `--pt-interaction-hover`，效果与叠加一致 |
+| `focus-visible:ring-ring` 等焦点环 | **保留原写法** | `--ring` 已指向 `--pt-interaction-focus`（中性 90%） |
+| 持久「选中 / 激活 / 开」态（`data-[state=selected/on]`、`data-[active=true]`） | 元素底色用 `bg-selected` | `--pt-bg-selected` ＝ 中性 8%，**与 hover 同色**；因为 hover 走 state-layer（叠加层而非替换背景），选中态被悬停时两层叠加 ≈ 16%，天然区分「选中」与「悬停」。**不要用品牌绿等彩色表达选中**（彩色只给 Brand / 语义 / 数据）。前提是该元素的 hover 必须是 state-layer 叠加；若 hover 仍是 `hover:bg-*` 替换式，则改用叠加式，或另加区分（如 sidebar 当前项用 `font-medium`） |
+| 纯文字反馈（link 变体 `hover:underline`） | **保留原写法** | 不加状态层 |
+
+## Button 变体词汇（与 shadcn 官方的差异）
+
+| 本库 variant | 样式 | 对应官方 |
+|---|---|---|
+| `default`（Primary） | 高强调黑，暗色反白，反转状态层 | 官方 default（本库 `--primary` 指向黑） |
+| `brand` | 品牌绿 | 无（本库新增，`bg-brand`） |
+| `secondary` | 描边白底 | 官方 **outline** 的样式 |
+| `tertiary` | 灰底弱强调 | 官方 **secondary** 的样式 |
+
+拷官方组件/示例进来时：`variant="outline"` → `variant="secondary"`；
+官方 `variant="secondary"` 的场景按语义改用 `tertiary`。`--primary` 槽位为黑色，
+品牌绿一律走 `--brand` / `bg-brand`。
+
+想定制某组件观感（配色 / 尺寸 / 圆角），改该组件 cva `variants` 里的类即可全站生效；
+Primary（黑，暗色反白）这类深色表面用 `state-layer-inverse`，其余用 `state-layer`。
+
+百分比只维护在 `src/styles/tokens.css` 语义层（`--pt-interaction-hover/press/focus`），
+调整后组件与 `/tokens` 展示页自动跟随。
+
+---
+
+## 圆角 Radius（六档）
+
+| 类名 | 值 | 用在 |
+|---|---|---|
+| `rounded-sm` | 6px | sm 档控件（24px 高） |
+| `rounded-md` | 8px | default / lg 档控件（32 / 40px 高） |
+| `rounded-lg` | 10px | 卡片、弹窗、浮层 —— 基准档 |
+| `rounded-12` | 12px | 更柔和的面板 |
+| `rounded-16` | 16px | 页面级外壳、对话坞 |
+| `rounded-20` | 20px | 需要强调圆润的大面 |
+
+正圆用 `rounded-full`。可视对照与选档指南见 playground 的 **Radius** 页。
+
+**为什么大档位用 px 命名而不是 `xl` / `2xl`**：Tailwind 默认 `rounded-xl`=12px、
+`rounded-2xl`=16px，与本库需要的 16 / 20 同名不同值。沿用 t 恤码会让从 shadcn / Tailwind
+生态抄来的代码**静默偏移几 px** —— 不报错、不警告，只是看着「有点不对」，极难自查。
+`rounded-12/16/20` 在两边都不存在，不可能撞。
+
+**两种产生方式有意混用**（改值前必读）：
+
+```
+--pt-radius      10px              手写，基准
+--pt-radius-md   calc(基准 − 2px)  派生 → 8px
+--pt-radius-sm   calc(基准 − 4px)  派生 → 6px
+--pt-radius-12   12px              固定，不跟随基准
+--pt-radius-16   16px              固定，不跟随基准
+--pt-radius-20   20px              固定，不跟随基准
+```
+
+派生那套来自 shadcn（一个 `--radius` 旋钮整体缩放，档间恒差 2px）；后加的三档要的是
+「更细的尺子」而不是「可整体缩放的比例」，且基准自建库起从未调过，那个旋钮实际没人用。
+**后果**：真去调基准时，前三档会动、后三档不动 —— 这个分裂是有意的，不是漏改。要统一
+应把前三档也写死，而不是把后三档改成 calc（那会让 `rounded-16` 在基准变化后不再是 16px）。
+
+⚠️ **缺档就加档，不要硬写 `rounded-[18px]` 这类任意值**，否则每个面板各写各的数，刻度失效。
+
+---
+
+## 字体 Typography（中/日/英三语）
+
+品牌字体（源自 Figma `Type/Mode` 的 family 变量）：EN `Inter` / JA `Noto Sans JP` /
+ZH `Noto Sans SC`。库侧在 `tokens.css` 以 `--font-sans` + `:lang()` 声明三语字体栈
+（`'Inter'` 置前，拉丁字符与数字三语统一用 Inter，CJK 落到 JP/SC；各栈带同语言
+系统字体回退），preset 将 `fontFamily.sans` 接到 `var(--font-sans)`。
+组件不声明字体，全部继承。（Figma 中 `family/code` / `family/metric` 亦为 Inter；
+代码展示场景仍保留等宽 `font-mono`，未用 Inter 覆盖。）
+
+**字阶**（preset `fontSize` 整表覆盖，源自 Figma Text Styles，机读存档
+`design/tokens.json`，**在源码仓里、不随 npm 包分发**）：`2xs 12/16 · xs 13/20 · sm 14/20 · base 16/24 · lg 18/28 ·
+xl 20/32 · 2xl 24/36 · 3xl 28/40 · 4xl 32/48 · 5xl 40/56 · 6xl 48/72 · 7xl 56/72 ·
+8xl 64/96 · 9xl 72/128`。与 Tailwind 默认的差异：新增 `2xs`；**`xs` 为 13px**（非 12）；
+`xl` 起行高/字号按设计表。字重五档：light 300 / normal 400 / medium 500 / semibold 600 / bold 700。
+
+**行高按语言可分**：字号三语一致；行高走 `tokens.css` 的 `--lh-*` 变量
+（`:root` ＝ English 基准）。现行策略 ja/zh 沿用 English 值；后续精修时在
+`:lang(ja)` / `:lang(zh)` 预留块中只填与英文不同的档位，全站自动生效，
+组件零改动（机制已验证：同字号、按语言不同行高）。
+
+**消费方应用需要做的三件事：**
+
+1. **正确设置 `<html lang>`**（`en` / `zh-CN` / `ja`，i18n 框架切语言时同步更新）——
+   字体栈按它切换，组件零改动。
+2. **加载字体文件**（库不打包字体）：Next.js 用 `next/font/google`，或 fontsource /
+   `<link>` 引 Google Fonts。加载 300/400/500/600/700 五档字重。
+3. **中国大陆环境自托管 `Noto Sans SC`**（Google Fonts 大陆不可达），并做
+   unicode-range 子集切片（CJK 全量单字重为 MB 级）。
+
+## 组件内建文案的本地化（库不做 i18n，消费方传译文）
+
+个别组件自带可见文案或读屏（sr-only / aria-label）标签。库不引 i18n 框架，
+统一做法是**通过 prop 传入、默认英文**——做多语界面时把译文传进去，不传保持
+英文，对现有代码零影响。
+
+| 组件 | prop | 默认值 |
+|---|---|---|
+| `SearchInput` | `clearLabel` | Clear |
+| `PaginationPrevious` / `PaginationNext` | `label` | Previous / Next |
+| `PaginationEllipsis` / `BreadcrumbEllipsis` | `label` | More pages / More |
+| `DialogContent` / `SheetContent` | `closeLabel` | Close |
+| `CarouselPrevious` / `CarouselNext` | `label` | Previous slide / Next slide |
+| `SidebarTrigger` / `SidebarRail` | `label` | Toggle sidebar |
+| `MessageScrollerButton` | `label` | Scroll to end / Scroll to start |
+| `Spinner` | `label` | Loading |
+
+```tsx
+<PaginationPrevious label={t('上一页')} />
+<DialogContent closeLabel={t('关闭')}>…</DialogContent>
+```
+
+新组件若要内建文案，照此约定加 prop，不要写死字符串。
+
+---
+
+## 组件的行为契约
+
+以下几条约束的是**界面的行为**，不是某个组件的样式。适用范围要说清楚：
+
+> 它们约束的是**用这套设计系统做出来的界面**，而不只是"用到了本库组件的地方"。
+> 消费方手写的界面同样适用 —— 一个自己搭的加载态，和用了 `Spinner` 的加载态，
+> 对用户来说没有区别，规则不该因为实现方式不同而失效。
+
+### 反馈：可点的看得出来，不可点的不要装
+
+可操作元素必须给出明确的交互反馈（hover / focus / active / disabled 四态齐全）；
+**没有实际功能的元素不得产生交互暗示** —— 不给手型光标、不给 hover 变化。
+
+本库的 state-layer 机制是这条的落地手段；这一节写的是它为什么必须做：
+交互暗示是用户判断"这能点吗"的唯一线索。给不能点的东西加暗示等于骗点击；
+能点的东西没有暗示，等于这个功能不存在。
+
+### 异步操作：三个状态一个都不能少
+
+任何触发请求的交互，都要显式设计三态：
+
+| 状态 | 做法 |
+|---|---|
+| 进行中 | 按钮进 loading（同时禁掉重复点击），或区域上 skeleton。**禁止全屏遮罩式 spinner**，除非该操作真的锁死整页 |
+| 成功 | 轻提示（toast），2–3 秒自动消失。成功是常态，不要用弹框打断 |
+| 失败 | 必须说清**发生了什么**和**能做什么**（重试 / 换个输入 / 联系支持）。禁止只写"操作失败" |
+
+缺任何一态，用户都会卡在"它到底动没动"的疑问里，然后重复点击。
+
+### 空态：说清为什么空，并给出下一步
+
+`Empty` 不是用来显示"暂无数据"的。它至少要回答两件事：
+
+1. **为什么空** —— 还没创建过 / 筛选后无结果 / 数据还在采集中，这三种是不同的文案。
+2. **下一步做什么** —— 对应给出创建入口 / 清除筛选 / 查看接入文档。
+
+空白处不要填装饰性插画。空态是用户最需要指引的时刻，也是最容易被做成死路的地方。
+
+### 颜色不能单独承载含义
+
+状态、涨跌、分类等信息**不得只靠颜色区分**，必须同时配图标、文字或形状。
+
+色盲用户、打印稿、低对比度屏幕上，只有颜色的信息等于没有信息。这是可访问性底线，
+不是风格偏好。本库的语义色（success / danger / warning / information）和 chart 色板
+是最容易违反这条的地方 —— 用它们的时候，检查一下拿掉颜色后信息还在不在。
+
+### 破坏性操作分两档
+
+| | 做法 |
+|---|---|
+| **不可逆**（删除） | 二次确认（`AlertDialog`），确认按钮用错误色，文案写明操作对象 |
+| **可逆**（移出列表、归档） | 不弹框，操作后给一个带撤销入口的 toast |
+
+一刀切地弹框，会让用户练成盲点确认，真正危险的那次也照点不误。
+
+### 权限三态
+
+同一个界面对不同权限的人应呈现三种形态，且必须可区分：
+
+| 态 | 呈现 |
+|---|---|
+| **可编辑** | 正常交互，控件全部可用 |
+| **只读** | 内容照常可读，控件不呈现为可交互（不是灰掉的按钮，是没有按钮）；需要时说明为什么只读 |
+| **无权限** | 内容不呈现，给出一句说明和申请路径 |
+
+⚠️ **只读不等于禁用**：禁用态（`disabled`）表达"现在不能用，但你有权用，条件不满足"；
+只读表达"你没有这个权限"。两者用同一种灰色，会让用户一直等一个永远不会亮的按钮。
+（参考 Carbon 的 enabled / read-only / disabled 三分。）
+
+---
+
+## 使用规约（消费方必读）
+
+本库经 npm 分发，消费方装的是**锁定的版本号**。因此改动的传播分两段，
+别把它们当成一回事：
+
+| | 怎么发生 |
+|---|---|
+| **你在本地看到改动** | 开了覆盖开关就是即时的（见上一节），零流程 |
+| **产品真正用上新版本** | 发版（打 tag → CI 发 npm）+ 消费方升版本号装一次，**不会自动** |
+
+第二段的手动闸门是有意的：库里手滑改错一行，不该让全线产品下次构建就跟着炸。
+
+要让改动能顺畅传播下去，业务项目使用时须遵守：
+
+1. **只从包入口引用**：`import { Button } from '@ptengine/design-components'`。
+   **禁止**把组件源码复制进业务项目——复制即与库脱钩，后续更新不再同步。
+2. **观感全部交给库**：颜色、字体、字号、圆角、阴影一律由组件与 token 提供。
+   业务代码**禁止**硬编码色值（`#xxx` / `rgb()`）、字体名、字阶之外的字号；
+   需要色彩语义时用 preset 暴露的 token 类（`text-muted-foreground`、
+   `bg-secondary`、`border-weak`、`bg-brand` 等）。
+3. **`className` 只做布局**：透传 className 用于宽度、间距、栅格、对齐等；
+   **不要**用它改组件观感（如 `bg-red-500`、`shadow-lg`、`rounded-full`）。
+   观感不满足 → 到库里改 variant / token（全站生效），不在调用处打补丁。
+4. **不覆盖 CSS 变量**：业务侧不得重定义 `--pt-*` 或别名变量；`tokens.css`
+   只在应用入口引一次，不复制、不改内容；主题切换只用 `.dark` 类。
+   唯一豁免：`--pt-z-overlay / --pt-z-popup / --pt-z-tooltip` 三个浮层
+   z-index 集成钩子本就设计为由宿主赋值（见 [README](./README.md) 「接入」第 4 步）。
+5. **缺组件到库里加**：需要新组件时按 [README](./README.md) 的「加组件」流程落到本库
+   （结构对齐 shadcn + 按交互状态规范适配），不在 app 内单独手写同类组件。
+
+> 破坏性变更（variant 改名、导出项调整等）会在库侧 commit 说明中标注，
+> 消费方按提示迁移。
+
+### 规约的执行
+
+机器强制现状：**ESLint 层在 apps/x**（`apps/x/eslint.config.js`「组件库治理」块：
+禁直引 Radix / cva、禁深路径引库内部文件、封死 antd；存量 `src/components/ui/**`
+豁免，随迁移批次收紧）。那批存量副本的清理是搬仓之后的下一期工作。
+
+---
+
+## 本文件的生长规则
+
+### 与 `llms.txt` 的派生关系（硬约束）
+
+`llms.txt` 是**对外产物** —— 它随 npm 包发布，外部 AI 从
+`https://unpkg.com/@ptengine/design-components/llms.txt` 直接读它来生成 UI。
+
+- **本文件是真值源，`llms.txt` 是它的派生物。**
+- 目前**没有生成脚本，靠手工同步**。改了本文件里任何一条硬规范（基调 / token 规矩 /
+  交互状态 / Button 词汇 / 圆角 / 字阶 / 消费方规约），**必须在同一个提交里更新
+  `llms.txt`**。
+- 漏同步的后果是**静默的**：库内规范已经变了，而外部（以及任何读 llms.txt 的 AI）
+  仍按旧规范生成代码，没有任何报错，要等到有人肉眼发现"生成出来的东西不对"才暴露。
+
+### 规范候选的提名（AI 在本仓工作时的义务）
+
+在本仓做任何组件工作时，留意有没有一条可以推广的规范正在浮现 ——
+重复出现的取舍、理由明显可推广的决策、代码里普遍存在但没写下来的隐性惯例。
+
+提名格式（出现在工作汇报末尾）：
+
+> 💡 **候选规范**：〔规则一句话〕
+> **为什么**：〔理由〕
+> **证据**：〔≥1 个真实出处〕
+> **建议归入**：〔本文件的哪一节〕
+> **过边界判据了吗**：〔换个产品还成立？成立才该进本文件〕
+
+**纪律**：提名 ≠ 生效。AI 绝不自行把候选规范写进本文件 —— 提名后等人类点头，
+点头了才回填。一次工作最多提名 1–2 条，拿不准就不提。

package/README.md

@@ -12,24 +12,16 @@
 - **源码随包分发**：`files` 含全量 `src`，消费方的 Tailwind 扫的是源码而非压缩产物
   （压缩会改写 class 字符串，扫 `dist` 会漏类）。开发期还可用本地覆盖开关直连源码，
   见下方「在 apps/x 里联调本组件库」。
-- **Token 唯一数据源**：`src/styles/tokens.css` 定义所有 CSS 变量——三层嵌套架构（③ shadcn 别名 → ② PTEngine 语义层 → ① 原语层纯通道三元组），透明度只在语义层以 `var(--pt-x) / a` 表达，明暗差异只在语义层覆盖；`tailwind.preset.js` 定义 Token → Tailwind 颜色键映射（实色套 `<alpha-value>`，自带透明度的只包 `rgb()`）。详见 tokens.css 文件头注释。
+- **Token 唯一数据源**：`src/styles/tokens.css` 定义所有 CSS 变量；`tailwind.preset.js` 定义 Token → Tailwind 颜色键映射。三层架构与硬规矩见 [组件设计规范](./COMPONENTS-DESIGN-SYSTEM.md)，完整定义见 `tokens.css` 文件头注释。
 - 保留可选 `pnpm build`（vite lib + d.ts），供独立发布。
 
-## 品牌视觉基调
+## 设计规范
 
-可以概括成「**克制、编辑感、内容优先**」——让整个界面看起来冷静、不吵：
+设计侧的硬规范 —— 设计基调、Token 规矩、交互状态、Button 变体词汇、圆角刻度、字阶、
+组件内建文案的本地化、消费方规约 —— 统一在 **[组件设计规范](./COMPONENTS-DESIGN-SYSTEM.md)**。
 
-- **近黑文字 + 暖灰中性色为绝对主体**，界面安静、不抢内容。文字灰阶全部由同一个
-  近黑原语（`--pt-black`）配不同透明度得来（strong 90% / standard 70% / weak 40%），
-  面与描边走 neutral 色阶与黑色低透明度叠加。
-- **彩色是稀缺资源、按功能发放，而不是用来装饰**。品牌绿只给 Brand 场景（`bg-brand`）、
-  语义色只表达状态（success / danger / warning / information / AI 角色 Token）、
-  chart 色板只给数据。没有功能含义的地方不出现彩色。
-- **大字号标题 + 充足留白建立层级**，而非靠色块、分隔线与阴影。字阶见下方
-  Typography；Card / 表单控件等根元素无阴影也是同一原则的落地。
-
-新增组件或调整 variant 时先对照这三条：一个改动如果让界面「变吵」了
-（多了一种装饰性颜色、多了一层非浮层阴影、层级靠色块而非字阶），方向就是错的。
+本库服务**多个产品**，这份规范只写产品无关的部分；某个产品自己的品牌取值与产品级
+模式归它自己的设计文件，**对本库无约束力**。
 
 ## 接入（所有消费方一致）
 
@@ -76,7 +68,7 @@ pnpm add @ptengine/design-components
    menubar / hover-card）< `--pt-z-tooltip`（tooltip），未设置时回退 `50`。
    宿主在自己的全局样式里赋值即可接入既有阶梯（apps/x 设 1000 / 1050 / 1070，
    见其 `src/styles/variables.css`），数值须保持 overlay < popup < tooltip。
-   这三个变量是「使用规约 4：不覆盖 CSS 变量」的**唯一豁免**——它们是布局
+   这三个变量是 [组件设计规范](./COMPONENTS-DESIGN-SYSTEM.md) 「使用规约」第 4 条（不覆盖 CSS 变量）的**唯一豁免**——它们是布局
    集成钩子，不是观感 token，本就设计为由宿主赋值。
 
 > **包里没有编译好的 CSS**：观感全靠消费方自己的 Tailwind 编译 + `tokens.css` 变量。
@@ -105,45 +97,6 @@ PT_DESIGN_COMPONENTS_SRC=/你的路径/design-components
   忘了自己设过 → 「apps/x 里看到的不是发布版的样子」。两种都难自查，
   改组件前先确认当前是哪种模式。
 
-## 使用规约（消费方必读）
-
-本库经 npm 分发，消费方装的是**锁定的版本号**。因此改动的传播分两段，
-别把它们当成一回事：
-
-| | 怎么发生 |
-|---|---|
-| **你在本地看到改动** | 开了覆盖开关就是即时的（见上一节），零流程 |
-| **产品真正用上新版本** | 发版（打 tag → CI 发 npm）+ 消费方升版本号装一次，**不会自动** |
-
-第二段的手动闸门是有意的：库里手滑改错一行，不该让全线产品下次构建就跟着炸。
-
-要让改动能顺畅传播下去，业务项目使用时须遵守：
-
-1. **只从包入口引用**：`import { Button } from '@ptengine/design-components'`。
-   **禁止**把组件源码复制进业务项目——复制即与库脱钩，后续更新不再同步。
-2. **观感全部交给库**：颜色、字体、字号、圆角、阴影一律由组件与 token 提供。
-   业务代码**禁止**硬编码色值（`#xxx` / `rgb()`）、字体名、字阶之外的字号；
-   需要色彩语义时用 preset 暴露的 token 类（`text-muted-foreground`、
-   `bg-secondary`、`border-weak`、`bg-brand` 等）。
-3. **`className` 只做布局**：透传 className 用于宽度、间距、栅格、对齐等；
-   **不要**用它改组件观感（如 `bg-red-500`、`shadow-lg`、`rounded-full`）。
-   观感不满足 → 到库里改 variant / token（全站生效），不在调用处打补丁。
-4. **不覆盖 CSS 变量**：业务侧不得重定义 `--pt-*` 或别名变量；`tokens.css`
-   只在应用入口引一次，不复制、不改内容；主题切换只用 `.dark` 类。
-   唯一豁免：`--pt-z-overlay / --pt-z-popup / --pt-z-tooltip` 三个浮层
-   z-index 集成钩子本就设计为由宿主赋值（见「消费方接入」第 5 步）。
-5. **缺组件到库里加**：需要新组件时按下方「加组件」流程落到本库
-   （结构对齐 shadcn + 按交互状态规范适配），不在 app 内单独手写同类组件。
-
-> 破坏性变更（variant 改名、导出项调整等）会在库侧 commit 说明中标注，
-> 消费方按提示迁移。
-
-### 规约的执行
-
-机器强制现状：**ESLint 层在 apps/x**（`apps/x/eslint.config.js`「组件库治理」块：
-禁直引 Radix / cva、禁深路径引库内部文件、封死 antd；存量 `src/components/ui/**`
-豁免，随迁移批次收紧）。那批存量副本的清理是搬仓之后的下一期工作。
-
 ## 使用
 
 ```tsx
@@ -158,130 +111,12 @@ import { Button, Input, Label, cn } from '@ptengine/design-components';
 
 沿用 shadcn 目录约定，把组件放到 `src/components/ui/`，用 `cn()` 合并类名、`cva` 管理 variants，然后在 `src/index.ts` 导出。`components.json` 已配好，也可用 `npx shadcn@latest add <component>` 落到本库再按需定制。
 
-### 交互状态规范（新组件接入必读）
-
-交互反馈统一走「状态层 State Layer」+ 中性交互 Token，**禁止**沿用 shadcn 官方的
-替换式写法（`hover:bg-primary/90`、`hover:bg-*/80` 等）。拷官方组件进来时按此适配：
-
-| 官方写法 | 本库写法 | 说明 |
-|---|---|---|
-| `hover:bg-primary/90` / `hover:bg-*/80` | 变体类里加 `state-layer` | hover 在原样式上叠加 `--pt-interaction-hover`，active 自动叠加 `--pt-interaction-press`（定义见 `tailwind.preset.js`） |
-| `hover:bg-accent hover:text-accent-foreground`（outline/ghost 等） | `state-layer` | 同上，文字色不再切换 |
-| `focus:bg-accent` / `data-[highlighted]:bg-accent`（菜单项、下拉选项） | **保留原写法** | Radix 键盘高亮机制依赖 focus/highlighted 态；`--accent` 已指向 `--pt-interaction-hover`，效果与叠加一致 |
-| `focus-visible:ring-ring` 等焦点环 | **保留原写法** | `--ring` 已指向 `--pt-interaction-focus`（中性 90%） |
-| 持久「选中 / 激活 / 开」态（`data-[state=selected/on]`、`data-[active=true]`） | 元素底色用 `bg-selected` | `--pt-bg-selected` ＝ 中性 8%，**与 hover 同色**；因为 hover 走 state-layer（叠加层而非替换背景），选中态被悬停时两层叠加 ≈ 16%，天然区分「选中」与「悬停」。**不要用品牌绿等彩色表达选中**（彩色只给 Brand / 语义 / 数据）。前提是该元素的 hover 必须是 state-layer 叠加；若 hover 仍是 `hover:bg-*` 替换式，则改用叠加式，或另加区分（如 sidebar 当前项用 `font-medium`） |
-| 纯文字反馈（link 变体 `hover:underline`） | **保留原写法** | 不加状态层 |
-
-### Button 变体词汇（与 shadcn 官方的差异）
-
-| 本库 variant | 样式 | 对应官方 |
-|---|---|---|
-| `default`（Primary） | 高强调黑，暗色反白，反转状态层 | 官方 default（本库 `--primary` 指向黑） |
-| `brand` | 品牌绿 | 无（本库新增，`bg-brand`） |
-| `secondary` | 描边白底 | 官方 **outline** 的样式 |
-| `tertiary` | 灰底弱强调 | 官方 **secondary** 的样式 |
-
-拷官方组件/示例进来时：`variant="outline"` → `variant="secondary"`；
-官方 `variant="secondary"` 的场景按语义改用 `tertiary`。`--primary` 槽位为黑色，
-品牌绿一律走 `--brand` / `bg-brand`。
-
-想定制某组件观感（配色 / 尺寸 / 圆角），改该组件 cva `variants` 里的类即可全站生效；
-Primary（黑，暗色反白）这类深色表面用 `state-layer-inverse`，其余用 `state-layer`。
+新组件必须按 [组件设计规范](./COMPONENTS-DESIGN-SYSTEM.md) 的「交互状态规范」与「Button 变体词汇」适配，
+不要沿用 shadcn 官方的替换式 hover 写法。
 
 > **注**：组件源码内不写决策/过程注释（playground 会原样展示源码给使用者），
-> 规范与决策记录统一沉淀在本 README；`/** */` 形式的 props 说明属于 API 文档，保留。
-
-百分比只维护在 `src/styles/tokens.css` 语义层（`--pt-interaction-hover/press/focus`），
-调整后组件与 `/tokens` 展示页自动跟随。
-
-## 圆角 Radius（六档）
-
-| 类名 | 值 | 用在 |
-|---|---|---|
-| `rounded-sm` | 6px | sm 档控件（24px 高） |
-| `rounded-md` | 8px | default / lg 档控件（32 / 40px 高） |
-| `rounded-lg` | 10px | 卡片、弹窗、浮层 —— 基准档 |
-| `rounded-12` | 12px | 更柔和的面板 |
-| `rounded-16` | 16px | 页面级外壳、对话坞 |
-| `rounded-20` | 20px | 需要强调圆润的大面 |
-
-正圆用 `rounded-full`。可视对照与选档指南见 playground 的 **Radius** 页。
-
-**为什么大档位用 px 命名而不是 `xl` / `2xl`**：Tailwind 默认 `rounded-xl`=12px、
-`rounded-2xl`=16px，与本库需要的 16 / 20 同名不同值。沿用 t 恤码会让从 shadcn / Tailwind
-生态抄来的代码**静默偏移几 px** —— 不报错、不警告，只是看着「有点不对」，极难自查。
-`rounded-12/16/20` 在两边都不存在，不可能撞。
-
-**两种产生方式有意混用**（改值前必读）：
-
-```
---pt-radius      10px              手写，基准
---pt-radius-md   calc(基准 − 2px)  派生 → 8px
---pt-radius-sm   calc(基准 − 4px)  派生 → 6px
---pt-radius-12   12px              固定，不跟随基准
---pt-radius-16   16px              固定，不跟随基准
---pt-radius-20   20px              固定，不跟随基准
-```
-
-派生那套来自 shadcn（一个 `--radius` 旋钮整体缩放，档间恒差 2px）；后加的三档要的是
-「更细的尺子」而不是「可整体缩放的比例」，且基准自建库起从未调过，那个旋钮实际没人用。
-**后果**：真去调基准时，前三档会动、后三档不动 —— 这个分裂是有意的，不是漏改。要统一
-应把前三档也写死，而不是把后三档改成 calc（那会让 `rounded-16` 在基准变化后不再是 16px）。
-
-⚠️ **缺档就加档，不要硬写 `rounded-[18px]` 这类任意值**，否则每个面板各写各的数，刻度失效。
-
-## 字体 Typography（中/日/英三语）
-
-品牌字体（源自 Figma `Type/Mode` 的 family 变量）：EN `Inter` / JA `Noto Sans JP` /
-ZH `Noto Sans SC`。库侧在 `tokens.css` 以 `--font-sans` + `:lang()` 声明三语字体栈
-（`'Inter'` 置前，拉丁字符与数字三语统一用 Inter，CJK 落到 JP/SC；各栈带同语言
-系统字体回退），preset 将 `fontFamily.sans` 接到 `var(--font-sans)`。
-组件不声明字体，全部继承。（Figma 中 `family/code` / `family/metric` 亦为 Inter；
-代码展示场景仍保留等宽 `font-mono`，未用 Inter 覆盖。）
-
-**字阶**（preset `fontSize` 整表覆盖，源自 Figma Text Styles，机读存档
-`design/tokens.json`，**在源码仓里、不随 npm 包分发**）：`2xs 12/16 · xs 13/20 · sm 14/20 · base 16/24 · lg 18/28 ·
-xl 20/32 · 2xl 24/36 · 3xl 28/40 · 4xl 32/48 · 5xl 40/56 · 6xl 48/72 · 7xl 56/72 ·
-8xl 64/96 · 9xl 72/128`。与 Tailwind 默认的差异：新增 `2xs`；**`xs` 为 13px**（非 12）；
-`xl` 起行高/字号按设计表。字重五档：light 300 / normal 400 / medium 500 / semibold 600 / bold 700。
-
-**行高按语言可分**：字号三语一致；行高走 `tokens.css` 的 `--lh-*` 变量
-（`:root` ＝ English 基准）。现行策略 ja/zh 沿用 English 值；后续精修时在
-`:lang(ja)` / `:lang(zh)` 预留块中只填与英文不同的档位，全站自动生效，
-组件零改动（机制已验证：同字号、按语言不同行高）。
-
-**消费方应用需要做的三件事：**
-
-1. **正确设置 `<html lang>`**（`en` / `zh-CN` / `ja`，i18n 框架切语言时同步更新）——
-   字体栈按它切换，组件零改动。
-2. **加载字体文件**（库不打包字体）：Next.js 用 `next/font/google`，或 fontsource /
-   `<link>` 引 Google Fonts。加载 300/400/500/600/700 五档字重。
-3. **中国大陆环境自托管 `Noto Sans SC`**（Google Fonts 大陆不可达），并做
-   unicode-range 子集切片（CJK 全量单字重为 MB 级）。
-
-### 组件内建文案的本地化（库不做 i18n，消费方传译文）
-
-个别组件自带可见文案或读屏（sr-only / aria-label）标签。库不引 i18n 框架，
-统一做法是**通过 prop 传入、默认英文**——做多语界面时把译文传进去，不传保持
-英文，对现有代码零影响。
-
-| 组件 | prop | 默认值 |
-|---|---|---|
-| `SearchInput` | `clearLabel` | Clear |
-| `PaginationPrevious` / `PaginationNext` | `label` | Previous / Next |
-| `PaginationEllipsis` / `BreadcrumbEllipsis` | `label` | More pages / More |
-| `DialogContent` / `SheetContent` | `closeLabel` | Close |
-| `CarouselPrevious` / `CarouselNext` | `label` | Previous slide / Next slide |
-| `SidebarTrigger` / `SidebarRail` | `label` | Toggle sidebar |
-| `MessageScrollerButton` | `label` | Scroll to end / Scroll to start |
-| `Spinner` | `label` | Loading |
-
-```tsx
-<PaginationPrevious label={t('上一页')} />
-<DialogContent closeLabel={t('关闭')}>…</DialogContent>
-```
-
-新组件若要内建文案，照此约定加 prop，不要写死字符串。
+> 规范与决策记录统一沉淀在 [组件设计规范](./COMPONENTS-DESIGN-SYSTEM.md)；`/** */` 形式的 props
+> 说明属于 API 文档，保留。
 
 ## 现有组件（shadcn 官方清单已全量覆盖）
 

package/dist/components/ui/prompt-picker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompt-picker.d.ts","sourceRoot":"","sources":["../../../src/components/ui/prompt-picker.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAK/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,WAAW,gBAAgB;IAC7B,kDAAkD;IAClD,EAAE,EAAE,MAAM,CAAC;IACX,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,QAAQ,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC9B;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,IAAI,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAkB,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,UAAU,CAAC;IAC7F,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B;;;OAGG;IACH,MAAM,EAAE,CAAC,IAAI,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACzC;;;;OAIG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAwCD,QAAA,MAAM,YAAY,0FAkIjB,CAAC;AAGF,OAAO,EAAE,YAAY,EAAE,CAAC"}
+{"version":3,"file":"prompt-picker.d.ts","sourceRoot":"","sources":["../../../src/components/ui/prompt-picker.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAK/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,WAAW,gBAAgB;IAC7B,kDAAkD;IAClD,EAAE,EAAE,MAAM,CAAC;IACX,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,QAAQ,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC9B;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,IAAI,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAkB,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,UAAU,CAAC;IAC7F,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B;;;OAGG;IACH,MAAM,EAAE,CAAC,IAAI,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACzC;;;;OAIG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AA0CD,QAAA,MAAM,YAAY,0FAkIjB,CAAC;AAGF,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/dist/components/ui/search-input.d.ts

@@ -1,8 +1,8 @@
 import * as React from 'react';
 declare const SIZE_CLASSES: {
-    readonly sm: "h-[24px] px-[8px] rounded-[var(--pt-radius-sm)] [&_input]:text-[12px] [&_input]:leading-[16px]";
+    readonly sm: "h-[24px] px-[8px] rounded-[var(--pt-radius-sm)] [&_input]:text-2xs";
     readonly default: "h-[32px] px-[10px]";
-    readonly lg: "h-[40px] px-[12px] [&_input]:text-[14px] [&_input]:leading-[20px]";
+    readonly lg: "h-[40px] px-[12px] [&_input]:text-sm";
 };
 export interface SearchInputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'value' | 'onChange' | 'type' | 'size'> {
     /** 尺寸:sm 24px(行内)· default 32px(常规)· lg 36px(页面级主搜索) */

package/dist/components/ui/select.d.ts

@@ -17,7 +17,7 @@ declare const SelectValue: React.ForwardRefExoticComponent<SelectPrimitive.Selec
  *
  * `w-full` 不在里面：Select 自己要撑满容器，而筛选器通常按内容宽。各自加。
  */
-export declare const selectTriggerClassName = "flex h-[32px] items-center justify-between whitespace-nowrap rounded-[var(--pt-radius-md)] border border-input bg-transparent px-[12px] py-[8px] text-[13px] leading-[20px] ring-offset-background transition-colors placeholder:text-muted-foreground enabled:hover:border-neutral focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50 aria-[invalid=true]:border-destructive aria-[invalid=true]:text-destructive aria-[invalid=true]:enabled:hover:border-destructive aria-[invalid=true]:focus-visible:ring-destructive/30 [&>span]:line-clamp-1";
+export declare const selectTriggerClassName = "flex h-[32px] items-center justify-between whitespace-nowrap rounded-[var(--pt-radius-md)] border border-input bg-transparent px-[12px] py-[8px] text-xs ring-offset-background transition-colors placeholder:text-muted-foreground enabled:hover:border-neutral focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50 aria-[invalid=true]:border-destructive aria-[invalid=true]:text-destructive aria-[invalid=true]:enabled:hover:border-destructive aria-[invalid=true]:focus-visible:ring-destructive/30 [&>span]:line-clamp-1";
 declare const SelectTrigger: React.ForwardRefExoticComponent<Omit<SelectPrimitive.SelectTriggerProps & React.RefAttributes<HTMLButtonElement>, "ref"> & React.RefAttributes<HTMLButtonElement>>;
 declare const SelectScrollUpButton: React.ForwardRefExoticComponent<Omit<SelectPrimitive.SelectScrollUpButtonProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
 declare const SelectScrollDownButton: React.ForwardRefExoticComponent<Omit<SelectPrimitive.SelectScrollDownButtonProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/components/ui/select.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"select.d.ts","sourceRoot":"","sources":["../../../src/components/ui/select.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,eAAe,MAAM,wBAAwB,CAAC;AAK1D,QAAA,MAAM,MAAM,uCAAuB,CAAC;AAEpC,QAAA,MAAM,WAAW,yGAAwB,CAAC;AAE1C,QAAA,MAAM,WAAW,0GAAwB,CAAC;AAE1C;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,sBAAsB,6lBAC2jB,CAAC;AAE/lB,QAAA,MAAM,aAAa,oKAejB,CAAC;AAGH,QAAA,MAAM,oBAAoB,qKAWxB,CAAC;AAGH,QAAA,MAAM,sBAAsB,uKAW1B,CAAC;AAGH,QAAA,MAAM,aAAa,8JA6BjB,CAAC;AAGH,QAAA,MAAM,WAAW,4JASf,CAAC;AAGH,QAAA,MAAM,UAAU,2JAmBd,CAAC;AAGH,QAAA,MAAM,eAAe,gKASnB,CAAC;AAGH,OAAO,EACH,MAAM,EACN,WAAW,EACX,WAAW,EACX,aAAa,EACb,aAAa,EACb,WAAW,EACX,UAAU,EACV,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACzB,CAAC"}
+{"version":3,"file":"select.d.ts","sourceRoot":"","sources":["../../../src/components/ui/select.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,eAAe,MAAM,wBAAwB,CAAC;AAK1D,QAAA,MAAM,MAAM,uCAAuB,CAAC;AAEpC,QAAA,MAAM,WAAW,yGAAwB,CAAC;AAE1C,QAAA,MAAM,WAAW,0GAAwB,CAAC;AAE1C;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,sBAAsB,0kBACwiB,CAAC;AAE5kB,QAAA,MAAM,aAAa,oKAejB,CAAC;AAGH,QAAA,MAAM,oBAAoB,qKAWxB,CAAC;AAGH,QAAA,MAAM,sBAAsB,uKAW1B,CAAC;AAGH,QAAA,MAAM,aAAa,8JA6BjB,CAAC;AAGH,QAAA,MAAM,WAAW,4JASf,CAAC;AAGH,QAAA,MAAM,UAAU,2JAmBd,CAAC;AAGH,QAAA,MAAM,eAAe,gKASnB,CAAC;AAGH,OAAO,EACH,MAAM,EACN,WAAW,EACX,WAAW,EACX,aAAa,EACb,aAAa,EACb,WAAW,EACX,UAAU,EACV,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACzB,CAAC"}