@chenzy-design/svelte 0.1.0

package/src/input-number/meta.ts

@@ -0,0 +1,65 @@
+/**
+ * Machine-readable component metadata for AI/docs consumption.
+ * See specs/00-foundation/ai-friendly.spec.md.
+ */
+export const meta = {
+  name: 'InputNumber',
+  category: 'input',
+  description: '受约束的数值录入框，含步进按钮、键盘步进、精度与范围 clamp，复用 Input 视觉。',
+  props: [
+    { name: 'value', type: 'number | null', default: 'undefined', desc: '受控值；提供则为受控' },
+    { name: 'defaultValue', type: 'number | null', default: 'null', desc: '非受控初始值' },
+    { name: 'min', type: 'number', default: '-Infinity' },
+    { name: 'max', type: 'number', default: 'Infinity' },
+    { name: 'step', type: 'number', default: '1' },
+    { name: 'shiftStep', type: 'number', default: 'step * 10', desc: 'Shift+↑↓ 步长' },
+    { name: 'precision', type: 'number', default: 'undefined', desc: '失焦四舍五入保留小数位' },
+    { name: 'boundaryMode', type: "'clamp'|'strict'", default: 'clamp', desc: '越界处理：钳制 / 拒绝回滚' },
+    { name: 'formatter', type: '(n: number) => string', default: 'undefined', desc: '自定义显示格式化（仅非编辑态）' },
+    { name: 'parser', type: '(s: string) => number', default: 'undefined', desc: '自定义解析' },
+    { name: 'size', type: "'small'|'default'|'large'", default: 'default' },
+    { name: 'disabled', type: 'boolean', default: 'false' },
+    { name: 'readonly', type: 'boolean', default: 'false' },
+    { name: 'status', type: "'default'|'warning'|'error'", default: 'default' },
+    { name: 'controls', type: 'boolean', default: 'true', desc: '是否显示步进按钮' },
+    { name: 'controlsPosition', type: "'right'|'sides'", default: 'right', desc: '步进按钮布局：右侧 stacked / 两侧' },
+    { name: 'innerButtons', type: 'boolean', default: 'false', desc: '按钮内嵌悬浮（hover/focus 显形）' },
+    { name: 'keyboard', type: 'boolean', default: 'true', desc: '是否启用 ↑↓/PageUp·Down 步进' },
+    { name: 'mouseWheel', type: 'boolean', default: 'false', desc: '聚焦时滚轮步进' },
+    { name: 'placeholder', type: 'string', default: 'undefined' },
+    { name: 'prefix', type: 'string | Snippet', default: 'undefined', desc: '输入框前置内容（如货币符号、单位）' },
+    { name: 'suffix', type: 'string | Snippet', default: 'undefined', desc: '输入框后置内容（如单位 %、kg）' },
+    { name: 'name', type: 'string', default: 'undefined' },
+    { name: 'id', type: 'string', default: '自动生成', desc: 'input 元素 id，关联外部 label' },
+    { name: 'ariaLabel', type: 'string', default: 'undefined' },
+    { name: 'autofocus', type: 'boolean', default: 'false', desc: '挂载自动聚焦' },
+    { name: 'selectOnFocus', type: 'boolean', default: 'false', desc: '聚焦时全选文本' },
+    { name: 'locale', type: 'string', default: 'undefined', desc: '数字格式化 locale（仅未提供 formatter 时生效）' },
+    { name: 'onChange', type: '(v: number | null) => void', default: 'undefined', desc: '归一化后值变化' },
+    { name: 'onBoundaryHit', type: "(e: { boundary: 'min'|'max'; value: number }) => void", default: 'undefined', desc: '触达/试图越过边界' },
+  ],
+  events: [
+    { name: 'change', payload: '{ value: number | null }', desc: '归一化后值变化（受控核心事件）' },
+    { name: 'boundaryHit', payload: "{ boundary: 'min'|'max'; value: number }", desc: '触达/试图越过边界' },
+    {
+      name: 'step',
+      payload: "{ value: number; direction: 'up'|'down'; source: 'button'|'keyboard'|'wheel' }",
+      desc: '任一步进动作完成',
+    },
+    { name: 'focus', payload: 'FocusEvent', desc: '聚焦' },
+    { name: 'blur', payload: 'FocusEvent', desc: '失焦（已完成 commit 归一化）' },
+    { name: 'keydown', payload: 'KeyboardEvent', desc: '透传原生 keydown' },
+  ],
+  a11y: {
+    role: 'spinbutton',
+    keyboard: ['ArrowUp', 'ArrowDown', 'Shift+ArrowUp', 'Shift+ArrowDown', 'PageUp', 'PageDown', 'Enter'],
+    notes: [
+      'input role=spinbutton + aria-valuenow/valuemin/valuemax',
+      '失焦按 precision 四舍五入并 clamp 到 [min,max]',
+      '到 min/max 时对应步进按钮 disabled',
+      '步进按钮 tabindex=-1，mousedown.preventDefault 不夺焦',
+      'disabled→aria-disabled，readonly→aria-readonly，error→aria-invalid',
+    ],
+  },
+  tokens: ['--cd-input-*', '--cd-color-*', '--cd-spacing-*', '--cd-focus-ring', '--cd-motion-*'],
+} as const;

package/src/layout/Content.svelte

@@ -0,0 +1,37 @@
+<!--
+  Content — main region within Layout. Grows to fill, token-driven background.
+-->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+
+  interface Props {
+    /** true→token padding; number→px; string→raw; false→0 */
+    padding?: string | number | boolean;
+    class?: string;
+    children?: Snippet;
+  }
+
+  let { padding = false, class: className = '', children }: Props = $props();
+
+  const paddingCss = $derived.by(() => {
+    if (padding === true) return 'var(--cd-layout-content-padding)';
+    if (padding === false) return '0';
+    return typeof padding === 'number' ? `${padding}px` : padding;
+  });
+
+  const cls = $derived(['cd-layout-content', className].filter(Boolean).join(' '));
+
+  const inlineStyle = $derived(`padding:${paddingCss}`);
+</script>
+
+<main class={cls} style={inlineStyle}>
+  {@render children?.()}
+</main>
+
+<style>
+  .cd-layout-content {
+    flex: 1;
+    min-height: 0;
+    background: var(--cd-layout-content-bg);
+  }
+</style>

package/src/layout/Footer.svelte

@@ -0,0 +1,49 @@
+<!--
+  Footer — bottom bar within Layout. Token-driven background/color.
+-->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+
+  interface Props {
+    sticky?: boolean;
+    /** override height; number→px, string→raw */
+    height?: string | number;
+    class?: string;
+    children?: Snippet;
+  }
+
+  let { sticky = false, height, class: className = '', children }: Props = $props();
+
+  const heightCss = $derived.by(() => {
+    if (height === undefined) return undefined;
+    return typeof height === 'number' ? `${height}px` : height;
+  });
+
+  const cls = $derived(
+    ['cd-layout-footer', sticky && 'cd-layout-footer--sticky', className].filter(Boolean).join(' '),
+  );
+
+  const inlineStyle = $derived(heightCss ? `height:${heightCss}` : undefined);
+</script>
+
+<footer class={cls} style={inlineStyle}>
+  {@render children?.()}
+</footer>
+
+<style>
+  .cd-layout-footer {
+    display: flex;
+    flex: 0 0 auto;
+    align-items: center;
+    justify-content: center;
+    padding-block: var(--cd-spacing-4);
+    padding-inline: var(--cd-spacing-6);
+    background: var(--cd-layout-footer-bg);
+    color: var(--cd-layout-footer-color);
+    text-align: center;
+  }
+  .cd-layout-footer--sticky {
+    position: sticky;
+    inset-block-end: 0;
+  }
+</style>

package/src/layout/Header.svelte

@@ -0,0 +1,46 @@
+<!--
+  Header — top bar within Layout. Token-driven background/height.
+-->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+
+  interface Props {
+    sticky?: boolean;
+    /** override token height; number→px, string→raw */
+    height?: string | number;
+    class?: string;
+    children?: Snippet;
+  }
+
+  let { sticky = false, height, class: className = '', children }: Props = $props();
+
+  const heightCss = $derived.by(() => {
+    if (height === undefined) return undefined;
+    return typeof height === 'number' ? `${height}px` : height;
+  });
+
+  const cls = $derived(
+    ['cd-layout-header', sticky && 'cd-layout-header--sticky', className].filter(Boolean).join(' '),
+  );
+
+  const inlineStyle = $derived(heightCss ? `height:${heightCss}` : undefined);
+</script>
+
+<header class={cls} style={inlineStyle}>
+  {@render children?.()}
+</header>
+
+<style>
+  .cd-layout-header {
+    display: flex;
+    flex: 0 0 auto;
+    align-items: center;
+    height: var(--cd-layout-header-height);
+    background: var(--cd-layout-header-bg);
+  }
+  .cd-layout-header--sticky {
+    position: sticky;
+    inset-block-start: 0;
+    z-index: var(--cd-layout-header-z);
+  }
+</style>

package/src/layout/Layout.a11y.test.ts

@@ -0,0 +1,34 @@
+// Layout a11y：页面级布局骨架（section + header/main/footer/aside 语义元素）。
+// 纯布局，不引入额外 role；Sider collapsible 触发器为原生 button + aria-expanded/aria-controls/aria-label。
+import { describe, it, expect } from 'vitest';
+import { renderWithLocale, expectNoAxeViolations } from '../test-utils/a11y.js';
+import LayoutFixture from './LayoutA11yFixture.svelte';
+
+describe('Layout a11y', () => {
+  it('默认渲染：语义布局元素齐全，无 axe violations', async () => {
+    const { container } = renderWithLocale(LayoutFixture, {});
+    expect(container.querySelector('section.cd-layout')).not.toBeNull();
+    expect(container.querySelector('header.cd-layout-header')).not.toBeNull();
+    expect(container.querySelector('main.cd-layout-content')).not.toBeNull();
+    expect(container.querySelector('footer.cd-layout-footer')).not.toBeNull();
+    expect(container.querySelector('aside.cd-layout-sider')).not.toBeNull();
+    await expectNoAxeViolations(container);
+  });
+
+  it('collapsible Sider：触发器 button aria-expanded/aria-controls/aria-label，无 axe violations', async () => {
+    const { container } = renderWithLocale(LayoutFixture, {
+      props: { collapsible: true },
+    });
+    const trigger = container.querySelector('button.cd-layout-sider__trigger');
+    expect(trigger).not.toBeNull();
+    // 展开态 aria-expanded=true。
+    expect(trigger?.getAttribute('aria-expanded')).toBe('true');
+    // aria-controls 指向 Sider id（不悬空）。
+    const controls = trigger?.getAttribute('aria-controls');
+    expect(controls).toBeTruthy();
+    expect(container.ownerDocument.getElementById(controls!)).not.toBeNull();
+    // aria-label 来自 i18n（验证 LocaleProvider 管线）。
+    expect(trigger?.getAttribute('aria-label')).toBeTruthy();
+    await expectNoAxeViolations(container);
+  });
+});

package/src/layout/Layout.svelte

@@ -0,0 +1,60 @@
+<!--
+  Layout — root flex container. Column by default; row when a Sider is present.
+  Sider auto-detection: Sider registers itself via context on mount, flipping the
+  direction to row. Explicit `hasSider` always wins.
+  NOTE: child onMount runs after the parent, so SSR/first frame may render column
+  then switch to row. For SSR correctness pass `hasSider` explicitly.
+-->
+<script lang="ts" module>
+  export const LAYOUT_CONTEXT_KEY = Symbol('cd-layout');
+
+  export interface LayoutContext {
+    registerSider: () => void;
+  }
+</script>
+
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import { setContext } from 'svelte';
+
+  interface Props {
+    hasSider?: boolean;
+    class?: string;
+    children?: Snippet;
+  }
+
+  let { hasSider, class: className = '', children }: Props = $props();
+
+  let hasSiderDetected = $state(false);
+
+  setContext<LayoutContext>(LAYOUT_CONTEXT_KEY, {
+    registerSider: () => {
+      hasSiderDetected = true;
+    },
+  });
+
+  const isRow = $derived(hasSider ?? hasSiderDetected);
+
+  const cls = $derived(
+    ['cd-layout', isRow ? 'cd-layout--has-sider' : 'cd-layout--column', className]
+      .filter(Boolean)
+      .join(' '),
+  );
+</script>
+
+<section class={cls}>
+  {@render children?.()}
+</section>
+
+<style>
+  .cd-layout {
+    display: flex;
+    flex: auto;
+    flex-direction: column;
+    min-height: 0;
+    background: var(--cd-layout-bg);
+  }
+  .cd-layout--has-sider {
+    flex-direction: row;
+  }
+</style>

package/src/layout/LayoutA11yFixture.svelte

@@ -0,0 +1,21 @@
+<!--
+  仅供 Layout.a11y.test.ts 使用的测试夹具：Layout 根 + Header/Sider/Content/Footer。
+  Sider collapsible 渲染原生 button 触发器（aria-expanded/aria-controls/aria-label）。
+-->
+<script lang="ts">
+  import { Layout } from './index.js';
+
+  interface Props {
+    collapsible?: boolean;
+  }
+  let { collapsible = false }: Props = $props();
+</script>
+
+<Layout hasSider>
+  <Layout.Sider {collapsible}>Navigation</Layout.Sider>
+  <Layout>
+    <Layout.Header>Page header</Layout.Header>
+    <Layout.Content padding>Main content</Layout.Content>
+    <Layout.Footer>Page footer</Layout.Footer>
+  </Layout>
+</Layout>

package/src/layout/Sider.svelte

@@ -0,0 +1,207 @@
+<!--
+  Sider — collapsible side panel. Backed by headless createSider from core.
+  Registers with Layout (context) so Layout switches to row direction.
+  aria-label 文案经 useLocale 取自 locale 包（Sider.expand/collapse）。
+-->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import { getContext, onMount, untrack } from 'svelte';
+  import {
+    createSider,
+    type Breakpoint,
+    type SiderOptions,
+    type SiderTrigger,
+  } from '@chenzy-design/core';
+  import { LAYOUT_CONTEXT_KEY, type LayoutContext } from './Layout.svelte';
+  import { useLocale } from '../locale-provider/index.js';
+
+  interface Props {
+    /** controlled collapsed value */
+    collapsed?: boolean;
+    defaultCollapsed?: boolean;
+    collapsible?: boolean;
+    width?: string | number;
+    collapsedWidth?: string | number;
+    breakpoint?: Breakpoint;
+    reverseArrow?: boolean;
+    placement?: 'left' | 'right';
+    class?: string;
+    onCollapse?: (collapsed: boolean, trigger: SiderTrigger) => void;
+    children?: Snippet;
+    /** custom trigger; receives current collapsed + toggle */
+    trigger?: Snippet<[{ collapsed: boolean; toggle: () => void }]>;
+  }
+
+  let {
+    collapsed,
+    defaultCollapsed = false,
+    collapsible = false,
+    width = 200,
+    collapsedWidth = 60,
+    breakpoint,
+    reverseArrow = false,
+    placement = 'left',
+    class: className = '',
+    onCollapse,
+    children,
+    trigger,
+  }: Props = $props();
+
+  const loc = useLocale();
+
+  const layout = getContext<LayoutContext | undefined>(LAYOUT_CONTEXT_KEY);
+
+  // Headless machine is created once with the initial prop values; later changes
+  // to the controlled `collapsed` prop are applied via the $derived below.
+  // untrack documents that we intentionally capture only the initial values here.
+  const sider = untrack(() => {
+    // Build options conditionally — exactOptionalPropertyTypes forbids passing
+    // `undefined` for optional props typed without `| undefined`.
+    const options: SiderOptions = {
+      defaultCollapsed,
+      onChange: (value, t) => onCollapse?.(value, t),
+    };
+    if (collapsed !== undefined) options.collapsed = collapsed;
+    if (breakpoint !== undefined) options.breakpoint = breakpoint;
+    return createSider(options);
+  });
+
+  // Tracks the headless machine's uncontrolled collapsed state.
+  let internalCollapsed = $state(sider.getCollapsed());
+
+  // Controlled `collapsed` prop always wins over the internal value.
+  const collapsedState = $derived(collapsed ?? internalCollapsed);
+
+  // Notify Layout once so it switches to row direction.
+  onMount(() => {
+    layout?.registerSider();
+  });
+
+  // Bridge the headless subscription/breakpoint watcher into Svelte reactivity.
+  // This is the intended escape-hatch use of $effect: syncing an external store.
+  $effect(() => {
+    const unsubscribe = sider.subscribe((value) => {
+      internalCollapsed = value;
+    });
+    const stopWatch = sider.watchBreakpoint();
+    return () => {
+      unsubscribe();
+      stopWatch();
+    };
+  });
+
+  function toggle(): void {
+    sider.toggle();
+  }
+
+  function toCss(value: string | number): string {
+    return typeof value === 'number' ? `${value}px` : value;
+  }
+
+  const widthCss = $derived(collapsedState ? toCss(collapsedWidth) : toCss(width));
+
+  const isCollapsedToZero = $derived(
+    collapsedState && (collapsedWidth === 0 || collapsedWidth === '0' || collapsedWidth === '0px'),
+  );
+
+  const cls = $derived(
+    [
+      'cd-layout-sider',
+      `cd-layout-sider--${placement}`,
+      collapsedState && 'cd-layout-sider--collapsed',
+      className,
+    ]
+      .filter(Boolean)
+      .join(' '),
+  );
+
+  const inlineStyle = $derived(`flex: 0 0 ${widthCss}; width: ${widthCss}; max-width: ${widthCss}`);
+
+  // Arrow direction: point "outward" to expand, "inward" to collapse.
+  // placement + reverseArrow flip which glyph means which.
+  const pointsStart = $derived.by(() => {
+    const base = placement === 'left' ? collapsedState : !collapsedState;
+    return reverseArrow ? !base : base;
+  });
+</script>
+
+<aside class={cls} style={inlineStyle}>
+  <div
+    id={sider.id}
+    class="cd-layout-sider__children"
+    aria-hidden={isCollapsedToZero || undefined}
+  >
+    {@render children?.()}
+  </div>
+
+  {#if trigger}
+    {@render trigger({ collapsed: collapsedState, toggle })}
+  {:else if collapsible}
+    <button
+      type="button"
+      class="cd-layout-sider__trigger"
+      aria-expanded={!collapsedState}
+      aria-controls={sider.id}
+      aria-label={collapsedState ? loc().t('Sider.expand') : loc().t('Sider.collapse')}
+      onclick={toggle}
+    >
+      <span class="cd-layout-sider__arrow" aria-hidden="true">{pointsStart ? '‹' : '›'}</span>
+    </button>
+  {/if}
+</aside>
+
+<style>
+  .cd-layout-sider {
+    position: relative;
+    display: flex;
+    flex-direction: column;
+    min-height: 0;
+    background: var(--cd-layout-sider-bg);
+    transition:
+      flex-basis var(--cd-layout-motion-duration) var(--cd-layout-motion-ease),
+      width var(--cd-layout-motion-duration) var(--cd-layout-motion-ease),
+      max-width var(--cd-layout-motion-duration) var(--cd-layout-motion-ease);
+  }
+  .cd-layout-sider--left {
+    border-inline-end: var(--cd-layout-sider-border);
+  }
+  .cd-layout-sider--right {
+    border-inline-start: var(--cd-layout-sider-border);
+  }
+  .cd-layout-sider__children {
+    flex: 1;
+    min-height: 0;
+    overflow: hidden;
+  }
+  .cd-layout-sider__trigger {
+    display: flex;
+    flex: 0 0 auto;
+    align-items: center;
+    justify-content: center;
+    height: var(--cd-layout-header-height);
+    padding: 0;
+    border: none;
+    background: var(--cd-layout-sider-trigger-bg);
+    color: var(--cd-layout-sider-trigger-color);
+    cursor: pointer;
+    transition: background-color var(--cd-layout-motion-duration) var(--cd-layout-motion-ease);
+  }
+  .cd-layout-sider__trigger:hover {
+    background: var(--cd-layout-sider-trigger-hover-bg);
+  }
+  .cd-layout-sider__trigger:focus-visible {
+    outline: none;
+    box-shadow: var(--cd-focus-ring);
+  }
+  .cd-layout-sider__arrow {
+    display: inline-flex;
+    font-size: var(--cd-font-size-3);
+    line-height: 1;
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .cd-layout-sider,
+    .cd-layout-sider__trigger {
+      transition: none;
+    }
+  }
+</style>

package/src/layout/index.ts

@@ -0,0 +1,26 @@
+import LayoutRoot from './Layout.svelte';
+import Header from './Header.svelte';
+import Footer from './Footer.svelte';
+import Content from './Content.svelte';
+import Sider from './Sider.svelte';
+
+/** Named exports (also usable directly). */
+export {
+  Header as LayoutHeader,
+  Footer as LayoutFooter,
+  Content as LayoutContent,
+  Sider as LayoutSider,
+};
+
+/**
+ * Aggregated namespace export: enables <Layout.Header /> etc.
+ * Explicit type annotation avoids leaking component Props type errors.
+ */
+export const Layout: typeof LayoutRoot & {
+  Header: typeof Header;
+  Footer: typeof Footer;
+  Content: typeof Content;
+  Sider: typeof Sider;
+} = Object.assign(LayoutRoot, { Header, Footer, Content, Sider });
+
+export { meta as layoutMeta } from './meta.js';

package/src/layout/meta.ts

@@ -0,0 +1,116 @@
+/**
+ * Machine-readable component metadata for AI/docs consumption.
+ * Aggregated metadata for the Layout family (root + Header/Sider/Content/Footer).
+ */
+export const meta = {
+  name: 'Layout',
+  category: 'basic',
+  description: '页面级布局骨架：Layout 根容器 + Header / Sider / Content / Footer 子组件。',
+  subComponents: [
+    {
+      name: 'Layout',
+      element: 'section',
+      props: [
+        {
+          name: 'hasSider',
+          type: 'boolean',
+          default: 'undefined',
+          desc: '显式声明含侧边栏→row 方向；不传则由 Sider 挂载时自动检测',
+        },
+        { name: 'class', type: 'string', default: "''" },
+      ],
+    },
+    {
+      name: 'Layout.Header',
+      element: 'header',
+      props: [
+        { name: 'sticky', type: 'boolean', default: 'false', desc: 'position:sticky top:0' },
+        { name: 'height', type: 'string|number', default: 'undefined', desc: 'number→px，覆盖 token 高度' },
+        { name: 'class', type: 'string', default: "''" },
+      ],
+    },
+    {
+      name: 'Layout.Footer',
+      element: 'footer',
+      props: [
+        { name: 'sticky', type: 'boolean', default: 'false', desc: 'position:sticky bottom:0' },
+        { name: 'height', type: 'string|number', default: 'undefined' },
+        { name: 'class', type: 'string', default: "''" },
+      ],
+    },
+    {
+      name: 'Layout.Content',
+      element: 'main',
+      props: [
+        {
+          name: 'padding',
+          type: 'string|number|boolean',
+          default: 'false',
+          desc: 'true→token padding；number→px；string→原样；false→0',
+        },
+        { name: 'class', type: 'string', default: "''" },
+      ],
+    },
+    {
+      name: 'Layout.Sider',
+      element: 'aside',
+      props: [
+        { name: 'collapsed', type: 'boolean', default: 'undefined', desc: '受控收起状态' },
+        { name: 'defaultCollapsed', type: 'boolean', default: 'false' },
+        { name: 'collapsible', type: 'boolean', default: 'false', desc: 'true→渲染默认触发器' },
+        { name: 'width', type: 'string|number', default: '200', desc: 'number→px' },
+        { name: 'collapsedWidth', type: 'string|number', default: '60', desc: '0 时收起隐藏内容' },
+        { name: 'breakpoint', type: "'xs'|'sm'|'md'|'lg'|'xl'|'xxl'", default: 'undefined', desc: '低于断点自动收起' },
+        { name: 'reverseArrow', type: 'boolean', default: 'false', desc: '反转触发器箭头方向' },
+        { name: 'placement', type: "'left'|'right'", default: "'left'" },
+        { name: 'class', type: 'string', default: "''" },
+        { name: 'onCollapse', type: "(collapsed, trigger:'click'|'breakpoint')=>void", default: 'undefined' },
+        { name: 'trigger', type: 'Snippet<[{collapsed,toggle}]>', default: 'undefined', desc: '自定义触发器' },
+      ],
+    },
+  ],
+  events: [
+    { name: 'onCollapse', desc: 'Sider 收起状态变化，第二参数区分 click / breakpoint 触发来源' },
+  ],
+  slots: [
+    { name: 'children', desc: '各子组件内容' },
+    { name: 'trigger', desc: 'Sider 自定义触发器，接收 {collapsed, toggle}' },
+  ],
+  a11y: {
+    hasRole: false,
+    focusable: false,
+    sider: 'Sider 触发器为原生 button，含 aria-expanded / aria-controls / aria-label；collapsedWidth=0 时内容 aria-hidden',
+    note: 'reduced-motion 下移除 Sider 过渡',
+  },
+  tokens: [
+    '--cd-layout-bg',
+    '--cd-layout-header-bg',
+    '--cd-layout-header-height',
+    '--cd-layout-header-z',
+    '--cd-layout-footer-bg',
+    '--cd-layout-footer-color',
+    '--cd-layout-content-bg',
+    '--cd-layout-content-padding',
+    '--cd-layout-sider-bg',
+    '--cd-layout-sider-width',
+    '--cd-layout-sider-collapsed-width',
+    '--cd-layout-sider-border',
+    '--cd-layout-sider-trigger-bg',
+    '--cd-layout-sider-trigger-color',
+    '--cd-layout-sider-trigger-hover-bg',
+    '--cd-layout-motion-duration',
+    '--cd-layout-motion-ease',
+  ],
+  aiHints: [
+    'SSR/首屏含侧边栏时显式传 hasSider，避免 column→row 闪动。',
+    'Sider 受控用 collapsed + onCollapse；非受控用 defaultCollapsed。',
+    '需要响应式自动收起时传 breakpoint。',
+    'Layout.Header / Layout.Sider 等命名空间用法与具名 LayoutHeader 等价。',
+  ],
+  examples: [
+    {
+      title: '经典后台布局',
+      code: '<Layout hasSider><Layout.Sider collapsible /><Layout><Layout.Header /><Layout.Content padding>内容</Layout.Content><Layout.Footer>底部</Layout.Footer></Layout></Layout>',
+    },
+  ],
+} as const;