@ui-arch · 私人组件库

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

快速开始

pnpm install            # 包间依赖用 workspace:*，npm 不支持
npm run check           # 门禁一条龙：build → demo → style → typecheck → smoke → index → verify
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 可查漂移）

组件（共 59 个）

accordion · affix · alert · anchor · autoComplete · avatar · backTop · badge · breadcrumb · button · carousel · card · cascader · checkbox · checkboxGroup · colorPicker · dataTable · datePicker · descriptions · divider · drawer · empty · form · image · inputNumber · list · menu · modal · multiSelect · notification · pagination · popover · popconfirm · progress · radioGroup · rate · result · segmented · select · skeleton · slider · space · spinner · splitter · statistic · stepper · switchButton · tabs · tag · textField · textarea · timeline · toast · tooltip · tour · transfer · tree · upload · watermark

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

可访问性约定

• 键盘焦点：所有库内元素统一 outline: 2px solid var(--ua-color-accent)（focus-visible 专属，鼠标点击不出现），组件自绘的 box-shadow 光环与它叠加不冲突。
• 关键交互都有键盘等价：Tab 进焦点、Enter/空格 激活、↑↓/Home/End 在列表类组件内移动、Esc 逐层关闭（内层先关，不连带外层）。
• 语义与播报：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：59 个 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 | info <包名|组件id> | docs | tokens | verify | mcp
• MCP：在 ~/.workbuddy/mcp.json 注册 ua mcp，可用 list_components / get_component / search_components / get_tokens

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

分支流水线

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

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