mogu-visual

Transform technical descriptions into interactive animated HTML visualizations starring Mogu — a mushroom character whose cap adapts to each concept. Generates self-contained HTML files with Canvas 2D

SKILL.md

GitHub

Mogu Visual

Transform technical concepts into interactive animated HTML visualizations starring Mogu.

Before writing any code, read references/character.md -- it contains the canonical Mogu specification that governs every visual decision below. If the reference fails to load, the inline quick reference in Section 4 of this document is sufficient to draw a correct Mogu.

Workflow

Step 1: Extract Concepts

Parse the user's input and enumerate every distinct concept before doing anything else. This is the most critical step — concepts that aren't listed here will be invisible in the output.

1a. Section-by-section extraction: Walk through the input text section by section (not a single pass). For each paragraph or section, ask: "What concepts are introduced here that aren't already in my list?" Tag each concept with the source section for traceability.

1b. Implicit concept scan: After the explicit pass, scan for concepts the text implies but doesn't name directly: consistency boundaries, failure domains, trust zones, ownership boundaries, backpressure, retry behavior, ordering guarantees, staleness.

1c. Deduplication: Group aliases that refer to the same concept. "Broker," "message broker," and "coordination layer" might be one concept or three — resolve based on context.

1d. Assign concept IDs: Give each deduplicated concept a stable ID (C01, C02, ...). These IDs track through the entire pipeline: extraction → categorization → mapping → code → rendered output.

1e. Concept categorization: Classify each concept. The taxonomy has 12 types — use the most specific match, not the first match:

Type What it is Visual treatment
Entity A named thing with identity and behavior → Mogu actor
Property An attribute of an entity (capability, comfort zone, role) → Cap variation, badge, or onDraw glyph
Flow Something that moves between entities (message, request, data) → Animated item (differentiated by shape + color)
Relationship A structural link (parent-child, peer, reviewer, depends-on) → Connection line (style encodes type)
State A lifecycle phase an entity passes through → Expression change + cap color shift
Event/Trigger Something that causes a transition ("on timeout", "when queue full") → Key Moment with visible cause
Policy/Strategy A decision mechanism (routing strategy, decomposition policy, retry policy) → Policy gate: visual decision point that branches items based on criteria
Constraint/Invariant A rule that must never be violated ("exactly one writer", "no cross-region") → Boundary zone, guardrail line, or violation animation
Boundary/Domain A scope delimiter (trust boundary, failure domain, ownership zone) → Translucent region drawn via onDraw, actors contained inside
Metric/Resource A measurable quantity (latency, capacity, utilization, budget) → Stat display, bar gauge, or threshold line
Derived/Projection State computed from other state (cache, dashboard, index, view) → Fainter/offset Mogu or ghost copy, visually subordinate to source
Source of Truth The authoritative canonical state (ledger, config, primary DB) → Grounded Mogu with solid base line, bold label, "rooted" feel
Layer/Tier A conceptual grouping or abstraction level → Spatial zone or view toggle

Multi-type concepts: A concept can have a primary type and secondary tags. A database is primarily an Entity but also a Source of Truth. A queue is an Entity but also has Metric/Resource (depth) and Constraint (capacity limit). Tag the primary type in the categorization, add secondary tags in parentheses: C07 MessageQueue [Entity (Metric, Constraint)]. The primary type determines the main visual element; secondary tags add overlays (gauge, boundary, badge).

1f. Complexity assessment: Count concepts. Then decide the scope:

Count Strategy
1-8 Single scene, all concepts visible at once
9-15 Single scene with 2-3 view toggles (each view ≤ 8 active concepts)
16-25 Hierarchical drill-down: overview scene → subsystem details on click/toggle
25+ Decompose input into 2-3 independent visualizations, each with its own scene

1g. View design (if multi-view):

First, group concepts using one of these strategies (pick the one that best fits the input):

Strategy How to group Best for
By subsystem Each view = one subsystem or component cluster Microservices, modular architectures
By lifecycle Each view = one phase (setup → running → failure → recovery) Stateful protocols, workflow engines
By abstraction Each view = one layer (infra → platform → application → user) Layered architectures
By data path Each view = one data flow from source to sink ETL, event-driven systems
By question Each view answers one user question ("How does X work?" "What happens when Y fails?") Complex systems with diverse audiences

Then for each view, define:

  • Purpose: what question does this view answer?
  • Concepts shown (by ID): which concepts are active? Target ≤ 8 per view (soft cap — allow 9-10 if concepts are spatially grouped and don't clutter; never exceed 12)
  • Anchor concepts: which concepts appear in ALL views as spatial landmarks (same position)?
  • Cross-view links: which flows/relationships connect this view to others?

1h. Clarifying questions (only if needed):

  • Audience? Developer, student, PM, general public?
  • Which aspect? The whole system or a specific mechanism?
  • Depth? High-level overview or implementation-level detail?

Step 2: Write the Scene Script

The scene script must include a concept coverage manifest — every concept ID from Step 1 must appear with its visual encoding. This is the traceability contract.

Scene: [title]
Archetype: [archetype name or "custom: X + Y"]

Concept Coverage Manifest:
  C01 [concept name] → [visual element] — [encoding: position/cap/shape/motion/color/size/zone/stat/gate]
  C02 [concept name] → [visual element] — [encoding]
  C03 [concept name] → deferred to view:[view name] — [encoding when active]
  ...
  Coverage: N/N concepts mapped (must be 100%)

Views (if multi-view):
  - [view name] — purpose: [question it answers]
    Active: C01, C03, C07, C12 (≤8)
    Anchors: C01, C03
    Toggle: param "view" value "[name]"

Actors:
  - [role] ([size], [cap color], [cap shape], [texture]) — represents C01, C04
Items: [what flows, differentiated by shape/color — each type maps to a concept ID]
Connections: [relationships, style maps to relationship type]
Zones: [boundary/domain regions drawn via onDraw — each maps to a concept ID]
Parameters:
  - [name]: [type] [range] [default] — reveals/controls C07
  - view: toggle [view names] — switches active concept set
Key Moments:
  - [trigger] → [visual effect] — demonstrates C09 ([event/trigger concept])
Stats:
  - [stat name] — tracks C15 ([metric concept])

Rendering patterns for hard concept types (not just actors and items):

Concept type Rendering pattern
Policy/Strategy Policy gate Mogu: items enter, gate Mogu evaluates (processing expression), branches items to different paths based on criteria. Criteria shown as label on the gate.
Constraint/Invariant Colored boundary line around a zone. Items that violate the constraint flash red + bounce back. The constraint is a visible guardrail, not just text.
Boundary/Domain Translucent rectangular region (onDraw) containing the relevant actors. Label at top-left. Distinct color per domain.
Metric/Resource Horizontal gauge bar (onDraw) near the relevant actor. Fill level animates with state changes. Threshold marker shows limits.
Derived/Projection Ghost-Mogu: same shape as source but 60% opacity, offset slightly, connected by dotted line to source. Stale state shown as faded + lag animation.
Source of Truth Solid base line under the Mogu + bold label. Visual "rooted" feel vs. floating derived copies.

Scene archetype selection (see references/scenes.md):

# Archetype When to use
1 Pipeline Sequential stages, conveyor belt, ETL
2 Network Nodes with edges, mesh, routing
3 Pool/Queue Shared resource, workers grabbing tasks
4 State Machine Single entity, morphing states
5 Guard/Gate Gatekeeper, accept/reject, validation
6 Tree Parent-child hierarchy, traversal
7 Race Parallel tracks, contention, locks
8 Transform Input goes in, different output comes out
9 Broadcast One-to-many fan-out, pub/sub
-- Custom Combine archetypes or invent a new one

Present the scene script to the user for confirmation before generating code. This is the contract — changes after code generation are expensive.

Step 2.5: Concept Coverage Audit

Before proceeding to Step 3, run this checklist against the concept manifest:

  1. 100% coverage: Every concept ID from Step 1 appears in the manifest. Count them. If coverage < 100%, stop and fix the scene script. No exceptions.
  2. No text-only escapes: If a concept's encoding is just "label" or "annotation," reconsider — can it be a cap shape, item variation, zone, gauge, gate, or expression instead? Text is a last resort. If text is truly the only option, add a textOnlyReason.
  3. "Deferred" concepts must resolve: Every concept deferred to a view must have that view defined, with the concept listed as active in that view. Grep the manifest for "deferred" and verify each has a matching view entry.
  4. Visual differentiation: If multiple concepts share the same type (e.g., 4 kinds of WorkItem), each must have a distinct visual encoding (shape + color, not just label).
  5. States have transitions: If a concept has a lifecycle (proposed → active → blocked → completed), the visualization must show ≥ 2 states and animate the transition.
  6. Layers are spatial: If the concept has architectural layers or tiers, they must be visually separated as canvas zones, not just described in text.
  7. Policies branch: If a concept is a policy/strategy, the visualization must show the decision point and at least 2 different outcomes.
  8. Boundaries enclose: If a concept is a boundary/domain, it must be drawn as a visible region with actors inside, not just labeled.

If any check fails, revise the scene script before generating.

Step 3: Design the Cast

Select cap shapes, textures, and colors for each Mogu actor. Follow rules from references/character.md:

  • Size = importance. Central component gets the largest Mogu.
  • Same color = same role. All API services share one color, all databases another.
  • Max 3 cap colors per scene. More than 3 creates visual noise. Use shape/texture variation instead if you need more groups.
  • Colors: Saturated but muted. Must pair with cream stem #F5EDE0.

Step 4: Generate HTML

Use the MoguScene engine (components/mogu-engine.js) to keep generated HTML short and focused on scene logic.

HTML template:

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>[Scene Title] — Mogu Visual</title>
  <style>
    * { margin:0; padding:0; box-sizing:border-box; }
    html, body { width:100%; height:100%; overflow:hidden; }
    canvas { display:block; width:100%; height:100%; }
  </style>
</head>
<body>
<canvas id="c"></canvas>
<!-- Path assumes output is in a sibling directory to components/ (e.g., test-output/).
     For standalone distribution, inline the engine or adjust the path. -->
<script src="../components/mogu-engine.js"></script>
<script>
// --- Scene code starts here (target: 150-250 lines) ---
var scene = new MoguScene(document.getElementById('c'), { title: '[Scene Title]' });

// 1. Add actors
scene.addActor('id', { label: 'Name', x: 0.5, y: 0.5, size: 80, cap: { color: '#FF4D4D' } });

// 2. Add connections
scene.connect('from', 'to', { style: 'dashed' });

// 3. Add parameters
scene.addParam({ id: 'rate', label: 'Rate', type: 'slider', min: 1, max: 30, value: 5, step: 1 });

// 4. Scene logic
scene.onUpdate(function(dt, time) { /* spawn items, manage state */ });
scene.onDraw(function(ctx, w, h, time) { /* custom visuals */ });

// 5. Start with absorption
scene.start(['keyword1', 'keyword2'], '#targetCapColor');
</script>
</body>
</html>

Engine API quick reference:

Method Purpose
addActor(id, config) Add a Mogu. Config: label, x, y (0-1), size, cap.color/shape/texture
removeActor(id) Remove a Mogu
setExpression(id, expr) Change expression: neutral/curious/processing/proud/alert
setCapColor(id, color) Animate cap color change
getActorPos(id) Get pixel position {x, y}
connect(from, to, opts) Draw line. Style: dashed/dotted/solid
addParam(config) Add control. Type: slider/toggle/stepper
param(id) Get current parameter value
spawnItem(config) Spawn flowing item. Config: from, to, color, speed, arc, onArrive
addZone(id, config) Boundary/domain region. Config: x, y, w, h (0-1), color, borderColor, label
removeZone(id) Remove a zone
addGauge(id, config) Metric bar attached to an actor. Config: actorId, label, value, max, threshold (same unit as value/max, e.g. 80 if max=100), color/warnColor/dangerColor
setGauge(id, value) Update a gauge's current value
addGhost(srcActorId, ghostId, config) Derived/projection copy of an actor. Config: x, y, opacity, staleOffset
addAnnotation(id, config) Text callout on canvas. Config: x, y (0-1), text, color, fontSize, bg
removeAnnotation(id) Remove an annotation
onUpdate(fn) Register per-frame update: fn(dt, time)
onDraw(fn) Register custom draw: fn(ctx, w, h, time)
setStat(key, value) Show stat in bottom-left
start(keywords?, color?) Begin (with optional absorption ceremony)

Built-in cap shapes (use by string name): dome, flat, pointy, wavy, bumpy, droopy, split, spiky

Built-in textures (use by string name): spots, stripes, hex, circuit, swirl, constellation, scales, lightning

The rule: AI generates only scene-specific code. The engine handles rendering, game loop, controls, labels, connections, items, and the absorption ceremony. If the generated HTML exceeds 300 lines, you're probably reimplementing something the engine already provides.

Step 5: Quality Gate

Check every item before delivering. If any row fails, fix it before handing off.

Check Failure Fix
Concept coverage Input concepts missing from visualization Revisit concept mapping, add actors/items/views/annotations
Character consistency Proportions wrong, missing highlight/feet Compare to canonical SVG in Section 4
Interactivity works Controls don't affect animation Bind params to game loop via state object
Animation smoothness Stuttering Use requestAnimationFrame, not setInterval
Concept accuracy Doesn't match the technical concept Re-examine scene script, fix the metaphor
Self-contained Errors on open Check CDN links, inline all critical code
Not dead No motion without interaction Add idle bounce + ambient particle/item motion
Not skin-deep Params only change cosmetics Params must affect behavior (rate, count, routing)
Labels readable Text overlapping Mogus, other labels, or UI elements See label layout rules below

Label layout rules (common source of visual bugs):

  1. Labels go below their Mogu, offset by at least moguSize * 0.35 from center. Never place labels at a fixed y that ignores Mogu size.
  2. Never stack two text elements without clearance. If a queue bar / counter / status text exists between a Mogu and its label, the label goes below ALL of them.
  3. Shorten labels when actors multiply. 5 consumers labeled "Consumer 1" through "Consumer 5" will overlap. Use "C1"–"C5" or omit labels when the cap color already distinguishes roles.
  4. Queue/status indicators inside or to the side, not stacked below in the same column as the label. Prefer rendering counts inside bars (textBaseline = 'middle') rather than as separate text below.
  5. Test at extremes. Check layout with max actor count (e.g., 5 consumers) and max queue depth. If pills/items overflow their container, cap the visible count.

Mogu Character Quick Reference

This section is the fallback specification. If references/character.md loads, prefer that. If it does not, everything below is sufficient to draw a correct Mogu.

Canonical SVG

Source of truth. ViewBox: 0 0 140 170.

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 140 170">
  <!-- Stem: rx=14 gives soft rounded corners -->
  <rect x="50" y="95" width="40" height="50" rx="14" fill="#F5EDE0"/>

  <!-- Cap: dominant dome, ~2.6x wider than stem -->
  <ellipse cx="70" cy="82" rx="52" ry="38" fill="#FF4D4D"/>

  <!-- Cap highlight: subtle polish, shifted upper-left -->
  <ellipse cx="55" cy="68" rx="18" ry="10" fill="#FF7070" opacity="0.5"/>

  <!-- Spots: 3 circles, varied size, scattered unevenly -->
  <circle cx="42" cy="72" r="6" fill="#FF8080" opacity="0.7"/>
  <circle cx="68" cy="55" r="5" fill="#FF8080" opacity="0.7"/>
  <circle cx="90" cy="68" r="7" fill="#FF8080" opacity="0.7"/>

  <!-- Eyes: solid black dots on stem, no highlights -->
  <circle cx="60" cy="115" r="4.5" fill="#0a0a0a"/>
  <circle cx="80" cy="115" r="4.5" fill="#0a0a0a"/>

  <!-- Mouth: simple upward arc -->
  <path d="M63,127 Q70,133 77,127" stroke="#0a0a0a" stroke-width="2.5" fill="none" stroke-linecap="round"/>

  <!-- Feet: small ellipses for grounding -->
  <ellipse cx="58" cy="145" rx="10" ry="4" fill="#EBE0D0"/>
  <ellipse cx="82" cy="145" rx="10" ry="4" fill="#EBE0D0"/>
</svg>

Proportions (Scale-Independent Ratios)

These ratios hold at any render size. The size parameter in drawMogu() maps to the viewBox height (170 units).

Ratio Value Derivation
Cap width / Stem width 2.6x Cap rx=52 (diameter 104), stem width=40
Cap height / Total height ~45% Cap zone 76px out of 170px
Stem height / Total height ~30% Stem 50px out of 170px
Feet zone / Total height ~15% Feet at y=145, ±4px
Eye spacing Stem width x 50% Eyes at x=60, x=80; spacing=20, stem=40
Mouth below eyes Stem height x 24% Eyes y=115, mouth y=127; offset=12/50
Eye radius Stem width x 11% r=4.5, stem=40

Invariants (Never Change)

These values are fixed across all Mogus regardless of concept:

Property Value Notes
Stem fill #F5EDE0 Warm cream
Eyes fill #0a0a0a Near-black
Eye radius stem_width x 11% ~4.5 at canonical scale
Feet fill #EBE0D0 Slightly darker cream
Cap highlight Cap color lightened 20%, opacity 0.5 Upper-left shift
Spot color Cap color lightened 25%, opacity 0.7 Default texture

Never change stem/feet colors, eye color, or the proportions above.

Expression System

Only eyes and mouth change. No new elements added. Alert is the only expression with eye-whites.

Expression Eyes Mouth When to use
Neutral Solid dots (r=4.5) Upward arc M63,127 Q70,133 77,127 Default, idle, at rest
Curious Left dot normal, right dot bigger (r=5.5) shifted up to y=113 Small circle "o" at (70, 129) r=3.5 Encountering new input, inspecting data
Processing Horizontal lines (x1=54..66, x1=74..86 at y=115) Wavy line M60,128 Q65,124 70,128 Q75,132 80,128 Actively computing, transforming
Proud Upward arcs (happy squint) M55,114 Q60,110 65,114 Wide grin M60,126 Q70,136 80,126 Task complete, success, output delivered
Alert White circles (r=6) + dark pupils (r=3.5, offset +1x, +1y) Inverted-V M64,129 L70,124 L76,129 Error, warning, unexpected input

Cap Shapes (8 Reference Shapes)

Shape = structural metaphor. The AI can invent new shapes beyond these.

Shape Silhouette Semantic mapping
Classic Dome Standard ellipse Default, general-purpose
Flat / Shiitake Wide, low ellipse (capRy x 0.6) Platform, infrastructure, database
Pointy / Wizard Tall cone (quadratic curve) Algorithm, logic, security, encryption
Wavy / Ruffled Undulating edge (sin wave x 4) Streaming, async, event-driven, reactive
Multi-bump Three overlapping circles Distributed systems, concurrency, microservices
Droopy / Melting Dripping edges (quadratic drips) Cache overflow, memory leak, GC, degradation
Split / Forked Two lobes, split down middle Load balancing, branching, A/B testing, fork
Spiky / Urchin Triangular protrusions (8 spikes) Firewall, defense, rate limiting, DDoS protection

Each shape function receives (ctx, cx, cy, capRx, capRy), calls ctx.beginPath(), draws the path, and leaves it open for the caller to fill.

Cap Textures (8 Reference Textures)

Texture = surface pattern mapped to concept characteristics.

Texture Visual Semantic mapping
Classic Spots Scattered circles, varied sizes Default, general-purpose
Ridges / Stripes Vertical lines, evenly spaced Ordered flow, pipeline, sequential
Hexagonal Honeycomb grid Network topology, mesh, P2P, graph
Circuit PCB trace lines + dots Computation, digital logic, CPU, binary
Swirl Spiral curves (2 turns) Recursion, loops, iteration, cycles
Constellation Dots connected by lines Node networks, service mesh, distributed
Scales Overlapping arcs Queues, stacks, buffers, pagination
Lightning / Cracks Zigzag paths Energy, events, interrupts, exceptions

Each texture function receives (ctx, cx, cy, capRx, capRy, spotColor, baseAlpha). The 7th param baseAlpha (0-1, default 1) is a multiplier for all alpha values inside the texture. This enables ghost/derived actors to render textures at reduced opacity. Textures set ctx.globalAlpha = ownAlpha * baseAlpha, draw the pattern, then restore ctx.globalAlpha = 1.0.

Cap Color Palette

Colors should be saturated but muted -- "as if the mushroom grew that way naturally." Must pair with the cream stem #F5EDE0. No rigid domain-to-color mapping.

Color Hex Semantic suggestions
Red #FF4D4D Default, error, alert, critical path
Orange #FF8C42 Activity, build, deployment, queue
Amber #FFB84D Warning, caution, cache, fallback
Yellow #FFD966 Highlight, indexing, search
Lime #A3D977 Growth, scaling, optimization
Green #52C77A Success, health, pass, ready
Teal #4DBFBF Flow, streaming, data pipeline
Sky Blue #5BA3E0 Cloud, API, interface, communication
Blue #5680E0 Logic, stable, core service
Indigo #7B68EE Deep computation, AI/ML, complex algorithm
Purple #A66FD9 Transformation, middleware, orchestration
Magenta #E066A6 Creative, UX, frontend, design system
Pink #FF6B9D Playful, user-facing, delight
Brown #A67C52 Persistence, storage, database, logs
Gray #8C8C8C Neutral, deprecated, archived, inactive

Multi-Mogu Rules

When multiple Mogus appear in a single scene:

  1. Size = importance. Primary component = largest. Helpers = small.
  2. Same cap color = same role. All API services share one blue. All DBs share one brown.
  3. Max 3 cap colors per scene. Use shape/texture variation for additional groups.
  4. Spatial arrangement: Data flow left-to-right. Hierarchy top-to-bottom. Peers in a row.
  5. Same shape/texture = same structure type. All async services get wavy caps.

Absorption Ceremony

The 4-step brand intro sequence. Total duration: 3 seconds at 60fps.

Step 1: Idle (0-0.8s)

  • Cap: #FF4D4D (red), classic dome, classic spots
  • Expression: neutral
  • Y-offset: sinusoidal idle bounce (+-2px, 2.5s period)

Step 2: Notice (0.8-1.5s)

  • Expression: curious
  • Keywords float in from the right (stagger 0.1s, slide + fade, monospace #aaa)
  • Idle bounce continues

Step 3: Swallow (1.5-2.2s)

  • Expression: processing
  • Cap inflates: capRy increases by 15% (spring easing with overshoot)
  • Keywords scale down toward cap center, fade out

Step 4: Ready (2.2-3.0s)

  • Expression: proud
  • Cap color lerps to final semantic color (ease-out, 0.5s)
  • Cap shape morphs to final shape (if different from dome)
  • capRy returns to normal (ease-out, 0.3s)
  • One final small hop

After the ceremony, the Mogu is the concept and the main visualization begins.

Timing control:

var time = 0; // seconds, incremented each frame by dt

if (time >= 1.5 && time < 2.2) {
  var stepTime = time - 1.5;
  var stepDuration = 0.7;
  var t = Math.min(stepTime / stepDuration, 1);
  var inflateAmount = ease.spring(t, 0.5);
  capRy = baseCapRy * (1 + 0.15 * inflateAmount);
}

Color interpolation (RGB lerp):

function lerpColor(hex1, hex2, t) {
  var r1 = parseInt(hex1.substring(1, 3), 16);
  var g1 = parseInt(hex1.substring(3, 5), 16);
  var b1 = parseInt(hex1.substring(5, 7), 16);
  var r2 = parseInt(hex2.substring(1, 3), 16);
  var g2 = parseInt(hex2.substring(3, 5), 16);
  var b2 = parseInt(hex2.substring(5, 7), 16);
  var r = Math.round(r1 + (r2 - r1) * t);
  var g = Math.round(g1 + (g2 - g1) * t);
  var b = Math.round(b1 + (b2 - b1) * t);
  return '#' + ((1 << 24) + (r << 16) + (g << 8) + b).toString(16).slice(1);
}

Quick Reference Links

  • MoguScene engine: components/mogu-engine.js — load this in generated HTML, write only scene code
  • Character spec: references/character.md
  • Scene archetypes: references/scenes.md
  • Interaction patterns: references/interactions.md
  • Complete examples: references/examples.md
  • Canonical SVG: components/mogu.svg
  • Expression variants: components/mogu-expressions.svg
  • Low-level drawing code (for reference, not direct use): components/widgets.js