dag-visual-editor-design（dag 可视化编辑器设计）

DAG Visual Editor Design

Design modern, intuitive DAG and workflow visual editors. This skill captures best practices from industry leaders like n8n, ComfyUI, Retool Workflows, and React Flow — prioritizing clarity over complexity.

Philosophy: LEGO, Not LabView

Traditional node editors (LabView, Max/MSP, older VFX tools) suffer from:

• Dense, cluttered interfaces
• Overwhelming port/connection complexity
• Steep learning curves
• "Spaghetti" wire syndrome

Modern DAG editors take a different approach:

• LEGO-like composability — snap blocks together
• Progressive disclosure — show complexity only when needed
• Clear data flow — left-to-right or top-to-bottom
• Minimal chrome — the content IS the interface

Core Design Principles

1. Nodes as First-Class Components

Nodes should feel like self-contained units, not wiring terminals.

┌─────────────────────────────┐
│ 🔄 Transform Data           │  ← Clear title with icon
├─────────────────────────────┤
│ Input: users.json           │  ← Inline config, not ports
│ Output: filtered_users      │
├─────────────────────────────┤
│ ▶ Run  │ ⚙ Config │ 📋 Docs │  ← Actions in footer
└─────────────────────────────┘

Bad (LabView style):

    ●─┬─●     ●─●
      │       │
  ┌───┴───┐ ┌─┴─┐
  │ Node  │─│ N │
  └───┬───┘ └─┬─┘
      │       │
    ●─┴─●   ●─┴─●

Good (Modern style):

┌──────────┐      ┌──────────┐
│  Input   │ ───▶ │ Process  │ ───▶ [Output]
└──────────┘      └──────────┘

2. Connection Semantics

Key insight from ComfyUI: Show data flowing through edges during execution. Users understand what's happening.

3. Handle Design

Avoid: Multiple tiny ports crammed on node sides

Prefer:

• Single input handle (top or left)
• Single output handle (bottom or right)
• Type indicators via color/shape only when needed
• Handle reveals on hover for clean default state

4. Layout Algorithms

Auto-layout is critical. Users shouldn't manually arrange nodes.

// Dagre layout (hierarchical, left-to-right)
const layout = dagre.graphlib.Graph()
  .setGraph({ rankdir: 'LR', ranksep: 80, nodesep: 40 })
  .setDefaultEdgeLabel(() => ({}));

// ELK (more sophisticated, handles complex graphs)
const elk = new ELK();
await elk.layout(graph, {
  algorithm: 'layered',
  'elk.direction': 'RIGHT',
  'elk.layered.spacing.nodeNodeBetweenLayers': 100,
});

5. Minimap & Navigation

Essential for complex workflows:

• Minimap in corner (toggleable)
• Fit-to-view on double-click background
• Breadcrumbs for nested/grouped nodes
• Search to jump to nodes

Technology Stack

React Flow (Recommended)

import ReactFlow, {
  Background,
  Controls,
  MiniMap,
  useNodesState,
  useEdgesState,
} from 'reactflow';

function WorkflowEditor() {
  const [nodes, setNodes, onNodesChange] = useNodesState(initialNodes);
  const [edges, setEdges, onEdgesChange] = useEdgesState(initialEdges);

  return (
    <ReactFlow
      nodes={nodes}
      edges={edges}
      onNodesChange={onNodesChange}
      onEdgesChange={onEdgesChange}
      fitView
    >
      <Background variant="dots" gap={16} />
      <MiniMap />
      <Controls />
    </ReactFlow>
  );
}

Custom Node Template

const SkillNode = ({ data, selected }) => (
  <div className={cn(
    "rounded-lg border-2 bg-white shadow-md min-w-[200px]",
    selected ? "border-blue-500" : "border-gray-200"
  )}>
    {/* Header */}
    <div className="flex items-center gap-2 px-3 py-2 bg-gray-50 rounded-t-lg">
      <span className="text-lg">{data.icon}</span>
      <span className="font-medium">{data.label}</span>
    </div>

    {/* Body - preview of config */}
    <div className="px-3 py-2 text-sm text-gray-600">
      {data.preview}
    </div>

    {/* Handles */}
    <Handle type="target" position={Position.Left} />
    <Handle type="source" position={Position.Right} />
  </div>
);

Interaction Patterns

Edge Drawing

1. Click source handle → drag → release on target handle
2. Show valid drop targets while dragging
3. Snap to nearest compatible handle
4. Allow edge deletion via backspace or context menu

Node Creation

1. Context menu — Right-click on canvas
2. Quick add — Type / to search nodes (like Notion)
3. Drag from library — Sidebar with categorized nodes
4. Connection drop — Drop edge on empty space → node picker

Keyboard Shortcuts

Visual Hierarchy

Node States

/* Default */
.node { border: 2px solid #e5e7eb; }

/* Selected */
.node.selected { border-color: #3b82f6; box-shadow: 0 0 0 2px rgba(59,130,246,0.3); }

/* Running */
.node.running { border-color: #f59e0b; animation: pulse 1s infinite; }

/* Completed */
.node.completed { border-color: #10b981; }

/* Error */
.node.error { border-color: #ef4444; background: #fef2f2; }

Edge Animation During Execution

.edge-animated path {
  stroke-dasharray: 5;
  animation: dash 0.5s linear infinite;
}

@keyframes dash {
  to { stroke-dashoffset: -10; }
}

Anti-Patterns to Avoid

1. Too many handle types — Color-code sparingly, not per data type
2. Wire spaghetti — Use auto-layout, not manual positioning
3. Hidden complexity — Don't collapse essential config into modals
4. No execution feedback — Show what's running and what's waiting
5. Monolithic nodes — Break complex operations into composable pieces
6. Ignoring touch — Support touch/pen for tablet users

Case Studies

n8n

• Clean card-based nodes
• Inline parameter editing
• Execution visualization with timing
• Excellent error highlighting

ComfyUI

• Familiar to VFX/3D artists
• Lazy evaluation (only runs changed nodes)
• Shareable workflow JSON files
• Preview widgets inside nodes

Retool Workflows

• Conditional branching UI
• Loop visualization
• Strong typing with visual indicators
• Enterprise-grade error handling

Implementation Checklist

• React Flow or similar graph library
• Auto-layout with Dagre/ELK
• Custom node components with consistent design
• Edge animation during execution
• Minimap for navigation
• Keyboard shortcuts
• Undo/redo system
• Node search/quick add
• Save/load workflow state
• Export to JSON/image

Resources

• React Flow Documentation
• xyflow/awesome-node-based-uis
• n8n Node UI Design
• ComfyUI Technical Deep Dive
• ELK.js Layout Algorithms
• Dagre Layout