boos/BoosAPI
2
0
Fork 2
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
cf732509998e9b6c1ad7993b3532edb37cfbaca8
BoosAPI/desktop/libs/markstream-vue/design/architecture.md
T
boos e0a5f57793 feat(desktop): embed BoosAPI Desktop client as a subproject 
Vendor the rebranded BoosAPI Desktop client (Tauri + Vue) into metapi as
a monorepo subdirectory under desktop/. Source only — node_modules,
dist, Cargo target and the upstream .git history are excluded.

desktop/ keeps its own independent Cargo workspace (desktop/src-tauri
with crates/*); it is not part of the backend boosapi crate, so a
`cargo check` at the metapi root still compiles only the backend. Build
the desktop app from desktop/src-tauri per desktop/README.md.

Note: app icons are still placeholder assets pending the final BoosAPI
logo. The updater signing keys live outside the repo and are not
included.
2026-06-22 11:32:57 +08:00

522 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 样式架构方案
> 核心决策：**带默认样式 + CSS 变量全量可定制**，非 headless。
> shadcn 兼容：继承宿主变量，不覆盖；无宿主时回退到内置默认值。
---
## 设计原则
1. **开箱即用** — 引入即有完整合理的 Markdown 渲染样式
2. **变量换肤** — 用户只需覆盖 CSS 变量即可定制全部视觉表现
3. **零硬编码** — 组件内不允许出现硬编码的色值、间距等魔法数字
4. **Light/Dark 内建** — 两套主题开关切换，暗色模式完整覆盖所有组件
5. **不污染宿主** — 所有样式限定在 `.markstream-vue` 作用域内
6. **不覆盖宿主** — 不重定义 shadcn 同名变量，通过继承 + 回退兼容
---
## 变量不冲突策略
### 问题
如果我们在 `.markstream-vue` 上直接定义 `--background`，会覆盖宿主从 `:root` 继承下来的值：
```
宿主 :root { --background: 210 20% 98% } ← 用户自定义的暖灰
我们 .markstream-vue { --background: 0 0% 100% } ← 覆盖成了纯白 ❌
```
### 解决方案：Bridge Tokens
引入 `--ms-*` 前缀的桥接层，用 `var()` 继承宿主变量，未定义时回退到默认值：
```css
.markstream-vue {
--ms-background: var(--background, 0 0% 100%);
/* ↑ 宿主有则用宿主的 ↑ 没有则用回退值 */
}
```
**shadcn 宿主**：
```
:root { --background: 210 20% 98% } ← 宿主定义
└─ .markstream-vue 继承 --background = 210 20% 98%
└─ --ms-background: var(--background, 0 0% 100%)
= 210 20% 98% ✅ 宿主主题穿透生效
```
**独立使用（无 shadcn）**：
```
:root 未定义 --background
└─ .markstream-vue 未继承到 --background
└─ --ms-background: var(--background, 0 0% 100%)
= 0 0% 100% ✅ 回退值生效，开箱即用
```
---
## 分层架构
```
┌──────────────────────────────────────────────┐
│ Layer 4: Dark Theme │ 仅覆盖 Layer 1 bridge + ext 的回退值
│ .dark .markstream-vue { --ms-bg: var(...) } │
├──────────────────────────────────────────────┤
│ Layer 3: Component Styles │ 引用 Layer 2 变量，不允许硬编码
│ .heading { color: var(--blockquote-fg) } │
├──────────────────────────────────────────────┤
│ Layer 2: Semantic Tokens │ 组件级变量，引用 Layer 1
│ --code-bg: hsl(var(--ms-background)); │
├──────────────────────────────────────────────┤
│ Layer 1: Base Tokens │
│ ├─ Bridge (--ms-*): 继承 shadcn + 回退 │
│ └─ Extension (--*): 本项目独有 │
└──────────────────────────────────────────────┘
```
---
## Layer 1: Base Tokens
### 1.1 Bridge Tokens（`--ms-*`，继承 shadcn 同名变量）
> 内部桥接用。用户定制时直接覆盖 shadcn 变量名（如 `--background`）或覆盖 semantic token 即可。
#### Light（默认）
```css
.markstream-vue {
/* ── 背景 / 前景 ── */
--ms-background: var(--background, 0 0% 100%);
--ms-foreground: var(--foreground, 222.2 84% 4.9%);
/* ── 弱化 ── */
--ms-muted: var(--muted, 210 40% 96.1%);
--ms-muted-foreground: var(--muted-foreground, 215.4 16.3% 46.9%);
/* ── 次要 ── */
--ms-secondary: var(--secondary, 210 40% 96.1%);
--ms-secondary-foreground: var(--secondary-foreground, 222.2 47.4% 11.2%);
/* ── 强调 ── */
--ms-accent: var(--accent, 210 40% 96.1%);
--ms-accent-foreground: var(--accent-foreground, 222.2 47.4% 11.2%);
/* ── 主要操作 ── */
--ms-primary: var(--primary, 222.2 47.4% 11.2%);
--ms-primary-foreground: var(--primary-foreground, 210 40% 98%);
/* ── 危险 ── */
--ms-destructive: var(--destructive, 0 84.2% 60.2%);
--ms-destructive-foreground: var(--destructive-foreground, 210 40% 98%);
/* ── 边框 / Focus ── */
--ms-border: var(--border, 214.3 31.8% 91.4%);
--ms-ring: var(--ring, 222.2 84% 4.9%);
/* ── 弹出层 ── */
--ms-popover: var(--popover, 0 0% 100%);
--ms-popover-foreground: var(--popover-foreground, 222.2 84% 4.9%);
/* ── 圆角 ── */
--ms-radius: var(--radius, 0.5rem);
}
```
#### Dark
```css
.dark .markstream-vue,
.markstream-vue.dark {
--ms-background: var(--background, 222.2 84% 4.9%);
--ms-foreground: var(--foreground, 210 40% 98%);
--ms-muted: var(--muted, 217.2 32.6% 17.5%);
--ms-muted-foreground: var(--muted-foreground, 215 20.2% 65.1%);
--ms-secondary: var(--secondary, 217.2 32.6% 17.5%);
--ms-secondary-foreground: var(--secondary-foreground, 210 40% 98%);
--ms-accent: var(--accent, 217.2 32.6% 17.5%);
--ms-accent-foreground: var(--accent-foreground, 210 40% 98%);
--ms-primary: var(--primary, 210 40% 98%);
--ms-primary-foreground: var(--primary-foreground, 222.2 47.4% 11.2%);
--ms-destructive: var(--destructive, 0 62.8% 30.6%);
--ms-destructive-foreground: var(--destructive-foreground, 210 40% 98%);
--ms-border: var(--border, 217.2 32.6% 17.5%);
--ms-ring: var(--ring, 212.7 26.8% 83.9%);
--ms-popover: var(--popover, 222.2 84% 4.9%);
--ms-popover-foreground: var(--popover-foreground, 210 40% 98%);
}
```
**工作原理**：
- shadcn 宿主有 `.dark { --background: X }` → `var(--background, fallback)` 取 X → 宿主暗色穿透
- 独立使用，无 `--background` → 取 fallback 中的暗色值 → 内置暗色生效
### 1.2 Extension Tokens（本项目独有，无冲突风险）
> 这些变量名 shadcn 不存在，直接定义即可。
#### Light
```css
.markstream-vue {
/* ── 语义色 ── */
--ms-info: 217 91% 60%; /* 信息/备注 (#448aff) */
--ms-info-foreground: 210 40% 98%;
--ms-success: 168 100% 37.5%; /* 成功/提示 (#00bfa5) */
--ms-success-foreground: 210 40% 98%;
--ms-warning: 34 100% 50%; /* 警告 (#ff9100) */
--ms-warning-foreground: 0 0% 100%;
/* ── Diff ── */
--ms-diff-added: 174 60% 51%; /* 新增 (#14b8a6) */
--ms-diff-removed: 350 100% 60%; /* 删除 (#ff3658) */
/* ── 其他 ── */
--ms-highlight: 54 100% 62%; /* 文本高亮 */
--ms-highlight-foreground: 0 0% 0%;
--ms-link: 212 100% 42%; /* 链接色 (#0366d6) */
/* ── 排版 ── */
--ms-font-sans: ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji";
--ms-font-mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace;
}
```
#### Dark
```css
.dark .markstream-vue,
.markstream-vue.dark {
--ms-diff-added: 174 72% 70%; /* 暗色更亮 (#5eead4) */
--ms-diff-removed: 0 92% 82%; /* 暗色更柔 (#fda4af) */
--ms-highlight: 54 80% 42%; /* 暗色降低亮度 */
--ms-highlight-foreground: 0 0% 100%;
--ms-link: 213 94% 68%; /* 暗色更亮链接 */
/* info / success / warning 在暗色下保持不变，仍然醒目 */
}
```
### 1.3 圆角推算规则
```
sm = calc(var(--ms-radius) - 2px) → 6px
base = var(--ms-radius) → 8px (0.5rem)
md = calc(var(--ms-radius) + 2px) → 10px
lg = calc(var(--ms-radius) + 4px) → 12px
full = 9999px
```
---
## Layer 2: Semantic Tokens
全部引用 Layer 1 的 `--ms-*` 变量。Dark 模式下 Layer 1 变化 → Layer 2 自动跟随，无需重复定义。
```css
.markstream-vue {
/* ── 行内代码 ── */
--inline-code-bg: hsl(var(--ms-secondary));
--inline-code-fg: hsl(var(--ms-foreground));
--inline-code-border: hsl(var(--ms-border) / 0.9);
/* ── 代码块 ── */
--code-bg: hsl(var(--ms-background));
--code-fg: hsl(var(--ms-foreground));
--code-border: hsl(var(--ms-border));
--code-header-bg: hsl(var(--ms-muted));
--code-selection-bg: hsl(var(--ms-accent) / 0.3);
--code-line-number: hsl(var(--ms-muted-foreground));
/* ── 代码块操作栏 ── */
--code-action-fg: hsl(var(--ms-muted-foreground));
--code-action-hover-bg: hsl(var(--ms-accent));
--code-action-hover-fg: hsl(var(--ms-accent-foreground));
--code-action-active-bg: hsl(var(--ms-primary));
--code-action-active-fg: hsl(var(--ms-primary-foreground));
/* ── Diff ── */
--diff-added-fg: hsl(var(--ms-diff-added));
--diff-removed-fg: hsl(var(--ms-diff-removed));
--diff-added-bg: hsl(var(--ms-diff-added) / 0.1);
--diff-added-inline-bg: hsl(var(--ms-diff-added) / 0.2);
--diff-removed-bg: hsl(var(--ms-diff-removed) / 0.1);
--diff-removed-inline-bg: hsl(var(--ms-diff-removed) / 0.2);
/* ── 引用块 ── */
--blockquote-border: hsl(var(--ms-border));
--blockquote-fg: hsl(var(--ms-foreground));
/* ── 提示框 (Admonition) ── */
--admonition-bg: hsl(var(--ms-muted));
--admonition-border: hsl(var(--ms-border));
--admonition-fg: hsl(var(--ms-foreground));
--admonition-muted: hsl(var(--ms-muted-foreground));
--admonition-header-bg: hsl(var(--ms-muted) / 0.5);
--admonition-note: hsl(var(--ms-info));
--admonition-tip: hsl(var(--ms-success));
--admonition-warning: hsl(var(--ms-warning));
--admonition-danger: hsl(var(--ms-destructive));
/* ── 表格 ── */
--table-border: hsl(var(--ms-border));
--table-header-bg: hsl(var(--ms-muted));
--table-header-fg: hsl(var(--ms-foreground));
--table-row-hover-bg: hsl(var(--ms-accent) / 0.5);
/* ── 链接 ── */
--link-color: hsl(var(--ms-link));
/* ── 列表 ── */
--list-marker: hsl(var(--ms-border));
--list-counter-marker: hsl(var(--ms-muted-foreground));
/* ── 分割线 ── */
--hr-border: hsl(var(--ms-border));
/* ── 高亮 ── */
--highlight-bg: hsl(var(--ms-highlight));
--highlight-fg: hsl(var(--ms-highlight-foreground));
/* ── 脚注 ── */
--footnote-border: hsl(var(--ms-border));
/* ── Tooltip ── */
--tooltip-bg: hsl(var(--ms-popover));
--tooltip-fg: hsl(var(--ms-popover-foreground));
--tooltip-border: hsl(var(--ms-border));
/* ── Modal ── */
--modal-overlay: hsl(0 0% 0% / 0.7);
--modal-bg: hsl(var(--ms-popover));
--modal-fg: hsl(var(--ms-popover-foreground));
/* ── 图表容器 (Mermaid / D2 / Infographic) ── */
--diagram-bg: hsl(var(--ms-muted));
--diagram-border: hsl(var(--ms-border));
--diagram-header-bg: hsl(var(--ms-muted));
/* ── 数学公式 ── */
--math-fg: hsl(var(--ms-foreground));
/* ── 加载态 ── */
--loading-spinner: hsl(var(--ms-muted-foreground));
--loading-shimmer: hsl(var(--ms-muted) / 0.5);
/* ── 图片 ── */
--image-placeholder-bg: hsl(var(--ms-muted));
/* ── Focus ring ── */
--focus-ring: hsl(var(--ms-ring));
}
```
**Dark 模式下无需重复定义 Layer 2** — 因为 Layer 1 的 `--ms-*` 值变了，这里自动跟随。
---
## Layer 3: Component Styles
组件中只引用 Layer 2 语义变量：
```css
/* ❌ 之前 */
.blockquote { border-left: 0.25rem solid #e2e8f0; }
.admonition-note { border-left-color: #448aff; }
.highlight-node { background-color: #ffff00; }
/* ✅ 之后 */
.blockquote { border-left: 0.25rem solid var(--blockquote-border); }
.admonition-note { border-left-color: var(--admonition-note); }
.highlight-node { background: var(--highlight-bg); }
```
---
## 暗色模式统一方案
**去掉组件级 `.is-dark` CSS**，统一为：
```
之前：isDark prop → 每个组件 .is-dark → 30+ 组件各自覆盖 CSS 变量
之后：.dark 类 → Layer 1 bridge 回退值切换 → Layer 2 自动跟随 → 全部组件适配
```
**保留 `isDark` prop** 仅用于 JS 逻辑（不用于 CSS）：
- Monaco Editor 主题名切换
- Mermaid 主题名切换
- `prefers-color-scheme` 检测兜底
### CodeBlockNode `.is-dark` 例外
CodeBlockNode 保留 `.is-dark` CSS 块。此处 `.is-dark` 的语义是**"编辑器表面为暗色"**
（由 Monaco 主题检测 `resolvedSurfaceIsDark` 决定），与页面级 `.dark` 无关。
- 一个亮色页面上可以出现暗色主题的代码块
- `.is-dark` 块包含 ~15 个 diff 视图的阴影/透明度/渐变差异值
- 这些值已全部引用 `--ms-*` 语义令牌，只是 opacity 系数不同
### Admonition header-bg 例外
提示框标题背景需要在 dark 下使用更高透明度（6% → 12%），因此
`--admonition-*-header-bg` 在 `.dark` 区块中重新定义。这是 Layer 2 中
唯一需要 dark 覆盖的语义令牌。
---
## shadcn 兼容矩阵
| 变量来源 | 我们的处理 | 用户如何定制 |
|---|---|---|
| shadcn 同名（`--background` 等 14 个） | `--ms-*` 桥接继承 + 回退 | 在 `:root` 设置 shadcn 变量，自动穿透 |
| 本项目独有（`--ms-info` 等 8 个） | 直接定义在 `.markstream-vue` | 在 `.markstream-vue` 上覆盖 |
| 组件语义（`--code-bg` 等 ~35 个） | 引用 `--ms-*`，定义一次 | 在 `.markstream-vue` 上覆盖 |
### shadcn 未采用（本项目不需要）
| Token | 原因 |
|---|---|
| `--card` / `--card-foreground` | 无 card 组件 |
| `--input` | 无输入框 |
| `--sidebar-*` | 无侧边栏 |
| `--chart-*` | Mermaid 自带主题 |
### 本项目扩展（shadcn 没有）
| Token | 用途 |
|---|---|
| `--ms-info` / `--ms-success` / `--ms-warning` | Admonition 语义色 |
| `--ms-diff-added` / `--ms-diff-removed` | Diff 视图 |
| `--ms-highlight` / `--ms-highlight-foreground` | `==高亮==` 语法 |
| `--ms-link` | 链接色 |
---
## 当前控件清单
| 控件 | 出现组件 | 涉及 tokens |
|---|---|---|
| 操作按钮（复制/折叠/全屏/导出） | CodeBlock, Mermaid, D2, Infographic, Admonition | `--code-action-*`, `--focus-ring` |
| 字号调节按钮组 | CodeBlock, MarkdownCodeBlock | `--code-action-*` |
| 模式切换（Preview/Source） | CodeBlock, Mermaid, D2, Infographic | `--code-action-active-*` |
| 缩放控制 | Mermaid, Infographic | `--code-action-*` |
| Tooltip | 全局 | `--tooltip-*` |
| Modal | CodeBlock, Mermaid, Infographic | `--modal-*` |
| Checkbox（只读） | CheckboxNode | `--ms-foreground` |
| Spinner | Image, Table, MathBlock | `--loading-spinner` |
| Shimmer 骨架屏 | CodeBlock, Table | `--loading-shimmer` |
| 错误态 | ImageNode | `--ms-destructive` |
| 可点击引用 | FootnoteRef, ReferenceNode | `--link-color` |
---
## 用户定制示例
### 场景 1：shadcn 项目（零配置接入）
```js
// 只需引入样式，shadcn 变量自动穿透
import 'markstream-vue/dist/index.css'
```
宿主 `:root` 上的 `--background`、`--foreground` 等自动继承进 `.markstream-vue`。
如需补充 Markdown 扩展色：
```css
.markstream-vue {
--ms-info: 217 91% 60%;
--ms-success: 142 71% 45%;
--ms-link: 221 83% 53%;
}
```
### 场景 2：独立项目，换整体配色
```css
/* 方式 A：覆盖 bridge 识别的 shadcn 变量名 */
:root {
--background: 0 0% 98%;
--foreground: 240 10% 10%;
--border: 240 5% 85%;
}
/* 方式 B：直接覆盖 --ms-* bridge token */
.markstream-vue {
--ms-background: 0 0% 98%;
--ms-foreground: 240 10% 10%;
--ms-border: 240 5% 85%;
}
```
### 场景 3：只改代码块（覆盖 semantic token）
```css
.markstream-vue {
--code-bg: #1e1e2e;
--code-fg: #cdd6f4;
--code-border: transparent;
}
```
### 场景 4：只改提示框色彩
```css
.markstream-vue {
--ms-info: 221 83% 53%;
--ms-success: 142 71% 45%;
--ms-warning: 38 92% 50%;
--ms-destructive: 0 72% 51%;
}
```
---
## 已知边界情况
**shadcn 宿主 + 仅对 markstream-vue 启用 dark**：
```html
<!-- 宿主全局 light，但 markstream-vue 想用 dark -->
<div class="markstream-vue dark">...</div>
```
此时宿主的 light `--background` 仍会继承进来，bridge 的 dark 回退值不会生效。
**解决**：shadcn 宿主应在文档级切换 `.dark`，或通过覆盖 semantic token 单独控制。
---
## 迁移策略
分步进行，每步可独立验证：
| 阶段 | 内容 | 影响范围 |
|---|---|---|
| 1 | 定义 Bridge Tokens + Extension Tokens（Layer 1） | 仅新增变量，不破坏现有 |
| 2 | 定义 Semantic Tokens（Layer 2），引用 `--ms-*` | 仅新增变量，不破坏现有 |
| 3 | 逐组件替换硬编码值为 Semantic Token 引用 | 逐组件改，可逐个验证 |
| 4 | 补全 Dark 的 Bridge Token 回退值 | 暗色模式完整 |
| 5 | 移除组件内 `.is-dark` CSS 覆盖 | 简化暗色逻辑 |
| 6 | 清理：删除废弃变量、统一动画变量 | 最终打磨 |
Reference in New Issue View Git Blame Copy Permalink