git:20260804.d3cfee8 to git:20260806.c9aaaee

- # Claude Code Required Project Instructions

-

- This repository is Roam / ttmux. Before editing code, read:

-

- - [AGENTS.md](AGENTS.md) for shared coding-agent rules.

- - [docs/development/i18n.md](docs/development/i18n.md) for the mandatory internationalization standard.

- - [docs/development/ui-design-system.md](docs/development/ui-design-system.md) before touching any Web UI.

-

- Internationalization is required for all user-facing product UI. Do not add new hardcoded Chinese or English UI copy in React components, fallback HTML, or user-visible backend responses unless the i18n standard explicitly allows it.

-

- ## Web UI 硬规则

-

- 改前端时以下几条是强制的，细节与踩坑清单见上面的设计系统文档：

-

- - **只用令牌，不写死数值。** 字号六档（`--fs-micro/meta/sm/body/lg/title`）、圆角四档

- （`--r-xs/sm/card/pill`）、间距五档（`--sp-1`…`--sp-5`）、强调色一组

- （`--accent` / `--accent-solid` / `--accent-soft` / `--accent-border`）、成功绿一组

- （`--ok` / `--ok-solid` / `--ok-soft` / `--ok-border`）。

- **全站蓝只有一支、绿只有一支**（品牌标同色），组件里不许再出现 `#58a6ff` / `#3fb950`

- 这类十六进制。**除眉标/角标外字号不许低于 12px**，不要出现 10.5 / 11.5 / 12.5 这类半档。

- - **强调色不要照抄十六进制**：antd 的 darkAlgorithm 会在 seed 上再推导一层，照抄的值

- 必然比 antd 自己画的差一档。要一致就用 `--accent-solid`。

- - **断点只有一个入口** `useLayout()`；不要读 `window.innerWidth`，不要自己 `matchMedia`。

- 纯样式差异走 `<html>` 上的 `data-size` / `data-pointer`。

- - **粗指针下命中区 ≥44**，用伪元素撑命中区、不撑视觉尺寸。

- - **一级页面的页头用 `.tt-pagehead`**（眉标 + 标题 + 一句话），不要各写各的标题行。

- - 前端改动不能只靠 typecheck 收工：真机验收跑法见

- [docs/development/web-ui-checklist.md](docs/development/web-ui-checklist.md)。

- 提交前必过 `npm run typecheck && npm run i18n:check && npx vitest run && npm run build`。

-

- ## 图标硬规则（不许 emoji、不许文字符号）

- 界面上的图标**只有一种来源：SVG**。以下三类一律禁止新增，看到旧的顺手换掉：

- 1. **emoji**：🔄 📎 🤖 📢 📖 ✏️ 🔍 🌐 ✅ ⬜ 🏠 👤 🧭 🎨 …

- 各平台字体各画各的，大小、基线、配色都不受控，一列排下来高低不齐，深色底上还常常自带白边。

- 2. **文字符号当图标**：`✕ × ✓ ✔ ▾ ▸ ▼ ▶ ← → ↑ ↓ ⌃ ⏎ ■ ● ○ ◆ ◁ ▭ ⚠ ⎇ ⧉ ⇡ ⇥ ⬡ ⚑ ＋ ❯ ⤷` …

- 字号下与标点混作一团、粗细跟不上线性图标语言、基线随字体漂，手机字体上尤其难看。

- 3. **临时自画的一次性 SVG**：想要的图标没有就**加进图标模块**，不要在组件里就地画一个。

- 规则：

- - **唯一出处 [`frontend/src/icons.tsx`](frontend/src/icons.tsx)**：24×24 viewBox、

- `stroke="currentColor"`、1.8 线宽、圆头圆角，颜色一律继承父级（不写死）。

- 文件类型图标在 `frontend/src/file-icons.tsx`，Git 专用图标在 `frontend/src/git/parts.tsx`，

- 这两处沿用同一套画法；**新图标默认加在 `icons.tsx`**。

- - **同一个动作全站同一枚图标。** 曾经「关闭」在 Dock 是 `✕`、浏览器标签是 `×`、文件页签是

- 第三种写法——这是最刺眼的一类不一致，比图标本身丑更糟。

- - **图标不写进 i18n 文案。** `'＋ 新增任务'` / `'■ 停止'` / `'✓{count} 可清理'` 这种把符号

- 焊死在译文里：换图标要改两份 locale，而且永远换不成 SVG。**文案只写字**，图标在调用处给：

- `icon={<PlusIcon />}`（antd 的 `Button` / `Tag` 都吃 `icon`；`Segmented` / `Menu` 的

- `label` 直接放 JSX）。

- - **状态点、色块用画的，不用字符。** `●` → `border-radius:50%` 的 `<i>`；`■` 图例 →

- `<Swatch color=... />`。

- - **例外只有两类**：① 键盘快捷键提示里的修饰键符号（`⌘ ⇧ ⌃`）——那是键帽的正确排版；

- ② 蜂群「办公室」插画视图里的角色头像 emoji（`Swarm.tsx` 的 `SUBROLES`），

- 那是刻意的插画风格，不是功能图标。除此之外没有例外。

- - 自查：改完在 `frontend/src` 下 grep 一遍 emoji 与上面那串符号（注释、TUI 输出解析用的正则

- 不算），命中即是要改的。