diff --git a/.github/ISSUE_PROPOSAL_mechanical_diagrams.md b/.github/ISSUE_PROPOSAL_mechanical_diagrams.md new file mode 100644 index 0000000..7841b52 --- /dev/null +++ b/.github/ISSUE_PROPOSAL_mechanical_diagrams.md @@ -0,0 +1,152 @@ +# Improve complex mechanical/illustrative diagram quality + +## Problem + +When users ask questions like "how do cars work?" or "how do airplanes work?", the agent generates SVG/HTML diagrams via the `widgetRenderer` component that are **functional but lack precision and intentionality**. + +### Screenshots + +**Car diagram** — rough silhouette, floating component boxes, crude annotations, oversimplified pedal sub-diagram: + +![car-diagram](./assets/car-diagram-screenshot.png) + +**Airplane diagram** — imprecise plane shape, rough control surfaces mini-diagram, adequate force arrows but weak airfoil representation: + +![airplane-diagram](./assets/airplane-diagram-screenshot.png) + +### Root causes + +1. **No planning step** — the agent generates complex illustrative diagrams in a single pass with no composition planning (what to emphasize, where components sit spatially, how controls map to visuals) +2. **Thin illustrative guidance** — the existing skill files give strong rules for flowcharts and structural diagrams but only **9 lines** to illustrative diagrams (`svg-diagram-skill.txt` lines 157-165) +3. **No shape construction method** — the LLM generates freehand SVG paths that produce rough, unrecognizable silhouettes +4. **No control-to-visual binding pattern** — interactive elements (sliders, presets) are architecturally disconnected from the SVG elements they should modify + +### Specific deficiencies + +- Object silhouettes (car body, airplane fuselage) are rough freehand paths rather than recognizable shapes +- Internal components (engine, transmission, control surfaces) are colored boxes floating over the outline without spatial accuracy +- Annotations use crude arrows/lines without a clear visual hierarchy (primary vs secondary labels) +- Sub-diagrams (pedal arrangement, control surface detail) are oversimplified rectangles +- Interactive controls don't visually update the diagram — no feedback loop + +--- + +## Proposed PRs + +All changes are to **skill/prompt files only** — no runtime code changes needed. New `.txt` files are auto-discovered by `load_all_skills()` in `apps/agent/skills/__init__.py`. + +### PR 1: Expand illustrative diagram rules in `svg-diagram-skill.txt` + +**Scope:** `apps/agent/skills/svg-diagram-skill.txt` lines 157-165 (+ MCP mirror) + +The current "Illustrative Diagram" section is only 9 lines. Expand with: +- **Composition grid rule**: divide 680px viewBox into zones — main illustration (x=40-480), annotation margin (x=490-640), optional sub-diagram zone (bottom 25%) +- **Depth layering order**: background -> silhouette -> internals -> connectors -> labels +- **Shape construction rule**: build recognizable objects from 4-8 geometric primitives, not a single complex path +- **Force/motion arrow conventions**: larger arrowheads (`markerWidth=8`), color-coded by type (warm = resistance, cool = propulsion, gray = gravity) +- **Cross-section vs side-view guidance**: when to use each and how to indicate cut planes + +**Impact:** Immediate quality improvement for all illustrative diagrams. Smallest change, do first. + +--- + +### PR 2: Add diagram planning protocol (pre-generation thinking step) + +**Scope:** `apps/agent/skills/svg-diagram-skill.txt` (+ MCP mirror) + +Before generating any illustrative diagram, the agent must complete a structured plan: + +1. **Subject decomposition** — identify 3-5 key subsystems, classify as primary (prominent) vs secondary (annotation-level) +2. **Spatial layout** — assign components to a coordinate grid before writing SVG +3. **Educational priority** — what is the single most important thing to convey? +4. **Composition sketch** — define bounding rectangles for illustration, annotations, controls, sub-diagrams +5. **Control-to-visual mapping** — list which SVG element IDs each interactive control will modify +6. **Shape fidelity check** — list 4-6 defining visual features that make the subject recognizable (e.g., for a car: wheel wells, hood slope, windshield angle, roof line) + +Pure prompt enhancement — no code changes. **Highest single-item impact.** + +--- + +### PR 3: Add progressive rendering pattern for interactive diagrams + +**Scope:** `apps/agent/skills/master-agent-playbook.txt`, `apps/agent/skills/svg-diagram-skill.txt` (+ MCP mirrors) + +Replace scattered `oninput` handlers with a structured architecture: + +- **Explicit HTML sections** via comments: ``, ``, ``, ``, `` +- **Centralized state-and-render pattern**: + ```js + const state = { throttle: 50, gear: 3, mode: 'city' }; + function updateState(key, value) { state[key] = value; render(); } + function render() { /* update ALL visual elements from state */ } + ``` +- **Element ID convention**: `viz-{component}-{property}` (e.g., `viz-engine-fill`, `viz-speed-text`) +- **Preset pattern**: presets as calls to `updateState` with multiple values + +Ensures controls and visuals are architecturally connected rather than accidentally coupled. + +--- + +### PR 4: Create dedicated `mechanical-illustration-skill.txt` + +**Scope:** New file `apps/agent/skills/mechanical-illustration-skill.txt` (+ MCP mirror) + +Comprehensive skill for mechanical/illustrative diagrams: + +- **Shape construction method** — decompose objects into geometric primitives (body = rounded rect, wheels = circles, windows = trapezoids) +- **Spatial accuracy rules** — grid overlay technique for component placement +- **Annotation hierarchy** — primary (14px/500 weight, solid leader lines), secondary (12px/400, dashed leaders), tertiary (11px/400, inline) +- **Sub-diagram quality standards** — minimum 150x100px, visually connected to main diagram via callout +- **Interactive control binding template** — reusable JS pattern for slider/button -> SVG element updates +- **Two worked reference compositions** — car drivetrain and airfoil cross-section with full SVG examples + +Auto-loaded by the existing `load_all_skills()` glob — no code changes. + +--- + +### PR 5: Add SVG shape library with reusable path fragments + +**Scope:** New file `apps/agent/skills/svg-shape-library.txt` (+ MCP mirror) + +Pre-designed SVG path fragments the agent can reference and adapt: + +- **Vehicles**: sedan side profile, airplane side profile, airplane top-down +- **Mechanical parts**: gear/cog, piston, spring, valve, wheel with spokes +- **Physics shapes**: airfoil cross-section (NACA-style), force arrow with proper head +- **Annotation elements**: zoom callout box, dimension line with tick marks +- **Control surfaces**: rudder, aileron, elevator (neutral and deflected) + +Each entry includes normalized coordinates (0-100 units), transform instructions for positioning, and customization notes. + +**Note:** Adds ~30-50KB to system prompt. Monitor context budget. Consider including only 6-8 most common shapes initially. + +--- + +## Recommended sequencing + +| Order | PR | Effort | Impact | +|-------|-----|--------|--------| +| 1 | PR 1: Expand illustrative rules | Small | Medium | +| 2 | PR 2: Diagram planning protocol | Small | **High** | +| 3 | PR 3: Progressive rendering | Medium | Medium | +| 4 | PR 4: Mechanical illustration skill | Medium | High | +| 5 | PR 5: SVG shape library | Large | High | + +PRs 1 and 2 can be merged independently. PR 4 builds on conventions from PR 1. PR 3 and PR 5 are independent of each other. + +## Verification + +After each PR, test with these prompts and compare before/after: +- "how do cars work?" +- "can you explain how airplanes fly? I'm a visual person" +- "explain how a combustion engine works" +- Verify dark mode compatibility +- Check system prompt token count stays within model context budget + +## Key files + +- `apps/agent/skills/svg-diagram-skill.txt` — primary skill to expand (illustrative section at lines 157-165) +- `apps/agent/skills/master-agent-playbook.txt` — interactive widget templates (Part 2) +- `apps/agent/skills/__init__.py` — auto-discovers new `.txt` skill files (line 23, glob pattern) +- `apps/agent/main.py` — injects skills into system prompt (line 49) +- `apps/mcp/skills/` — MCP mirrors of all skill files diff --git a/apps/agent/skills/master-agent-playbook.txt b/apps/agent/skills/master-agent-playbook.txt index e27ff25..287f4f5 100644 --- a/apps/agent/skills/master-agent-playbook.txt +++ b/apps/agent/skills/master-agent-playbook.txt @@ -218,6 +218,106 @@ render(); } ``` +### Architecture: Progressive Rendering for Complex Interactive Diagrams + +When building interactive diagrams with controls (sliders, buttons, presets), use this structured architecture instead of scattered inline handlers. This ensures controls and visuals stay connected. + +**HTML Section Structure** — organize your HTML in explicit, commented sections: + +```html + + + + + 0 rpm + + + + +
+ ... +
+
Engine speed: 0 rpm
+
Wheel force: 0
+
+
+ + +
+ + + + +
+ + + +``` + +**Element ID Convention**: `viz-{component}-{property}` +- `viz-engine-fill` — engine block fill color/opacity +- `viz-speed-text` — speed readout text content +- `viz-force-arrow` — force arrow being resized +- `viz-rpm` — RPM stat display + +This convention makes it trivial to trace which control affects which visual element. Every `updateState` call triggers `render()`, which updates every dynamic element from the centralized state. + +**Key rules**: +- Never use anonymous `oninput="document.getElementById(...)"` handlers. Always go through `updateState` → `render`. +- Every slider/button must produce a visible change in the SVG — if a control doesn't update anything visual, remove it. +- Preset buttons must also update slider positions to stay in sync. +- The `render()` function should be idempotent — calling it twice with the same state produces the same output. + --- ## Part 3: Skill — Data Visualization diff --git a/apps/agent/skills/mechanical-illustration-skill.txt b/apps/agent/skills/mechanical-illustration-skill.txt new file mode 100644 index 0000000..1c22ba6 --- /dev/null +++ b/apps/agent/skills/mechanical-illustration-skill.txt @@ -0,0 +1,350 @@ +# Mechanical & Illustrative Diagram Skill + +This skill extends the SVG Diagram Skill with specific guidance for mechanical and physical-world illustrations — cars, airplanes, engines, circuits, buildings, and similar real-world objects where **shape fidelity** and **spatial accuracy** matter. + +Use this skill whenever you need to illustrate something that exists in the physical world and has a recognizable form. + +--- + +## Shape Construction Method + +LLMs cannot reliably produce accurate freehand SVG paths. Instead, **compose recognizable shapes from geometric primitives**. + +### The Primitive Composition Rule + +Break every real-world object into 4-8 simple SVG elements: + +| Primitive | SVG Element | Use For | +|-----------|------------|---------| +| Rectangle | `` with `rx` | Bodies, blocks, panels, frames | +| Circle/Ellipse | ``, `` | Wheels, gears, dials, ports | +| Trapezoid | `` or `` | Windshields, tapered sections | +| Arc/Curve | `` with cubic bezier | Hood slopes, fuselage tapers, airfoils | +| Line | `` | Axles, shafts, structural members | +| Rounded path | `` with Q/C commands | Organic contours, fenders | + +### Example: Car Side Profile (Composed from Primitives) + +```svg + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +**Key principle**: Each primitive is a separate element that can be individually styled, labeled, or animated. The composition reads top-to-bottom as: body → hood → cabin → roof → trunk → wheels. + +--- + +## Spatial Accuracy Rules + +### Grid Overlay Technique + +Before placing components, mentally divide the main subject into a grid: + +1. **Horizontal zones** — for a car: front bumper (0-15%), engine bay (15-35%), cabin (35-65%), trunk (65-85%), rear bumper (85-100%) +2. **Vertical zones** — roof (0-25%), windows (25-40%), body (40-70%), undercarriage (70-85%), wheels (85-100%) + +Place components within their correct grid cell. An engine MUST be in the front 15-35% zone. A differential MUST be in the rear 65-85% zone. + +### Spatial Rules + +- **Components must be positioned where they physically exist** in the real object. Never float a component outside its container. +- **Overlapping indicates containment**: pistons overlap with cylinders, gears mesh with each other, wires run through conduits. +- **Connection lines must follow physical paths**: a driveshaft runs horizontally from transmission to differential, not diagonally through the cabin. +- **Scale matters**: an engine block is larger than a spark plug. Maintain approximate relative proportions. + +--- + +## Annotation Hierarchy + +Use three distinct tiers so the viewer's eye finds the most important information first. + +### Tier 1: Primary Labels (max 5 per diagram) +```svg + + + +Engine +power source +``` + +### Tier 2: Secondary Labels +```svg + + + +driveshaft +``` + +### Tier 3: Tertiary Labels (inline, no leader) +```svg + +front wheel +``` + +**Placement rules**: +- All Tier 1 and 2 labels go in the annotation margin (x=490 to x=640). +- Leader lines must be angled — never purely horizontal. Angle conveys which element they point to. +- Leader lines must never cross each other. If they would, reorder vertically. +- Tier 3 labels sit directly below or beside the element they describe. + +--- + +## Sub-Diagram Quality Standards + +Sub-diagrams appear in the sub-diagram zone (bottom 25% of the SVG or in a separate card below). They zoom into a specific subsystem. + +### Requirements + +1. **Minimum viewBox**: 150×100 units. Anything smaller is unreadable. +2. **Same shape standards**: Sub-diagrams must use the primitive composition method. No placeholder rectangles. +3. **Visual connection**: Link the sub-diagram to the main illustration with one of: + - A dotted leader line from the relevant area to the sub-diagram + - A "zoom bracket" — a dashed rectangle around the area in the main diagram, with a line to the sub-diagram + - A matching color that ties the sub-diagram to its parent region + +### Example: Pedal Sub-Diagram (Good vs Bad) + +**Bad** (oversimplified): +```svg + + + + +``` + +**Good** (recognizable pedal shapes): +```svg + + + +clutch + + + +brake + + + +throttle + + + +``` + +--- + +## Interactive Control Binding + +When a diagram has interactive controls (sliders, buttons), every control must produce a visible change in the SVG. + +### Binding Pattern + +```javascript +// 1. Define state with meaningful defaults +const state = { throttle: 30, gear: 2, steering: 0 }; + +// 2. Physics/logic model — compute derived values from state +function compute() { + const rpm = state.throttle * 40 + state.gear * 200; + const speed = rpm / (state.gear * 25 + 50); + const force = state.throttle * (7 - state.gear) * 0.5; + return { rpm, speed: Math.round(speed), force: Math.round(force) }; +} + +// 3. Render — apply computed values to SVG elements +function render() { + const v = compute(); + + // Update text readouts + setText('viz-rpm', v.rpm.toLocaleString() + ' rpm'); + setText('viz-speed', v.speed + ' mph'); + setText('viz-force', v.force); + + // Update visual indicators + setAttr('viz-engine-glow', 'opacity', 0.2 + state.throttle * 0.008); + setAttr('viz-force-arrow', 'x2', + getAttr('viz-force-arrow', 'x1') + v.force * 2); + + // Highlight active preset button + document.querySelectorAll('.preset-btn').forEach(b => + b.classList.toggle('active', b.dataset.preset === state.mode)); +} + +// Helpers +function setText(id, val) { + const el = document.getElementById(id); + if (el) el.textContent = val; +} +function setAttr(id, attr, val) { + const el = document.getElementById(id); + if (el) el.setAttribute(attr, val); +} +function getAttr(id, attr) { + const el = document.getElementById(id); + return el ? +el.getAttribute(attr) : 0; +} +``` + +### What "Visible Change" Means + +For each control, at least one of these must change in the SVG: +- **Fill opacity/color** — e.g., engine glows brighter at higher RPM +- **Element position** — e.g., piston moves up/down, needle rotates +- **Path length/size** — e.g., force arrow grows/shrinks +- **Text content** — e.g., speed readout updates +- **Stroke dash animation speed** — e.g., flow particles speed up + +If a control doesn't change anything visual, remove it. + +--- + +## Worked Reference: Car Drivetrain Composition + +This shows the complete planning-to-SVG process for a "how do cars work?" response. + +### Planning Step + +1. **Subject decomposition**: Engine (primary), Transmission (primary), Differential (primary), Driveshaft (secondary), Wheels (secondary), Brakes (secondary) +2. **Educational priority**: Energy conversion chain — fuel burns → crankshaft spins → gears trade speed for force → wheels push road +3. **Spatial layout**: Left-to-right: Engine (x=100-200) → Transmission (x=220-320) → Driveshaft (x=320-400) → Differential (x=400-480) → Wheels (x=480-540) +4. **Shape fidelity**: Car needs: body rectangle, hood slope, windshield, roof arc, 2 wheels with hubs, wheel wells +5. **Control mapping**: Throttle slider → viz-engine-glow opacity + viz-rpm text; Gear slider → viz-gear-text + viz-force text + +### SVG Structure Outline + +``` +Car silhouette (composed from 8 primitives) + └─ Engine block (teal rect, positioned in front 20%) + └─ Transmission (purple rect, positioned at 35%) + └─ Driveshaft (line connecting transmission to differential) + └─ Differential (blue rect, positioned at 70%) + └─ Flow arrows: engine → transmission → driveshaft → differential → wheels +Annotation margin (x=490): + └─ "Engine" — primary label with leader + └─ "Transmission" — primary label with leader + └─ "Differential" — primary label with leader + └─ "brakes squeeze rotors" — secondary label +Sub-diagram zone: + └─ Pedal arrangement (clutch/brake/throttle with proper shapes) + └─ Steering wheel indicator +Controls: + └─ Throttle slider, Gear slider + └─ Preset buttons: City, Highway, Braking +Stats: + └─ Engine speed (rpm), Wheel force, Road speed (mph) +``` + +--- + +## Worked Reference: Airfoil / Airplane Composition + +### Planning Step + +1. **Subject decomposition**: Wing/airfoil (primary), Forces — lift/weight/thrust/drag (primary), Control surfaces (secondary), Engine (secondary) +2. **Educational priority**: Lift generation — wing shape creates pressure difference, net upward force +3. **Spatial layout**: Airplane centered horizontally. Forces as arrows: Lift (up from wing center), Weight (down from fuselage center), Thrust (right from engine), Drag (left from nose) +4. **Shape fidelity**: Airplane needs: fuselage cylinder, wing cross-section (NACA-style curve), tail fin, engine nacelle, cockpit windows +5. **Control mapping**: Engine power → viz-thrust-arrow length + viz-thrust-text; Wing angle → viz-lift-arrow length + airfoil rotation + +### Airfoil Cross-Section Shape + +The airfoil is the most important shape for airplane diagrams. Use this NACA-style profile: + +```svg + + + + + + + + + + + +``` + +### Control Surfaces Sub-Diagram + +```svg + + + + + + + + + + + + + + + + + + + + + + + +ailerons: roll +rudder: yaw +elevator: pitch +``` + +--- + +## Common Mistakes to Avoid + +1. **Single-path silhouettes**: Don't draw `` for a car outline. It will look wrong. Use primitives. +2. **Floating components**: An engine drawn at x=400 in a car that spans x=100-500 is in the trunk. Check your grid. +3. **Placeholder rectangles**: Three identical rectangles labeled "clutch", "brake", "throttle" convey nothing. Give them distinct shapes and proportions. +4. **Disconnected controls**: A "throttle" slider that doesn't change anything in the SVG is useless. Every control needs a visible effect. +5. **Label soup**: 10 primary labels at the same font size creates visual noise. Use the 3-tier hierarchy. +6. **Missing physics**: Force arrows without labels or with wrong directions are worse than no arrows. Double-check: lift points UP, weight points DOWN, thrust points FORWARD, drag points BACKWARD. diff --git a/apps/agent/skills/svg-diagram-skill.txt b/apps/agent/skills/svg-diagram-skill.txt index 2a28385..6a48620 100644 --- a/apps/agent/skills/svg-diagram-skill.txt +++ b/apps/agent/skills/svg-diagram-skill.txt @@ -155,13 +155,87 @@ If you're rendering inside a system that supports CSS variables, prefer: - Use different color ramps for parent vs child to show hierarchy. ### 3. Illustrative Diagram -**When**: Building intuition. "How does X actually work?" +**When**: Building intuition. "How does X actually work?" (engines, airplanes, circuits, load paths) **Layout**: Freeform — follows the subject's natural geometry. -**Rules**: + +**Composition Zones** (divide the 680px viewBox): +- **Main illustration**: x=40 to x=480, full height. This is where the primary subject lives. +- **Annotation margin**: x=490 to x=640. Primary and secondary labels go here with leader lines pointing into the illustration. +- **Sub-diagram zone** (optional): bottom 25% of height. For detail callouts (e.g., pedal arrangement, control surface close-up). +- Never let the main illustration bleed into the annotation margin. + +**Depth Layering Order** (draw in this sequence for proper stacking): +1. Background/context shapes (low opacity, large, sets the scene) +2. Main subject silhouette (the recognizable outline — car body, airplane fuselage) +3. Internal components (engine, transmission, etc. — positioned where they physically exist) +4. Connectors and flow lines (driveshafts, force arrows, data paths) +5. Labels and annotations (always on top, never occluded) + +**Shape Construction** (critical for recognizable real-world objects): +- **Never draw a complex object as a single ``**. LLMs cannot reliably produce accurate freehand SVG paths. +- Instead, **compose from 4-8 geometric primitives**: a car = body rect with rounded corners + hood slope path + windshield trapezoid + 2 wheel circles + bumper rects. +- Each primitive should be a separate SVG element so it can be individually styled and labeled. +- Test: "Would someone recognize what this is without labels?" If not, add more defining features. +- Key features that make objects recognizable: + - **Car**: wheel wells, hood slope, windshield angle, roof line, distinct front/rear + - **Airplane**: fuselage taper, wing sweep, tail fin, engine nacelles + - **Building**: floor lines, window grid, foundation, roof pitch + +**Force & Motion Arrows**: +- Use larger arrowheads for force arrows: `markerWidth="8" markerHeight="8"` (vs default 6 for connectors). +- Color-code by type: warm (coral/red) for resistance/friction, cool (blue/teal) for propulsion/thrust, gray for gravity/neutral forces. +- Scale arrow stroke width to indicate magnitude: 1.5px normal, 2.5px for dominant forces. +- Always label force arrows with both name and direction. + +**Annotation Hierarchy**: +- **Primary labels** (14px, font-weight 500, solid leader lines at 1px stroke): main components being explained. Max 5 per diagram. +- **Secondary labels** (12px, font-weight 400, dashed leader lines at 0.5px stroke): supporting details and dimensions. +- **Tertiary labels** (11px, font-weight 400, inline with no leader line): minor callouts, units, values. +- Leader lines should be angled (not purely horizontal/vertical) and must never cross each other. + +**Cross-Section vs Side View**: +- Use **side profile** for: force diagrams, motion paths, external appearance, spatial relationships between subsystems. +- Use **cross-section (cut-away)** for: internal mechanisms, flow paths through chambers, layered structures. +- When using cross-section, draw a dashed line indicating the cut plane and label it (e.g., "section A-A"). + +**Sub-Diagram Standards**: +- Minimum viewBox area: 150×100 units. +- Visually connect to the main diagram with a dotted leader line or a "zoom" callout bracket. +- Sub-diagrams must meet the same shape quality standards as the main illustration — no placeholder rectangles. + +**General Rules**: - Shapes can be freeform (paths, ellipses, polygons), not just rects. - Color encodes intensity, not category (warm = active, cool = dormant). - Overlap shapes for depth, but never let strokes cross text. -- Labels go in margins with leader lines pointing to the relevant part. +- Components must be positioned where they physically exist in the real object — don't float an engine in the trunk. +- Max 5-7 labeled components per diagram. If more, use the multi-diagram approach. + +--- + +## Diagram Planning Protocol + +Before generating any illustrative or mechanical diagram, **stop and plan**. Work through these steps mentally before writing any SVG: + +1. **Subject decomposition**: What are the 3-5 key subsystems? Which are primary (must be visually prominent) vs secondary (annotation-level detail)? + +2. **Educational priority**: What is the ONE most important concept to convey? Everything else supports this. (e.g., for "how cars work" the key insight is energy conversion: fuel → spin → motion) + +3. **Spatial layout**: Where does each component physically sit relative to others? Mentally assign components to a rough coordinate grid: + - Left/right positioning (e.g., engine front, differential rear) + - Top/bottom positioning (e.g., wing above fuselage, wheels below body) + - Overlap relationships (e.g., pistons inside cylinders) + +4. **Composition sketch**: Define bounding rectangles before writing SVG: + - Main illustration: `x=__, y=__, w=__, h=__` + - Annotation margin: `x=490, y=40, w=150, h=__` + - Sub-diagram zone (if needed): `x=__, y=__, w=__, h=__` + - Controls area (if interactive): below the SVG + +5. **Shape fidelity check**: For the primary subject, list 4-6 defining visual features that make it recognizable. Each must appear in the final SVG. + +6. **Control-to-visual mapping** (if interactive): For each slider/button, identify which SVG element IDs it will modify and what attribute changes (fill, transform, text content, path d, etc.). + +This planning step prevents the most common illustrative diagram failures: unrecognizable shapes, spatially inaccurate component placement, and disconnected interactive controls. --- diff --git a/apps/agent/skills/svg-shape-library.txt b/apps/agent/skills/svg-shape-library.txt new file mode 100644 index 0000000..cd9602c --- /dev/null +++ b/apps/agent/skills/svg-shape-library.txt @@ -0,0 +1,317 @@ +# SVG Shape Library + +Pre-designed SVG path fragments for common objects in mechanical and illustrative diagrams. Use these as **starting points** — adapt proportions, add/remove details, and recolor to match your diagram's needs. Never paste verbatim without adapting to context. + +All shapes use a **normalized coordinate space** (noted per shape). Use `transform="translate(x,y) scale(s)"` to position and resize within your diagram. + +--- + +## Vehicles + +### Sedan Side Profile +**Coordinate space**: 0-400 wide, 0-120 tall. Origin at top-left. + +```svg + + + + + + + + + + + + + + + + + + + + + + + + + +``` +**Customization**: Adjust roof arc control point for sportier/boxier look. Change wheel size for SUV (r=28). Remove hood slope for van/bus. + +--- + +### Airplane Side Profile +**Coordinate space**: 0-420 wide, 0-140 tall. + +```svg + + + + + + + + + + + + + + + + + + + + + + + + + +``` +**Customization**: Remove cabin windows for schematic view. Add second engine nacelle at cx=220 for twin-engine. Adjust wing sweep by changing the wing path control points. + +--- + +## Mechanical Parts + +### Gear/Cog +**Coordinate space**: 0-60 wide, 0-60 tall. Center at (30,30). + +```svg + + + + + + + + + + + + + + + + + +``` + +### Piston & Cylinder +**Coordinate space**: 0-50 wide, 0-100 tall. + +```svg + + + + + + + + + + + + + + +``` + +### Wheel with Spokes +**Coordinate space**: 0-80 wide, 0-80 tall. Center at (40,40). + +```svg + + + + + + + + + + + + + + + + +``` + +--- + +## Physics Shapes + +### Airfoil Cross-Section (NACA-style) +**Coordinate space**: 0-300 wide, 0-80 tall. + +```svg + + + + + + + + + + +``` +**Customization**: Adjust the upper surface control points (y=18, y=14, y=10) for more/less camber. For a symmetric airfoil, mirror the bottom curve to match the top. + +### Force Arrow (Large, Labeled) +**Coordinate space**: width varies, 0-30 tall. + +```svg + + + + + Thrust + + + + + + +``` +**Color conventions**: Blue/teal for propulsion (thrust, lift). Coral/red for resistance (drag, friction, braking). Gray for gravity (weight). Amber for user-applied forces. + +--- + +## Annotation Elements + +### Zoom Callout Box +Highlights an area in the main diagram and connects it to a sub-diagram. + +```svg + + + + + + + + ++ +``` + +### Dimension Line with Tick Marks + +```svg + + + + + + + + 2.4 m + +``` + +--- + +## Control Surfaces (Airplane) + +### Rudder (Neutral and Deflected) + +```svg + + + + rudder + + + + + + rudder (yaw right) + +``` + +### Aileron (Neutral and Deflected) + +```svg + + + + + + + + + + + + + + +``` + +### Elevator (Neutral and Deflected) + +```svg + + + + + + + + + +``` + +--- + +## Usage Notes + +- **Adapt, don't copy**: These shapes are starting points. Change proportions, colors, and detail level to match your diagram's needs and scale. +- **Scale with transform**: Use `transform="translate(x,y) scale(factor)"` on the `` wrapper to position within your viewBox. A `scale(0.5)` halves the shape. +- **Consistent stroke width**: After scaling, stroke widths also scale. If you scale down significantly (< 0.5), increase stroke-width to maintain visibility. +- **Color adaptation**: Replace the hardcoded fills/strokes with colors from the SVG Diagram Skill color palette that match your diagram's color scheme. +- **Combine shapes**: Layer these fragments. A car with its hood open = sedan profile + piston visible through hood gap + zoom callout to engine detail. diff --git a/apps/mcp/skills/master-agent-playbook.txt b/apps/mcp/skills/master-agent-playbook.txt index e27ff25..287f4f5 100644 --- a/apps/mcp/skills/master-agent-playbook.txt +++ b/apps/mcp/skills/master-agent-playbook.txt @@ -218,6 +218,106 @@ render(); } ``` +### Architecture: Progressive Rendering for Complex Interactive Diagrams + +When building interactive diagrams with controls (sliders, buttons, presets), use this structured architecture instead of scattered inline handlers. This ensures controls and visuals stay connected. + +**HTML Section Structure** — organize your HTML in explicit, commented sections: + +```html + + + + + 0 rpm + + + + +
+ ... +
+
Engine speed: 0 rpm
+
Wheel force: 0
+
+
+ + +
+ + + + +
+ + + +``` + +**Element ID Convention**: `viz-{component}-{property}` +- `viz-engine-fill` — engine block fill color/opacity +- `viz-speed-text` — speed readout text content +- `viz-force-arrow` — force arrow being resized +- `viz-rpm` — RPM stat display + +This convention makes it trivial to trace which control affects which visual element. Every `updateState` call triggers `render()`, which updates every dynamic element from the centralized state. + +**Key rules**: +- Never use anonymous `oninput="document.getElementById(...)"` handlers. Always go through `updateState` → `render`. +- Every slider/button must produce a visible change in the SVG — if a control doesn't update anything visual, remove it. +- Preset buttons must also update slider positions to stay in sync. +- The `render()` function should be idempotent — calling it twice with the same state produces the same output. + --- ## Part 3: Skill — Data Visualization diff --git a/apps/mcp/skills/mechanical-illustration-skill.txt b/apps/mcp/skills/mechanical-illustration-skill.txt new file mode 100644 index 0000000..1c22ba6 --- /dev/null +++ b/apps/mcp/skills/mechanical-illustration-skill.txt @@ -0,0 +1,350 @@ +# Mechanical & Illustrative Diagram Skill + +This skill extends the SVG Diagram Skill with specific guidance for mechanical and physical-world illustrations — cars, airplanes, engines, circuits, buildings, and similar real-world objects where **shape fidelity** and **spatial accuracy** matter. + +Use this skill whenever you need to illustrate something that exists in the physical world and has a recognizable form. + +--- + +## Shape Construction Method + +LLMs cannot reliably produce accurate freehand SVG paths. Instead, **compose recognizable shapes from geometric primitives**. + +### The Primitive Composition Rule + +Break every real-world object into 4-8 simple SVG elements: + +| Primitive | SVG Element | Use For | +|-----------|------------|---------| +| Rectangle | `` with `rx` | Bodies, blocks, panels, frames | +| Circle/Ellipse | ``, `` | Wheels, gears, dials, ports | +| Trapezoid | `` or `` | Windshields, tapered sections | +| Arc/Curve | `` with cubic bezier | Hood slopes, fuselage tapers, airfoils | +| Line | `` | Axles, shafts, structural members | +| Rounded path | `` with Q/C commands | Organic contours, fenders | + +### Example: Car Side Profile (Composed from Primitives) + +```svg + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +**Key principle**: Each primitive is a separate element that can be individually styled, labeled, or animated. The composition reads top-to-bottom as: body → hood → cabin → roof → trunk → wheels. + +--- + +## Spatial Accuracy Rules + +### Grid Overlay Technique + +Before placing components, mentally divide the main subject into a grid: + +1. **Horizontal zones** — for a car: front bumper (0-15%), engine bay (15-35%), cabin (35-65%), trunk (65-85%), rear bumper (85-100%) +2. **Vertical zones** — roof (0-25%), windows (25-40%), body (40-70%), undercarriage (70-85%), wheels (85-100%) + +Place components within their correct grid cell. An engine MUST be in the front 15-35% zone. A differential MUST be in the rear 65-85% zone. + +### Spatial Rules + +- **Components must be positioned where they physically exist** in the real object. Never float a component outside its container. +- **Overlapping indicates containment**: pistons overlap with cylinders, gears mesh with each other, wires run through conduits. +- **Connection lines must follow physical paths**: a driveshaft runs horizontally from transmission to differential, not diagonally through the cabin. +- **Scale matters**: an engine block is larger than a spark plug. Maintain approximate relative proportions. + +--- + +## Annotation Hierarchy + +Use three distinct tiers so the viewer's eye finds the most important information first. + +### Tier 1: Primary Labels (max 5 per diagram) +```svg + + + +Engine +power source +``` + +### Tier 2: Secondary Labels +```svg + + + +driveshaft +``` + +### Tier 3: Tertiary Labels (inline, no leader) +```svg + +front wheel +``` + +**Placement rules**: +- All Tier 1 and 2 labels go in the annotation margin (x=490 to x=640). +- Leader lines must be angled — never purely horizontal. Angle conveys which element they point to. +- Leader lines must never cross each other. If they would, reorder vertically. +- Tier 3 labels sit directly below or beside the element they describe. + +--- + +## Sub-Diagram Quality Standards + +Sub-diagrams appear in the sub-diagram zone (bottom 25% of the SVG or in a separate card below). They zoom into a specific subsystem. + +### Requirements + +1. **Minimum viewBox**: 150×100 units. Anything smaller is unreadable. +2. **Same shape standards**: Sub-diagrams must use the primitive composition method. No placeholder rectangles. +3. **Visual connection**: Link the sub-diagram to the main illustration with one of: + - A dotted leader line from the relevant area to the sub-diagram + - A "zoom bracket" — a dashed rectangle around the area in the main diagram, with a line to the sub-diagram + - A matching color that ties the sub-diagram to its parent region + +### Example: Pedal Sub-Diagram (Good vs Bad) + +**Bad** (oversimplified): +```svg + + + + +``` + +**Good** (recognizable pedal shapes): +```svg + + + +clutch + + + +brake + + + +throttle + + + +``` + +--- + +## Interactive Control Binding + +When a diagram has interactive controls (sliders, buttons), every control must produce a visible change in the SVG. + +### Binding Pattern + +```javascript +// 1. Define state with meaningful defaults +const state = { throttle: 30, gear: 2, steering: 0 }; + +// 2. Physics/logic model — compute derived values from state +function compute() { + const rpm = state.throttle * 40 + state.gear * 200; + const speed = rpm / (state.gear * 25 + 50); + const force = state.throttle * (7 - state.gear) * 0.5; + return { rpm, speed: Math.round(speed), force: Math.round(force) }; +} + +// 3. Render — apply computed values to SVG elements +function render() { + const v = compute(); + + // Update text readouts + setText('viz-rpm', v.rpm.toLocaleString() + ' rpm'); + setText('viz-speed', v.speed + ' mph'); + setText('viz-force', v.force); + + // Update visual indicators + setAttr('viz-engine-glow', 'opacity', 0.2 + state.throttle * 0.008); + setAttr('viz-force-arrow', 'x2', + getAttr('viz-force-arrow', 'x1') + v.force * 2); + + // Highlight active preset button + document.querySelectorAll('.preset-btn').forEach(b => + b.classList.toggle('active', b.dataset.preset === state.mode)); +} + +// Helpers +function setText(id, val) { + const el = document.getElementById(id); + if (el) el.textContent = val; +} +function setAttr(id, attr, val) { + const el = document.getElementById(id); + if (el) el.setAttribute(attr, val); +} +function getAttr(id, attr) { + const el = document.getElementById(id); + return el ? +el.getAttribute(attr) : 0; +} +``` + +### What "Visible Change" Means + +For each control, at least one of these must change in the SVG: +- **Fill opacity/color** — e.g., engine glows brighter at higher RPM +- **Element position** — e.g., piston moves up/down, needle rotates +- **Path length/size** — e.g., force arrow grows/shrinks +- **Text content** — e.g., speed readout updates +- **Stroke dash animation speed** — e.g., flow particles speed up + +If a control doesn't change anything visual, remove it. + +--- + +## Worked Reference: Car Drivetrain Composition + +This shows the complete planning-to-SVG process for a "how do cars work?" response. + +### Planning Step + +1. **Subject decomposition**: Engine (primary), Transmission (primary), Differential (primary), Driveshaft (secondary), Wheels (secondary), Brakes (secondary) +2. **Educational priority**: Energy conversion chain — fuel burns → crankshaft spins → gears trade speed for force → wheels push road +3. **Spatial layout**: Left-to-right: Engine (x=100-200) → Transmission (x=220-320) → Driveshaft (x=320-400) → Differential (x=400-480) → Wheels (x=480-540) +4. **Shape fidelity**: Car needs: body rectangle, hood slope, windshield, roof arc, 2 wheels with hubs, wheel wells +5. **Control mapping**: Throttle slider → viz-engine-glow opacity + viz-rpm text; Gear slider → viz-gear-text + viz-force text + +### SVG Structure Outline + +``` +Car silhouette (composed from 8 primitives) + └─ Engine block (teal rect, positioned in front 20%) + └─ Transmission (purple rect, positioned at 35%) + └─ Driveshaft (line connecting transmission to differential) + └─ Differential (blue rect, positioned at 70%) + └─ Flow arrows: engine → transmission → driveshaft → differential → wheels +Annotation margin (x=490): + └─ "Engine" — primary label with leader + └─ "Transmission" — primary label with leader + └─ "Differential" — primary label with leader + └─ "brakes squeeze rotors" — secondary label +Sub-diagram zone: + └─ Pedal arrangement (clutch/brake/throttle with proper shapes) + └─ Steering wheel indicator +Controls: + └─ Throttle slider, Gear slider + └─ Preset buttons: City, Highway, Braking +Stats: + └─ Engine speed (rpm), Wheel force, Road speed (mph) +``` + +--- + +## Worked Reference: Airfoil / Airplane Composition + +### Planning Step + +1. **Subject decomposition**: Wing/airfoil (primary), Forces — lift/weight/thrust/drag (primary), Control surfaces (secondary), Engine (secondary) +2. **Educational priority**: Lift generation — wing shape creates pressure difference, net upward force +3. **Spatial layout**: Airplane centered horizontally. Forces as arrows: Lift (up from wing center), Weight (down from fuselage center), Thrust (right from engine), Drag (left from nose) +4. **Shape fidelity**: Airplane needs: fuselage cylinder, wing cross-section (NACA-style curve), tail fin, engine nacelle, cockpit windows +5. **Control mapping**: Engine power → viz-thrust-arrow length + viz-thrust-text; Wing angle → viz-lift-arrow length + airfoil rotation + +### Airfoil Cross-Section Shape + +The airfoil is the most important shape for airplane diagrams. Use this NACA-style profile: + +```svg + + + + + + + + + + + +``` + +### Control Surfaces Sub-Diagram + +```svg + + + + + + + + + + + + + + + + + + + + + + + +ailerons: roll +rudder: yaw +elevator: pitch +``` + +--- + +## Common Mistakes to Avoid + +1. **Single-path silhouettes**: Don't draw `` for a car outline. It will look wrong. Use primitives. +2. **Floating components**: An engine drawn at x=400 in a car that spans x=100-500 is in the trunk. Check your grid. +3. **Placeholder rectangles**: Three identical rectangles labeled "clutch", "brake", "throttle" convey nothing. Give them distinct shapes and proportions. +4. **Disconnected controls**: A "throttle" slider that doesn't change anything in the SVG is useless. Every control needs a visible effect. +5. **Label soup**: 10 primary labels at the same font size creates visual noise. Use the 3-tier hierarchy. +6. **Missing physics**: Force arrows without labels or with wrong directions are worse than no arrows. Double-check: lift points UP, weight points DOWN, thrust points FORWARD, drag points BACKWARD. diff --git a/apps/mcp/skills/svg-diagram-skill.txt b/apps/mcp/skills/svg-diagram-skill.txt index 2a28385..6a48620 100644 --- a/apps/mcp/skills/svg-diagram-skill.txt +++ b/apps/mcp/skills/svg-diagram-skill.txt @@ -155,13 +155,87 @@ If you're rendering inside a system that supports CSS variables, prefer: - Use different color ramps for parent vs child to show hierarchy. ### 3. Illustrative Diagram -**When**: Building intuition. "How does X actually work?" +**When**: Building intuition. "How does X actually work?" (engines, airplanes, circuits, load paths) **Layout**: Freeform — follows the subject's natural geometry. -**Rules**: + +**Composition Zones** (divide the 680px viewBox): +- **Main illustration**: x=40 to x=480, full height. This is where the primary subject lives. +- **Annotation margin**: x=490 to x=640. Primary and secondary labels go here with leader lines pointing into the illustration. +- **Sub-diagram zone** (optional): bottom 25% of height. For detail callouts (e.g., pedal arrangement, control surface close-up). +- Never let the main illustration bleed into the annotation margin. + +**Depth Layering Order** (draw in this sequence for proper stacking): +1. Background/context shapes (low opacity, large, sets the scene) +2. Main subject silhouette (the recognizable outline — car body, airplane fuselage) +3. Internal components (engine, transmission, etc. — positioned where they physically exist) +4. Connectors and flow lines (driveshafts, force arrows, data paths) +5. Labels and annotations (always on top, never occluded) + +**Shape Construction** (critical for recognizable real-world objects): +- **Never draw a complex object as a single ``**. LLMs cannot reliably produce accurate freehand SVG paths. +- Instead, **compose from 4-8 geometric primitives**: a car = body rect with rounded corners + hood slope path + windshield trapezoid + 2 wheel circles + bumper rects. +- Each primitive should be a separate SVG element so it can be individually styled and labeled. +- Test: "Would someone recognize what this is without labels?" If not, add more defining features. +- Key features that make objects recognizable: + - **Car**: wheel wells, hood slope, windshield angle, roof line, distinct front/rear + - **Airplane**: fuselage taper, wing sweep, tail fin, engine nacelles + - **Building**: floor lines, window grid, foundation, roof pitch + +**Force & Motion Arrows**: +- Use larger arrowheads for force arrows: `markerWidth="8" markerHeight="8"` (vs default 6 for connectors). +- Color-code by type: warm (coral/red) for resistance/friction, cool (blue/teal) for propulsion/thrust, gray for gravity/neutral forces. +- Scale arrow stroke width to indicate magnitude: 1.5px normal, 2.5px for dominant forces. +- Always label force arrows with both name and direction. + +**Annotation Hierarchy**: +- **Primary labels** (14px, font-weight 500, solid leader lines at 1px stroke): main components being explained. Max 5 per diagram. +- **Secondary labels** (12px, font-weight 400, dashed leader lines at 0.5px stroke): supporting details and dimensions. +- **Tertiary labels** (11px, font-weight 400, inline with no leader line): minor callouts, units, values. +- Leader lines should be angled (not purely horizontal/vertical) and must never cross each other. + +**Cross-Section vs Side View**: +- Use **side profile** for: force diagrams, motion paths, external appearance, spatial relationships between subsystems. +- Use **cross-section (cut-away)** for: internal mechanisms, flow paths through chambers, layered structures. +- When using cross-section, draw a dashed line indicating the cut plane and label it (e.g., "section A-A"). + +**Sub-Diagram Standards**: +- Minimum viewBox area: 150×100 units. +- Visually connect to the main diagram with a dotted leader line or a "zoom" callout bracket. +- Sub-diagrams must meet the same shape quality standards as the main illustration — no placeholder rectangles. + +**General Rules**: - Shapes can be freeform (paths, ellipses, polygons), not just rects. - Color encodes intensity, not category (warm = active, cool = dormant). - Overlap shapes for depth, but never let strokes cross text. -- Labels go in margins with leader lines pointing to the relevant part. +- Components must be positioned where they physically exist in the real object — don't float an engine in the trunk. +- Max 5-7 labeled components per diagram. If more, use the multi-diagram approach. + +--- + +## Diagram Planning Protocol + +Before generating any illustrative or mechanical diagram, **stop and plan**. Work through these steps mentally before writing any SVG: + +1. **Subject decomposition**: What are the 3-5 key subsystems? Which are primary (must be visually prominent) vs secondary (annotation-level detail)? + +2. **Educational priority**: What is the ONE most important concept to convey? Everything else supports this. (e.g., for "how cars work" the key insight is energy conversion: fuel → spin → motion) + +3. **Spatial layout**: Where does each component physically sit relative to others? Mentally assign components to a rough coordinate grid: + - Left/right positioning (e.g., engine front, differential rear) + - Top/bottom positioning (e.g., wing above fuselage, wheels below body) + - Overlap relationships (e.g., pistons inside cylinders) + +4. **Composition sketch**: Define bounding rectangles before writing SVG: + - Main illustration: `x=__, y=__, w=__, h=__` + - Annotation margin: `x=490, y=40, w=150, h=__` + - Sub-diagram zone (if needed): `x=__, y=__, w=__, h=__` + - Controls area (if interactive): below the SVG + +5. **Shape fidelity check**: For the primary subject, list 4-6 defining visual features that make it recognizable. Each must appear in the final SVG. + +6. **Control-to-visual mapping** (if interactive): For each slider/button, identify which SVG element IDs it will modify and what attribute changes (fill, transform, text content, path d, etc.). + +This planning step prevents the most common illustrative diagram failures: unrecognizable shapes, spatially inaccurate component placement, and disconnected interactive controls. --- diff --git a/apps/mcp/skills/svg-shape-library.txt b/apps/mcp/skills/svg-shape-library.txt new file mode 100644 index 0000000..cd9602c --- /dev/null +++ b/apps/mcp/skills/svg-shape-library.txt @@ -0,0 +1,317 @@ +# SVG Shape Library + +Pre-designed SVG path fragments for common objects in mechanical and illustrative diagrams. Use these as **starting points** — adapt proportions, add/remove details, and recolor to match your diagram's needs. Never paste verbatim without adapting to context. + +All shapes use a **normalized coordinate space** (noted per shape). Use `transform="translate(x,y) scale(s)"` to position and resize within your diagram. + +--- + +## Vehicles + +### Sedan Side Profile +**Coordinate space**: 0-400 wide, 0-120 tall. Origin at top-left. + +```svg + + + + + + + + + + + + + + + + + + + + + + + + + +``` +**Customization**: Adjust roof arc control point for sportier/boxier look. Change wheel size for SUV (r=28). Remove hood slope for van/bus. + +--- + +### Airplane Side Profile +**Coordinate space**: 0-420 wide, 0-140 tall. + +```svg + + + + + + + + + + + + + + + + + + + + + + + + + +``` +**Customization**: Remove cabin windows for schematic view. Add second engine nacelle at cx=220 for twin-engine. Adjust wing sweep by changing the wing path control points. + +--- + +## Mechanical Parts + +### Gear/Cog +**Coordinate space**: 0-60 wide, 0-60 tall. Center at (30,30). + +```svg + + + + + + + + + + + + + + + + + +``` + +### Piston & Cylinder +**Coordinate space**: 0-50 wide, 0-100 tall. + +```svg + + + + + + + + + + + + + + +``` + +### Wheel with Spokes +**Coordinate space**: 0-80 wide, 0-80 tall. Center at (40,40). + +```svg + + + + + + + + + + + + + + + + +``` + +--- + +## Physics Shapes + +### Airfoil Cross-Section (NACA-style) +**Coordinate space**: 0-300 wide, 0-80 tall. + +```svg + + + + + + + + + + +``` +**Customization**: Adjust the upper surface control points (y=18, y=14, y=10) for more/less camber. For a symmetric airfoil, mirror the bottom curve to match the top. + +### Force Arrow (Large, Labeled) +**Coordinate space**: width varies, 0-30 tall. + +```svg + + + + + Thrust + + + + + + +``` +**Color conventions**: Blue/teal for propulsion (thrust, lift). Coral/red for resistance (drag, friction, braking). Gray for gravity (weight). Amber for user-applied forces. + +--- + +## Annotation Elements + +### Zoom Callout Box +Highlights an area in the main diagram and connects it to a sub-diagram. + +```svg + + + + + + + + ++ +``` + +### Dimension Line with Tick Marks + +```svg + + + + + + + + 2.4 m + +``` + +--- + +## Control Surfaces (Airplane) + +### Rudder (Neutral and Deflected) + +```svg + + + + rudder + + + + + + rudder (yaw right) + +``` + +### Aileron (Neutral and Deflected) + +```svg + + + + + + + + + + + + + + +``` + +### Elevator (Neutral and Deflected) + +```svg + + + + + + + + + +``` + +--- + +## Usage Notes + +- **Adapt, don't copy**: These shapes are starting points. Change proportions, colors, and detail level to match your diagram's needs and scale. +- **Scale with transform**: Use `transform="translate(x,y) scale(factor)"` on the `` wrapper to position within your viewBox. A `scale(0.5)` halves the shape. +- **Consistent stroke width**: After scaling, stroke widths also scale. If you scale down significantly (< 0.5), increase stroke-width to maintain visibility. +- **Color adaptation**: Replace the hardcoded fills/strokes with colors from the SVG Diagram Skill color palette that match your diagram's color scheme. +- **Combine shapes**: Layer these fragments. A car with its hood open = sedan profile + piston visible through hood gap + zoom callout to engine detail.