# @ui-arch · 私人组件库

自研、零依赖、Agent 友好的 DOM 组件库单体仓：**signal 微框架 + headless 表格内核 + 令牌化皮肤组件**，所有文档与 MCP 注册表都从一个清单派生。

## 快速开始

```bash
pnpm install            # 包间依赖用 workspace:*，npm 不支持
npm run check           # 门禁一条龙：build → demo → style → typecheck → smoke → index → verify → lint-iterations → audit:visual → audit:contrast → audit:motion
npm run demo            # 打开演示：apps/demo/dist/demo.html
npm run docs            # 生成人类文档站 apps/docs/index.html + Agent 全量文档 llms-full.txt
npm run changelog       # 依据 git 提交史重写 CHANGELOG.md（发版前跑；changelog:check 可查漂移）
```

## 组件（共 78 个）

<!-- ua:components -->
accordion · affix · alert · anchor · autoComplete · avatar · avatarGroup · backTop · badge · breadcrumb · button · calendar · carousel · card · cascader · checkbox · checkboxGroup · colorPicker · commandPalette · copyButton · countdown · dataTable · datePicker · descriptions · divider · drawer · empty · floatButton · form · grid · highlight · image · inputNumber · inputTag · jsonViewer · kbd · layout · link · list · menu · modal · mentions · multiSelect · notification · pagination · pinInput · popover · popconfirm · progress · radioGroup · rate · result · segmented · select · skeleton · slider · space · spinner · splitter · statistic · stepper · switchButton · tabs · tag · textField · textarea · timeline · timePicker · toast · tooltip · tour · transfer · tree · treeSelect · typography · upload · virtualList · watermark
<!-- /ua:components -->

分组：表单（button / copyButton / textField / inputNumber / inputTag / textarea / checkbox / checkboxGroup / colorPicker / switchButton / select / mentions / multiSelect / radioGroup / slider / rate / autoComplete / datePicker / timePicker / pinInput / segmented / upload / form + formItem / transfer / cascader）、反馈（alert / toast / notification / result / spinner / progress / skeleton / badge / empty / statistic / countdown）、浮层（tooltip / popover / popconfirm / modal / drawer / menu / commandPalette）、导航（tabs / breadcrumb / pagination / accordion / stepper / tree / treeSelect / anchor）、数据展示（dataTable / jsonViewer / descriptions / card / list / kbd / highlight / timeline / tag / avatar / avatarGroup / image / carousel / calendar / typography / virtualList）、其他（floatButton / grid / layout / link / space / divider / splitter / backTop / affix / tour / watermark）。

## 可访问性约定

- 对比度：令牌层 18 组「前景色 × 底色」在亮 / 暗 × 常规 / 高对比四套主题下都不低于 WCAG 阈值（正文 7、常规 4.5、禁用 2.6、焦点描边等非文本 3），`npm run audit:contrast` 是这条约定的门禁；系统开启「提高对比度」时边框与弱文字自动加深一档
- 键盘焦点：所有库内元素统一 `outline: 2px solid var(--ua-color-accent)`（focus-visible 专属，鼠标点击不出现），组件自绘的 box-shadow 光环与它叠加不冲突。
- 关键交互都有键盘等价：Tab 进焦点、Enter/空格 激活、↑↓/Home/End 在列表类组件内移动、Esc 逐层关闭（内层先关，不连带外层）。
- 高对比模式：除「提高对比度」偏好外，Windows 强制色（`@media (forced-colors: active)`）下也有兜底——浮层与控件改回真边框（不再靠阴影）、选中态改用系统 Highlight 高亮底、占位与骨架走 GrayText，避免高对比下「控件隐形」。
- 语义与播报：modal/drawer 带 `role="dialog" aria-modal`、toast/notification/empty/result 带 `role="status"/"alert"`，切换类组件用 `aria-selected`/`aria-expanded` 同步状态。

## 目录

| 路径 | 说明 |
|---|---|
| `packages/core/frame` | @ui-arch/frame：signal / computed / effect + hyperscript（无虚拟 DOM） |
| `packages/core/table-core` | @ui-arch/table-core：headless 表格（filter → sort → paginate 派生管线） |
| `packages/skin/ui` | @ui-arch/ui：78 个 DOM 组件 + ui.css（只消费 `--ua-*` 令牌） |
| `packages/design/tokens` | @ui-arch/tokens：设计令牌（暗色只换值不换名） |
| `packages/tools/cli` | @ui-arch/cli：`ua` 命令行与 stdio MCP server |
| `apps/demo` | 交互演示（esbuild 打包成单文件） |
| `apps/docs` | 文档站纯产物（`ua docs` 生成） |

## 三道门禁

1. `ua style`：注释规范——导出必须有 `/*** 作用 ***/`、接口字段行尾注释、行注释用中文，且分层包 src 内单文件 ≤ 200 行（`types.ts` / `index.ts` 豁免）。
2. `ua verify`：清单 ↔ 文档 ↔ 演示一致（id 唯一、exports 对应、props 带 n/t/d、steps ≥ 3、demo 锚点存在），皮肤样式表禁止 `#hex` 硬编码颜色，`var(--ua-*)` 必须引用 tokens.css 已定义或组件自设的变量。
3. `ua index`：刷新 `.ua/index.json` / `llms.txt`，供 MCP 与 Agent 查询。

## Agent 接入

- 静态：`llms.txt`（速览）/ **`llms-full.txt`（全量：逐组件参数 / 回调 / 手把手 / 令牌）**
- 命令行：`node packages/tools/cli/bin/ua.js list | search <关键词> | info <包名|组件id> | docs | tokens | verify | mcp`
- MCP：在 `~/.workbuddy/mcp.json` 注册 `ua mcp`，可用 `list_components` / `get_component` / `search_components` / `get_tokens` / `list_recipes` / `get_recipe`

规范见 `AGENTS.md`（接入手册）、`ARCHITECTURE.md`（分层与依赖方向）、`CODING.md`（编码规范）、`ITERATION.md`（自动迭代协议）。

## 分支流水线

```
qa/probe ──门禁通过──▶ qa/stable ──人工审阅──▶ main（受保护）
```

自动化只在 `qa/stable` 做 fast-forward 合并，`main` 仅由人审后合入。