pma-d2

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

D2 Diagram Author

D2图表创作器

Generate idiomatic

.d2

source files — diagrams encoded as declarative text, rendered by the official

d2

CLI to SVG / PNG / PDF / GIF. The output is human-readable, diffable, and embeds anywhere D2 embeds (GitHub, Notion, VS Code, docs sites, Oxide's play.d2lang.com).

Keep this entry file small. Load only the reference packs that match the current diagram.

生成符合规范的

.d2

源文件——以声明式文本编码的图表，可通过官方

d2

CLI渲染为SVG/PNG/PDF/GIF格式。输出内容可读性强、可对比差异，并且能嵌入所有支持D2的平台（GitHub、Notion、VS Code、文档站点、Oxide的play.d2lang.com）。

请保持此入口文件简洁。仅加载与当前图表匹配的参考包。

Always-On Rules

通用规则

Output is
.d2
text, nothing else. The skill never invokes a renderer; the user runs
```
d2 input.d2 out.svg
```
or opens play.d2lang.com. Quality must be enforceable by reading the source.
Idiomatic D2 over clever D2. Prefer declarative node names (
```
api -> db
```
) over IDs + labels when the name reads naturally. Reach for
```
label:
```
only when the natural name would be awkward or duplicated.
Shape type matches concept. A database is
```
shape: cylinder
```
, a queue is
```
shape: queue
```
, an actor is
```
shape: person
```
. Never default everything to
```
rectangle
```
. Full catalog in
```
references/shapes.md
```
.
Direction declared up front. Set
```
direction: down | right | up | left
```
on the root (and per container if needed). Layout direction is a communication choice, not an incidental default.
Semantic edge style, not ornamental.
```
stroke-dash
```
for async / weak dependency;
```
animated: true
```
for streams;
```
stroke
```
color to encode criticality / failure paths. Catalog in
```
references/connections.md
```
.
Group by container, not by proximity. If nodes belong to one domain (a subsystem, a cloud, a bounded context), nest them in a container map. Containers are D2's native grouping — use them instead of manual placement.
One concept per diagram. If a diagram answers two questions, split into two
```
layers:
```
or two files. Don't compress.
Classes for repetition. ≥ 2 nodes share styling → define a class in
```
classes: {}
```
and apply with
```
.class: name
```
or a glob.
No invented shapes. All
```
shape:
```
values must come from
```
references/shapes.md
```
. D2 silently falls back to rectangle on typos, which is the worst failure mode: it looks right but isn't.
Commit-ready source. File ends with a newline, uses 2-space indentation, no trailing whitespace, comments explain intent not mechanics. D2 is git-friendly — keep it that way.

输出仅为
.d2
文本，无其他内容。本工具从不调用渲染器；用户需自行运行
```
d2 input.d2 out.svg
```
或打开play.d2lang.com。通过阅读源代码即可确保输出质量。
优先使用符合规范的D2写法，而非巧妙的技巧。 当名称自然易读时，优先使用声明式节点名称（
```
api -> db
```
），而非ID+标签的形式。仅当自然名称会显得生硬或重复时，才使用
```
label:
```
。
图形类型与概念匹配。 数据库使用
```
shape: cylinder
```
，队列使用
```
shape: queue
```
，角色使用
```
shape: person
```
。切勿默认所有图形为
```
rectangle
```
。完整图形目录请查看
```
references/shapes.md
```
。
提前声明布局方向。 在根节点设置
```
direction: down | right | up | left
```
（必要时可为每个容器单独设置）。布局方向是一种沟通选择，而非随意的默认值。
语义化的连线样式，而非装饰性样式。 使用
```
stroke-dash
```
表示异步/弱依赖；
```
animated: true
```
表示流；
```
stroke
```
颜色用于区分关键路径/故障路径。样式目录请查看
```
references/connections.md
```
。
按容器分组，而非按位置 proximity。 如果节点属于同一领域（子系统、云环境、限界上下文），将它们嵌套在容器映射中。容器是D2原生的分组方式——请使用容器而非手动定位。
每个图表对应一个概念。 如果一个图表需要回答两个问题，拆分为两个
```
layers:
```
或两个文件。不要压缩内容。
使用类处理重复样式。 ≥2个节点共享样式时→在
```
classes: {}
```
中定义一个类，并通过
```
.class: name
```
或通配符应用。
不使用自定义图形。 所有
```
shape:
```
的值必须来自
```
references/shapes.md
```
。D2在输入错误时会静默回退为矩形，这是最糟糕的故障模式：看起来正常但实际不符合要求。
提交就绪的源代码。 文件以换行结尾，使用2空格缩进，无尾随空格，注释说明意图而非实现细节。D2对Git友好——请保持这一特性。

Core Workflow

核心工作流程

Step 1: Choose Diagram Family

步骤1：选择图表类型

Family	D2 primitive	Use when
Architecture / flow	default (nodes + connections)	Systems, pipelines, dependency graphs
Sequence	`shape: sequence_diagram`	Protocol exchanges, API call flows, timing
ERD / schema	`shape: sql_table` per table	Data model, foreign keys
UML class	`shape: class` per class	OO design, type relationships
Grid / matrix	`grid-rows` / `grid-columns`	Tabular layouts, comparison matrices, k8s cluster views
Multi-board	`layers:` / `scenarios:` / `steps:`	Before/after, drill-down, animation

Details per family in

references/special-diagrams.md

and

references/composition.md

类型	D2原语	使用场景
架构/流程	默认（节点+连线）	系统、流水线、依赖图
时序图	`shape: sequence_diagram`	协议交互、API调用流程、时序
ER图/ schema	每个表使用 `shape: sql_table`	数据模型、外键
UML类图	每个类使用 `shape: class`	面向对象设计、类型关系
网格/矩阵	`grid-rows` / `grid-columns`	表格布局、对比矩阵、k8s集群视图
多面板	`layers:` / `scenarios:` / `steps:`	前后对比、钻取、动画

各类型详情请查看

references/special-diagrams.md

和

references/composition.md

。

Step 2: Pick Layout Engine

步骤2：选择布局引擎

dagre (default, free, bundled): DAG-oriented, good for most architecture diagrams.
elk (free, bundled since v0.7): cleaner for nested hierarchies and orthogonal routing. Worth trying for multi-container diagrams.
tala (paid, separate binary): best-in-class for complex, dense diagrams. Note in the file header if required so the user knows what to install.

Pick once per file via

vars.d2-config.layout-engine

. Don't fight the engine with manual positions — D2 has no

x,y

dagre（默认、免费、内置）：面向有向无环图，适用于大多数架构图。
elk（免费，v0.7版本起内置）：在嵌套层级和正交路由方面表现更简洁。适合多容器图表。
tala（付费、独立二进制文件）：在复杂、密集图表中表现最佳。如果需要使用，请在文件头部注明，以便用户了解需要安装的内容。

通过

vars.d2-config.layout-engine

为每个文件选择一次布局引擎。不要通过手动位置对抗引擎——D2没有

x,y

属性。

Step 3: Draft Structure

步骤3：草拟结构

Sketch the top-level containers first: which systems / domains exist.
Add nodes inside each container with the correct
```
shape:
```
.
Add connections — direction first, labels after topology is right.
Apply
```
classes:
```
to collapse repetition.
Add
```
vars.d2-config
```
block (theme, layout engine) at the top.

先绘制顶层容器：确定存在哪些系统/领域。
在每个容器内添加带有正确
```
shape:
```
的节点。
添加连线——先确定方向，拓扑正确后再添加标签。
应用
```
classes:
```
来简化重复样式。
在顶部添加
```
vars.d2-config
```
块（主题、布局引擎）。

Step 4: Style Pass

步骤4：样式优化

Walk every connection — is its style (solid / dashed / animated / color) semantically distinct from its neighbors'?
Walk every node — does its
```
shape:
```
and class carry information?
Remove ornamentation that doesn't encode meaning (decorative colors, gratuitous shadows).

检查每条连线——其样式（实线/虚线/动画/颜色）是否与相邻连线在语义上有区别？
检查每个节点——其
```
shape:
```
和类是否传递了信息？
删除不传递含义的装饰（装饰性颜色、多余阴影）。

Step 5: Validate & Hand Off

步骤5：验证与交付

Run the pre-flight in

references/validation.md

. Tell the user:

The output path (default
```
docs/architecture/<name>.d2
```
).
The render command:
```
d2 <name>.d2 <name>.svg
```
(or whatever target they need).
The chosen layout engine and whether it requires a separate install.
Any icons referenced by URL (so they can mirror internally if needed).

运行

references/validation.md

中的预检步骤。告知用户：

输出路径（默认
```
docs/architecture/<name>.d2
```
）。
渲染命令：
```
d2 <name>.d2 <name>.svg
```
（或用户需要的其他目标格式）。
所选布局引擎以及是否需要单独安装。
所有通过URL引用的图标（以便用户在内部镜像使用）。

Section-by-Section for Large Diagrams

大型图表的分段处理

Write the
```
vars
```
+
```
direction
```
header and one container.
Append one container per edit; prefix child IDs by container if they'd otherwise collide.
Cross-container edges use dotted paths (
```
aws.api -> gcp.auth
```
); verify the path exists before emitting the edge.
When a diagram grows past ~60 nodes, split into
```
layers:
```
or separate
```
.d2
```
files composed via
```
@file
```
imports (
```
references/composition.md
```
).

编写
```
vars
```
+
```
direction
```
头部和一个容器。
每次编辑添加一个容器；如果子ID可能冲突，则在子ID前添加容器前缀。
跨容器连线使用点路径（
```
aws.api -> gcp.auth
```
）；在输出连线前验证路径是否存在。
当图表节点超过约60个时，拆分为
```
layers:
```
或单独的
```
.d2
```
文件，通过
```
@file
```
导入组合（查看
```
references/composition.md
```
）。

Output

输出

File:
```
docs/architecture/<name>.d2
```
by default, or a path the user specifies.

Render (user runs):

```
d2 name.d2
```
→
```
name.svg
```
(default)
```
d2 name.d2 name.png
```
/
```
name.pdf
```
/
```
name.gif
```
```
d2 --watch name.d2
```
→ live preview on localhost

d2 --theme <id> --dark-theme <id> name.d2

→ theme pairing

Web preview: paste into https://play.d2lang.com/ for instant rendering without installing D2.
Embedding: see
```
references/integration.md
```
for MDX, GitHub READMEs (checked-in SVG), docs sites (live render at build time), and CI pipelines.

文件：默认路径为
```
docs/architecture/<name>.d2
```
，或用户指定的路径。

渲染（用户执行）：

```
d2 name.d2
```
→
```
name.svg
```
（默认）
```
d2 name.d2 name.png
```
/
```
name.pdf
```
/
```
name.gif
```
```
d2 --watch name.d2
```
→ 在localhost上实时预览

d2 --theme <id> --dark-theme <id> name.d2

→ 主题组合

网页预览：将内容粘贴到https://play.d2lang.com/，无需安装D2即可即时渲染。
嵌入：查看
```
references/integration.md
```
了解MDX、GitHub README（已提交的SVG）、文档站点（构建时实时渲染）和CI流水线的嵌入方法。

Reference Packs

参考包

```
references/syntax.md
```
Core grammar: identifiers, labels, maps, comments, escaping, the shorthand rules D2 is full of.
```
references/shapes.md
```
Every built-in shape with picture description, data semantics, and "use when" guidance.
```
references/connections.md
```
Edge operators (
```
->
```
,
```
<-
```
,
```
<->
```
,
```
--
```
), chaining, arrowheads, labels, semantic styling patterns.
```
references/containers.md
```
Nesting,
```
_
```
parent refs, dotted paths, the difference between a container and a shape, when to flatten vs nest.
```
references/classes.md
```
```
classes:
```
block, applying via
```
.class:
```
, multi-class arrays, glob-based mass application.
```
references/styles.md
```
Complete style key catalog (fill, stroke, stroke-dash, shadow, 3d, multiple, animated, fill-pattern, border-radius, font-size, bold/italic/underline, opacity).
```
references/layouts.md
```
Direction, grid layouts, dagre vs elk vs tala tradeoffs,
```
near:
```
positioning for titles and legends.
```
references/special-diagrams.md
```
Sequence diagrams (actors, spans, notes, groups),
```
sql_table
```
ERDs,
```
class
```
UML, markdown / code / LaTeX blocks.
```
references/composition.md
```
```
layers:
```
(isolated boards),
```
scenarios:
```
(inherit + override),
```
steps:
```
(animation),
```
@file
```
imports,
```
...@file
```
spread.
```
references/vars.md
```
```
vars:
```
block,
```
${var}
```
substitution,
```
d2-config
```
(theme-id, dark-theme-id, sketch, pad, center, layout-engine), nested vars for design tokens.
```
references/templates.md
```
Copy-paste starter files: 3-tier web, microservices, data pipeline, CI/CD, sequence (OAuth), ERD, k8s cluster (grid).
```
references/design.md
```
Concept→pattern mapping, isomorphism test, when D2 beats ReactFlow / Mermaid / Excalidraw, when it loses.
```
references/validation.md
```
Pre-flight algorithm and checklists; common D2 mistakes (silent shape fallback, missing container path, label vs comment collisions).
```
references/render.md
```
CLI flags, watch mode, playground, icon catalogs (terrastruct icons, svgrepo), theme gallery.
```
references/integration.md
```
MDX / Docusaurus / Nextra embedding, GitHub README via checked-in SVG, docs-site build pipelines, pre-commit render.

```
references/syntax.md
```
核心语法：标识符、标签、映射、注释、转义、D2包含的各种简写规则。
```
references/shapes.md
```
所有内置图形，包含图片说明、数据语义和“使用场景”指南。
```
references/connections.md
```
连线运算符（
```
->
```
,
```
<-
```
,
```
<->
```
,
```
--
```
）、链式连线、箭头、标签、语义化样式模式。
```
references/containers.md
```
嵌套、
```
_
```
父引用、点路径、容器与图形的区别、何时扁平化 vs 嵌套。
```
references/classes.md
```
```
classes:
```
块、通过
```
.class:
```
应用、多类数组、基于通配符的批量应用。
```
references/styles.md
```
完整样式键目录（填充、描边、描边虚线、阴影、3D、多重样式、动画、填充图案、圆角、字体大小、粗体/斜体/下划线、透明度）。
```
references/layouts.md
```
方向、网格布局、dagre vs elk vs tala的权衡、标题和图例的
```
near:
```
定位。
```
references/special-diagrams.md
```
时序图（角色、跨度、注释、分组）、
```
sql_table
```
ER图、
```
class
```
UML、markdown/代码/LaTeX块。
```
references/composition.md
```
```
layers:
```
（独立面板）、
```
scenarios:
```
（继承+覆盖）、
```
steps:
```
（动画）、
```
@file
```
导入、
```
...@file
```
展开。
```
references/vars.md
```
```
vars:
```
块、
```
${var}
```
替换、
```
d2-config
```
（theme-id、dark-theme-id、sketch、pad、center、layout-engine）、用于设计令牌的嵌套变量。
```
references/templates.md
```
可复制粘贴的启动文件：三层Web架构、微服务、数据流水线、CI/CD、时序图（OAuth）、ER图、k8s集群（网格）。
```
references/design.md
```
概念→模式映射、同构测试、D2优于ReactFlow/Mermaid/Excalidraw的场景、以及劣势场景。
```
references/validation.md
```
预检算法和检查清单；常见D2错误（静默图形回退、缺失容器路径、标签与注释冲突）。
```
references/render.md
```
CLI标志、监听模式、在线编辑器、图标目录（terrastruct icons、svgrepo）、主题画廊。
```
references/integration.md
```
MDX/Docusaurus/Nextra嵌入、通过已提交SVG在GitHub README中展示、文档站点构建流水线、提交前渲染。

Quick Routing

快速指引

New to D2 syntax: load
```
syntax.md
```
+
```
shapes.md
```
+
```
connections.md
```
.

Architecture / system diagram:

shapes.md

containers.md

layouts.md

templates.md

Sequence / SQL / UML:
```
special-diagrams.md
```
+
```
templates.md
```
.
Styling pass:
```
classes.md
```
+
```
styles.md
```
.
Multi-board story (before/after, drill-down, animation):
```
composition.md
```
.
Theming / config:
```
vars.md
```
+
```
render.md
```
.
Before delivering:
```
validation.md
```
.
Telling the user how to render or embed:
```
render.md
```
+
```
integration.md
```
.

If the project also uses

/pma

for workflow control, load

/pma

first, then

/pma-d2

only when a diagram is required. If the project needs interactive, in-browser diagrams with custom React node components, use

/pma-draw

instead — D2 renders to static images.

不熟悉D2语法：加载
```
syntax.md
```
+
```
shapes.md
```
+
```
connections.md
```
。

架构/系统图：

shapes.md

containers.md

layouts.md

templates.md

。

时序图/SQL/UML：
```
special-diagrams.md
```
+
```
templates.md
```
。
样式优化：
```
classes.md
```
+
```
styles.md
```
。
多面板场景（前后对比、钻取、动画）：
```
composition.md
```
。
主题/配置：
```
vars.md
```
+
```
render.md
```
。
交付前：
```
validation.md
```
。
告知用户如何渲染或嵌入：
```
render.md
```
+
```
integration.md
```
。

如果项目同时使用

/pma

进行工作流控制，请先加载

/pma

，仅在需要图表时再加载

/pma-d2

。如果项目需要带有自定义React节点组件的交互式浏览器图表，请使用

/pma-draw

替代——D2仅渲染静态图像。