@chenzy-design/svelte 0.1.0

package/src/side-sheet/meta.ts

@@ -0,0 +1,116 @@
+/**
+ * Machine-readable component metadata for AI/docs consumption.
+ * SideSheet — see specs/components/feedback/SideSheet.spec.md
+ */
+export const meta = {
+  name: 'SideSheet',
+  category: 'feedback',
+  stage: 'M5',
+  semiEquivalent: 'SideSheet',
+  description:
+    '侧边滑出浮层：从视口四边（left/right/top/bottom）滑入的容器，承载次要任务流/详情/筛选/表单，比 Modal 提供更大可滚动内容区。与 Modal 同构复用浮层基建——portal 到 body（或 getContainer）脱离父层叠上下文；role=dialog，mask 时加 aria-modal；useFocusTrap 焦点捕获与归还（仅 mask=true）、useDismiss Esc 关闭（closeOnEsc），mask 时 useScrollLock 锁背景滚动（可 disableScrollLock 关闭）。mask=true 模态（遮罩+锁滚+陷阱），mask=false 非模态（无遮罩、不锁滚动、不抢焦点，outsideClosable 时点外部关闭）。size(small/default/large) 预设宽（横向）/高（纵向），width/height 显式覆盖；窄视口近铺满。Header/Body/Footer 三段式，footer 暴露 close()。滑入过渡为 CSS transform/opacity（token 时长缓动，reduced-motion 与 motionDisabled 退化为即时显隐）。lazyMount 首开前惰性挂载，destroyOnClose 关闭即卸载内容（出场过渡结束后 onAfterClose）。堆叠 z-index 复用 modal/z-stack 模块级计数器，与 Modal 统一层栈、后开者在上、Esc 仅关栈顶。受控 open（不回写），仅经 onOpenChange({open, reason}) 通知，reason 覆盖 esc/mask/outside/closeButton/programmatic。',
+  exports: ['SideSheet'],
+  a11yPattern: 'dialog-modal',
+  apgRef: 'dialog (modal)',
+  replaces: ['Drawer'],
+  relatedComponents: ['Modal', 'Popover', 'Notification'],
+  usageHints:
+    '承载次要任务流/详情/筛选；模态用 mask=true，协作式（打开仍可操作主页面）用 mask=false。承载单一确认/决策用 Modal，不要混用。',
+  dangerousActions:
+    'footer 危险操作（删除/清空等不可逆）使用 --cd-color-danger 与具体动词文案，并由业务侧拦截 onOpenChange 对未保存内容做二次确认。',
+  props: [
+    { name: 'open', type: 'boolean', default: 'false', desc: '受控显隐；受控时不回写，仅 onOpenChange 通知' },
+    { name: 'placement', type: "'left'|'right'|'top'|'bottom'", default: "'right'", desc: '滑出方向（贴附边缘）；RTL 下 left/right 镜像' },
+    { name: 'size', type: "'small'|'default'|'large'", default: "'default'", desc: '预设尺度（横向→宽度，纵向→高度）' },
+    { name: 'width', type: 'number|string', default: 'undefined', desc: 'left/right 显式宽度，覆盖 size；数字按 px' },
+    { name: 'height', type: 'number|string', default: 'undefined', desc: 'top/bottom 显式高度，覆盖 size；数字按 px' },
+    { name: 'title', type: 'string', default: 'undefined', desc: '标题文案' },
+    { name: 'titleSnippet', type: 'Snippet', default: 'undefined', desc: '自定义标题区，覆盖 title' },
+    { name: 'headerExtra', type: 'Snippet', default: 'undefined', desc: 'Header 右侧额外操作（关闭按钮之前）' },
+    { name: 'closeIcon', type: 'Snippet', default: 'undefined', desc: '自定义关闭图标' },
+    { name: 'mask', type: 'boolean', default: 'true', desc: '显示遮罩并以模态呈现（锁滚动+focus trap）；false 非模态' },
+    { name: 'maskClosable', type: 'boolean', default: 'true', desc: '点击遮罩是否关闭（mask=true 生效）' },
+    { name: 'outsideClosable', type: 'boolean', default: 'false', desc: 'mask=false 时点击面板外部是否关闭' },
+    { name: 'closeOnEsc', type: 'boolean', default: 'true', desc: '按 Esc 是否关闭（仅作用于浮层栈顶）' },
+    { name: 'closable', type: 'boolean', default: 'true', desc: 'Header 是否显示关闭按钮' },
+    { name: 'lazyMount', type: 'boolean', default: 'true', desc: '首次打开前是否惰性挂载内容' },
+    { name: 'keepDOM', type: 'boolean', default: 'undefined', desc: 'true 时保留 DOM（禁用惰性挂载）；lazyMount 优先' },
+    { name: 'destroyOnClose', type: 'boolean', default: 'false', desc: '关闭后是否销毁内部内容（出场过渡结束后卸载），重开重建' },
+    { name: 'getContainer', type: '() => HTMLElement | null', default: '() => document.body', desc: 'Portal 挂载容器' },
+    { name: 'zIndex', type: 'number', default: '1000', desc: '浮层基准层级（栈内自动递增）' },
+    { name: 'disableScrollLock', type: 'boolean', default: 'false', desc: '强制不锁背景滚动（即便 mask=true）' },
+    { name: 'returnFocusTo', type: 'HTMLElement | (() => HTMLElement | null) | null', default: '触发元素', desc: '关闭后焦点返回目标' },
+    { name: 'motionDisabled', type: 'boolean', default: 'false', desc: '关闭进出动效（独立于 reduced-motion）' },
+    { name: 'footer', type: 'Snippet<[{ close: () => void }]>|null', default: 'undefined', desc: 'Footer 操作区；提供 close() 关闭面板；未提供不渲染' },
+    { name: 'children', type: 'Snippet', default: 'undefined', desc: 'Body 主内容区（可滚动）' },
+    { name: 'ariaLabel', type: 'string', default: 'undefined', desc: '无可见标题时提供 aria-label' },
+    { name: 'class', type: 'string', default: 'undefined', desc: '面板自定义类名' },
+    { name: 'bodyClass', type: 'string', default: 'undefined', desc: 'Body 自定义类名' },
+    { name: 'maskClass', type: 'string', default: 'undefined', desc: '遮罩自定义类名' },
+    { name: 'onOpenChange', type: '(e: { open: boolean; reason: Reason }) => void', default: 'undefined', desc: '显隐意图变化（受控，需外部回写 open）' },
+    { name: 'onAfterOpen', type: '() => void', default: 'undefined', desc: '进入动效结束、内容完全可见后触发' },
+    { name: 'onAfterClose', type: '() => void', default: 'undefined', desc: '退出动效结束、DOM 卸载后触发' },
+    { name: 'onCancel', type: '(e: { reason: Reason }) => void', default: 'undefined', desc: '用户主动取消（Esc/遮罩/外部/关闭按钮）' },
+  ],
+  events: [
+    { name: 'onOpenChange', desc: '显隐意图变化，payload { open, reason: esc|mask|outside|closeButton|programmatic }' },
+    { name: 'onAfterOpen', desc: '进入动效结束后触发' },
+    { name: 'onAfterClose', desc: '退出动效结束、DOM 卸载后触发' },
+    { name: 'onCancel', desc: '用户主动取消，payload { reason }' },
+  ],
+  slots: [
+    { name: 'children', desc: 'Body 主内容区（可滚动）' },
+    { name: 'titleSnippet', desc: '自定义标题区，覆盖 title' },
+    { name: 'headerExtra', desc: 'Header 右侧额外操作（关闭按钮之前）' },
+    { name: 'footer', desc: 'Footer 操作区，提供 close()' },
+    { name: 'closeIcon', desc: '自定义关闭图标' },
+  ],
+  a11y: {
+    hasRole: true,
+    focusable: true,
+    note: 'role=dialog；mask=true 加 aria-modal=true（非模态不设，避免误导锁定语义）；有 title 用 aria-labelledby，无则 ariaLabel；mask 时 useFocusTrap 捕获 Tab 焦点循环并在关闭归还 returnFocusTo/触发元素；closeOnEsc 控制 Esc（仅栈顶）；mask 时 useScrollLock 锁背景滚动；关闭按钮 aria-label 经 SideSheet.closeAriaLabel；reduced-motion / motionDisabled 退化即时显隐。',
+  },
+  tokens: [
+    '--cd-sidesheet-bg',
+    '--cd-sidesheet-color',
+    '--cd-sidesheet-mask-bg',
+    '--cd-sidesheet-border',
+    '--cd-sidesheet-radius',
+    '--cd-sidesheet-shadow',
+    '--cd-sidesheet-padding',
+    '--cd-sidesheet-header-padding',
+    '--cd-sidesheet-footer-padding',
+    '--cd-sidesheet-title-color',
+    '--cd-sidesheet-title-size',
+    '--cd-sidesheet-close-color',
+    '--cd-sidesheet-close-color-hover',
+    '--cd-sidesheet-close-hover-bg',
+    '--cd-sidesheet-width-small',
+    '--cd-sidesheet-width',
+    '--cd-sidesheet-width-large',
+    '--cd-sidesheet-height-small',
+    '--cd-sidesheet-height',
+    '--cd-sidesheet-height-large',
+    '--cd-sidesheet-z',
+    '--cd-sidesheet-motion-duration',
+  ],
+  responsive: true,
+  examples: [
+    {
+      title: '右侧模态面板',
+      code: '<SideSheet open={visible} title="编辑用户" onOpenChange={(e) => (visible = e.open)}>表单</SideSheet>',
+    },
+    {
+      title: '左侧导航面板',
+      code: '<SideSheet open={visible} placement="left" title="菜单" onOpenChange={(e) => (visible = e.open)}>导航</SideSheet>',
+    },
+    {
+      title: '非模态协作面板',
+      code: '<SideSheet open={visible} mask={false} outsideClosable title="通知中心" onOpenChange={(e) => (visible = e.open)}>列表</SideSheet>',
+    },
+    {
+      title: 'Footer 操作区',
+      code: '<SideSheet open={visible} title="筛选" onOpenChange={(e) => (visible = e.open)}>{#snippet footer({ close })}<Button onclick={close}>取消</Button><Button type="primary">应用筛选</Button>{/snippet}内容</SideSheet>',
+    },
+  ],
+} as const;

package/src/skeleton/Skeleton.a11y.test.ts

@@ -0,0 +1,35 @@
+// Skeleton a11y：loading 占位容器 aria-busy + aria-live=polite + aria-label。
+//
+// 已知 violation（组件源码缺口，本批不改源码）：占位容器是裸 <div>，带 aria-label/aria-live
+// 但无 role，axe 规则 [aria-prohibited-attr] 报「aria-label cannot be used on a div with no
+// valid role」。修复需给容器加 role（如 role="status"），属组件改动，故相关 axe 断言 it.skip。
+// 结构性 ARIA 断言（aria-busy/aria-live/aria-label 存在）仍作为非 skip 用例保留。
+import { describe, it, expect } from 'vitest';
+import { renderWithLocale, expectNoAxeViolations } from '../test-utils/a11y.js';
+import Skeleton from './Skeleton.svelte';
+
+describe('Skeleton a11y', () => {
+  it('loading：占位容器 aria-busy + aria-live + aria-label 结构正确', () => {
+    const { container } = renderWithLocale(Skeleton, {
+      props: { loading: true },
+    });
+    const root = container.querySelector('.cd-skeleton');
+    expect(root?.getAttribute('aria-busy')).toBe('true');
+    expect(root?.getAttribute('aria-live')).toBe('polite');
+    expect(root?.getAttribute('aria-label')).toBeTruthy();
+  });
+
+  it('loading：无 axe violations（占位容器 role=status）', async () => {
+    const { container } = renderWithLocale(Skeleton, {
+      props: { loading: true },
+    });
+    await expectNoAxeViolations(container);
+  });
+
+  it('active：无 axe violations（占位容器 role=status）', async () => {
+    const { container } = renderWithLocale(Skeleton, {
+      props: { loading: true, active: true },
+    });
+    await expectNoAxeViolations(container);
+  });
+});

package/src/skeleton/Skeleton.svelte

@@ -0,0 +1,131 @@
+<!--
+  Skeleton — 骨架屏容器。
+  loading 切换占位/真实内容；active 控制 shimmer 动画（经 context 传给原子子组件）。
+  loading 受控不回写（红线 #1）：仅由父级 prop 驱动，组件内部不修改。
+  占位容器 aria-busy + aria-live=polite + aria-label；骨架块本身 aria-hidden。
+  unmountPlaceholder=true（默认）：{#if} 条件渲染，未激活的一侧从 DOM 卸载。
+  unmountPlaceholder=false（keepDOM）：占位与真实内容同时挂载，靠 display:none 切换，避免重挂开销。
+-->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import { setContext } from 'svelte';
+  import { SKELETON_KEY, type SkeletonContext } from './context.js';
+  import SkeletonAvatar from './SkeletonAvatar.svelte';
+  import SkeletonTitle from './SkeletonTitle.svelte';
+  import SkeletonParagraph from './SkeletonParagraph.svelte';
+  import { useLocale } from '../locale-provider/index.js';
+
+  interface Props {
+    loading?: boolean;
+    active?: boolean;
+    unmountPlaceholder?: boolean;
+    placeholder?: Snippet;
+    children?: Snippet;
+    ariaLabel?: string;
+    class?: string;
+  }
+
+  let {
+    loading = true,
+    active = false,
+    // unmountPlaceholder=true（默认）走 {#if} 卸载；false 走 keepDOM（display:none 切换）。
+    unmountPlaceholder = true,
+    placeholder,
+    children,
+    ariaLabel,
+    class: className,
+  }: Props = $props();
+
+  const loc = useLocale();
+
+  // setContext 一个带 getter 的对象：原子子组件读取 ctx.active 即建立响应式依赖。
+  const ctx: SkeletonContext = {
+    get active() {
+      return active;
+    },
+  };
+  setContext(SKELETON_KEY, ctx);
+
+  const cls = $derived(
+    ['cd-skeleton', active && 'cd-skeleton--active', className]
+      .filter(Boolean)
+      .join(' '),
+  );
+
+  // 状态渲染派生纯函数（红线 #2）：仅由入参算出隐藏标记，不产生副作用。
+  function hidden(isLoading: boolean, showWhenLoading: boolean): boolean {
+    return showWhenLoading ? !isLoading : isLoading;
+  }
+</script>
+
+{#snippet placeholderBody()}
+  {#if placeholder}
+    {@render placeholder()}
+  {:else}
+    <div class="cd-skeleton__default">
+      <SkeletonAvatar />
+      <div class="cd-skeleton__default-body">
+        <SkeletonTitle />
+        <SkeletonParagraph />
+      </div>
+    </div>
+  {/if}
+{/snippet}
+
+{#if unmountPlaceholder}
+  {#if loading}
+    <div class={cls} role="status" aria-busy="true" aria-live="polite" aria-label={ariaLabel ?? loc().t('Skeleton.loading')}>
+      {@render placeholderBody()}
+    </div>
+  {:else}
+    {@render children?.()}
+  {/if}
+{:else}
+  <!-- keepDOM：两侧均挂载，靠 display:none 切换；隐藏侧加 inert/aria-hidden 防焦点与朗读。 -->
+  <div
+    class={cls}
+    role="status"
+    aria-busy="true"
+    aria-live="polite"
+    aria-label={ariaLabel ?? loc().t('Skeleton.loading')}
+    aria-hidden={hidden(loading, true) ? 'true' : undefined}
+    inert={hidden(loading, true)}
+    hidden={hidden(loading, true)}
+  >
+    {@render placeholderBody()}
+  </div>
+  <div
+    class="cd-skeleton__content"
+    aria-hidden={hidden(loading, false) ? 'true' : undefined}
+    inert={hidden(loading, false)}
+    hidden={hidden(loading, false)}
+  >
+    {@render children?.()}
+  </div>
+{/if}
+
+<style>
+  .cd-skeleton {
+    display: block;
+  }
+  .cd-skeleton__content {
+    display: contents;
+  }
+  /* keepDOM 隐藏侧：[hidden] 须压过 .cd-skeleton 的 display:block 与 __content 的 display:contents。 */
+  .cd-skeleton[hidden],
+  .cd-skeleton__content[hidden] {
+    display: none;
+  }
+  .cd-skeleton__default {
+    display: flex;
+    gap: var(--cd-skeleton-gap);
+    align-items: flex-start;
+  }
+  .cd-skeleton__default-body {
+    display: flex;
+    flex: 1 1 auto;
+    flex-direction: column;
+    gap: var(--cd-skeleton-gap);
+    min-inline-size: 0;
+  }
+</style>

package/src/skeleton/SkeletonAvatar.svelte

@@ -0,0 +1,82 @@
+<!--
+  SkeletonAvatar — 头像骨架块（圆形 / 方形）。
+  size 映射 small 24 / default 32 / large 40 / 数字直接 px。
+  active 优先从 context 读（无 context 默认 false）。
+-->
+<script lang="ts">
+  import { getContext } from 'svelte';
+  import { SKELETON_KEY, type SkeletonContext } from './context.js';
+
+  interface Props {
+    shape?: 'circle' | 'square';
+    size?: 'small' | 'default' | 'large' | number;
+    class?: string;
+    style?: string;
+  }
+
+  let { shape = 'circle', size = 'default', class: className, style }: Props = $props();
+
+  const ctx = getContext<SkeletonContext | undefined>(SKELETON_KEY);
+  const active = $derived(ctx?.active ?? false);
+
+  const px = $derived.by(() => {
+    if (typeof size === 'number') return size;
+    if (size === 'small') return 24;
+    if (size === 'large') return 40;
+    return 32;
+  });
+  const radius = $derived(
+    shape === 'circle'
+      ? 'var(--cd-skeleton-radius-pill)'
+      : 'var(--cd-skeleton-radius)',
+  );
+  const cls = $derived(
+    ['cd-skeleton__block', 'cd-skeleton__avatar', className].filter(Boolean).join(' '),
+  );
+</script>
+
+<div
+  class={cls}
+  class:cd-skeleton__block--active={active}
+  aria-hidden="true"
+  style="inline-size:{px}px; block-size:{px}px; border-radius:{radius}; {style ?? ''}"
+></div>
+
+<style>
+  .cd-skeleton__avatar {
+    flex: 0 0 auto;
+  }
+
+  .cd-skeleton__block {
+    background: var(--cd-skeleton-color-bg);
+    border-radius: var(--cd-skeleton-radius);
+  }
+  .cd-skeleton__block--active {
+    background-image: linear-gradient(
+      90deg,
+      var(--cd-skeleton-color-bg) 25%,
+      var(--cd-skeleton-color-highlight) 37%,
+      var(--cd-skeleton-color-bg) 63%
+    );
+    background-size: 400% 100%;
+    animation: -global-cd-skeleton-shimmer var(--cd-skeleton-anim-duration)
+      var(--cd-skeleton-anim-timing) infinite;
+  }
+
+  @keyframes -global-cd-skeleton-shimmer {
+    0% {
+      background-position: 100% 50%;
+    }
+    100% {
+      background-position: 0 50%;
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .cd-skeleton__block--active {
+      animation: none;
+      background-image: none;
+      background: var(--cd-skeleton-color-bg);
+    }
+  }
+</style>

package/src/skeleton/SkeletonButton.svelte

@@ -0,0 +1,90 @@
+<!--
+  SkeletonButton — 按钮骨架块（矩形 / 胶囊）。
+  size 映射高度 small 24 / default 32 / large 40；block 时宽 100%，否则默认约 64px。
+  active 优先从 context 读（无 context 默认 false）。
+-->
+<script lang="ts">
+  import { getContext } from 'svelte';
+  import { SKELETON_KEY, type SkeletonContext } from './context.js';
+
+  interface Props {
+    size?: 'small' | 'default' | 'large';
+    block?: boolean;
+    pill?: boolean;
+    width?: string | number;
+    class?: string;
+    style?: string;
+  }
+
+  let {
+    size = 'default',
+    block = false,
+    pill = false,
+    width,
+    class: className,
+    style,
+  }: Props = $props();
+
+  const ctx = getContext<SkeletonContext | undefined>(SKELETON_KEY);
+  const active = $derived(ctx?.active ?? false);
+
+  const heightPx = $derived(size === 'small' ? 24 : size === 'large' ? 40 : 32);
+  const inlineSize = $derived.by(() => {
+    if (block) return '100%';
+    if (width !== undefined) return typeof width === 'number' ? `${width}px` : width;
+    return '64px';
+  });
+  const radius = $derived(
+    pill ? 'var(--cd-skeleton-radius-pill)' : 'var(--cd-skeleton-radius)',
+  );
+  const cls = $derived(
+    ['cd-skeleton__block', 'cd-skeleton__button', className].filter(Boolean).join(' '),
+  );
+</script>
+
+<div
+  class={cls}
+  class:cd-skeleton__block--active={active}
+  aria-hidden="true"
+  style="inline-size:{inlineSize}; block-size:{heightPx}px; border-radius:{radius}; {style ??
+    ''}"
+></div>
+
+<style>
+  .cd-skeleton__button {
+    display: inline-block;
+  }
+
+  .cd-skeleton__block {
+    background: var(--cd-skeleton-color-bg);
+    border-radius: var(--cd-skeleton-radius);
+  }
+  .cd-skeleton__block--active {
+    background-image: linear-gradient(
+      90deg,
+      var(--cd-skeleton-color-bg) 25%,
+      var(--cd-skeleton-color-highlight) 37%,
+      var(--cd-skeleton-color-bg) 63%
+    );
+    background-size: 400% 100%;
+    animation: -global-cd-skeleton-shimmer var(--cd-skeleton-anim-duration)
+      var(--cd-skeleton-anim-timing) infinite;
+  }
+
+  @keyframes -global-cd-skeleton-shimmer {
+    0% {
+      background-position: 100% 50%;
+    }
+    100% {
+      background-position: 0 50%;
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .cd-skeleton__block--active {
+      animation: none;
+      background-image: none;
+      background: var(--cd-skeleton-color-bg);
+    }
+  }
+</style>

package/src/skeleton/SkeletonImage.svelte

@@ -0,0 +1,100 @@
+<!--
+  SkeletonImage — 大矩形图片骨架块，showIcon 时中心放弱色图片图标。
+  active 优先从 context 读（无 context 默认 false）。
+-->
+<script lang="ts">
+  import { getContext } from 'svelte';
+  import { SKELETON_KEY, type SkeletonContext } from './context.js';
+
+  interface Props {
+    width?: string | number;
+    height?: string | number;
+    showIcon?: boolean;
+    class?: string;
+    style?: string;
+  }
+
+  let {
+    width = '100%',
+    height = '120px',
+    showIcon = true,
+    class: className,
+    style,
+  }: Props = $props();
+
+  const ctx = getContext<SkeletonContext | undefined>(SKELETON_KEY);
+  const active = $derived(ctx?.active ?? false);
+
+  const inlineSize = $derived(typeof width === 'number' ? `${width}px` : width);
+  const blockSize = $derived(typeof height === 'number' ? `${height}px` : height);
+  const cls = $derived(
+    ['cd-skeleton__block', 'cd-skeleton__image', className].filter(Boolean).join(' '),
+  );
+</script>
+
+<div
+  class={cls}
+  class:cd-skeleton__block--active={active}
+  aria-hidden="true"
+  style="inline-size:{inlineSize}; block-size:{blockSize}; {style ?? ''}"
+>
+  {#if showIcon}
+    <svg
+      class="cd-skeleton__image-icon"
+      viewBox="0 0 48 48"
+      width="32"
+      height="32"
+      aria-hidden="true"
+      focusable="false"
+    >
+      <path
+        fill="currentColor"
+        d="M40 8H8a4 4 0 0 0-4 4v24a4 4 0 0 0 4 4h32a4 4 0 0 0 4-4V12a4 4 0 0 0-4-4Zm0 28H8v-6l8-8 6 6 10-10 8 8v10ZM16 22a4 4 0 1 1 0-8 4 4 0 0 1 0 8Z"
+      />
+    </svg>
+  {/if}
+</div>
+
+<style>
+  .cd-skeleton__image {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  }
+  .cd-skeleton__image-icon {
+    color: var(--cd-color-text-3);
+  }
+
+  .cd-skeleton__block {
+    background: var(--cd-skeleton-color-bg);
+    border-radius: var(--cd-skeleton-radius);
+  }
+  .cd-skeleton__block--active {
+    background-image: linear-gradient(
+      90deg,
+      var(--cd-skeleton-color-bg) 25%,
+      var(--cd-skeleton-color-highlight) 37%,
+      var(--cd-skeleton-color-bg) 63%
+    );
+    background-size: 400% 100%;
+    animation: -global-cd-skeleton-shimmer var(--cd-skeleton-anim-duration)
+      var(--cd-skeleton-anim-timing) infinite;
+  }
+
+  @keyframes -global-cd-skeleton-shimmer {
+    0% {
+      background-position: 100% 50%;
+    }
+    100% {
+      background-position: 0 50%;
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .cd-skeleton__block--active {
+      animation: none;
+      background-image: none;
+      background: var(--cd-skeleton-color-bg);
+    }
+  }
+</style>

package/src/skeleton/SkeletonParagraph.svelte

@@ -0,0 +1,103 @@
+<!--
+  SkeletonParagraph — 多行段落骨架块。
+  宽度规则：width 是数组按行取（越界用 100%）；是单值时全部行用该值；
+  未给 width 时末行收窄到 61%、其余 100%。
+  active 优先从 context 读（无 context 默认 false）。
+-->
+<script lang="ts">
+  import { getContext } from 'svelte';
+  import { SKELETON_KEY, type SkeletonContext } from './context.js';
+
+  interface Props {
+    rows?: number;
+    width?: string | number | Array<string | number>;
+    class?: string;
+    style?: string;
+  }
+
+  let { rows = 3, width, class: className, style }: Props = $props();
+
+  const ctx = getContext<SkeletonContext | undefined>(SKELETON_KEY);
+  const active = $derived(ctx?.active ?? false);
+
+  function toLength(value: string | number): string {
+    return typeof value === 'number' ? `${value}px` : value;
+  }
+
+  const widths = $derived.by(() => {
+    const list: string[] = [];
+    for (let i = 0; i < rows; i++) {
+      const last = i === rows - 1;
+      if (Array.isArray(width)) {
+        const v = width[i];
+        list.push(v === undefined ? '100%' : toLength(v));
+      } else if (width === undefined) {
+        list.push(last ? '61%' : '100%');
+      } else {
+        list.push(toLength(width));
+      }
+    }
+    return list;
+  });
+
+  const cls = $derived(
+    ['cd-skeleton__paragraph', className].filter(Boolean).join(' '),
+  );
+</script>
+
+<ul class={cls} aria-hidden="true" style={style}>
+  {#each widths as w, i (i)}
+    <li
+      class="cd-skeleton__block cd-skeleton__paragraph-row"
+      class:cd-skeleton__block--active={active}
+      style="inline-size:{w}"
+    ></li>
+  {/each}
+</ul>
+
+<style>
+  .cd-skeleton__paragraph {
+    display: flex;
+    flex-direction: column;
+    gap: var(--cd-skeleton-gap);
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+  .cd-skeleton__paragraph-row {
+    block-size: var(--cd-skeleton-paragraph-height);
+  }
+
+  .cd-skeleton__block {
+    background: var(--cd-skeleton-color-bg);
+    border-radius: var(--cd-skeleton-radius);
+  }
+  .cd-skeleton__block--active {
+    background-image: linear-gradient(
+      90deg,
+      var(--cd-skeleton-color-bg) 25%,
+      var(--cd-skeleton-color-highlight) 37%,
+      var(--cd-skeleton-color-bg) 63%
+    );
+    background-size: 400% 100%;
+    animation: -global-cd-skeleton-shimmer var(--cd-skeleton-anim-duration)
+      var(--cd-skeleton-anim-timing) infinite;
+  }
+
+  @keyframes -global-cd-skeleton-shimmer {
+    0% {
+      background-position: 100% 50%;
+    }
+    100% {
+      background-position: 0 50%;
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .cd-skeleton__block--active {
+      animation: none;
+      background-image: none;
+      background: var(--cd-skeleton-color-bg);
+    }
+  }
+</style>