@teamix-evo/ui 0.3.0 → 0.5.0

package/src/_design-system/theme-tokens/stories.tsx

@@ -0,0 +1,1474 @@
+import { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import type { ReactNode } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+/* ──────────────────────────────────────────────────────────────────────────
+ * Theme Tokens · Token Atlas
+ *
+ * 一份"设计档案"式的运行时变量浏览器:读取当前 Storybook 主题(由顶栏的
+ * Theme 切换器决定)下,Tailwind v4 实际解析的颜色 / 圆角 / 阴影 / 字号 /
+ * 字重值。所有数值都通过 getComputedStyle 在浏览器里实时拿;切换 variant
+ * 时无需刷新页面,数值会跟着变。
+ *
+ * 不直接读 token 文件,因为各 variant 的覆盖面不同(opentrek 没显式声明
+ * shadow / radius 档,而是吃 Tailwind v4 默认值)。统一通过"在隐藏 probe
+ * 上挂 utility class → 读 computed style"获取真实生效值,展示与业务实际
+ * 渲染完全一致的结果。
+ *
+ * 跨 variant 缺失档位的处理:对于「某些 variant 才声明」的 token(如 op 的
+ * --radius-2xl 在 op 中没有,um 才有),使用 readVar() 探测,空值则隐藏
+ * 整行,避免显示无意义的"—"。
+ * ────────────────────────────────────────────────────────────────────────── */
+
+// ── 数据维度 ────────────────────────────────────────────────────────────────
+
+/**
+ * 颜色分组 — 每条 token 直接用 var(--color-<token>) 读取。
+ * 名称结构:`group.label` 用作分组标题,`tokens` 列表逐条渲染样本 + foreground 配对。
+ * `optional: true` 的条目缺失时整行隐藏(避免在不声明该档的 variant 下显示空值)。
+ */
+const COLOR_GROUPS: Array<{
+  label: string;
+  caption?: string;
+  tokens: Array<{ name: string; optional?: boolean }>;
+}> = [
+  {
+    label: 'Brand · 品牌',
+    caption: 'primary 主色 + 状态扩展(hover/pressed/glow)',
+    tokens: [
+      { name: 'primary' },
+      { name: 'primary-foreground' },
+      { name: 'primary-hover', optional: true },
+      { name: 'primary-pressed', optional: true },
+      { name: 'primary-glow', optional: true },
+      { name: 'accent' },
+      { name: 'accent-foreground' },
+    ],
+  },
+  {
+    label: 'Greyscale · 灰阶语义',
+    caption: '4 档文字 + 中性面板 / 边框扩展',
+    tokens: [
+      { name: 'foreground' },
+      { name: 'foreground-body', optional: true },
+      { name: 'muted-foreground' },
+      { name: 'foreground-subtle', optional: true },
+      { name: 'panel', optional: true },
+      { name: 'border-subtle', optional: true },
+    ],
+  },
+  {
+    label: 'Surface · 容器背景',
+    tokens: [
+      { name: 'background' },
+      { name: 'card' },
+      { name: 'card-foreground' },
+      { name: 'muted' },
+      { name: 'popover' },
+      { name: 'popover-foreground' },
+      { name: 'secondary' },
+      { name: 'secondary-foreground' },
+    ],
+  },
+  {
+    label: 'Border · 边框 / 描边',
+    // eslint-disable-next-line teamix-evo/no-bare-border -- token slugs, not classNames
+    tokens: [{ name: 'border' }, { name: 'input' }, { name: 'ring' }],
+  },
+  {
+    label: 'Status · Success',
+    // eslint-disable-next-line teamix-evo/no-bare-border -- caption text, not className
+    caption: 'success 全档:default / hover / pressed / bg / border',
+    tokens: [
+      { name: 'success' },
+      { name: 'success-foreground' },
+      { name: 'success-hover', optional: true },
+      { name: 'success-pressed', optional: true },
+      { name: 'success-bg', optional: true },
+      { name: 'success-border', optional: true },
+      { name: 'success-subtle', optional: true },
+    ],
+  },
+  {
+    label: 'Status · Destructive',
+    tokens: [
+      { name: 'destructive' },
+      { name: 'destructive-foreground' },
+      { name: 'destructive-hover', optional: true },
+      { name: 'destructive-pressed', optional: true },
+      { name: 'destructive-bg', optional: true },
+      { name: 'destructive-border', optional: true },
+    ],
+  },
+  {
+    label: 'Status · Warning',
+    tokens: [
+      { name: 'warning' },
+      { name: 'warning-foreground' },
+      { name: 'warning-hover', optional: true },
+      { name: 'warning-pressed', optional: true },
+      { name: 'warning-bg', optional: true },
+      { name: 'warning-border', optional: true },
+      { name: 'warning-subtle', optional: true },
+    ],
+  },
+  {
+    label: 'Status · Info',
+    tokens: [
+      { name: 'info' },
+      { name: 'info-foreground' },
+      { name: 'info-hover', optional: true },
+      { name: 'info-pressed', optional: true },
+      { name: 'info-bg', optional: true },
+      { name: 'info-border', optional: true },
+      { name: 'info-subtle', optional: true },
+    ],
+  },
+  {
+    label: 'Status · Help',
+    caption: '新档位:与 warning 区隔(色相 45° vs 40°),业务低频',
+    tokens: [
+      { name: 'help', optional: true },
+      { name: 'help-foreground', optional: true },
+      { name: 'help-bg', optional: true },
+      { name: 'help-border', optional: true },
+    ],
+  },
+  {
+    label: 'Sidebar · 侧栏',
+    tokens: [
+      { name: 'sidebar' },
+      { name: 'sidebar-foreground' },
+      { name: 'sidebar-primary' },
+      { name: 'sidebar-primary-foreground' },
+      { name: 'sidebar-accent' },
+      { name: 'sidebar-accent-foreground' },
+      { name: 'sidebar-border' },
+      { name: 'sidebar-ring' },
+      // op 独有 sidebar 扩展槽位（um 不声明 → 自动隐藏）
+      { name: 'sidebar-active', optional: true },
+      { name: 'sidebar-active-foreground', optional: true },
+      { name: 'sidebar-hover', optional: true },
+      { name: 'sidebar-title', optional: true },
+      { name: 'sidebar-group', optional: true },
+      { name: 'sidebar-item', optional: true },
+      { name: 'sidebar-item-muted', optional: true },
+    ],
+  },
+  {
+    label: 'OpenTrek · Topbar',
+    caption: 'op-only · 顶部导航条',
+    tokens: [
+      { name: 'topbar', optional: true },
+      { name: 'topbar-foreground', optional: true },
+      { name: 'topbar-divider', optional: true },
+    ],
+  },
+  {
+    label: 'OpenTrek · Accent 调色板',
+    caption: 'op-only · MasterGuide 提取的 10 色辅助色',
+    tokens: [
+      { name: 'accent-blue', optional: true },
+      { name: 'accent-violet', optional: true },
+      { name: 'accent-apricot', optional: true },
+      { name: 'accent-indigo', optional: true },
+      { name: 'accent-green', optional: true },
+      { name: 'accent-magenta', optional: true },
+      { name: 'accent-turquoise', optional: true },
+      { name: 'accent-orange', optional: true },
+      { name: 'accent-berry', optional: true },
+      { name: 'accent-olive', optional: true },
+    ],
+  },
+  {
+    label: 'OpenTrek · Gray 灰阶',
+    caption: 'op-only · v7.4 重构 8 级语义灰',
+    tokens: [
+      { name: 'gray-primary', optional: true },
+      { name: 'gray-primary-foreground', optional: true },
+      { name: 'gray-secondary-foreground', optional: true },
+      { name: 'gray-disabled', optional: true },
+      { name: 'gray-line', optional: true },
+      { name: 'gray-sidebar-accent', optional: true },
+      { name: 'gray-muted', optional: true },
+      { name: 'gray-white', optional: true },
+    ],
+  },
+  {
+    label: 'OpenTrek · Type 指示',
+    caption: 'op-only · API / MCP 类型徽标',
+    tokens: [
+      { name: 'type-api', optional: true },
+      { name: 'type-api-light', optional: true },
+      { name: 'type-api-border', optional: true },
+      { name: 'type-mcp', optional: true },
+      { name: 'type-mcp-light', optional: true },
+      { name: 'type-mcp-border', optional: true },
+    ],
+  },
+  {
+    label: 'OpenTrek · Runtime 状态',
+    caption: 'op-only · 服务运行状态指示点',
+    tokens: [
+      { name: 'status-running', optional: true },
+      { name: 'status-stopped', optional: true },
+      { name: 'status-error', optional: true },
+    ],
+  },
+  {
+    label: 'OpenTrek · Terminal',
+    caption: 'op-only · 命令行 / 控制台配色',
+    tokens: [
+      { name: 'terminal', optional: true },
+      { name: 'terminal-foreground', optional: true },
+    ],
+  },
+  {
+    label: '扩展 / Variant 特色',
+    caption: '跨 variant 各自声明的细节槽位',
+    tokens: [
+      { name: 'avatar-bg', optional: true },
+      { name: 'input-placeholder', optional: true },
+      { name: 'input-focus', optional: true }, // um-only
+      { name: 'info-light', optional: true }, // op-only
+      { name: 'background-dark', optional: true }, // op-only
+      { name: 'background-panel', optional: true }, // op-only
+    ],
+  },
+];
+
+/** Charts 调色板 — opentrek 10 色 / uni-manager 5 色,缺失档自动隐藏。 */
+const CHART_TOKENS: Array<{ name: string; optional?: boolean }> = [
+  { name: 'chart-1' },
+  { name: 'chart-2' },
+  { name: 'chart-3' },
+  { name: 'chart-4' },
+  { name: 'chart-5' },
+  { name: 'chart-6', optional: true },
+  { name: 'chart-7', optional: true },
+  { name: 'chart-8', optional: true },
+  { name: 'chart-9', optional: true },
+  { name: 'chart-10', optional: true },
+];
+
+const RADIUS_SCALE: Array<{ key: string; cls: string }> = [
+  { key: 'sm', cls: 'rounded-sm' },
+  { key: 'md', cls: 'rounded-md' },
+  { key: 'lg', cls: 'rounded-lg' },
+  { key: 'xl', cls: 'rounded-xl' },
+  { key: '2xl', cls: 'rounded-2xl' },
+  { key: 'full', cls: 'rounded-full' },
+];
+
+/** 组件级圆角 — 各 variant 按需声明,缺失整行隐藏。 */
+const COMPONENT_RADIUS: Array<{ name: string; varName: string }> = [
+  { name: 'dialog', varName: '--radius-dialog' },
+  { name: 'tag', varName: '--radius-tag' },
+  { name: 'checkbox', varName: '--radius-checkbox' },
+];
+
+const SHADOW_SCALE: Array<{ key: string; cls: string; varName?: string }> = [
+  // · op + um 均不声明的档位只走 Tailwind 默认。
+  // · 声明了 varName 的档位，若 · readVar(varName) 空，推断本 variant 未覆写，整行隐藏。
+  { key: '2xs', cls: 'shadow-2xs', varName: '--shadow-2xs' }, // um-only
+  { key: 'xs', cls: 'shadow-xs', varName: '--shadow-xs' }, // um-only
+  { key: 'sm', cls: 'shadow-sm' },
+  { key: 'md', cls: 'shadow-md' },
+  { key: 'lg', cls: 'shadow-lg' },
+  { key: 'xl', cls: 'shadow-xl' },
+  { key: '2xl', cls: 'shadow-2xl' },
+];
+
+/** 组件级阴影 — 由 token 直接声明,不走 Tailwind utility。 */
+const COMPONENT_SHADOWS: Array<{ name: string; varName: string }> = [
+  { name: 'dialog', varName: '--shadow-dialog' },
+  { name: 'drawer', varName: '--drawer-shadow' },
+  { name: 'select-content', varName: '--shadow-select-content' },
+  { name: 'form-hover', varName: '--shadow-form-hover' },
+];
+
+const TEXT_SIZES: Array<{
+  key: string;
+  cls: string;
+  px: number;
+  semantic?: string;
+}> = [
+  { key: 'xs', cls: 'text-xs', px: 12, semantic: 'body-1 · 正文 / Caption' },
+  { key: 'sm', cls: 'text-sm', px: 14, semantic: 'body-2 · 强调正文 / Tab' },
+  {
+    key: 'base',
+    cls: 'text-base',
+    px: 16,
+    semantic: 'subhead · 卡片标题 / 区块标题',
+  },
+  { key: 'lg', cls: 'text-lg', px: 18, semantic: 'title · 页面主标题' },
+  { key: 'xl', cls: 'text-xl', px: 20, semantic: 'headline · 数据指标-中' },
+  { key: '2xl', cls: 'text-2xl', px: 24, semantic: 'display-1 · 页头标题' },
+  { key: '3xl', cls: 'text-3xl', px: 28, semantic: 'display-2 · 数据指标-大' },
+  { key: '4xl', cls: 'text-4xl', px: 36, semantic: '超大(备用 / 营销)' },
+];
+
+/** 语义字号 token — 独立于 Tailwind 默认 8 档之外。 */
+const TEXT_SEMANTIC_TOKENS: Array<{
+  varName: string;
+  px: number;
+  semantic: string;
+}> = [
+  { varName: '--text-xxs', px: 10, semantic: 'xxs · 角标 / 计数器' },
+  { varName: '--text-display-3', px: 32, semantic: 'display-3 · 运营标题' },
+  {
+    varName: '--font-size-page-header',
+    px: 18,
+    semantic: 'PageHeader 标题专用',
+  },
+];
+
+/**
+ * 字重档位 — 标 `tokenVar` 表示有 `--font-weight-*` token 别名声明,
+ * 否则仅是 Tailwind v4 默认 utility(永远可用)。
+ */
+const TEXT_WEIGHTS: Array<{
+  key: string;
+  cls: string;
+  weight: number;
+  tokenVar?: string;
+}> = [
+  {
+    key: 'normal',
+    cls: 'font-normal',
+    weight: 400,
+    tokenVar: '--font-weight-normal',
+  },
+  {
+    key: 'medium',
+    cls: 'font-medium',
+    weight: 500,
+    tokenVar: '--font-weight-medium',
+  },
+  { key: 'semibold', cls: 'font-semibold', weight: 600 },
+  { key: 'bold', cls: 'font-bold', weight: 700 },
+  {
+    key: 'black',
+    cls: 'font-black',
+    weight: 900,
+    tokenVar: '--font-weight-black',
+  },
+];
+
+// ── 运行时读取 ─────────────────────────────────────────────────────────────
+
+/** 触发 token 重计算的信号:监听 <html> 的 data-theme 变化 + window resize。 */
+function useThemeTick(): number {
+  const [tick, setTick] = useState(0);
+  useEffect(() => {
+    const bump = () => setTick((n) => n + 1);
+    const observer = new MutationObserver(bump);
+    observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ['data-theme', 'class'],
+    });
+    window.addEventListener('resize', bump);
+    return () => {
+      observer.disconnect();
+      window.removeEventListener('resize', bump);
+    };
+  }, []);
+  return tick;
+}
+
+/** 读取 :root 上指定 CSS 变量的当前值(去前后空白)。SSR 安全。 */
+function readVar(name: string): string {
+  if (typeof window === 'undefined') return '';
+  const v = getComputedStyle(document.documentElement).getPropertyValue(name);
+  return v.trim();
+}
+
+/** 把任意 css 长度字符串(rem/px/em)规范化成同时显示原值 + 像素值。 */
+function fmtLength(raw: string): string {
+  if (!raw) return '—';
+  if (raw.endsWith('px')) return raw;
+  if (raw.endsWith('rem')) {
+    const n = parseFloat(raw);
+    if (!Number.isNaN(n)) return `${raw} · ${Math.round(n * 16)}px`;
+  }
+  return raw;
+}
+
+// ── 视觉原子 ───────────────────────────────────────────────────────────────
+
+/**
+ * 档案条目 — Token Atlas 的核心展示单元。
+ * 左侧:变量名(mono) + 当前值(mono dim);右侧:视觉样本。
+ * 一行一条,横向规则线分隔,刻意像档案/印刷品。
+ */
+function AtlasRow({
+  name,
+  value,
+  preview,
+  children,
+}: {
+  name: string;
+  value: string;
+  preview?: ReactNode;
+  children?: ReactNode;
+}) {
+  return (
+    <div
+      className="group grid items-center gap-x-6 border-t border-border/60 py-5 transition-colors hover:bg-muted/40"
+      style={{ gridTemplateColumns: 'minmax(0, 1fr) minmax(0, 1.4fr)' }}
+    >
+      <div className="min-w-0 flex flex-col gap-1">
+        <code className="font-mono text-xs tracking-tight text-foreground">
+          {name}
+        </code>
+        <code className="font-mono text-xxs uppercase tracking-widest text-muted-foreground/80">
+          {value || '—'}
+        </code>
+      </div>
+      <div className="min-w-0">{preview ?? children}</div>
+    </div>
+  );
+}
+
+function GroupBlock({
+  index,
+  label,
+  caption,
+  children,
+}: {
+  index: string;
+  label: string;
+  caption?: string;
+  children: ReactNode;
+}) {
+  return (
+    <section className="mb-16">
+      <header className="mb-4 flex items-baseline gap-4 border-b border-foreground pb-3">
+        <span className="font-mono text-xxs tracking-widest text-muted-foreground">
+          {index}
+        </span>
+        <h3 className="text-lg font-medium tracking-tight text-foreground">
+          {label}
+        </h3>
+        {caption ? (
+          <span className="ml-auto font-mono text-xxs uppercase tracking-widest text-muted-foreground">
+            {caption}
+          </span>
+        ) : null}
+      </header>
+      <div>{children}</div>
+    </section>
+  );
+}
+
+function AtlasFrame({
+  title,
+  subtitle,
+  children,
+}: {
+  title: string;
+  subtitle: string;
+  children: ReactNode;
+}) {
+  return (
+    <div
+      className="mx-auto w-full max-w-5xl px-10 py-12"
+      style={{
+        fontFamily: 'var(--font-sans)',
+        color: 'var(--color-foreground)',
+        background: 'var(--color-background)',
+      }}
+    >
+      {/* 页眉:档案抬头 + 元信息条 */}
+      <header className="mb-12 flex items-end justify-between gap-8 border-b-2 border-foreground pb-6">
+        <div>
+          <p className="font-mono text-xxs uppercase tracking-widest text-muted-foreground">
+            Teamix Evo · Token Atlas
+          </p>
+          <h2 className="mt-3 text-3xl font-medium tracking-tight">{title}</h2>
+          <p className="mt-2 max-w-prose text-sm leading-relaxed text-muted-foreground">
+            {subtitle}
+          </p>
+        </div>
+        <ThemeBadge />
+      </header>
+      {children}
+      <footer className="mt-16 border-t border-border pt-4 font-mono text-xxs uppercase tracking-widest text-muted-foreground">
+        values resolved at runtime · getComputedStyle(:root)
+      </footer>
+    </div>
+  );
+}
+
+/** 顶栏当前主题徽标 — 跟着 data-theme 实时刷新。 */
+function ThemeBadge() {
+  const tick = useThemeTick();
+  const theme = useMemo(() => {
+    if (typeof document === 'undefined') return 'opentrek';
+    void tick;
+    return document.documentElement.getAttribute('data-theme') || 'opentrek';
+  }, [tick]);
+
+  return (
+    <div className="flex items-center gap-2 border border-foreground px-3 py-1.5">
+      <span
+        className="inline-block size-2 rounded-full"
+        style={{ background: 'var(--color-primary)' }}
+        aria-hidden
+      />
+      <span className="font-mono text-xxs uppercase tracking-widest">
+        {theme}
+      </span>
+    </div>
+  );
+}
+
+// ── Color story ────────────────────────────────────────────────────────────
+
+function ColorSwatch({
+  token,
+  optional,
+}: {
+  token: string;
+  optional?: boolean;
+}) {
+  const tick = useThemeTick();
+  const varName = `--color-${token}`;
+  const value = useMemo(() => readVar(varName), [varName, tick]);
+  const isForeground = token.endsWith('-foreground');
+
+  // optional 且当前 variant 未声明 → 整行隐藏,避免视觉噪音
+  if (optional && !value) return null;
+
+  // 给 foreground token 配对 chip:在对应的容器色块上绘制实际文字
+  const pairBg = isForeground
+    ? `--color-${token.replace(/-foreground$/, '')}`
+    : null;
+
+  return (
+    <AtlasRow name={varName} value={value}>
+      <div className="flex items-stretch gap-3">
+        <div
+          className="h-14 w-24 border border-border/60"
+          style={{ background: `var(${varName})` }}
+          aria-label={`${token} swatch`}
+        />
+        {pairBg ? (
+          <div
+            className="flex h-14 flex-1 items-center justify-center border border-border/60 px-3"
+            style={{ background: `var(${pairBg})`, color: `var(${varName})` }}
+          >
+            <span className="font-mono text-xs uppercase tracking-widest">
+              on {pairBg.replace('--color-', '')}
+            </span>
+          </div>
+        ) : (
+          <div className="flex h-14 flex-1 items-center border border-dashed border-border/60 px-4">
+            <span className="font-mono text-xxs uppercase tracking-widest text-muted-foreground">
+              bg-{token}
+            </span>
+          </div>
+        )}
+      </div>
+    </AtlasRow>
+  );
+}
+
+/** Charts 调色板专用 chip — 紧凑展示色值 + 序号。 */
+function ChartChip({ token }: { token: string }) {
+  const tick = useThemeTick();
+  const varName = `--color-${token}`;
+  const value = useMemo(() => readVar(varName), [varName, tick]);
+  if (!value) return null;
+  return (
+    <div className="flex flex-col gap-1.5">
+      <div
+        className="h-12 w-full border border-border/60"
+        style={{ background: `var(${varName})` }}
+      />
+      <code className="font-mono text-xxs uppercase tracking-widest text-muted-foreground">
+        {token}
+      </code>
+      <code className="font-mono text-xxs text-foreground/70">{value}</code>
+    </div>
+  );
+}
+
+export const Color: StoryObj = {
+  name: '01 · Color',
+  parameters: {
+    layout: 'fullscreen',
+    controls: { disable: true },
+    docs: {
+      description: {
+        story:
+          '颜色档案:按品牌 / 灰阶 / 容器 / 边框 / 状态(success/destructive/warning/info/help) / 侧栏 / 数据可视化七组陈列。每条同时展示变量名、HSL/HEX 原值,以及与之配对的 foreground 在容器色上的真实可读性。`optional` 档位若当前 variant 未声明,整行隐藏。',
+      },
+    },
+  },
+  render: () => (
+    <AtlasFrame
+      title="Color · 颜色档案"
+      subtitle="所有语义色槽位的当前生效值。foreground 直接绘制在对应容器色上,可一眼判断对比度是否过关。"
+    >
+      {COLOR_GROUPS.map((group, i) => (
+        <GroupBlock
+          key={group.label}
+          index={`§ 01.${String(i + 1).padStart(2, '0')}`}
+          label={group.label}
+          caption={group.caption ?? `${group.tokens.length} tokens`}
+        >
+          {group.tokens.map((t) => (
+            <ColorSwatch key={t.name} token={t.name} optional={t.optional} />
+          ))}
+        </GroupBlock>
+      ))}
+      <GroupBlock
+        index={`§ 01.${String(COLOR_GROUPS.length + 1).padStart(2, '0')}`}
+        label="Charts · 数据可视化"
+        caption="op 10 色 / um 5 色"
+      >
+        <div className="grid grid-cols-5 gap-4">
+          {CHART_TOKENS.map((c) => (
+            <ChartChip key={c.name} token={c.name} />
+          ))}
+        </div>
+      </GroupBlock>
+    </AtlasFrame>
+  ),
+};
+
+// ── Corner story ──────────────────────────────────────────────────────────
+
+function RadiusRow({ k, cls }: { k: string; cls: string }) {
+  const probeRef = useRef<HTMLDivElement | null>(null);
+  const tick = useThemeTick();
+  const [value, setValue] = useState('');
+  useLayoutEffect(() => {
+    if (!probeRef.current) return;
+    setValue(getComputedStyle(probeRef.current).borderTopLeftRadius);
+  }, [cls, tick]);
+
+  return (
+    <AtlasRow name={`rounded-${k}`} value={fmtLength(value)}>
+      <div className="flex items-center gap-4">
+        {/* 隐形 probe 用来取值,与可见样本同一 class 同一渲染路径 */}
+        <div ref={probeRef} className={cls} style={{ display: 'none' }} />
+        <div
+          className={`flex h-16 w-16 items-center justify-center border-2 border-foreground ${cls}`}
+          aria-label={`rounded-${k} sample`}
+        >
+          <span className="font-mono text-xxs uppercase tracking-widest">
+            {k}
+          </span>
+        </div>
+        <div
+          className={`flex h-16 w-32 items-end justify-end border border-border bg-muted p-2 ${cls}`}
+        >
+          <span className="font-mono text-xxs uppercase tracking-widest text-muted-foreground">
+            surface
+          </span>
+        </div>
+      </div>
+    </AtlasRow>
+  );
+}
+
+/** 组件专属圆角条目 — 通过自定义 var 读取(没有则隐藏整条)。 */
+function ComponentRadiusRow({
+  name,
+  varName,
+}: {
+  name: string;
+  varName: string;
+}) {
+  const tick = useThemeTick();
+  const value = useMemo(() => readVar(varName), [varName, tick]);
+  if (!value) return null;
+  return (
+    <AtlasRow name={varName} value={fmtLength(value)}>
+      <div
+        className="flex h-16 w-32 items-center justify-center border-2 border-dashed border-foreground bg-muted"
+        style={{ borderRadius: `var(${varName})` }}
+      >
+        <span className="font-mono text-xxs uppercase tracking-widest">
+          {name}
+        </span>
+      </div>
+    </AtlasRow>
+  );
+}
+
+/** Token base 圆角(--radius)— 各 variant 必定声明,值是其余 rounded-* 的基准。 */
+function BaseRadiusRow() {
+  const tick = useThemeTick();
+  const value = useMemo(() => readVar('--radius'), [tick]);
+  return (
+    <AtlasRow name="--radius" value={fmtLength(value)}>
+      <div
+        className="flex h-16 w-32 items-center justify-center border-2 border-foreground bg-card"
+        style={{ borderRadius: 'var(--radius)' }}
+      >
+        <span className="font-mono text-xxs uppercase tracking-widest">
+          base
+        </span>
+      </div>
+    </AtlasRow>
+  );
+}
+
+export const Corner: StoryObj = {
+  name: '02 · Corner',
+  parameters: {
+    layout: 'fullscreen',
+    controls: { disable: true },
+    docs: {
+      description: {
+        story:
+          '圆角档案:Tailwind v4 实际生效的 rounded-{sm/md/lg/xl/2xl/full} 几何形态 + 组件级别名 (--radius-dialog / --radius-tag / --radius-checkbox)。值随主题变化(opentrek 圆润 4–16px,uni-manager 锐利 0–12px 阶梯)。',
+      },
+    },
+  },
+  render: () => (
+    <AtlasFrame
+      title="Corner · 圆角档案"
+      subtitle="每条展示一个 Tailwind 圆角档位的实际曲率。左侧粗描边样本看几何形态,右侧填色样本看落到 surface 上的视觉重量。"
+    >
+      <GroupBlock
+        index="§ 02.01"
+        label="Scale · 阶梯"
+        caption={`${RADIUS_SCALE.length} steps`}
+      >
+        {RADIUS_SCALE.map((r) => (
+          <RadiusRow key={r.key} k={r.key} cls={r.cls} />
+        ))}
+      </GroupBlock>
+      <GroupBlock
+        index="§ 02.02"
+        label="Component · 组件级别名"
+        caption="optional · 缺失自动隐藏"
+      >
+        <BaseRadiusRow />
+        {COMPONENT_RADIUS.map((c) => (
+          <ComponentRadiusRow
+            key={c.varName}
+            name={c.name}
+            varName={c.varName}
+          />
+        ))}
+      </GroupBlock>
+    </AtlasFrame>
+  ),
+};
+
+// ── Shadow story ──────────────────────────────────────────────────────────
+
+function ShadowRow({
+  k,
+  cls,
+  varName,
+}: {
+  k: string;
+  cls: string;
+  varName?: string;
+}) {
+  const probeRef = useRef<HTMLDivElement | null>(null);
+  const tick = useThemeTick();
+  const [value, setValue] = useState('');
+  // optional 档位：当前 variant 未声明该 var 则隐藏
+  const declared = useMemo(
+    () => (varName ? !!readVar(varName) : true),
+    [varName, tick],
+  );
+  useLayoutEffect(() => {
+    if (!probeRef.current) return;
+    setValue(getComputedStyle(probeRef.current).boxShadow);
+  }, [cls, tick]);
+
+  if (!declared) return null;
+
+  return (
+    <AtlasRow name={`shadow-${k}`} value={value || 'none'}>
+      <div className="flex items-center gap-6 py-3">
+        <div ref={probeRef} className={cls} style={{ display: 'none' }} />
+        <div
+          className={`flex h-20 w-32 items-center justify-center border border-border bg-card ${cls}`}
+        >
+          <span className="font-mono text-xxs uppercase tracking-widest text-muted-foreground">
+            shadow-{k}
+          </span>
+        </div>
+        <div className="flex-1 text-xs leading-relaxed text-muted-foreground">
+          <p className="break-all font-mono">{value || '—'}</p>
+        </div>
+      </div>
+    </AtlasRow>
+  );
+}
+
+/** 组件级阴影条目 — 直接读 token,缺失整行隐藏。 */
+function ComponentShadowRow({
+  name,
+  varName,
+}: {
+  name: string;
+  varName: string;
+}) {
+  const tick = useThemeTick();
+  const value = useMemo(() => readVar(varName), [varName, tick]);
+  if (!value) return null;
+  return (
+    <AtlasRow name={varName} value={value}>
+      <div className="flex items-center gap-6 py-3">
+        <div
+          className="flex h-20 w-32 items-center justify-center border border-border bg-card"
+          style={{ boxShadow: `var(${varName})` }}
+        >
+          <span className="font-mono text-xxs uppercase tracking-widest text-muted-foreground">
+            {name}
+          </span>
+        </div>
+        <div className="flex-1 text-xs leading-relaxed text-muted-foreground">
+          <p className="break-all font-mono">{value}</p>
+        </div>
+      </div>
+    </AtlasRow>
+  );
+}
+
+export const Shadow: StoryObj = {
+  name: '03 · Shadow',
+  parameters: {
+    layout: 'fullscreen',
+    controls: { disable: true },
+    docs: {
+      description: {
+        story:
+          '阴影档案:5 档 Tailwind shadow utility + 组件级别名 (--shadow-dialog / --drawer-shadow / --shadow-select-content / --shadow-form-hover) 落在 card surface 上的真实视觉。展开值显示完整 box-shadow 串。',
+      },
+    },
+  },
+  render: () => (
+    <AtlasFrame
+      title="Shadow · 阴影档案"
+      subtitle="每档以 card 容器为载体,展示阴影对悬浮层级的真实贡献。展开值显示完整 box-shadow 串。"
+    >
+      <GroupBlock
+        index="§ 03.01"
+        label="Elevation · 阶梯"
+        caption={`${SHADOW_SCALE.length} steps`}
+      >
+        {SHADOW_SCALE.map((s) => (
+          <ShadowRow key={s.key} k={s.key} cls={s.cls} varName={s.varName} />
+        ))}
+      </GroupBlock>
+      <GroupBlock
+        index="§ 03.02"
+        label="Component · 组件级别名"
+        caption="optional · 缺失自动隐藏"
+      >
+        {COMPONENT_SHADOWS.map((c) => (
+          <ComponentShadowRow
+            key={c.varName}
+            name={c.name}
+            varName={c.varName}
+          />
+        ))}
+      </GroupBlock>
+    </AtlasFrame>
+  ),
+};
+
+// ── Text story ────────────────────────────────────────────────────────────
+
+function TextSizeRow({
+  k,
+  cls,
+  px,
+  semantic,
+}: {
+  k: string;
+  cls: string;
+  px: number;
+  semantic?: string;
+}) {
+  const probeRef = useRef<HTMLDivElement | null>(null);
+  const tick = useThemeTick();
+  const [value, setValue] = useState('');
+  useLayoutEffect(() => {
+    if (!probeRef.current) return;
+    setValue(getComputedStyle(probeRef.current).fontSize);
+  }, [cls, tick]);
+
+  return (
+    <AtlasRow
+      name={`text-${k}`}
+      value={`${value || `${px}px`} · spec ${px}px${
+        semantic ? ` · ${semantic}` : ''
+      }`}
+    >
+      <div className={`flex items-baseline gap-4 ${cls}`}>
+        <span ref={probeRef} className={cls} style={{ display: 'none' }} />
+        <span className="font-medium tracking-tight">敏捷的设计系统</span>
+        <span className="text-muted-foreground">— Token Atlas</span>
+      </div>
+    </AtlasRow>
+  );
+}
+
+/** 语义字号 token 行 — 如 --text-xxs / --text-display-3,独立于 Tailwind 默认 8 档之外。 */
+function TextSemanticRow({
+  varName,
+  px,
+  semantic,
+}: {
+  varName: string;
+  px: number;
+  semantic: string;
+}) {
+  const tick = useThemeTick();
+  const value = useMemo(() => readVar(varName), [varName, tick]);
+  if (!value) return null;
+  return (
+    <AtlasRow
+      name={varName}
+      value={`${fmtLength(value)} · spec ${px}px · ${semantic}`}
+    >
+      <div
+        className="flex items-baseline gap-4"
+        style={{ fontSize: `var(${varName})` }}
+      >
+        <span className="font-medium tracking-tight">敏捷的设计系统</span>
+        <span className="text-muted-foreground">— Token Atlas</span>
+      </div>
+    </AtlasRow>
+  );
+}
+
+function TextWeightRow({
+  k,
+  cls,
+  weight,
+  tokenVar,
+}: {
+  k: string;
+  cls: string;
+  weight: number;
+  tokenVar?: string;
+}) {
+  const probeRef = useRef<HTMLSpanElement | null>(null);
+  const tick = useThemeTick();
+  const [value, setValue] = useState('');
+  useLayoutEffect(() => {
+    if (!probeRef.current) return;
+    setValue(getComputedStyle(probeRef.current).fontWeight);
+  }, [cls, tick]);
+
+  // tokenVar 缺失则不在右侧标注 token 别名(说明这一档只是 Tailwind utility,无 token 声明)
+  const aliasNote = tokenVar ? ` · ${tokenVar}` : ' · utility-only';
+
+  return (
+    <AtlasRow
+      name={`font-${k}`}
+      value={`${value || weight} · ${weight}${aliasNote}`}
+    >
+      <div className="flex items-baseline gap-4 text-xl">
+        <span ref={probeRef} className={`${cls} tracking-tight`}>
+          The quick brown fox · 敏捷的棕狐狸
+        </span>
+      </div>
+    </AtlasRow>
+  );
+}
+
+function FontFamilyRow({ token, sample }: { token: string; sample: string }) {
+  const tick = useThemeTick();
+  const value = useMemo(() => readVar(token), [token, tick]);
+  return (
+    <AtlasRow name={token} value={value || '—'}>
+      <p
+        className="text-lg tracking-tight"
+        style={{ fontFamily: `var(${token})` }}
+      >
+        {sample}
+      </p>
+    </AtlasRow>
+  );
+}
+
+export const Text: StoryObj = {
+  name: '04 · Text',
+  parameters: {
+    layout: 'fullscreen',
+    controls: { disable: true },
+    docs: {
+      description: {
+        story:
+          '文字档案:Tailwind 8 档字号(含语义映射 body-1/body-2/subhead/title/headline/display-1/display-2) + 语义 token (--text-xxs / --text-display-3 / --font-size-page-header) + 5 档字重 (font-normal/medium/semibold/bold/black) + sans/mono 字体族。所有数值由 probe 元素的 computed font-size / font-weight 反推,与业务实际渲染完全一致。',
+      },
+    },
+  },
+  render: () => (
+    <AtlasFrame
+      title="Text · 文字档案"
+      subtitle="字号、字重、字体族三组。中英文混排样本同时验证拉丁字形和 CJK 字形的视觉协调。"
+    >
+      <GroupBlock
+        index="§ 04.01"
+        label="Size · 字号"
+        caption={`${TEXT_SIZES.length} Tailwind + ${TEXT_SEMANTIC_TOKENS.length} semantic`}
+      >
+        {TEXT_SIZES.map((s) => (
+          <TextSizeRow
+            key={s.key}
+            k={s.key}
+            cls={s.cls}
+            px={s.px}
+            semantic={s.semantic}
+          />
+        ))}
+        {TEXT_SEMANTIC_TOKENS.map((t) => (
+          <TextSemanticRow
+            key={t.varName}
+            varName={t.varName}
+            px={t.px}
+            semantic={t.semantic}
+          />
+        ))}
+      </GroupBlock>
+      <GroupBlock
+        index="§ 04.02"
+        label="Weight · 字重"
+        caption={`${TEXT_WEIGHTS.length} steps`}
+      >
+        {TEXT_WEIGHTS.map((w) => (
+          <TextWeightRow
+            key={w.key}
+            k={w.key}
+            cls={w.cls}
+            weight={w.weight}
+            tokenVar={w.tokenVar}
+          />
+        ))}
+      </GroupBlock>
+      <GroupBlock index="§ 04.03" label="Family · 字体族">
+        <FontFamilyRow
+          token="--font-sans"
+          sample="Sans · 设计系统的呼吸感 0123456789"
+        />
+        <FontFamilyRow
+          token="--font-mono"
+          sample="Mono · const tokens = readAtlas() // 0O1lI"
+        />
+      </GroupBlock>
+    </AtlasFrame>
+  ),
+};
+
+// ── Layout story ───────────────────────────────────────────────────────────
+
+/** 通用 Layout token 行 — 文字 + 尺寸条形可视化(纵横任选)。 */
+function LayoutRow({
+  varName,
+  semantic,
+  axis = 'x',
+  optional,
+}: {
+  varName: string;
+  semantic?: string;
+  axis?: 'x' | 'y';
+  optional?: boolean;
+}) {
+  const tick = useThemeTick();
+  const value = useMemo(() => readVar(varName), [varName, tick]);
+  if (optional && !value) return null;
+
+  // viewport 占比的值(90vw / 85vh)不做条形,只展示数字
+  const isViewport = /v[wh]/.test(value);
+
+  return (
+    <AtlasRow
+      name={varName}
+      value={`${fmtLength(value)}${semantic ? ` · ${semantic}` : ''}`}
+    >
+      {isViewport ? (
+        <div className="flex h-12 items-center font-mono text-xxs uppercase tracking-widest text-muted-foreground">
+          relative · {value}
+        </div>
+      ) : axis === 'x' ? (
+        <div className="flex items-center gap-3">
+          <div
+            className="h-8 border border-foreground bg-muted"
+            style={{ width: `var(${varName})`, maxWidth: '100%' }}
+            aria-label={`${varName} bar`}
+          />
+          <span className="font-mono text-xxs uppercase tracking-widest text-muted-foreground">
+            ↔ width
+          </span>
+        </div>
+      ) : (
+        <div className="flex items-end gap-3">
+          <div
+            className="w-8 border border-foreground bg-muted"
+            style={{ height: `var(${varName})`, maxHeight: '120px' }}
+            aria-label={`${varName} bar`}
+          />
+          <span className="font-mono text-xxs uppercase tracking-widest text-muted-foreground">
+            ↕ height
+          </span>
+        </div>
+      )}
+    </AtlasRow>
+  );
+}
+
+/** Form spacing 行 — gap 用两段虚线 + 中间空白尺度示意。 */
+function SpacingRow({
+  varName,
+  semantic,
+}: {
+  varName: string;
+  semantic: string;
+}) {
+  const tick = useThemeTick();
+  const value = useMemo(() => readVar(varName), [varName, tick]);
+  if (!value) return null;
+  return (
+    <AtlasRow name={varName} value={`${fmtLength(value)} · ${semantic}`}>
+      <div className="flex flex-col">
+        <div className="flex h-6 items-center border border-dashed border-foreground/60 px-2 font-mono text-xxs uppercase tracking-widest text-muted-foreground">
+          element-A
+        </div>
+        <div
+          className="w-full border-l-2 border-r-2 border-primary"
+          style={{ height: `var(${varName})`, minHeight: '2px' }}
+          aria-label={`gap ${varName}`}
+        />
+        <div className="flex h-6 items-center border border-dashed border-foreground/60 px-2 font-mono text-xxs uppercase tracking-widest text-muted-foreground">
+          element-B
+        </div>
+      </div>
+    </AtlasRow>
+  );
+}
+
+const LAYOUT_CONTAINER: Array<{
+  varName: string;
+  semantic: string;
+  axis?: 'x' | 'y';
+}> = [
+  {
+    varName: '--layout-sidebar-width',
+    semantic: 'L1 Sidebar 展开宽',
+    axis: 'x',
+  },
+  { varName: '--topbar-height', semantic: '顶栏高度', axis: 'y' },
+  { varName: '--page-header-height', semantic: 'PageHeader 高度', axis: 'y' },
+  { varName: '--page-container-gap', semantic: '白卡外间距', axis: 'x' },
+  {
+    varName: '--page-container-padding',
+    semantic: 'PageContainer 内边距',
+    axis: 'x',
+  },
+  {
+    varName: '--page-container-padding-left',
+    semantic: '主区左缘内边距',
+    axis: 'x',
+  },
+];
+
+const LAYOUT_DIALOG: Array<{ varName: string; semantic: string }> = [
+  { varName: '--layout-dialog-sm', semantic: 'Dialog SM' },
+  { varName: '--layout-dialog-md', semantic: 'Dialog MD' },
+  { varName: '--layout-dialog-lg', semantic: 'Dialog LG' },
+  { varName: '--layout-dialog-xl', semantic: 'Dialog XL' },
+];
+
+const LAYOUT_DRAWER: Array<{ varName: string; semantic: string }> = [
+  { varName: '--layout-drawer-sm', semantic: 'Drawer SM' },
+  { varName: '--layout-drawer-md', semantic: 'Drawer MD' },
+  { varName: '--layout-drawer-lg', semantic: 'Drawer LG' },
+  { varName: '--layout-drawer-xl', semantic: 'Drawer XL' },
+];
+
+const LAYOUT_FLYOUT: Array<{
+  varName: string;
+  semantic: string;
+  axis?: 'x' | 'y';
+  optional?: boolean;
+}> = [
+  { varName: '--layout-panel-sm', semantic: 'Panel SM' },
+  { varName: '--layout-panel-md', semantic: 'Panel MD' },
+  { varName: '--layout-submenu', semantic: '二级菜单宽' },
+  { varName: '--layout-menu-min', semantic: 'Menu 最小宽' },
+  { varName: '--layout-menu-md', semantic: 'Menu MD' },
+  { varName: '--layout-popover-max', semantic: 'Popover 最大宽' },
+  { varName: '--layout-listbox-max', semantic: 'Listbox 最大宽' },
+  { varName: '--layout-notification', semantic: '通知卡片宽' },
+  { varName: '--layout-counter', semantic: '徽标计数器' },
+  { varName: '--layout-textarea-min', semantic: 'Textarea 最小高', axis: 'y' },
+  { varName: '--layout-image-preview-max-w', semantic: '图片预览最大宽' },
+  {
+    varName: '--layout-image-preview-max-h',
+    semantic: '图片预览最大高',
+    axis: 'y',
+  },
+];
+
+const LAYOUT_FORM: Array<{ varName: string; semantic: string }> = [
+  { varName: '--spacing-form-label-to-input', semantic: 'label → input' },
+  { varName: '--spacing-form-error-to-input', semantic: 'error → input' },
+  { varName: '--spacing-form-help-to-input', semantic: 'help → input' },
+  { varName: '--spacing-form-item-gap', semantic: '同区域 item 间距' },
+  { varName: '--spacing-form-section-gap', semantic: '区域间距' },
+  { varName: '--spacing-form-section-title-gap', semantic: '区域标题间距' },
+];
+
+export const Layout: StoryObj = {
+  name: '05 · Layout',
+  parameters: {
+    layout: 'fullscreen',
+    controls: { disable: true },
+    docs: {
+      description: {
+        story:
+          '布局档案:容器骨架(sidebar / topbar / page-header / page-container) + 浮层尺寸阶梯(dialog / drawer / panel / submenu / menu / popover / listbox / notification / textarea / image-preview)+ Form 区域间距体系。每条按真实 token 值绘制比例条形,可一眼对比 SM→XL 阶梯。',
+      },
+    },
+  },
+  render: () => (
+    <AtlasFrame
+      title="Layout · 布局档案"
+      subtitle="容器、组件浮层、Form 间距三组。横竖条形按 token 真实长度绘制(超过容器宽则截断显示数值)。"
+    >
+      <GroupBlock
+        index="§ 05.01"
+        label="Container · 容器骨架"
+        caption={`${LAYOUT_CONTAINER.length} tokens`}
+      >
+        {LAYOUT_CONTAINER.map((t) => (
+          <LayoutRow key={t.varName} {...t} />
+        ))}
+      </GroupBlock>
+      <GroupBlock
+        index="§ 05.02"
+        label="Dialog · 对话框尺寸阶梯"
+        caption="SM → XL"
+      >
+        {LAYOUT_DIALOG.map((t) => (
+          <LayoutRow key={t.varName} {...t} />
+        ))}
+      </GroupBlock>
+      <GroupBlock
+        index="§ 05.03"
+        label="Drawer · 抽屉尺寸阶梯"
+        caption="SM → XL"
+      >
+        {LAYOUT_DRAWER.map((t) => (
+          <LayoutRow key={t.varName} {...t} />
+        ))}
+      </GroupBlock>
+      <GroupBlock
+        index="§ 05.04"
+        label="Flyout · 浮层与组件最值"
+        caption={`${LAYOUT_FLYOUT.length} tokens`}
+      >
+        {LAYOUT_FLYOUT.map((t) => (
+          <LayoutRow key={t.varName} {...t} />
+        ))}
+      </GroupBlock>
+      <GroupBlock
+        index="§ 05.05"
+        label="Form · 间距体系"
+        caption={`${LAYOUT_FORM.length} tokens`}
+      >
+        {LAYOUT_FORM.map((t) => (
+          <SpacingRow key={t.varName} {...t} />
+        ))}
+      </GroupBlock>
+    </AtlasFrame>
+  ),
+};
+
+// ── Motion story ──────────────────────────────────────────────────────────
+
+/** Duration 行 — 实时循环动画演示真实节奏感。 */
+function DurationRow({
+  varName,
+  semantic,
+}: {
+  varName: string;
+  semantic: string;
+}) {
+  const tick = useThemeTick();
+  const value = useMemo(() => readVar(varName), [varName, tick]);
+  if (!value) return null;
+  return (
+    <AtlasRow name={varName} value={`${value} · ${semantic}`}>
+      <div className="flex items-center gap-4">
+        <div
+          className="relative h-2 w-48 overflow-hidden border border-foreground/60 bg-muted"
+          aria-label={`${varName} animation track`}
+        >
+          <div
+            className="absolute inset-y-0 left-0 w-6 bg-primary"
+            style={{
+              animation: `atlas-shuttle var(${varName}) ease-in-out infinite alternate`,
+            }}
+          />
+        </div>
+        <span className="font-mono text-xxs uppercase tracking-widest text-muted-foreground">
+          loop · ease-in-out
+        </span>
+      </div>
+    </AtlasRow>
+  );
+}
+
+/** Overlay 行 — 在棋盘格上叠覆盖色,直观展示透明度。 */
+function OverlayRow({
+  varName,
+  semantic,
+}: {
+  varName: string;
+  semantic: string;
+}) {
+  const tick = useThemeTick();
+  const value = useMemo(() => readVar(varName), [varName, tick]);
+  if (!value) return null;
+  return (
+    <AtlasRow name={varName} value={`${value} · ${semantic}`}>
+      <div
+        className="relative h-14 w-full overflow-hidden border border-border"
+        style={{
+          backgroundImage:
+            'linear-gradient(45deg, var(--color-muted) 25%, transparent 25%), linear-gradient(-45deg, var(--color-muted) 25%, transparent 25%), linear-gradient(45deg, transparent 75%, var(--color-muted) 75%), linear-gradient(-45deg, transparent 75%, var(--color-muted) 75%)',
+          backgroundSize: '12px 12px',
+          backgroundPosition: '0 0, 0 6px, 6px -6px, -6px 0',
+        }}
+      >
+        <div
+          className="absolute inset-0"
+          style={{ background: `var(${varName})` }}
+        />
+      </div>
+    </AtlasRow>
+  );
+}
+
+/** Z-index 行 — 用层叠卡片直观展示槽位距离。 */
+function ZIndexRow({
+  varName,
+  semantic,
+}: {
+  varName: string;
+  semantic: string;
+}) {
+  const tick = useThemeTick();
+  const value = useMemo(() => readVar(varName), [varName, tick]);
+  if (!value) return null;
+  const numeric = parseInt(value, 10);
+  // 把 0~500 的 z-index 映射成 0~120px 的 translateY,让差距可视化
+  const offset = Number.isFinite(numeric) ? Math.min(120, numeric * 0.24) : 0;
+  return (
+    <AtlasRow name={varName} value={`z = ${value} · ${semantic}`}>
+      <div className="relative h-24 w-full">
+        <div className="absolute inset-x-0 bottom-0 h-px bg-foreground/40" />
+        <div
+          className="absolute left-4 flex h-12 w-32 items-center justify-center border border-foreground bg-card font-mono text-xxs uppercase tracking-widest shadow-md"
+          style={{ bottom: `${offset}px` }}
+        >
+          z = {value}
+        </div>
+      </div>
+    </AtlasRow>
+  );
+}
+
+const MOTION_DURATIONS: Array<{ varName: string; semantic: string }> = [
+  { varName: '--duration-fast', semantic: '微交互(hover/focus 反馈)' },
+  { varName: '--duration-normal', semantic: '常规过渡(切换/展开)' },
+  { varName: '--duration-slow', semantic: '面板滑入(drawer/sheet)' },
+  { varName: '--duration-slower', semantic: 'Progress / 长进度' },
+];
+
+const MOTION_OVERLAYS: Array<{ varName: string; semantic: string }> = [
+  { varName: '--overlay-scrim', semantic: '遮罩层(Dialog/Drawer 背后)' },
+  { varName: '--overlay-watermark', semantic: '水印浮层' },
+];
+
+const MOTION_Z: Array<{ varName: string; semantic: string }> = [
+  { varName: '--z-base', semantic: '常规内容' },
+  { varName: '--z-dropdown', semantic: '下拉菜单 / Select' },
+  { varName: '--z-sticky', semantic: '吸顶元素' },
+  { varName: '--z-overlay', semantic: '蒙层' },
+  { varName: '--z-modal', semantic: 'Dialog / Drawer' },
+  { varName: '--z-tooltip', semantic: 'Tooltip / Popover 顶层' },
+];
+
+export const Motion: StoryObj = {
+  name: '06 · Motion',
+  parameters: {
+    layout: 'fullscreen',
+    controls: { disable: true },
+    docs: {
+      description: {
+        story:
+          '动效与层叠档案:Duration 4 档(fast/normal/slow/slower)以循环动画演示真实节奏 + Overlay 蒙层在棋盘格上展示透明度 + Z-index 6 档以浮起卡片高度差直观展示层级距离。',
+      },
+    },
+  },
+  render: () => (
+    <AtlasFrame
+      title="Motion · 动效与层叠"
+      subtitle="Duration / Overlay / Z-index 三组,均为运行时实时读取。Duration 行的循环动画用 ease-in-out 配真实 token 值,可比对节奏差异。"
+    >
+      {/* 注入循环动画 keyframes(scoped on the page,不污染全局 utility) */}
+      <style>{`@keyframes atlas-shuttle { from { transform: translateX(0); } to { transform: translateX(calc(192px - 1.5rem)); } }`}</style>
+      <GroupBlock
+        index="§ 06.01"
+        label="Duration · 时长"
+        caption={`${MOTION_DURATIONS.length} steps`}
+      >
+        {MOTION_DURATIONS.map((t) => (
+          <DurationRow key={t.varName} {...t} />
+        ))}
+      </GroupBlock>
+      <GroupBlock
+        index="§ 06.02"
+        label="Overlay · 蒙层 / 水印"
+        caption={`${MOTION_OVERLAYS.length} tokens`}
+      >
+        {MOTION_OVERLAYS.map((t) => (
+          <OverlayRow key={t.varName} {...t} />
+        ))}
+      </GroupBlock>
+      <GroupBlock
+        index="§ 06.03"
+        label="Z-index · 层叠序"
+        caption={`${MOTION_Z.length} layers`}
+      >
+        {MOTION_Z.map((t) => (
+          <ZIndexRow key={t.varName} {...t} />
+        ))}
+      </GroupBlock>
+    </AtlasFrame>
+  ),
+};
+
+// ── Meta ───────────────────────────────────────────────────────────────────
+
+const meta: Meta = {
+  title: '设计系统 · Design System',
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'Token Atlas — 当前主题(由顶栏 Theme 切换器决定)下,Tailwind v4 实际解析的 6 个维度 token 运行时档案:Color / Corner / Shadow / Text / Layout / Motion。所有值通过 getComputedStyle 实时读取;切换 variant 数值随之刷新。`optional` 档位若当前 variant 未声明,整行自动隐藏。',
+      },
+    },
+  },
+};
+
+export default meta;