salvador

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

使用该技能通过p5.js将概念可视化，重点关注高质量UX、美学设计与持续动态效果。

可视化本身就是解释。 通过视觉隐喻进行教学——将概念展示为观众可以跟随的物理动作（比如一堆物体分裂成小块、元素重新排列、数量流动）。文字仅作为注释，而非核心内容。如果可以通过动画或变换来展示，就不要用文字描述。

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

Scaffold: Ensure
```
index.html
```
and
```
src/main.js
```
exist.
Read p5.js Reference: Read
```
resources/p5-missing-knowledge.md
```
for p5.js 2.x API changes before writing any code.
Read Responsive Design: Read
```
resources/responsive-design.md
```
for the scale factor pattern.
Read Visual Quality Rules: Read
```
resources/visual-quality.md
```
for layout, typography, and color rules.
Read Design Defaults: Read
```
resources/design-defaults.md
```
for spacing values and code patterns.

检查上下文：如果缺少

package.json

，请运行

bash .claude/skills/salvador/scripts/setup.sh

。

搭建基础框架：确保
```
index.html
```
和
```
src/main.js
```
文件存在。
查阅p5.js参考文档：在编写任何代码之前，阅读
```
resources/p5-missing-knowledge.md
```
了解p5.js 2.x的API变更。
查阅响应式设计规范：阅读
```
resources/responsive-design.md
```
了解缩放因子模式。
查阅视觉质量规则：阅读
```
resources/visual-quality.md
```
了解布局、排版与配色规则。
查阅设计默认配置：阅读
```
resources/design-defaults.md
```
了解间距值与代码模式。

Phase 1.5: Concept Analysis (Before Coding!)

阶段1.5：概念分析（编码前必做！）

Before writing any code, decompose the concept:

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.
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°")
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

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

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.
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.

在编写任何代码之前，先分解概念：

确定可视化类型：
- 分阶段型：概念需要分步讲解（比如量子比特的工作原理、排序算法的对比、光合作用的过程）。包含多个阶段，支持← →导航。
- 独立场景型：单个动态场景（比如星空、分形、熔岩灯、粒子系统、物理沙盒）。无阶段划分——是一个包含交互的持续体验。
- 混合型：主要为单个场景，但用户可切换模式或图层（比如带可点击行星的太阳系、带参数滑块的波形探索器）。
这一决定将影响后续所有工作。不要强行给不需要分阶段的概念添加阶段。
研究领域知识：查阅真实的事实数据（角度、数量、公式、规则）
- 不要猜测科学/数学细节
- 获取真实数值（比如H₂O的键角是104.5°，而非“约109°”）
如果是分阶段型：阅读
```
resources/storytelling.md
```
了解叙事结构，然后规划流程：
- 铺垫：介绍角色与场景
- 冲突：提出问题或未知点，引发好奇心
- 揭秘：带来洞察的时刻（这是学习的核心）
- 理解：展示机制，解释“为什么”
- 掌握：让用户进行交互或探索变体

如果是分阶段型——暂停——编写过渡链（未完成此步骤禁止编码）：

为每个阶段编写如下精确结构：

stage 1: [标题]
  BEFORE: [该阶段开始时观众看到的内容]
  AFTER:  [该阶段结束时观众看到的内容——发生了哪些变化及原因]
  teaches: [该视觉变化向观众传达的信息]
  analogy: [类似的日常事物]
  → "[引导进入下一阶段的问题]"
stage 2: [标题]
  BEFORE: [起始视觉状态——必须承接上一阶段的问题]
  AFTER:  [结束视觉状态——发生了哪些转变]
  teaches: [对比所传达的信息]
  analogy: [...]
  → "[引导进入第三阶段的问题]"
stage 3: ...

反例：

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

正例：

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

规则：

每个阶段必须有可见的转变（BEFORE ≠ AFTER）。如果某个阶段没有变化，那它只是静态展示——合并或重新设计该阶段。
如果无法在两个阶段之间写出引导问题，说明它们脱节了——重新规划顺序或合并。
每个引导问题必须在渲染后的阶段中以视觉形式呈现
每个类比必须与真实概念一起以视觉形式呈现在渲染后的阶段中——不能作为卡片中的文字
完成过渡链后，编写场景规划：为每个过渡（1→2、2→3……）决定使用
```
同一画布
```
还是
```
新场景
```
并说明原因。拿不定主意时，优先选择同一画布——观众可以看到场景演变，而非在幻灯片之间跳转。这将决定使用
```
design-defaults.md
```
中的哪种过渡模式。
该过渡链是你的契约——代码必须严格实现它

如果是独立场景型/混合型：规划场景与交互：
- 视觉核心是什么？（观众看到并交互的主要内容）
- 用户可以控制哪些参数？（滑块、鼠标、点击、键盘）
- 什么让它具有动态感？（物理效果、粒子、程序化生成、对输入的响应）
- 哪些元素会动，如何动，为什么动？不要制作静态快照——宇宙中的一切都在运动。
确定需要解释的内容（如果是教育类可视化）：
- 需要定义的关键术语
- 需要展示的数量
- 需要突出的关系
- 每一步都要问：观众还不知道什么？ 不要跳过看似明显的步骤——观众是在学习，而非复习。

Phase 1.6: Design Principles

阶段1.6：设计原则

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.
(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.
(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
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
(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

动态系统：系统必须具有“呼吸感”。
- 闲置动画：即使在等待用户输入时，也不能有完全静止的元素。
- 持续时间：使用
```
draw()
```
  来持续驱动物理/逻辑动画。禁止使用
```
noLoop()
```
  。
（仅分阶段型）场景过渡：使用步骤4中的场景规划。
- 同一画布：在原有画布上添加/修改元素。使用
```
design-defaults.md
```
  中的线性插值（lerp）过渡模式。（比如三角函数图逐步构建；排序算法在原数组上变换。）
- 新场景：使用
```
design-defaults.md
```
  中的场景切换模式——共享组件（信息卡片、导航栏）使用线性插值过渡，场景内容平滑淡入。禁止直接切换。
（仅分阶段型）精细过渡：永远不要跳过“变化时刻”
- 错误做法：“状态A” → “状态B”（观众错过转变过程）
- 正确做法：“状态A” → “即将变化” → “变化时刻” → “状态B”
- 规则：如果两个阶段之间的跳转过大，添加中间阶段
可追踪性：当元素变换或移动时，观众必须能跟上它们的轨迹
- 在初始阶段为每个独立组件分配独特的颜色
- 在整个可视化过程中保持这些颜色
- 清晰展示元素的去向、变化或组合情况
（教育类）数据卡片：展示底层事实，而非仅展示视觉效果
- 包含领域符号（公式、方程、配置、伪代码）
- 使用专业术语展示数量、测量值与标签

Phase 2: Autonomous Loop (The "Work")

阶段2：自主循环（核心工作）

Repeat this cycle until the visualization is High Quality:

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)
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.
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.
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.

重复以下循环直到可视化达到高质量标准：

实现/优化：编写
```
src/main.js
```
。
- 通用要求：
  - 使用现代配色方案（避免默认纯RGB颜色）
  - 持续动态：
```
draw()
```
    持续运行。即使在闲置状态下也要展示微动画。
  - 动画速度：动画过程中出现的文字必须至少保持可见3秒。变换速度要足够慢以便观众跟上——拿不定主意时，将时长翻倍。
  - 单阶段文字限制：1个标题（3-5个词）、最多4个标签（1-3个词）、1个引导问题、可选1个公式。超过此限制即属于“文字优先”的反模式。
  - 确保文字可读且对比度高
  - 字体层级：字号体现重要性（参考
```
resources/visual-quality.md
```
    ）
  - 分数表示：永远不要用正斜杠表示数学分数。使用
```
design-defaults.md
```
    中的视觉分数渲染器。
  - 画布尺寸：使用850x540作为基础坐标
  - 键盘处理：使用
```
window.addEventListener('keydown')
```
    。将'G'键映射到
```
saveGif
```
    功能。
  - 支持交互（鼠标、点击、键盘）
- 仅分阶段型要求：
  - 构建支持阶段导航的交互式步进器（← →）
  - 暴露阶段数量：设置
```
window.stageCount = stages.length
```
    以便检查器可以导航到所有阶段。
  - 过渡效果——禁止淡切：连续阶段中存在的元素必须通过线性插值过渡到新位置/尺寸。新元素可淡入，移除的元素可淡出，但共享元素必须持续移动。使用
```
design-defaults.md
```
    中的过渡模式。
  - 为变换的组件分配颜色，并在所有阶段中保持这些颜色。
  - 使用领域准确的数值，而非近似值
- 仅独立场景型/混合型要求：
  - 重点关注交互性与响应速度
  - 让控件易于发现（视觉提示、发光效果、光标变化）
检查：运行
```
node inspect.js
```
- 分阶段型：检查器会捕获所有阶段（通过右键箭头导航，为每个阶段保存
```
snapshots/stage_N.png
```
  ）。
- 独立场景型：检查器会在动画的不同时刻捕获3帧（
```
snapshots/frame_1.png
```
  、
```
frame_2.png
```
  、
```
frame_3.png
```
  ）。如果可视化没有阶段，则无需设置
```
window.stageCount
```
  。
评判：打开所有快照。你的任务是发现问题——每张截图至少列出3个问题。如果找不到3个，就更仔细地检查——初稿中总会存在问题。

在检查细节之前，先问自己：如果观众无法阅读任何文字，他们能理解这个概念吗？如果不能，说明视觉效果的信息量不足——重新设计方案，不要只优化细节。

对每张快照，按顺序完成以下两件事：

首先——描述所见内容：首次观看的观众仅通过这张截图能理解什么？哪些内容清晰？哪些内容令人困惑？哪些内容有问题？（重叠、裁剪、对齐错误、文字碰撞、元素超出边界、流程或连接不清晰）
然后——检查具体问题（参考
```
resources/visual-quality.md
```
）：
- 重叠、裁剪、超出边界、对齐错误
- （仅分阶段型）连续阶段之间的过渡：共享元素是否通过线性插值过渡？引导问题是否可见？
- （仅独立场景型）对比各帧：动画是否展示了有意义的变化？是否有内容过快导致无法阅读？
验证规则：如果你声称修复了某个问题，请重新运行
```
node inspect.js
```
并在新截图中验证该问题已解决，然后再继续。
决策：
- 存在错误？ -> 修复代码 -> 重复循环。
- 静态/乏味？ -> 添加微动画（振动、轨道运动） -> 重复循环。
- 物理/逻辑错误？ -> 修复模拟逻辑 -> 重复循环。
- 布局/排版/过渡问题？ -> 修复具体问题 -> 重复循环。
- 效果惊艳、动态且精致？ -> 进入阶段3。

Phase 3: Presentation (The "Reveal")

阶段3：展示（成果发布）

Once the loop is complete and the visualization is polished:

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

当循环完成且可视化效果达到精致标准后：

启动：运行
```
npx vite --open
```
。
通知用户：告知用户“可视化已准备就绪。操作说明：[在此列出操作方法]。"