@orbit-work/ui 0.1.0

package/src/components/primitives/Dropdown/DropdownSource.test.mjs

@@ -0,0 +1,23 @@
+import assert from "node:assert/strict"
+import { readFile } from "node:fs/promises"
+import test from "node:test"
+
+const source = await readFile(new URL("./index.tsx", import.meta.url), "utf8")
+
+// DS 2.0 蓝图批次②：Dropdown 已并入 Menu 簇，本文件只剩兼容层。形态断言搬去了
+// primitives/Menu/MenuSource.test.mjs，这里只锁「薄」和「不破」两件事。
+
+test("dropdown is a thin deprecated alias, not a second implementation", () => {
+  assert.match(source, /@deprecated/)
+  assert.match(source, /export const Dropdown = MenuSurface/)
+  assert.match(source, /export type DropdownItem = MenuItem/)
+  assert.match(source, /export type DropdownProps = MenuSurfaceProps/)
+  // 兼容层再长出自己的 JSX/状态，就等于合并没做成。
+  assert.doesNotMatch(source, /useState|useRef|createPortal|<div/)
+})
+
+test("the legacy divider value keeps its old shape so old items arrays still work", () => {
+  // MenuSurface 仍识别 { key: "---" }，所以这个常量不能改成 MENU_SEPARATOR 的形态，
+  // 否则包外老代码里的分隔线会变成一个空条目。
+  assert.match(source, /export const DROPDOWN_DIVIDER: DropdownItem = \{ key: "---", label: "" \}/)
+})

package/src/components/primitives/Dropdown/index.tsx

@@ -0,0 +1,29 @@
+/**
+ * Dropdown — 兼容导出（@deprecated · DS 2.0 蓝图批次② 合并件）。
+ *
+ * 蓝图把 Dropdown / RowOverflowMenu / DetailOverflowMenu 合并为一个 `Menu` 簇：
+ * 「面」是 `MenuSurface`，「触发器 + 面」是 `Menu`。本文件只做薄兼容层，属性与
+ * 行为逐字同构（`DropdownProps` 就是 `MenuSurfaceProps`），包内消费方已迁走，
+ * 包外代码可继续 import 而不破。
+ *
+ * 新代码请直接用：
+ * - 自己管开合、只要一张面 → `MenuSurface`
+ * - 触发器 + 菜单（外点关闭、Esc 归位、键盘导航齐备）→ `Menu`
+ */
+import type { MenuItem, MenuSurfaceProps } from "../Menu"
+import { MenuSurface } from "../Menu"
+
+/** @deprecated 改用 `MenuItem`（primitives/Menu）。 */
+export type DropdownItem = MenuItem
+/** @deprecated 改用 `MenuSurfaceProps`。 */
+export type DropdownProps = MenuSurfaceProps
+/** @deprecated 改用 `MenuSurface`（同一实现），或带触发器的 `Menu`。 */
+export const Dropdown = MenuSurface
+
+/**
+ * 分隔项。
+ *
+ * @deprecated 改用 `MENU_SEPARATOR`。旧值形态（`{ key: "---" }`）仍被
+ * `MenuSurface` 识别，所以这里保持原样导出，老 items 数组不用改。
+ */
+export const DROPDOWN_DIVIDER: DropdownItem = { key: "---", label: "" }

package/src/components/primitives/EmptyState/EmptyState.stories.tsx

@@ -0,0 +1,159 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import { Button } from "../Button"
+import { EmptyState } from "./index"
+
+const meta = {
+  title: "Primitives/EmptyState",
+  component: EmptyState,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+} satisfies Meta<typeof EmptyState>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** 标准形（二级 inline 档）：信标 mono 母题（紧裁横向姿态，text-3，不引荧黄）＋ 一句 text-2。 */
+export const MessageOnly: Story = {
+  args: {
+    message: "还没有会话，从左上角新建一个开始。",
+  },
+}
+
+/** 一句话 + 可选主按钮。 */
+export const WithAction: Story = {
+  args: {
+    message: "这个项目还没有定时任务。",
+    actionLabel: "新建任务",
+    onAction: () => {},
+  },
+}
+
+/**
+ * 一级 · page 档（原型定时任务 L1771-1780）：母题 52×32 ＋ 16/500 标题 ＋ 14/1.75 副句，
+ * 版心 `margin:56px auto 0; max-width:440px; gap:14px`。这一档不带钮时也是四件里的三件。
+ */
+export const PageTier: Story = {
+  args: {
+    size: "page",
+    title: "还没有定时任务",
+    message: "把每天都要做的事交出去：到点它自己开一段会话，跑完通知你。",
+  },
+}
+
+/**
+ * page 档 ＋ 实底 CTA：空态是该容器唯一行动入口时走 primary（R4 裁决 6 的同屏行动极记账）。
+ * 同屏页头已有同名主钮时，调用点传 `actionVariant="secondary"` 降描边——见下一条。
+ */
+export const PageTierWithAction: Story = {
+  args: {
+    size: "page",
+    title: "还没有定时任务",
+    message: "把每天都要做的事交出去：到点它自己开一段会话，跑完通知你。",
+    actionLabel: "新建任务",
+    onAction: () => {},
+  },
+}
+
+/** page 档 ＋ 描边 CTA：同屏页头已有同名主钮（定时任务、插件中心），暗档不出现第二块荧黄。 */
+export const PageTierOutlinedAction: Story = {
+  args: {
+    size: "page",
+    title: "还没有发布过站点",
+    message: "在会话里说一句「把这个做成网页」，产物就会出现在这里。",
+    actionLabel: "在会话里新建",
+    actionVariant: "secondary",
+    onAction: () => {},
+  },
+}
+
+/** 卡片式 `variant="card"`（原型 L1841 / 2117 / 2146）：1px 边 ＋ radius-lg ＋ surface 底，一句居中，无母题无钮。 */
+export const Card: Story = {
+  args: {
+    variant: "card",
+    message: "还没跑过。恢复之后到点会自己开一段会话。",
+  },
+  render: (args) => (
+    <div style={{ width: 420 }}>
+      <EmptyState {...args} />
+    </div>
+  ),
+}
+
+/** 纯文本行 `variant="text"`（原型命令面板 L3018 / @ 菜单 L923）：弹层里一行灰字，左对齐，无母题无钮。 */
+export const Text: Story = {
+  args: {
+    variant: "text",
+    message: "没有匹配项",
+  },
+  render: (args) => (
+    <div
+      style={{
+        width: 320,
+        background: "var(--ow-popover-bg, var(--ow-surface))",
+        border: "1px solid var(--ow-border)",
+        borderRadius: "var(--ow-radius-lg)",
+      }}
+    >
+      <EmptyState {...args} />
+    </div>
+  ),
+}
+
+/** 自定义动作区（仍应为按钮类元素）。 */
+export const WithCustomAction: Story = {
+  args: {
+    message: "没有找到匹配的技能。",
+    action: (
+      <Button variant="secondary" size="md">
+        清除筛选
+      </Button>
+    ),
+  },
+}
+
+/** 紧凑档 `size="sm"`：弹层（菜单/下拉/命令面板）里的空态，母题 28 ＋内距收到 12/16。 */
+export const CompactTier: Story = {
+  args: {
+    size: "sm",
+    message: "没有匹配的结果。",
+  },
+}
+
+/** 紧凑档也能带按钮，按钮随档落 sm（28px）。 */
+export const CompactWithAction: Story = {
+  args: {
+    size: "sm",
+    message: "这个列表是空的。",
+    actionLabel: "去添加",
+    onAction: () => {},
+  },
+}
+
+/** `markSize` 仍是逃生舱：只调母题**宽度**（高按 1.62:1 自动算）、不动内距（旧调用点靠它，签名不删）。 */
+export const CompactMark: Story = {
+  args: {
+    message: "暂无通知。",
+    markSize: 28,
+  },
+}
+
+export const InPanel: Story = {
+  render: () => (
+    <div
+      style={{
+        width: 420,
+        minHeight: 240,
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        background: "var(--ow-surface)",
+        border: "1px solid var(--ow-border)",
+        borderRadius: "var(--ow-radius-card, 12px)",
+      }}
+    >
+      <EmptyState message="回收站是空的。" />
+    </div>
+  ),
+}

package/src/components/primitives/EmptyState/EmptyStateSource.test.mjs

@@ -0,0 +1,169 @@
+import assert from "node:assert/strict"
+import { readFile } from "node:fs/promises"
+import test from "node:test"
+
+const source = await readFile(new URL("./index.tsx", import.meta.url), "utf8")
+
+/**
+ * 剥注释后的代码面。DS2 的架构注释里大量复述**被撤销的旧写法**（"原 viewBox 0 0 96 96"、
+ * "撤销 joinSentence"…），不剥注释这些反向断言会被自己的注释打中。同 scripts/ds2-rules.mjs 的做法。
+ */
+const stripComments = (text) =>
+  text.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, " ")).replace(/(^|[^:\\])\/\/[^\n]*/g, "$1")
+const code = stripComments(source)
+
+// R4 原型对齐轮（裁决 6）：母题改吃原型的紧裁 bbox，六颗圆坐标不变、取景框不再旋转。
+// 旧断言压的是 viewBox="0 0 96 96" + rotate(24 48 48)，那正是「母题太小」的物理根因
+// （40×40 槽位里字形只画出 32.9×25.3px），按新口径反向重写。BeaconSpinner rest 姿态不动。
+test("EmptyState mark is the beacon dots in the prototype's tight横向 bbox, no rotation, single color", () => {
+  assert.match(source, /MARK_VIEW_BOX = "13 11\.7 73\.4 45\.3"/)
+  assert.match(source, /viewBox=\{MARK_VIEW_BOX\}/)
+  assert.doesNotMatch(code, /viewBox="0 0 96 96"/)
+  assert.doesNotMatch(code, /rotate\(/)
+  // 六颗圆坐标/半径逐条锁定（几何同 BeaconSpinner，勿改）
+  assert.match(source, /cx="48" cy="48" r="8\.2"/)
+  assert.match(source, /cx="60\.2" cy="20\.6" r="6\.7"/)
+  assert.match(source, /cx="41\.76" cy="18\.66" r="5\.5"/)
+  assert.match(source, /cx="25\.71" cy="27\.93" r="4\.3"/)
+  assert.match(source, /cx="18\.16" cy="44\.86" r="3\.3"/)
+  assert.match(source, /cx="75\.4" cy="35\.8" r="10\.4"/)
+  // markSize 给宽，高按紧裁比例算（52 → 32）
+  assert.match(source, /MARK_RATIO = 45\.3 \/ 73\.4/)
+  assert.match(source, /height=\{Math\.round\(size \* MARK_RATIO\)\}/)
+  assert.match(source, /--ow-empty-mark/)
+})
+
+test("EmptyState never touches the beacon yellow poles (R3 neutral, mark = text-3 tone)", () => {
+  assert.doesNotMatch(code, /--ow-beacon|--ow-accent-dot|--ow-yellow/)
+})
+
+test("EmptyState = mark + optional 16/500 title + text-2 sentence + optional button", () => {
+  assert.match(source, /text-\[color:var\(--ow-text-2\)\]/)
+  assert.match(source, /actionLabel\?: string/)
+  assert.match(source, /role="status"/)
+  // R4：标题槽（16/500 --ow-text）回到原语，不再由调用点拼句
+  assert.match(source, /title\?: ReactNode/)
+  assert.match(source, /text-ow-fs-subtitle font-medium/)
+  assert.match(source, /text-\[color:var\(--ow-text\)\]/)
+  // page 档副句升到 --ow-fs-body 14/1.75（原型 L1777），md/sm 仍 --ow-fs-ui
+  assert.match(source, /text-ow-fs-body leading-\[1\.75\]/)
+  assert.match(source, /text-ow-fs-ui leading-normal/)
+})
+
+// R2 记的是「空态一律 secondary」；R4 裁决 6 改判为**同屏行动极记账**：
+// page 档默认 primary（空态是该容器唯一行动入口），同屏已有同名主钮时调用点传
+// actionVariant="secondary" 降描边。md/sm 两档默认仍 secondary。
+test("R4 改判：动作钮档位随 size 档，可被 actionVariant 覆写", () => {
+  assert.match(source, /actionVariant\?: "primary" \| "secondary"/)
+  assert.match(source, /variant=\{actionVariant \?\? metrics\.action\}/)
+  assert.match(source, /page: \{ mark: 52,[^}]*action: "primary"/)
+  assert.match(source, /md: \{ mark: 40,[^}]*action: "secondary"/)
+  assert.match(source, /sm: \{ mark: 28,[^}]*action: "secondary"/)
+  // 原语自己不再写死某一个 variant 字面量
+  assert.doesNotMatch(code, /<Button variant="(primary|secondary)"/)
+})
+
+// 原型的两种无母题退化形（裁决 6：一并收进原语，全库四档一套语法）。
+test('variant="card" 是 1px 边 + radius-lg + surface 底的居中一句，无母题无钮', () => {
+  assert.match(source, /export type EmptyStateVariant = "default" \| "card" \| "text"/)
+  assert.match(source, /variant === "card"/)
+  assert.match(
+    source,
+    /border border-\[color:var\(--ow-border\)\] \[border-radius:var\(--ow-radius-lg\)\] bg-\[var\(--ow-surface\)\]/,
+  )
+  assert.match(source, /px-4 py-7 text-center/)
+  assert.match(source, /data-ow-variant="card"/)
+})
+
+test('variant="text" 是弹层里一行灰字，无母题无钮、左对齐', () => {
+  assert.match(source, /variant === "text"/)
+  assert.match(source, /px-2\.5 py-4 text-ow-fs-ui leading-normal text-\[color:var\(--ow-text-2\)\]/)
+  assert.match(source, /data-ow-variant="text"/)
+})
+
+test("R4 三档：page/md/sm 共用同一套语法，只差度量（弹层不许另造空态）", () => {
+  assert.match(source, /export type EmptyStateSize = "page" \| "sm" \| "md"/)
+  assert.match(source, /size\?: EmptyStateSize/)
+  // 档位表：page 母题 52（版心 56 / 文字量度 440 / gap14），md 40，sm 28。
+  // A5-B3：盒宽写 488＝440 量度 ＋ 2×24 内距——原型那个容器没有横向内距，440 是量度不是盒宽。
+  assert.match(source, /page: \{ mark: 52, box: "gap-3\.5 px-6 mt-14 mx-auto max-w-\[488px\]"/)
+  assert.match(source, /md: \{ mark: 40,/)
+  assert.match(source, /sm: \{ mark: 28,/)
+  // markSize 仍是逃生舱（旧调用点不改签名），不传时随档
+  assert.match(source, /markSize \?\? metrics\.mark/)
+  assert.match(source, /size = "md"/)
+})
+
+// R4 B2：撤销 W3 的 joinSentence 退化——标题与副句拆回两槽，调用点签名不变。
+const TWO_SLOT_CONSUMERS = [
+  [
+    "../../composite/CatalogStates/index.tsx",
+    /title=\{hasHint \? title : undefined\}/,
+    /message=\{hasHint \? hint : title\}/,
+  ],
+  [
+    "../../domain/desktop/DesktopWorkspaceView/index.tsx",
+    /title=\{hasDescription \? title : undefined\}/,
+    /message=\{hasDescription \? description : title\}/,
+  ],
+]
+
+test("R4 B2：CatalogStates / DesktopWorkspaceView 不再把标题副句拼成一句", async () => {
+  for (const [rel, titleSlot, messageSlot] of TWO_SLOT_CONSUMERS) {
+    const consumer = await readFile(new URL(rel, import.meta.url), "utf8")
+    assert.doesNotMatch(stripComments(consumer), /joinSentence/, rel)
+    assert.match(consumer, titleSlot, rel)
+    assert.match(consumer, messageSlot, rel)
+  }
+})
+
+// W5 移交项③：已 G5 但仍手搓紧凑档（markSize + 自写 px-*/py-*）的调用点，
+// 统一改吃档位表。手搓度量＝把档位表复制到调用点，档位一改就分叉。
+// A5-B4 分家：**块内**空态留 sm（母题 ＋ 一句），**弹层**空态改 variant="text"
+//（一行 --ow-fs-ui 灰字、无母题）——原型 @ 菜单 L923 / 命令面板 L3018 就是这一档；
+// 弹层只有一两行高，塞 28px 母题会把面撑成两倍，也让「没搜到」看着像一屏正经空态。
+const COMPACT_CONSUMERS = [
+  // 块内档（sm）：贴地卡里的检索结果 / 追问推荐，母题保留
+  ["../../composite/SearchResult/index.tsx", /<EmptyState message=\{emptyMessage\} size="sm" \/>/],
+  ["../../composite/ContentRecommendation/index.tsx", /<EmptyState message=\{emptyMessage\} size="sm" \/>/],
+  // 弹层档（text）：模型选择器 / 命令面板 / composer @ 菜单 / Menu 面
+  ["../../composite/ModelPickerList/index.tsx", /<EmptyState message=\{message\} variant="text" \/>/],
+  ["../../composite/CommandPalette/index.tsx", /<EmptyState message=\{emptyMessage\} variant="text" \/>/],
+  ["../../domain/chat/Composer/parts/ComposerMenu.tsx", /<EmptyState message=\{emptyMessage\} variant="text" \/>/],
+  ["../Menu/index.tsx", /<EmptyState message=\{empty\} variant="text" \/>/],
+]
+
+test("W5/A5-B4 调用点吃档位表：块内 sm、弹层 text，不再手搓 markSize + 内距", async () => {
+  for (const [rel, expected] of COMPACT_CONSUMERS) {
+    const consumer = await readFile(new URL(rel, import.meta.url), "utf8")
+    assert.match(consumer, expected, rel)
+    // 手搓的紧凑内距整族退场（容器档 md 空态不受影响，它不写这些类）
+    assert.doesNotMatch(consumer, /<EmptyState[^>]*className="(?:gap-2 )?px-\d py-6"/, rel)
+  }
+})
+
+// A5-B3：整页/整栏空态挂 page 一级档（母题 52×32 ＋ 16/500 标题 ＋ 14/1.75 副句），
+// 二级 inline 档不许升档、也不许把标题副句塞回一句。
+const PAGE_TIER_CONSUMERS = [
+  ["../../domain/tasks/ScheduledTasksSpaceView/index.tsx", /size="page"\s+title="还没有定时任务"/],
+  ["../../domain/skills/McpServerListView/index.tsx", /size="page"\s+title="还没有自定义 MCP"/],
+]
+
+test("A5-B3：整栏空态挂 page 档，标题与副句各占一层", async () => {
+  for (const [rel, expected] of PAGE_TIER_CONSUMERS) {
+    const consumer = await readFile(new URL(rel, import.meta.url), "utf8")
+    assert.match(consumer, expected, rel)
+    // page 档的版心全在档位表里，调用点不得再叠 py-16 / mt-* 这类外挂内距
+    assert.doesNotMatch(consumer, /<EmptyState[\s\S]{0,200}className="[^"]*\bpy-16\b/, rel)
+  }
+})
+
+// 原型里的卡片式空态（1px 边 ＋ radius-lg ＋ surface 底 ＋ 居中一句，无母题无钮）：
+// 它替的是一张列表卡的位置，要占住那块面，不是在空气里摆一枚母题（原型 L1841）。
+test("A5-B3：定时任务详情的运行记录空态走 card 变体", async () => {
+  const consumer = await readFile(
+    new URL("../../domain/tasks/ScheduledTaskDetailView/index.tsx", import.meta.url),
+    "utf8",
+  )
+  assert.match(consumer, /<EmptyState variant="card" message="还没跑过。恢复之后到点会自己开一段会话。" \/>/)
+})

package/src/components/primitives/EmptyState/index.tsx

@@ -0,0 +1,185 @@
+import type { ReactNode } from "react"
+import { cn } from "../../../lib/utils"
+import { Button } from "../Button"
+
+/**
+ * EmptyState — 空态标准形（DS 2.0 原语）
+ *
+ * 规格（COMPONENT-RULES §6 容器空态 + 原型 template.dc.html）：信标 mono 母题
+ * （--ow-empty-mark = text-3 单色，不引荧黄不占极）＋ 可选标题 ＋ 一句 text-2 ＋ 可选动作钮。
+ *
+ * ## 四档一套语法（R4 原型对齐轮，裁决 6）
+ * · `size="page"` 一级：整页/整栏空态，四件齐 —— 母题 52×32 ＋ 16/500 标题 ＋ 14/1.75 副句
+ *   ＋ 一枚 32 高的钮。版心 `margin:56px auto 0; 文字量度 440; gap:14px`（原型定时任务
+ *   L1771-1780、工作台产物 L1963-1972）。
+ * · `size="md"` 二级 inline：区块内 / 搜索无结果 / 预览栏，母题 ＋ 一句（＋轮廓钮）。
+ *   （原型插件目录 L1706-1714、会话 L1407-1412、右栏 L2304-2311）
+ * · `size="sm"` 二级紧凑：弹层里带母题的紧凑档。
+ * · `variant="card"` 卡片式：1px --ow-border ＋ --ow-radius-lg ＋ --ow-surface 底 ＋ 居中一句，
+ *   **无母题无钮**（原型站点访问统计 L2117、站点数据库 L2146、定时任务运行记录 L1841）。
+ * · `variant="text"` 纯文本行：弹层里**一行灰字**，无母题无钮，左对齐
+ *   （原型命令面板 L3018 `padding:16px 10px`、@ 菜单 L923）。
+ * 弹层空间小不是「另造一套灰字空态」的理由——一律走 `variant="text"` 或 `size="sm"`。
+ *
+ * ## 母题几何（R4 改）
+ * 原型用的是六颗圆的**紧裁 bbox** `viewBox="13 11.7 73.4 45.3"`（比例 1.62:1 的横向宽弧），
+ * 六颗圆坐标一字不改，但**不做任何旋转**。此前我们套的是 `viewBox="0 0 96 96"` ＋
+ * `rotate(24 48 48)`：同一组坐标转斜 24° 再塞进方框，四周空白吃掉一半——40×40 的槽位里
+ * 字形只画出 32.9×25.3px（原型 50.3×30.4px），这就是「母题太小」的物理根因。
+ * 裁决 6 允许空态母题单独用横向姿态：§12 锁定件 BeaconSpinner 的 rest 姿态**不动**，
+ * 两者不再是同一个姿势，母题的锁定物是那六颗圆的坐标与半径，不是取景框。
+ *
+ * ## R2 裁决改判（空态钮档位）
+ * R2 记的是「空态不占行动极，一律 secondary」。R4 裁决 6 改判为**同屏行动极记账**：
+ * 行动极的配额按「同一屏是否已有同名主钮」结算，不按「空态」这个身份一刀切。
+ * · 空态是该容器唯一行动入口时（工作台产物、MCP、我的空间）→ `actionVariant="primary"`
+ *   实底，也就是 page 档的默认值；暗档那块荧黄整屏仍只有这一处。
+ * · 同屏页头已有同名主钮时（定时任务的「新建任务」、插件中心的「清空搜索」旁）→ 调用点显式
+ *   传 `actionVariant="secondary"` 降为描边，避免暗档同屏两块荧黄（§4 全屏一处）。
+ * md/sm 两档默认仍是 secondary——二级空态坐在别人的容器里，默认不该抢极。
+ * 禁插画、禁 emoji；CTA 不带图标（图标只留给页头钮）。
+ */
+export type EmptyStateSize = "page" | "sm" | "md"
+
+/**
+ * 形态：`default` 带母题（三档度量由 `size` 决定）；`card` 卡片式一句；`text` 弹层纯文本行。
+ * `card` / `text` 是原型里两种**无母题**的退化形，只渲 `message`——传 title/action 不生效。
+ */
+export type EmptyStateVariant = "default" | "card" | "text"
+
+export interface EmptyStateProps {
+  /**
+   * 名词短句标题，16/500 --ow-text。原型只有 page 档带标题层，二级档（md/sm）按形制不该传；
+   * 但传了就渲——原语不吞调用点给的内容，档位归位是调用侧的事（见 B3 巡检）。
+   */
+  title?: ReactNode
+  /** 一句话说明，text-2；像同事说话：短句、不感叹、无 emoji */
+  message: ReactNode
+  /** 可选动作钮文案；与 onAction 成对出现。档位见 `actionVariant`。 */
+  actionLabel?: string
+  onAction?: () => void
+  /** 自定义动作区（覆盖 actionLabel/onAction），仍应为按钮类元素 */
+  action?: ReactNode
+  /** 内置动作钮的档位；不传时随 size 档（page=primary 实底 · md/sm=secondary 描边）。 */
+  actionVariant?: "primary" | "secondary"
+  /** 尺寸档，默认 `md`；整页/整栏空态用 `page`，弹层内用 `sm` 紧凑档 */
+  size?: EmptyStateSize
+  /** 形态，默认 `default`（带母题）；`card` / `text` 是无母题的两种退化形 */
+  variant?: EmptyStateVariant
+  /** 母题**宽度** px；高按紧裁 bbox 比例（1.62:1）自动算。不传时随 size 档（page=52 · md=40 · sm=28） */
+  markSize?: number
+  className?: string
+}
+
+/** 档位度量表：母题宽 ＋ 容器间距/内距/版心。按钮尺寸与默认档位随档。 */
+const EMPTY_STATE_SIZES = {
+  // A5-B3 修正：原型 page 档的 `max-width:440px` 是**文字量度**（那个容器没有横向内距）。
+  // 我们为窄容器留了 `px-6`，量度就得跟着补上 2×24 —— 写 440 的话可用宽只剩 392，
+  // 原型能一行放下的那句副句（实测墨迹 406px）会折成两行、末尾掉出「知你。」这种孤字。
+  page: { mark: 52, box: "gap-3.5 px-6 mt-14 mx-auto max-w-[488px]", button: "md", action: "primary" },
+  md: { mark: 40, box: "gap-3 px-4 py-8", button: "md", action: "secondary" },
+  sm: { mark: 28, box: "gap-2 px-3 py-4", button: "sm", action: "secondary" },
+} as const
+
+/** 六颗圆的紧裁 bbox（原型 template.dc.html L1772）；坐标锁定，取景框不含任何旋转。 */
+const MARK_VIEW_BOX = "13 11.7 73.4 45.3"
+/** 紧裁 bbox 的高宽比 45.3 / 73.4 —— markSize 给宽，高由它推。 */
+const MARK_RATIO = 45.3 / 73.4
+
+/** 空态信标母题：六点构型紧裁横向姿态（坐标同 BeaconSpinner，勿改），单色 --ow-empty-mark。 */
+function EmptyMark({ size = 52 }: { size?: number }) {
+  return (
+    <svg
+      width={size}
+      height={Math.round(size * MARK_RATIO)}
+      viewBox={MARK_VIEW_BOX}
+      aria-hidden="true"
+      className="ow-empty-icon block mb-4"
+      style={{ color: "var(--ow-empty-mark)" }}
+    >
+      <circle cx="48" cy="48" r="8.2" fill="currentColor" />
+      <circle cx="60.2" cy="20.6" r="6.7" fill="currentColor" opacity=".6" />
+      <circle cx="41.76" cy="18.66" r="5.5" fill="currentColor" opacity=".45" />
+      <circle cx="25.71" cy="27.93" r="4.3" fill="currentColor" opacity=".3" />
+      <circle cx="18.16" cy="44.86" r="3.3" fill="currentColor" opacity=".2" />
+      <circle cx="75.4" cy="35.8" r="10.4" fill="currentColor" />
+    </svg>
+  )
+}
+
+export function EmptyState({
+  title,
+  message,
+  actionLabel,
+  onAction,
+  action,
+  actionVariant,
+  size = "md",
+  variant = "default",
+  markSize,
+  className,
+}: EmptyStateProps) {
+  /* 卡片式：1px 边 ＋ radius-lg ＋ surface 底 ＋ 居中一句，无母题无钮（原型 L1841/2117/2146）。 */
+  if (variant === "card") {
+    return (
+      <div
+        data-slot="empty-state"
+        data-ow-variant="card"
+        role="status"
+        className={cn(
+          "px-4 py-7 text-center [text-wrap:pretty]",
+          "border border-[color:var(--ow-border)] [border-radius:var(--ow-radius-lg)] bg-[var(--ow-surface)]",
+          "text-ow-fs-body leading-normal text-[color:var(--ow-text-2)]",
+          className,
+        )}
+      >
+        {message}
+      </div>
+    )
+  }
+
+  /* 纯文本行：弹层里一行灰字，无母题无钮、左对齐（原型命令面板 L3018 / @ 菜单 L923）。 */
+  if (variant === "text") {
+    return (
+      <div
+        data-slot="empty-state"
+        data-ow-variant="text"
+        role="status"
+        className={cn("px-2.5 py-4 text-ow-fs-ui leading-normal text-[color:var(--ow-text-2)]", className)}
+      >
+        {message}
+      </div>
+    )
+  }
+
+  const metrics = EMPTY_STATE_SIZES[size] ?? EMPTY_STATE_SIZES.md
+  const isPage = size === "page"
+  return (
+    <div
+      data-slot="empty-state"
+      data-ow-size={size}
+      data-ow-variant="default"
+      role="status"
+      className={cn("flex flex-col items-center justify-center text-center", metrics.box, className)}
+    >
+      <EmptyMark size={markSize ?? metrics.mark} />
+      {title ? (
+        <p className="m-0 text-ow-fs-subtitle font-medium leading-[1.4] text-[color:var(--ow-text)]">{title}</p>
+      ) : null}
+      <p
+        className={cn(
+          "m-0 text-[color:var(--ow-text-2)]",
+          isPage ? "text-ow-fs-body leading-[1.75] [text-wrap:pretty]" : "text-ow-fs-ui leading-normal",
+        )}
+      >
+        {message}
+      </p>
+      {action ??
+        (actionLabel && (
+          <Button variant={actionVariant ?? metrics.action} size={metrics.button} onClick={onAction}>
+            {actionLabel}
+          </Button>
+        ))}
+    </div>
+  )
+}

package/src/components/primitives/ErrorCard/ErrorCard.stories.tsx

@@ -0,0 +1,50 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import { ErrorCard } from "./index"
+
+const meta = {
+  title: "Primitives/ErrorCard",
+  component: ErrorCard,
+  parameters: {
+    layout: "centered",
+    docs: {
+      description: {
+        component:
+          '已废弃：DS2 已并入 InlineMessage（variant="error"）。此件仅为薄兼容导出，请迁移到 Primitives/InlineMessage。',
+      },
+    },
+  },
+  tags: ["autodocs"],
+} satisfies Meta<typeof ErrorCard>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: {
+    message: "Something went wrong",
+  },
+}
+
+export const WithDetails: Story = {
+  args: {
+    message: "Failed to load data",
+    detail: "Network request failed: Connection timeout after 30s",
+  },
+}
+
+export const LongMessage: Story = {
+  args: {
+    message: "Authentication Error",
+    detail: "Your session has expired. Please log in again to continue. If the problem persists, contact support.",
+  },
+}
+
+/** W5 终扫：重试钮从手搓 unstyled 换成 Button secondary/sm（28 高、8 圆角、focus 三件套），
+ *  只把边/字/hover 底重着到 error tint 族 token。 */
+export const WithRetry: Story = {
+  args: {
+    message: "Failed to load data",
+    detail: "Network request failed: Connection timeout after 30s",
+    onRetry: () => {},
+  },
+}