iter: d22 新增头像 avatar 组件

llms-full.txt

@@ -1,6 +1,6 @@
 # @ui-arch 组件库 Agent 文档（无图形版）
 
-> 自动生成于 2026-10-23T09:03:01.680Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
+> 自动生成于 2026-10-23T09:03:43.931Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
 
 ## 快速上手
@@ -48,7 +48,7 @@
 
 ## @ui-arch/ui（skin-dom）v0.1.0
 
-27 个 DOM 组件，统一用法：组件是普通函数，传入 props 返回 DOM 节点；需要状态时先创建 signal 再双向绑定。引入 CSS：import '@ui-arch/ui/ui.css'（内部已消费 tokens）。
+28 个 DOM 组件，统一用法：组件是普通函数，传入 props 返回 DOM 节点；需要状态时先创建 signal 再双向绑定。引入 CSS：import '@ui-arch/ui/ui.css'（内部已消费 tokens）。
 
 ### button — 按钮 Button
 
@@ -384,6 +384,30 @@ tag({ label: '前端', variant: 'info', closable: true, onClose: () => remove('
 
 现场演示：apps/docs/demo.html#sec-tag
 
+### avatar — 头像 Avatar
+
+参数：
+
+- name（必填）：string —— 名称：生成占位首字，并作为图片 alt 与悬停标题
+- src：string —— 图片地址；缺省用首字占位
+- size（默认 32）：number —— 直径像素；缺省 32
+- variant（默认 default）：'default' | 'success' | 'warning' | 'danger' —— 占位底色语义档；缺省 default
+
+示例：
+
+```
+avatar({ name: '张三' }); avatar({ name: 'Alice', size: 40, variant: 'success' })
+```
+
+手把手：
+
+1. 只传 name：用名称首字做占位（中文取首字、英文大写），底色走 accent 淡化，暗色自动适配
+2. 有图片就传 src：渲染 img 并用 name 作 alt，读屏语义完整；图片缺失时由浏览器 alt 兜底
+3. 尺寸用 size（像素）控制，头像不参与布局拉伸（flex:none），可安全排进 .row 与表格单元格
+4. 需要区分类别（在线/告警）时用 variant 换底色档，颜色一律来自令牌
+
+现场演示：apps/docs/demo.html#sec-avatar
+
 ### alert — 提示条 Alert
 
 参数：
@@ -737,6 +761,7 @@ API 速览：
 - 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 = info | success | warning | danger
 - toast.info/success/warning/error(message, duration?)：消息提示工厂，右上角堆叠，默认 3s 自动消失，出入场微动画；showToast(props) 为完整入参版本（closable 显示关闭按钮，同屏最多 4 条）
 - tooltip(props, trigger)：悬浮提示，包裹触发器，hover / focus 延迟 150ms 出场，移出 / 失焦 / Esc 收起