UI/llms.txt

# @ui-arch 私人组件库索引

> 本文件由 `ua index` 自动生成，请勿手改。机器可读版：`.ua/index.json`。
> Agent 可通过 `ua mcp`（stdio MCP server）直接查询注册表。

## @ui-arch/frame (v0.1.0)

- 类型: headless-core · 目录: packages/core/frame
- 描述: 自研微框架：signal / computed / effect 信号系统 + hyperscript（h）DOM 层。函数值属性与函数型子节点自动响应式；renderList 做列表整体替换；零依赖、无虚拟 DOM。
- API:
  - signal(initial) -> Signal<T>：无参读值并收集依赖，传参写值并触发订阅
  - effect(fn)：立即执行并追踪依赖，信号变化自动重跑
  - computed(fn)：由信号派生的只读计算值
  - h(tag, props, ...children)：hyperscript；on* 绑事件，函数值属性/子节点自动响应式
  - renderList(el, fn)：信号变化时整体替换容器子节点
  - mount(target, view)：挂载视图
- 用法: `const count = signal(0); mount('#app', () => h('button', { onClick: () => count(count() + 1) }, () => `count = ${count()}`))`
- 约定: 组件 = 返回 DOM 节点的普通函数，不做类组件与生命周期抽象
- 约定: 跨系统状态（如 table-core）用桥接信号：subscribe 里递增 version 信号

## @ui-arch/table-core (v0.1.0)

- 类型: headless-core · 目录: packages/core/table-core
- 描述: Headless table state machine: immutable state, dispatch/reducer, composable derive pipeline (filter -> sort -> paginate) with per-stage memoization. No DOM, no framework dependency.
- API:
  - createTable(options) -> TableInstance: create headless table instance
  - sortPlugin(options?) -> multi-column sorting plugin (asc -> desc -> off cycle)
  - filterPlugin(options?) -> column filter plugin (default substring match, custom predicate supported)
  - paginationPlugin() -> client-side pagination with page clamping, exposes setPage/nextPage/prevPage/getPageInfo
  - selectionPlugin() -> rowKey-based selection, exposes selectAllVisible
- 用法: `const table = createTable({ data, columns, rowKey: 'id', plugins: [filterPlugin(), sortPlugin(), paginationPlugin()], initialState: { pagination: { page: 1, pageSize: 20 } } }); table.dispatch({ type: 'toggleSort', key: 'name' }); table.getVisibleRows()`
- 约定: selection/expanded must store rowKey, never row index
- 约定: derive pipeline order is fixed: filter -> sort -> paginate
- 约定: actions are the only way to mutate state; state is immutable

## @ui-arch/tokens (v0.1.0)

- 类型: design-tokens · 目录: packages/design/tokens
- 描述: Single source of design tokens. Skin packages consume CSS variables only - hardcoded colors inside skins are forbidden. Dark theme overrides values under [data-theme='dark'], never names.
- API:
  - tokens.css: import '@ui-arch/tokens/tokens.css' once at app root
  - tokens.json: programmatic access for tools and agents
- 用法: `import '@ui-arch/tokens/tokens.css'; then use var(--ua-color-accent) etc. in any skin package`

## @ui-arch/ui (v0.1.0)

- 类型: skin-dom · 目录: packages/skin/ui
- 描述: DOM 皮肤组件库：表单 / 反馈 / 浮层 / 导航 / 数据展示，构建在 @ui-arch/frame 与 @ui-arch/table-core 之上，样式只消费 --ua-* 令牌（组件全量见 api.exports 或刚体清单）
- API:
  - button(props)：按钮，variant 三档视觉强度，disabled / loading 支持布尔或信号动态同步（loading 转圈并禁点），onClick 点击回调
  - textField(props)：文本输入，value 信号双向绑定，disabled 支持布尔或信号，onInput 输入回调；prefix/suffix 可选渲染为输入框内侧附加块，clearable 开启后有值即显一键清空按钮，maxCount 设原生上限并实时显示字数
  - inputNumber(props)：数字输入，−/+ 按钮与键盘 ↑↓ 调节（长按连发步进），min/max/step 夹取，precision 小数位归一；prefix/suffix 可选渲染为整组前后附加块
  - textarea(props)：多行输入，value 信号双向绑定，disabled 支持布尔或信号，rows 控行数；prefix/suffix 可选渲染为上下附加块，maxCount 显示实时字数并设原生上限
  - slider(props)：滑块，value 信号双向绑定，min/max/step 可配，原生 range 承载键盘交互，右侧可显示当前值
  - checkbox(props)：复选框，checked 信号双向绑定，indeterminate 半选态（读屏播报 mixed），disabled 支持布尔或信号禁用
  - switchButton(props)：开关，checked 信号双向绑定，loading 加载锁（滑块转圈 + aria-busy），disabled 支持布尔或信号禁用
  - select(props)：自绘下拉选择（非原生 select），value 信号双向绑定，点外部 / Esc 关闭，选项弹层带微动画，disabled 支持布尔或信号禁用，空间不足自动翻转，键入字母快跳选项；searchable 开启弹层搜索框，clearable 有值时给清空按钮
  - menu(props)：下拉菜单，触发器 + 自绘弹层，条目支持禁用 / 危险 / 分隔线，↑↓ 环形导航，点外部 / Esc 关闭，空间不足自动翻转，键入字母快跳菜单项
  - flip(trigger, panel, preferred)：浮层上下翻转判定，按触发器与面板的视口几何决定 preferred 方位放不下时是否翻转，返回实际生效方位 'top' | 'bottom'
  - radioGroup(props)：单选组，options + value 信号双向绑定，disabled 整组禁用
  - accordion(props)：折叠面板，标题按钮 + grid 行高过渡，单开（手风琴）或多开，支持禁用面板与 active 信号受控
  - breadcrumb(props)：面包屑，nav + ol 语义结构，末项为当前页（aria-current），有 href 走原生链接、无 href 交给 onNavigate
  - card(props, ...children)：卡片容器
  - badge(props)：徽标，variant = default | success | warning | danger
  - tag(props)：可关闭标签，variant 五档语义色，closable + onClose 支持从数据源移除（纯展示请用 badge）
  - avatar(props)：头像，有 src 渲染图片（alt 用名称）、无 src 用首字占位，size 可调 + 四档语义底色
  - alert(props)：提示条，variant 四档语义色 + 可选 title 与 closable 关闭按钮，role=alert 读屏可播报
  - toast.info/success/warning/error(message, duration?)：消息提示工厂，右上角堆叠，默认 3s 自动消失（悬停暂停、移出续时），出入场微动画；showToast(props) 为完整入参版本（closable 显示关闭按钮，同屏最多 4 条）
  - tooltip(props, trigger)：包裹式悬浮提示，hover / 键盘聚焦延迟出场，Esc 收起；触摸屏按下即出、抬手延迟 1.2s 收起，气泡 pointer-events: none 不挡点击
  - popover(props, trigger)：可交互气泡卡片，包裹触发器，默认点击开合 + 点外部 / Esc 收起，content 可放按钮等交互元素；视口一侧空间不足时自动翻转
  - skeleton(props)：骨架屏占位，variant = text | rect | circle，text 支持 rows 多行，扫光微动画
  - pagination(props)：独立分页器，page 信号双向绑定，页码过多折叠省略号，首末页禁用翻页，jumpable 时末尾可输入页码直接跳转，键盘可达；pageSizes 可切每页条数
  - spinner(props)：加载指示器，size 控制直径
  - progress(props)：进度条，value 信号驱动 0-100（满格切 success 色）；不传 value 退化为不确定态无限往复
  - tabs(props)：标签页，active 信号双向绑定，滑动指示条 + 方向键环形导航，支持禁用页签；页签项 closable 时带关闭按钮（聚焦后 Delete 同样可关），关闭只回调 onClose 由调用方摘数据
  - stepper(props)：步骤条，done/current/upcoming 三态，active 信号双向绑定，clickable 时已完成步骤可回跳
  - rate(props)：评分星标，value 信号双向绑定，hover 预览移出还原，键盘方向键调节，max 可配，allowHalf 开启半星（左半区 0.5 分）
  - empty(props)：空状态占位，title/description 可选，action 放操作区
  - divider(props)：分隔线，水平/垂直两种方向，可带居中文案标签，dashed 切虚线
  - space(props)：间距容器，flex gap 统一子元素间距，direction / size / align / justify / wrap / block 可调
  - modal(props, ...children)：弹窗，open 信号驱动显隐，Esc / 遮罩 / × 关闭，size 三档宽度，footer 提供底部操作区
  - drawer(props, ...children)：抽屉，open 信号驱动侧滑面板，placement 左右可配、width 可调、footer 操作区，遮罩 / × / Esc 关闭
  - form(props, items)：表单容器，布局 + 聚合校验，全部通过才触发 onSubmit
  - formItem(props, control)：表单字段，label + 必填红星 + 规则校验 + 错误区，返回 { el, validate } 句柄
  - dataTable(props)：数据表格，粘性表头 / 行选择（全选三态）/ 排序 / 筛选 / 分页 / 空状态；loading 为真时数据行换骨架行且筛选/翻页禁用，内核为 table-core
  - image(props)：图片，缩略图点击 / 回车开遮罩大图预览（Esc 或点击遮罩关闭），width 控制缩略宽，加载失败自动落占位（fallback 自定义文案）
  - timeline(props)：时间线，items 按序渲染纵向事件流（标题 / 时间 / 正文 + 语义色节点），mode 控制轴线左右，pending 追加进行中节点
  - segmented(props)：分段控制器，胶囊分段 + 滑动滑块，value 信号双向绑定，←→ 环形导航，整组或单项可禁用
  - descriptions(props)：描述列表，items(label/value/span) 铺进 column 列网格，bordered 切表格形态，窄屏自动单列
  - statistic(props)：统计数值，标题 + 大号数字 + 前后缀 + 环比趋势，value 变化时 rAF 滚动过渡（400ms easeOutCubic），减弱动效偏好下直落终值
  - list(props)：列表，header/footer 外壳 + 条目 avatar/title/description/extra，onItemClick 让条目可点击，items 为空回落空状态
  - carousel(props)：轮播，items 横排位移，指示点/箭头/←→ 键切换，autoplay 毫秒自动前进且悬停暂停，index 信号可外部受控
  - tree(props)：树形，递归节点 + 箭头展开/收起 + 点选节点，键盘 Enter 选中、→ 展开、← 收起，禁用节点不响应
  - upload(props)：文件选择，点击或拖拽入列，清单可逐个移除，onChange 回传文件数组（不内置上传请求）
  - notification(props)：右下角通知卡片（标题 + 描述 + 操作区），返回 { el, close } 句柄，缺省常驻需手动关闭
  - result(props)：结果页，status 四档语义色 + 标题 + 说明 + 操作区，用于提交完成/校验失败等终态
  - transfer(props)：穿梭框，左右两栏勾选后整体搬运，targetKeys 信号双向绑定，两栏各自搜索与全选（含半选），禁用条目不参与搬运也不可勾选
  - cascader(props)：级联选择，多列联动面板（悬停下钻 / 点击提交），value 为路径数组信号，changeOnSelect 允许停在中间层，全键盘可操作
  - splitter(props)：可拖拽分栏容器，分隔条支持指针拖拽 / 方向键微调 / 双击复位，sizes 为百分比数组信号
  - autoComplete(props)：输入联想，输入即过滤候选、↑↓ 环形高亮 / Enter 选中 / Esc 收起，options 可传函数做远程联想
  - datePicker(props)：日期选择，单月网格 + 翻月 / 今天快捷键，value 为 YYYY-MM-DD 信号，min/max 闭区间限制，方向键逐日逐周可导航
  - backTop(props)：返回顶部悬浮按钮，越过阈值才浮现，外环 conic-gradient 显示已滚比例，点击平滑回顶
  - colorPicker(props)：颜色选择，预设色板（缺省语义令牌色）+ 原生取色器 + 手输 CSS 颜色串，value 为颜色串信号
  - tour(props)：引导漫游，返回 { el, start, close } 句柄；聚光框按 target 选择器定位，卡片自动选方位，Esc / 跳过走 onClose
  - watermark(props, ...children)：内容容器 + 平铺水印覆盖层，canvas 生成单元、颜色取自令牌，覆盖层不挡交互
  - checkboxGroup(props)：多选组，value 为数组信号，min/max 用禁用边界项实现（不抛错），checkAll 支持半选且只统计未禁用项
  - affix(props, ...children)：固钉，滚过 offset 后内容转 fixed 贴顶、外层保留占位高度，固定后宽度随容器自适应
  - multiSelect(props)：多选下拉，标签式回显 + 可搜索弹层，点选不收起便于连续多选，max 到限后未选项禁用
  - anchor(props)：锚点导航，竖排区块链接，滚动时按目标位置高亮当前区块（aria-current 同步），点击按 offset 偏移量平滑定位并回写 hash；container 可指定内滚容器
  - popconfirm(props, trigger)：二次确认气泡，挂在任意触发器上，就地确认危险操作；确定后先收起再回调，取消 / 点外部 / Esc 走 onCancel，展开即聚焦「取消」
  - calendar(props)：月历，整月网格内嵌页面（排期 / 值班 / 日程），每日可带 marker 标记文案，方向键漫游 + Enter 选中，翻月走 onMonthChange
  - typography(props)：排版文本，variant 决定语义（标题出 h1-h5 / 段落出 p / 行内出 span），支持语义色、装饰位、对齐、多行截断与复制按钮
  - grid(props, ...children)：栅格容器，columns 固定列数或 min 走 auto-fit 自适应列宽，gutter 统一列间距，窄屏自动降为单列
  - floatButton(props)：悬浮操作按钮，固定停靠左下 / 右下角，label 缺省为纯图标圆形，badge 走角标，tooltip 兼作 aria-label
  - mentions(props)：@提及输入，textarea 内键入 @ 弹候选（名字 / 关键词过滤），↑↓ 环形移动、Enter/Tab 选中、Esc 只收本层，选中按光标替换并写回 value
  - treeSelect(props)：树形选择，按钮触发弹层并复用 tree（搜索 / 多选 / 级联），单选选中即收起、多选保持展开，Esc 与点外收起
  - link(props)：链接，站内跳转与站外跳转统一入口，external 自动补 ↗ 与 rel=noopener noreferrer 并给读屏播报
  - avatarGroup(props)：头像组，横向叠放并在超出 max 时折叠成 +N，整组 title 列出全部姓名
  - virtualList(props)：虚拟列表，固定行高长列表只渲染可视窗口 + 上下缓冲条，万级数据滚动不随总量掉帧；返回 { el, scrollTo } 句柄
  - commandPalette(props)：命令面板，⌘K / Ctrl+K 唤起，输入即过滤（主文案/说明/关键词三层），↑↓ 环形选择 + 回车执行 + Esc 收起，选中与关闭都归还焦点；返回 { el, open, close } 句柄
  - timePicker(props)：时间选择，时 / 分两列弹层，value 信号双向绑定 HH:mm，分钟可配步长，Esc 收起
  - pinInput(props)：验证码输入，N 格单字符数字输入，输入自动进格、退格回删、方向键移格、粘贴自动分发，value 信号双向绑定，mask 可密文显示
  - copyButton(props)：复制按钮，点击把 text 写入剪贴板并短暂显示已复制，text 可传函数取实时值，clipboard API 不可用时降级 execCommand
  - countdown(props)：倒计时，秒级递减到 0 自动停表并触发 onFinish，缺省 mm:ss 展示，返回句柄 start/stop/reset
  - kbd(props)：键盘按键标记，键帽样式展示单个按键或组合键（多键以 + 连接），用于快捷键提示
  - highlight(props)：关键词高亮，命中片段包 mark（大小写不敏感全部命中），text / keyword 支持信号响应式刷新
  - inputTag(props)：标签输入，输入后回车 / 逗号成标签、chip 可单个删除、空框退格删末个，value 信号双向绑定，max 满额自动禁输
  - layout(props, ...children)：布局骨架，页头 / 侧栏 / 内容 / 页脚四区一次成型，侧栏可折叠（collapsed 信号双向绑定）
  - jsonViewer(props)：JSON 树查看，按层折叠、分支带计数摘要、叶子按类型着色，只读不编辑
  - diffView(props)：文本差异对比，行级 LCS 对齐 + 增删着色 + 双行号列，顶部带 +N / −N 统计
  - codeBlock(props)：代码块，等宽多行 + 行号列 + 标题行 + 一键复制原文，只展示不高亮
  - signaturePad(props)：手写签名板，指针绘制 + DPR 位图，返回 handle（el / clear / toDataURL / isEmpty）
  - loading(props, ...children)：区域加载遮罩，内容原地降透明度 + 转圈文案，带延迟出场避免快请求闪烁
  - relativeTime(props)：把时间戳渲染成「3 分钟前」并自动刷新，超阈值改显示绝对日期，title 恒给精确值
  - sparkline(props)：迷你趋势线，把数值序列压成折线（可填充 + 末点标记），无坐标轴无交互
  - heatmap(props)：日历热力图，按周列 × 星期行铺格子、四档浓度表示当天数量，悬停看明细
  - progressRing(props)：环形进度，SVG 双圆靠 dasharray 画弧 + 中心百分比，value 可传信号自动重绘
  - noticeBar(props)：单行通知条，语义色 + 左侧符号 + 可选跑马灯与关闭，适合页顶常驻播报
  - sortableList(props)：拖拽排序列表，整行可拖 + Alt+↑↓ 键盘搬位，返回 { el, move, order } 句柄
- 用法: `const checked = signal(false); checkbox({ label: '同意', checked }); const open = signal(false); modal({ title: '确认', open }, '内容')`
- 约定: 皮肤不持有业务状态，一律委托 headless 内核或调用方信号
- 约定: 表单类组件统一约定：*Props.value/checked/active 为 Signal 双向绑定，onChange/onInput 为回调
- 约定: 语义色 variant 四档：default|info / success / warning / danger，一律来自令牌，禁止硬编码颜色
- 约定: 无障碍基线：装饰性占位（skeleton）aria-hidden、加载指示（spinner）role=status、关闭按钮必须 aria-label、弹层弹窗 aria-haspopup/expanded、读屏可见的状态一律同步 aria-*

## @ui-arch/cli (v0.1.0)

- 类型: tooling · 目录: packages/tools/cli
- 描述: ua 命令行与 MCP 注册表服务：把各包 ua.manifest.json 汇总成机器可读索引（.ua/index.json）、Agent 全量文档（llms-full.txt）与人类文档站，并提供清单一致性门禁。
- API:
  - ua doctor：11 项环境与自洽预检（node / 依赖 / git 钩子与身份 / .ua 元数据可解析 / usage 串 ↔ dispatch 一致 / check 链覆盖全部门禁步骤 / CLI 清单声明的命令都有实现），任一失败退出码 1
  - ua index：扫描 packages/ 两层目录的 ua.manifest.json，生成 .ua/index.json 与 llms.txt
  - ua list：列出注册表内所有包与组件数；--json 输出「包 + 组件 id」结构化数组，--components 逐组件展开
  - ua info <包名|组件id>：包名返回摘要，组件 id 返回 props 表 + 步骤 + 示例；--json 输出原始清单，--md 直接给可粘贴的 Markdown 片段（标题 + 参数表 + 用法 + 示例）
  - ua tokens [关键词] [--json|--unused]：打印 --ua-* 令牌清单（颜色带暗色值）；--unused 反向列出皮肤包与令牌自身都没引用的令牌，用来收口令牌面
  - ua docs：生成人类文档站 apps/docs/index.html + demo.html 与 Agent 全量文档 llms-full.txt
  - ua style：注释规范门禁（导出必须 /*** ***/、接口字段行尾注释、行注释中文），违规退出码 1
  - ua verify：清单一致性门禁（id 唯一 / exports 对应 / props 必带 n t d / steps≥3 / demo 锚点存在 / 视觉回归抽查清单六组件各 ≥3 条且五维度齐全）
  - ua commit-lint <文件|message>：提交信息门禁（type 枚举 / scope 规则 / subject 中文祈使 ≤50 字符），规范见 COMMITTING.md，违规退出码 1
  - ua audit:visual [--json|--baseline]：视觉漂移门禁，统计皮肤包里各类硬编码视觉字面量（字号/动效时长/阴影/圆角/焦点环/内距/控件高度/字重/行高/层级/边框色）并与 .ua/visual-baseline.json 棘轮比对，超基线退出码 1；--baseline 重写基线，--json 出机器可读计数与每类命中行号（line / prop / value / hint，Agent 可直接定位）
  - ua audit:contrast [--json|--list]：对比度门禁，把令牌里 18 组「前景色 × 底色」配对按 WCAG 公式算成对比度（求值支持 var() 与 color-mix，半透明底先压到页面底色），亮/暗 × 常规/高对比四套分算，低于阈值（正文 7 / 常规 4.5 / 禁用 2.6 / 非文本 3）退出码 1；--json 出逐对明细，--list 只列配对表
  - ua audit:motion [--json]：动效兜底门禁，两类必查——① 带 infinite 的动画逐个核对是否在 prefers-reduced-motion 块里 animation: none；② 悬停 / 按压的位移（translate）是否在减少动效下归零（认 ua- 类通配的全局规则）。缺兜底退出码 1（--json 出逐条明细）
  - ua audit:surface [--json|--list]：表面阶梯门禁，逐档核对底色对底色的亮度比（页面底 → 表面 → 悬停底 → 按下底 ≥1.04、凹陷底 ≥1.02），亮/暗 × 常规/高对比四套主题各算一遍，不达标退出码 1；对比度只管文字读不读得清，管不到「悬停有没有反馈」（实测过 1.008 的悬停底）
  - ua mcp：零依赖 stdio MCP server，暴露 list_components / get_component / search_components / get_tokens / list_recipes / get_recipe；get_component 支持 format: md 直接取可粘贴的 Markdown 片段
  - ua loop [--json]：迭代循环诊断，一眼看清锁心跳（是否 15 分钟内）、上次留痕、backlog 待办与视觉欠账数，并给出本轮该不该抢锁、下一条该选谁；多实例错位接力时不必翻调度器数据库
- 用法: `node packages/tools/cli/bin/ua.js <index|list|info <包名|组件id> [--json|--md]|docs|tokens [--json|--unused]|style|verify|commit-lint|audit:visual|audit:contrast|audit:motion|doctor|mcp>；仓库内等价于 npm run index / docs / style / verify / audit:visual / audit:contrast / audit:motion / doctor`
- 约定: 零依赖：只用 node 标准库，Node >= 18
- 约定: 清单是单一来源：代码注释、文档站、llms-full.txt、MCP 全部从 ua.manifest.json 派生
- 约定: 门禁只增不改：新增校验必须能被人手复现，报错要指出文件与字段

## 组合配方（跨组件拼装）

> 全文见 `packages/tools/cli/recipes.md` 或 llms-full.txt；MCP 用 `list_recipes` / `get_recipe` 取骨架与要点。

- 配方 1：表单校验 + 提交反馈（2 条要点）
- 配方 2：危险操作二次确认（2 条要点）
- 配方 3：表格筛选 + 分页 + 批量操作（3 条要点）
- 配方 4：长列表数据加载与空态（2 条要点）
- 配方 5：数据表 + 独立分页器 + 导出（4 条要点）
- 配方 6：长表单编辑页（吸底操作条 + 提交锁定）（4 条要点）
- 配方 7：筛选栏（层级归属 + 日期区间）（3 条要点）
- 配方 8：评论输入（@ 提及 + 参与人头像组）（3 条要点）
- 配方 9：详情页排版（栅格 + 排版文本 + 描述列表）（3 条要点）
- 配方 10：暗色主题切换（只切 data-theme，不改令牌名）（3 条要点）
- 配方 11：数据看板筛选区（区间滑块 + 日期预设 + 分组下拉）（3 条要点）
- 配方 12：命令面板（⌘K 全局操作入口）（6 条要点）
- 配方 13：预约时点（日期 + 时间两段拼装）（5 条要点）
- 配方 14：标签筛选条 → 表格联动（5 条要点）
- 配方 15：表格分页与独立分页器联动（每页条数 + 受控页码）（4 条要点）
- 配方 16：后台页骨架（3 条要点）
- 配方 17：表格刷新遮罩（3 条要点）
- 配方 18：变更审阅面板（3 条要点）
- 配方 19：可排序的检查单（拖拽 + 键盘搬位 + 顺序回写）（5 条要点）