git:20261104.0c13885 to git:20261104.4a802a7

# DESIGN.md — Flint 界面设计系统

> 视觉世界与实现约定的单一来源。产品判断见 `PRODUCT.md`，使用说明见 `../README.md`，工程约定见 `../AGENTS.md`。

> 本文描述的是 2026-11 的整体重设计（矿物标本柜），旧版蓝灰 SaaS 外观不再有效。

## 1. 世界：矿物标本柜

Flint 是燧石。界面把「技能」当矿物标本陈列：一处沉淀的标本，多处落点。世界只提供三样东西——**石头质的底色、标本标签的排版、刻度的状态表达**。布局、导航、控件都是常规工具形态，不扮演仪表盘、终端或科幻舱。

- **一个强调色**：朱砂（`--c-accent`）只给主操作、激活项、活跃状态与焦点。它出现的地方就是「火花」出现的地方。

- **状态是刻度，不是色块**：`--c-good / --c-warn / --c-bad / --c-info / --c-standard` 取矿物颜料（玉、赭、赤、石青、紫晶），只承担语义；徽标同时带图标或文字，不靠颜色单独编码。

- **标签行**：实体的次要信息（`name@来源`、路径、版本）排成等宽目录行，像标本卡上的编号行，可扫读、可对齐。

## 2. Token（`src/styles/tokens.css`）

| 组 | 变量 | 说明 |

| --- | --- | --- |

| 底色 | `--c-bg` `--c-surface` `--c-surface-2/3` `--c-bg-2` | 石灰岩纸底（浅）／玄武岩（深）；`--c-bg-2` 是代码块凹底 |

| 墨 | `--c-ink-1/2/3` | 三级文字，均 ≥ 4.5:1；不要再引入第四级灰 |

| 侧轨 | `--c-rail` `--c-rail-2` `--c-rail-ink` `--c-rail-ink-dim` `--c-rail-line` | 浅色主题下侧轨仍是深玄武岩：方位由它承担 |

| 强调 | `--c-accent` `-hover` `-active` `-soft` `-line` `--c-on-accent` | 朱砂；`-soft` 只做底纹，不承载文字以外的信息 |

| 状态 | `--c-good/warn/bad/info/standard` + `-soft` | `standard` 专指「开源生态推荐目录」，与活跃/非活跃正交 |

| 线 | `--c-line` `--c-line-strong` | 1px 发丝线；分格靠它，不靠阴影 |

| 焦点 | `--c-focus` `--c-focus-ring` | 2px 实心环 + 3px 柔光 |

| 间距 | `--sp-1…8`（4px 基线） | 组件内 8/12，区块 24/32 |

| 圆角 | `--r-sm/md/lg` = 3/6/8px，`--notch` = 7px | 石头切口，不做大胶囊 |

| 字体 | `--ff-sans` = Archivo，`--ff-mono` = JetBrains Mono | 标题同族，靠字重/字号/紧字距分层 |

| 字号 | `--fs-11…26` | 11px 是功能文字下限；正文 13–14，页标题 26 |

| 动效 | `--dur-100/150/250` `--ease` `--ease-out` | 只有三档，`prefers-reduced-motion` 下全部归零 |

| 壳层 | `--rail-w` `--topbar-h` `--control-h` | 232 / 56 / 36 |

主题跟随系统（首次打开按 `prefers-color-scheme`，读不到时用深色），由 `index.html` 内联脚本在首帧写入 `data-theme`，避免深色底闪白。用户手动切换才写入 `localStorage.lsh-theme`。

## 3. 壳层与布局

```

[ 232px 玄武岩侧轨 ][ 顶栏 56px（仅详情显示面包屑 + 工具）]

[ 内容区 max 1220px ]

```

- 侧轨：品牌燧石标记 + `FLINT` 字标 + 导航（图标 + 文字 + 计数）。激活项 = 深底面 + 右上凿口 + 左侧 4×16px 朱砂刻度，并带 `aria-current="page"`。≤1080px 收成 64px 图标轨，≤760px 变成横向导航条（保留字标）。

- 顶栏：列表页左侧留空（页名由内容区 h1 承担，避免同一页写两次标题）；详情页显示 `页面 / 对象标识` 面包屑，右侧是刷新 / 主题 / 语言三枚方形工具。

- 页面标题：`h1`（26px，`--fs-26`）→ 区块 `h2`（列表区标题、section-head）→ 卡片 `h3`。不再跳级。

- 列表区（`.listing`）不套外框：标题下方一条发丝线，卡片/台账直接立在石面上。**只有表单、设置、详情分组才用 `.panel` 盒子**，避免卡片套卡片。只装列表的 `.panel` 也会被 `:has()` 规则降级成无框分区。

## 4. 组件约定

| 组件 | 规则 |

| --- | --- |

| `.btn` | 32/26px 高、3px 圆角、1px 描边。`--primary` 用朱砂填充，并在右上角叠 7px 暗面凿口（用渐变实现，不用 `clip-path`，以免裁掉焦点环）。`--ghost` 无边框，hover 才显形。 |

| `.field` | 36px 高；hover 加深描边，focus 用朱砂描边 + 3px 柔光。`select` 自绘箭头。 |

| `.badge` | 标本标签：2px 圆角、1px 同色描边、浅底、11px；禁止胶囊化。 |

| `.dot` | 6px 方块：填充 = 生效，空心 = 未生效。 |

| `.chip` | 过滤器；选中 = 朱砂描边 + 浅底 + 底部 2px 实线。 |

| `.seg` | 视图切换；选中项用底部 2px 朱砂线，不用位移。 |

| `.switch` | 34×20 方形轨道 + 方形滑块；checked 时整体朱砂。 |

| `.entity-card` | `--c-surface` 抬起的石片 + 1px 线 + `--sh-1`；四角有 8px 裁切标记（hover 变朱砂）；标题 15px、副行 12px 等宽、描述 2 行截断、操作行钉在底部（`margin-top:auto`）保证整行基线一致。`is-off` 改虚线并压暗标题；`--standard` 换紫晶刻线。卡片里有操作时不再显示来源（已在上方标签行里）。 |

| `.entity-list` / `.entity-row` | 台账：行间只靠 1px 横线，hover 用半透明底纹（面板内外都可见）。行标题 13px 600，副行等宽 12px。 |

| `.std-title__info` | 说明气泡只在 hover/focus 时挂载（常驻会被算成溢出，也会被读屏当正文）；按钮保留 `aria-label`。 |

| 路径 | 一律用 `<PathText>`：在 `/` 后插入 `<wbr>`，只在分隔符处换行，不产生额外字符（复制与文本匹配仍是原路径）。 |

| 空状态 | 40px 手绘图标（`Icon` 的 `flint` 兜底）+ 标题 + 提示；不写营销句。 |

| 弹窗 | 遮罩 56% 玄武岩 + 4px 模糊；打开即收焦、Tab 循环、Esc 与点遮罩关闭、关闭后焦点回到触发点。 |

## 5. 图标

`src/components/ui/Icon.tsx` 是全站唯一图标源：24 视框、1.5 描边、圆头端点、`aria-hidden`。**禁止用 Unicode 字符或 emoji 充当图标**（会随字体变形、无法对齐、读屏行为不可控）。`EmptyState` 历史上传的字符通过 `iconFromGlyph` 映射到绘制图标，新代码直接用 `Icon`。

## 6. 动效

三处，都是「一次性的、有因果的」：

1. 切页：内容区整体上浮 6px + 淡入（250ms）。

2. 弹窗：0.99 → 1 缩放 + 上浮 8px（250ms）。

3. 悬停：卡片上浮 1px 换 `--sh-2`；行换底纹；裁切标记变朱砂（150ms）。

没有循环动画、没有视差、没有与滚动绑定的效果。`prefers-reduced-motion: reduce` 下全部关闭。

## 7. 无障碍

- 正文与次要文字 ≥ 4.5:1（浅/深两套分别实测；此前的 `#8b90a5` 已废弃）。

- 状态不只靠颜色：徽标配图标（✓ / ▲ / ✕）或文字；目录状态用「填充/空心」刻度。

- 焦点可见：`:focus-visible` 2px 朱砂实心环 + 2px 偏移；卡片 `:focus-within` 另加 3px 柔光。

- 图标按钮一律带 `aria-label` + `title`；侧轨 `aria-current`；弹窗 `role="dialog"` + `aria-modal` + `aria-labelledby`。

- 触达尺寸：工具按钮 32px，卡片操作 26px（桌面工具，不追求 44px）。

## 8. 已知取舍（记录，不视为缺陷）

- **11px 等宽元数据**：`name@来源`、路径、计数是标本标签，不是正文；布局检测器会以「body text < 12px」提示，这里保留 11–12px 以免破坏密度。已把 `.entity-card__sub` 提到 12px 作为折中。

- **SKILL.md 正文的 `line-length` / `em-dash` 提示**：那是用户技能的原始内容，原样呈现，不做改写。

- **页名在顶栏与 h1 同时出现**：只发生在详情页（面包屑 = 页面 / 对象），列表页顶栏不再重复页名。

历史文件名不再使用：`--c-accent-2`、`--c-good-2`、`.entity-card__top`、`.card-strip`。新增组件前先看本表，不要另起一套。