Merge branch 'feature/header-system' into develop

Author: pallyoung

docs/superpowers/specs/2026-05-18-header-design-system-spec.md

@@ -0,0 +1,202 @@
+# Header 设计规范
+
+> **版本：** 1.0
+> **日期：** 2026-05-18
+> **状态：** Draft
+> **作者：** Codex
+
+## 0. 目标
+
+统一当前项目的页面 header、列表/面板 header、弹框 header，收敛到固定共享 contract，禁止页面、功能模块、弹层各自再写一套标题区结构和字号规则。
+
+本规范的核心目标只有两个：
+
+- header 结构统一
+- header 排版 token 固定，禁止自定义字号
+
+## 1. 适用范围
+
+本规范适用于普通业务 UI 中承担“标题区 / 顶部信息区”职责的 header：
+
+- 一级页面 header
+- 二级页面 header
+- panel / 列表 / 侧栏 / 卡片上沿 header
+- modal / dialog / sheet 标题区
+
+不纳入本规范的豁免面：
+
+- terminal / code editor / diff / review 等技术面板 header
+- 纯品牌展示型 hero
+- 不承担页面或容器标题职责的普通工具栏
+
+说明：
+
+- 名字里带 `header` 不等于必须纳入本规范。
+- 是否纳入，取决于它是不是“页面或容器的标准标题区”。
+
+## 2. 唯一允许的 Header Contract
+
+业务 UI 只允许使用以下共享 header 入口：
+
+### 2.1 `PageHeader`
+
+用途：
+
+- 一级页面
+- 二级页面
+- 设置页、内容页、详情页的顶部标题区
+
+当前 contract：
+
+- `level="primary"`：页面级主标题
+- `level="secondary"`：二级页 / 常规页标题
+- `onBack` / `backLabel`
+- `kicker`
+- `rightSlot`
+
+排版约束：
+
+- `PageHeader.primary` title 固定使用 `--type-section-title-*`
+- `PageHeader.secondary` title 固定使用 `--type-app-title-*`
+- `PageHeader` kicker 固定使用 `--type-kicker-*`
+- `PageHeader` back 文案固定使用 `--type-label-*`
+
+### 2.2 `MobilePageHeader`
+
+用途：
+
+- 移动端页面 header
+- 全屏 mobile sheet 的标准 header
+
+说明：
+
+- `MobilePageHeader` 是 `PageHeader` 的移动端包装，不是另一套独立排版系统。
+- 它只能调整移动端布局、间距和返回区交互密度，不能自定义 title 字号。
+
+排版约束：
+
+- title 固定使用 `--type-app-title-*`
+- back 文案固定使用 `--type-code-inline-*`
+
+### 2.3 `PanelHeader`
+
+用途：
+
+- 列表区块
+- workspace panel
+- 侧栏 / 卡片 / 面板上沿标题区
+
+当前 contract：
+
+- `title`
+- `status`
+- `meta`
+- `actions`
+
+排版约束：
+
+- title 固定使用 `--type-app-title-*`
+- `status` / `meta` 只能使用共享辅助文案语义，不允许局部重写 panel title 字号
+
+### 2.4 `DialogHeader`
+
+用途：
+
+- modal
+- dialog
+- 标准弹层标题区
+
+说明：
+
+- `DialogHeader` 是弹层 header 的 canonical 入口。
+- `ModalHeader` 仅作为兼容命名，不应继续扩展成新规范分支。
+
+推荐结构：
+
+- `dialog-header__leading`
+- `dialog-header__icon`
+- `dialog-header__copy`
+- `dialog-header__description`
+- `ModalTitle`
+
+排版约束：
+
+- `ModalTitle` / dialog title 固定使用 `--type-section-title-*`
+- `dialog-header__description` 固定使用 `--type-meta-*`
+
+## 3. 允许的差异
+
+允许存在的差异只有以下几类：
+
+- 高度
+- padding / gap / 对齐方式
+- 是否带返回
+- 是否带 kicker
+- 是否带 actions / meta / status
+- icon 样式和状态色
+
+这些差异必须建立在共享 contract 之上实现，不能通过重新发明一套 header DOM 来实现。
+
+## 4. 明确禁止项
+
+以下做法一律不允许：
+
+- 页面自己新写 `xxx-header` DOM 结构来替代 `PageHeader`
+- modal / dialog 自己拼一套标题区而不走 `DialogHeader`
+- panel 自己写标题区而不走 `PanelHeader`
+- 在页面包装层覆盖 `.page-header__title` / `.panel-header__title` / `.modal-title` 字号
+- 在场景样式里新增 header 专属 `font-size` / `line-height` / `font-weight` override
+- header 继续直接使用裸写 `px`
+- header 继续直接使用旧 `--text-*` 尺度 token
+
+一句话规则：
+
+- 页面可以改 header 的布局，不可以改 header 的排版语义。
+
+## 5. Token 使用规则
+
+header 只允许消费 `--type-*` 语义排版 token，不允许直接消费基础字号 token。
+
+当前批准映射如下：
+
+- `PageHeader.primary` -> `--type-section-title-*`
+- `PageHeader.secondary` -> `--type-app-title-*`
+- `MobilePageHeader.title` -> `--type-app-title-*`
+- `MobilePageHeader.back` -> `--type-code-inline-*`
+- `PanelHeader.title` -> `--type-app-title-*`
+- `DialogHeader.title` -> `--type-section-title-*`
+- `DialogHeader.description` -> `--type-meta-*`
+
+如果未来要调整 header 的视觉层级，只能修改这份映射和共享实现，不能在业务页面就地逃逸。
+
+## 6. 落地原则
+
+后续新增页面或重构旧页面时，按下面规则执行：
+
+1. 先判断这是页面 header、panel header 还是 dialog header。
+2. 直接复用共享组件。
+3. 如果现有 props 不够，优先扩展共享组件 contract。
+4. 只有在确认不属于标准标题区时，才允许不用这套 header contract。
+
+评审口径：
+
+- 看到自定义 header DOM，默认视为问题
+- 看到 header 自定义字号，默认视为问题
+- 看到 header 使用 `--text-*` 或裸 `px`，默认视为问题
+
+## 7. 当前仓库结论
+
+截至 2026-05-18，这套规范在当前代码中的主路径已经收敛为：
+
+- `PageHeader`
+- `MobilePageHeader`
+- `PanelHeader`
+- `DialogHeader`
+
+同时已确认：
+
+- settings 桌面 header 已回收为共享 `PageHeader`
+- dialog description 已回收为 `dialog-header__description`
+- header 主路径已与 `develop` 上新的 semantic typography token 对齐
+
+后续如果再出现 header 自定义字号，应视为违反规范而不是可接受的局部例外。

packages/web/src/components/ui/index.ts

@@ -23,7 +23,7 @@ export { Input } from "./input";
 export type { KbdProps } from "./kbd";
 export { Kbd } from "./kbd";
 export type { ModalProps, ModalSize } from "./modal";
-export { Modal, ModalBody, ModalFooter, ModalHeader, ModalTitle } from "./modal";
+export { DialogHeader, Modal, ModalBody, ModalFooter, ModalHeader, ModalTitle } from "./modal";
 export type { NoticeProps, NoticeTone } from "./notice";
 export { Notice } from "./notice";
 export type { PillProps } from "./pill";

packages/web/src/components/ui/modal/README.md

@@ -5,9 +5,9 @@
 
 ```tsx
 <Modal open onOpenChange={setOpen}>
-  <ModalHeader>
+  <DialogHeader>
     <ModalTitle>Workspace details</ModalTitle>
-  </ModalHeader>
+  </DialogHeader>
   <ModalBody>Body</ModalBody>
   <ModalFooter>Footer</ModalFooter>
 </Modal>
@@ -26,4 +26,6 @@
 ## 注意
 - 组件通过 portal 渲染到 `document.body`。
 - 打开后会把焦点移入弹窗，关闭后恢复到先前焦点。
+- `DialogHeader` 是弹层 header 的 canonical 入口；`ModalHeader` 保留为兼容命名。
+- 如需标准化 icon / copy / description 结构，使用 `dialog-header__leading`、`dialog-header__icon`、`dialog-header__copy`、`dialog-header__description`。
 - 迁移期仍保留 `modal-overlay`、`modal-card`、`modal-header`、`modal-title`、`modal-body`、`modal-footer` 等兼容类名。

packages/web/src/components/ui/modal/index.module.css

@@ -53,6 +53,47 @@
   border-bottom: 1px solid var(--border);
 }
 
+.dialogHeader,
+:global(.dialog-header) {
+  align-items: flex-start;
+}
+
+:global(.dialog-header__leading) {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--sp-3);
+  min-width: 0;
+  flex: 1;
+}
+
+:global(.dialog-header__copy) {
+  display: flex;
+  min-width: 0;
+  flex: 1;
+  flex-direction: column;
+  gap: 2px;
+}
+
+:global(.dialog-header__icon) {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  height: 28px;
+  border-radius: var(--radius-md);
+  flex-shrink: 0;
+  background: var(--bg-hover);
+  color: var(--text-secondary);
+}
+
+:global(.dialog-header__description) {
+  margin: 0;
+  font-size: var(--type-meta-size);
+  line-height: var(--type-meta-line-height);
+  font-weight: var(--type-meta-weight);
+  color: var(--text-tertiary);
+}
+
 .title,
 :global(.modal-title) {
   display: flex;
@@ -111,6 +152,8 @@
 
   .header,
   :global(.modal-header),
+  .dialogHeader,
+  :global(.dialog-header),
   .body,
   :global(.modal-body),
   .footer,

packages/web/src/components/ui/modal/index.test.tsx

@@ -2,7 +2,7 @@ import { render, screen, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { createRef } from "react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { Modal, ModalBody, ModalFooter, ModalHeader, ModalTitle } from ".";
+import { DialogHeader, Modal, ModalBody, ModalFooter, ModalHeader, ModalTitle } from ".";
 
 const activeElementState = {
   current: null as HTMLElement | null,
@@ -78,6 +78,20 @@ describe("Modal", () => {
     expect(document.body).toContainElement(dialog);
   });
 
+  it("exports DialogHeader as the canonical modal header alias", () => {
+    render(
+      <DialogHeader>
+        <ModalTitle>Workspace details</ModalTitle>
+      </DialogHeader>
+    );
+
+    const header = document.querySelector(".dialog-header");
+
+    expect(header).not.toBeNull();
+    expect(header).toHaveClass("modal-header");
+    expect(screen.getByText("Workspace details")).toBeInTheDocument();
+  });
+
   it("applies the large card variant for size='lg'", () => {
     render(<ModalFixture size="lg" />);
 

packages/web/src/components/ui/modal/index.tsx

@@ -134,6 +134,21 @@ export function ModalHeader({ className, ...props }: HTMLAttributes<HTMLDivEleme
   return <div {...props} className={clsx(styles.header, "modal-header", className)} />;
 }
 
+export function DialogHeader({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      {...props}
+      className={clsx(
+        styles.header,
+        styles.dialogHeader,
+        "modal-header",
+        "dialog-header",
+        className
+      )}
+    />
+  );
+}
+
 export function ModalTitle({ className, ...props }: HTMLAttributes<HTMLHeadingElement>) {
   const context = useContext(ModalContext);
   const fallbackId = useId();

packages/web/src/features/agent-panes/components/session-card.test.tsx

@@ -279,15 +279,20 @@ describe("SessionCard", () => {
       </Provider>
     );
 
-    const header = screen.getByText("SESSION-56").closest(".session-header");
+    const bespokeHeader = screen.getByText("SESSION-56").closest(".session-header");
+    const header = screen.getByText("SESSION-56").closest(".panel-header");
+    const actions = header?.querySelector(".panel-header__actions");
     const accessory = screen.getByRole("button", { name: "Supervisor entry" });
     const right = header?.querySelector(".session-header-right");
 
+    expect(bespokeHeader).toBeNull();
     expect(header).not.toBeNull();
+    expect(actions).not.toBeNull();
     expect(accessory.parentElement).toHaveClass("session-header-accessory");
     expect(right).not.toBeNull();
     expect(right).toContainElement(accessory);
-    expect(header?.lastElementChild).toBe(right);
+    expect(actions).toContainElement(right as HTMLElement);
+    expect(header?.lastElementChild).toBe(actions);
   });
 
   it("forces the terminal read-only when terminalReadOnlyOverride is true", () => {