XiStudio v3 · 基础风格与骨架定义总结
一句话：XiStudio v3 = brand-color-system v1.2 法典 × macOS 设计语言 × VSCode/Figma 工作台骨架。 11 个 demo 界面共享同一套设计 token、同一套 6 主题、同一套三段式骨架。本文档是这套体系的精炼定义。
配套阅读： -
v3-implementation-spec.md— Vue 3 落地详细规格（1142 行） -v3-frontend-implementation-roadmap.md— 6 周路线图 -xistudio-codex.css— 视觉法典（1212 行，最终事实来源） -v3-unified-macos.html— 设计原型 demo
0. 11 个 demo 界面的家族图谱
| 类别 | demo 文件 | 角色 |
|---|---|---|
| 统一外壳 | v3-unified-macos.html |
⭐ 设计语言基准，骨架法典原型 |
| XiStudio 系（4） | v3-full-xistudio-graph.html |
链路（流图编辑） |
v3-full-xistudio-tuning-view.html |
调音（Tuning Stack 7 卡片） | |
v3-full-xistudio-simulation.html |
测试（频响/频谱/波形/RTA 4 联屏） | |
v3-full-xistudio-deploy.html |
部署 | |
| XiForge 系（3） | v3-full-xiforge-ui-design.html |
UI 设计器 |
v3-full-xiforge-source.html |
源码视图 | |
v3-full-xiforge-simulation.html |
仿真 | |
| XiTune 系（3） | v3-full-xitune-chain.html |
调音链 |
v3-full-xitune-curve.html |
曲线编辑 | |
v3-full-xitune-abx.html |
A/B 对比 | |
| 辅助页 | index.html / themes.html / themes-runtime.html / product-entry-map.html |
索引、主题展示、产品入口图 |
通用规律：
- CSS 唯一来源 = xistudio-codex.css（1212 行），所有 11 个页面 <link rel="stylesheet" href="./xistudio-codex.css">
- 品牌词不可改 = XiStudio/XiForge/XiTune/XiProbe/XiCloud/XiMind 是产品矩阵，hex 值是 brand-color-system v1.2 法典
- 每个 page = 主壳 + 一个独立中央画布，左/右/底/顶/状态栏与外壳共用
1. 设计 Token 三层模型
┌─────────────────────────────────────────────────────────┐
│ Layer 1 · 法典层 (:root, 不可改) │
│ ├─ 品牌色：--yin / --xi / --sheng / --night-* / --paper │
│ ├─ 等级色：--L0 ~ --L5（产品 6 色阶） │
│ └─ macOS 通用：--radius-* / --mac-shadow-* / traffic-* │
├─────────────────────────────────────────────────────────┤
│ Layer 2 · 语义层 ([data-theme="X"], 6 主题切换) │
│ ├─ 背景：--bg-0 / --bg-1 / --bg-2 / --bg-3 │
│ ├─ 前景：--fg-0 / --fg-1 / --fg-2 │
│ ├─ 强调：--accent / --accent-2 / --accent-fg │
│ ├─ 状态：--info / --ok / --warn / --err │
│ ├─ 画布：--canvas-bg / --canvas-grid-color │
│ ├─ 节点：--node-bg / --node-border │
│ ├─ 面板：--panel-bg / --bottom-bg / --statusbar-bg / │
│ │ --menubar-bg / --toolbar-bg │
│ └─ 特效：--frosted / --hero-grad / --focus-ring │
├─────────────────────────────────────────────────────────┤
│ Layer 3 · 组件层 (.tuning-dialog, .scope-card, ...) │
│ └─ 全部用 var(--xxx) 引用 Layer 2，禁止硬编码 hex │
└─────────────────────────────────────────────────────────┘
1.1 法典色（Layer 1，hex 锁死）
| Token | 角色 | 备注 |
|---|---|---|
--yin（玫瑰金 #D4A574） |
主色 / CTA / 强调 | 主题 A 默认 accent |
--xi（曦紫 #9D4EDD） |
辅色 / 渐变 | Hero 三色之一 |
--sheng（极光青 #5DDECF） |
数据高亮 / 工程师风 | 主题 B 默认 accent |
--night-*（夜蓝 #0B1C2E 系列） |
深色背景 / 标题 | 4 阶 night-0/½/3 |
--pearl / --paper（米纸 #FBFAF6） |
浅色背景 | 主题 C 默认 bg-0 |
--L0 ~ --L5 |
产品 6 色阶 | 用于 .xy-stack / Subgraph classDef |
⚠️ 红线：禁止在任何位置直接写
#D4A574/#9D4EDD/#5DDECF等十六进制。所有引用必须经var(--yin)/var(--accent)等变量。
1.2 macOS 通用变量（Layer 1，主题无关）
/* 圆角 4 级阶梯 */
--radius-sm: 6px; /* 小按钮、tag */
--radius-md: 10px; /* 普通卡片、面板 */
--radius-lg: 14px; /* 浮窗、对话框 */
--radius-xl: 20px; /* 引导卡、Hero */
/* 阴影 3 级 */
--mac-shadow-sm: 1+1px 轻浮起 /* tag、按钮 hover */
--mac-shadow-md: 4+1px 卡片浮起 /* 面板、popover */
--mac-shadow-lg: 12+4px 强浮起 /* 浮窗、命令面板 */
/* 红黄绿 traffic-lights */
--mac-traffic-red: #FF5F57;
--mac-traffic-yellow: #FEBC2E;
--mac-traffic-green: #28C840;
2. 6 主题对照表
主题分为 品牌组（A/B/C，源自法典） 和 审美组（D/E/F，行业风格借鉴）。所有主题通过 <body data-theme="X"> 切换，通过 CSS 变量级联无重渲染生效，刷新页面从 localStorage 恢复。
| ID | 主题名 | 子标签 | 组别 | accent 主色 | bg-0 主基调 | 关键调性 |
|---|---|---|---|---|---|---|
| A | 玫瑰金主导 | Yin Gold · 品牌默认 | 品牌组 | var(--yin) 玫瑰金 |
夜蓝深色 | 暖色奢感、品牌名片 |
| B | 极光青主导 | Sheng Cyan · 工程师风 | 品牌组 | var(--sheng) 极光青 |
夜蓝深色 | 冷峻、数据可视化 |
| C | 米纸浅色 | Paper Light · 白天模式 | 品牌组 | 玫瑰金 | 米纸 #FBFAF6 | 白天高对比、文档友好 |
| D | 极简白 | Linear / Notion 风 | 审美组 | 中性蓝 | 纯白/浅灰 | 极简、文字驱动 |
| E | 赛博紫黑 | Cyberpunk DAW | 审美组 | 曦紫 | 接近纯黑 | 重霓虹、专业 DAW 感 |
| F | 毛玻璃 | Vision OS | 审美组 | 玫瑰金 | 半透明 | backdrop-filter: blur(28px) 毛玻璃，仅 F 主题启用 |
关键差异速查
--frosted毛玻璃：仅主题 F 设为blur(28px) saturate(180%)，其他主题为none或弱化值--hero-gradHero 渐变：每个主题自定义自己的三色涟漪渐变--node-bg流图节点底色：主题 D/E 与 A/B/C 差异最大（极简白 vs 赛博紫黑）--accent：A=玫瑰金 / B=极光青 / C=玫瑰金 / D=中性蓝 / E=曦紫 / F=玫瑰金
原则：切主题只切语义层（Layer 2），法典层和组件层永远不动。
3. 骨架布局五段式
所有 11 个 demo 共用同一份外壳骨架，只在中央画布区域差异化：
┌──────────────────────────────────────────────────────────────┐
│ ① MenuBar 28px traffic-lights · Logo · 9 菜单 · 主题 │
├──────────────────────────────────────────────────────────────┤
│ ② ToolBar 44px 4 toolbar-group · 搜索 ⌘K │
├──────────────────────────────────────────────────────────────┤
│ ③ MainTabs 38px XiStudio · XiForge · XiTune · XiProbe │
│ ④ SubTabs 32px 随主 tab 联动（4 / 3 / 3 / 4 子页） │
├────────┬────────────────────────────────┬────────────────────┤
│ │ │ │
│ ⑤左栏 │ ⑥ 中央画布（每个 tab │ ⑦ 右栏 │
│ 240px │ 独立组件，唯一差异） │ 320px │
│ │ │ │
│ │ ⑧ BottomPanel 220px (跨 tab 共享) │
├────────┴────────────────────────────────┴────────────────────┤
│ ⑨ StatusBar 24px 左侧元数据 · 右侧 LED/状态 │
└──────────────────────────────────────────────────────────────┘
3.1 关键尺寸表
| 区域 | 高度 / 宽度（默认） | 1280px 断点收窄 |
|---|---|---|
| MenuBar | 28px | — |
| ToolBar | 44px | — |
| MainTabs | 38px | — |
| SubTabs | 32px | — |
| 顶栏合计 | 142px | — |
| 左栏 | 240px | 220px |
| 右栏 | 320px | 280px |
| BottomPanel | 220px | — |
| StatusBar | 24px | — |
3.2 容器网格
.workspace-shell {
display: grid;
grid-template-columns: 240px 1fr 320px;
height: 100%; /* 父级 .body-wrap 用 absolute 让出底部 220px */
}
@media (max-width: 1280px) {
.workspace-shell { grid-template-columns: 220px 1fr 280px; }
}
3.3 z-index 层级
| 层级 | 用途 |
|---|---|
| 1 ~ 10 | 普通文档流 |
| 50 ~ 99 | Tuning 浮窗（每个 +1，最近打开置顶） |
| 100 ~ 149 | popover / dropdown（主题选择、下拉菜单） |
| 150 ~ 199 | 辅助产品悬浮窗（XiCal/XiMic/XiBox） |
| 200 ~ 299 | 命令面板 (⌘⇧P) |
| 999 | Toast 提示、模态遮罩 |
使用
z-counter计数器递增，确保后开浮窗永远在最前。
4. 组件库（Component Class 清单）
| 组件类 | 角色 | 关键样式 | 复用范围 |
|---|---|---|---|
.menubar |
顶栏第 1 行 | backdrop-filter: var(--frosted) + 28px 高 |
11 个页面 |
.toolbar |
顶栏第 2 行 | 44px + 4 个 .toolbar-group 圆角组 |
11 个页面 |
.main-tabs |
主 tab pill 胶囊 | border-radius: 999px 激活态实色 accent |
11 个页面 |
.sub-tabs |
子 tab 下划线 | border-bottom: 2px solid var(--accent) 激活 |
11 个页面 |
.panel-left / .panel-right |
三栏侧边 | --panel-bg + 内含 .sidebar-tabs |
11 个页面 |
.sidebar-tab |
侧栏 tab 行 | hover 浅色、active 加左侧 accent 竖条 | 左/右栏 |
.workspace-shell |
三栏 grid 容器 | 240/1fr/320，1280px 断点收窄 | 11 个页面 |
.bottom-panel |
底部跨 tab 面板 | position: absolute 220px + 7 个 tab |
11 个页面 |
.statusbar |
底部状态栏 | 24px + 左/右两区 | 11 个页面 |
.tuning-dialog |
Tuning 浮窗 | --radius-lg 14px + --mac-shadow-lg + traffic-lights 标题栏 |
跨 tab 多开 |
.aux-window |
辅助产品悬浮窗 | 同上但默认右下角、不入托盘 | XiCal/XiMic/XiBox |
.traffic-lights |
红黄绿三色按钮 | 12px 圆 × 3，hover 加暗叠 | 所有浮窗、对话框 |
.scope-card |
示波器卡片 | --radius-md + ECharts/SVG 嵌入 |
仿真页 4 联屏 |
.toolbar-group |
工具栏圆角分组 | --radius-md + 内嵌按钮无边框 |
ToolBar |
.pill |
状态/标签胶囊 | border-radius: 999px + 浅色底 |
全局 |
.btn-primary |
主按钮 | --accent 实色 + --accent-fg 文字 |
全局 |
.command-palette |
⌘⇧P 命令面板 | 居中 + --mac-shadow-lg + 毛玻璃 |
全局 |
.theme-popover |
主题选择弹层 | 6 卡网格 + 当前态高亮 | MenuBar |
通用样式约定
- 圆角：小元素
--radius-sm、卡片--radius-md、浮窗--radius-lg、Hero--radius-xl - 阴影：tag/按钮
--mac-shadow-sm、卡片/popover--mac-shadow-md、浮窗/命令面板--mac-shadow-lg - 边框：普通用
var(--line)，弱化用var(--line-soft) - 焦点环：
*:focus-visible { box-shadow: var(--focus-ring); }用品牌色而非系统蓝
5. macOS 设计语言 9 个关键点
这 9 点是"一眼看到 macOS 味"的判定标准，缺一不可：
| # | 设计点 | 实现要点 | 反例 |
|---|---|---|---|
| 1 | 4 级圆角阶梯 | --radius-sm/md/lg/xl = 6/10/14/20px |
全用 4px 锐角 |
| 2 | 毛玻璃半透明 | backdrop-filter: var(--frosted) 主题 F 启用 |
全实色背景 |
| 3 | 红黄绿 traffic-lights | 12px 圆 × 3，所有窗口/浮窗左上 | Windows 风的 X 关闭按钮 |
| 4 | SF Pro 字体栈 | -apple-system, BlinkMacSystemFont, "SF Pro Text", ... |
Arial / sans-serif |
| 5 | emoji 占位 SFSymbols 风图标 | 📄📂💾⚙▶■⚡↶↷🎚🔍🚀 | Material Icons / Bootstrap Icons |
| 6 | 滚动条 hover 才显 | *:hover::-webkit-scrollbar-thumb |
永远显示的粗滚动条 |
| 7 | 按钮按下缩放 | button:active { transform: scale(0.97); } + 80ms ease |
按下无反馈 |
| 8 | 品牌色焦点环 | *:focus-visible { box-shadow: var(--focus-ring); } |
系统默认蓝色 outline |
| 9 | 主 tab Pill 胶囊 | border-radius: 999px 激活态填充 accent 实色 |
矩形带下划线的 tab |
6. 主 Tab × 子 Tab × License 隔离矩阵
┌──────────────────────────────────────────────────────────────┐
│ 4 个主 tab × N 个子 tab，未授权 tab 灰显加 🔒 不可点击 │
├──────────────────────────────────────────────────────────────┤
│ XiStudio (L4 · studio-pro) → flow / tune / sim / deploy │
│ XiForge (L4 · forge-pro) → design / source / sim │
│ XiTune (L2 · tune-basic) → chain / curve / abx │
│ XiProbe (L2 · probe-basic) → freq / thd / snr / batch │
└──────────────────────────────────────────────────────────────┘
- 代码层隔离：每个主 tab = 一个
() => import(...)异步 chunk，未授权用户根本不下载该 tab 的 JS - 路由守卫：
router.beforeEach检查to.meta.license，不通过则showToast拦截 - VST 开发场景：用户
tiers=['forge-pro']→ 启动默认重定向/xiforge，其他 3 tab 全灰显
7. 核心交互模式
7.1 Tuning 多开浮窗（最核心）
节点双击 → useTuningManager.open(id, title, Component, props, fromEl)
→ 全局 reactive Map<id, TuningInstance>
→ <TuningContainer> Teleport 到 body 渲染所有打开浮窗
→ 跨 tab 持续存在（切主 tab 不关）
→ 黄色 traffic 最小化进 BottomPanel 托盘（不销毁）
→ 红色 traffic 关闭（销毁）
→ 多开错位 30px 阶梯 + zIndex 递增置顶
复用守则：所有 *TuningDialog.vue（GEQ/PEQ/Mixer/Limiter ... 12 个）只渲染内容，标题栏/拖拽/traffic-lights 统一由 TuningDialogShell.vue 接管。
7.2 主题切换
点击 🎨 → ThemePopover 6 卡网格
→ 点击 → useThemeStore.setTheme('B')
→ body.setAttribute('data-theme', 'B')
→ CSS 变量级联（无重渲染，毫秒级）
→ 写 localStorage 'xistudio.v3.preferences.v1'
→ showToast 提示
7.3 命令面板 + 全局快捷键
| 快捷键 | 行为 |
|---|---|
Ctrl+1/2/3/4 |
切主 tab |
Ctrl+K T |
主题选择 |
Ctrl+Shift+P |
命令面板 |
F7 / F5 / Shift+F5 |
编译 / 运行 / 停止 |
Ctrl+S |
保存 |
Esc |
关闭所有浮层 |
所有命令通过 registerCommand() 注册到全局表，命令面板 ⌘⇧P 可模糊搜索调用。
7.4 状态变更链路（举例：切主 tab）
点击主 tab
→ router.push('/xiforge')
→ MainTabs 监听 useRoute 更新 active
→ 路由懒加载 XiForgeWorkspace（License 检查 → 渲染）
→ SubTabs 自动渲染 children
→ BottomPanel 计算 showCodeTab=true（仅 xiforge）
→ useTuningManager 不变（浮窗跨 tab 持续）
→ showToast('已切换到 XiForge')
8. 复用与红线
✅ 可做
- 引用
var(--accent)/var(--bg-0)/var(--radius-md)等所有 Layer ⅔ 变量 - 新增组件类，但内部色值/尺寸必须通过变量
- 在
[data-theme="X"]块中扩展新变量（前提是法典层不动）
❌ 不可做（红线）
- ❌ 修改
--yin / --xi / --sheng / --night-* / --L0~L5任何 hex 值（brand-color-system v1.2 法典） - ❌ 在组件 CSS 里直接写
#D4A574/rgb(...)等硬编码 - ❌ 引入 Material Icons / Bootstrap Icons 等非 SFSymbols 风图标库
- ❌ 用 Arial/Roboto 替换 SF Pro 字体栈
- ❌ 改动 9 个 macOS 关键点中的任意一个
- ❌ 在
*TuningDialog.vue内部保留独立标题栏/关闭按钮（必须由 Shell 接管） - ❌ 让 z-index 跨层（如把 popover 设到 999 与 toast 抢位）
9. demo → 生产映射速查
| demo 行号位置 | 生产文件位置 | 对应章节 |
|---|---|---|
| L14–46 法典 token | src/styles/tokens.css |
spec §1.2 |
| L51–217 6 主题 | src/styles/themes.css |
spec §1.3 |
| L228–262 macOS 全局 | src/styles/macos.css |
spec §2 |
| L304–388 菜单栏 | src/components/shell/MenuBar.vue |
spec §3.2 |
| L390–446 工具栏 | src/components/shell/ToolBar.vue |
spec §3.3 |
| L450–500 主 tab | src/components/shell/MainTabs.vue |
spec §4.3 |
| L502–532 子 tab | src/components/shell/SubTabs.vue |
spec §4.4 |
| L535–662 三栏 | WorkspaceShell + LeftSidebar + RightInspector |
spec §5 |
| L668–784 底部 | src/components/shell/BottomPanel.vue |
spec §6 |
| L800–906 Tuning 浮窗 | src/components/tuning/TuningDialogShell + Container |
spec §7 |
详细行号→文件→Vue 组件对应表见
v3-implementation-spec.md附录 A，文件创建命令清单见附录 B。
10. 落地优先级（来自 roadmap §10 决议）
用户已拍板 方案 B 深完整型 · 6 周排期：
| 周 | 产物 |
|---|---|
| W1 | XiStudio 4 子 tab demo（graph / tuning-view / simulation / deploy） |
| W2 | XiForge 3 子 tab demo（design / source / sim） |
| W3 | XiTune 3 + XiProbe 前 2 |
| W4 | XiProbe 后 2 + 空/错/加载态附录 |
| W5 | spec v1.0 重写（基于全量 14 demo 反推） |
| W6 | 缓冲整改 + 全量回归 |
当前进度（2026-05-17）：W1–W3 的 11 个 v3-full-* 已完成 + commit 推送（详见 v0.8 迭代记录）。
附录 · 一句话总览
XiStudio v3 是用 macOS 设计语言重新组织过的 VSCode/Figma 风格工作台，外壳是统一的，灵魂是 6 主题切换 + Tuning 多开 + License 隔离，11 个 demo 是同一具骨架穿不同衣服。新人接手时记住三句话： 1. CSS 改动只动 Layer ⅔，禁碰法典 2. 新建组件用
var(--xxx)，不写 hex 3. 9 个 macOS 关键点缺一不可，少一个就不像 mac 了