iter: d22 新增头像 avatar 组件

.ua/backlog.json

@@ -224,6 +224,14 @@
       "acceptance": "modal 关闭按钮补 type/aria-label、spinner 补 role=status + aria-label、skeleton 全形态 aria-hidden、tabs 的 tablist 补 aria-label 且禁用页签标 aria-disabled；manifest conventions 记录无障碍基线；npm run check 全绿",
       "status": "done",
       "notes": "纯属性级修复，不动结构与样式；tabIndex 漫游（仅激活页签可 Tab）此前已实现，本次只补语义；分页器审计后无需改动（已有 nav aria-label、页码 aria-current、‹› aria-label）"
+    },
+    {
+      "id": "d22",
+      "title": "新增头像 avatar 组件",
+      "motivation": "用户列表/评论区需要头像位，缺 component 只能手拼 img + 圆角；首字占位是缺图时的标准兜底",
+      "acceptance": "新增 avatar.ts：name 必填（alt / title / 首字来源），src 可选（有则图片、无则首字占位），size 可调，variant 四档语义底色；只消费 --ua-* 令牌；导出 / manifest / 文档 / llms-full.txt / demo 同步；npm run check 全绿",
+      "status": "done",
+      "notes": "首字占位对中文取首字、英文大写，空名兜底 ?；flex:none 保证不被挤压；首次跑 verify 被自身新门禁拦下（声明 sec-avatar 但 demo 缺区块），补独立区块后通过——门禁有效性再次得到验证"
     }
   ]
 }

.ua/index.json

@@ -1,6 +1,6 @@
 {
   "$schema": "ui-arch-registry-index/0.1",
-  "generatedAt": "2026-10-23T09:03:01.680Z",
+  "generatedAt": "2026-10-23T09:03:43.931Z",
   "repoRoot": ".",
   "packages": [
     {
@@ -130,7 +130,7 @@
     {
       "name": "@ui-arch/ui",
       "type": "skin-dom",
-      "description": "DOM 皮肤组件库：button / textField / textarea / slider / checkbox / switch / select / menu / radioGroup / accordion / breadcrumb / card / badge / tag / alert / toast / tooltip / popover / skeleton / spinner / progress / tabs / pagination / modal / drawer / form / formItem / dataTable，构建在 @ui-arch/frame 与 @ui-arch/table-core 之上，样式只消费 --ua-* 令牌。",
+      "description": "DOM 皮肤组件库：button / textField / textarea / slider / checkbox / switch / select / menu / radioGroup / accordion / breadcrumb / card / badge / tag / avatar / alert / toast / tooltip / popover / skeleton / spinner / progress / tabs / pagination / modal / drawer / form / formItem / dataTable，构建在 @ui-arch/frame 与 @ui-arch/table-core 之上，样式只消费 --ua-* 令牌。",
       "tags": [
         "components",
         "dom",
@@ -156,6 +156,7 @@
           "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 收起",
@@ -205,7 +206,8 @@
           "PopoverProps",
           "SliderProps",
           "TagProps",
-          "DrawerProps"
+          "DrawerProps",
+          "AvatarProps"
         ]
       },
       "usage": "const checked = signal(false); checkbox({ label: '同意', checked }); const open = signal(false); modal({ title: '确认', open }, '内容')",
@@ -216,7 +218,7 @@
         "无障碍基线：装饰性占位（skeleton）aria-hidden、加载指示（spinner）role=status、关闭按钮必须 aria-label、弹层弹窗 aria-haspopup/expanded、读屏可见的状态一律同步 aria-*"
       ],
       "docs": {
-        "intro": "27 个 DOM 组件，统一用法：组件是普通函数，传入 props 返回 DOM 节点；需要状态时先创建 signal 再双向绑定。引入 CSS：import '@ui-arch/ui/ui.css'（内部已消费 tokens）。",
+        "intro": "28 个 DOM 组件，统一用法：组件是普通函数，传入 props 返回 DOM 节点；需要状态时先创建 signal 再双向绑定。引入 CSS：import '@ui-arch/ui/ui.css'（内部已消费 tokens）。",
         "steps": [
           "安装依赖：pnpm add @ui-arch/ui @ui-arch/frame（workspace 内自动链接）",
           "引入样式：在应用入口 import '@ui-arch/ui/ui.css'，暗色主题在根元素设 data-theme='dark'",
@@ -738,6 +740,43 @@
               "标签是内联元素，可直接排进 .row 等容器，自动换行由容器决定"
             ]
           },
+          {
+            "id": "avatar",
+            "title": "头像 Avatar",
+            "demo": "sec-avatar",
+            "props": [
+              {
+                "n": "name",
+                "t": "string",
+                "r": 1,
+                "d": "名称：生成占位首字，并作为图片 alt 与悬停标题"
+              },
+              {
+                "n": "src",
+                "t": "string",
+                "d": "图片地址；缺省用首字占位"
+              },
+              {
+                "n": "size",
+                "t": "number",
+                "d": "直径像素；缺省 32",
+                "df": "32"
+              },
+              {
+                "n": "variant",
+                "t": "'default' | 'success' | 'warning' | 'danger'",
+                "d": "占位底色语义档；缺省 default",
+                "df": "default"
+              }
+            ],
+            "example": "avatar({ name: '张三' }); avatar({ name: 'Alice', size: 40, variant: 'success' })",
+            "steps": [
+              "只传 name：用名称首字做占位（中文取首字、英文大写），底色走 accent 淡化，暗色自动适配",
+              "有图片就传 src：渲染 img 并用 name 作 alt，读屏语义完整；图片缺失时由浏览器 alt 兜底",
+              "尺寸用 size（像素）控制，头像不参与布局拉伸（flex:none），可安全排进 .row 与表格单元格",
+              "需要区分类别（在线/告警）时用 variant 换底色档，颜色一律来自令牌"
+            ]
+          },
           {
             "id": "alert",
             "title": "提示条 Alert",

.ua/iterations.log

@@ -26,3 +26,4 @@
 {"time": "2026-10-23T17:01:46+08:00", "id": "d19", "result": "done", "summary": "dataTable 新增 selected 受控信号：与内核选择双向同步（内容比较 + 拷贝保护），demo 展示已选计数与清空；check 全绿"}
 {"time": "2026-10-23T17:02:24+08:00", "id": "d20", "result": "done", "summary": "progress 支持不确定态：value 可选，缺省时 35% 填充块往复 + aria-label 进行中；定量态补 aria-valuenow；demo/manifest/llms 同步，check 全绿"}
 {"time": "2026-10-23T17:03:02+08:00", "id": "d21", "result": "done", "summary": "无障碍收尾：modal × 补 aria-label/type、spinner role=status、skeleton aria-hidden、tablist aria-label + 禁用页签 aria-disabled；conventions 记录基线；check 全绿"}
+{"time": "2026-10-23T17:03:49+08:00", "id": "d22", "result": "done", "summary": "新增头像 avatar（src 图片 / 首字占位 + size + 四档语义底色），demo 独立 sec-avatar；中途被 verify 的 demo 锚点检查拦下已补；check 全绿"}

apps/demo/main.ts

@@ -2,6 +2,7 @@ import { h, mount, renderList, signal } from '@ui-arch/frame';
 import {
   accordion,
   alert,
+  avatar,
   badge,
   breadcrumb,
   button,
@@ -207,6 +208,19 @@ const content = h(
       return box;
     })(),
   ),
+  section(
+    'sec-avatar',
+    '头像',
+    'avatar：有 src 走图片（alt 用名称），无 src 用首字占位；size 与语义底色都可调。',
+    h(
+      'div',
+      { class: 'row' },
+      avatar({ name: '张三' }),
+      avatar({ name: 'Alice', size: 40, variant: 'success' }),
+      avatar({ name: 'Bob', size: 24, variant: 'warning' }),
+      avatar({ name: '李四', size: 36, variant: 'danger' }),
+    ),
+  ),
   section(
     'sec-slider',
     '滑块',

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 收起

llms.txt

@@ -45,7 +45,7 @@
 ## @ui-arch/ui (v0.1.0)
 
 - 类型: skin-dom · 目录: packages/skin/ui
-- 描述: DOM 皮肤组件库：button / textField / textarea / slider / checkbox / switch / select / menu / radioGroup / accordion / breadcrumb / card / badge / tag / alert / toast / tooltip / popover / skeleton / spinner / progress / tabs / pagination / modal / drawer / form / formItem / dataTable，构建在 @ui-arch/frame 与 @ui-arch/table-core 之上，样式只消费 --ua-* 令牌。
+- 描述: DOM 皮肤组件库：button / textField / textarea / slider / checkbox / switch / select / menu / radioGroup / accordion / breadcrumb / card / badge / tag / avatar / alert / toast / tooltip / popover / skeleton / spinner / progress / tabs / pagination / modal / drawer / form / formItem / dataTable，构建在 @ui-arch/frame 与 @ui-arch/table-core 之上，样式只消费 --ua-* 令牌。
 - API:
   - button(props)：按钮，variant = primary | ghost | danger，disabled 支持布尔或信号禁用
   - textField(props)：文本输入，value 信号双向绑定，disabled 支持布尔或信号禁用
@@ -61,6 +61,7 @@
   - 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 收起

packages/skin/ui/src/avatar.ts

@@ -0,0 +1,20 @@
+import { h } from '@ui-arch/frame';
+import type { AvatarProps } from './types.js';
+
+/*** 头像：有 src 渲染图片（alt 用名称），否则用名称首字做占位；尺寸与语义底色由 props 决定 ***/
+export function avatar(props: AvatarProps): HTMLElement {
+  const size = `${props.size ?? 32}px`;
+  return h(
+    'span',
+    { class: `ua-avatar ua-avatar-${props.variant ?? 'default'}`, style: `width:${size};height:${size}`, title: props.name },
+    props.src
+      ? h('img', { class: 'ua-avatar-img', src: props.src, alt: props.name })
+      : h('span', { class: 'ua-avatar-text', 'aria-label': props.name }, firstChar(props.name)),
+  );
+}
+
+/*** 取首个可见字符（中文取首字、英文取首字母大写） ***/
+function firstChar(name: string): string {
+  const c = name.trim().charAt(0);
+  return c ? c.toUpperCase() : '?'; // 空名兜底问号，避免空白圆
+}

packages/skin/ui/src/index.ts

@@ -13,6 +13,7 @@ export { breadcrumb } from './breadcrumb.js';
 export { card } from './card.js';
 export { badge } from './badge.js';
 export { tag } from './tag.js';
+export { avatar } from './avatar.js';
 export { alert } from './alert.js';
 export { toast, showToast } from './toast.js';
 export { tooltip } from './tooltip.js';

packages/skin/ui/src/types.ts

@@ -170,6 +170,14 @@ export interface BadgeProps {
   variant?: 'default' | 'success' | 'warning' | 'danger'; // 语义色；缺省 default
 }
 
+/*** 头像入参 ***/
+export interface AvatarProps {
+  name: string;   // 名称：生成占位首字，并作为图片 alt 与悬停标题
+  src?: string;   // 图片地址；缺省用首字占位
+  size?: number;  // 直径像素；缺省 32
+  variant?: 'default' | 'success' | 'warning' | 'danger'; // 占位底色语义档；缺省 default
+}
+
 /*** 标签入参（可关闭，与纯展示的 badge 区分） ***/
 export interface TagProps {
   label: string;   // 标签文案

packages/skin/ui/ua.manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "@ui-arch/ui",
   "type": "skin-dom",
-  "description": "DOM 皮肤组件库：button / textField / textarea / slider / checkbox / switch / select / menu / radioGroup / accordion / breadcrumb / card / badge / tag / alert / toast / tooltip / popover / skeleton / spinner / progress / tabs / pagination / modal / drawer / form / formItem / dataTable，构建在 @ui-arch/frame 与 @ui-arch/table-core 之上，样式只消费 --ua-* 令牌。",
+  "description": "DOM 皮肤组件库：button / textField / textarea / slider / checkbox / switch / select / menu / radioGroup / accordion / breadcrumb / card / badge / tag / avatar / alert / toast / tooltip / popover / skeleton / spinner / progress / tabs / pagination / modal / drawer / form / formItem / dataTable，构建在 @ui-arch/frame 与 @ui-arch/table-core 之上，样式只消费 --ua-* 令牌。",
   "tags": [
     "components",
     "dom",
@@ -27,6 +27,7 @@
       "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 收起",
@@ -76,7 +77,8 @@
       "PopoverProps",
       "SliderProps",
       "TagProps",
-      "DrawerProps"
+      "DrawerProps",
+      "AvatarProps"
     ]
   },
   "usage": "const checked = signal(false); checkbox({ label: '同意', checked }); const open = signal(false); modal({ title: '确认', open }, '内容')",
@@ -87,7 +89,7 @@
     "无障碍基线：装饰性占位（skeleton）aria-hidden、加载指示（spinner）role=status、关闭按钮必须 aria-label、弹层弹窗 aria-haspopup/expanded、读屏可见的状态一律同步 aria-*"
   ],
   "docs": {
-    "intro": "27 个 DOM 组件，统一用法：组件是普通函数，传入 props 返回 DOM 节点；需要状态时先创建 signal 再双向绑定。引入 CSS：import '@ui-arch/ui/ui.css'（内部已消费 tokens）。",
+    "intro": "28 个 DOM 组件，统一用法：组件是普通函数，传入 props 返回 DOM 节点；需要状态时先创建 signal 再双向绑定。引入 CSS：import '@ui-arch/ui/ui.css'（内部已消费 tokens）。",
     "steps": [
       "安装依赖：pnpm add @ui-arch/ui @ui-arch/frame（workspace 内自动链接）",
       "引入样式：在应用入口 import '@ui-arch/ui/ui.css'，暗色主题在根元素设 data-theme='dark'",
@@ -609,6 +611,43 @@
           "标签是内联元素，可直接排进 .row 等容器，自动换行由容器决定"
         ]
       },
+      {
+        "id": "avatar",
+        "title": "头像 Avatar",
+        "demo": "sec-avatar",
+        "props": [
+          {
+            "n": "name",
+            "t": "string",
+            "r": 1,
+            "d": "名称：生成占位首字，并作为图片 alt 与悬停标题"
+          },
+          {
+            "n": "src",
+            "t": "string",
+            "d": "图片地址；缺省用首字占位"
+          },
+          {
+            "n": "size",
+            "t": "number",
+            "d": "直径像素；缺省 32",
+            "df": "32"
+          },
+          {
+            "n": "variant",
+            "t": "'default' | 'success' | 'warning' | 'danger'",
+            "d": "占位底色语义档；缺省 default",
+            "df": "default"
+          }
+        ],
+        "example": "avatar({ name: '张三' }); avatar({ name: 'Alice', size: 40, variant: 'success' })",
+        "steps": [
+          "只传 name：用名称首字做占位（中文取首字、英文大写），底色走 accent 淡化，暗色自动适配",
+          "有图片就传 src：渲染 img 并用 name 作 alt，读屏语义完整；图片缺失时由浏览器 alt 兜底",
+          "尺寸用 size（像素）控制，头像不参与布局拉伸（flex:none），可安全排进 .row 与表格单元格",
+          "需要区分类别（在线/告警）时用 variant 换底色档，颜色一律来自令牌"
+        ]
+      },
       {
         "id": "alert",
         "title": "提示条 Alert",

packages/skin/ui/ui.css

@@ -546,6 +546,38 @@
   padding-bottom: 12px;
 }
 
+/* —— 头像 —— */
+.ua-avatar {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  border-radius: 50%;
+  overflow: hidden;
+  background: color-mix(in srgb, var(--ua-color-accent) 14%, transparent);
+  color: var(--ua-color-accent);
+  font-size: var(--ua-font-size-md);
+  font-weight: 500;
+  user-select: none;
+}
+.ua-avatar-img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+.ua-avatar-success {
+  background: color-mix(in srgb, var(--ua-color-success) 16%, transparent);
+  color: var(--ua-color-success);
+}
+.ua-avatar-warning {
+  background: color-mix(in srgb, var(--ua-color-warning) 18%, transparent);
+  color: var(--ua-color-warning);
+}
+.ua-avatar-danger {
+  background: color-mix(in srgb, var(--ua-color-danger) 16%, transparent);
+  color: var(--ua-color-danger);
+}
+
 /* —— 标签（可关闭） —— */
 .ua-tag {
   display: inline-flex;