@chenzy-design/svelte 0.1.0

package/src/autocomplete/AutoCompleteKbdFixture.svelte

@@ -0,0 +1,24 @@
+<!--
+  仅供 AutoComplete.kbd.test.ts（browser project）使用的键盘 e2e 夹具。
+  AutoComplete 输入框 role=combobox，焦点始终留在 input 上；建议浮层渲染在
+  .cd-autocomplete 内（非 portal），高亮走 aria-activedescendant 指向 option id。
+  夹具暴露 onSelect 写入 lastSelected，供测试断言 Enter 选中。
+-->
+<script lang="ts">
+  import { LocaleProvider } from '../locale-provider/index.js';
+  import AutoComplete from './AutoComplete.svelte';
+
+  const data = ['Apple', 'Apricot', 'Banana'];
+  let lastSelected = $state<unknown>(undefined);
+</script>
+
+<LocaleProvider locale="en_US">
+  <AutoComplete
+    {data}
+    ariaLabel="Fruit"
+    onSelect={(v) => {
+      lastSelected = v;
+    }}
+  />
+  <output data-testid="selected">{JSON.stringify(lastSelected ?? null)}</output>
+</LocaleProvider>

package/src/autocomplete/index.ts

@@ -0,0 +1,2 @@
+export { default as AutoComplete } from './AutoComplete.svelte';
+export { meta as autocompleteMeta } from './meta.js';

package/src/autocomplete/meta.ts

@@ -0,0 +1,41 @@
+/**
+ * Machine-readable component metadata for AI/docs consumption.
+ * See specs/00-foundation/ai-friendly.spec.md.
+ */
+export const meta = {
+  name: 'AutoComplete',
+  category: 'input',
+  description: '输入联想框，支持本地过滤候选、远程异步搜索、选项分组、内嵌标签与键盘选择。',
+  props: [
+    { name: 'value', type: 'string', default: 'undefined' },
+    { name: 'defaultValue', type: 'string', default: "''" },
+    { name: 'data', type: 'ItemOrGroup[]', default: '[]' },
+    { name: 'open', type: 'boolean', default: 'undefined' },
+    { name: 'defaultOpen', type: 'boolean', default: 'false' },
+    { name: 'placeholder', type: 'string', default: "''" },
+    { name: 'insetLabel', type: 'string|Snippet', default: 'undefined' },
+    { name: 'openOnFocus', type: 'boolean', default: 'false' },
+    { name: 'size', type: "'small'|'default'|'large'", default: 'default' },
+    { name: 'status', type: "'default'|'warning'|'error'", default: 'default' },
+    { name: 'disabled', type: 'boolean', default: 'false' },
+    { name: 'filter', type: 'boolean', default: 'true' },
+    { name: 'defaultActiveFirstOption', type: 'boolean', default: 'true' },
+    { name: 'clearable', type: 'boolean', default: 'false' },
+    { name: 'onSearch', type: '(query: string) => void', default: 'undefined' },
+    { name: 'loading', type: 'boolean', default: 'false' },
+    { name: 'searchDebounce', type: 'number', default: '300' },
+    { name: 'maxCount', type: 'number', default: '0' },
+    { name: 'onChange', type: '(v: string) => void', default: 'undefined' },
+    { name: 'onSelect', type: '(value: string|number) => void', default: 'undefined' },
+    { name: 'onOpenChange', type: '(open: boolean) => void', default: 'undefined' },
+  ],
+  a11y: {
+    role: 'combobox',
+    notes: [
+      'combobox + aria-autocomplete="list" + listbox',
+      'aria-activedescendant 指向高亮候选',
+      '键盘：↑↓ 移动、Enter 选中、Esc 关闭',
+    ],
+  },
+  tokens: ['--cd-input-*', '--cd-select-dropdown-*', '--cd-focus-ring', '--cd-motion-*'],
+} as const;

package/src/avatar/Avatar.a11y.test.ts

@@ -0,0 +1,37 @@
+// Avatar a11y：展示原子，含可交互态（href→<a> / onClick→role=button）。
+// 文字头像取 role=img + aria-label（来自 alt），避免逐字读缩写。
+import { describe, it, expect } from 'vitest';
+import { renderWithLocale, expectNoAxeViolations } from '../test-utils/a11y.js';
+import Avatar from './Avatar.svelte';
+
+describe('Avatar a11y', () => {
+  it('图片头像：img 带 alt，无 axe violations', async () => {
+    const { container } = renderWithLocale(Avatar, {
+      props: { src: 'https://example.com/a.png', alt: 'Jane Doe' },
+    });
+    const img = container.querySelector('img');
+    expect(img?.getAttribute('alt')).toBe('Jane Doe');
+    await expectNoAxeViolations(container);
+  });
+
+  it('文字头像：role=img + aria-label，无 axe violations', async () => {
+    const { container } = renderWithLocale(Avatar, {
+      props: { alt: 'Kim Lee' },
+    });
+    const root = container.querySelector('.cd-avatar');
+    expect(root?.getAttribute('role')).toBe('img');
+    expect(root?.getAttribute('aria-label')).toBe('Kim Lee');
+    await expectNoAxeViolations(container);
+  });
+
+  it('可交互（onClick）：role=button + tabindex=0 + aria-label，无 axe violations', async () => {
+    const { container } = renderWithLocale(Avatar, {
+      props: { alt: 'Settings', onClick: () => {} },
+    });
+    const root = container.querySelector('.cd-avatar');
+    expect(root?.getAttribute('role')).toBe('button');
+    expect(root?.getAttribute('tabindex')).toBe('0');
+    expect(root?.getAttribute('aria-label')).toBe('Settings');
+    await expectNoAxeViolations(container);
+  });
+});

package/src/avatar/Avatar.svelte

@@ -0,0 +1,315 @@
+<!--
+  Avatar — see specs/components/show/Avatar.spec.md
+  Display atom: image with text fallback, status dot, color hashing.
+-->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import { getAvatarGroupContext, type AvatarShape, type AvatarSizeEnum } from './context.js';
+
+  type AvatarStatus = 'default' | 'warning' | 'error';
+
+  interface Props {
+    src?: string;
+    srcset?: string;
+    alt?: string;
+    shape?: AvatarShape;
+    size?: AvatarSizeEnum | number;
+    color?: 'auto' | string;
+    status?: AvatarStatus;
+    dot?: boolean;
+    dotColor?: string;
+    gap?: number;
+    /** 可交互：跳转链接，渲染为 <a>（优先于 onClick 的 button 语义）。 */
+    href?: string;
+    /** 链接 target（仅 href 时生效）。 */
+    target?: string;
+    /** 可交互：点击回调；无 href 时根元素取 role=button + 键盘 Enter/Space 激活。 */
+    onClick?: (event: MouseEvent | KeyboardEvent) => void;
+    /** hover 时显示的遮罩层 Snippet。 */
+    hoverMask?: Snippet;
+    /** 右下角绝对定位标记 Snippet（如在线状态徽标）。 */
+    bottomSlot?: Snippet;
+    /** 右上角绝对定位标记 Snippet。 */
+    topSlot?: Snippet;
+    /** 额外传给 img 标签的属性（如 loading、decoding 等）。 */
+    imgAttr?: Record<string, string>;
+    /** img 加载失败回调。 */
+    onError?: (e: Event) => void;
+    children?: Snippet;
+  }
+
+  let {
+    src,
+    srcset,
+    alt,
+    shape: shapeProp,
+    size: sizeProp,
+    color = 'grey',
+    status = 'default',
+    dot = false,
+    dotColor,
+    gap = 3,
+    href,
+    target,
+    onClick,
+    hoverMask,
+    bottomSlot,
+    topSlot,
+    imgAttr,
+    onError,
+    children,
+  }: Props = $props();
+
+  // Avatar.Group may provide shared shape/size; the child's own prop wins,
+  // falling back to the group's value, then the standalone default.
+  const group = getAvatarGroupContext();
+  const shape = $derived(shapeProp ?? group?.getShape() ?? 'circle');
+  const size = $derived(sizeProp ?? group?.getSize() ?? 'default');
+
+  // image load failure → fall back to text/children
+  let failed = $state(false);
+  const showImage = $derived(!!src && !failed);
+
+  // text fallback: alt's first character (uppercased)
+  const fallbackText = $derived(alt ? alt.trim().charAt(0).toUpperCase() : '');
+
+  const sizeIsNumber = $derived(typeof size === 'number');
+
+  const palette = [
+    'var(--cd-color-blue-5)',
+    'var(--cd-color-green-5)',
+    'var(--cd-color-orange-6)',
+    'var(--cd-color-red-5)',
+    'var(--cd-color-primary)',
+  ];
+
+  function hashString(s: string): number {
+    let h = 0;
+    for (let i = 0; i < s.length; i += 1) {
+      h = (h << 5) - h + s.charCodeAt(i);
+      h |= 0;
+    }
+    return Math.abs(h);
+  }
+
+  const autoColor = $derived(palette[hashString(fallbackText || 'cd') % palette.length]);
+
+  // resolved background: 'auto' → hashed palette color; explicit color → inline value
+  const bgColor = $derived(
+    color === 'auto' ? autoColor : color === 'grey' ? undefined : color,
+  );
+
+  const dotBg = $derived(
+    dotColor ??
+      (status === 'error'
+        ? 'var(--cd-color-danger)'
+        : status === 'warning'
+          ? 'var(--cd-color-warning)'
+          : 'var(--cd-color-success)'),
+  );
+
+  const cls = $derived(
+    [
+      'cd-avatar',
+      `cd-avatar--${shape}`,
+      !sizeIsNumber && `cd-avatar--${size}`,
+    ]
+      .filter(Boolean)
+      .join(' '),
+  );
+
+  const rootStyle = $derived(
+    [
+      sizeIsNumber ? `inline-size:${size}px;block-size:${size}px` : '',
+      bgColor ? `background:${bgColor}` : '',
+      sizeIsNumber ? `font-size:${Math.round((size as number) / 2.4)}px` : '',
+    ]
+      .filter(Boolean)
+      .join(';'),
+  );
+
+  const textStyle = $derived(gap !== 0 ? `padding-inline:${gap}px` : '');
+  const ariaLabel = $derived(alt ?? fallbackText ?? undefined);
+
+  // 可交互语义（spec §6）：href→<a>；仅 onClick→role=button + tabindex=0 + 键盘激活；
+  // 纯展示头像不可聚焦。纯派生（红线 #2，render 期只读）。
+  const isLink = $derived(href != null);
+  const isButton = $derived(!isLink && onClick != null);
+  const interactive = $derived(isLink || isButton);
+  // 根元素标签：链接 a，可点击但非链接保持 span（role=button），纯展示 span。
+  const rootTag = $derived(isLink ? 'a' : 'span');
+
+  function handleError(e: Event) {
+    failed = true;
+    onError?.(e);
+  }
+
+  function handleClick(event: MouseEvent) {
+    onClick?.(event);
+  }
+
+  // role=button 时键盘 Enter/Space 激活（<a> 由原生处理，不接管）。
+  function handleKeydown(event: KeyboardEvent) {
+    if (!isButton) return;
+    if (event.key === 'Enter' || event.key === ' ') {
+      event.preventDefault();
+      onClick?.(event);
+    }
+  }
+</script>
+
+<!--
+  根元素：可交互时为 <a>（href）或带 role=button 的 <span>（onClick），并进入 Tab 序列；
+  纯展示时为 <span>，文字/图标头像取 role=img（避免逐字读缩写）。
+  交互根统一用 aria-label 命名（图片头像 alt 已在 <img>，文字头像取 ariaLabel）。
+-->
+<svelte:element
+  this={rootTag}
+  class={[cls, interactive && 'cd-avatar--interactive'].filter(Boolean).join(' ')}
+  style={rootStyle || undefined}
+  href={isLink ? href : undefined}
+  target={isLink ? target : undefined}
+  role={isButton ? 'button' : !interactive && !showImage ? 'img' : undefined}
+  tabindex={isButton ? 0 : undefined}
+  aria-label={interactive ? ariaLabel : showImage ? undefined : ariaLabel}
+  onclick={interactive ? handleClick : undefined}
+  onkeydown={isButton ? handleKeydown : undefined}
+>
+  {#if showImage}
+    <img
+      class="cd-avatar__img"
+      {src}
+      {srcset}
+      {alt}
+      {...(imgAttr ?? {})}
+      onerror={handleError}
+    />
+  {:else if children}
+    <span class="cd-avatar__text" style={textStyle || undefined}>{@render children()}</span>
+  {:else if fallbackText}
+    <span class="cd-avatar__text" style={textStyle || undefined}>{fallbackText}</span>
+  {/if}
+
+  {#if hoverMask}
+    <span class="cd-avatar__hover-mask" aria-hidden="true">{@render hoverMask()}</span>
+  {/if}
+
+  {#if topSlot}
+    <span class="cd-avatar__slot cd-avatar__slot--top" aria-hidden="true">{@render topSlot()}</span>
+  {/if}
+
+  {#if dot}
+    <span class="cd-avatar__dot" style="background:{dotBg}" aria-hidden="true"></span>
+  {/if}
+
+  {#if bottomSlot}
+    <span class="cd-avatar__slot cd-avatar__slot--bottom" aria-hidden="true">{@render bottomSlot()}</span>
+  {/if}
+</svelte:element>
+
+<style>
+  .cd-avatar {
+    position: relative;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    flex: 0 0 auto;
+    inline-size: var(--cd-avatar-size-default);
+    block-size: var(--cd-avatar-size-default);
+    background: var(--cd-avatar-bg);
+    color: var(--cd-avatar-color);
+    border-radius: var(--cd-avatar-radius);
+    overflow: hidden;
+    user-select: none;
+    font-weight: var(--cd-font-weight-medium);
+    line-height: 1;
+    vertical-align: middle;
+  }
+  .cd-avatar--circle {
+    border-radius: var(--cd-radius-full);
+  }
+  /* 可交互头像：指针手势 + 可见焦点环（<a> 还需重置文字装饰/继承色）。 */
+  .cd-avatar--interactive {
+    cursor: pointer;
+    text-decoration: none;
+    color: var(--cd-avatar-color);
+  }
+  .cd-avatar--interactive:focus-visible {
+    outline: none;
+    box-shadow: var(--cd-focus-ring);
+  }
+  .cd-avatar--extra-small {
+    inline-size: var(--cd-avatar-size-extra-small);
+    block-size: var(--cd-avatar-size-extra-small);
+    font-size: var(--cd-font-size-1);
+  }
+  .cd-avatar--small {
+    inline-size: var(--cd-avatar-size-small);
+    block-size: var(--cd-avatar-size-small);
+    font-size: var(--cd-font-size-1);
+  }
+  .cd-avatar--default {
+    inline-size: var(--cd-avatar-size-default);
+    block-size: var(--cd-avatar-size-default);
+    font-size: var(--cd-font-size-2);
+  }
+  .cd-avatar--large {
+    inline-size: var(--cd-avatar-size-large);
+    block-size: var(--cd-avatar-size-large);
+    font-size: var(--cd-font-size-3);
+  }
+  .cd-avatar--extra-large {
+    inline-size: var(--cd-avatar-size-extra-large);
+    block-size: var(--cd-avatar-size-extra-large);
+    font-size: var(--cd-font-size-4);
+  }
+  .cd-avatar__img {
+    inline-size: 100%;
+    block-size: 100%;
+    object-fit: cover;
+    display: block;
+  }
+  .cd-avatar__text {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    white-space: nowrap;
+  }
+  .cd-avatar__dot {
+    position: absolute;
+    inset-block-end: 0;
+    inset-inline-end: 0;
+    inline-size: 25%;
+    block-size: 25%;
+    min-inline-size: 6px;
+    min-block-size: 6px;
+    border-radius: var(--cd-radius-full);
+    box-shadow: 0 0 0 2px var(--cd-color-bg-0);
+  }
+  .cd-avatar__hover-mask {
+    position: absolute;
+    inset: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    background: rgba(0, 0, 0, 0.4);
+    color: var(--cd-color-text-inverse);
+    opacity: 0;
+    transition: opacity 0.15s ease;
+    border-radius: inherit;
+  }
+  .cd-avatar:hover .cd-avatar__hover-mask {
+    opacity: 1;
+  }
+  .cd-avatar__slot {
+    position: absolute;
+    inset-inline-end: 0;
+    display: inline-flex;
+  }
+  .cd-avatar__slot--top {
+    inset-block-start: 0;
+  }
+  .cd-avatar__slot--bottom {
+    inset-block-end: 0;
+  }
+</style>

package/src/avatar/AvatarGroup.svelte

@@ -0,0 +1,142 @@
+<!--
+  Avatar.Group — overlapping row of avatars.
+  Two modes:
+    1. data-driven `items` → supports maxCount collapse into a "+M" avatar
+       (collapse is a pure derived computation, no DOM measurement).
+    2. free-form `children` snippet → custom overlapping avatars, no collapse.
+  Group-level shape/size are shared to child Avatars via context; each child's
+  own prop still wins (red line: child override > group > standalone default).
+-->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import Avatar from './Avatar.svelte';
+  import { useLocale } from '../locale-provider/index.js';
+  import {
+    setAvatarGroupContext,
+    type AvatarShape,
+    type AvatarSizeEnum,
+  } from './context.js';
+
+  /** One member when using the data-driven `items` API. */
+  export interface AvatarGroupItem {
+    src?: string;
+    srcset?: string;
+    alt?: string;
+    color?: 'auto' | string;
+    /** text/initials fallback content */
+    content?: string;
+  }
+
+  interface Props {
+    /** data-driven members; enables maxCount collapse */
+    items?: AvatarGroupItem[];
+    /** show at most N avatars, the rest collapse into a "+M" avatar */
+    maxCount?: number;
+    /** shared shape for all child avatars (child prop overrides) */
+    shape?: AvatarShape;
+    /** shared size for all child avatars (child prop overrides) */
+    size?: AvatarSizeEnum | number;
+    /** overlap distance between adjacent avatars in px */
+    overlapFrom?: number;
+    /** click handler for the "+M" overflow avatar */
+    onMore?: () => void;
+    /** 自定义溢出头像渲染，参数为 {overlapList, count}。 */
+    renderMore?: Snippet<[{ overlapList: AvatarGroupItem[]; count: number }]>;
+    /** free-form avatars when not using `items` */
+    children?: Snippet;
+  }
+
+  let {
+    items,
+    maxCount,
+    shape,
+    size,
+    overlapFrom = 8,
+    onMore,
+    renderMore,
+    children,
+  }: Props = $props();
+
+  const loc = useLocale();
+
+  // share group config with descendant Avatars across the context boundary
+  setAvatarGroupContext({
+    getShape: () => shape,
+    getSize: () => size,
+  });
+
+  // pure collapse computation — slice visible items and count the rest.
+  const list = $derived(items ?? []);
+  const overlapList = $derived(list.slice(limit));
+  const limit = $derived(
+    typeof maxCount === 'number' && maxCount >= 0 ? maxCount : list.length,
+  );
+  const visible = $derived(list.slice(0, limit));
+  const restCount = $derived(Math.max(0, list.length - visible.length));
+
+  const groupStyle = $derived(`--cd-avatar-overlap:${overlapFrom}px`);
+</script>
+
+<div class="cd-avatar-group" style={groupStyle} role="group">
+  {#if items}
+    {#each visible as item, i (i)}
+      {@const { content, color, ...rest } = item}
+      <span class="cd-avatar-group__item">
+        <Avatar {...rest} color={color ?? 'grey'}>
+          {#if content}{content}{/if}
+        </Avatar>
+      </span>
+    {/each}
+    {#if restCount > 0}
+      <span class="cd-avatar-group__item">
+        {#if renderMore}
+          {@render renderMore({ overlapList, count: restCount })}
+        {:else if onMore}
+          <button type="button" class="cd-avatar-group__more-btn" onclick={onMore}>
+            <Avatar color="grey" alt={loc().t('Avatar.moreAlt', { count: restCount })}>+{restCount}</Avatar>
+          </button>
+        {:else}
+          <Avatar color="grey" alt={loc().t('Avatar.moreAlt', { count: restCount })}>+{restCount}</Avatar>
+        {/if}
+      </span>
+    {/if}
+  {:else if children}
+    {@render children()}
+  {/if}
+</div>
+
+<style>
+  .cd-avatar-group {
+    display: inline-flex;
+    align-items: center;
+  }
+  /* later avatars overlap (and sit above) the previous ones */
+  .cd-avatar-group :global(.cd-avatar),
+  .cd-avatar-group__item {
+    position: relative;
+  }
+  .cd-avatar-group > :global(.cd-avatar:not(:first-child)),
+  .cd-avatar-group__item:not(:first-child) {
+    margin-inline-start: calc(-1 * var(--cd-avatar-overlap, 8px));
+  }
+  /* ring so overlapping avatars read as separated */
+  .cd-avatar-group > :global(.cd-avatar),
+  .cd-avatar-group__item :global(.cd-avatar) {
+    box-shadow: 0 0 0 2px var(--cd-color-bg-0);
+  }
+  .cd-avatar-group__item :global(.cd-avatar) {
+    display: inline-flex;
+  }
+  .cd-avatar-group__more-btn {
+    display: inline-flex;
+    padding: 0;
+    border: 0;
+    background: transparent;
+    cursor: pointer;
+    border-radius: var(--cd-radius-full);
+  }
+  .cd-avatar-group__more-btn:focus-visible {
+    outline: 2px solid var(--cd-color-primary);
+    outline-offset: 2px;
+  }
+</style>

package/src/avatar/context.ts

@@ -0,0 +1,21 @@
+import { getContext, setContext } from 'svelte';
+
+export type AvatarShape = 'circle' | 'square';
+export type AvatarSizeEnum = 'extra-small' | 'small' | 'default' | 'large' | 'extra-large';
+
+export interface AvatarGroupContext {
+  // getters keep the shared config reactive to Group prop changes across the
+  // context boundary (reading a plain value would freeze the initial snapshot).
+  getShape: () => AvatarShape | undefined;
+  getSize: () => AvatarSizeEnum | number | undefined;
+}
+
+const KEY = Symbol('cd-avatar-group');
+
+export function setAvatarGroupContext(ctx: AvatarGroupContext): void {
+  setContext(KEY, ctx);
+}
+
+export function getAvatarGroupContext(): AvatarGroupContext | undefined {
+  return getContext<AvatarGroupContext | undefined>(KEY);
+}

package/src/avatar/index.ts

@@ -0,0 +1,10 @@
+import Avatar_ from './Avatar.svelte';
+import AvatarGroup from './AvatarGroup.svelte';
+
+export const Avatar: typeof Avatar_ & {
+  Group: typeof AvatarGroup;
+} = Object.assign(Avatar_, { Group: AvatarGroup });
+
+export { AvatarGroup };
+export { meta as avatarMeta } from './meta.js';
+export type { AvatarShape, AvatarSizeEnum, AvatarGroupContext } from './context.js';

package/src/avatar/meta.ts

@@ -0,0 +1,73 @@
+/**
+ * Machine-readable component metadata for AI/docs consumption.
+ * Avatar — see specs/components/show/Avatar.spec.md
+ */
+export const meta = {
+  name: 'Avatar',
+  category: 'show',
+  description:
+    '头像：支持图片(src/srcset)、加载失败降级到 children/alt 首字，circle/square 形状，枚举或自定义数字尺寸，color=auto 按文字哈希取色，右下角状态点。Avatar.Group 把多个头像重叠排列，items+maxCount 折叠出「+M」溢出头像，组级 shape/size 透传（子 Avatar 自身 prop 优先）。',
+  exports: ['Avatar', 'AvatarGroup'],
+  props: [
+    { name: 'src', type: 'string', default: 'undefined', desc: '图片地址' },
+    { name: 'srcset', type: 'string', default: 'undefined' },
+    { name: 'alt', type: 'string', default: 'undefined', desc: 'a11y 文本，也作文字降级来源' },
+    { name: 'shape', type: "'circle'|'square'", default: "'circle'" },
+    {
+      name: 'size',
+      type: "'extra-small'|'small'|'default'|'large'|'extra-large'|number",
+      default: "'default'",
+      desc: '枚举映射 token，number 内联 px',
+    },
+    {
+      name: 'color',
+      type: "'auto'|string",
+      default: "'grey'",
+      desc: 'auto 按文字哈希取预设色；具体色内联背景',
+    },
+    { name: 'status', type: "'default'|'warning'|'error'", default: "'default'", desc: '状态点色推导' },
+    { name: 'dot', type: 'boolean', default: 'false', desc: '右下角状态点' },
+    { name: 'dotColor', type: 'string', default: 'undefined', desc: '覆盖状态点颜色' },
+    { name: 'gap', type: 'number', default: '3', desc: '文字头像左右内距(px)' },
+    { name: 'href', type: 'string', default: 'undefined', desc: '可交互：跳转链接，根渲染为 <a>' },
+    { name: 'target', type: 'string', default: 'undefined', desc: '链接 target（仅 href 生效）' },
+    {
+      name: 'onClick',
+      type: '(e: MouseEvent|KeyboardEvent) => void',
+      default: 'undefined',
+      desc: '可交互：点击回调；无 href 时根取 role=button + 键盘 Enter/Space 激活',
+    },
+    { name: 'children', type: 'Snippet', default: 'undefined', desc: '文字/图标内容' },
+  ],
+  events: [{ name: 'click', desc: '可交互头像（href/onClick）被点击或键盘激活' }],
+  slots: [{ name: 'children', desc: '文字或图标降级内容' }],
+  a11y: {
+    hasRole: true,
+    focusable: false,
+    note: '图片头像用 <img alt>；纯文字头像 role=img + aria-label(alt 或文字)。可交互：href→<a>，仅 onClick→role=button + tabindex=0 + 键盘 Enter/Space；纯展示头像不可聚焦。',
+  },
+  tokens: [
+    '--cd-avatar-size-extra-small',
+    '--cd-avatar-size-small',
+    '--cd-avatar-size-default',
+    '--cd-avatar-size-large',
+    '--cd-avatar-size-extra-large',
+    '--cd-avatar-bg',
+    '--cd-avatar-color',
+    '--cd-avatar-radius',
+  ],
+  responsive: false,
+  examples: [
+    { title: '图片', code: '<Avatar src="/u.png" alt="用户" />' },
+    { title: '文字', code: '<Avatar color="auto" alt="陈" />' },
+    { title: '状态点', code: '<Avatar alt="A" dot status="error" />' },
+    {
+      title: '头像组折叠',
+      code: '<Avatar.Group maxCount={3} items={[{content:"陈"},{content:"李"},{content:"王"},{content:"赵"}]} />',
+    },
+    {
+      title: '头像组自定义',
+      code: '<Avatar.Group size="small"><Avatar>陈</Avatar><Avatar color="auto" alt="李" /></Avatar.Group>',
+    },
+  ],
+} as const;