hunjing/frontend/design/README.md

design — 视觉原型（North Star）

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

共享层

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

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

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

新建 AppShell 原型时：

<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。灵台 · 魂册 · 心智 · 编排·酒馆融合 · 内景 · 藏识 · 百工。所有 AppShell 页（除 chat）由 _theme.js 自动注入同一份；底部另有「设计系统」入口直达 North Star 基准页。logo 单击即时回目录，350ms 内连点 5 次触发「镜启」彩蛋。

本地预览

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

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

原型索引

入口：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（命名已于 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 — 把原型接入共享层（加 _chrome.css link、替换 sidebar 为 mount、加 _theme.js）。一次性迁移已完成；新原型按上文模板手写即可。
• clean-design-css.mjs — 清理各页与 _base.css / _chrome.css 重复的 body / reset / sidebar CSS（幂等，可重复跑）。
• serve-design.mjs — 零依赖预览服务器，pnpm design 调用。