salvador

name	salvador
description	Autonomous p5.js visualization agent. It implements, inspects, critiques design/UX, fixes, and launches the result.

Salvador Agent

Use this skill to visualize concepts using p5.js with a focus on high-quality UX, aesthetics, and continuous motion.

The visual IS the explanation. Teach through visual metaphor — show concepts as physical actions the viewer can follow (a pile splitting into chunks, elements rearranging, quantities flowing). Text is annotation, not content. If you can show it with animation or transformation, don't write it in words.

Workflow

Follow this strict loop when asked to visualize a concept:

Phase 1: Bootstrap

1. Check Context: If package.json is missing, run bash .claude/skills/salvador/scripts/setup.sh.
2. Scaffold: Ensure index.html and src/main.js exist.
3. Read p5.js Reference: Read resources/p5-missing-knowledge.md for p5.js 2.x API changes before writing any code.
4. Read Responsive Design: Read resources/responsive-design.md for the scale factor pattern.
5. Read Visual Quality Rules: Read resources/visual-quality.md for layout, typography, and color rules.
6. Read Design Defaults: Read resources/design-defaults.md for spacing values and code patterns.

Phase 1.5: Concept Analysis (Before Coding!)

Before writing any code, decompose the concept:

1. Decide the visualization type:

   • Staged: concept needs step-by-step explanation (how a qubit works, how sorting algorithms compare, how photosynthesis works). Has multiple stages with ← → navigation.
   • Standalone: single living scene (starfield, fractal, lava lamp, particle system, a physics sandbox). No stages — one continuous experience with interactivity.
   • Hybrid: mostly one scene but with modes or layers the user can toggle (solar system with clickable planets, waveform explorer with parameter sliders).

   This decision shapes everything below. Don't force stages on a concept that doesn't need them.

2. Research the Domain: Look up the actual facts (angles, counts, formulas, rules)

   • Don't guess scientific/mathematical details
   • Get the real values (e.g., H2O bond angle is 104.5°, not "about 109°")

3. If staged: Read resources/storytelling.md for narrative structure, then plan the arc:

   • Setup: introduce the actors and the world
   • Tension: what's the question or unknown? create curiosity
   • Revelation: the moment of insight (this is where learning happens)
   • Understanding: show the mechanism, the "why"
   • Mastery: let the user interact or explore variations

4. If staged — STOP — Write the Bridge Chain (do NOT proceed to coding without it):

   Write out this exact structure for every stage:

   stage 1: [title]
     BEFORE: [what the viewer sees at the START of this stage]
     AFTER:  [what the viewer sees at the END — what changed and why]
     teaches: [what this visual change communicates to the viewer]
     analogy: [everyday thing that works like this]
     → "[question that creates pull to stage 2]"
   stage 2: [title]
     BEFORE: [starting visual state — must answer the bridge from stage 1]
     AFTER:  [ending visual state — what transformed]
     teaches: [what the contrast communicates]
     analogy: [...]
     → "[question that creates pull to stage 3]"
   stage 3: ...
   

   Example — BAD:

   stage 2: Cooper Pairs
     BEFORE: lattice with electrons
     AFTER:  lattice with paired electrons
     teaches: Cooper pairs have zero resistance
   

   Example — GOOD:

   stage 2: Cooper Pairs
     BEFORE: 12 electrons bouncing chaotically off lattice nodes, leaving short jittery trails
     AFTER:  temperature gauge drops, electrons slow, snap into pairs with glowing bonds, glide smoothly through lattice without deflecting
     teaches: the CONTRAST between chaotic-bouncing and smooth-gliding IS the explanation of superconductivity — no text needed
   

   Rules:

   • every stage MUST have a visible transformation (BEFORE ≠ AFTER). if a stage has no change, it's a static exhibit — merge it or rethink it.
   • if you can't write a bridge question between two stages, they are disconnected — rethink the order or merge them
   • each bridge question MUST appear visually in the rendered stage
   • each analogy MUST appear visually in the rendered stage alongside the real concept — not as text in a card
   • after the chain, write a scene plan: for each transition (1→2, 2→3, ...) decide same canvas or new scene and say why. when in doubt, same canvas is better — the viewer sees the scene evolve instead of jumping between slides. this decides which transition pattern from design-defaults.md to use.
   • this chain is your contract — the code must implement it

5. If standalone/hybrid: Plan the scene and interactions:

   • what is the visual core? (the main thing the viewer sees and interacts with)
   • what parameters can the user control? (sliders, mouse, click, keyboard)
   • what makes it alive? (physics, particles, procedural generation, response to input)
   • what moves, how, and why? Do NOT make a static snapshot — everything moves in the Universe.

6. Identify What Needs Explanation (if educational):

   • Key terms to define
   • Quantities to show
   • Relationships to highlight
   • For each step, ask: what does the viewer NOT know yet? Don't skip steps that seem obvious — the viewer is learning, not reviewing.

Phase 1.6: Design Principles

7. Living Systems: The system must breathe.

   • Idle Animation: Even when waiting for user input, nothing should be perfectly frozen.
   • Continuous Time: Use draw() to animate physics/logic continuously. noLoop() is forbidden.

8. (Staged only) Scene Transitions: Use the scene plan from step 4.

   • Same canvas: add/modify elements in place. Use the lerp transition pattern from design-defaults.md. (e.g., trigonometry builds up one diagram; sorting transforms the array in place.)
   • New scene: use the scene-switch pattern from design-defaults.md — shared chrome (info card, nav) lerps, scene content fades in smoothly. Never instant-cut.

9. (Staged only) Granular Transitions: Never skip the "moment of change"

   • BAD: "state A" → "state B" (viewer misses the transformation)
   • GOOD: "state A" → "approaching change" → "moment of change" → "state B"
   • Rule: if two stages feel like a big jump, add an intermediate stage

10. Trackability: When elements transform or move, viewers must follow them

    • Assign distinct colors to individual components at the start
    • Maintain those colors throughout the visualization
    • Make it obvious which element went where, became what, or combined with whom

11. (Educational) Data Cards: Show the underlying facts, not just the visual

    • Include domain notation (formulas, equations, configurations, pseudocode)
    • Display quantities, measurements, and labels using proper terminology

Phase 2: Autonomous Loop (The "Work")

Repeat this cycle until the visualization is High Quality:

1. Implement/Refine: Write src/main.js.

   • Always:
     • Use a modern color palette (avoid default pure RGB)
     • Continuous Motion: draw() runs continuously. Show micro-movements even in idle states.
     • Animation speed: text that appears during animation must stay visible for at least 3 seconds. Transformations must be slow enough to follow — when in doubt, double the duration.
     • Text budget per stage: 1 title (3-5 words), up to 4 labels (1-3 words each), 1 bridge question, optionally 1 equation. More text than this = text-first anti-pattern.
     • Ensure text is readable and has high contrast
     • Font hierarchy: size reflects importance (see resources/visual-quality.md)
     • Fractions: NEVER use forward-slash for math fractions. Use the visual fraction renderer from resources/design-defaults.md.
     • Canvas sizing: Use 850x540 base coordinates
     • Keyboard handling: Use window.addEventListener('keydown'). Map 'G' to saveGif.
     • Support interactions (mouse, click, keyboard)
   • Staged only:
     • Build an interactive stepper (← →) through stages
     • Expose stage count: Set window.stageCount = stages.length so the inspector can navigate all stages.
     • Transitions — NO FADE-CUTS: Elements present in consecutive stages must lerp to their new positions/sizes. New elements can fade in, removed elements can fade out, but shared elements move continuously. Use the transition pattern from resources/design-defaults.md.
     • Color-code components that transform and maintain those colors throughout all stages.
     • Use domain-accurate values, not approximations
   • Standalone/hybrid:
     • Focus on interactivity and responsiveness
     • Make controls discoverable (visual hints, glow, cursor changes)

2. Inspect: Run node inspect.js

   • For staged: the inspector captures ALL stages (navigates via ArrowRight, saves snapshots/stage_N.png for each).
   • For standalone: the inspector captures 3 frames at different animation moments (snapshots/frame_1.png, frame_2.png, frame_3.png). If the visualization has no stages, window.stageCount is not needed.

3. Critique: Open every snapshot. Your job is to find problems — list at least 3 per screenshot. If you can't find 3, look harder — there are always problems in a first draft.

   Before checking details, ask: would a viewer understand this concept if they couldn't read any text? If not, the visuals aren't carrying enough weight — rethink the approach, don't polish details.

   For each snapshot, do these two things in order:

   First — describe what you see: What would a first-time viewer understand from this screenshot alone? What's clear? What's confusing? What's broken? (overlaps, clipping, misalignment, text collisions, elements outside bounds, unclear processes or connections)

   Then — check specifics (use resources/visual-quality.md as reference):

   • overlaps, clipping, out-of-bounds, misalignment
   • (staged only) transitions between consecutive stages: do shared elements lerp? bridge questions visible?
   • (standalone) compare frames: does animation show meaningful change? is anything too fast to read?

   Verification rule: if you claim a fix, re-run node inspect.js and verify the specific area in the new screenshot before proceeding.

4. Decide:

   • Errors? -> Fix code -> Repeat.
   • Static/Boring? -> Add Micro-Movement (vibration, orbits) -> Repeat.
   • Physics/Logic Broken? -> Fix Simulation Logic -> Repeat.
   • Layout/Typography/Transition issues? -> Fix the specific issue -> Repeat.
   • Amazing, Dynamic & Polished? -> Proceed to Phase 3.

Phase 3: Presentation (The "Reveal")

Once the loop is complete and the visualization is polished:

1. Launch: Run npx vite --open.
2. Notify: Tell the user "Visualization is ready. Controls: [List controls here]."