illustrator-diagrams

name

illustrator-diagrams

description

Create information design diagrams in Adobe Illustrator via ExtendScript automation. Follows a data-first approach: identify data dimensions, map to visual channels using perceptual effectiveness research (Cleveland & McGill, Tufte), then compose into a diagram structure. Use when asked to create any diagram, chart, visual explanation, system architecture, flowchart, data visualization, process flow, org chart, concept map, timeline, or infographic in Illustrator. Also use when iterating on an existing Illustrator diagram. Triggers on: Illustrator, diagram, flowchart, architecture, system diagram, process flow, information design, visual explanation, data visualization, infographic, .ai file.

Illustrator Information Design

Create diagrams in Adobe Illustrator where the visual form encodes the data — not decorates it.

Architecture

Three tools work together in a loop:

1. Write tool → Create .jsx ExtendScript file
2. mcp__Control_your_Mac__osascript → Execute JSX in Illustrator, which exports PNG
3. Read tool → View the exported PNG for evaluation

See references/extendscript-api.md Section 1 for the JSX file execution pattern (always preferred over inline AppleScript).

Execution Pattern (use this every time)

1. Write JSX to:   /sessions/eloquent-zen-bohr/my_diagram.jsx
2. Copy to Mac:    cp .../my_diagram.jsx .../mnt/darcyburner/Desktop/my_diagram.jsx
3. Execute:        osascript: tell "Adobe Illustrator" to do javascript file (POSIX file ".../Desktop/my_diagram.jsx")
4. View:           Read /sessions/eloquent-zen-bohr/mnt/darcyburner/Desktop/my_diagram.png

Before execution, close stale documents (see extendscript-api.md Section 1).

Core Workflow

Phase 1: Analyze (before writing ANY code)

Read references/decision-framework.md and work through the five steps:

1. Identify data dimensions — List every quantitative, categorical, relational, and ordinal dimension in the information
2. Rank by priority — What should the viewer understand in the first 3 seconds? What rewards closer inspection?
3. Map to visual channels — Primary dimension → most effective channel. Use the Cleveland & McGill hierarchy.
4. Check dynamic range — At the diagram's actual pixel size, can the viewer distinguish the values? If not, choose a different channel.
5. Select composition — Find a matching pattern in references/compositions.md, or compose from multiple.

This phase is the most important. The difference between a C- diagram and an A diagram is NOT typography or color palette — it's whether the visual form itself encodes the data. If the viewer needs to read labels to understand the diagram's message, the visual encoding has failed.

Phase 2: Design (plan before coding)

With your dimension→channel→composition decided:

• Artboard size: Calculate from content bounds. Never use fixed sizes. Content should fill 70-85% of the artboard.
• Spatial layout: Define grid positions for all elements. Assign (col, row) to each.
• Color: If color encodes a data dimension, assign from the dimension's values. If color is purely categorical, use monochromatic (grays + one accent). Color that doesn't encode data is decoration.
• Typography: One font family (Helvetica Neue). Three sizes: title 22-28pt bold, labels 12-14pt medium, annotations 10-11pt regular. Text color: dark gray (#1F2937) on light, white on dark.

Phase 3: Implement

Write the complete JSX script. Structure:

// 1. Close existing docs, create new document
while(app.documents.length > 0) { app.documents[0].close(SaveOptions.DONOTSAVECHANGES); }
var doc = app.documents.add(DocumentColorSpace.RGB, width, height);

// 2. Define helpers (rgb, drawing functions)
function rgb(r,g,b) { var c = new RGBColor(); c.red=r; c.green=g; c.blue=b; return c; }

// 3. Create ALL text frames FIRST (avoids MRAP errors)
// 4. Create shapes and connectors
// 5. Auto-size artboard to content
// 6. Export PNG
var opts = new ExportOptionsPNG24();
opts.antiAliasing = true; opts.transparency = false;
opts.artBoardClipping = true; opts.horizontalScale = 200; opts.verticalScale = 200;
doc.exportFile(new File('~/Desktop/diagram_name.png'), ExportType.PNG24, opts);
'OK';

See references/extendscript-api.md for the full API and utility patterns.

Phase 4: Evaluate

After EVERY render, assess against these criteria:

Does the visual form encode the data?

• Can you understand the diagram's primary message WITHOUT reading any labels? (The visual encoding test)
• Is the primary visual channel working? (Can you see the differences it's supposed to show?)
• Does the secondary channel add information without conflicting with the primary?

Spatial efficiency:

• Does content fill 70-85% of the artboard? (If not, auto-size the artboard)
• Is there dead space with no purpose? (Large empty corridors, excessive margins)
• Are elements packed too tightly? (Labels overlapping, connectors crossing)

Readability:

• All text ≥ 10pt and high contrast
• Labels unambiguously associated with their elements
• Reading direction immediately obvious (single dominant direction)

Data-ink ratio:

• Every visual element earns its place. No decorative shadows, gradients, 3D effects.
• If color doesn't encode data, switch to monochromatic.
• If a connector can be removed without losing information (e.g., spatial position already implies sequence), remove it.

Phase 5: Iterate

Fix issues found in evaluation. Common iteration patterns:

• Visual channel not working → Switch to a more effective channel (e.g., area → length)
• Too much dead space → Auto-size artboard; tighten spacing
• Labels overlapping → Increase spacing or reduce label count
• Message not clear in 3 seconds → Strengthen the primary visual encoding; remove clutter

References

• references/decision-framework.md — The data-first decision process: dimensions → channels → composition. Read this first for every new diagram.
• references/compositions.md — Gallery of 10 proven visual compositions with what they encode, when they work/fail, and ExtendScript implementation patterns.
• references/extendscript-api.md — Full ExtendScript API reference, JSX file execution pattern, coordinate system, utility functions, and known errors.

Quick Reference: Common Palettes

When color is purely categorical (not encoding quantitative data):

Monochromatic (default — use unless color encodes data):
  Dark:    rgb(31, 41, 55)     #1F2937
  Mid:     rgb(107, 114, 128)  #6B7280
  Light:   rgb(229, 231, 235)  #E5E7EB
  Accent:  rgb(37, 99, 235)    #2563EB

Two-track (e.g., batch vs real-time):
  Track A: rgb(156, 163, 175)  #9CA3AF  (gray-400)
  Track B: rgb(147, 197, 253)  #93C5FD  (blue-300)
  Text:    rgb(31, 41, 55)     #1F2937

When color encodes a quantitative dimension (e.g., heatmap):

Sequential: white → rgb(37, 99, 235) (light to saturated blue)
Diverging:  rgb(239, 68, 68) → white → rgb(37, 99, 235) (red ← neutral → blue)