Flowchart Design Standard

Scope: Layout, aesthetics, and visual design principles for flowcharts. NOT in scope: Symbol shapes, colors, edge types — see flowchart_symbols_standard.md (the SINGLE SOURCE OF TRUTH).

Core philosophy: 美化是手段，传递信息才是目的。 Any decoration that prevents a reader from narrating the main flow in 3 seconds is harmful.

1. Design Axiom

A flowchart is a visual language for information transfer. Every design choice must answer one question: does this help the reader understand the logic faster? If not, remove it.

2. Color Principles

Node and edge colors are defined in flowchart_symbols_standard.md. This section covers how to use color, not which colors.

2.1 Consistency (统一性)

• Same semantic type → same color. All Process nodes are Blue. All Decision nodes are Amber. No exceptions.
• The color palette is fixed per symbol type (see Color Standard in flowchart_symbols_standard.md). Never invent new hues.
• If a node doesn't fit any standard type, use process (Blue) as default.

2.2 Contrast (对比度)

• Fill vs. Stroke: Every node uses a light fill + saturated stroke. The stroke carries identity; the fill provides area.
• Text vs. Background: Minimum lightness difference > 30%. Use the designated font-color from the standard.
• Primary vs. Secondary edges: Primary Flow is 3px black (opacity 0.85). All other edges are thinner, lighter, or dashed. The visual gap must be obvious.

2.3 Restraint (精简性)

• Max 3 dominant hues in any single diagram. The rest are accents.
• If a diagram uses 6+ symbol types, the palette naturally expands — but the reader still perceives "blue things = actions, amber things = decisions" because shape reinforces color.
• Never use color to encode a second dimension (e.g., "blue = process AND blue = deterministic"). Color encodes symbol type only.

2.4 Context Adaptation (场景适配)

3. Node Design Principles

3.1 Size Standardization (节点标准化)

• Same-type nodes must have the same dimensions. Two Process nodes side by side should be identical in size.
• Decision diamonds are naturally taller due to shape — keep the text area compact.

3.2 Content Density (文字易读化)

Each node has at most 3 text lines. Each line answers ONE question for the reader:

┌──────────────────────────────────┐
│  Literature Survey               │  Line 1: What IS this stage?
│  collect background papers       │  Line 2: What does it PRODUCE?
│  topic → annotated reading notes │  Line 3: What goes IN → what comes OUT?
└──────────────────────────────────┘

Title: Verb + Object (动词化)

• GOOD: Literature Survey, Parse Goal, Gate Decision, Final Verify
• BAD: Session (too vague — session of what?), Data Processing (generic)

Subtitle: What it Produces

• GOOD: collect background papers, build hypothesis tree, distill key findings
• BAD: Literature Review (noun phrase — what does it DO?), goal.md parsing (filename, not meaning)

I/O: Semantic Transformation (语义变换, NOT 实现细节)

The io line describes the domain-level transformation: what data enters, what data exits. It must NOT contain implementation details.

The acid test: Cover the label. Can a reader understand the node's purpose from sub + io alone? If not, rewrite.

Rule: The io line must form a data story when read top-to-bottom across all nodes:

goal.md → role + topic + project
  → topic → annotated reading notes
    → papers → hypothesis tree
      → hypotheses → experiment plan
        → plan → per-hypothesis results
          → results → advance or backtrack
            → experiments → reusable insights
              → insights → paper + slides
                → all artifacts → pass / fail

Each output feeds into the next input. If there's a gap, a node label or io is wrong.

Chips (Optional, for Overview Nodes)

• Font: Sans-serif only (no serifs, no monospace for node text).
• Alignment: Center-aligned. Never wrap title to 2+ lines — shorten instead.
• No icons inside nodes unless replacing text entirely (max 1 icon per node).

3.3 Badges and Status

• Depth badge (L0/L1/L2): Top-left corner, small pill, neutral background.
• Status badge (pass/fail/running): Top-right corner, single character (✓/✗/●).
• Badges never overlap title text. If the node is too small, omit badges.

4. Edge Design Principles

Edge types and colors are defined in flowchart_symbols_standard.md. This section covers routing and visual hierarchy.

4.1 Visual Hierarchy (线条层级)

The reader should instantly know which line is the "main road":

• If all edges look equally important, the diagram is broken. Primary must dominate.

4.2 Straightness Rules (线条必须直，Non-Negotiable)

If a line CAN be straight, it MUST be straight. A crooked line between aligned nodes is always a bug.

4.3 Routing Rules (线条路由)

4.3 Label Rules

• Labels are small (10px), with white semi-transparent background for readability.
• Primary Flow is never labeled — its identity comes from visual weight alone.

5. Layout Principles

5.1 Spine-First Layout (主干优先)

Every flowchart must have exactly one main trunk (spine). All other information hangs off this spine as sidecars, chips, or detail views.

Correct:                           Wrong:
  A → B → C → D → E               A → B → C
                                       ↓   ↗
                                       D → E
                                   (two competing paths)

The reader's eye follows ONE line. If two paths look equally strong, the hierarchy is broken.

5.2 Direction Rules

• Never mix L→R and T→B in the same diagram level. Pick one and commit.

5.3 Row Wrapping (Hard Rule)

• Max 5 nodes per row. If more than 5, wrap to the next row.
• 10 nodes = 2 rows × 5 columns (the standard Overview layout).
• Wrapping is left-to-right, top-to-bottom (reading order).

5.4 Alignment (对齐，Non-Negotiable)

If two nodes CAN be aligned, they MUST be aligned. Misalignment is the #1 cause of crooked lines.

Correct (aligned):              Wrong (misaligned):
  ┌───┐   ┌───┐   ┌───┐          ┌───┐  ┌───┐
  │ A │───│ B │───│ C │          │ A │──┐ │ B │
  └───┘   └───┘   └───┘          └───┘  └─└───┘
  (same Y → straight lines)         (offset Y → crooked line)

5.5 No Overlap (不重叠，Non-Negotiable)

Nodes must never overlap other nodes. Edges must never pass through unconnected nodes.

Correct (no overlap):           Wrong (edge crosses node):
  ┌───┐   ┌───┐                   ┌───┐───┌───┐
  │ A │───│ B │                   │ A │ X │ B │
  └───┘   └───┘                   └───┘───└───┘
  ┌───┐   ┌───┐                        │
  │ C │───│ D │                   ┌───┐─┘
  └───┘   └───┘                   │ C │
                                  └───┘

5.6 Spacing

• Uniform spacing is non-negotiable. Inconsistent gaps create the illusion of semantic grouping where none exists.

5.7 Visual Balance (视觉平衡)

• The diagram's center of gravity should be near the geometric center of the canvas.
• Left/right and top/bottom should have roughly equal visual weight.
• If one side is heavy (many nodes), add whitespace or rebalance by moving auxiliary nodes.

6. Overview Design (L0)

The Overview is the reader's first and most important impression. It must be optimized for instant comprehension.

6.1 Hard Limits

• If the process has < 10 logical steps: split granular steps to reach 10.
• If the process has > 10 logical steps: group related steps into collapsed containers.

6.2 What Belongs in Overview

6.3 Collapsed Groups

When multiple related steps are collapsed into one group node:

• Label: Phase name (e.g., Analysis)
• Badge: P1→P2→P3 or 3 steps
• Visual: Use group class (neutral border, light fill)
• Click behavior: Drill into detail view (no page change — expand in-place or navigate to detail diagram)

6.4 Sidecar Pattern

Artifacts, configurations, and data products should NOT be main-trunk nodes. Instead:

• Attach as chips on the producing node (max 3 visible, overflow +N)
• Or use a single sidecar note (e.g., "Key Artifacts" box) anchored beside the main trunk
• The sidecar does NOT count toward the 10-node limit

7. Detail Design (L1+)

Detail views expand what was collapsed in the Overview.

7.1 Expansion Rules

• Expanding a group only pushes downstream nodes — upstream stays fixed (the reader's mental map is preserved).
• Expanded children stack vertically within the group container (T→B inside L→R spine).
• Collapsed state shows 1 node; expanded state shows N children + internal edges.

7.2 Detail Limits

7.3 Internal Layout

Within an expanded group:

Group Container (Analysis)
  ├─ Map (Pass 1)         ← vertical stack
  ├─ Q1 Gate (diamond)    ← smaller, same column
  ├─ Mechanics (Pass 2)
  └─ Mastery (Pass 3)

• Same-phase steps share the same X coordinate (strict column alignment).
• Group padding: 16px. Inter-step: 28px.

8. Interaction Principles

8.1 Default State

• Locked layout — nodes are not draggable by default. This is a presentation, not a whiteboard.
• Auto fitView — on load, on expand/collapse, on navigation.
• Provide an "Unlock layout" toggle for editing mode only.

8.2 Progressive Disclosure

• Overview starts with Step 1 visible. Click "Next" to reveal each subsequent step.
• Edges appear when both source and target are visible.
• Notes appear when their associated step is revealed.

8.3 Navigation

• Click group → drill into detail (expand or navigate)
• Back button → return to Overview (restore position)
• Legend toggle → show/hide the legend overlay

9. Legend (Required)

Every diagram MUST include a legend. The legend shows:

1. Symbol shapes used in this diagram (subset of the 20 standard types)
2. Edge types used in this diagram (subset of the 6 standard types)

Legend rules:

• Fixed position: bottom-right corner or floating overlay
• Does not scroll with the canvas
• Shows only symbols/edges actually present in the current view
• Compact: 1 row of shape chips + 1 row of edge samples

10. Anti-Patterns (What NOT to Do)

11. Acceptance Checklist (8-Point Test)

Before shipping any flowchart, verify all 8:

12. Quick Decision Tree

Use this when designing a new flowchart:

Q: How many main steps?
├─ ≤ 5 → Single row, L→R, direction: right
├─ 6–10 → Grid layout, 2 rows × 5 cols
└─ > 10 → Overview (10 nodes) + Detail drilldowns

Q: Does a step contain sub-steps?
├─ Yes, 2–5 sub-steps → Collapse into group node
├─ Yes, > 5 sub-steps → Separate detail diagram
└─ No → Regular node

Q: Is this an artifact, not an action?
├─ Key output (PDF, report) → Data or Document node in spine
├─ Intermediate file (config, index) → Chip on producing node
└─ Multiple artifacts → Sidecar note box

Q: Does this edge go backward?
├─ Main retry loop → 1 Feedback edge (purple dotted)
├─ Gate fail → rework → Gate Fail edge (red dashed) to rework node
└─ Other backward reference → Skip edge (slate dashed), or hide in detail

References

• Symbol Standard: flowchart_symbols_standard.md — shapes, colors, edge types (SINGLE SOURCE OF TRUTH)
• D2 Classes: flowviz_d2_classes.md — copy-paste D2 class blocks
• FlowViz Skill: /flowchart SKILL.md — workflow and rendering instructions