# design — 视觉原型（North Star）

本目录是魂镜前端的设计原型集合，**非生产代码**。入口：[`index.html`](./index.html)（可点击目录，每张卡带 **live iframe 缩略图**，`pnpm design` 后访问）。每个 `*-preview.html` 是视觉参考稿，共享三层样式（`tokens` / `_base` / `_chrome`）与统一侧栏（`_nav.html` 经 `_theme.js` 注入），页面 `<style>` 仅保留页面特异样式。实现时按其重写为 `src/` 下的 React 组件。

## 共享层

原型引用**三层共享文件** + **统一侧栏片段** + **共享脚本**，消除此前每个原型各存一份 token / reset / sidebar 副本（且已漂移、写法分叉）的问题。改一处，全站 25 页同步。

| 文件 | 职责 |
| --- | --- |
| [`tokens.css`](./tokens.css) | 铜镜鉴心 暗+亮 全套 CSS 变量（`--ink` / `--patina` / `--gilt` / `--cinnabar` …） |
| [`_base.css`](./_base.css) | reset / `body` / 极光铜晕 `body::before` / `.serif` / `.mono` / `prefers-reduced-motion` |
| [`_chrome.css`](./_chrome.css) | AppShell 组件层：`.sidebar` / `.nav-item` / `.card` / `.btn` / `.tag` / `.page-header` / `.back-link` |
| [`_nav.html`](./_nav.html) | 统一 7 组侧栏片段（20 项），由 `_theme.js` fetch 注入各页 `.sidebar-mount` |
| [`_theme.js`](./_theme.js) | nav 注入 + 当前页高亮 + 主题切换 + `localStorage` 持久化 + logo 回首页 |

加载顺序：`tokens.css` → `_base.css` → `_chrome.css` → 页面 `<style>`。**页面 `<style>` 只写页面特异样式**，不得重复定义 `_chrome.css` 已覆盖的 `.sidebar` / `.nav-item` / `body` / `:root`——否则后加载覆盖共享层，改一处不再全站生效。

**新建 AppShell 原型时**：

```html
<head>
  <link rel="stylesheet" href="tokens.css" />
  <link rel="stylesheet" href="_base.css" />
  <link rel="stylesheet" href="_chrome.css" />
  <style>/* 仅页面特异样式 */</style>
</head>
<body>
  <div class="app-shell">
    <div class="sidebar-mount" data-active="当前页名"></div>
    <div class="main-area"><!-- page-header + page-body --></div>
  </div>
  <script src="_theme.js" defer></script>
</body>
```

`data-active` 对齐 `_nav.html` 的 `data-nav`（如 `对话` / `灵枢` / `魂册降生`）。**加导航项 / 改链接**：只改 `_nav.html` 一处。**改 sidebar 视觉**：只改 `_chrome.css` 一处。

> **与生产侧的差异（有意）**：`tokens.css` 的 `--surface` 是半透明玻璃（`rgba(255,255,255,0.022)`，配极光底做镜面通透感）；`src/styles/globals.css` 演进为实色面板（`#121817`，渲染可预测）。两层各持一套，勿强行统一。

## 布局体系

原型按页面层级用 4 种 shell：

| Shell | 用途 | 结构 | 代表页 |
| --- | --- | --- | --- |
| **AppShell** | 功能页（主导航可达） | `.sidebar-mount`（注入）+ `main-area`（page-header + page-body） | cosmos / wuxing / characters / chat / personality / drive / evolution / world / time / memory / archive / tools / model-gateway / settings / admin / card-import / lorebook / rune-engine / margin-notes … |
| **NarrowShell** | 二级详情页（从人物列表进入） | `app-main` max-width 居中 + `back-link` 面包屑；**仍注入侧栏**（高亮上级项 `人物`） | character-detail / character-materials |
| **StageShell** | 登录 / 落地 / 目录 | `stage` max-width 居中，无 sidebar（或独立 theme 按钮） | copper-mirror-v2 / login / **index** |
| **AdminShell** | 司命台控制台 | dashboard 网格（也注入 `.sidebar-mount`） | admin / admin-characters |

> **NarrowShell 与侧栏**：二级详情页（人物详情 / 资料）保留侧栏注入并高亮 `人物`，便于在详情态随时切走；`back-link` 面包屑负责"回到列表"的层级回退。两者职责不同，并不冲突。
>
> **归类修正（2026-07-25）**：`card-import` / `lorebook` 原标 NarrowShell，实际带 sidebar（属一级功能页），归 **AppShell**——主区宽度与 shell 类型解耦（窄流程页用 `.app-main` 限宽，但仍有全局导航）。NarrowShell 仅用于「从人物列表进入的二级详情」。
>
> **分组重组（2026-07-27）**：原「载入」组重命名为「**编排**」——该组横跨数据载入（魂册降生 / 世谱）与运行时编排（符文引擎 / 眉批），「编排」涵盖两者。心智组内分层：灵枢（总览）↔ 维度（五行 / 人格 / 内驱力 / 演化），以 `.nav-divider` 发丝线分隔。每项 nav 加 `data-route` 数据属性（供调试 / a11y 辅助，侧栏不渲染——路由映射见目录页 `.proto-route` 与原型索引表）。

**chat** 同样接入 `.sidebar-mount`（与其他 AppShell 页一致）。其此前的 60px 可折叠 sidebar 是未完成态（折叠隐藏文字但 HTML 无图标替代 → 空白窄条，且无触发器无法展开），已统一为标准 220px 展开侧栏；对话区宽度由 `.main-area` flex 自适应。

**统一 sidebar 导航（7 组 20 项）**：见 [`_nav.html`](./_nav.html)。灵台 · 魂册 · 心智 · **编排·酒馆融合** · 内景 · 藏识 · 百工。所有 AppShell 页（除 chat）由 `_theme.js` 自动注入同一份；底部另有「设计系统」入口直达 North Star 基准页。**logo 单击即时回目录**，350ms 内连点 5 次触发「镜启」彩蛋。

## 本地预览

侧栏经 `_theme.js` 用 `fetch` 注入 `_nav.html`，目录页缩略图用 live `<iframe>`；`file://` 双击打开时两者均受 CORS 限制（侧栏显示 fallback 提示、缩略图空白）。须启动本地服务器：

```bash
pnpm design   # → http://localhost:3001（零依赖，scripts/serve-design.mjs）
```

## 原型索引

**入口**：[`index.html`](./index.html)（可点击的目录页，每张卡带 live iframe 缩略图）。

> 状态：✅ 已落地（有对应路由） · 🟡 部分/待确认 · ⬜ 待实现 · 🆕 新增

### 设计系统 / 北极星

| 文件 | 功能 | 路由 | 状态 |
| --- | --- | --- | --- |
| `copper-mirror-redesign-v2` | 铜镜鉴心 North Star（色谱 / 字阶 / 组件 / 九枢星盘） | — | 🎯 设计基准 |
| `copper-mirror-login` | 登入灵台 | `/login` | ✅ |

### 灵台 · 对话

| 文件 | 功能 | 路由 | 状态 |
| --- | --- | --- | --- |
| `chat-redesign-preview` | 对话页 v6 | `/chat` | ✅ |
| `run-trace-preview` | 运行轨迹 | `/runs/[id]` | ✅ |

### 魂册

| 文件 | 功能 | 路由 | 状态 |
| --- | --- | --- | --- |
| `characters-preview` | 人物列表 | `/characters` | ✅ |
| `character-detail-preview` | 人物详情 | `/characters/[id]` | 🟡 |
| `character-materials-preview` | 人物资料与沉淀 | `/characters/[id]/*` | 🟡 |

### 心智

| 文件 | 功能 | 路由 | 状态 |
| --- | --- | --- | --- |
| `cosmos-preview` | 灵枢（九枢系统视图） | `/cosmos` | ✅ |
| `wuxing-preview` | 五行 | `/wuxing` | ✅ |
| `personality-preview` | 人格 | `/personality` | ✅ |
| `drive-preview` | 内驱力 | `/drive` | ✅ |
| `evolution-preview` | 演化 | `/evolution` | ✅ |

### 编排 · 酒馆融合（P0/P1，路由已定）

| 文件 | 功能 | 路由 | 状态 |
| --- | --- | --- | --- |
| `card-import-preview` | 魂册降生 · 角色卡导入导出 | `/characters/import` | ⬜ P0 |
| `lorebook-preview` | 世谱 · World Info | `/lorebooks` | ⬜ P0 |
| `rune-engine-preview` | 符文引擎 · Macros | `/macros` | 🆕 P0 |
| `margin-notes-preview` | 眉批 · Author's Note | `/author-notes` | 🆕 P1 |

### 内景

| 文件 | 功能 | 路由 | 状态 |
| --- | --- | --- | --- |
| `world-preview` | 世界（河图绘形） | `/world` | ✅ |
| `time-preview` | 时态 | `/time` | ✅ |

### 藏识

| 文件 | 功能 | 路由 | 状态 |
| --- | --- | --- | --- |
| `memory-preview` | 记忆 | `/memory` | ✅ |
| `archive-preview` | 归档（记忆时间河） | `/archive` | ✅ |

### 百工 · 系统

| 文件 | 功能 | 路由 | 状态 |
| --- | --- | --- | --- |
| `tools-preview` | 工具 | `/tools` | ✅ |
| `model-gateway-preview` | 模型网关 | `/models` | ✅ |
| `settings-preview` | 设置 | `/settings` | ✅ |

### 司命台 · admin

| 文件 | 功能 | 路由 | 状态 |
| --- | --- | --- | --- |
| `admin-preview` | 司命台融合稿 | `/admin` | ✅ |
| `admin-characters-preview` | 人物模板管理 | `/admin/*` | 🟡 |

## 酒馆（SillyTavern）融合映射

酒馆功能**已融入魂镜中式命名**，不单设 `tavern/` 子目录——相关原型就是魂镜的功能页。下表把酒馆概念串到魂镜名、对应原型、后端表与设计文档章节。权威设计见 [`docs/contracts/contract-glossary.md`](../../docs/contracts/contract-glossary.md)（命名已于 2026-07-24 拍板，登记契约字典 §2.1）。

| 酒馆概念 | 魂镜名 | design 原型 | 后端表 | 文档 § | 阶段 |
| --- | --- | --- | --- | --- | --- |
| Character Card | **魂册** | `card-import` · `character-materials` · `personality` | `character` | §8 | **P0** |
| World Info / Lorebook | **世谱** | `lorebook` · `world` | `lorebooks` | §7 | **P0** |
| Macros `{{char}}` | **符文引擎** | `rune-engine` | `macros` | §8.4 | **P0** |
| Author's Note | **眉批** | `margin-notes` | `author_notes` | §9.1 | P1 |
| Prompt Manager | 言灵编排 | ⛔ 无 | — | §9.2 | — |
| User Personas | 本相 | ⛔ 无 | — | §9.3 | — |
| Presets | 火候 | ⛔ 无 | — | §9.4 | — |
| Instruct Mode | 科仪 | ⛔ 无 | — | §9.5 | — |
| Regex Scripts | 刻符 | ⛔ 无 | — | §9.6 | — |
| Quick Reply | 锦囊 | ⛔ 无 | — | §9.7 | — |
| Slash Commands | 咒令 | ⛔ 无 | — | §9.8 | — |
| Group Chat | 雅集 | ⛔ 无 | — | §9.9 | — |

**已建原型**：`符文引擎`（rune-engine，P0）、`眉批`（margin-notes，P1）。其余酒馆载体（言灵编排 / 本相 / 火候 / …）尚无原型——若需要，可建 `design/tavern/` 子目录放置并在上表登记。

## 设计决策摘要

- **铜镜鉴心语言**：铜绿锈（主色·在场/健康/记忆）、鎏金（结构/发丝线）、朱漆（**仅**司命/朱批/告警）、墨/夜铜（暗底）。暗色优先，亮色一等公民。
- **字阶**：宋体（Songti SC）显示字 + 系统体正文 + JetBrains Mono 数据/标签。
- **签名元素**：九枢星盘是"活的仪器"（数据可视化），非装饰。
- **a11y**：亮色 AA 对比度修正、`prefers-reduced-motion`、`focus-visible`、SVG `aria-label`。
- **转 React**：原型共享层（`tokens` / `_base` / `_chrome` / `nav` / `_theme`）仅服务于设计稿；实现时按 section 重写为 React 组件，样式走 `globals.css` 的 `@theme` 映射类（见 `frontend/CLAUDE.md` 的 CSS 变量三层规则）。页面特异样式随组件迁移。

## 已废弃

- `copper-mirror-redesign.html`（v1，双面镜探索方向）——已被 v2 取代并删除，`git show HEAD:frontend/design/copper-mirror-redesign.html` 可取回。
- `admin-preview.html.bak`——已删除。

## 维护脚本（`frontend/scripts/`）

- [`migrate-design.mjs`](../scripts/migrate-design.mjs) — 把原型接入共享层（加 `_chrome.css` link、替换 sidebar 为 mount、加 `_theme.js`）。一次性迁移已完成；新原型按上文模板手写即可。
- [`clean-design-css.mjs`](../scripts/clean-design-css.mjs) — 清理各页与 `_base.css` / `_chrome.css` 重复的 body / reset / sidebar CSS（幂等，可重复跑）。
- [`serve-design.mjs`](../scripts/serve-design.mjs) — 零依赖预览服务器，`pnpm design` 调用。