AirShelf/电商AI平台/design.md

# 流·Studio 设计规范 · design.md

> **唯一权威 source of truth** · 所有页面调整必须遵循本文件。
> **代号:** Restraint(克制)· V2.1 · Firecrawl-aligned
> **维护日期:** 2026-05-22
> **配套实现:** [assets/restraint.css](assets/restraint.css) (token + 100+ 组件类 · 1592 行)
> **可视样板间(归档):** [_archive/design-system.html](_archive/design-system.html)
> **历史规范(归档):** [_archive/DESIGN_SPEC_V2.md](_archive/DESIGN_SPEC_V2.md)

---

## §0 · AI 协作铁律(每次启动必读)

**Claude / 任何 AI 在做页面或 CSS 调整前,必须执行以下流程:**

1. **先 Read 本文件** · 至少读 §1 设计哲学 + §3 组件清单 + §8 Don't List
2. **检查 restraint.css 是否已有该组件** · 用 `Grep "\.btn|\.pill|\.input" assets/restraint.css` 查现成类名
3. **禁止在页面 inline `<style>` 重写 restraint.css 已有的共享类**(`.btn` `.pill` `.input` `.modal` `.drawer` `.toast` `.field` `.tabs` `.chip` 等)— 要变体先回 restraint.css 加
4. **禁止创建新色值** · 颜色必须用 §2.1 的 token,不能写裸 hex
5. **禁止动 token 数值** · 不要改 `--heat` `--background-base` `--border-faint` 等基础变量,改了破坏全站
6. **完成后对照 §8 Don't List 自检**
7. **不确定就问用户**,而不是凭感觉发挥

**违反任何一条,用户有权要求重做。**

---

## §1 · 设计哲学

**一句话:** 一台精密设备的工作面板。

**三条铁律:**
1. **克制大于装饰** · 留白 > 容器 > 内容,大量空气感
2. **单色锚点** · 全场只有一个 accent(橙),只用于 CTA / 关键状态 / 强调单词
3. **结构清晰可见** · 用 1 px 边框 + 8 px 圆角 + 准星 + 装订线 + mono 标签暴露"图纸感",而非阴影/渐变隐藏结构

**避免的 "AI 味":** 渐变铺面 / 玻璃拟态 / 彩色阴影 / emoji 图标 / 圆角无差别 / 卡片"贴纸感" / 装饰盖过内容。

**核心签名(4 个不能丢):**
- 主橙 `#fa5d19`(Firecrawl 实测)+ 单 hue alpha 阶梯
- 全场 8 px 圆角(Pill 999 例外)
- 主容器左右装订线 + 四角准星
- Mono 装饰 `[ 200 OK ]` `// 05.14` `[ /v2 ]`(品牌签名 · Firecrawl 没有)

---

## §2 · 全局 Token

### §2.1 色彩 · 你 90% 时间用这 14 个

| Token | Hex / Value | 用途 |
| ----- | ----------- | ---- |
| `--background-base` | `#f9f9f9` | 页面底色 · 冷灰无色相 |
| `--background-lighter` | `#fbfbfb` | 容器底 / hover 浅底(部分场景) |
| `--surface` | `#ffffff` | 卡片 / 主容器表面 |
| `--surface-raised` | `#ffffff` | Modal / 浮层 |
| `--border-faint` | `#ededed` | **默认 1 px 边框 ★ 80% 场景** |
| `--border-muted` | `#e8e8e8` | 略深(主分隔线) |
| `--border-loud` | `#e6e6e6` | 最深(强分隔) |
| `--accent-black` | `#262626` | **主前景色 · 文字** |
| `--heat` | `#fa5d19` | **主橙 100% · CTA / 链接 ★** |
| `--heat-12` | `rgba(250,93,25,.12)` | tint 底 · active nav / icon-box |
| `--heat-20` | `rgba(250,93,25,.20)` | pill 边框 / selection 底色 |
| `--heat-40` | `rgba(250,93,25,.40)` | focus ring / disabled CTA |
| `--accent-forest` | `#42c366` | 绿 · success / 已完成 |
| `--accent-crimson` | `#eb3424` | 红 · error / 失败 |
| `--accent-honey` | `#ecb730` | 黄 · warning |

### §2.2 Black-Alpha 阶梯(20 档 · 核心工具尺)

> **规则:** 0–24% 用 `rgba(0,0,0,...)`;32% 起换 `rgba(38,38,38,...)`(避免叠出"灰中带蓝")。

最常用 8 档:

| Token | 用途 |
| ----- | ---- |
| `--black-alpha-4` | **hover 底色 ★** |
| `--black-alpha-7` | **active 底色 ★** |
| `--black-alpha-12` | **inside-border / disabled fg ★** |
| `--black-alpha-24` | input hover 边框 |
| `--black-alpha-48` | **占位字色 ★** |
| `--black-alpha-56` | **次级文字 / 未选中 Tab ★** |
| `--black-alpha-64` | 描述文字 |
| `--black-alpha-88` | 近主前景 |

完整 20 档清单见 [assets/restraint.css](assets/restraint.css) §root。

### §2.3 状态色配套(底 / 边)

| 含义 | 主色 | 配套底色 8% | 配套边框 20% |
| ---- | ---- | ----------- | ------------ |
| 成功 | `--accent-forest` `#42c366` | `--forest-bg` | `--forest-bd` |
| 失败 | `--accent-crimson` `#eb3424` | `--crimson-bg` | `--crimson-bd` |
| 信息 | `--heat` `#fa5d19` | `--heat-12` | `--heat-20` |
| 警告 | `--accent-honey` `#ecb730` | `--honey-bg` | `--honey-bd` |

### §2.4 Selection · Firecrawl 签名细节

```css
::selection { background: var(--heat-20); color: var(--heat); }
```

任何文字选中时,底色 20% 橙 + 文字 100% 橙。已全局生效 · 不要覆盖。

### §2.5 字体族 · 中英协作

| 用途 | 字体声明 | 加载方式 |
| ---- | -------- | -------- |
| 正文 / UI · `--font-sans` | `'Inter', 'Alibaba PuHuiTi', 'PingFang SC', 'Microsoft YaHei', system-ui, sans-serif` | Inter Google Fonts + 普惠体 CDN |
| 强制纯英 · `--font-inter` | `'Inter', system-ui, sans-serif` | 用于 Ctrl K 等英文徽标 |
| Mono 装饰 · `--font-mono` | `'JetBrains Mono', 'Geist Mono', ui-monospace, 'Alibaba PuHuiTi', 'PingFang SC', 'Microsoft YaHei', monospace` | JetBrains Google Fonts |

**字符级 fallthrough 原理:** 浏览器对每个字符逐个查找,Inter 不含 CJK → 中文自动跳到普惠体。**不需要 JS,不会字重错位。**

**字重档位仅 3 档:** `400 / 500 / 600`。700 仅用于 `Ctrl K` 这种纯英文徽标。

### §2.6 字号 / 字重 / 行高(11 档)

| 角色 | 字号 | 字重 | 字距 | 行高 | 用途 |
| ---- | ---- | ---- | ---- | ---- | ---- |
| H1 / Hero | 36 px | 500 | -0.024em | 1.2 | 页面主标题 |
| 区块 H2 | 28 px | 500 | -0.02em | 1.25 | section-head |
| KPI 数值 | 32 px | 500 | -0.02em | 1.1 | 统计大数(`tabular-nums`) |
| 子区 H3 | 16 px | 500 | -0.01em | 1.4 | subsection |
| 卡片标题 | 14 px | 500 | normal | 1.4 | 项目名 / 商品名 |
| 正文 body | 14 px | 400 | normal | **1.65** | 默认正文 |
| 描述次级 | 13 px | 400 | normal | 1.8 | 子区说明 |
| Label / Tab | 13 px | 500 | normal | 1.4 | 按钮文字 / Tab |
| Pill | 11.5 px | 500 | normal | 1.3 | 状态徽标 |
| Inter Bold 徽标 | 11.5 px | 700 | 0.02em | 1 | Ctrl K / ESC(`--font-inter`) |
| Mono 标签 | 11 px | 400 | 0.04em | 1.5 | `[ STATUS ]` `// 注释` |
| Mono 散点 | 8.5 px | 400 | 0.04em | 1 | 背景 ASCII 装饰 |

**数值类必加** `font-variant-numeric: tabular-nums`(或加 `.num` 工具类)。
**正文中文行高 1.65–1.8**(给中文留呼吸)。

### §2.7 圆角

| 元素 | 值 | Token |
| ---- | -- | ----- |
| 所有结构性容器 / 按钮 / 输入框 / 缩略图 | **8 px** | `--r-md` |
| 头像 / 小色块 | 6 px | — |
| Mono 标签 / kbd / badge | 4 px | `--r-sm` |
| 进度条段位 | 2 px | — |
| Pill / dot | 999 px | `--r-pill` |

**默认是 8 px。** 不确定就选 8。`>12 px` 直接判错。

### §2.8 间距(全站统一)

**基础栅格:** 4 px。
**阶梯:** `4 / 8 / 12 / 16 / 20 / 24 / 28 / 32 / 40 / 48 / 64 / 72 / 80 / 104`。

| 场景 | 值 |
| ---- | -- |
| Sidebar 宽度 | `248 px` |
| Topbar 高度 | `64 px` |
| Content padding | `48 28 72` |
| 卡片内 padding(大) | `28 30` / `24 28` |
| 卡片内 padding(列表行) | `14 18` ~ `20 24` |
| KPI cell padding | `24 28` |
| 主区块间(section margin) | `36–48 px`(子)/ `64–104 px`(主) |
| 子区标题底距 | `mb 14`(h2)/ `mb 22-28`(h1) |
| 卡片网格 gap | `14`(子区)/ `24`(主区) |
| Modal padding | `head 24 28 / body 24 28 / foot 18 28` |

**最重要的一条:** 别再吝啬空气。**当不确定 padding 是 16 还是 24 时,选 24。** 当不确定 margin 是 48 还是 64 时,选 64。

### §2.9 阴影(只 3 个允许场景)

| 场景 | 阴影 |
| ---- | ---- |
| 主 CTA(`.btn-primary`) | 4 层橙色阴影 `--shadow-cta` |
| 主 CTA hover | 阴影抬升 `--shadow-cta-hover` |
| Toast / Dropdown 浮层 | 白色 `0 4px 20px rgba(21,20,15,.06)` = `--shadow-floating` |

**禁:** 灰色阴影 / 文字阴影 / 通用 box-shadow。

### §2.10 边框策略 · inside-border

默认边框用 `::before` 伪元素绘制(而非真 `border`),hover 时让 `::before` 透明度 → 0,不触发布局抖动。

```css
.inside-border { position: relative; }
.inside-border::before {
  content: ''; position: absolute; inset: 0;
  border: 1px solid var(--black-alpha-12);
  border-radius: inherit;
  pointer-events: none;
  transition: opacity .2s, border-color .2s;
}
.inside-border:hover::before { opacity: 0; }
```

**禁:** 2 px / 3 px 实线 / 真 `border` + hover 边框消失。
**例外:** `.tip` 提示框允许 `1 px dashed`。

---

## §3 · 页面骨架(全站统一)

```
┌──────────────────────────────────────────────┐
│  <div class="app">                           │
│  ┌────────┬──────────────────────────────┐   │
│  │        │  <div class="topbar">        │   │
│  │ aside  │    crumbs · right(chips)     │   │
│  │ side   │  </div>                      │   │
│  │ bar    │  ┌────────────────────────┐  │   │
│  │ 248px  │  │ <div class="content">  │  │   │
│  │        │  │   <div class="page-head"> │   │
│  │        │  │   <div class="section-h"> │   │
│  │        │  │   ...                  │  │   │
│  │        │  │ </div>                 │  │   │
│  │        │  └────────────────────────┘  │   │
│  └────────┴──────────────────────────────┘   │
│  </div>                                      │
└──────────────────────────────────────────────┘
```

### §3.1 入口约束

每个新页面 `<head>`:
```html
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
<link rel="stylesheet" href="assets/restraint.css">
```

每个新页面 `<body>` 末尾:
```html
<script src="assets/shell.js" defer></script>
```

`shell.js` 自动注入 sidebar + topbar,**页面只写 `<main>` 内的 `.content` 内容**。

### §3.2 标题区(必有)

```html
<div class="page-head">
  <div>
    <h1>商品库</h1>
    <div class="sub">
      <span class="mono">// 12 个商品</span> · 你的所有商品和卖点
    </div>
  </div>
  <div class="actions">
    <button class="btn">导入</button>
    <button class="btn btn-primary">+ 新建商品</button>
  </div>
</div>
```

**page-head 内主操作按钮强制 40 px 高**(`.page-head .actions > .btn { height: 40px }` 已全局覆盖)。

### §3.3 子区块(可选)

```html
<div class="section-h">
  <h2>最近项目</h2>
  <a class="more">[ ALL · 12 ] →</a>
</div>
<!-- 内容 -->
```

`.more` mono 11.5 / `--black-alpha-48` / hover 转橙。

### §3.4 主容器装订线(签名元素 · 主工作台型必有)

工作台 / 项目列表 / 商品库 / 流水线主区:左右两条 1 px 边线 + 4 角圆弧内凹 SVG 准星。Modal / 编辑器全屏画布不必加。

```css
.workbench-container {
  max-width: 1480px;
  margin: 0 auto;
  border-left: 1px solid var(--border-faint);
  border-right: 1px solid var(--border-faint);
  position: relative;
}
/* 4 角 SVG · 用 .with-corners + .corner-tr/.corner-bl */
```

---

## §4 · 组件清单(restraint.css 已实现 · 不要重发明)

### §4.1 按钮族 · 三级体系(按功能重要性区分)

> **核心原则:** 按钮的视觉强度 = 操作的重要程度。一个区域**只能有一个**一级按钮(像航海图上只能有一个北极星)。视觉等级混乱比按钮不好看更致命。

#### 三级体系

| 等级 | 类名 | 视觉 | 语义 | 数量约束 |
| ---- | ---- | ---- | ---- | -------- |
| **一级 · Primary** | `.btn .btn-primary` | 橙底 + 4 层橙阴影 + 字重 600 | **页面/弹窗的最重要动作** · 用户主动作 | **一个区域只能有一个** ★ |
| **二级 · Secondary** | `.btn` 默认 | 白底 + inside-border + 主前景字 | 跟主操作**并列**的重要动作 | 可以有多个 |
| **三级 · Tertiary** | `.btn .btn-ghost` | 透明底 + 无框 + alpha-56 字 | **辅助/链接式**的弱化操作 | 不限 |

#### 选谁?决策表

| 操作类型 | 等级 | 例子 |
| -------- | ---- | ---- |
| 提交 / 确认 / 创建 / 下一步 / 保存 / 生成 | **一级** | "创建商品" "确认删除" "开始生成" |
| 取消 / 重置 / 导出 / 导入 / 上一步 / 关闭 | **二级** | "取消" "重置" "导出 CSV" |
| 跳过 / 了解更多 / 查看详情 / 折叠 / 链接式 | **三级** | "跳过" "了解更多 →" "[查看] [编辑] [删除]" 行内动作 |
| 破坏性(删除/危险) | **二级**(在 modal 里)或**一级**(确认按钮) | modal 里:取消[二级] + 确认删除[一级] |

#### 典型组合

| 场景 | 组合 |
| ---- | ---- |
| `.page-head .actions`(页面标题区) | [二级] + [一级] · 例:[导入] [+ 新建商品] |
| `.modal-f`(弹窗底栏) | [二级取消] + [一级确认] · 永远主操作在右 |
| 卡片行内操作 | [三级] × N · 例:[查看] [编辑] [删除] |
| 表单底部 | [三级上一步] + spacer + [二级保存草稿] + [一级提交] |
| 空状态 CTA | [一级] · 唯一一个 |

#### 尺寸阶梯(独立于等级,按上下文密度选)

| 类名 | 高度 | padding | 字号 | 用法 |
| ---- | ---- | ------- | ---- | ---- |
| `.btn-sm` | 28 px | `0 12` | 12 | 行内 / 列表行末 / 表格内 / 紧凑工具栏 |
| 默认 | 36 px | `0 16` | 13 | **标准 ★** · 通用场景 |
| `.btn-lg` | 40 px | `0 20` | 13.5 | hero CTA / page-head 主操作(已全局覆盖) |
| `.icon-btn` 方形 | 36×36 | — | — | 纯 icon(无文字时) |

> **等级 × 尺寸** 可自由组合 — 一级可以是 sm/默认/lg,二级三级同理。

#### 5 种状态

| 状态 | 一级表现 | 二级表现 | 三级表现 |
| ---- | -------- | -------- | -------- |
| Default | 橙底 + 4 层橙阴影 | 白底 + inside-border `--black-alpha-12` | 透明 + 字 `--black-alpha-56` |
| Hover | 阴影抬升(第 3 层加亮) | 底 `--black-alpha-4` + 边 `--black-alpha-24` | 底 `--black-alpha-4` + 字转 `--accent-black` |
| Active(按下) | `scale(.995)` + 阴影 inset 加深 | 底 `--black-alpha-7` + `scale(.99)` | 底 `--black-alpha-7` |
| Focused | 2 px `--heat-40` ring · offset 2 | 同左 | 同左 |
| Disabled | 底 `--heat-40` + 字 `#fff` + 阴影消失 + `not-allowed` | 底 `--black-alpha-5` + 字 `--black-alpha-32` + 边 `--black-alpha-12` | 字 `--black-alpha-32` |

**所有按钮过渡:** `background 200ms, transform 100ms ease`。

#### 常见错误

- ❌ **一个区域两个一级按钮** — 用户视线分散 → 改为 [二级] + [一级]
- ❌ **危险操作用一级橙色** — 改为放在 modal 里二次确认,modal 内的"确认删除"用一级
- ❌ **重要操作用三级 ghost** — 弱化了主流程,改用一级或二级
- ❌ **三级按钮加边框** — 三级就是 ghost,加边框就变二级了
- ❌ **页面 inline 调高度/字号** — 用 `.btn-sm` / `.btn-lg`,不要 inline 改

### §4.2 Pill(状态徽标 · 严格 3 级分层)

> **同级别尺寸必须完全一致。** 不允许混用。

| 级别 | 类名 | 高度 | padding | 字号 | dot | 用途 |
| ---- | ---- | ---- | ------- | ---- | --- | ---- |
| L1 大胶囊 | `.pill-l1` | 28 px | `0 12` | 13 | 8 px | 项目状态 / 列表行主标签 |
| **L2 中胶囊 ★ 默认** | `.pill-l2`(或不写) | 22 px | `0 10` | 11.5 | 6 px | 卡片内 / 表格内默认 |
| L3 小胶囊 | `.pill-l3` | 18 px | `0 8` | 10.5 | 5 px | KPI 角标 / 行内 mono 标签 |

**4 种色调:**

| 类名 | 文字色 | 底色 | 边框 | 含义 |
| ---- | ------ | ---- | ---- | ---- |
| `.pill.info` | `--heat` | `--heat-12` | `--heat-20` | 信息 / 进行中 / 默认强调 |
| `.pill.ok` | `--accent-forest` | `--forest-bg` | `--forest-bd` | 成功 / 已完成 |
| `.pill.err` | `--accent-crimson` | `--crimson-bg` | `--crimson-bd` | 失败 / 错误 |
| `.pill.neutral` | `--black-alpha-56` | `--black-alpha-4` | `--border-faint` | 中性 / 已归档 |

```html
<span class="pill pill-l2 pill-info"><span class="dot"></span>生成中</span>
```

每个 pill 前置 `<span class="dot"></span>`,色继承 `currentColor`。

### §4.3 输入族

| 类名 | 高度 | 用法 |
| ---- | ---- | ---- |
| `.input` | 36 px | 单行文本框 |
| `.textarea` | 自动 | 多行 · min 88 px / line-height 1.6 / resize vertical |
| `.select` | 36 px | 下拉 · 带 chevron 背景图 |
| `.field` | flex col / gap 6 | 包 label + input + hint 的容器 |
| `.field-label` | 13 / 500 | 字段标签(必填用 `<span class="req">*</span>`) |
| `.field-hint` | 12 / `--black-alpha-48` | 字段提示 |
| `.search-box`(sidebar) | 36 px | 顶部全局搜索 + Ctrl K |
| `.toolbar .search-inline` | 36 px | 列表页工具栏内嵌搜索(左侧 icon 必加 `z-index: 2`) |

**5 种状态:**

| 状态 | 边框 | 底色 |
| ---- | ---- | ---- |
| Default | `--black-alpha-12` | `--surface` |
| Hover | `--black-alpha-24` | `--surface` |
| Focus | `--heat-40` + `inset 0 0 0 1px --heat-40` | `--surface` |
| Error | `--accent-crimson` | `--crimson-bg` |
| Disabled | `--black-alpha-12` | `--black-alpha-5` + 字 `--black-alpha-32` |

**占位字色:** `--black-alpha-48`,disabled 占位 `--black-alpha-24`。

**带 Ctrl K 搜索框关键坑:**
1. 左侧 icon 必须 `z-index: 2`(否则被 input 白底盖住)
2. 用 "Ctrl K" 纯文本,**不要用 `⌘` 字符**(JetBrains Mono 不带该字形,显示成方框)
3. 快捷键提示不要 kbd 边框,**纯灰色 mono 平铺**(克制)
4. 字体用 `var(--font-inter) / 700`(Inter Bold 紧凑感)

### §4.4 表单控件(Checkbox / Radio / Switch)

**通用原则:** 全部用真 SVG indicator(via background-image data URI 或 inline `<svg>`),**禁止用 border-width / transform: rotate(45deg) 凑对勾**。

| 控件 | 容器尺寸 | Checked 表现 |
| ---- | -------- | ------------ |
| Checkbox `.ck` | 16×16 / 4 px 圆角 / 边 `--black-alpha-24` | `--heat` 底 + 12×12 白 SVG checkmark |
| Indeterminate | 同上 | `--heat` 底 + 12×12 白 SVG 横线 |
| Radio `.rd` | 16×16 圆 / 边 `--black-alpha-24` | 8×8 `--heat` 实心圆(`::after` 即可) |
| Switch `.sw` | 28×16 / 999 圆角 | On: `--heat` 底,圆球右移 `left: 14px` |

Disabled: 底 `--black-alpha-5` + 边 `--black-alpha-12` + 半透明。

### §4.5 KPI 统计行(`.stats`)

```html
<div class="stats with-corners">
  <div class="stat">
    <div class="lbl">本月营收 <span class="pill pill-l3 pill-ok"><span class="dot"></span>+33%</span></div>
    <div class="v">¥327<small>.40 K</small></div>
    <div class="delta up">↑ 较上月 +33%</div>
  </div>
  <!-- ×4 -->
</div>
```

- 1 行 4 格 grid,共用一个 inside-border 容器,圆角 8 px,**无 gap**
- 列与列之间用 `border-right: 1px solid var(--border-faint)`(最后一列去掉)
- 容器四角加 SVG "+" 准星(`.with-corners`)
- 每格结构:label + L3 pill → 大数字(32 px) → delta / mini progress

### §4.6 进度条(5 段流水线)

```html
<div class="prog">
  <span class="done"></span><span class="done"></span>
  <span class="cur"></span><!-- 或 .now -->
  <span></span><span></span>
</div>
```

每段 18×5 px / 3 px 间距 / 2 px 圆角。

| 状态 | 颜色 | 动画 |
| ---- | ---- | ---- |
| 未开始 | `--black-alpha-8` | 静态 |
| 已完成 `.done` | `--accent-forest` | 静态 |
| 进行中 `.cur` 或 `.now` | `--heat` | **1.4s 脉动** opacity 1↔0.55 + scaleY 1↔0.7 |
| 失败 `.fail` / `.err` | `--accent-crimson` | 静态 |

**核心:** 动 = 在运行,静 = 完成/失败。脉动只给"进行中"。

### §4.7 列表行(`.list-row`)

```
[缩略图 56×72] [标题 + meta] [.prog 5 段] [.pill L2] [.btn-sm]
```

- grid: `56px 1fr auto auto auto` / gap 22
- padding: `20 24`
- 行间 1 px 分隔(`--border-faint`),最后行去
- Hover: `--black-alpha-4` 底色

### §4.8 Tabs(主 / 副)

**主 Tab(下划线激活):**
- 高 36 px / padding `0 14` / 字号 13 / 字重 500
- 未选中: `--black-alpha-56`
- 选中: `--accent-black` + bottom 2 px `--heat` 横线
- Hover(未选中): `--black-alpha-4` 底

**副 Tab(过滤型):**
- 高 28 px / padding `0 10` / 字号 12
- 未选中: `--black-alpha-56` + 灰度 icon
- 选中: `--accent-black` + 彩色 icon
- Tab 之间用 1 px 高 12 的 `--ink-alpha-7` 竖条分隔

### §4.9 Chip 筛选(下拉)

```html
<div class="chip-wrap">
  <button class="chip"><span>商品品类</span><svg class="caret"></svg></button>
  <div class="chip-menu"><!-- .mi 选项 · 多选含 .mi-check --></div>
</div>
```

- `.chip` 高 36 / padding `0 14` / 字号 13 / 圆角 8
- Active: 边 `--heat-40` + 字 `--heat` + 底 `--heat-12`
- 打开后菜单 `.chip-wrap.open .chip-menu { display: block }`
- 选项 `.mi` 高 32 / hover `--black-alpha-4` / selected `--heat-12` + 右侧 `--heat` 勾

### §4.10 卡片 / 快捷入口

| 类名 | 描述 |
| ---- | ---- |
| `.card-hard` | 通用硬卡 · 白底 + inside-border + 8 px 圆角 |
| `.card-hard.with-corners` | 加四角 SVG 准星 |
| `.shortcut` | 快捷入口 · 左 32×32 橙 icon-box + 右标题 + mono 描述 |
| `.tip` | 提示框 · **1 px dashed** 边框 + 加粗标题 + 正文 |
| `.placeholder` | 缩略图占位 · 灰底网纹 · 内置 `.ph-frame` 显示 `9:16` |
| `.product-card / .proj-card / .asset-card` | 各类卡片(模板见现有页面) |

`.icon-box`:32×32 / 8 px 圆角 / `--heat-12` 底 / 16 px line icon(`--heat`)。

### §4.11 浮层 / 反馈

| 组件 | 类名 | 关键参数 |
| ---- | ---- | -------- |
| Modal | `.modal-bg > .modal > .modal-h/b/f` | 居中 460-480 px · 4 角 SVG 准星 · `rgba(21,20,15,.42)` 遮罩 + `backdrop-filter: blur(8px)` · 进入 `scale(.96→1)` / 250ms 弹性 · ESC / 点击遮罩关闭 |
| Drawer | `.drawer-bg > .drawer > .drawer-h/b/f` | 右侧抽屉 · 默认 540 px(商品 drawer 820 px) · 进入 `translateX(100%→0)` / 250 ms |
| Toast | `.toast`(`.show` 触发) | 右下 24 px / 白底 inside-border + `--shadow-floating` / 进入 `translateX(420→0)` 300ms 弹性 / 自动 2400 ms 消失 / 内含 24×24 橙 icon-box + 标题 + mono 副文 |
| Empty | `.empty-state.show` | 虚线边框 + 灰 icon + 标题(14/600)+ mono 描述 |
| 缺图徽标 | `.tri-missing-badge` + `.tri-missing-pop` | 商品/人物卡缩图左上角橙底告警徽标 + hover 暗色 tooltip |
| 卡片删除 | `.card-del-btn` | 卡片右上角 hover 显示 · 32×32 / 红 hover |
| 批量栏 | `.bulk-bar` | 选中后吸底浮动操作栏 |
| 卡片勾选 | `.card-check` | 卡片左上角 22×22 圆形 checkbox(编辑模式 hover 显示) |
| Spinner | `.spinner` | 18×18 旋转 · 2 px 橙边 |

### §4.12 Icon 系统

**通用规则:**
- 一律 **SVG inline**,禁止 `<img>` 引图标
- 库:Lucide 或 Phosphor Regular
- `stroke-width: 1.5` / `stroke-linecap: round` / `stroke-linejoin: round` / `fill: none`
- 颜色:`stroke="currentColor"` 继承
- **禁:** 彩色 emoji / filled icon

**5 档尺寸:**

| 档 | 尺寸 | 用途 |
| -- | ---- | ---- |
| S | 14 px | 内嵌 inline 文字旁 |
| **M ★ 默认** | 16 px | 按钮内 / Tab / list 行 |
| L | 20 px | 顶栏 / 快捷入口 / dropdown 触发器 |
| XL | 24 px | Modal 头 / Toast / 空状态 |
| Hero | 36 px | 空状态插画 / 大占位 |

**颜色:** 默认 `--black-alpha-56` / hover `--accent-black` / active `--heat` / disabled `--black-alpha-12` / 在主 CTA 内 `#fff`。

---

## §5 · Mono 装饰元素(品牌签名 · 不能丢)

| 用法 | 示例 |
| ---- | ---- |
| 方括号标签 | `[ 200 OK ]` `[ /v2 ]` `[ .MP4 · 9:16 ]` `[ STUDIO ]` `[ ALL · 12 ] →` |
| 注释时间戳 | `// 05.14 · 周五 · 14:32` |
| 命令路径 | `/sidebar collapse · /toast dismiss` |
| 数值后缀 | `¥327`(主体大字)+ `<small>.40</small>`(小字次级) |
| 强调单词上色 | `<b style="color: var(--accent-black)">3 个项目</b>` — 加深一档,**不变橙**。橙色只留给 CTA |
| ASCII 散点装饰 | 主区域 4 角撒 `· · + +XX+ +XXXX·` / 8.5 px / `--black-alpha-12` |
| 边角 Mono 标签 | 主区域 4 角:左上 `[ 200 OK ]` / 右上 `[ /v2 ]` / 左下 `[ .MP4 · 9:16 ]` / 右下 `[ STUDIO ]` |
| 链接式"更多" | `[ ALL · 12 ] →` — mono 标签 + 箭头,`--black-alpha-48`,hover 转橙 |
| 缩略图占位 | 不放假图,放比例 `9:16` mono 字符 |

**字体:** `var(--font-mono)` / 11 px / `0.04em` 字距(标签场景)。

---

## §6 · 五种页面级布局模式

页面骨架统一,**内容区布局**按用途分 5 类:

### A · 看板型(Dashboard)
**代表页:** [index.html](index.html) · [projects.html](projects.html)(列表)· [library.html](library.html)
**布局:** KPI 行(`.stats.with-corners`)→ 多个 section(`.section-h` + 内容卡)→ 列表行 / shortcut 网格
**辅助类:** `.dash-grid`(1.7 fr + 1 fr 主辅)/ `.recent-row` / `.shortcut` / `.tip`(虚线提示)

### B · 列表 + 筛选型(List + Filter)
**代表页:** [products.html](products.html) · [projects.html](projects.html) · [library.html](library.html) · [team.html](team.html)
**布局:**
```
[ toolbar(search-inline + chip-wrap × n + view-toggle) ]  ← sticky top
[ result-meta · 共 N 条 ]
[ ░░ 卡片网格 / 列表 ░░ ]
[ pagination ]                                            ← sticky bottom
[ bulk-bar(选中后显示) ]                                  ← 吸底浮动
```
**辅助类:** `.product-card / .proj-card / .asset-card` · `.view-toggle` · `.pagination` · `.bulk-bar` · `.card-check` · `.card-del-btn`

### C · 编辑器型(Editor / IDE)
**代表页:** [pipeline.html](pipeline.html) · [model-photo.html](model-photo.html) · [image-optimize.html](image-optimize.html) · [studio.html](studio.html)
**特征:** 锁视口高度 · 多栏内部滚 · 大量页面级独有样式(目前 inline `<style>` 600-1400 行)
**布局:** 左栏(资产/导航 sticky)+ 中央(画布/参数)+ 右栏(预览/AI 助手)
**⚠️ 警告:** 这一类页面定制最多,改之前先确认 restraint.css 没有现成组件再加 inline。

### D · 表单 / 向导型(Wizard / Form)
**代表页:** [projects-new.html](projects-new.html) · [products.html](products.html) drawer · [account.html](account.html) · [settings.html](settings.html)
**布局:** 左侧 sticky 步数条 + 右侧多 pane 同时显示(非 Tab 切换)
**辅助类:** `.wizard` · `.steps .step` · `.wiz-pane` · `.opt-card` · `.bullet-list`

### E · 单卡型(Single Screen)
**代表页:** [login.html](login.html) · [register.html](register.html)
**特征:** 不渲染 sidebar/topbar · 全屏灰底 + 中心白卡

---

## §7 · 待统一清单(V2.1 落地偏离点)

> 扫完 18 个 HTML 发现的偏离点。按影响视觉一致性的程度排序。**改页面时遇到这些点,顺手改正。**

### 高优先级(影响视觉对齐)

| # | 问题 | 现状 | 应改为 |
| - | ---- | ---- | ------ |
| 1 | **按钮等级混乱**(★ 最严重) | 各页随意选 `.btn` / `.btn-primary` / `.btn-ghost`,有的页面 2 个一级按钮并列,有的把"取消"做成主橙;尺寸也乱(38/32/44 混) | 按 §4.1 三级体系:**一个区域只 1 个一级**(`.btn-primary`,主动作)· 二级 `.btn`(并列动作)· 三级 `.btn-ghost`(辅助)· 尺寸默认 36 / lg 40 / sm 28 |
| 2 | 输入框高度 | products 38 / projects search 32 / login 36 | 统一 36 |
| 3 | Tab 激活样式 | product-detail 下划线 / library 底色填充 | **统一下划线 + bottom 2 px `--heat`** |
| 4 | Hover 底色 | 多数 `--background-lighter` / 部分 `--black-alpha-4` | **统一 `--black-alpha-4`** |
| 5 | 卡片标题字号 | projects 13.5 / products 14 | **统一 14 px / 500** |
| 6 | 卡片网格列宽 | products 240 固定 / library auto-fill 180 / projects-new 4 列固定 | 商品类 240 · 资产类 180 · 通用 `auto-fill minmax(220px, 1fr)` |

### 中优先级(语义偏离)

| # | 问题 | 现状 | 应改为 |
| - | ---- | ---- | ------ |
| 7 | Pill 变体不全 | restraint.css 只 4 种(info/ok/err/neutral),library 用了 `.pill.archive` 没定义 | 在 restraint.css 补 `.pill.archive`(灰)、`.pill.warn`(honey 黄) |
| 8 | X 关闭按钮 | drawer 30 / modal 32 / toast inline 28 | **统一 32×32 / 8 px 圆角** |
| 9 | label 字重 | products 500 / product-detail 600 | **统一 500** |
| 10 | mono 装饰 | 部分页有 4 角 `[ 200 OK ]`,部分没 | **主工作台型必须有,编辑器型可省** |
| 11 | section-h 分隔 | 部分用 `border-bottom`,部分不用 | **统一不用**(留白即分隔) |

### 低优先级(架构清理)

| # | 问题 | 现状 | 应改为 |
| - | ---- | ---- | ------ |
| 12 | 编辑器页 inline `<style>` 过大 | pipeline 795 / model-photo 1393 / platform-cover 1003 行 | 抽 `.stepper / .shot-card / .mp-prod-item / .pl-modal` 等高频组件到 restraint.css 或独立 editor.css |
| 13 | 四角准星重复 SVG | restraint.css 已有 `.with-corners` 工具,部分页面又自己定义了 SVG 背景 | 全部改用 `.with-corners` + `<span class="corner-tr/.corner-bl">` |
| 14 | 滚动条样式残留 | 部分页 inline `scrollbar-width: thin` | restraint.css 已 `!important` 全局隐藏,清理 inline |
| 15 | mono 字体里的中文 | 部分页直接写 `font-family: monospace` 走系统字体 | 全部换 `var(--font-mono)` |

---

## §8 · Don't List(绝对禁止 · 每次自检)

- ❌ **0 px 硬切角的卡片** — 一律 8 px
- ❌ **大圆角 `>12 px`** — 直接判错
- ❌ **渐变背景 / 玻璃拟态** — 只允许 modal 遮罩 `backdrop-filter: blur`
- ❌ **彩色 emoji** — 一律 SVG line icon · stroke 1.5
- ❌ **多个 accent 色** — 全场只有橙(其他色仅做语义信号点)
- ❌ **hover 时换深 hue 的橙** — 用 alpha,不用更深的橙(`#D04E1F` 这种判错)
- ❌ **真 `border` + hover 边框消失** — 用 inside-border `::before`
- ❌ **居中对齐大段正文** — 全部左对齐
- ❌ **同一行混用直角和圆角** — "不要有些是直角,胶囊又是圆角"
- ❌ **荧光状态色** — 避免霓虹绿、电光蓝、霓虹粉
- ❌ **页面内 `<style>` 重写共享类**(`.btn` `.pill` `.input` `.modal` 等)— 改 restraint.css
- ❌ **新建色 token** — 必须复用现有 token
- ❌ **`⌘` Unicode 字符** — JetBrains Mono webfont 不带该字形,显示成方框 → 用 "Ctrl K" 纯文本或 SVG
- ❌ **多色 emoji icon / filled icon** — 一律 line icon
- ❌ **居中卡片浮在背景上的"贴纸感"** — 用边框 + 装订线,不用阴影
- ❌ **彩虹流光 / hover 旋转缩放** — 无意义微动效
- ❌ **场记板 / 丝绒 / 霓虹灯** — 装饰盖过内容,判错

---

## §9 · 新页面 / 改页面 checklist(每次必过)

### 写代码前
- [ ] 已 Read 本文件 §1 § 3 § 8(至少)
- [ ] 用 `Grep` 查 restraint.css 是否已有该组件
- [ ] 看 `_archive/design-system.html` 找视觉参考(用浏览器打开 file://)
- [ ] 不确定的设计点 — **先问用户**,不要凭感觉

### 写代码时
- [ ] HTML 用 `<div class="app"><aside class="sidebar"></aside><main><div class="topbar"></div><div class="content">…</div></main></div>` 骨架
- [ ] head 含 `<link rel="stylesheet" href="assets/restraint.css">` + Inter + JetBrains Mono Google Fonts
- [ ] body 末尾 `<script src="assets/shell.js" defer></script>`
- [ ] 标题区用 `.page-head > h1 + .sub`
- [ ] 主操作按钮放 `.page-head > .actions`(自动 40 px 高)
- [ ] 子区块用 `.section-h > h2 + .more`
- [ ] 按钮全 `.btn` 系列 · 不要自己写
- [ ] 状态徽标全 `.pill.info/.ok/.err/.neutral` · 要新变体先回 restraint.css 加
- [ ] 输入框全 `.input / .select / .textarea` · 字段用 `.field`
- [ ] 浮层全用现成 Modal / Drawer / Toast
- [ ] 图标 SVG line icon · stroke 1.5 / linecap round / `stroke="currentColor"`
- [ ] 时间戳 mono 注释 `// 05.22 · 周四`
- [ ] 强调单词加深(不变橙) `<b style="color:var(--accent-black)">3 个</b>`
- [ ] 数字加 `.num` 或 `tabular-nums`
- [ ] 状态色按语义选 `--heat / --accent-forest / --accent-crimson / --accent-honey`

### 写完自检
- [ ] 对照 §8 Don't List 逐条过
- [ ] 在浏览器打开页面 · 截图 + 跟 design-system.html 对比
- [ ] 测 hover / focus / active / disabled 状态都正确
- [ ] 测 dark mode(给 body 加 `.dark` class 看是否破)
- [ ] 移动端缩到 1100 px 以下看响应式

### 提交前
- [ ] 不在 master/main 上,在 dev 分支
- [ ] 不带 `--no-verify`,不跳过 hook
- [ ] commit 信息简洁,说"为什么"不只是"什么"

---

## §10 · 参考资料

- [assets/restraint.css](assets/restraint.css) — 共享 CSS · token 定义 + 100+ 组件类(1592 行)· 实现层
- [assets/shell.js](assets/shell.js) — 通用 sidebar / topbar 注入
- [_archive/design-system.html](_archive/design-system.html) — 历史交互样板间(浏览器打开看效果)
- [_archive/DESIGN_SPEC_V2.md](_archive/DESIGN_SPEC_V2.md) — 历史详细规范(理论依据 / 迁移轨迹)
- 视觉灵感:Firecrawl Playground · Linear · Stripe Dashboard
- 图纸感来源:印刷套版准星 + 老 Unix 终端

---

**任何条款不清晰、想加新组件、或想改 token,先在群里讨论 → 写进本文件 → 改 restraint.css。**
**永远不要在某个页面 inline `<style>` 里偷偷扩展规范。**