AirShelf/电商AI平台/design.md

流·Studio 设计规范 · design.md

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

::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,不触发布局抖动。

.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>:

<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> 末尾:

<script src="assets/shell.js" defer></script>

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

§3.2 标题区(必有)

<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 子区块(可选)

<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 / 编辑器全屏画布不必加。

.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	中性 / 已归档

<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)

<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 段流水线)

<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 筛选(下拉)

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

D · 表单 / 向导型(Wizard / Form)

代表页: projects-new.html · products.html drawer · account.html · settings.html 布局: 左侧 sticky 步数条 + 右侧多 pane 同时显示(非 Tab 切换) 辅助类: .wizard · .steps .step · .wiz-pane · .opt-card · .bullet-list

E · 单卡型(Single Screen)

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

---

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