Format Spec Changelog · v1.0.1

文档格式规范变更日志 v1.0.1

10 条视觉决议沉淀 · 视觉对标 → 工程落地的桥梁

版本基线:format-demo-0-current.html v0.3(2026-05-11) · 适用于:5 份下游规范 + 全站 .md

文档格式规范变更日志 v1.0.1

本文档定位

角色:Step 3a(视觉对标 demo)→ Step 3b(工程规范落地)的桥梁文档
作用:把 nav-demo/format-demo-0-current.html 与已确认导航 Demo 上 10 条已用户确认的视觉决议,固化为可引用的工程规则
下游:md-writing-spec.md v2.0 / brand-color-system.md v1.2 / nav-display-spec.md 都会引用本文档作为视觉来源依据,而不是各自重写决议
不是:本文档不替代 md-writing-spec(MD 写法契约)和 brand-color-system(色板权威),它只是「为何这么改」的索引册

版本基线

视觉源文件:AlgoDepartment/06_docs/site-build/nav-demo/format-demo-0-current.html(v0.3 优化版,2026-05-11)
决议数量:10 条
审批状态:用户已最终确认(2026-05-11)
CSS 变量来源:docs/assets/stylesheets/xiyin-brand.css line 1-200(三色法典 + 产品 6 色 + Night/Pearl/Paper 中性色)

1. 10 条视觉决议总览表

#	决议主题	改前	改后	主要 CSS 类	下游规范
1	引言/箴言卡	标准 `<blockquote>` 与品牌脱节	`.xy-quote` 大金引号 + 浅金底 + 玫瑰金边	`.xy-quote` / `.xy-quote-content` / `.xy-quote-author` / `.xy-quote-nested`	md-writing-spec §5a
2	术语网格	定义列表 `<dl>` 视觉混乱	`.xy-glossary` 卡片化 + 层级 tag	`.xy-glossary` / `.xy-term` / `.xy-term-name` / `.xy-term-tag.l0/.l3/.l4`	md-writing-spec §7.2b
3	Admonition 12 类配色	12 类 admonition 全部一个色	按语义分 6 组配色	`.callout.info/.tip/.warning/.danger/.example/.quote` 等 12 类	md-writing-spec §5 + brand-color-system §3.4(新增)
4	Tabs 激活态	激活态颜色不明显	玫瑰金实色填充 + 白字 + 底部小三角	`.tab-active` + `::after` 三角	md-writing-spec §10
5	Subgraph 子图色	子图无视觉层级	浅产品色底(L1 浅青 / L3 浅金 / L4 浅紫)	`.xySgL0` ~ `.xySgL5`(已存在于 xiyin-mermaid.js)	md-writing-spec §9.3
6	甘特图	Mermaid 默认甘特视觉差,无法呈现品牌色	双轨:Mermaid gantt(简单) + `.xy-gantt` HTML 自绘(精致)	`.xy-gantt` / `.xy-gantt-bar.done/.active/.planned`	md-writing-spec §9.5
7	Mermaid 放大按钮	复杂图表难以查看细节	右上角 `⛶` 按钮 + 全屏 modal(支持 ESC)	`.xy-mermaid-zoom-btn` / `#xy-mermaid-modal`	nav-display-spec §6 + 新增 `xiyin-mermaid-zoom.js`
8	数学公式	KaTeX 未加载,arithmatex 是占位符	双轨:Unicode + HTML(简单) + KaTeX CDN(复杂)	`.xy-frac`(分数线) + `<sup>/<sub>`	md-writing-spec §13(新增) + mkdocs.yml extra_javascript
9	xy-stack 产品 6 色	层级栈无品牌色	L0-L5 各自层级背景 + 边框 + 徽章	`.xy-stack` / `.xy-stack-item.l0~.l5`	md-writing-spec §11(新增)
10 ⭐	Stripe 三栏布局(站点骨架)	mkdocs material 默认双栏视觉无品牌识别	Demo 1 · Stripe / Linear 风格:深色侧栏 260px / 主区 720px / 右 TOC 220px,玫瑰金接管 Stripe 紫	11 个 CSS 变量(`--xy-sidebar-* / --xy-main-* / --xy-stripe-*`) + `.md-sidebar--primary/secondary` 接管	nav-display-spec §3(新增 v1.0.1)

2. 决议详情:逐条沉淀

每条决议给出 4 个要素:改前问题 → 改后方案 → CSS 类与变量 → 作者写法示例。

决议 1 · `.xy-quote` 引言/箴言卡

改前问题 - Material 主题的 <blockquote>(> 写法)用的是中性灰边线 + 灰文字,与 Xiyin 三色法典完全脱节 - 引用经典语句、产品箴言、客户原话时,缺乏「仪式感」

改后方案 - 大金引号(80px Cormorant Garamond ::before)+ 浅金渐变底(paper-warm → paper)+ 玫瑰金左边线(4px solid var(--yin)) - 支持作者署名(.xy-quote-author)和嵌套引用(.xy-quote-nested)

CSS 类与变量(权威来源:xiyin-extra.css 待新增章节)

.xy-quote {
  position: relative;
  margin: 1.5rem 0;
  padding: 1.5rem 1.5rem 1.5rem 4rem;
  background: linear-gradient(135deg, var(--paper-warm), var(--paper));
  border-left: 4px solid var(--yin);
  border-radius: 4px;
}
.xy-quote::before {
  content: '"';
  position: absolute;
  left: 0.5rem;
  top: -0.5rem;
  font-family: 'Cormorant Garamond', 'Times New Roman', serif;
  font-size: 80px;
  color: var(--yin);
  opacity: 0.4;
  line-height: 1;
}
.xy-quote-content { font-size: 1.05rem; line-height: 1.7; }
.xy-quote-author {
  display: block;
  margin-top: 0.75rem;
  font-style: italic;
  color: var(--yin-deep);
  text-align: right;
}
.xy-quote-author::before { content: '— '; }
.xy-quote-nested {
  margin-top: 0.75rem;
  padding-left: 1rem;
  border-left: 2px dashed var(--line);
  opacity: 0.85;
}

作者写法示例(在 .md 文件中,需 md_in_html 已启用)

<div class="xy-quote" markdown="1">
<div class="xy-quote-content" markdown="1">
人因梦想而伟大,因学习而成长,因行动而成就。
</div>
<span class="xy-quote-author">米开朗基罗</span>
</div>

决议 2 · `.xy-glossary` 术语网格

改前问题 - Markdown 标准定义列表 <dl>/<dt>/<dd>(def_list 扩展)在 Material 主题下视觉极简,大量术语堆叠时找不到重点 - 算法部文档大量术语(声学 / 信号处理 / 产品),需要快速扫读

改后方案 - CSS Grid 自适应卡片(grid-template-columns: repeat(auto-fill, minmax(240px, 1fr))) - 每个术语一张卡:玫瑰金左边线 + 名称 + 简短解释 + 层级 tag(L0/L3/L4) - hover 上浮 transform: translateY(-2px) 增强交互感

CSS 类与变量

.xy-glossary {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(240px, 1fr));
  gap: 1rem;
  margin: 1.5rem 0;
}
.xy-term {
  padding: 1rem;
  background: var(--paper);
  border-left: 3px solid var(--yin);
  border-radius: 4px;
  transition: transform 0.2s;
}
.xy-term:hover { transform: translateY(-2px); }
.xy-term-name {
  display: block;
  font-weight: 600;
  color: var(--yin-deep);
  margin-bottom: 0.5rem;
}
.xy-term-tag {
  display: inline-block;
  padding: 0.1rem 0.5rem;
  font-size: 0.75rem;
  border-radius: 3px;
  margin-left: 0.5rem;
}
.xy-term-tag.l0 { background: var(--L0-bg); color: var(--L0-fg); }
.xy-term-tag.l3 { background: var(--L3-bg); color: var(--L3-fg); }
.xy-term-tag.l4 { background: var(--L4-bg); color: var(--L4-fg); }

作者写法示例

<div class="xy-glossary" markdown="1">

<div class="xy-term" markdown="1">
<span class="xy-term-name">DSP <span class="xy-term-tag l0">L0</span></span>
Digital Signal Processing,数字信号处理。
</div>

<div class="xy-term" markdown="1">
<span class="xy-term-name">Mixer <span class="xy-term-tag l3">L3</span></span>
混音模块,负责多通道信号矩阵混合。
</div>

</div>

决议 3 · Admonition 12 类按 6 组配色

改前问题 - mkdocs material 默认 12 类 admonition(note/abstract/info/tip/success/question/warning/failure/danger/bug/example/quote)颜色各异,但 Xiyin 主题之前为了协调,全部统一成极光青色——结果失去语义区分

改后方案 · 6 组语义配色

组	包含 admonition	主色	CSS 变量	用途
信息组	`note` `abstract` `info`	紫霞	`--xi: #9D4EDD`	一般信息陈述
提示组	`tip` `success` `question`	极光青	`--sheng: #5DDECF`	提示、成功、疑问
警告组	`warning`	玫瑰金	`--yin: #D4A574`	注意事项
危险组	`failure` `danger` `bug`	赤陶	`--status-error: #B87A6F`	错误、危险、Bug
示例组	`example`	古铜金	`--yin-deep: #A87E4C`	示例代码、用例
引用组	`quote`	中性灰	`--text-muted`	引用(与 .xy-quote 互补,quote admonition 用于行内短引)

CSS 类与变量(增量,仅替换原 patch.css 「全部统一极光青」规则)

.callout.info, .callout.note, .callout.abstract { border-left-color: var(--xi); }
.callout.info .callout-title, .callout.note .callout-title, .callout.abstract .callout-title { color: var(--xi); }

.callout.tip, .callout.success, .callout.question { border-left-color: var(--sheng); }
.callout.tip .callout-title, .callout.success .callout-title, .callout.question .callout-title { color: var(--sheng-deep); }

.callout.warning { border-left-color: var(--yin); }
.callout.warning .callout-title { color: var(--yin-deep); }

.callout.danger, .callout.failure, .callout.bug { border-left-color: var(--status-error); }
.callout.danger .callout-title, .callout.failure .callout-title, .callout.bug .callout-title { color: var(--status-error); }

.callout.example { border-left-color: var(--yin-deep); }
.callout.example .callout-title { color: var(--yin-deep); }

.callout.quote { border-left-color: var(--text-muted); }

⚠️ 注:Material 主题实际 admonition 类名是 .admonition,不是 .callout。本规范统一用 .admonition.<type> 选择器。完整选择器在 xiyin-extra.css 落地时由 web 维护者校准。

作者写法示例(无变化,作者只需用对类型,主题自动配色)

!!! info "一般信息(紫霞)"
    陈述事实。

!!! tip "提示(极光青)"
    给作者的建议。

!!! warning "警告(玫瑰金)"
    需要注意的边界条件。

!!! danger "危险(赤陶)"
    这是错误状态色破例。

!!! example "示例(古铜金)"
    代码示例。

!!! quote "引用(中性灰)"
    简短引用,长引用请用 .xy-quote。

决议 4 · Tabs 激活态:玫瑰金实色 + 白字 + 底部小三角

改前问题 - pymdownx.tabbed 默认激活态是细下划线,与 Xiyin 整体的「卡片+渐变」风格不统一

改后方案 - 激活 tab:玫瑰金实色填充(--yin)+ 白字 + 底部小三角指示器(::after) - 非激活 tab:透明底 + 玫瑰金深色字(--yin-deep)+ hover 浅金底

CSS 类与变量

.tabbed-set > input:checked + label {
  background: var(--yin);
  color: white;
  border-radius: 4px 4px 0 0;
  position: relative;
}
.tabbed-set > input:checked + label::after {
  content: '';
  position: absolute;
  bottom: -6px;
  left: 50%;
  transform: translateX(-50%);
  width: 0;
  height: 0;
  border-left: 6px solid transparent;
  border-right: 6px solid transparent;
  border-top: 6px solid var(--yin);
}
.tabbed-set > label {
  color: var(--yin-deep);
  padding: 0.5rem 1rem;
  cursor: pointer;
}
.tabbed-set > label:hover { background: var(--paper-warm); }

作者写法示例(无变化)

=== "Tab 1"
    Content 1
=== "Tab 2"
    Content 2

决议 5 · Subgraph 子图浅产品色底

改前问题 - Mermaid subgraph 默认无背景色,大型流程图层级看不出来

改后方案 - 给 subgraph 注入 6 套浅色 classDef:xySgL0 ~ xySgL5,与产品 6 色对齐 - 已在 xiyin-mermaid.js init 时自动注入,作者只需 class subgraphID xySgL3

CSS / Mermaid classDef(在 xiyin-mermaid.js 中)

const subgraphClassDefs = {
  xySgL0: { fill: '#F0FCFA', stroke: '#2E8D7E', strokeWidth: '1.5px' },  // 浅极光青
  xySgL1: { fill: '#E8FBF7', stroke: '#5DDECF', strokeWidth: '1.5px' },
  xySgL2: { fill: '#FAF4EA', stroke: '#E8C9A0', strokeWidth: '1.5px' },
  xySgL3: { fill: '#FAF0E0', stroke: '#D4A574', strokeWidth: '1.5px' },  // 浅金
  xySgL4: { fill: '#F5EBFF', stroke: '#C77DFF', strokeWidth: '1.5px' },  // 浅紫
  xySgL5: { fill: '#EFE0FF', stroke: '#9D4EDD', strokeWidth: '1.5px' },
};

作者写法示例

```mermaid
flowchart LR
    subgraph S1 [前端层]
      A[UI]
    end
    subgraph S2 [后端层]
      B[API]
    end
    A --> B
    class S1 xySgL1
    class S2 xySgL3
```

决议 6 · 甘特图:双轨方案

改前问题 - Mermaid 默认 gantt 视觉简陋,且无法表达「done = 已交付 / active = 进行中 / planned = 计划」的品牌色差异 - 但纯 HTML 自绘工作量大,简单甘特杀鸡用牛刀

改后方案 · 双轨(决策 3 = Z)

场景	推荐方案	工作量	视觉精度
一般里程碑 / Roadmap 草图	Mermaid `gantt` + JS 主题注入	5 行 markdown	60% v0.3
战略级 Roadmap / 客户提案	`.xy-gantt` HTML 自绘	~20 行 HTML	100% v0.3

轨道 A · Mermaid gantt(默认推荐)

由 xiyin-mermaid.js 在 mermaid.initialize 时注入 themeVariables:

mermaid.initialize({
  theme: 'base',
  themeVariables: {
    ganttDoneColor: '#5DDECF',      // 极光青
    ganttDoneAltColor: '#3FBEAE',
    ganttActiveColor: '#D4A574',    // 玫瑰金
    ganttActiveAltColor: '#A87E4C',
    ganttPlannedColor: '#E8E4DA',
    ganttGridColor: '#F0F4F8',
    sectionBkgColor: '#FBFAF6',
    titleColor: '#9D4EDD',
  }
});

轨道 B · .xy-gantt HTML 自绘(精致版)

.xy-gantt { display: flex; flex-direction: column; gap: 0.5rem; margin: 1.5rem 0; }
.xy-gantt-row { display: grid; grid-template-columns: 120px 1fr; align-items: center; gap: 1rem; }
.xy-gantt-label { font-size: 0.9rem; color: var(--text); }
.xy-gantt-track { position: relative; height: 28px; background: var(--pearl); border-radius: 4px; }
.xy-gantt-bar {
  position: absolute; top: 0; bottom: 0;
  border-radius: 4px;
  display: flex; align-items: center; justify-content: center;
  font-size: 0.8rem; color: white; font-weight: 500;
}
.xy-gantt-bar.done { background: var(--sheng); }
.xy-gantt-bar.active {
  background: linear-gradient(90deg, var(--yin), var(--yin-deep));
  animation: xy-gantt-pulse 2s ease-in-out infinite;
}
.xy-gantt-bar.planned {
  background: transparent;
  border: 1.5px dashed var(--yin);
  color: var(--yin-deep);
}
@keyframes xy-gantt-pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.7; } }

作者写法示例(轨道 A)

```mermaid
gantt
    title Xistudio Roadmap 2026
    dateFormat YYYY-MM
    section P1
    需求评审 :done, p1a, 2026-01, 2M
    架构设计 :active, p1b, 2026-03, 2M
    section P2
    试点开发 :p2a, 2026-05, 3M
```

作者写法示例(轨道 B)

<div class="xy-gantt" markdown="1">
<div class="xy-gantt-row" markdown="1">
<span class="xy-gantt-label">P0 基础设施</span>
<div class="xy-gantt-track">
<div class="xy-gantt-bar done" style="left:0%; width:25%;">已交付</div>
</div>
</div>
<div class="xy-gantt-row" markdown="1">
<span class="xy-gantt-label">P1 高优文档</span>
<div class="xy-gantt-track">
<div class="xy-gantt-bar active" style="left:25%; width:30%;">进行中</div>
</div>
</div>
<div class="xy-gantt-row" markdown="1">
<span class="xy-gantt-label">P2 业务层</span>
<div class="xy-gantt-track">
<div class="xy-gantt-bar planned" style="left:55%; width:35%;">计划</div>
</div>
</div>
</div>

改前问题 - 复杂架构图在文档内显示尺寸有限,无法看清节点细节

改后方案 - 给所有 .mermaid 容器右上角自动注入 ⛶ 放大 按钮 - 点击后在全屏 modal(#xy-mermaid-modal)中放大显示原图 - 支持 ESC 键关闭

新增 JS 文件:docs/assets/javascripts/xiyin-mermaid-zoom.js(在 P0 阶段创建)

/* xiyin-mermaid-zoom.js
 * 给所有 .mermaid 图表加放大按钮 + 全屏 modal
 * 加载时机:DOMContentLoaded(在 xiyin-mermaid.js 之后)
 */
(function () {
  function ensureModal() {
    if (document.getElementById('xy-mermaid-modal')) return;
    const modal = document.createElement('div');
    modal.id = 'xy-mermaid-modal';
    modal.className = 'xy-mermaid-modal';
    modal.innerHTML = `
      <div class="xy-mermaid-modal-backdrop"></div>
      <div class="xy-mermaid-modal-body"></div>
      <button class="xy-mermaid-modal-close" aria-label="关闭">✕</button>`;
    document.body.appendChild(modal);
    modal.querySelector('.xy-mermaid-modal-backdrop').addEventListener('click', closeModal);
    modal.querySelector('.xy-mermaid-modal-close').addEventListener('click', closeModal);
    document.addEventListener('keydown', (e) => { if (e.key === 'Escape') closeModal(); });
  }
  function closeModal() {
    const modal = document.getElementById('xy-mermaid-modal');
    if (modal) modal.classList.remove('open');
  }
  function openModal(svgClone) {
    const modal = document.getElementById('xy-mermaid-modal');
    const body = modal.querySelector('.xy-mermaid-modal-body');
    body.innerHTML = '';
    body.appendChild(svgClone);
    modal.classList.add('open');
  }
  function decorate(container) {
    if (container.querySelector('.xy-mermaid-zoom-btn')) return;
    const btn = document.createElement('button');
    btn.className = 'xy-mermaid-zoom-btn';
    btn.title = '放大查看';
    btn.innerHTML = '⛶';
    btn.addEventListener('click', () => {
      const svg = container.querySelector('svg');
      if (!svg) return;
      ensureModal();
      openModal(svg.cloneNode(true));
    });
    container.style.position = 'relative';
    container.appendChild(btn);
  }
  function bootstrap() {
    document.querySelectorAll('.mermaid').forEach(decorate);
  }
  // Mermaid 渲染是异步的,需要轮询/observer
  if (document.readyState !== 'loading') {
    setTimeout(bootstrap, 800);
  } else {
    document.addEventListener('DOMContentLoaded', () => setTimeout(bootstrap, 800));
  }
  // 二次保险:MutationObserver 监听 SVG 注入
  const observer = new MutationObserver(() => bootstrap());
  observer.observe(document.body, { childList: true, subtree: true });
})();

配套 CSS(加到 xiyin-extra.css)

.xy-mermaid-zoom-btn {
  position: absolute; top: 8px; right: 8px;
  width: 32px; height: 32px;
  background: rgba(212, 165, 116, 0.85);
  color: white; border: none; border-radius: 4px;
  cursor: pointer; font-size: 16px;
  z-index: 10;
}
.xy-mermaid-zoom-btn:hover { background: var(--yin-deep); }
.xy-mermaid-modal {
  display: none; position: fixed; inset: 0; z-index: 9999;
}
.xy-mermaid-modal.open { display: block; }
.xy-mermaid-modal-backdrop {
  position: absolute; inset: 0;
  background: rgba(11, 28, 46, 0.85);
}
.xy-mermaid-modal-body {
  position: relative;
  width: 90vw; height: 90vh; margin: 5vh auto;
  background: white; border-radius: 8px; padding: 2rem;
  overflow: auto;
  box-shadow: 0 20px 60px rgba(0, 0, 0, 0.5);
}
.xy-mermaid-modal-body svg { width: 100%; height: 100%; }
.xy-mermaid-modal-close {
  position: absolute; top: 1rem; right: 1rem;
  width: 36px; height: 36px;
  background: white; border: 1px solid var(--line);
  border-radius: 50%; cursor: pointer; font-size: 18px;
  z-index: 10000;
}

mkdocs.yml 加载顺序(P0 阶段集成)

extra_javascript:
  # ... 已有
  - assets/javascripts/xiyin-mermaid.js
  - assets/javascripts/xiyin-mermaid-zoom.js  # 新增,必须在 mermaid.js 之后

决议 8 · 数学公式:双轨方案

改前问题 - mkdocs.yml 启用了 pymdownx.arithmatex generic: true 但 未加载 KaTeX/MathJax CDN → 当前所有 $E=mc^2$ 都是占位符,不渲染 - 算法部文档大量出现公式

改后方案 · 双轨(决策 4 = R)

场景	推荐方案	加载体积	适用复杂度
行内简单公式(变量、上下标)	Unicode + HTML	0KB	低
简单分数	`.xy-frac` CSS 分数线	0KB	低
矩阵 / 积分 / 求和 / 复杂分数	KaTeX CDN	~280KB(按需)	高

轨道 A · Unicode + HTML(零依赖)

- 信号能量:E = ∑ x[n]²(用 Unicode `∑`)
- 滤波器:H<sub>∞</sub>(z) = b<sub>0</sub> + b<sub>1</sub> z<sup>-1</sup>
- 简单分数:<span class="xy-frac"><span class="xy-frac-num">1</span><span class="xy-frac-den">2π</span></span>

.xy-frac CSS:

.xy-frac {
  display: inline-flex; flex-direction: column;
  vertical-align: middle; text-align: center;
  font-family: 'Cambria Math', 'Times New Roman', serif;
  font-size: 0.95em;
}
.xy-frac-num { border-bottom: 1px solid currentColor; padding: 0 0.3em; }
.xy-frac-den { padding: 0.1em 0.3em; }

轨道 B · KaTeX CDN(P0 阶段在 mkdocs.yml 添加)

extra_javascript:
  # KaTeX
  - https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.js
  - https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/contrib/auto-render.min.js
  - assets/javascripts/xiyin-katex.js  # 启动 auto-render

extra_css:
  - https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css

xiyin-katex.js(P0 阶段创建):

document.addEventListener('DOMContentLoaded', () => {
  if (typeof renderMathInElement === 'function') {
    renderMathInElement(document.body, {
      delimiters: [
        { left: '$$', right: '$$', display: true },
        { left: '$', right: '$', display: false },
        { left: '\\(', right: '\\)', display: false },
        { left: '\\[', right: '\\]', display: true },
      ],
      throwOnError: false,
    });
  }
});

作者写法(LaTeX,需轨道 B 加载后才渲染)

内联:$E = mc^2$
块级:
$$
H(z) = \frac{b_0 + b_1 z^{-1}}{1 + a_1 z^{-1}}
$$

决议 9 · `.xy-stack` 产品 6 色层级栈

改前问题 - 表达「L0 平台 → L5 用户」这种产品分层时,无视觉品牌色

改后方案 - L0-L5 各自层级背景 + 边框 + 徽章 - 产品 6 色锁定:L0 深极光青 → L1 极光青 → L2 香槟金 → L3 玫瑰金 → L4 浅紫 → L5 曦紫

CSS 类与变量

.xy-stack { display: flex; flex-direction: column; gap: 0.5rem; margin: 1.5rem 0; }
.xy-stack-item {
  padding: 1rem 1.5rem;
  border-radius: 6px;
  border-left: 4px solid;
  display: flex; align-items: center; gap: 1rem;
}
.xy-stack-item .badge {
  display: inline-block;
  padding: 0.2rem 0.6rem;
  font-size: 0.75rem;
  font-weight: 600;
  color: white;
  border-radius: 3px;
}
.xy-stack-item.l0 { background: var(--L0-bg); border-color: var(--L0-fg); }
.xy-stack-item.l0 .badge { background: var(--L0-fg); }
.xy-stack-item.l1 { background: var(--L1-bg); border-color: var(--L1-fg); }
.xy-stack-item.l1 .badge { background: var(--L1-fg); }
.xy-stack-item.l2 { background: var(--L2-bg); border-color: var(--L2-fg); }
.xy-stack-item.l2 .badge { background: var(--L2-fg); color: var(--L2-text); }
.xy-stack-item.l3 { background: var(--L3-bg); border-color: var(--L3-fg); }
.xy-stack-item.l3 .badge { background: var(--L3-fg); }
.xy-stack-item.l4 { background: var(--L4-bg); border-color: var(--L4-fg); }
.xy-stack-item.l4 .badge { background: var(--L4-fg); }
.xy-stack-item.l5 { background: var(--L5-bg); border-color: var(--L5-fg); }
.xy-stack-item.l5 .badge { background: var(--L5-fg); }

作者写法示例

<div class="xy-stack" markdown="1">
<div class="xy-stack-item l5"><span class="badge">L5</span> 用户体验层</div>
<div class="xy-stack-item l4"><span class="badge">L4</span> 应用层</div>
<div class="xy-stack-item l3"><span class="badge">L3</span> 业务层</div>
<div class="xy-stack-item l2"><span class="badge">L2</span> 算法层</div>
<div class="xy-stack-item l1"><span class="badge">L1</span> 引擎层</div>
<div class="xy-stack-item l0"><span class="badge">L0</span> 平台层</div>
</div>

3. 工程落地依赖矩阵

决议	依赖 mkdocs.yml	依赖 xiyin-extra.css	依赖新增 JS	依赖新增 CSS 变量
1 `.xy-quote`	-	✅ 新增 §xy-quote 块	-	-
2 `.xy-glossary`	-	✅ 新增 §xy-glossary 块	-	✅ `--L0-bg/L3-bg/L4-bg`
3 Admonition 6 组	-	✅ 替换 patch.css 旧统一规则	-	-
4 Tabs 激活态	-	✅ 新增 §tabbed-set 块	-	-
5 Subgraph 子图色	-	-	✅ `xiyin-mermaid.js` 已有(检查)	-
6a Mermaid gantt	-	-	✅ `xiyin-mermaid.js` 注入 themeVariables	-
6b `.xy-gantt` HTML	-	✅ 新增 §xy-gantt 块	-	-
7 Mermaid 放大	✅ 加 `xiyin-mermaid-zoom.js`	✅ 新增 §xy-mermaid-modal 块	✅ 新建 `xiyin-mermaid-zoom.js`	-
8a Unicode/HTML 公式	-	✅ 新增 §xy-frac 块	-	-
8b KaTeX	✅ 加 KaTeX CDN + `xiyin-katex.js`	-	✅ 新建 `xiyin-katex.js`	-
9 `.xy-stack`	-	✅ 新增 §xy-stack 块	-	✅ `--L0~L5-bg/fg/text`

P0 阶段一次性落地清单(交给文档管理员智能体):

xiyin-extra.css 末尾追加 9 个 §块(总 ~250 行 CSS)
xiyin-brand.css 检查并补齐 --L0-bg ~ --L5-fg ~ --L5-text 共约 18 个 CSS 变量(具体见 brand-color-system.md v1.2 §4)
xiyin-patch.css 替换原「Admonition 全部统一极光青」规则为 6 组配色映射
新建 docs/assets/javascripts/xiyin-mermaid-zoom.js(本文件 §决议 7 提供完整代码)
新建 docs/assets/javascripts/xiyin-katex.js(本文件 §决议 8 提供完整代码)
mkdocs.yml 在 extra_javascript / extra_css 加载 KaTeX CDN + 上述 2 个新 JS(具体见 nav-display-spec.md §2)
xiyin-mermaid.js 检查 themeVariables 是否含 gantt* 系列(本文件 §决议 6a),缺则补

4. 与下游规范的引用关系

flowchart TD
    A["format-spec-changelog.md<br>(本文档 · 视觉决议来源)"] -->|引用决议 1/2/3/4/9| B["md-writing-spec.md v2.0<br>(MD 写作契约)"]
    A -->|引用决议 3/9| C["brand-color-system.md v1.2<br>(色板权威)"]
    A -->|引用决议 7/8b| D["nav-display-spec.md<br>(站点配置)"]
    A -->|引用决议 5/6| B
    B --> E["folder-structure-spec.md<br>(目录约定)"]
    F["migration-plan-2026Q2.md<br>(阶段计划)"] -->|P0 落地清单引用本文档 §3| A

    class A xyL3
    class B,C,D xyL1
    class E xyL2
    class F xyL5

引用规则: - ✅ 下游规范引用本文档:用 [决议 N · XX](format-spec-changelog.md#决议-n-xx) 锚点链接 - ❌ 下游规范不得重复决议描述:只能引用,不能抄写,避免多份文档失同步 - ✅ 本文档不重复 CSS 变量定义:具体 hex 值以 brand-color-system.md v1.2 为准

决议 10 · Stripe 三栏布局(站点骨架 · v1.0.1 新增 ⭐)

改前问题 - mkdocs material 默认是「双栏:左 nav + 主区」,无独立右 TOC - 默认主题视觉与 Stripe / Linear 顶级文档站差距大,无品牌识别度 - 产品矩阵 11 个 + 13 稳态文档导致 nav 极深,默认侧栏太窄(240px)文字易截断

改后方案 · Demo 1 · Stripe / Linear 风格(用户已决议 ✓) - 三栏 grid 布局:grid-template-columns: 260px 1fr 220px - 左侧栏:深海军蓝 #0a2540(与项目「夜蓝堆栈 deep #0B1C2E」几乎一致)+ 13/12.5/11px 三级字号 + 当前项 2px 玫瑰金色条 - 主区:max-width: 720px + padding: 48px 64px + 32/22/16px 标题字号 - 右 TOC:220px + 1px 浅灰左边线 + 当前项玫瑰金边线 - 顶部 Banner(可选):28px 高 + 三色法典渐变(替代 Stripe 紫蓝渐变)

关键决策 · 色彩接管: - ✅ Stripe 主色 #635bff 紫 → 替换为玫瑰金 var(--yin) #D4A574(三色法典之一) - ✅ Stripe 蓝渐变 → 替换为三色法典渐变 var(--gradient-trinity) - ❌ 禁止在任何位置使用原 Stripe 紫 / 蓝(避免引入第 5 色)

视觉源文件:nav-demo/demo-1-stripe-style.html(417 行 · 已用户确认 ✓) 参考来源:stripe.com/docs + linear.app/docs 3 选 1 比较:同时排除 Demo 2 Vercel 风(顶部 tab 切大类,信息层级太浅) / Demo 3 Notion 风(抽屉式 nav,不适合开发者高频查阅场景)

完整 CSS / Material 主题接管 / 9 项验收清单详见:nav-display-spec.md §3

5. 修订历史

版本	日期	修订人	关键变更
v1.0.1	2026-05-11	AlgoDepartment	§1 总览表新增决议 10「Stripe 三栏布局」 + §2 末尾新增决议 10 详情;落地第一组早期导航方案决议(此前漏记录)
v1.0	2026-05-11	AlgoDepartment	首版发布 · 沉淀 v0.3 demo 9 条视觉决议(第二组格式 Demo)

下一步

本文档完成后,文档管理员智能体应: 1. 按 §3 落地清单,在 P0 阶段执行 7 项工程动作 2. 按 §4 引用关系,在 5 份下游规范中插入锚点链接 3. 完成后将本文档状态从 published 改为 frozen(冻结,作为版本基线)

文档格式规范变更日志 v1.0.1

文档格式规范变更日志 v1.0.1

1. 10 条视觉决议总览表

2. 决议详情:逐条沉淀

决议 1 · .xy-quote 引言/箴言卡

决议 2 · .xy-glossary 术语网格

决议 3 · Admonition 12 类按 6 组配色

决议 4 · Tabs 激活态:玫瑰金实色 + 白字 + 底部小三角

决议 5 · Subgraph 子图浅产品色底

决议 6 · 甘特图:双轨方案

决议 7 · Mermaid 放大按钮 + 全屏 modal

决议 8 · 数学公式:双轨方案

决议 9 · .xy-stack 产品 6 色层级栈

3. 工程落地依赖矩阵

4. 与下游规范的引用关系

决议 10 · Stripe 三栏布局(站点骨架 · v1.0.1 新增 ⭐)

5. 修订历史

决议 1 · `.xy-quote` 引言/箴言卡

决议 2 · `.xy-glossary` 术语网格

决议 9 · `.xy-stack` 产品 6 色层级栈