@tfdesign/b-end 1.0.4

package/src/_b_end_runtime/components/AiSuggestionShared.jsx

@@ -0,0 +1,166 @@
+import { useState } from 'react';
+import Tooltip from './Tooltip';
+
+export const AI_REFRESH_CLASS = [
+  'inline-flex items-center justify-center shrink-0 size-[var(--spacing-4)]',
+  'rounded-full cursor-pointer',
+  'text-foreground-muted hover:text-foreground-secondary',
+  'opacity-0 group-hover:opacity-100 group-focus-within:opacity-100 group-data-[open=true]:opacity-100 transition-opacity duration-150',
+  'bg-transparent border-none p-0',
+  'transition-colors duration-150',
+].join(' ');
+
+export const AI_REFRESH_VISIBLE_CLASS = [
+  'inline-flex items-center justify-center shrink-0 size-[var(--spacing-4)]',
+  'rounded-full cursor-pointer',
+  'text-foreground-muted hover:text-foreground-secondary',
+  'opacity-100',
+  'bg-transparent border-none p-0',
+  'transition-colors duration-150',
+].join(' ');
+
+export const AI_REFRESH_TOOLTIP_TRIGGER_CLASS = 'inline-flex shrink-0 items-center justify-center';
+
+export const SUGGESTION_LIST_CLASS = [
+  'inline-flex w-full flex-col rounded-md p-1 gap-0.5',
+  'transition-opacity duration-150',
+].join(' ');
+
+export const SUGGESTION_ITEM_CLASS = [
+  'inline-flex w-full rounded-[6px] px-3 py-1',
+  'text-left text-sm leading-5 text-foreground-secondary',
+  'transition-opacity duration-150',
+  'disabled:cursor-not-allowed',
+].join(' ');
+
+export const AI_SUGGESTION_LIST_STYLE = {
+  background: 'var(--gradient-ai-fill-1)',
+};
+
+export const AI_SUGGESTION_ITEM_STYLE = {
+  background: 'transparent',
+};
+
+export const AI_SUGGESTION_ITEM_HOVER_STYLE = {
+  background: 'var(--gradient-ai-fill-2)',
+};
+
+export function rotateList(list, offset = 1) {
+  if (!Array.isArray(list) || list.length === 0) return [];
+  const safeOffset = ((offset % list.length) + list.length) % list.length;
+  if (safeOffset === 0) return [...list];
+  return [...list.slice(safeOffset), ...list.slice(0, safeOffset)];
+}
+
+function normalizeTextSuggestionGroup(items) {
+  const seen = new Set();
+  return (Array.isArray(items) ? items : [])
+    .map((item) => (typeof item === 'string' ? item.trim() : ''))
+    .filter((item) => {
+      if (!item || seen.has(item)) return false;
+      seen.add(item);
+      return true;
+    });
+}
+
+export function buildSuggestionGroupsFromFlatList(items, fallbackGroups = []) {
+  const baseGroup = normalizeTextSuggestionGroup(items);
+  if (baseGroup.length === 0) return [];
+  const serialized = new Set();
+  const groups = [];
+
+  const pushGroup = (group) => {
+    const normalized = normalizeTextSuggestionGroup(group);
+    if (normalized.length === 0) return;
+    const key = JSON.stringify(normalized);
+    if (serialized.has(key)) return;
+    serialized.add(key);
+    groups.push(normalized);
+  };
+
+  pushGroup(baseGroup);
+
+  if (baseGroup.length > 1) {
+    for (let offset = 1; offset < baseGroup.length; offset += 1) {
+      pushGroup(rotateList(baseGroup, offset));
+    }
+    pushGroup([...baseGroup].reverse());
+  }
+
+  fallbackGroups.forEach(pushGroup);
+  return groups;
+}
+
+const AI_REFRESH_ICON_MASK = `url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath fill='black' fill-rule='evenodd' clip-rule='evenodd' d='M1 12C1 6.47715 5.47715 2 11 2C13.7624 2 16.2648 3.12139 18.0735 4.93138C18.7132 5.57146 19.3981 6.36248 20 7.09444V4C20 3.44772 20.4477 3 21 3C21.5523 3 22 3.44772 22 4V10C22 10.5523 21.5523 11 21 11H15C14.4477 11 14 10.5523 14 10C14 9.44772 14.4477 9 15 9H18.9692C18.277 8.13128 17.4165 7.10335 16.6588 6.34511C15.2098 4.89514 13.2104 4 11 4C6.58172 4 3 7.58172 3 12C3 16.4183 6.58172 20 11 20C14.6457 20 17.7243 17.5605 18.6874 14.2227C18.8406 13.6921 19.3948 13.3861 19.9255 13.5392C20.4561 13.6923 20.7622 14.2466 20.609 14.7773C19.4055 18.9481 15.5605 22 11 22C5.47715 22 1 17.5228 1 12Z'/%3E%3C/svg%3E")`;
+const AI_REFRESH_ICON_STYLE = {
+  width: '16px',
+  height: '16px',
+  display: 'block',
+  flexShrink: 0,
+  backgroundImage: 'var(--gradient-ai-fill-3)',
+  maskImage: AI_REFRESH_ICON_MASK,
+  maskRepeat: 'no-repeat',
+  maskPosition: 'center',
+  maskSize: 'contain',
+  WebkitMaskImage: AI_REFRESH_ICON_MASK,
+  WebkitMaskRepeat: 'no-repeat',
+  WebkitMaskPosition: 'center',
+  WebkitMaskSize: 'contain',
+};
+
+export function AiRefreshGradientIcon() {
+  return <span aria-hidden="true" style={AI_REFRESH_ICON_STYLE} />;
+}
+
+export function AiRefreshButton({ onClick, ariaLabel = '刷新推荐', className = AI_REFRESH_CLASS }) {
+  return (
+    <Tooltip content="刷新推荐" placement="top" triggerClassName={AI_REFRESH_TOOLTIP_TRIGGER_CLASS}>
+      <button
+        type="button"
+        className={className}
+        onClick={onClick}
+        aria-label={ariaLabel}
+      >
+        <AiRefreshGradientIcon />
+      </button>
+    </Tooltip>
+  );
+}
+
+export default function AiSuggestionPanel({
+  suggestions,
+  onSelect,
+  getSuggestionKey,
+  getSuggestionLabel,
+  getSuggestionAriaLabel,
+}) {
+  const [hoveredSuggestionIndex, setHoveredSuggestionIndex] = useState(-1);
+
+  if (!Array.isArray(suggestions) || suggestions.length === 0) return null;
+
+  return (
+    <div className={SUGGESTION_LIST_CLASS} style={AI_SUGGESTION_LIST_STYLE}>
+      {suggestions.map((suggestion, index) => {
+        const key = getSuggestionKey?.(suggestion, index) ?? `${getSuggestionLabel?.(suggestion) || index}-${index}`;
+        const label = getSuggestionLabel?.(suggestion) ?? '';
+        const ariaLabel = getSuggestionAriaLabel?.(suggestion, index) ?? `采纳 AI 推荐内容 ${index + 1}`;
+        return (
+          <button
+            key={key}
+            type="button"
+            className={`${SUGGESTION_ITEM_CLASS} ${hoveredSuggestionIndex === index ? 'items-start' : 'items-center'}`}
+            style={hoveredSuggestionIndex === index ? AI_SUGGESTION_ITEM_HOVER_STYLE : AI_SUGGESTION_ITEM_STYLE}
+            onClick={() => onSelect?.(suggestion)}
+            onMouseEnter={() => setHoveredSuggestionIndex(index)}
+            onMouseLeave={() => setHoveredSuggestionIndex(-1)}
+            aria-label={ariaLabel}
+          >
+            <span className={hoveredSuggestionIndex === index ? 'block w-full whitespace-normal break-words' : 'block w-full truncate'}>
+              {label}
+            </span>
+          </button>
+        );
+      })}
+    </div>
+  );
+}

package/src/_b_end_runtime/components/Avatar.jsx

@@ -0,0 +1,325 @@
+import { useEffect, useState } from 'react';
+import defaultAvatarSrc from './avatar-assets/avatar-default.png';
+import Icon from './Icon';
+import { getRandomTeamAvatarSrc } from '../teamMembers';
+
+/**
+ * Avatar — B端基础头像组件（Tailwind 内联）
+ *
+ * 对齐 Figma Avatar 组件集，覆盖 2 种形状、6 档尺寸、6 种内容类型。
+ * 图片态在未传 src 或加载失败时会优先回退到本地成员头像素材，再兜底到内置默认头像；英文态 / 中文态可通过 label 覆盖默认示例文案。
+ *
+ * **何时用**：表格/会话/导航里标识「单个」用户、机器人或 AI；需要字母/中文占位或兜底轮廓时。
+ * **不用**：多人交叠缩略氛围 → 用 `AvatarGroup`；纯功能符号 → 用 `Icon`；可配置人数的成员列表 → 列表 + 多个 `Avatar`。
+ *
+ * @prop {'round'|'rect'} [shape='round'] — 头像形状，round 为圆形，rect 为 3px 圆角方形
+ * @prop {'xxs'|'mini'|'xs'|'s'|'default'|'m'} [size='default'] — 尺寸档位，对应 16 / 20 / 24 / 32 / 40 / 48px
+ * @prop {'image'|'eng'|'ch'|'fallback'|'robot'|'ai'} [type='image'] — 内容类型：图片 / 英文 / 中文 / 兜底 / 机器人 / AI头像
+ * @prop {string|null} [src=null] — 图片地址，仅 image 态生效；不传时默认随机使用本地成员头像图片素材
+ * @prop {string|null} [label=null] — 文本头像内容，仅 eng / ch 态生效
+ * @prop {string} [alt='头像'] — 图片替代文本，仅 image 态生效
+ * @prop {string} [className=''] — 自定义类名
+ * @prop {React.CSSProperties|undefined} [style=undefined] — 自定义内联样式
+ */
+
+/* ── 基础容器 ── */
+const BASE = [
+  'relative inline-flex shrink-0 items-center justify-center overflow-hidden align-middle select-none',
+  '[font-family:inherit]',
+].join(' ');
+
+/* ── 形状 → 圆角 ── */
+const SHAPE_CLASS = {
+  round: 'rounded-full',
+  rect: 'rounded-avatar',
+};
+
+/* ── 尺寸 → 边长 ── */
+const SIZE_CLASS = {
+  xxs: 'size-4',
+  mini: 'size-5',
+  xs: 'size-6',
+  s: 'size-8',
+  default: 'size-10',
+  m: 'size-12',
+};
+
+/* ── 类型 → 背景 / 文字色 ── */
+const TYPE_CLASS = {
+  image: 'bg-grey-100',
+  eng: 'bg-grey-300 text-white',
+  ch: 'text-white',
+  fallback: 'bg-grey-100 text-grey-200',
+  robot: 'bg-robot-500',
+  ai: '',
+};
+
+/* ── 中文态在不同形状下的底色 ── */
+const CHINESE_SHAPE_CLASS = {
+  round: 'bg-brand-500',
+  rect: 'bg-brand-500',
+};
+
+/* ── 图片态 → 保持原图完整，仅由容器尺寸与圆角决定头像形态 ── */
+const IMAGE_CLASS = {
+  xxs: '',
+  mini: '',
+  xs: '',
+  s: '',
+  default: '',
+  m: '',
+};
+
+/* ── 文本态 → 字号 / 行高 ── */
+const TEXT_CLASS = {
+  xxs: 'text-xs leading-4 [font-weight:var(--font-semibold)]',
+  mini: 'text-xs leading-4 [font-weight:var(--font-semibold)]',
+  xs: 'text-xs leading-4 [font-weight:var(--font-semibold)]',
+  s: 'text-lg leading-6 [font-weight:var(--font-semibold)]',
+  default: 'text-lg leading-6 [font-weight:var(--font-semibold)]',
+  m: 'text-xl leading-[28px] [font-weight:var(--font-semibold)]',
+};
+
+/* ── 兜底态 → 图形尺寸 ── */
+const FALLBACK_ICON_CLASS = {
+  xxs: 'size-[10px]',
+  mini: 'size-[12px]',
+  xs: 'size-[14px]',
+  s: 'size-[18px]',
+  default: 'size-[22px]',
+  m: 'size-[26px]',
+};
+
+/* ── 机器人态 → 设计稿 SVG 在完整画布内自带留白，直接铺满容器即可 ── */
+const ROBOT_ICON_CLASS = 'block size-full';
+
+/* ── AI态 → 参考图中的居中留白比例 ── */
+const AI_ICON_WRAP_CLASS = {
+  xxs: 'w-[62%] max-w-[10px]',
+  mini: 'w-[60%] max-w-[12px]',
+  xs: 'w-[58%] max-w-[14px]',
+  s: 'w-[56%] max-w-[18px]',
+  default: 'w-[54%] max-w-[22px]',
+  m: 'w-[52%] max-w-[26px]',
+};
+const AI_BACKGROUND_LAYER = 'pointer-events-none absolute inset-px rounded-[inherit]';
+const IMAGE_STROKE_LAYER = 'pointer-events-none absolute inset-0 z-10 rounded-[inherit] shadow-[inset_0_0_0_1px_var(--color-fill)]';
+const AI_CONTENT_LAYER = 'relative z-10 inline-flex items-center justify-center';
+
+/* ── 默认示例文案（对齐 Figma） ── */
+const DEFAULT_LABEL = {
+  eng: {
+    xxs: 'T',
+    mini: 'T',
+    xs: 'T',
+    s: 'TF',
+    default: 'TF',
+    m: 'TF',
+  },
+  ch: {
+    xxs: '体',
+    mini: '体',
+    xs: '体',
+    s: '体',
+    default: '体服',
+    m: '体服',
+  },
+};
+
+/* ── 图片层 ── */
+const IMAGE = [
+  'absolute inset-0 size-full object-contain object-center',
+  'pointer-events-none select-none',
+].join(' ');
+
+function FallbackGlyph({ className }) {
+  return (
+    <svg
+      viewBox="0 0 64 64"
+      aria-hidden="true"
+      className={['block', className].filter(Boolean).join(' ')}
+      xmlns="http://www.w3.org/2000/svg">
+      <g transform="translate(0 -4)">
+        <path
+          fill="currentColor"
+          d="M32 10c7.18 0 13 5.82 13 13s-5.82 13-13 13-13-5.82-13-13 5.82-13 13-13Zm0 32c13.81 0 25 7.16 25 16v4H7v-4c0-8.84 11.19-16 25-16Z"
+        />
+      </g>
+    </svg>
+  );
+}
+
+function RobotGlyph({ className }) {
+  return (
+    <svg
+      viewBox="0 0 48 48"
+      aria-hidden="true"
+      className={className}
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+    >
+      <path
+        className="fill-robot-50"
+        d="M24.0002 38.4398C12.2509 38.4787 7.57003 32.0143 7.50041 25.1558V25.1445C7.49622 24.5517 7.52425 23.959 7.58437 23.3692C7.66218 22.6321 7.75532 21.9092 7.86897 21.2038C8.9194 14.6084 11.4697 9.56512 14.2064 10.3647C14.2402 10.3739 14.276 10.3862 14.3088 10.3985C14.8371 10.5736 15.435 10.9309 16.0605 11.4029H16.0677C17.6669 12.6079 19.4545 14.549 20.765 16.0858C21.0629 16.4329 21.3352 16.7605 21.5758 17.0543L21.5932 17.0758C22.1135 17.7007 22.8584 18.0963 23.6674 18.1774C24.1788 18.2337 24.6961 18.1628 25.1735 17.9712C25.6509 17.7795 26.0736 17.4731 26.4041 17.0789C26.4111 17.0722 26.4177 17.0651 26.4236 17.0574C28.1723 14.9207 31.6143 10.9995 33.795 10.3637C36.8235 9.47912 39.6308 15.752 40.4171 23.3661C41.1911 30.8451 36.7661 38.4807 24.0002 38.4398Z"
+      />
+      <path
+        className="fill-robot-900"
+        d="M20.5989 29.1987C20.5913 29.534 20.4785 29.8585 20.2764 30.1263C19.9391 30.575 19.4646 30.9013 18.925 31.0559C17.764 31.4112 16.604 30.9873 16.3337 30.1078C16.0634 29.2284 16.7914 28.2271 17.9524 27.8718C18.6946 27.6456 19.4349 27.7377 19.9437 28.0623C20.2294 28.2341 20.4427 28.5042 20.5436 28.8219C20.5809 28.944 20.5995 29.071 20.5989 29.1987Z"
+      />
+      <path
+        className="fill-robot-900"
+        d="M21.8426 27.2135C21.8291 27.2588 21.8068 27.3011 21.7769 27.3378C21.747 27.3745 21.7102 27.405 21.6685 27.4275C21.6269 27.4499 21.5812 27.4639 21.5341 27.4686C21.487 27.4734 21.4394 27.4688 21.3941 27.4551L20.5996 27.2176V29.1403C20.5915 29.5086 20.4675 29.8651 20.2454 30.159H20.2403C20.193 30.1591 20.1462 30.1499 20.1024 30.1319C20.0587 30.1139 20.019 30.0875 19.9855 30.0541C19.952 30.0207 19.9255 29.981 19.9074 29.9374C19.8892 29.8937 19.8799 29.8469 19.8799 29.7996V26.7282C19.88 26.6722 19.8932 26.617 19.9184 26.5671C19.9436 26.5171 19.9803 26.4738 20.0253 26.4405C20.0703 26.4066 20.1227 26.3838 20.1782 26.3738C20.2337 26.3639 20.2907 26.3671 20.3447 26.3832L21.6009 26.7609C21.6468 26.7744 21.6894 26.7969 21.7265 26.827C21.7635 26.8571 21.7942 26.8944 21.8167 26.9365C21.8392 26.9786 21.8531 27.0248 21.8575 27.0724C21.8619 27.1199 21.8569 27.1679 21.8426 27.2135Z"
+      />
+      <path
+        className="fill-robot-900"
+        d="M32.3822 29.1987C32.3745 29.534 32.2617 29.8585 32.0596 30.1263C31.7223 30.575 31.2478 30.9013 30.7082 31.0559C29.5472 31.4112 28.3872 30.9873 28.1169 30.1078C27.8466 29.2284 28.5746 28.2271 29.7356 27.8718C30.4778 27.6456 31.2181 27.7377 31.7269 28.0623C32.0124 28.2344 32.2256 28.5043 32.3269 28.8219C32.3641 28.944 32.3827 29.071 32.3822 29.1987Z"
+      />
+      <path
+        className="fill-robot-900"
+        d="M33.604 27.2688C33.563 27.3463 33.496 27.407 33.4148 27.4401C33.3335 27.4732 33.2432 27.4767 33.1596 27.45L32.4215 27.2288C32.417 27.2276 32.4123 27.2274 32.4077 27.2282C32.4031 27.2291 32.3988 27.2309 32.3951 27.2337C32.3913 27.2365 32.3883 27.24 32.3861 27.2442C32.3839 27.2483 32.3827 27.2528 32.3826 27.2575V29.1403C32.3744 29.5086 32.2505 29.8651 32.0284 30.159C31.9811 30.1591 31.9342 30.1499 31.8905 30.1319C31.8468 30.1139 31.8071 30.0875 31.7736 30.0541C31.7401 30.0207 31.7135 29.981 31.6954 29.9374C31.6773 29.8937 31.668 29.8469 31.668 29.7996V26.7282C31.668 26.6722 31.6812 26.617 31.7065 26.5671C31.7317 26.5171 31.7683 26.4738 31.8133 26.4405C31.8584 26.4066 31.9108 26.3838 31.9662 26.3738C32.0217 26.3639 32.0788 26.3671 32.1328 26.3832L33.389 26.7609C33.4393 26.7763 33.4856 26.8025 33.5247 26.8376C33.5638 26.8728 33.5947 26.9162 33.6152 26.9646C33.6357 27.013 33.6453 27.0654 33.6434 27.1179C33.6415 27.1705 33.628 27.222 33.604 27.2688Z"
+      />
+      <path
+        className="stroke-robot-900"
+        d="M24.4765 31.7734C24.4765 32.401 23.8847 32.9099 23.1547 32.9099C22.4248 32.9099 21.833 32.398 21.833 31.7734"
+        strokeWidth="0.454199"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+      <path
+        className="stroke-robot-900"
+        d="M27.12 31.7734C27.12 32.401 26.5283 32.9099 25.7983 32.9099C25.0683 32.9099 24.4766 32.398 24.4766 31.7734"
+        strokeWidth="0.454199"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+      <path
+        className="fill-robot-900"
+        d="M25.7196 30.2304C25.3315 29.6683 24.6855 29.9713 24.4623 30.1116C24.2401 29.9713 23.5255 29.7103 23.2061 30.2304C22.6604 31.118 24.1818 31.9217 24.4551 31.9637H24.4705C24.7439 31.9217 26.3113 31.0873 25.7196 30.2304Z"
+      />
+      <path
+        className="fill-robot-100"
+        d="M13.7053 20.1578C13.4614 20.2941 13.186 20.3639 12.9066 20.3603C12.6272 20.3567 12.3536 20.2798 12.1133 20.1373C11.873 19.9947 11.6744 19.7916 11.5373 19.5481C11.4002 19.3046 11.3294 19.0294 11.3321 18.75C11.3608 16.0502 12.2986 12.7167 13.6449 12.7188C15.239 12.7188 16.744 14.7009 18.1016 16.2734C18.2807 16.4788 18.403 16.7273 18.4566 16.9945C18.5102 17.2616 18.4931 17.5381 18.4071 17.7966C18.321 18.0551 18.169 18.2867 17.9661 18.4685C17.7631 18.6502 17.5162 18.7759 17.2498 18.833C16.012 19.1062 14.8188 19.5521 13.7053 20.1578Z"
+      />
+      <path
+        className="fill-robot-100"
+        d="M34.3964 20.1568C34.6403 20.2934 34.9158 20.3634 35.1954 20.36C35.4749 20.3565 35.7486 20.2796 35.9891 20.137C36.2296 19.9944 36.4283 19.7912 36.5655 19.5476C36.7027 19.304 36.7734 19.0286 36.7706 18.7491C36.7419 16.0503 35.757 12.7157 34.4578 12.7178C32.8627 12.7178 31.3587 14.7009 30.0011 16.2735C29.8233 16.4788 29.702 16.7268 29.6491 16.9932C29.5962 17.2596 29.6136 17.5352 29.6995 17.7929C29.7855 18.0505 29.937 18.2814 30.1393 18.4627C30.3415 18.644 30.5875 18.7695 30.853 18.8269C32.0905 19.1024 33.2832 19.5501 34.3964 20.1568Z"
+      />
+      <path
+        className="fill-white"
+        d="M29.1824 29.7046C29.3097 29.7033 29.4314 29.6522 29.5215 29.5623C29.6116 29.4724 29.663 29.3507 29.6646 29.2234C29.6625 29.0962 29.611 28.9748 29.521 28.8848C29.431 28.7948 29.3096 28.7433 29.1824 28.7412C29.0551 28.7428 28.9334 28.7942 28.8435 28.8843C28.7536 28.9744 28.7025 29.0961 28.7012 29.2234C28.7033 29.3504 28.7546 29.4716 28.8444 29.5614C28.9342 29.6511 29.0554 29.7025 29.1824 29.7046Z"
+      />
+      <path
+        className="fill-white"
+        d="M17.6277 29.44C17.7552 29.4386 17.877 29.3874 17.9672 29.2973C18.0573 29.2071 18.1086 29.0852 18.1099 28.9578C18.1078 28.8306 18.0563 28.7093 17.9663 28.6195C17.8763 28.5297 17.7548 28.4784 17.6277 28.4766C17.5005 28.4779 17.3788 28.529 17.2889 28.619C17.1989 28.7089 17.1478 28.8305 17.1465 28.9578C17.1486 29.0848 17.1999 29.2061 17.2897 29.2961C17.3794 29.386 17.5006 29.4376 17.6277 29.44Z"
+      />
+    </svg>
+  );
+}
+
+export default function Avatar({
+  shape = 'round',
+  size = 'default',
+  type = 'image',
+  src = null,
+  label = null,
+  alt = '头像',
+  className = '',
+  style,
+  ...rest
+}) {
+  const resolvedShape = Object.prototype.hasOwnProperty.call(SHAPE_CLASS, shape) ? shape : 'round';
+  const resolvedSize = SIZE_CLASS[size] ? size : 'default';
+  const resolvedType = Object.prototype.hasOwnProperty.call(TYPE_CLASS, type) ? type : 'image';
+  const [fallbackImageSrc] = useState(() => getRandomTeamAvatarSrc() || defaultAvatarSrc);
+  const [imageSrc, setImageSrc] = useState(src || fallbackImageSrc);
+
+  useEffect(() => {
+    setImageSrc(src || fallbackImageSrc);
+  }, [fallbackImageSrc, src]);
+
+  const defaultLabel = DEFAULT_LABEL[resolvedType]?.[resolvedSize] ?? '';
+  const resolvedLabel = resolvedType === 'eng'
+    ? (label || defaultLabel).toUpperCase()
+    : (label || defaultLabel);
+  const mergedStyle = {
+    ...(resolvedType === 'ai' ? { background: 'var(--gradient-ai-fill-2)' } : null),
+    ...style,
+  };
+
+  const cls = [
+    BASE,
+    SIZE_CLASS[resolvedSize],
+    SHAPE_CLASS[resolvedShape],
+    TYPE_CLASS[resolvedType],
+    resolvedType === 'ch' ? CHINESE_SHAPE_CLASS[resolvedShape] : '',
+    className,
+  ].filter(Boolean).join(' ');
+  const content = {
+    image: (
+      <img
+        alt={alt}
+        src={imageSrc}
+        className={[IMAGE, IMAGE_CLASS[resolvedSize]].join(' ')}
+        draggable="false"
+        onError={() => {
+          if (imageSrc !== fallbackImageSrc) {
+            setImageSrc(fallbackImageSrc);
+          } else if (imageSrc !== defaultAvatarSrc) {
+            setImageSrc(defaultAvatarSrc);
+          }
+        }}
+      />
+    ),
+    eng: (
+      <span
+        className={[
+          'block max-w-[90%] overflow-hidden text-ellipsis whitespace-nowrap uppercase',
+          TEXT_CLASS[resolvedSize],
+        ].join(' ')}
+      >
+        {resolvedLabel}
+      </span>
+    ),
+    ch: (
+      <span
+        className={[
+          'block max-w-[90%] overflow-hidden text-ellipsis whitespace-nowrap',
+          TEXT_CLASS[resolvedSize],
+        ].join(' ')}
+      >
+        {resolvedLabel}
+      </span>
+    ),
+    fallback: <FallbackGlyph className={FALLBACK_ICON_CLASS[resolvedSize]} />,
+    robot: <RobotGlyph className={ROBOT_ICON_CLASS} />,
+    ai: (
+      <span className={[AI_CONTENT_LAYER, AI_ICON_WRAP_CLASS[resolvedSize]].join(' ')}>
+        <Icon
+          name="hiai-logo"
+          size="xl"
+          className="size-full"
+          aria-hidden="true"
+        />
+      </span>
+    ),
+  }[resolvedType];
+
+  return (
+    <span className={[`tfds-avatar`, cls].filter(Boolean).join(' ')} style={mergedStyle} {...rest} data-tfds-component="Avatar">
+      {resolvedType === 'image' ? (
+        <span
+          aria-hidden="true"
+          className={IMAGE_STROKE_LAYER}
+        />
+      ) : null}
+      {resolvedType === 'ai' ? (
+        <span
+          aria-hidden="true"
+          className={AI_BACKGROUND_LAYER}
+          style={{ background: 'var(--gradient-ai-fill-1)' }}
+        />
+      ) : null}
+      {content}
+    </span>
+  );
+}

package/src/_b_end_runtime/components/Avatar.tokens.js

@@ -0,0 +1,76 @@
+/**
+ * Avatar — TOKEN_MAP（供平台属性面板展示）
+ *
+ * 分组顺序：容器 → 类型 → 图片 → 尺寸
+ */
+export const AVATAR_TOKEN_MAP = {
+  base: [],
+  外框: [
+    { label: '裁切', cssProp: 'overflow', value: 'hidden' },
+    { label: '圆角', cssProp: 'border-radius', token: '--radius-full', value: '9999px', state: 'round' },
+    { label: '圆角', cssProp: 'border-radius', token: '--radius-avatar', value: '3px', state: 'rect' },
+  ],
+  图片层: [
+    { label: '适配', cssProp: 'object-fit', value: 'cover' },
+    { label: '定位', cssProp: 'object-position', value: 'center top' },
+  ],
+  英文态: [
+    { label: '背景色', cssProp: 'background', token: '--color-grey-300', value: '#A7A8B0' },
+    { label: '文字色', cssProp: 'color', token: '--color-white', value: '#FFFFFF', semanticRef: 'text-inverse' },
+    { label: '字重', cssProp: 'font-weight', token: '--font-semibold', value: '600（运行时使用 [font-weight:var(--font-semibold)]）' },
+  ],
+  中文态: [
+    { label: '圆形底色', cssProp: 'background', token: '--color-brand-500', value: '#56D3BC', semanticRef: 'status-primary', state: 'round' },
+    { label: '方形底色', cssProp: 'background', token: '--color-orange-500', value: '#FA8B14', semanticRef: 'status-warning', state: 'rect' },
+    { label: '文字色', cssProp: 'color', token: '--color-white', value: '#FFFFFF', semanticRef: 'text-inverse' },
+    { label: '字重', cssProp: 'font-weight', token: '--font-semibold', value: '600（运行时使用 [font-weight:var(--font-semibold)]）' },
+  ],
+  兜底态: [
+    { label: '背景色', cssProp: 'background', token: '--color-grey-100', value: '#E6E7EA' },
+    { label: '图形色', cssProp: 'color', token: '--color-grey-200', value: '#C6C7CD' },
+  ],
+  机器人态: [
+    { label: '背景色', cssProp: 'background', token: '--color-robot-500', value: '#24B9D9' },
+    { label: '图形主色', cssProp: 'fill', token: '--color-robot-50', value: '#FCFCFC' },
+    { label: '耳朵底色', cssProp: 'fill', token: '--color-robot-100', value: '#EDEDED' },
+    { label: '五官色', cssProp: 'fill / stroke', token: '--color-robot-900', value: '#000000' },
+    { label: '高光色', cssProp: 'fill', token: '--color-white', value: '#FFFFFF' },
+  ],
+  AI头像态: [
+    { label: '背景色', cssProp: 'background', token: '--gradient-ai-fill-1', value: 'linear-gradient(90deg, rgba(230, 247, 244, 1) 0%, rgba(239, 246, 255, 1) 55%, rgba(243, 245, 255, 1) 90%, rgba(252, 243, 255, 1) 100%)' },
+    { label: '图形来源', cssProp: 'component', value: 'Icon / hiai-logo' },
+    { label: '图形颜色', cssProp: '—', value: '使用图标内置渐变与高光，不额外覆写 color' },
+  ],
+  sizes: {
+    xxs: [
+      { label: '边长', cssProp: 'width / height', token: '--spacing-4', value: '16px' },
+      { label: '字体', cssProp: 'font-size', token: '--text-xs', value: '12px' },
+      { label: '行高', cssProp: 'line-height', token: '--spacing-4', value: '16px' },
+    ],
+    mini: [
+      { label: '边长', cssProp: 'width / height', token: '--spacing-5', value: '20px' },
+      { label: '字体', cssProp: 'font-size', token: '--text-xs', value: '12px' },
+      { label: '行高', cssProp: 'line-height', token: '--spacing-4', value: '16px' },
+    ],
+    xs: [
+      { label: '边长', cssProp: 'width / height', token: '--spacing-6', value: '24px' },
+      { label: '字体', cssProp: 'font-size', token: '--text-xs', value: '12px' },
+      { label: '行高', cssProp: 'line-height', token: '--spacing-4', value: '16px' },
+    ],
+    s: [
+      { label: '边长', cssProp: 'width / height', token: '--spacing-8', value: '32px' },
+      { label: '字体', cssProp: 'font-size', token: '--text-lg', value: '18px' },
+      { label: '行高', cssProp: 'line-height', token: '--spacing-6', value: '24px' },
+    ],
+    default: [
+      { label: '边长', cssProp: 'width / height', token: '--spacing-10', value: '40px' },
+      { label: '字体', cssProp: 'font-size', token: '--text-lg', value: '18px' },
+      { label: '行高', cssProp: 'line-height', token: '--spacing-6', value: '24px' },
+    ],
+    m: [
+      { label: '边长', cssProp: 'width / height', token: '--spacing-12', value: '48px' },
+      { label: '字体', cssProp: 'font-size', token: '--text-xl', value: '20px' },
+      { label: '行高', cssProp: 'line-height', value: '28px' },
+    ],
+  },
+};

package/src/_b_end_runtime/components/AvatarGridPreview.jsx

@@ -0,0 +1,56 @@
+import Avatar from './Avatar';
+import { getTeamMemberByName } from '../teamMembers';
+
+const MATRIX_SIZES = ['xxs', 'mini', 'xs', 's', 'default', 'm'];
+const SCENE_TYPES = ['image', 'eng', 'ch', 'fallback', 'robot', 'ai'];
+const SCENE_FILTERS = ['all', ...SCENE_TYPES];
+const PREVIEW_IMAGE_MEMBER = getTeamMemberByName('程程murphy');
+
+function AvatarSection({ shape, rows }) {
+  return (
+    <div className="flex flex-col gap-8">
+      {rows.map((rowType) => (
+        <div key={`${shape}-${rowType}`} className="flex items-end gap-5">
+          {MATRIX_SIZES.map((rowSize) => (
+            <Avatar
+              key={`${shape}-${rowType}-${rowSize}`}
+              shape={shape}
+              size={rowSize}
+              type={rowType}
+              src={rowType === 'image' ? PREVIEW_IMAGE_MEMBER?.avatarSrc : undefined}
+              alt={rowType === 'image' ? PREVIEW_IMAGE_MEMBER?.name || '程程头像' : undefined}
+            />
+          ))}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+export default function AvatarGridPreview({
+  previewMode = 'matrix',
+  shape = 'round',
+  size = 'default',
+  type = 'image',
+}) {
+  const resolvedShape = shape === 'rect' ? 'rect' : 'round';
+  const resolvedType = SCENE_FILTERS.includes(type) ? type : 'all';
+  const matrixRows = resolvedType === 'all' ? SCENE_TYPES : [resolvedType];
+  const singleType = resolvedType === 'all' ? 'image' : resolvedType;
+
+  if (previewMode === 'single') {
+    return (
+      <Avatar
+        shape={resolvedShape}
+        size={size}
+        type={singleType}
+        src={singleType === 'image' ? PREVIEW_IMAGE_MEMBER?.avatarSrc : undefined}
+        alt={singleType === 'image' ? PREVIEW_IMAGE_MEMBER?.name || '程程头像' : undefined}
+      />
+    );
+  }
+
+  return (
+    <AvatarSection shape={resolvedShape} rows={matrixRows} />
+  );
+}