Container-Based Layered Diagram Skill (C4 Container Implementation · D2)

This skill is for drawing container-based layered diagrams (diagrams with the structure of "large containers nesting small containers, multi-level vertical nesting"). D2 is the implementation method (d2lang.com). This SKILL.md is a router — read it for main workflow, iron rules, and triage; refer to documents under

references/

as needed (see §4 References Routing Table).

1. What to Draw: C4 Container Diagram (Align Objectives First)

1.1 Definition: What is a Container-Based Layered Diagram (Including C4 Container)

• C4 model Container Diagram: Shows what containers a software system consists of (Official C4 definition: "A container represents an application or data store... The container diagram shows the high-level technology choices and how the containers communicate with one another.").
• Technical architecture diagrams / product architecture diagrams / business capability layered diagrams / microservice architecture diagrams: Any diagram that fits the form of "multi-level vertical nesting of large containers + sub-container distribution" is applicable to this skill.

• Container = An independently divisible unit in the diagram (application, service, data storage, business module, etc.), not Docker container.
• Container-based layered diagram = Zoom in on a system/product/business to show "what containers it consists of + how containers communicate with each other".

For the 9 characteristic requirements, feature-to-syntax mapping, dynamic padding calculation, and layered specifications (color/spacing/shape/rounded corner/color scheme), see references/c4-container-spec.md.

1.2 Align with Iron Rules (Highest Priority)

The following iron rules are the final effect standards — any syntax or template must comply. Self-check against them after generation; if not met =不合格, must adjust.

1.3 Core Methodology (DSL Guarantees from the Source)

D2 is a declarative DSL — every requirement can be guaranteed by syntax from the source, no need to "draw first then check for errors". When generating code, ensure that the syntax naturally meets the requirements, and rendering is only for verification.

1. Align structure (Steps 1-3 in §2 Workflow)
2. Calculate the width/height of all sub-containers using the formulas in references/layout-and-grid.md (every container, every partition, every sub-module)
3. Attach rounded corner classes to each node as specified in c4-container-spec.md §4.8
4. Write code → render → self-check verification (should pass at one time)

2. Workflow (Triage → 5 Steps for New Diagrams / Modifications Follow §2.3)

2.1 Triage (First Thing When Entering the Skill: New vs Modify vs Read-Only)

1. User input points to an existing d2 block — provides location + diagram name ("the capability layered diagram in

   docs/L1/PRODUCT-SPEC.md

   "), pastes the code block, or says "modify/adjust/update that diagram" → Modify Mode (§2.3 Workbench extract → modify → render → sync)
2. User uses new diagram terms (draw/create/add a new diagram) and does not reference existing blocks → New Mode (complete all 5 steps in §2.2; if there is another diagram at the target location → insert a new block, do not touch the old diagram)
3. User says redraw/override/regenerate a certain diagram → Modify Mode (replace the code block)
4. User says "check/look at" → Read-Only Mode (acceptance via troubleshooting.md, no code modification)

• Unable to locate: User does not provide document path/cannot find any d2 block, and cannot clarify intent → ask "Where is the target document/diagram?"
• Multiple blocks do not match: The document has multiple d2 blocks, and the diagram name mentioned by the user does not match the first-line comment of any block → list the diagram names of each block for the user to choose ("The document contains: ① System Architecture Diagram ② Deployment Architecture Diagram... Which one to modify?")
• No location at all: Only says "draw a diagram" without any document clues → ask "Where to draw it?"

Rendering Method: d2 code blocks are automatically rendered by the project Markdown rendering engine (embedded ```d2 is rendered). AI does not manually render SVG to files — all diagram outputs are in Markdown code blocks. Only temporarily render SVG with scripts for verification during self-check (see references/troubleshooting.md).

2.2 New Mode (5 Steps)

CRITICAL — BLOCKING (Blocking Requirement #1, Step 2): Before drawing an architecture diagram, must first align with the user on number of layers / modules in each layer / label style (top-centered vs left vertical arrangement). Prohibit writing d2 code before alignment.

CRITICAL — BLOCKING (Blocking Requirement #2, Step 3): Before writing the d2 code block, MUST first show the general structure of the diagram (number of layers + modules in each layer + connections between layers) to the user via an ASCII architecture diagram in the conversation. Prohibit writing d2 code before user confirmation. (See references/templates.md for ASCII diagram elements)

1. Locate the target Markdown document: Confirm the insertion position (new) or target code block (modify). Prohibit writing d2 code before confirming the target document
2. Align architecture diagram parameters (Mandatory, Blocking #1): Confirm with the user: ① Number of layers (usually 3~6 layers); ② Module names in each layer (users will list each product/service/capability name — must use real business labels, prohibit placeholders such as e1/e2/c1/c2, placeholders only appear in skill template examples); ③ Label style (top-centered = mainstream / left vertical arrangement = architect-style); ④ Color preference (default to the five layer systems of blue/purple/green/orange/gray, or user-specified); ⑤ Whether inter-layer arrows are needed (default to implicit dependency via stacking; when arrows are needed, only connect between layer containers, parent to parent, see references/connection-routing.md)
3. ASCII Architecture Confirmation (Mandatory, Blocking #2): Directly output an ASCII architecture diagram (number of layers + modules in each layer + connections between layers + label position) in a

   text

   code block in the conversation, and wait for the user's explicit confirmation. If the user proposes modifications, update the ASCII diagram and confirm again. (See references/templates.md)
4. Write/modify the

   ```d2

   code block in the target document: Write the diagram name comment in the first line (

   # Diagram Name

   ) — this is the identifier of the diagram, and subsequent location/modification relies on semantic matching (§2.1), prohibit omission. Format is not limited: Chinese is preferred (e.g.,

   # System Architecture Diagram

   ), subject to user preference, both Chinese and English are acceptable (e.g.,

   # System Architecture

   ) — the key is to have an identifiable name. Start the second line with

   vars: { d2-config: { layout-engine: elk } }

   (default elk), and you can continue to write meta-information comments such as perspective/purpose. After writing, rendering is automatically completed by the Markdown engine, AI does not perform any output/rendering actions
5. Self-check: Use one command from §2.3 Workbench (automatically verify viewBox/overflow/equal width/rounded corners) — for new diagrams:

   extract docs.md --name Diagram Name

   to extract the newly written block for verification (no sync needed); for modifications to existing diagrams:

   extract → render → sync

   . Use the manual process in troubleshooting.md only when the workbench is unavailable.

```d2

verify-svg.py

2.3 Modify Mode (Adjust Existing Diagrams, ≠ Redraw)

Objective: Modify diagrams quickly from the second time (3~5 minutes each time), not rewrite the entire diagram. Core principle: Authoritative source = Markdown code block, always modify the original document content when changing code (keep

\n

literals); temporary .d2 files are read-only for verification, prohibit "modifying temporary files then copying back" to cause duplicate maintenance. If the target block has no diagram name (no first-line comment): First ask the user to add a name (can suggest), add it before modifying — make all diagrams identifiable (§2.1).

# 1. Extract: Semantic matching by diagram name (first-line comment) or diagram serial number → workspace .d2/.svg/.png + verification
#    (without parameters, it will list the diagram names of all d2 blocks in the document)
python3 scripts/d2-workbench.py extract docs.md --name "System Architecture Diagram"
python3 scripts/d2-workbench.py extract docs.md 1 --out .     # or by serial number

# 2. Iterate modification: Edit workspace .d2 (modify label/add container/adjust width) → render + verify
python3 scripts/d2-workbench.py render docs-fig1.d2

# 3. Write back: Sync workspace .d2 back to md (replace original code block; see troubleshooting.md §7.4 for fallback semantics)
python3 scripts/d2-workbench.py sync docs.md docs-fig1.d2 --name "System Architecture Diagram"
python3 scripts/d2-workbench.py sync docs.md docs-fig1.d2 1   # or by serial number
# Explicit fallback when needed: sync docs.md docs-fig1.d2 --fallback=img ; cleanup: clean-fallback docs.md

• ⚠️ Modify Mode Exempts Blocking #1/#2 in §2.2: Alignment parameters (Blocking #1) and ASCII confirmation (Blocking #2) only need to be re-executed when the structure changes (adding layers/changing column count/moving modules); directly modify for pure label/width/color/arrow adjustments, and verify the closed loop with workbench commands after modification
• ⚠️ Modification = Replace the target code block in place, prohibit adding a second d2 block (high-frequency mistake: insert new content next to the original when modifying, resulting in two diagrams in the document). After modification, must confirm that the number of d2 blocks at the target location remains unchanged — naturally guaranteed by workbench sync (only replaces the Nth block + block count consistency assertion, aborts with error if blocks are added/deleted); count the number of

  ```d2

  after manual Markdown editing
• Only recalculate the width of the modified layer (formula in references/layout-and-grid.md): Keep the original values for unchanged layers/containers, do not recalculate the entire diagram for "consistency" — only modify the label when changing the label, only modify the color when changing the color
• Check for edges with the same semantics before adding containers/layers (avoid duplicate edges), remember to set

  border-radius

  for new containers (c4-container-spec.md §4.8)

• \n

  Literal Iron Rule: Write

  \n

  (two characters: backslash + n) for line breaks in labels, prohibit actual line breaks; prohibit

  echo

  /unquoted heredoc/Python string concatenation when writing .d2 with scripts (see references/d2-syntax-cheatsheet.md) — workbench scripts naturally avoid this (direct file IO writing)

3. ASCII Architecture Confirmation (Mandatory Before Drawing)

text

See references/templates.md for the ASCII architecture diagram element list + complete examples, and confirmation protocol. Prohibit writing d2 code or calling rendering commands before the user's explicit confirmation (blocking requirement).

4. References Routing Table (What You Need to Do → Which File to Read)

\n

diagram-review.md

is a project-specific post-rendering organization review checklist; other

connections/containers/elk/grid-diagrams

are localized D2 official documents.

5. Iron Rule Quick Reference (Non-Negotiable Red Lines, Must Follow When Drawing/Modifying Diagrams)

Each of the following is a red line, must adjust to comply if violated. See corresponding references for detailed rules.

1. Explicit width calculation for each layer: For each layer of nesting (A→B→C→D), explicitly calculate the width of sub-containers (references/layout-and-grid.md); the only exception: single-column vertical bars do not require setting width, let ELK automatically wrap and center them. Calculating only the outermost layer will cause "left-aligned offset".
2. Parent-to-parent arrows: Inter-layer arrows only connect between parent layer containers (

   Overall Architecture.Layer A -> Overall Architecture.Layer B

   ), do not connect sub-containers within layers; must write the complete path, otherwise d2 silently creates duplicate top-level nodes (references/connection-routing.md).
3. Multi-board diagrams prohibited:

   layers/scenarios/steps

   multi-board syntax cannot be output by the Markdown rendering engine, split into multiple independent

   ```d2

   code blocks (references/d2-syntax-cheatsheet.md).
4. TALA engine prohibited: TALA is closed-source and paid (free version has watermarks), use

   elk

   uniformly (d2-syntax-cheatsheet.md).
5. viewBox integer overflow: Combination of multiple classes + deep nesting + vertical bars will trigger ELK int64 overflow (viewBox=-9e18 blank diagram). Must use single class + outer 1×1 grid + no width setting for vertical bars (d2-syntax-cheatsheet.md §6.16).

6. \n

   Line Break Iron Rule: Write

   \n

   literal (two characters: backslash + n) for line breaks in labels, prohibit actual line breaks; long labels (>8 characters) must be split with

   \n

   into lines with ≤8 characters each (d2-syntax-cheatsheet.md §6.17).
7. Global rounded rectangles: Every graphic (outer layer/layer/partition/innermost sub-module/vertical bar) must have rounded corners (c4-container-spec.md §4.8).

6. Self-Check (One-Command Closed Loop)

Use one command from the workbench script (automatically verify viewBox/overflow/equal width/rounded corners), see references/troubleshooting.md for detailed process.

# Extract d2 block from md → workspace .d2/.svg/.png + automatic verification (preferred for modification)
python3 scripts/d2-workbench.py extract docs.md --name "System Architecture Diagram"
# Iterate modification
python3 scripts/d2-workbench.py render docs-fig1.d2
# Write back to md (replace original code block, automatically perform round-trip verification and prevent multiple diagrams)
python3 scripts/d2-workbench.py sync docs.md docs-fig1.d2 --name "System Architecture Diagram"

d2 validate

verify-svg.py

python3 scripts/verify-svg.py out.svg

7. CLI Quick Reference (For Self-Check, SVG Only)

d2 in.d2 out.svg                                # Render to SVG (default)
d2 in.d2 out.svg --layout=elk                    # Specify layout (default elk is already written in vars)
d2 validate in.d2                              # Syntax verification (no file output)
d2 fmt --check in.d2                            # Format check
d2 --theme=0 in.d2 out.svg                       # Theme: 0 Neutral Default / 200 Dark Mauve

8. Short Example (Minimal 3-Layer Skeleton)

Complete templates (3-layer standard/vertical arrangement/vertical bar/intra-layer partition) are available in references/templates.md.

# Minimal Architecture Diagram
vars: { d2-config: { layout-engine: elk } }

Overall Architecture: {
  grid-rows: 1
  grid-columns: 1
  grid-gap: 24
  Entry Layer: {
    width: 1000; grid-columns: 3; grid-gap: 12; class: module
    h1: { width: 317; height: 60; class: module }
    h2: { width: 317; height: 60; class: module }
    h3: { width: 317; height: 60; class: module }
  }
  Business Layer: {
    width: 1000; grid-columns: 2; grid-gap: 12; class: module
    b1: { width: 482; height: 60; class: module }
    b2: { width: 482; height: 60; class: module }
  }
  Support Layer: {
    width: 1000; grid-columns: 2; grid-gap: 12; class: module
    s1: { width: 482; height: 60; class: module }
    s2: { width: 482; height: 60; class: module }
  }
}