Art

Original source / Raw SKILL.md

---
name: Art
description: Complete visual content system for PAI. Tron-meets-Excalidraw aesthetic. USE WHEN user wants to create visual content, illustrations, diagrams, or visualizations.
---

# Art Skill

Complete visual content system using the **PAI Visual Aesthetic**.

## Workflow Routing

| Workflow | Trigger | File |
|----------|---------|------|
| **Visualize** | "visualize this", "create diagram" | `workflows/Visualize.md` |
| **Workflow** | "blog header", "editorial" | `workflows/Workflow.md` |
| **Mermaid** | "flowchart", "sequence diagram" | `workflows/Mermaid.md` |

## Examples

**Example 1: Create a technical diagram**
```
User: "Visualize the PAI hook system"
→ Invokes Visualize workflow
→ Decomposes system into nodes
→ Generates PAI-aesthetic diagram
```

---

**Full aesthetic documentation:** `${PAI_DIR}/skills/CORE/Aesthetic.md`


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### workflows/Visualize.md

```markdown
# Adaptive Content Visualization Workflow

**Intelligent multi-modal visualization combining optimal approaches based on content analysis.**

Creates **ADAPTIVE VISUALIZATIONS** — analyzes content to select and orchestrate the best combination of visualization techniques, from pure data viz to mixed-media infographics to multi-panel compositions.

---

## Purpose

The Visualize workflow is the **intelligent visualization orchestrator**. Unlike the 12 specialized workflows (which each serve specific purposes), Visualize analyzes your content and chooses the optimal visualization strategy — which may be one approach, or a sophisticated combination of multiple techniques.

**Use this workflow when:**
- You have content but aren't sure what visualization approach to use
- The content has multiple dimensions (data + narrative + concepts)
- You want the most effective visualization, not a predetermined format
- You're asking "what's the best way to visualize this?"
- You want to leverage Nano Banana Pro's full capabilities

**This workflow DOES NOT use:**
- Predetermined templates
- One-size-fits-all approaches
- Single-mode visualizations when combinations would be better

---

## Nano Banana Pro Capabilities

**Understanding what's possible:**

### Core Strengths
1. **Exceptional text rendering** — Clean typography, readable labels, multiple text tiers
2. **Data visualization** — Charts, graphs, quantitative displays
3. **Infographic composition** — Multi-element layouts, mixed media
4. **Iconic illustration** — Simple recognizable symbols and icons
5. **Multi-panel layouts** — Grids, sequences, comparative layouts
6. **Hybrid compositions** — Data + illustration + typography together
7. **Slide-quality output** — Presentation-ready visualizations

### What Nano Banana Pro Excels At
- **Text-heavy compositions** — Infographics with lots of labels
- **Data + context** — Numbers with explanatory illustrations
- **Icon systems** — Repeated simplified icons showing quantities
- **Multi-tier typography** — Clear hierarchies (titles, labels, annotations)
- **Mixed media** — Charts alongside illustrations
- **Grid layouts** — Organized multi-element compositions
- **Comparative panels** — Side-by-side or sequential comparisons

---

## 🚨 MANDATORY WORKFLOW STEPS

### Step 1: Deep Content Analysis (MANDATORY - Use UltraThink)

**🎯 CRITICAL: Use extended thinking to analyze content thoroughly before proceeding.**

Analyze the content across these dimensions:

#### A. Content Type Identification
What types of information are present?
- [ ] Quantitative data (numbers, statistics, metrics)
- [ ] Qualitative concepts (ideas, principles, arguments)
- [ ] Narrative elements (stories, sequences, transformations)
- [ ] Comparative elements (X vs Y, before/after, tradeoffs)
- [ ] Hierarchical structures (taxonomies, frameworks, levels)
- [ ] Temporal elements (timelines, evolution, progressions)
- [ ] Spatial relationships (maps, territories, domains)
- [ ] Process flows (steps, recipes, methodologies)

#### B. Communication Goal
What's the primary purpose?
- Explain a complex concept → Conceptual visualization
- Show data insights → Data visualization dominant
- Compare alternatives → Comparison/split approach
- Tell a story → Sequential/narrative visualization
- Organize information → Taxonomy/grid approach
- Guide action → Process/recipe format
- Make memorable → Metaphor + data hybrid

#### C. Audience Context
Who's this for?
- Technical audience → More data, precision, structure
- General audience → More metaphor, simplification, narrative
- Executive audience → High-level insights, clear takeaways
- Social media → Punchy, scannable, shareable
- Consulting deliverable → Professional, multi-faceted, comprehensive

#### D. Complexity Assessment
How much information needs to be conveyed?
- **Simple (1-2 key points):** Single focused visualization
- **Medium (3-5 dimensions):** Hybrid or two-element composition
- **Complex (6+ dimensions):** Multi-panel infographic or dashboard

**Output from Analysis:**
```
CONTENT TYPE: [Primary and secondary types from above]
INFORMATION DENSITY: [Simple / Medium / Complex]
COMMUNICATION GOAL: [Primary purpose]
AUDIENCE: [Who this is for]

KEY ELEMENTS TO VISUALIZE:
1. [Element type: data/concept/narrative/etc.]
2. [Element type]
3. [Element type]
...

VISUALIZATION OPPORTUNITIES:
- Data points that could be charts/graphs
- Concepts that need metaphors or icons
- Comparisons that need side-by-side
- Sequences that need panels or flow
- Hierarchies that need taxonomies or frameworks
```

---

### Step 2: Visualization Strategy Selection (MANDATORY - Use UltraThink)

**Based on Step 1 analysis, determine the optimal approach:**

#### Strategy Options

**A. SINGLE-MODE (Use one specialized workflow)**
When content clearly fits one visualization type:
- Pure data → Create data visualization
- Pure concept → Use editorial illustration or framework
- Pure comparison → Use comparison workflow
- Pure process → Use recipe card workflow

**B. HYBRID COMPOSITION (Combine 2-3 elements)**
When content has multiple dimensions:
- **Data + Metaphor:** Chart/graph with editorial illustration accent
- **Data + Process:** Numbers showing outcomes at each step
- **Concept + Structure:** Framework with illustrated metaphors in quadrants
- **Timeline + Data:** Progression with quantitative milestones
- **Comparison + Data:** Split screen with metrics on each side

**C. MULTI-PANEL INFOGRAPHIC (Dashboard approach)**
When content is complex and multifaceted:
- **Grid layout:** 4-6 panels each showing different aspect
- **Layered composition:** Top section data, middle concepts, bottom process
- **Dashboard:** Multiple charts/graphs with unified design
- **Slide series:** Sequential slides each focusing on one dimension

#### Decision Framework

```
IF content has 1 primary dimension:
  → Use specialized workflow directly

IF content has 2-3 dimensions of equal importance:
  → Design HYBRID composition

IF content has 4+ distinct dimensions:
  → Design MULTI-PANEL infographic

IF content is primarily quantitative:
  → Lead with DATA VISUALIZATION
  → Add conceptual elements as context

IF content is primarily conceptual:
  → Lead with METAPHOR/FRAMEWORK
  → Add data as supporting evidence

IF content tells a story:
  → Use SEQUENTIAL approach
  → Could be comic, timeline, or multi-step
```

**Output from Strategy Selection:**
```
VISUALIZATION STRATEGY: [Single-mode / Hybrid / Multi-panel]

CHOSEN APPROACH:
[Describe the specific visualization approach]

COMPOSITION ELEMENTS:
Primary element (60-70%): [Type and purpose]
Secondary element (20-30%): [Type and purpose]
Tertiary element (10%): [Type and purpose - optional]

LAYOUT STRUCTURE:
[Describe how elements are arranged spatially]

ASPECT RATIO: [1:1 / 16:9 / 9:16 / 4:3]
Rationale: [Why this ratio for this content]
```

---

### Step 3: Design Composition (MANDATORY - Use UltraThink)

**Plan the visual hierarchy and spatial organization:**

#### A. Spatial Layout
Design how elements occupy the canvas:

**For Single-Mode:**
- Follow the specialized workflow's layout guidelines
- Optimize for Nano Banana Pro's strengths

**For Hybrid Composition:**
```
Example: Data + Metaphor
┌─────────────────────────────────────┐
│                                     │
│    [TITLE - Advocate Block]         │
│                                     │
│  ┌───────────┐   ┌──────────────┐  │
│  │           │   │              │  │
│  │   DATA    │   │  METAPHOR    │  │
│  │   CHART   │   │ ILLUSTRATION │  │
│  │           │   │              │  │
│  └───────────┘   └──────────────┘  │
│        40%              40%         │
│                                     │
│  [Explanatory text - 20%]          │
│                                     │
└─────────────────────────────────────┘
```

**For Multi-Panel Infographic:**
```
Example: Dashboard Grid
┌─────────────────────────────────────┐
│  [OVERALL TITLE]                    │
├─────────────┬───────────────────────┤
│  Panel 1:   │   Panel 2:            │
│  Data viz   │   Concept diagram     │
├─────────────┼───────────────────────┤
│  Panel 3:   │   Panel 4:            │
│  Timeline   │   Key stat + icon     │
├─────────────┴───────────────────────┤
│  [Synthesis/Conclusion panel]       │
└─────────────────────────────────────┘
```

#### B. Visual Hierarchy
Establish information priority:
1. **Primary (Immediate attention):** 50-60% of visual weight
2. **Secondary (Supporting context):** 25-35% of visual weight
3. **Tertiary (Details/annotations):** 10-15% of visual weight

#### C. Typography System
Apply 3-tier system across all elements:
- **Tier 1 (Advocate Block):** Main title, section headers
- **Tier 2 (Concourse Sans):** Data labels, chart axes, element labels
- **Tier 3 (Advocate Condensed Italic):** Annotations, insights, Daniel's voice

#### D. Color Strategy
Maintain UL aesthetic while supporting information hierarchy:
- **Black #000000:** Primary structure (chart axes, borders, main elements)
- **Purple #4A148C:** Critical insights, key data points, optimal zones
- **Teal #00796B:** Secondary data, supporting elements, context
- **Charcoal #2D2D2D:** All body text and labels
- **Background:** Light cream #F5E6D3 or white #FFFFFF

Strategic color use:
- Don't color everything
- Purple for "look here" moments
- Teal for supporting information
- Black for structure and clarity

**Output from Design:**
```
COMPOSITION LAYOUT:
[Detailed spatial description or ASCII diagram]

VISUAL HIERARCHY:
Primary (50-60%): [Element and placement]
Secondary (25-35%): [Element and placement]
Tertiary (10-15%): [Element and placement]

TYPOGRAPHY ASSIGNMENTS:
Tier 1: [Where used - titles, headers]
Tier 2: [Where used - labels, axes]
Tier 3: [Where used - annotations, insights]

COLOR CODING:
Purple: [Specific elements to highlight]
Teal: [Supporting elements]
Black: [Structural elements]
Text: All charcoal

ELEMENT SPECIFICATIONS:
[For each major element, specify:]
- Type (chart/icon/illustration/text)
- Size (% of canvas)
- Position (coordinates or relative placement)
- Style (data viz / editorial / typographic)
```

---

### Step 4: Construct Comprehensive Prompt (MANDATORY - Use UltraThink)

**Build the generation prompt leveraging Nano Banana Pro's capabilities:**

#### Prompt Structure Template

```
[VISUALIZATION TYPE] in editorial infographic style optimized for Nano Banana Pro.

OVERALL CONCEPT: "[What this visualization communicates]"

STYLE REFERENCE: [Professional infographic / Data journalism / Editorial slide / Mixed media visualization]

BACKGROUND: [Light Cream #F5E6D3 / White #FFFFFF] — flat, clean

AESTHETIC:
- Professional infographic quality (deliverable standard)
- Hand-drawn editorial elements where appropriate
- Clean data visualization where precise
- Variable stroke weight (thicker for structure, thinner for details)
- Flat colors, no gradients or shadows
- Readable at multiple scales (works as thumbnail and full-size)

ASPECT RATIO: [1:1 / 16:9 / 9:16 / 4:3]

COMPOSITION STRUCTURE:
[Detailed description of spatial layout]

TYPOGRAPHY SYSTEM (3-TIER HIERARCHY):

TIER 1 - MAIN TITLE (Advocate Block Display):
- "[TITLE TEXT]"
- Font: Advocate style, extra bold, hand-lettered, all-caps
- Size: [Large - 3x body text / Massive - fills header]
- Color: Black #000000 (or Purple #4A148C for emphasis)
- Position: [Top center / Top left / etc.]

TIER 2 - ELEMENT LABELS (Concourse Sans):
- [List all labels: chart axes, data labels, section headers]
- Font: Concourse geometric sans-serif, clean, modern
- Size: Medium readable
- Color: Charcoal #2D2D2D
- Positions: [Specify for each]

TIER 3 - ANNOTATIONS (Advocate Condensed Italic):
- [List all annotations and insights]
- Font: Advocate condensed italic (Daniel's voice)
- Size: Small (60% of Tier 2)
- Color: Purple #4A148C (insights) or Teal #00796B (technical notes)
- Positions: [Near relevant elements]

[FOR EACH MAJOR ELEMENT IN COMPOSITION:]

ELEMENT 1: [TYPE - e.g., Bar Chart / Line Graph / Icon Grid]
- Purpose: [What this element communicates]
- Position: [Location in composition]
- Size: [Dimensions or % of canvas]
- Data to show: [Specific data points or values]
- Style: [Precise data viz / Hand-drawn editorial / Hybrid]
- Color: Black structure, Purple highlights on [specific], Teal on [specific]
- Labels: [Tier 2 typography for all labels]
- Details: [Any specific styling notes]

ELEMENT 2: [TYPE - e.g., Editorial Illustration / Framework Diagram]
- Purpose: [What this element communicates]
- Position: [Location in composition]
- Size: [Dimensions or % of canvas]
- Content: [What to illustrate]
- Style: [Hand-drawn / Iconic / Metaphorical]
- Color: Black linework, Purple accents on [specific]
- Integration: [How it relates to other elements]

[Continue for all elements...]

COLOR USAGE (Strategic, not overwhelming):
- Black (#000000): [All primary structure, chart elements, borders]
- Deep Purple (#4A148C): [Critical data points, key insights, optimal zones]
- Deep Teal (#00796B): [Secondary data, supporting elements]
- Charcoal (#2D2D2D): [All text labels and annotations]
- Background: [Light Cream or White]

CRITICAL REQUIREMENTS FOR NANO BANANA PRO:
- Exceptional text rendering required (multiple labels, clean typography)
- Data precision where needed (accurate chart rendering)
- Hand-drawn editorial quality where appropriate
- Multi-element composition with clear visual hierarchy
- Professional infographic / slide quality
- Readable at both thumbnail and full resolution
- No gradients, flat colors only
- Strategic color (not every element colored)
- All elements work together as unified composition

VALIDATION CHECKPOINTS:
- Is the primary message immediately clear?
- Can each element be read/understood independently?
- Do elements work together to tell complete story?
- Is typography hierarchy obvious?
- Are data elements accurate and precise?
- Do editorial elements enhance (not distract from) information?

Sign "{{{assistantName}}}" small in bottom right corner in charcoal (#2D2D2D).
```

---

### Step 5: Generate with Nano Banana Pro

**Execute the visualization:**

```bash
bun run ${PAI_DIR}/skills/art/tools/generate-ulart-image.ts \
  --model nano-banana-pro \
  --prompt "[YOUR COMPREHENSIVE PROMPT]" \
  --size 2K \
  --aspect-ratio [chosen ratio] \
  --output /path/to/visualization.png
```

**Why Nano Banana Pro for this workflow:**
- Best text rendering among all models (critical for infographics)
- Handles complex multi-element compositions well
- Excellent at data visualization elements
- Can combine precise (charts) with expressive (editorial) styles
- Reliable for professional deliverable quality

**Immediately open for review:**
```bash
open /path/to/visualization.png
```

---

### Step 6: Comprehensive Validation (MANDATORY)

**Validate across multiple dimensions:**

#### Information Effectiveness
- [ ] **Primary message clear:** Main insight obvious within 3 seconds
- [ ] **Data accuracy:** Numbers, proportions, relationships accurate
- [ ] **Visual hierarchy works:** Eye flows from primary → secondary → tertiary
- [ ] **All elements readable:** Text legible, charts clear, icons recognizable
- [ ] **Story cohesion:** Elements work together, not competing

#### Design Quality
- [ ] **Professional deliverable:** Client/publication ready
- [ ] **UL aesthetic maintained:** Flat colors, appropriate hand-drawn vs precise
- [ ] **Typography hierarchy clear:** 3 tiers obviously distinct
- [ ] **Color strategic:** Purple/teal highlight key elements, not overwhelming
- [ ] **Composition balanced:** Visual weight distributed appropriately

#### Technical Execution
- [ ] **Text rendering clean:** No blurry or malformed letters
- [ ] **Data viz precision:** Charts/graphs accurate and clear
- [ ] **Scale works:** Readable as thumbnail AND full-size
- [ ] **No gradients/shadows:** Flat aesthetic maintained
- [ ] **Aspect ratio appropriate:** Format suits content and use case

#### Audience Appropriateness
- [ ] **Matches audience sophistication:** Not too simple or too complex
- [ ] **Serves communication goal:** Actually achieves intended purpose
- [ ] **Platform optimized:** Works for intended distribution (social/email/presentation)

#### If Validation Fails

**Common issues and fixes:**

| Problem | Diagnosis | Fix |
|---------|-----------|-----|
| **Too cluttered** | Too many elements competing | Simplify: reduce to 2-3 main elements, increase whitespace |
| **Message unclear** | No clear visual hierarchy | Strengthen primary element (make larger, add purple), reduce secondary |
| **Text unreadable** | Font too small or wrong tier | Increase label sizes, strengthen typography tier differentiation |
| **Data imprecise** | Chart rendering issues | Add specific data points in prompt, request precision explicitly |
| **Looks generic** | Missing UL aesthetic | Add hand-drawn editorial elements, strategic purple/teal, flatten any gradients |
| **Elements disconnected** | Poor composition | Redesign spatial layout, add visual connectors (arrows, borders, grouping) |
| **Color chaos** | Too much color everywhere | Limit purple to 2-3 key elements, teal to 1-2 supporting, rest black/charcoal |
| **Not professional** | Too sketchy or too rigid | Balance: data viz precise, editorial elements hand-drawn, clean typography |

**Regeneration Process:**
1. Identify specific validation failures
2. Update prompt with targeted fixes
3. Regenerate with refined prompt
4. Re-validate against all checkpoints
5. Repeat until ALL validation criteria pass

**CRITICAL: Do not declare completion until validation passes.**

---

## Visualization Pattern Library

**Common effective combinations:**

### Pattern 1: Data + Metaphor Hybrid
**When:** Data needs conceptual context
**Layout:** 50% data visualization + 40% editorial illustration + 10% explanatory text
**Example:** Growth chart with rocket ship illustration showing trajectory
**Aspect:** 16:9 or 1:1

### Pattern 2: Comparative Dashboard
**When:** Analyzing multiple dimensions of comparison
**Layout:** Split or grid with data on each side/panel
**Example:** "Before AI vs After AI" with metrics and illustrations for each state
**Aspect:** 16:9 (split) or 1:1 (grid)

### Pattern 3: Process + Outcomes
**When:** Showing methodology with results
**Layout:** Vertical or horizontal flow with data at key milestones
**Example:** 5-step recipe with success metrics at each step
**Aspect:** 9:16 (vertical) or 16:9 (horizontal)

### Pattern 4: Icon Quantification
**When:** Showing quantities through repeated visual elements
**Layout:** Grid of icons where quantity = visual count
**Example:** "78 out of 100 developers" shown as 78 purple icons + 22 gray icons
**Aspect:** 1:1 or 4:3

### Pattern 5: Annotated Data Story
**When:** Data needs narrative explanation
**Layout:** Primary chart with hand-drawn annotations explaining insights
**Example:** Timeline chart with purple arrows: "*this is when everything changed*"
**Aspect:** 16:9 or 21:9

### Pattern 6: Multi-Chart Dashboard
**When:** Multiple related datasets
**Layout:** Grid of 2-4 charts with unified design language
**Example:** 4-panel view: bar chart, line graph, pie chart, key stat
**Aspect:** 16:9 or 1:1

### Pattern 7: Framework + Data
**When:** Conceptual model with quantitative evidence
**Layout:** Framework structure (2x2, Venn, pyramid) with data in each zone
**Example:** 2x2 matrix with percentage of companies in each quadrant
**Aspect:** 1:1

### Pattern 8: Infographic Slide
**When:** Comprehensive content for presentation
**Layout:** Title + multiple small visualizations + key takeaway
**Example:** Slide with 3 mini-charts + 2 key stats + insight annotation
**Aspect:** 16:9 (slide format)

---

## Decision Tree Summary

```
START: Analyze content deeply (Step 1)
   ↓
Is content primarily ONE dimension?
   ├─ YES → Use specialized workflow directly
   │         (Editorial / Technical / Timeline / etc.)
   │
   └─ NO → Content has multiple dimensions
             ↓
       Are there 2-3 equal dimensions?
          ├─ YES → HYBRID composition
          │         Design complementary elements
          │         (Data + Metaphor, Process + Outcomes, etc.)
          │
          └─ NO → 4+ dimensions or very complex
                    ↓
                  MULTI-PANEL infographic
                  Grid or layered dashboard approach
                  Each panel addresses one dimension

For HYBRID or MULTI-PANEL:
   ↓
Design composition (Step 3)
   → Spatial layout
   → Visual hierarchy
   → Typography tiers
   → Color strategy
   ↓
Construct comprehensive prompt (Step 4)
   → Detailed element specifications
   → Leverage Nano Banana Pro strengths
   → Clear validation checkpoints
   ↓
Generate with nano-banana-pro (Step 5)
   ↓
VALIDATE comprehensively (Step 6)
   → Information effectiveness
   → Design quality
   → Technical execution
   → Audience appropriateness
   ↓
PASS? → Complete
FAIL? → Diagnose, fix, regenerate
```

---

## Quick Reference

### When to Use Visualize Workflow
- Content has multiple dimensions to visualize
- You want optimal approach, not predetermined format
- Combining data + concepts + narrative
- Creating professional infographics or slides
- Need sophisticated composition beyond single workflow

### Nano Banana Pro Advantages
- Best text rendering (critical for labels/annotations)
- Multi-element composition handling
- Data visualization capabilities
- Professional infographic quality
- Hybrid precision + expressiveness

### Core Principles
1. **Analyze first** — Deep content analysis before choosing approach
2. **Strategic combination** — Use hybrid only when it serves content
3. **Visual hierarchy** — Clear primary/secondary/tertiary structure
4. **Color discipline** — Purple/teal strategic, not everywhere
5. **Professional quality** — Deliverable to clients/publications
6. **Validate thoroughly** — Information + design + technical + audience

---

**The workflow: Analyze → Strategy → Design → Prompt → Generate → Validate → Complete**

**The meta-principle: Let content dictate form. Use the full power of Nano Banana Pro to create the most effective visualization, whether that's one approach or a sophisticated orchestration of multiple techniques.**

```

### workflows/Workflow.md

```markdown
# UL Art Image Generation Workflow

**Single consolidated workflow for creating editorial illustrations in the Anthropic style.**

Creates **ONE ABSTRACT VISUAL METAPHOR** — flat colors, hand-drawn black linework, muted earth tones.

---

## 🚨 MANDATORY STEPS — EXECUTE IN ORDER

**CRITICAL: ALL 6 STEPS ARE MANDATORY. Execute them IN ORDER. Do NOT skip steps. Do NOT improvise your own process.**

**VIOLATION:** If you skip Step 1 (CSE) and derive concepts yourself, you are violating this workflow.

```
INPUT CONTENT
     ↓
[1] CSE: Run /cse command to extract core thesis ← MANDATORY, DO NOT SKIP
     ↓
[2] CONCEPT: Derive visual metaphor from LINE 8 of CSE output ← MANDATORY
     ↓
[3] AESTHETIC: Apply Anthropic editorial style (flat, hand-drawn, earth tones)
     ↓
[4] PROMPT: Construct with UltraThink
     ↓
[5] GENERATE: Execute CLI tool
     ↓
[6] VALIDATE: Flat? Hand-drawn? No gradients? Abstract?
```

---

## Step 1: Run 24-Item Story Explanation — MANDATORY

**Use the story-explanation skill to extract the FULL narrative arc.**

Invoke the story-explanation skill directly and request **24-item length**:

```
Use story-explanation skill with 24-item length for [URL or content]
```

This produces a 24-item numbered story explanation that captures the complete narrative journey: setup, tension, transformation, resolution.

**Why 24 items (not 8):**
- Captures the FULL story arc, not just the conclusion
- Shows transformation/process/journey
- Provides rich texture for visual metaphor derivation
- Editorial illustration should show STORY, not just endpoint

**Output:** 24-item story explanation with the complete narrative arc.

---

## Step 2: Derive Visual Concept from FULL NARRATIVE ARC — MANDATORY

**From the 24-item story explanation, use ALL items to construct a composition that captures the journey.**

**DO NOT derive concepts without running 24-item story explanation first. The concept MUST come from the FULL narrative arc (all 24 items).**

### The Key Question

Look at your 24-item story explanation and ask: **What single composition captures the TRANSFORMATION/JOURNEY/PROCESS?**

**Not just the endpoint - show the ARC:**
- What changes from beginning to end?
- What's the core tension or transformation?
- Can you show MOVEMENT or PROGRESSION?
- What visual metaphor captures the FULL story?

### Physical Conceptual Metaphors Showing JOURNEY

**CRITICAL REQUIREMENT: Concepts MUST use PHYSICAL RECOGNIZABLE objects and actions.**

The concept should be describable in ONE sentence with 2-3 PHYSICAL elements that show TRANSFORMATION:

✅ **GOOD (Physical/Recognizable):**
- "Scissors cutting through a tangled ball of yarn" (physical objects: scissors, yarn; action: cutting)
- "A robot hand and human hand pulling opposite ends of an em dash" (physical objects: hands, em dash; action: pulling)
- "Puzzle pieces being assembled by gestural hands" (physical objects: puzzle pieces, hands; action: assembling)
- "Hands reaching upward toward abstract mountains" (physical objects: hands, mountains; action: reaching)

❌ **BAD (Abstract/Geometric):**
- "A timeline: dense circles → sparse → dense again" (abstract shapes, no recognizable objects)
- "Flowing geometric transformation from chaos to order" (conceptual diagram, not physical scene)
- "Abstract shapes representing data flow" (requires explanation, not instantly readable)

### How to Derive Concept from 24 Items

1. **Read ALL 24 items** — Understand the complete narrative arc
2. **Identify the transformation** — What changes? What's the journey?
3. **Find a PHYSICAL metaphor that shows PROCESS** — Use recognizable objects/actions, NOT abstract shapes
4. **Apply "Instant Picture Test"** — Can you close your eyes and picture this like a photograph?
5. **Reduce to 2-3 PHYSICAL elements** — Scissors, hands, yarn, puzzle pieces, etc. (NOT circles, rectangles, flowing lines)
6. **Ensure it's immediately readable** — No explanation needed, viewer instantly gets it

**Key insight:** Use the RICHNESS of all 24 items to inform a composition that shows JOURNEY through PHYSICAL OBJECTS AND ACTIONS, not abstract geometric representations.

**MANDATORY VALIDATION before proceeding:**
- [ ] Uses recognizable physical objects (scissors, hands, yarn, etc.) ✅
- [ ] Shows clear action (cutting, pulling, assembling, reaching) ✅
- [ ] Passes "Instant Picture Test" - can picture it like a photograph ✅
- [ ] Does NOT use abstract shapes (circles, flowing lines, geometric forms) ❌
- [ ] Does NOT require explanation ("this represents...") ❌

**Output:** ONE sentence describing 2-3 PHYSICAL elements with CLEAR ACTION that capture the narrative ARC.

---

## Step 3: Apply Anthropic Editorial Aesthetic

**Convert your concept into the flat, hand-drawn style.**

### Read the Aesthetic Source

**Always read:** `${PAI_DIR}/skills/CORE/aesthetic.md`

### Core Visual Rules

1. **Background:** Single flat muted earth tone — NO gradients
2. **Linework:** Hand-drawn black ink — imperfect, gestural, variable weight
3. **Style:** Saul Steinberg / New Yorker / risograph aesthetic
4. **Composition:** Objects fill 40-60% of frame, 30-40% negative space
5. **Elements:** 2-3 abstract elements maximum
6. **{{{assistantName}}} Signature:** Small charcoal (#2D2D2D) bottom right

### Color System

**Background:** WHITE #FFFFFF for generation → remove.bg creates TRANSPARENCY

**Primary:** Black linework (#000000) — DOMINANT, carries composition

**Accents (SPARINGLY):**
| Color | Hex | Usage |
|-------|-----|-------|
| Deep Purple | #4A148C | Brand accent - REQUIRED but subtle |
| Deep Teal | #00796B | Secondary accent option |

### Map Your Concept

```
CONCEPT: [Your concept from Step 2]
BACKGROUND: [Pick one color from palette]
ELEMENTS: [2-3 abstract shapes/objects]
LINEWORK: Hand-drawn black, imperfect, gestural
```

**Output:** Your concept translated into the Anthropic aesthetic.

---

## Step 3.5: MANDATORY VALIDATION CHECKPOINT

**STOP. Before constructing the prompt, validate your concept:**

Run through this checklist. If ANY check fails, go back to Step 2 and redesign the concept.

✅ **Physical Object Check:**
- [ ] My concept uses recognizable physical objects (scissors, hands, yarn, puzzle pieces, mountains, etc.)
- [ ] I am NOT using abstract shapes (circles, rectangles, geometric forms, flowing lines)

✅ **Instant Picture Test:**
- [ ] I can close my eyes and picture this scene like a photograph
- [ ] Someone else could draw this from my one-sentence description without further explanation

✅ **Action Check:**
- [ ] My concept shows a clear physical action (cutting, pulling, assembling, reaching, untangling)
- [ ] The action is visible and dynamic

✅ **Readability Check:**
- [ ] The metaphor is immediately readable without explanation
- [ ] I don't need to say "this represents..." to explain what it means

**If all checks pass:** Proceed to Step 4
**If any check fails:** Return to Step 2 and find a PHYSICAL metaphor

---

## Step 4: Construct the Prompt Using UltraThink

**Use UltraThink (extended thinking) to construct the final prompt.**

### Prompt Template

```
Editorial conceptual illustration in Saul Steinberg / New Yorker style.

WHITE BACKGROUND (#FFFFFF) for transparency removal.

STYLE: Hand-drawn black ink linework with these characteristics:
- Variable stroke weight (thicker where pressure would be)
- Imperfect, slightly wobbly lines (human quality)
- Gestural brush strokes, NOT smooth vectors
- Risograph / editorial aesthetic

COMPOSITION (2-3 elements only):
[Describe your abstract metaphor with specific elements]
Elements drawn with bold BLACK LINEWORK as primary.
Purple (#4A148C) as small ACCENT details only.
[Optional secondary accent color] as subtle accent.

COLORS:
- BLACK is the PRIMARY color for all linework and main shapes
- Deep Purple #4A148C as small ACCENT only (hints, not dominant)
- [Secondary accent] sparingly

The image should be predominantly BLACK LINEWORK with color used sparingly as accents.

COMPOSITION: Full-bleed edge-to-edge. NO whitespace or margins.
Elements extend to or bleed off all edges. 100% frame fill.

CRITICAL REQUIREMENTS:
- FLAT colors only — NO gradients, NO shading
- NO shadows of any kind
- Lines must look hand-drawn, NOT perfect vectors
- Color is ACCENT only, black linework dominates

Sign "{{{assistantName}}}" as a tiny artist signature in charcoal (#2D2D2D) bottom right corner.
NO other text anywhere.
```

**IMPORTANT:** Always use `--remove-bg` flag to create transparency.

### Prompt Quality Check

Before generating, verify:
- [ ] ONE composition, not multiple panels
- [ ] 2-3 elements maximum
- [ ] Background color specified with hex
- [ ] "Hand-drawn", "imperfect", "gestural" explicitly stated
- [ ] "NO gradients" explicitly stated
- [ ] "Saul Steinberg" or "New Yorker" style reference
- [ ] SPECIFIC to this content (couldn't be about something else)

**Output:** A complete prompt ready for generation.

---

## Step 5: Execute the Generation

### Default Model: nano-banana-pro

```bash
bun run ${PAI_DIR}/skills/art/tools/generate-ulart-image.ts \
  --model nano-banana-pro \
  --prompt "[YOUR PROMPT]" \
  --size 2K \
  --aspect-ratio 1:1 \
  --output /path/to/output.png
```

### Alternative Models

| Model | Command | When to Use |
|-------|---------|-------------|
| **flux** | `--model flux --size 1:1` | Maximum quality |
| **gpt-image-1** | `--model gpt-image-1 --size 1024x1024` | Different interpretation |

### Immediately Open

```bash
open /path/to/output.png
```

---

## Step 6: Validation (MANDATORY - DO NOT SKIP)

**🚨 CRITICAL: This step is MANDATORY. You MUST validate the image and regenerate if validation fails. DO NOT declare completion without passing validation.**

### Validation Procedure

1. **Open the generated image** for visual inspection:
```bash
open /path/to/generated-image.png
```

2. **Check ALL criteria below** - If ANY fail, you MUST regenerate

3. **Do NOT proceed** to next steps until validation passes

### Must Have (ALL REQUIRED)
- [ ] **Flat background** — Single solid color, zero gradients
- [ ] **Hand-drawn quality** — Lines are imperfect, variable weight
- [ ] **Black linework** — Not colored lines, not smooth vectors
- [ ] **Abstract metaphor** — Conceptual, not literal
- [ ] **Full-bleed composition** — NO whitespace or margins, elements fill 100% of frame edge-to-edge
- [ ] **Square aspect ratio** — 1:1 format (NOT 16:9 rectangle)
- [ ] **Elements extend to edges** — Composition bleeds off all sides (NOT centered with margins)
- [ ] **Muted earth tone** — Cream/terracotta/sage/peach background (if not transparent)
- [ ] **🎨 COLOR PRESENCE (CRITICAL)** — Purple (#4A148C) and/or Teal (#00796B) MUST be visible and noticeable
  - NOT microscopic hints - should be immediately apparent
  - If you need to zoom in to see color, it's TOO SUBTLE
  - Color should be visible at normal viewing distance
  - Balance: accent, not dominant, but definitely present

### Must NOT Have (ALL FORBIDDEN)
- [ ] Any gradients anywhere
- [ ] Shadows or glows
- [ ] 3D rendering or depth
- [ ] Glossy/shiny surfaces
- [ ] Smooth perfect vector lines
- [ ] Saturated or cool colors
- [ ] Photorealistic elements
- [ ] Too little color (all black with microscopic purple)

### If Validation Fails - REGENERATION REQUIRED

**DO NOT SKIP THIS STEP. If validation fails, you MUST regenerate.**

Common failures and fixes:

| Problem | Fix |
|---------|-----|
| **Not enough color** | Strengthen color requirement: "Deep Purple #4A148C must be VISIBLE and NOTICEABLE - not microscopic. Use on at least 5-10% of main elements. Should be immediately visible when viewing image." |
| Has gradients | Add "FLAT colors only, absolutely NO gradients" more emphatically |
| Lines too smooth | Emphasize "imperfect wobbly hand-drawn brush strokes" |
| Too shiny/glossy | Add "matte, flat, risograph aesthetic" |
| Too detailed | Simplify concept, "minimal abstract" |
| Wrong colors | Specify exact hex codes, "muted earth tones only" |
| Looks like AI art | Reference "Saul Steinberg", "Matisse cutouts", "risograph" |

**Regeneration Process:**
1. Identify which validation criteria failed
2. Update prompt with specific fixes from table above
3. Regenerate using same command with adjusted prompt
4. Open new image and re-validate
5. Repeat until ALL validation criteria pass
6. Only then proceed to completion

**CRITICAL: You are NOT done until validation passes. Declaring completion without validation is a failure.**

---

## Quick Reference

### The Key Insight

**24-ITEM STORY → NARRATIVE ARC → VISUAL JOURNEY → FLAT HAND-DRAWN EDITORIAL**

1. Run 24-item story explanation to get FULL narrative arc
2. Use ALL 24 items to understand transformation/journey/process
3. Find ONE visual metaphor that shows the ARC (not just endpoint)
4. Reduce to 2-3 abstract elements that show MOVEMENT/CHANGE
5. Generate with flat background + hand-drawn black linework

Bad: "Detailed illustration of a complex scene with multiple characters"
Good: "Timeline showing dense circles → sparse → dense again with arrows" (shows journey)
Good: "Scissors mid-cut through tangled yarn ball" (shows process)

### Models

| Model | Command | Best For |
|-------|---------|----------|
| **nano-banana-pro** (DEFAULT) | `--model nano-banana-pro --size 2K --aspect-ratio 1:1` | High quality, good adherence |
| **flux** | `--model flux --size 1:1` | Maximum quality, slower |
| **gpt-image-1** | `--model gpt-image-1 --size 1024x1024` | Minimalism, alternative |

### The Anthropic Look Checklist

Before submitting any image:
- ✅ Flat solid background (cream/terracotta/sage/peach or transparent)
- ✅ Black hand-drawn linework (imperfect, gestural)
- ✅ Abstract conceptual metaphor
- ✅ Full-bleed edge-to-edge composition (NO whitespace or margins)
- ✅ Square 1:1 aspect ratio (NOT 16:9)
- ✅ Elements extend to or bleed off all edges (100% frame fill)
- ✅ 2-3 elements maximum
- ✅ No gradients, shadows, or shine
- ✅ {{{assistantName}}} signature bottom right
- ✅ **COLOR VISIBLE** - Purple and/or Teal must be noticeable (not microscopic)

---

**The workflow: CSE → Concept → Flat Editorial Prompt → Generate → VALIDATE (MANDATORY) → Regenerate if needed → Complete**

```

### workflows/Mermaid.md

```markdown
# Mermaid-Style Technical Diagrams with Excalidraw Aesthetic

**Hand-drawn technical diagrams combining Mermaid structure with Excalidraw sketchy aesthetic and UL color scheme.**

Creates **EXCALIDRAW-STYLE MERMAID DIAGRAMS** — flowcharts, sequence diagrams, state machines, and other technical diagrams with whiteboard hand-drawn feel, derived from content via story explanation.

---

## Purpose

The Mermaid workflow creates structured technical diagrams (like Mermaid.js generates) but with a **hand-drawn whiteboard aesthetic** (like Excalidraw) while maintaining **UL editorial color scheme**. Unlike generic technical diagrams, these follow specific diagram grammar (flowcharts, sequences, states, etc.) and are derived from content analysis, not hand-specified.

**Use this workflow for:**
- Flowcharts showing decision logic and process flows
- Sequence diagrams showing interactions over time
- State diagrams showing state transitions
- Class diagrams showing object relationships
- ER diagrams showing data models
- Git graphs showing branching/merging
- Any diagram where Mermaid structure + hand-drawn aesthetic is ideal

**This is NOT for:**
- Freeform architecture diagrams (use technical-diagrams.md)
- Abstract conceptual metaphors (use workflow.md editorial illustrations)
- Data visualizations (use visualize.md)

---

## Mermaid Diagram Types Supported

### 1. Flowcharts
**When:** Decision trees, algorithmic logic, process flows with conditions
```
Start → Decision? → [Yes] → Action → End
                 → [No] → Different Action → End
```

### 2. Sequence Diagrams
**When:** Interactions between entities/actors over time
```
User → API: Request
API → Database: Query
Database → API: Results
API → User: Response
```

### 3. State Diagrams
**When:** State machines, status transitions, lifecycle flows
```
[Idle] → (trigger) → [Processing] → (complete) → [Done]
                                  → (error) → [Failed]
```

### 4. Class Diagrams
**When:** Object relationships, inheritance, composition
```
User ──has many──> Posts
User ──belongs to──> Organization
Post ──has many──> Comments
```

### 5. Entity Relationship Diagrams
**When:** Database schemas, data models, table relationships
```
Customer ||──o{ Order : places
Order ||──o{ LineItem : contains
Product ||──o{ LineItem : ordered_in
```

### 6. Gantt Charts
**When:** Project timelines, task dependencies, schedules
```
Task 1: Jan 1 - Jan 15
Task 2: Jan 10 - Jan 30 (depends on Task 1)
Task 3: Jan 20 - Feb 10
```

### 7. Git Graphs
**When:** Branching strategies, merge flows, version control
```
main ──> feature branch ──> merged back ──> main
     └──> hotfix ──────────> merged ──────> main
```

---

## Excalidraw Aesthetic Principles

**Think:** Whiteboard sketch, not polished Visio diagram

### Visual Characteristics
1. **Wobbly boxes** — Rectangles with rough, hand-drawn edges (not perfect)
2. **Sketchy arrows** — Arrows with slight wobble, not ruler-straight
3. **Rough edges** — Everything has organic imperfection
4. **Hand-lettered text** — Labels look handwritten, not typed
5. **Whiteboard feel** — Looks like someone drew this on a whiteboard
6. **Variable line weight** — Heavier for boxes, lighter for arrows
7. **Crossing-out style** — Double-line or rough crossing for connections

### What This Looks Like
- Diamond decision boxes with wobbly edges
- Arrows that curve slightly even when "straight"
- Rectangles that aren't quite rectangular
- Text that's imperfectly aligned
- Circles that are slightly oval
- Lines that overlap at connections with organic joins

### AVOID
- Perfect geometric shapes
- Ruler-straight arrows
- Digital precision
- Smooth curves (too polished)
- Perfect alignment
- Vector crispness

---

## Color System for Mermaid Diagrams

### Structure
```
Black #000000 — All primary linework (boxes, arrows, decision diamonds)
```

### Flow Emphasis
```
Deep Purple #4A148C — Critical path, main flow, important states
Deep Teal #00796B — Alternative paths, secondary flows, supporting states
Charcoal #2D2D2D — All text labels and annotations
```

### Background
```
Light Cream #F5E6D3 — Whiteboard/sketch paper feel
OR
White #FFFFFF — Clean background
```

### Color Strategy for Diagram Types

**Flowcharts:**
- Main path boxes: Purple outlines
- Alternative branches: Teal outlines
- Decision diamonds: Black outlines
- All connecting arrows: Black

**Sequence Diagrams:**
- Critical actor/entity: Purple box
- Secondary actors: Teal boxes
- All messages/arrows: Black
- Activation boxes: Purple fills (subtle)

**State Diagrams:**
- Active/important states: Purple
- Transition states: Teal
- Terminal states: Black
- Arrows: Black with labels

**Class/ER Diagrams:**
- Key entities: Purple boxes
- Related entities: Teal boxes
- Relationships: Black arrows with labels
- Inheritance: Black with different arrow style

---

## 🚨 MANDATORY WORKFLOW STEPS

### Step 1: Run Story Explanation on Content (MANDATORY)

**🎯 CRITICAL: You MUST use /cse (Create Story Explanation) with 24-item length.**

This extracts the full narrative arc and identifies the STRUCTURE that needs to be diagrammed.

```bash
/cse [content or URL]
```

The 24-item output reveals:
- Process flows and sequences
- Decision points and conditions
- State transitions and triggers
- Entity relationships and interactions
- Temporal ordering and dependencies

**Do NOT skip this step. Do NOT manually derive diagram structure without running /cse first.**

**Output from CSE Analysis:**
```
24-ITEM STORY EXPLANATION:
1. [Item 1]
2. [Item 2]
...
24. [Item 24]

STRUCTURAL ELEMENTS IDENTIFIED:
- Processes: [List of distinct processes/actions]
- Decisions: [List of decision points with conditions]
- States: [List of distinct states]
- Entities: [List of actors/objects/components]
- Flows: [List of connections and sequences]
- Conditions: [List of triggers and transitions]
```

---

### Step 2: Determine Optimal Mermaid Diagram Type

**Based on CSE analysis, identify the best diagram type:**

#### Decision Framework

**Choose FLOWCHART when:**
- Content describes process with decision points
- "If/then/else" logic is present
- Multiple paths based on conditions
- Algorithm or procedure being explained
- Clear start and end points

**Choose SEQUENCE DIAGRAM when:**
- Content describes interactions between entities over time
- Request/response patterns present
- Multiple actors communicating
- Temporal ordering is critical
- API calls, messaging, or protocols

**Choose STATE DIAGRAM when:**
- Content describes states and transitions
- Status changes are central
- Lifecycle or workflow states
- Event-driven transitions
- System can be in discrete states

**Choose CLASS/ER DIAGRAM when:**
- Content describes relationships between objects/entities
- Data structures or models
- Inheritance or composition patterns
- Database schemas
- Object hierarchies

**Choose GANTT CHART when:**
- Content describes project timeline
- Task dependencies and schedules
- Milestones and deadlines
- Parallel and sequential tasks

**Choose GIT GRAPH when:**
- Content describes version control workflow
- Branching strategies
- Merge patterns
- Release flows

**Multiple diagram types possible?**
- Choose the PRIMARY type that captures the main structure
- Can note that alternative representations exist
- Focus on the most illuminating visualization

**Output from Type Selection:**
```
DIAGRAM TYPE: [Flowchart / Sequence / State / Class / ER / Gantt / Git Graph]

RATIONALE: [Why this type best represents the content]

ALTERNATIVE TYPES CONSIDERED: [If any, and why not chosen]
```

---

### Step 3: Extract Diagram Structure from CSE

**Map the 24-item story explanation to diagram components:**

#### For Flowcharts
Identify:
- **Start node:** Where does the process begin?
- **Process nodes:** What actions happen? (rectangles)
- **Decision nodes:** What choices are made? (diamonds)
- **End nodes:** Where does it terminate? (rounded rectangles)
- **Flows:** How do nodes connect? (arrows with labels)

#### For Sequence Diagrams
Identify:
- **Actors/Entities:** Who/what participates? (boxes at top)
- **Messages:** What communications occur? (arrows between lifelines)
- **Temporal order:** What sequence? (top to bottom)
- **Activations:** When are entities active? (vertical bars)

#### For State Diagrams
Identify:
- **States:** What are the distinct states? (rounded boxes)
- **Initial state:** Where does it start? (filled circle)
- **Final state:** Where does it end? (double circle)
- **Transitions:** What triggers state changes? (arrows with conditions)
- **Events:** What causes transitions?

#### For Class/ER Diagrams
Identify:
- **Entities/Classes:** What objects exist? (boxes)
- **Attributes:** What properties? (inside boxes)
- **Relationships:** How do they relate? (arrows with cardinality)
- **Inheritance:** What hierarchies? (special arrows)

**Output from Structure Extraction:**
```
DIAGRAM COMPONENTS:

[For Flowchart Example:]
NODES:
- Start: [Label]
- Process 1: [Action description] (rectangle, purple)
- Decision 1: [Question] (diamond, black)
- Process 2a: [Action if yes] (rectangle, purple)
- Process 2b: [Action if no] (rectangle, teal)
- End: [Terminal state] (rounded, black)

FLOWS:
- Start → Process 1: (black arrow)
- Process 1 → Decision 1: (black arrow)
- Decision 1 → Process 2a: "Yes" (black arrow)
- Decision 1 → Process 2b: "No" (black arrow)
- Process 2a → End: (black arrow)
- Process 2b → End: (black arrow)

CRITICAL PATH: [Start → Process 1 → Decision 1 → Process 2a → End]
(This path highlighted with purple boxes)
```

---

### Step 4: Design Excalidraw-Style Layout

**Plan the whiteboard sketch aesthetic:**

#### A. Spatial Arrangement
- **Flowcharts:** Top-to-bottom or left-to-right flow
- **Sequence diagrams:** Actors across top, interactions descending
- **State diagrams:** Circular or network layout
- **Class diagrams:** Hierarchical tree or interconnected network
- **ER diagrams:** Entities spread out with relationships between
- **Gantt:** Horizontal timeline with tasks stacked vertically
- **Git graph:** Branching tree structure

#### B. Hand-Drawn Styling
Each node type gets Excalidraw treatment:

**Rectangles (Process boxes):**
```
Instead of: ┌──────────┐
This:       ╱──────────╲  (wobbly, not perfect)
           │  Process  │  (slightly tilted)
           ╲──────────╱  (organic edges)
```

**Diamonds (Decisions):**
```
Instead of: ◇
This:       ◊  (wobbly, asymmetric, hand-drawn diamond)
```

**Arrows:**
```
Instead of: ────────→
This:       ∼∼∼∼∼∼∼→  (slightly wavy, organic curve)
```

**Text:**
```
Instead of: Arial 12pt
This:       Hand-lettered appearance, slight slant, imperfect
```

#### C. Visual Hierarchy
- **Primary path/flow:** Purple boxes, thicker lines
- **Secondary paths:** Teal boxes, standard lines
- **Structure/framework:** Black lines and shapes
- **Labels/text:** Charcoal, hand-lettered style

**Output from Layout Design:**
```
SPATIAL LAYOUT: [Top-to-bottom flow / Left-to-right / Circular / etc.]

EXCALIDRAW STYLING NOTES:
- All boxes: Wobbly rectangles, slightly tilted
- Arrows: Gentle curves even when "straight"
- Diamonds: Asymmetric, hand-drawn feel
- Circles: Slightly oval, imperfect
- Text: Hand-lettered, natural slant

NODE POSITIONING:
[Describe relative positions, e.g.:]
- Start node: Top center
- Process 1: Below start, slightly left
- Decision 1: Below process 1, centered
- Process 2a: Bottom left (Yes branch)
- Process 2b: Bottom right (No branch)
- End nodes: Bottom (two endpoints merge)

CONNECTION PATHS:
[Describe arrow routes with organic curves]
```

---

### Step 5: Construct Comprehensive Prompt

**Build the generation prompt with Excalidraw + Mermaid + UL aesthetic:**

### Prompt Template

```
Hand-drawn Mermaid [DIAGRAM TYPE] in Excalidraw whiteboard sketch style.

STYLE REFERENCE: Excalidraw whiteboard diagram, hand-drawn flowchart, sketchy technical diagram

BACKGROUND: [Light Cream #F5E6D3 / White #FFFFFF] — whiteboard/sketch paper feel

AESTHETIC:
- Excalidraw hand-drawn style (wobbly, sketchy, organic)
- Whiteboard sketch quality (looks hand-drawn, not digital)
- Rough edges on all shapes (rectangles not perfect, circles slightly oval)
- Sketchy arrows (gentle curves, slight wobble, not ruler-straight)
- Hand-lettered text labels (imperfect alignment, natural slant)
- Variable line weight (boxes thicker, arrows medium, details thinner)
- Organic connections (lines join naturally, small overlaps at nodes)
- NO digital precision, NO perfect geometry, NO smooth vectors

DIAGRAM TYPE: [Flowchart / Sequence Diagram / State Diagram / etc.]

OVERALL STRUCTURE:
[Describe the complete diagram flow, e.g.:]
- [DIAGRAM TYPE] showing [what it represents]
- Layout: [Top-to-bottom / Left-to-right / etc.]
- [Number] main nodes/states/entities
- Critical path highlighted in purple
- Alternative paths in teal

TYPOGRAPHY SYSTEM (3-TIER):

TIER 1 - DIAGRAM TITLE (Advocate Block Display):
- "[DIAGRAM TITLE]"
- Font: Advocate style, hand-lettered, all-caps
- Size: Large but not dominating (10% of diagram height)
- Color: Black #000000
- Position: Top center or top left
- Example: "USER AUTHENTICATION FLOW"

TIER 2 - NODE LABELS (Concourse Sans Hand-lettered):
- Labels inside boxes/nodes
- Font: Concourse-style geometric sans, hand-drawn interpretation
- Size: Medium readable
- Color: Charcoal #2D2D2D
- Style: Slightly imperfect, natural slant
- Examples: "Process Request", "Valid?", "Success State"

TIER 3 - EDGE LABELS (Advocate Condensed):
- Labels on arrows/connections
- Font: Advocate condensed, smaller
- Size: 60% of Tier 2
- Color: Charcoal #2D2D2D
- Style: Hand-written notes along arrows
- Examples: "Yes", "No", "timeout", "success"

DIAGRAM COMPONENTS (Excalidraw Style):

[LIST EACH NODE/COMPONENT:]

NODE 1: [Type - e.g., START NODE]
- Shape: [Rounded rectangle / Circle / etc.]
- Label: "[Label text]"
- Style: Wobbly hand-drawn edges, slightly asymmetric
- Color: Black (#000000) outline, no fill OR subtle cream fill
- Size: [Relative size]
- Position: [Location in layout]

NODE 2: [Type - e.g., PROCESS BOX]
- Shape: Rectangle with rough edges
- Label: "[Action description]"
- Style: Wobbly lines, slightly tilted, hand-drawn imperfection
- Color: Purple (#4A148C) outline — CRITICAL PATH
- Fill: Light cream or transparent
- Size: [Relative size]
- Position: [Below Node 1]

NODE 3: [Type - e.g., DECISION DIAMOND]
- Shape: Diamond/rhombus with wobbly edges
- Label: "[Question?]"
- Style: Hand-drawn, asymmetric diamond, organic edges
- Color: Black (#000000) outline
- Fill: Transparent or very light cream
- Size: [Relative size]
- Position: [Below Node 2, centered]

NODE 4: [Type - e.g., PROCESS BOX - ALTERNATIVE PATH]
- Shape: Rectangle with rough edges
- Label: "[Alternative action]"
- Style: Wobbly lines, slightly tilted
- Color: Teal (#00796B) outline — SECONDARY PATH
- Fill: Light cream or transparent
- Size: [Relative size]
- Position: [To the side, alternative branch]

NODE 5: [Type - e.g., END NODE]
- Shape: Rounded rectangle or double circle
- Label: "[Terminal state]"
- Style: Hand-drawn, organic curves
- Color: Black (#000000) outline
- Fill: Subtle fill or transparent
- Size: [Relative size]
- Position: [Bottom of diagram]

[Continue for all nodes...]

CONNECTIONS (Sketchy Arrows):

ARROW 1: [Node A] → [Node B]
- Style: Sketchy hand-drawn arrow, slight curve even if "straight"
- Path: [Describe route, e.g., "curves gently from Node 1 down to Node 2"]
- Color: Black (#000000)
- Label: [Optional label text, e.g., "process" or condition]
- Arrowhead: Hand-drawn triangle, slightly asymmetric

ARROW 2: [Node C] → [Node D]
- Style: Sketchy arrow with organic wobble
- Path: [Describe route]
- Color: Black (#000000)
- Label: "[Yes]" in small hand-written style
- Arrowhead: Rough triangle

[Continue for all arrows/connections...]

SPECIAL ELEMENTS (if applicable):

[For Sequence Diagrams:]
- Actor boxes: Hand-drawn rectangles at top
- Lifelines: Dashed vertical lines (hand-drawn, wobbly)
- Activation boxes: Rectangles on lifelines (purple for key)
- Messages: Arrows between lifelines with labels

[For State Diagrams:]
- Initial state: Filled circle (hand-drawn)
- Final state: Double circle (wobbly concentric circles)
- State boxes: Rounded rectangles with rough edges
- Transition arrows: Curved arrows with condition labels

[For Class/ER Diagrams:]
- Class boxes: Three-section rectangles (wobbly dividers)
- Relationship lines: Different arrow styles for different relationships
- Cardinality labels: Hand-written "1", "*", "0..1", etc.

COLOR USAGE (Strategic, UL Palette):
- Black (#000000): All primary structure (most boxes, all arrows)
- Deep Purple (#4A148C): Critical path nodes, main flow, key entities (10-20% of nodes)
- Deep Teal (#00796B): Alternative paths, secondary entities (5-10% of nodes)
- Charcoal (#2D2D2D): All text labels (node labels, arrow labels)
- Background: Light Cream (#F5E6D3) OR White (#FFFFFF)

CRITICAL REQUIREMENTS:
- Excalidraw hand-drawn aesthetic (wobbly, sketchy, organic)
- Mermaid diagram structure ([chosen type] grammar)
- UL color scheme (purple for critical, teal for secondary, black structure)
- 3-tier typography (title, node labels, edge labels)
- Whiteboard sketch feel (not polished, not digital)
- All shapes imperfect (rectangles wobbly, circles oval, arrows curved)
- Variable line weight (thicker boxes, medium arrows, thin details)
- Hand-lettered text (natural slant, imperfect alignment)
- Strategic color (not everything colored, mostly black structure)
- Readable and clear despite sketch style
- Follows [Mermaid diagram type] conventions

VALIDATION CHECKPOINTS:
- Does it look hand-drawn on a whiteboard (not digital)?
- Are all geometric shapes imperfect (wobbly edges)?
- Is the diagram type structure clear (flowchart/sequence/state/etc.)?
- Can you follow the flow/logic/sequence easily?
- Is the critical path obvious (purple highlights)?
- Are labels readable despite hand-lettered style?
- Does it maintain UL aesthetic (flat colors, no gradients)?

Sign "{{{assistantName}}}" small in bottom right corner in charcoal (#2D2D2D).
```

---

### Step 6: Determine Aspect Ratio

**Based on diagram type and complexity:**

| Diagram Type | Typical Aspect Ratio | Reasoning |
|--------------|---------------------|-----------|
| Flowchart (vertical) | 9:16 or 4:3 | Top-to-bottom flow |
| Flowchart (horizontal) | 16:9 or 21:9 | Left-to-right flow |
| Sequence diagram | 16:9 | Actors across, time down |
| State diagram | 1:1 | Circular/network layout |
| Class diagram | 1:1 or 4:3 | Tree or network |
| ER diagram | 16:9 or 1:1 | Entity spread |
| Gantt chart | 16:9 or 21:9 | Timeline horizontal |
| Git graph | 16:9 | Branching horizontal |

**Default: 16:9** — Works for most diagram types

---

### Step 7: Generate with Nano Banana Pro

**Execute with optimal model for text-heavy diagrams:**

```bash
bun run ${PAI_DIR}/skills/art/tools/generate-ulart-image.ts \
  --model nano-banana-pro \
  --prompt "[YOUR COMPREHENSIVE PROMPT]" \
  --size 2K \
  --aspect-ratio [chosen ratio] \
  --output /path/to/mermaid-diagram.png
```

**Why Nano Banana Pro:**
- Best text rendering (critical for labels on nodes and arrows)
- Handles complex multi-element compositions
- Can render hand-drawn aesthetic while maintaining readability
- Excellent for technical diagrams with lots of labels

**Note:** Do NOT use `--remove-bg` for Mermaid diagrams — the background helps the whiteboard aesthetic.

**Immediately open:**
```bash
open /path/to/mermaid-diagram.png
```

---

### Step 8: Comprehensive Validation (MANDATORY)

**Validate across all dimensions:**

#### Diagram Correctness
- [ ] **Structure accurate:** Diagram follows [type] conventions
- [ ] **Logic clear:** Flow/sequence/states make sense
- [ ] **Complete:** All elements from CSE represented
- [ ] **Connections correct:** Arrows point to right places
- [ ] **Labels accurate:** Node and edge labels match content

#### Excalidraw Aesthetic
- [ ] **Hand-drawn feel:** Looks sketched on whiteboard
- [ ] **Wobbly shapes:** No perfect rectangles/circles
- [ ] **Sketchy arrows:** Organic curves, not ruler-straight
- [ ] **Imperfect text:** Hand-lettered, natural slant
- [ ] **Variable line weight:** Thicker boxes, thinner details
- [ ] **Organic joins:** Connections look natural

#### UL Editorial Style
- [ ] **Color strategic:** Purple on critical (10-20%), teal on secondary (5-10%)
- [ ] **Black dominant:** Most structure in black
- [ ] **Typography hierarchy:** 3 tiers clear
- [ ] **No gradients:** Flat colors maintained
- [ ] **{{{assistantName}}} signature:** Present in corner

#### Readability & Clarity
- [ ] **Labels readable:** All text legible despite hand-drawn style
- [ ] **Flow obvious:** Can follow the diagram easily
- [ ] **Critical path clear:** Purple highlights guide eye
- [ ] **Not cluttered:** Spacing adequate, not cramped
- [ ] **Scale works:** Readable at thumbnail and full-size

#### If Validation Fails

**Common issues and fixes:**

| Problem | Diagnosis | Fix |
|---------|-----------|-----|
| **Too polished/digital** | Missing Excalidraw aesthetic | Emphasize: "Wobbly rectangles, sketchy arrows, hand-drawn on whiteboard, imperfect shapes" |
| **Perfect geometry** | Shapes too clean | "All rectangles with rough edges, circles slightly oval, organic imperfection throughout" |
| **Can't follow flow** | Unclear structure | Strengthen arrow directions, add labels, clarify critical path with purple |
| **Labels unreadable** | Text too sketchy or small | Increase label size, simplify hand-lettering: "Readable hand-lettered style" |
| **Wrong diagram type** | Doesn't match content | Return to Step 2, reconsider diagram type based on CSE |
| **Missing Mermaid structure** | Doesn't follow conventions | Add proper diagram grammar: decision diamonds for flowcharts, lifelines for sequence, etc. |
| **Color overload** | Too much purple/teal | Limit: "Purple on 2-3 critical nodes only, teal on 1-2 secondary, rest black" |
| **Looks generic** | Missing UL or Excalidraw style | Combine both: "Excalidraw wobbly whiteboard sketch + UL purple/teal strategic accents" |

**Regeneration Process:**
1. Identify specific validation failures
2. Update prompt with targeted fixes from table
3. Regenerate with refined prompt
4. Re-validate against all checkpoints
5. Repeat until ALL validation criteria pass

**CRITICAL: Do not declare completion until validation passes.**

---

## Diagram Type Deep Dives

### Flowchart Specifics

**Node Types:**
- **Start/End:** Rounded rectangles (wobbly ovals)
- **Process:** Rectangles with rough edges
- **Decision:** Diamonds (asymmetric, hand-drawn)
- **Input/Output:** Parallelograms (tilted, wobbly)
- **Predefined Process:** Rectangles with double side lines

**Flow Rules:**
- Always flows one direction (typically top-down or left-right)
- Arrows never cross if avoidable
- Decision diamonds have exactly 2 exits (Yes/No or True/False)
- Loops back with curved arrows

**Color Strategy:**
- Purple: Main success/happy path
- Teal: Error handling or alternative paths
- Black: All decision nodes and structure

---

### Sequence Diagram Specifics

**Components:**
- **Actors/Entities:** Boxes at top (wobbly rectangles)
- **Lifelines:** Vertical dashed lines (hand-drawn, imperfect)
- **Messages:** Horizontal arrows between lifelines
- **Activations:** Vertical bars on lifelines (when entity is active)
- **Return messages:** Dashed arrows going back

**Temporal Flow:**
- Always top to bottom (time flows down)
- Left to right is actor/entity ordering
- Synchronous: Solid arrow
- Asynchronous: Open arrow
- Return: Dashed arrow

**Color Strategy:**
- Purple: Critical actor/main entity
- Teal: Secondary actors
- Black: All messages/arrows
- Purple fill: Activation bars for critical entity

---

### State Diagram Specifics

**Components:**
- **States:** Rounded rectangles (wobbly)
- **Initial state:** Filled circle (hand-drawn blob)
- **Final state:** Double circle (concentric wobbly circles)
- **Transitions:** Arrows with event labels
- **Conditions:** Guards in brackets on arrows

**State Rules:**
- Each state is distinct and named
- Transitions show event/condition
- Initial state has only outgoing arrows
- Final state has only incoming arrows

**Color Strategy:**
- Purple: Active/current/important states
- Teal: Intermediate states
- Black: Terminal and error states
- All transitions: Black arrows

---

### Class/ER Diagram Specifics

**Components:**
- **Classes/Entities:** Three-section boxes (name, attributes, methods)
- **Relationships:** Arrows with labels
- **Cardinality:** 1, *, 0..1, 1..* on relationship lines
- **Inheritance:** Triangle arrow pointing to parent
- **Composition:** Diamond on containing class

**Relationship Types:**
- Association: Plain arrow
- Inheritance: Arrow with triangle head
- Composition: Arrow with filled diamond
- Aggregation: Arrow with open diamond

**Color Strategy:**
- Purple: Core/important entities
- Teal: Related entities
- Black: All relationship lines
- Charcoal: All attribute/method text

---

## Example Scenarios

### Example 1: Flowchart for Authentication Flow
**Content:** Blog post about user authentication process
**CSE Result:** 24-item story showing login attempt → credential check → success/failure paths
**Diagram Type:** Flowchart
**Structure:** Start → Enter Credentials → Valid? → [Yes] → Generate Token → Success
                                                   → [No] → Retry Limit? → [Yes] → Lock Account
                                                                         → [No] → Return to Enter
**Color:** Purple on success path, Teal on error handling
**Aspect:** 9:16 vertical

### Example 2: Sequence Diagram for API Call
**Content:** Technical article about microservices communication
**CSE Result:** 24-item story showing User → API Gateway → Auth Service → Database → Response chain
**Diagram Type:** Sequence Diagram
**Structure:** 4 actors (User, Gateway, Auth, DB) with message arrows showing request/response flow
**Color:** Purple on Gateway (critical), Teal on Auth (secondary)
**Aspect:** 16:9 horizontal

### Example 3: State Diagram for Order Lifecycle
**Content:** E-commerce order processing explanation
**CSE Result:** 24-item story showing order states: Pending → Processing → Shipped → Delivered (with error states)
**Diagram Type:** State Diagram
**Structure:** Initial → Pending → Processing → Shipped → Delivered → Final
                               → (error) → Cancelled
**Color:** Purple on happy path states, Teal on processing, Black on cancelled
**Aspect:** 1:1 square

### Example 4: ER Diagram for Database Schema
**Content:** Data modeling article about blog platform
**CSE Result:** 24-item story revealing entities: Users, Posts, Comments, Categories with relationships
**Diagram Type:** Entity Relationship Diagram
**Structure:** User 1──* Post, Post 1──* Comment, Post *──* Category (many-to-many)
**Color:** Purple on User and Post (core), Teal on Comment and Category
**Aspect:** 16:9 horizontal

---

## Quick Reference

### When to Use Mermaid Workflow
- Content has inherent diagram structure (flow, sequence, states)
- Need structured technical diagram (not freeform architecture)
- Want hand-drawn whiteboard aesthetic (Excalidraw style)
- Deriving diagram from content analysis (not manually specified)

### Mermaid vs Technical Diagrams
- **Mermaid:** Structured diagram types (flowchart, sequence, etc.), Excalidraw sketchy aesthetic
- **Technical:** Freeform architecture diagrams, cleaner hand-drawn style

### Process Summary
```
1. Run /cse (24-item story explanation) ← MANDATORY
2. Determine diagram type (flowchart, sequence, state, etc.)
3. Extract structure from CSE (nodes, edges, flows)
4. Design Excalidraw layout (wobbly, sketchy, whiteboard)
5. Construct comprehensive prompt
6. Choose aspect ratio (based on diagram type)
7. Generate with nano-banana-pro
8. Validate thoroughly (structure + aesthetic + UL + readability)
```

### Core Principles
1. **CSE-driven:** Always derive from content analysis, never manually specify
2. **Mermaid grammar:** Follow proper diagram type conventions
3. **Excalidraw aesthetic:** Hand-drawn whiteboard sketch feel
4. **UL color scheme:** Strategic purple/teal, black structure
5. **Readable imperfection:** Sketchy but clear

---

**The workflow: /cse → Diagram Type → Structure → Excalidraw Design → Prompt → Generate → Validate → Complete**

**The synthesis: Mermaid structure + Excalidraw aesthetic + UL editorial style = Technical diagrams that feel like smart sketches on a whiteboard.**

```