Format Demo · Index · 4 Styles Comparison
格式 Demo · 4 套风格对比
Pick one. Lock the format. Migrate.
同一篇 Source 模块文章 · 4 种排版可能性 · 你来挑哪一套
4
套风格
17
共有章节
12
Admonition 类型
6
Mermaid 图类型
格式 Demo · 4 套风格对比
本入口的作用
- 这是 Step 3「文档格式规范」正式定稿前的视觉决策环节
- 我们准备了 4 份完全相同的正文内容(XiStudio Source 模块运行 demo),分别套用 4 种不同的样式
- 你浏览器对照看完后,挑中其中 1 套,我们就以那套为基础写正式
format-spec.md进入 Step 3 定稿 - 4 套都不动
mkdocs.yml、overrides/main.html、xiyin-brand.css,风格隔离完全靠每篇 demo 顶部内联<style>+<div class="xy-style-x">包裹
1. 4 套风格速览
| 套号 | 名称 | 参考站 | 一句话定位 | 文件 |
|---|---|---|---|---|
| 0 | 现有 Xiyin 风格(基线) | 当前主题 | 仪式感 · 三色法典 · Hero 叙事 · Domain 卡章节 | 00-format-demo-current.md |
| A | Stripe 风 | Stripe / Vercel / Linear Docs | 克制 · 浅底 · 玫瑰金保留 · 紫色细线 | 01-format-demo-styleA-stripe.md |
| B | Linear/GitHub 风 | Linear / GitHub Engineering / Mintlify | 极简 · 高信息密度 · 灰阶 · 单色强调 | 02-format-demo-styleB-linear.md |
| C | Notion/Apple 风 | Notion / Apple Developer / Tailwind Docs | 柔和 · 卡片化 · 大留白 · 圆角阴影 | 03-format-demo-styleC-notion.md |
2. 元素差异详细对比
2.1 标题层级(H1 / H2 / H3)
| 元素 | 套 0 · 现有 | 套 A · Stripe | 套 B · Linear | 套 C · Notion |
|---|---|---|---|---|
| H1 | 深夜蓝 grid Domain 卡 + 三色顶线 + 章节号格 | 浅米白底 + 大字 + 紫色顶线 + 灰底线 | 无背景 + 大字 + 仅底部 1px 灰线 | 大字 36px + 玫瑰金渐变锚条(下方) |
| H2 | 深夜蓝 grid Domain 卡 + 三色顶线 | 浅灰底 + 内边距 + 左 4px 紫条 + 圆角 4px | 无背景 + 仅顶部 1px 灰线 + 字号阶梯 | 无背景 + 大字 26px + 字号阶梯 |
| H3 | 浅金渐变左晕染 + 左 3px 玫瑰金竖条 + 顶部 2px 三色线 | 无背景 + 左 8px 玫瑰金小圆点 | 无装饰 + 纯字号阶梯 | 玫瑰金小圆点 + 三色光晕(box-shadow) |
| 字体 | 衬线(思源宋体) | Inter + PingFang SC | Inter(紧凑) | SF Pro Display + apple-system |
2.2 正文 / 行内元素
| 元素 | 套 0 | 套 A | 套 B | 套 C |
|---|---|---|---|---|
| 行高 | 默认 1.7 | 1.75 | 1.65(紧凑) | 1.85(舒展) |
| 字号 | 14px | 14px | 14.5px | 16px |
| 行内代码 | 浅金底 + 玫瑰金描边 | 浅紫底 + 紫字 + 紫描边 | 浅灰底 + 深字 + 无描边 | 浅金底 + 玫瑰金字 + 圆角 6px |
| 链接 | 玫瑰金虚线下划线 | 紫色实线 + 玫瑰金 hover | 紫色 + 无下划线 + hover 下划线 | 玫瑰金实色 + 无下划线 + hover 下划线 |
| 引用 blockquote | 三色渐变左条 + 暖底 | 浅紫底 + 紫左条 + 圆角 | 灰色斜体 + 灰左条 + 无背景 | 玫瑰金左条 4px + 浅暖底 + 圆角 12px |
2.3 代码块
| 元素 | 套 0 | 套 A | 套 B | 套 C |
|---|---|---|---|---|
| 底色 | 夜蓝 #0B1C2E |
极深蓝 #1A2332 |
极深 #050812 |
中蓝 #14283F |
| 边框 | 玫瑰金 3px 左条 | 浅灰 1px 边框 | 无边框 + 1px 阴影 | 无边框 + 4px 大阴影 |
| 顶线 | 三色渐变 2px | 紫色 2px | 紫色 1px | 玫瑰金渐变 3px + 圆角 |
| 圆角 | 6px | 6px | 6px | 12px |
2.4 表格
| 元素 | 套 0 | 套 A | 套 B | 套 C |
|---|---|---|---|---|
| 外框 | 玫瑰金 3px 左条 + 灰边 + 浅阴影 | 浅灰 1px 边框 + 无阴影 | 无边框 + 无阴影 + 行底线 | 浅灰 1px 边框 + 大阴影 + 圆角 12px |
| 顶线 | 三色渐变 3px(由 patch.css A2) | 紫色 2px | 无 | 无 |
| 表头底 | 玫瑰金浅暖渐变(已是 A2) | 米白底 | 透明 | 浅暖渐变 |
| 表头字 | 深古铜金 + Inter + 12.5px + 字距 0.06em | 深字 + 13px + 无大写 | 灰字 + 12px + 大写 + 字距 0.04em | 深字 + 14px + 无大写 |
| 行 hover | 已移除 | 浅米白 | 极浅灰 | 浅金(rgba 0.04) |
2.5 Admonition
| 元素 | 套 0 | 套 A | 套 B | 套 C |
|---|---|---|---|---|
| 左条 | 极光青 4px(已统一) | 紫色 3px | 黑色 2px(warning/danger 紫) | 无左条 |
| 背景 | 浅极光青 rgba(.08) |
米白底 | 极浅灰底(无颜色区分) | 浅彩底按类型微差异(青 / 金 / 红 / 紫) |
| 标题 | 深极光青 + 中文 | 深紫 + 中文 | 大写 + 11px + 字距 + 紫图标 | 中文 + 15px + 颜色按类型 |
| 圆角 | 4px | 8px | 0(直角) | 14px |
| 类型区分 | 极光青统一 + 仅 icon 区分 | 极光青统一 + 仅 icon 区分 | 仅 warning/danger 用紫色 | 3 组色(成功 / 警告 / 错误)+ 浅彩底 |
2.6 Mermaid
| 元素 | 套 0 | 套 A | 套 B | 套 C |
|---|---|---|---|---|
| 画布底 | 夜蓝渐变 | 浅米白 | 极浅米白 | 浅米白 + 大阴影 |
| 左条 | 玫瑰金 3px | 紫色 3px | 无 | 无 |
| 顶线 | 三色 3px | 紫色 2px | 无 | 三色 2px |
| 节点色 | xyL 系列(品牌色保留) | xyL 系列保留 | xyL 系列保留 | xyL 系列保留 |
| 圆角 | 8px | 8px | 4px | 14px |
2.7 Tabs
| 元素 | 套 0 | 套 A | 套 B | 套 C |
|---|---|---|---|---|
| 激活态 | 玫瑰金 2px 底线 + 玫瑰金深字 | 紫色 2px + 紫字 | 紫色 + 紫字 + 加粗 | 玫瑰金 + 玫瑰金字 + 加粗 |
| 顶线 | 三色 3px | 紫色 2px | 无 | 玫瑰金渐变 2px |
| 底色 | 玫瑰金浅 6% | 米白 | 透明 + 底 1px 灰线 | 米白 + 圆角 12px |
3. 适用场景与受众建议
| 套号 | 最适合 | 不太适合 |
|---|---|---|
| 套 0 · 现有 | 公司战略材料 / 投资人材料 / L1A/L1B 旗舰文档 / 客户白皮书 | 长技术文档(章节卡片密集会显冗) |
| 套 A · Stripe | 对外开发者文档 / API 参考 / 客户集成指南 / Datasheet | 内部短交接文档(略显正式) |
| 套 B · Linear | 内部技术文档 / 模块迁移报告 / FAQ / 操作手册 | 对客户展示的旗舰物料(品牌识别度低) |
| 套 C · Notion | 用户手册 / 教程 / Tutorial / 长篇阅读型文档 | 高信息密度的参考文档(占屏空间大) |
4. 推荐意见(我的建议)
推荐组合方案 A · 单一定稿
选 套 A · Stripe 风 作为全站新基线,理由:
- ✅ 保留品牌识别:玫瑰金 + 紫色细线仍在,与 Hero / 全站三色一致
- ✅ 工程权威调性:Xisound 是 ToB 硬件公司,客户(车厂 / Tier1)看 Stripe 风更有"靠谱感"
- ✅ 中长技术文档友好:浅底 + 大行高比当前的 Domain 卡更适合长文阅读
- ✅ 改动最小:相对套 0 只是把 H1/H2 从深夜蓝 Domain 卡改为浅底 + 紫色细线,保留绝大多数现有 patch.css 规则
- ⚠️ 代价:Hero 的"仪式感叙事"在内部文档里会被弱化,但 L1A/L1B 旗舰文档 Hero 仍走品牌主题(因为模板独立渲染)
推荐组合方案 B · 分层定稿(更复杂但更精准)
按 frontmatter level 字段分配 4 套风格:
| level | 用什么风格 | 理由 |
|---|---|---|
| L1A 首页 | 套 0 · 现有 | 仪式感最强,首页就该惊艳 |
| L1B 旗舰 | 套 0 · 现有 | 客户白皮书 / 投资材料维持品牌识别 |
| L2 章节 | 套 A · Stripe | 工程权威,信息友好 |
| L3 内部 | 套 B · Linear | 极简高密度,内部读得快 |
| 教程类 | 套 C · Notion | 柔和大字,新人友好 |
实施成本:overrides/main.html 已经按 level 注入 body class,我们额外在 xiyin-extra.css 里 body.level-l2 { ... } 注入套 A 规则、body.level-l3 { ... } 注入套 B 规则即可,零侵入式分层
不推荐
选 套 B · Linear 作为全站基线 — 信息密度虽然好,但品牌识别度太弱,对外文档会失去"这是 Xisound"的辨识感。
5. 视觉对比要点(浏览器打开 4 个 tab 对照看)
打开 mkdocs serve 后,以下顺序看最有效:
- 第一遍 · 看 Hero:4 篇 Hero 视觉应该几乎一致(品牌共用模板)
- 第二遍 · 看 H1/H2 标题区:这是最大差异点,挑你最舒服的那种
- 第三遍 · 看代码块 + Tabs:工程师看长技术文档时眼睛主要落点
- 第四遍 · 看 Admonition 章节:看"成功 / 警告 / 错误"3 类视觉是否够辨识但又不花
- 第五遍 · 看 Mermaid 图章节:看图表风格是否与正文协调
- 第六遍 · 看暗色模式:点右上角太阳图标切换,4 套都做了暗色适配
6. 决策后的下一步
挑中风格后告诉我编号(0 / A / B / C),我会:
- 把那套 demo 的内联
<style>抽到docs/assets/stylesheets/xiyin-style-X.css - 写正式的
docs/D0-company/05-standards/format-spec.md(Step 3 输出) - 该 CSS 通过
mkdocs.yml: extra_css全站加载(或按方案 B 分层加载) - 把试点 6 commit 的 Source/Sink 文档改套上新风格作回归
- 进入 P0 全量迁移
7. 文件清单与 git 状态
7.1 文件清单(已落盘)
docs/D0-company/05-standards/format-demo/
├── README.md ← 你现在看的这份(对比表 + 推荐意见)
├── 00-format-demo-current.md ← 套 0 · 现有 Xiyin 风格(基线)
├── 01-format-demo-styleA-stripe.md ← 套 A · Stripe 风
├── 02-format-demo-styleB-linear.md ← 套 B · Linear/GitHub 风
└── 03-format-demo-styleC-notion.md ← 套 C · Notion/Apple 风
7.2 nav 临时入口
为了让 4 份 demo 出现在侧栏方便点击对比,临时在 mkdocs.yml 的「📖 旧目录」末尾追加:
- 📖 旧目录:
...
- 🎨 格式 Demo(待评审):
- 4 套对比说明: D0-company/05-standards/format-demo/README.md
- 套 0 · 现有 Xiyin: D0-company/05-standards/format-demo/00-format-demo-current.md
- 套 A · Stripe: D0-company/05-standards/format-demo/01-format-demo-styleA-stripe.md
- 套 B · Linear/GitHub: D0-company/05-standards/format-demo/02-format-demo-styleB-linear.md
- 套 C · Notion/Apple: D0-company/05-standards/format-demo/03-format-demo-styleC-notion.md
定稿后这个临时入口会撤掉,挑中的那套抽到 CSS 后正式落到 format-spec.md。
7.3 git 状态
- 当前分支:
feat/docs-migration-source-sink-pilot - 5 份新文件未 commit,等你浏览器看完决策后一并 commit
8. 浏览器预览
执行以下命令启动 dev 服务:
启动后访问:
format-demo · README · v0.1 · 2026-05-10 · Xisound AlgoDepartment