Quartz Diagram Style Guide

Purpose

这篇页面用于承接比 Mermaid 更美观、但仍然可维护的图形表达。它不替代 Mermaid，而是补充四类场景：

• 架构分层图：表达系统分层、数据平台、治理控制面。
• 数据流图：表达从源系统到消费层的链路。
• 能力地图：表达角色能力、治理能力、Agent 能力。
• 决策图：表达架构选型、设计取舍和方案对比。

Tip

Mermaid 适合快速表达结构，HTML diagram component 适合正式方案、教程、演讲和高频复用页面。

Design Rules

生成或手写图形 HTML 时，遵守这些规则：

1. 只写局部 HTML fragment，不写完整 html/head/body。
2. 不写 <style> 和 <script>，可复用样式放到 quartz/styles/custom/diagram-components.scss。
3. class 统一使用 wiki-diagram- 前缀，避免污染 Quartz 全站样式。
4. 使用 Quartz CSS 变量：var(--light)、var(--dark)、var(--darkgray)、var(--lightgray)、var(--secondary)。
5. 复杂交互图才考虑 iframe 或 Quartz component；普通图不要引入外部 CDN。

Claude / AI Prompt Contract

当使用 Claude frontend-design 或其他前端生成工具时，建议直接使用这段约束：

Generate only a self-contained HTML fragment for Quartz Markdown.
Do not include html/head/body/script/style tags.
Use classes prefixed with wiki-diagram-.
Use existing classes from diagram-components.scss where possible.
Use CSS variables: var(--light), var(--dark), var(--darkgray), var(--lightgray), var(--secondary), var(--tertiary), var(--highlight).
No Tailwind, no external CDN, no inline styles unless absolutely necessary.
The component must be responsive and work in dark mode.

Architecture Layers

适合数据平台、湖仓架构、Agent 架构、治理架构等分层表达。

Architecture

Bigdata Wiki OS Reference Architecture

Experience

Obsidian Writing, linking, local graph

Quartz Publishing and navigation

Knowledge

MOC Maps of content

Concept Cards Definitions and links

Case Notes Project evidence

Governance

DCMM Capability maturity

DAMA Knowledge domains

CDO Lens Business value

Use this layout when layers are more important than exact arrows.

<section class="wiki-diagram wiki-diagram-architecture" aria-labelledby="arch-title">
  <span class="wiki-diagram-kicker">Architecture</span>
  <h2 class="wiki-diagram-title" id="arch-title">Architecture Title</h2>
  <div class="wiki-diagram-layers">
    <div class="wiki-diagram-layer">
      <div class="wiki-diagram-layer-label">Layer</div>
      <div class="wiki-diagram-layer-items">
        <div class="wiki-diagram-node">
          <span class="wiki-diagram-node-title">Node</span>
          <span class="wiki-diagram-node-text">Description</span>
        </div>
      </div>
    </div>
  </div>
</section>

Data Flow

适合数据采集、实时数仓、RAG、Agent tool chain 等链路表达。

Data Flow

From Source to Agent

Source Docs, logs, tables

→

Compile Extract concepts and links

→

Wiki Markdown graph

→

Agent Answer, query, report

Use this layout when direction and transformation are the main story.

<section class="wiki-diagram wiki-diagram-flow" aria-labelledby="flow-title">
  <h2 class="wiki-diagram-title" id="flow-title">Flow Title</h2>
  <div class="wiki-diagram-flow-track">
    <div class="wiki-diagram-node"><span class="wiki-diagram-node-title">Source</span></div>
    <div class="wiki-diagram-arrow">→</div>
    <div class="wiki-diagram-node"><span class="wiki-diagram-node-title">Target</span></div>
  </div>
</section>

Capability Map

适合角色能力、知识域、产品能力和治理能力总览。

Capability Map

Data Architect Core Capabilities

Strategy Business value and roadmap

Governance DCMM, DAMA, policy

Modeling Metrics and semantic layer

Platform Lakehouse and serving

Data Architect Connects engineering, governance and value

AI Agent-ready data context

Use this layout when the central role or product matters most.

Decision Matrix

适合对比 Mermaid、HTML 组件、SVG、iframe 和 Quartz component。

Decision

Diagram Rendering Choice

Mermaid Best for fast, source-controlled logic diagrams.

• Low maintenance
• Plain visual style

HTML Component Best for polished pages and reusable visual systems.

• Matches site theme
• Needs CSS discipline

iframe Best for complex interactive diagrams.

• Strong isolation
• Harder to search

When To Use What

Need	Recommended Format	Notes
Quick flow or dependency graph	Mermaid	Best for rough notes and evolving design
Polished architecture page	HTML diagram component	Use classes from diagram-components.scss
Highly custom static visual	SVG asset	Store asset and caption it
Interactive demo	iframe or Quartz component	Avoid inline scripts in Markdown
Generated visual from Claude	HTML fragment + custom SCSS	Do not paste full standalone HTML

Maintenance Changelog

Date	Change	Files	Notes
2026-06-11	Add reusable diagram components	quartz/styles/custom/diagram-components.scss	Architecture, flow, capability, decision layouts
2026-06-11	Add diagram style guide	content/index/Posts/Quartz Diagram Style Guide.md	Demo page for future diagrams

Links

• related:: Quartz Style Guide
• supports:: Bigdata Wiki OS
• supports:: Data Agent Architecture