mirrors/hermes-agent
1
0
Fork 0
mirror of https://github.com/NousResearch/hermes-agent.git synced 2026-06-21 10:22:18 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

feat(skills): add html-artifact skill, fold in sketch + architecture-diagram + concept-diagrams (#48899)

Browse source 
* feat(skills): add html-artifact skill, fold in sketch + architecture-diagram + concept-diagrams

Adds a unified `html-artifact` creative skill that produces self-contained,
single-file HTML artifacts — concept explainers, implementation plans,
status/incident reports, code-review walkthroughs, technical + educational
SVG diagrams, multi-variant design comparisons, and throwaway editors that
export their state back to the clipboard. Grounded in Anthropic's
html-effectiveness gallery (MIT); the house style (token block, serif/sans/
mono split, hand-rolled diffs, inline-SVG diagrams, graceful degradation) is
distilled from reading all 20 reference files.

Supersedes and removes three overlapping skills, folding their unique value in:
- sketch              -> the fidelity dial (throwaway vs presentation) + the
                         multi-variant comparison layouts + the browser-vision
                         verify loop (references/fidelity-and-verify.md)
- architecture-diagram-> the dark "infra" token variant + double-rect masking +
                         semantic component palette (references/dark-tech.md,
                         templates/diagram.html infra mode)
- concept-diagrams    -> the 9-ramp educational color system + the concept
                         archetype library (references/concept-archetypes.md,
                         the light design system in templates/diagram.html)

Structure:
- SKILL.md (description exactly 60 chars), 6 references, 3 templates
- templates verified by headless-Chrome render + vision inspection
- editor export logic (file://-safe clipboard, Promise-normalized) verified in node

Cross-references updated in claude-design (new disambiguation table row drawing
the design-taste vs information-artifact boundary), design-md, pretext, spike,
and kanban-video-orchestrator. Website skill docs + catalogs regenerated;
stale EN/zh-Hans per-skill pages pruned and i18n cross-refs fixed.

Not folded (intentionally orthogonal): excalidraw (.excalidraw JSON), p5js
(generative canvas), claude-design / popular-web-designs / design-md (visual
design taste / brand vocab / token spec).

* feat(skills): ship html-effectiveness gallery as fetched reference examples

Add scripts/fetch-examples.sh (idempotent clone/pull of Anthropic's MIT
html-effectiveness gallery) + references/examples.md mapping each of the 20
example files to a mode so the agent reads the right worked example. The clone
lands in references/examples/ and is gitignored (it's a 384KB upstream repo,
not vendored). SKILL.md workflow + reference list now point at it; falls back to
the distilled pattern references when offline.

* feat(skills): make reading a gallery example a required authoring step

Reading the matching html-effectiveness example is now workflow step 2 (was an
optional aside in step 3): fetch the gallery, read_file the file for your mode,
mirror its structure. Models skip optional steps; the examples are the ground
truth, so consulting one is mandatory. Added an 'Example' column to the
mode->build quick-reference table and a 'don't skip the example' pitfall.

Also dogfooded the skill: read 03-code-review-pr.html and 13-flowchart-diagram.html
raw and reconciled the distilled references against source — aligned diff-row tint
opacity to the source's 0.15 (was 0.18) and added the .ctx/.hunk rows in
house-style.md + base.html so they match 03-code-review-pr.html verbatim.

* docs(skills): explain the consolidation + bundled-vs-optional rationale

The supersession note only stated *what* was folded, not *why* the prune is
sound. Expand SKILL.md's intro into a 'Why this skill exists' section: the three
former skills emitted the same artifact and overlapped, so consolidating removes
which-one-do-I-load ambiguity; and the optional->bundled promotion of
concept-diagrams is footprint-safe because this skill has zero deps (only cost is
the 60-char description; everything else is progressive-disclosure). States the
bundling dividing line explicitly: zero install cost + broadly useful gets
bundled, real install cost (hyperframes: Node+FFmpeg+Chromium) stays optional.

Regenerated website per-skill page to match.
This commit is contained in:
Siddharth Balyan 2026-06-19 13:32:31 +05:30 • committed by GitHub
parent 3f0e9849e7
commit 9362ce2575
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
98 changed files with 1610 additions and 6336 deletions
Download patch file Download diff file Expand all files Collapse all files

362
optional-skills/creative/concept-diagrams/SKILL.md
View file

@ -1,362 +0,0 @@
---
name: concept-diagrams
description: Generate flat, minimal light/dark-aware SVG diagrams as standalone HTML files, using a unified educational visual language with 9 semantic color ramps, sentence-case typography, and automatic dark mode. Best suited for educational and non-software visuals — physics setups, chemistry mechanisms, math curves, physical objects (aircraft, turbines, smartphones, mechanical watches), anatomy, floor plans, cross-sections, narrative journeys (lifecycle of X, process of Y), hub-spoke system integrations (smart city, IoT), and exploded layer views. If a more specialized skill exists for the subject (dedicated software/cloud architecture, hand-drawn sketches, animated explainers, etc.), prefer that — otherwise this skill can also serve as a general-purpose SVG diagram fallback with a clean educational look. Ships with 15 example diagrams.
version: 0.1.0
author: v1k22 (original PR), ported into hermes-agent
license: MIT
dependencies: []
platforms: [linux, macos, windows]
metadata:
hermes:
tags: [diagrams, svg, visualization, education, physics, chemistry, engineering]
related_skills: [architecture-diagram, excalidraw, generative-widgets]
---
# Concept Diagrams
Generate production-quality SVG diagrams with a unified flat, minimal design system. Output is a single self-contained HTML file that renders identically in any modern browser, with automatic light/dark mode.
## Scope
**Best suited for:**
- Physics setups, chemistry mechanisms, math curves, biology
- Physical objects (aircraft, turbines, smartphones, mechanical watches, cells)
- Anatomy, cross-sections, exploded layer views
- Floor plans, architectural conversions
- Narrative journeys (lifecycle of X, process of Y)
- Hub-spoke system integrations (smart city, IoT networks, electricity grids)
- Educational / textbook-style visuals in any domain
- Quantitative charts (grouped bars, energy profiles)
**Look elsewhere first for:**
- Dedicated software / cloud infrastructure architecture with a dark tech aesthetic (consider `architecture-diagram` if available)
- Hand-drawn whiteboard sketches (consider `excalidraw` if available)
- Animated explainers or video output (consider an animation skill)
If a more specialized skill is available for the subject, prefer that. If none fits, this skill can serve as a general-purpose SVG diagram fallback — the output will carry the clean educational aesthetic described below, which is a reasonable default for almost any subject.
## Workflow
1. Decide on the diagram type (see Diagram Types below).
2. Lay out components using the Design System rules.
3. Write the full HTML page using `templates/template.html` as the wrapper — paste your SVG where the template says `<!-- PASTE SVG HERE -->`.
4. Save as a standalone `.html` file (for example `~/my-diagram.html` or `./my-diagram.html`).
5. User opens it directly in a browser — no server, no dependencies.
Optional: if the user wants a browsable gallery of multiple diagrams, see "Local Preview Server" at the bottom.
Load the HTML template:
```
skill_view(name="concept-diagrams", file_path="templates/template.html")
```
The template embeds the full CSS design system (`c-*` color classes, text classes, light/dark variables, arrow marker styles). The SVG you generate relies on these classes being present on the hosting page.
---
## Design System
### Philosophy
- **Flat**: no gradients, drop shadows, blur, glow, or neon effects.
- **Minimal**: show the essential. No decorative icons inside boxes.
- **Consistent**: same colors, spacing, typography, and stroke widths across every diagram.
- **Dark-mode ready**: all colors auto-adapt via CSS classes — no per-mode SVG.
### Color Palette
9 color ramps, each with 7 stops. Put the class name on a `<g>` or shape element; the template CSS handles both modes.
| Class | 50 (lightest) | 100 | 200 | 400 | 600 | 800 | 900 (darkest) |
|------------|---------------|---------|---------|---------|---------|---------|---------------|
| `c-purple` | #EEEDFE | #CECBF6 | #AFA9EC | #7F77DD | #534AB7 | #3C3489 | #26215C |
| `c-teal` | #E1F5EE | #9FE1CB | #5DCAA5 | #1D9E75 | #0F6E56 | #085041 | #04342C |
| `c-coral` | #FAECE7 | #F5C4B3 | #F0997B | #D85A30 | #993C1D | #712B13 | #4A1B0C |
| `c-pink` | #FBEAF0 | #F4C0D1 | #ED93B1 | #D4537E | #993556 | #72243E | #4B1528 |
| `c-gray` | #F1EFE8 | #D3D1C7 | #B4B2A9 | #888780 | #5F5E5A | #444441 | #2C2C2A |
| `c-blue` | #E6F1FB | #B5D4F4 | #85B7EB | #378ADD | #185FA5 | #0C447C | #042C53 |
| `c-green` | #EAF3DE | #C0DD97 | #97C459 | #639922 | #3B6D11 | #27500A | #173404 |
| `c-amber` | #FAEEDA | #FAC775 | #EF9F27 | #BA7517 | #854F0B | #633806 | #412402 |
| `c-red` | #FCEBEB | #F7C1C1 | #F09595 | #E24B4A | #A32D2D | #791F1F | #501313 |
#### Color Assignment Rules
Color encodes **meaning**, not sequence. Never cycle through colors like a rainbow.
- Group nodes by **category** — all nodes of the same type share one color.
- Use `c-gray` for neutral/structural nodes (start, end, generic steps, users).
- Use **2-3 colors per diagram**, not 6+.
- Prefer `c-purple`, `c-teal`, `c-coral`, `c-pink` for general categories.
- Reserve `c-blue`, `c-green`, `c-amber`, `c-red` for semantic meaning (info, success, warning, error).
Light/dark stop mapping (handled by the template CSS — just use the class):
- Light mode: 50 fill + 600 stroke + 800 title / 600 subtitle
- Dark mode: 800 fill + 200 stroke + 100 title / 200 subtitle
### Typography
Only two font sizes. No exceptions.
| Class | Size | Weight | Use |
|-------|------|--------|-----|
| `th` | 14px | 500 | Node titles, region labels |
| `ts` | 12px | 400 | Subtitles, descriptions, arrow labels |
| `t` | 14px | 400 | General text |
- **Sentence case always.** Never Title Case, never ALL CAPS.
- Every `<text>` MUST carry a class (`t`, `ts`, or `th`). No unclassed text.
- `dominant-baseline="central"` on all text inside boxes.
- `text-anchor="middle"` for centered text in boxes.
**Width estimation (approx):**
- 14px weight 500: ~8px per character
- 12px weight 400: ~6.5px per character
- Always verify: `box_width >= (char_count × px_per_char) + 48` (24px padding each side)
### Spacing & Layout
- **ViewBox**: `viewBox="0 0 680 H"` where H = content height + 40px buffer.
- **Safe area**: x=40 to x=640, y=40 to y=(H-40).
- **Between boxes**: 60px minimum gap.
- **Inside boxes**: 24px horizontal padding, 12px vertical padding.
- **Arrowhead gap**: 10px between arrowhead and box edge.
- **Single-line box**: 44px height.
- **Two-line box**: 56px height, 18px between title and subtitle baselines.
- **Container padding**: 20px minimum inside every container.
- **Max nesting**: 2-3 levels deep. Deeper gets unreadable at 680px width.
### Stroke & Shape
- **Stroke width**: 0.5px on all node borders. Not 1px, not 2px.
- **Rect rounding**: `rx="8"` for nodes, `rx="12"` for inner containers, `rx="16"` to `rx="20"` for outer containers.
- **Connector paths**: MUST have `fill="none"`. SVG defaults to `fill: black` otherwise.
### Arrow Marker
Include this `<defs>` block at the start of **every** SVG:
```xml
<defs>
<marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5"
markerWidth="6" markerHeight="6" orient="auto-start-reverse">
<path d="M2 1L8 5L2 9" fill="none" stroke="context-stroke"
stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
</marker>
</defs>
```
Use `marker-end="url(#arrow)"` on lines. The arrowhead inherits the line color via `context-stroke`.
### CSS Classes (Provided by the Template)
The template page provides:
- Text: `.t`, `.ts`, `.th`
- Neutral: `.box`, `.arr`, `.leader`, `.node`
- Color ramps: `.c-purple`, `.c-teal`, `.c-coral`, `.c-pink`, `.c-gray`, `.c-blue`, `.c-green`, `.c-amber`, `.c-red` (all with automatic light/dark mode)
You do **not** need to redefine these — just apply them in your SVG. The template file contains the full CSS definitions.
---
## SVG Boilerplate
Every SVG inside the template page starts with this exact structure:
```xml
<svg width="100%" viewBox="0 0 680 {HEIGHT}" xmlns="http://www.w3.org/2000/svg">
<defs>
<marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5"
markerWidth="6" markerHeight="6" orient="auto-start-reverse">
<path d="M2 1L8 5L2 9" fill="none" stroke="context-stroke"
stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
</marker>
</defs>
<!-- Diagram content here -->
</svg>
```
Replace `{HEIGHT}` with the actual computed height (last element bottom + 40px).
### Node Patterns
**Single-line node (44px):**
```xml
<g class="node c-blue">
<rect x="100" y="20" width="180" height="44" rx="8" stroke-width="0.5"/>
<text class="th" x="190" y="42" text-anchor="middle" dominant-baseline="central">Service name</text>
</g>
```
**Two-line node (56px):**
```xml
<g class="node c-teal">
<rect x="100" y="20" width="200" height="56" rx="8" stroke-width="0.5"/>
<text class="th" x="200" y="38" text-anchor="middle" dominant-baseline="central">Service name</text>
<text class="ts" x="200" y="56" text-anchor="middle" dominant-baseline="central">Short description</text>
</g>
```
**Connector (no label):**
```xml
<line x1="200" y1="76" x2="200" y2="120" class="arr" marker-end="url(#arrow)"/>
```
**Container (dashed or solid):**
```xml
<g class="c-purple">
<rect x="40" y="92" width="600" height="300" rx="16" stroke-width="0.5"/>
<text class="th" x="66" y="116">Container label</text>
<text class="ts" x="66" y="134">Subtitle info</text>
</g>
```
---
## Diagram Types
Choose the layout that fits the subject:
1. **Flowchart** — CI/CD pipelines, request lifecycles, approval workflows, data processing. Single-direction flow (top-down or left-right). Max 4-5 nodes per row.
2. **Structural / Containment** — Cloud infrastructure nesting, system architecture with layers. Large outer containers with inner regions. Dashed rects for logical groupings.
3. **API / Endpoint Map** — REST routes, GraphQL schemas. Tree from root, branching to resource groups, each containing endpoint nodes.
4. **Microservice Topology** — Service mesh, event-driven systems. Services as nodes, arrows for communication patterns, message queues between.
5. **Data Flow** — ETL pipelines, streaming architectures. Left-to-right flow from sources through processing to sinks.
6. **Physical / Structural** — Vehicles, buildings, hardware, anatomy. Use shapes that match the physical form — `<path>` for curved bodies, `<polygon>` for tapered shapes, `<ellipse>`/`<circle>` for cylindrical parts, nested `<rect>` for compartments. See `references/physical-shape-cookbook.md`.
7. **Infrastructure / Systems Integration** — Smart cities, IoT networks, multi-domain systems. Hub-spoke layout with central platform connecting subsystems. Semantic line styles (`.data-line`, `.power-line`, `.water-pipe`, `.road`). See `references/infrastructure-patterns.md`.
8. **UI / Dashboard Mockups** — Admin panels, monitoring dashboards. Screen frame with nested chart/gauge/indicator elements. See `references/dashboard-patterns.md`.
For physical, infrastructure, and dashboard diagrams, load the matching reference file before generating — each one provides ready-made CSS classes and shape primitives.
---
## Validation Checklist
Before finalizing any SVG, verify ALL of the following:
1. Every `<text>` has class `t`, `ts`, or `th`.
2. Every `<text>` inside a box has `dominant-baseline="central"`.
3. Every connector `<path>` or `<line>` used as arrow has `fill="none"`.
4. No arrow line crosses through an unrelated box.
5. `box_width >= (longest_label_chars × 8) + 48` for 14px text.
6. `box_width >= (longest_label_chars × 6.5) + 48` for 12px text.
7. ViewBox height = bottom-most element + 40px.
8. All content stays within x=40 to x=640.
9. Color classes (`c-*`) are on `<g>` or shape elements, never on `<path>` connectors.
10. Arrow `<defs>` block is present.
11. No gradients, shadows, blur, or glow effects.
12. Stroke width is 0.5px on all node borders.
---
## Output & Preview
### Default: standalone HTML file
Write a single `.html` file the user can open directly. No server, no dependencies, works offline. Pattern:
```python
# 1. Load the template
template = skill_view("concept-diagrams", "templates/template.html")
# 2. Fill in title, subtitle, and paste your SVG
html = template.replace(
"<!-- DIAGRAM TITLE HERE -->", "SN2 reaction mechanism"
).replace(
"<!-- OPTIONAL SUBTITLE HERE -->", "Bimolecular nucleophilic substitution"
).replace(
"<!-- PASTE SVG HERE -->", svg_content
)
# 3. Write to a user-chosen path (or ./ by default)
write_file("./sn2-mechanism.html", html)
```
Tell the user how to open it:
```
# macOS
open ./sn2-mechanism.html
# Linux
xdg-open ./sn2-mechanism.html
```
### Optional: local preview server (multi-diagram gallery)
Only use this when the user explicitly wants a browsable gallery of multiple diagrams.
**Rules:**
- Bind to `127.0.0.1` only. Never `0.0.0.0`. Exposing diagrams on all network interfaces is a security hazard on shared networks.
- Pick a free port (do NOT hard-code one) and tell the user the chosen URL.
- The server is optional and opt-in — prefer the standalone HTML file first.
Recommended pattern (lets the OS pick a free ephemeral port):
```bash
# Put each diagram in its own folder under .diagrams/
mkdir -p .diagrams/sn2-mechanism
# ...write .diagrams/sn2-mechanism/index.html...
# Serve on loopback only, free port
cd .diagrams && python3 -c "
import http.server, socketserver
with socketserver.TCPServer(('127.0.0.1', 0), http.server.SimpleHTTPRequestHandler) as s:
print(f'Serving at http://127.0.0.1:{s.server_address[1]}/')
s.serve_forever()
" &
```
If the user insists on a fixed port, use `127.0.0.1:<port>` — still never `0.0.0.0`. Document how to stop the server (`kill %1` or `pkill -f "http.server"`).
---
## Examples Reference
The `examples/` directory ships 15 complete, tested diagrams. Browse them for working patterns before writing a new diagram of a similar type:
| File | Type | Demonstrates |
|------|------|--------------|
| `hospital-emergency-department-flow.md` | Flowchart | Priority routing with semantic colors |
| `feature-film-production-pipeline.md` | Flowchart | Phased workflow, horizontal sub-flows |
| `automated-password-reset-flow.md` | Flowchart | Auth flow with error branches |
| `autonomous-llm-research-agent-flow.md` | Flowchart | Loop-back arrows, decision branches |
| `place-order-uml-sequence.md` | Sequence | UML sequence diagram style |
| `commercial-aircraft-structure.md` | Physical | Paths, polygons, ellipses for realistic shapes |
| `wind-turbine-structure.md` | Physical cross-section | Underground/above-ground separation, color coding |
| `smartphone-layer-anatomy.md` | Exploded view | Alternating left/right labels, layered components |
| `apartment-floor-plan-conversion.md` | Floor plan | Walls, doors, proposed changes in dotted red |
| `banana-journey-tree-to-smoothie.md` | Narrative journey | Winding path, progressive state changes |
| `cpu-ooo-microarchitecture.md` | Hardware pipeline | Fan-out, memory hierarchy sidebar |
| `sn2-reaction-mechanism.md` | Chemistry | Molecules, curved arrows, energy profile |
| `smart-city-infrastructure.md` | Hub-spoke | Semantic line styles per system |
| `electricity-grid-flow.md` | Multi-stage flow | Voltage hierarchy, flow markers |
| `ml-benchmark-grouped-bar-chart.md` | Chart | Grouped bars, dual axis |
Load any example with:
```
skill_view(name="concept-diagrams", file_path="examples/<filename>")
```
---
## Quick Reference: What to Use When
| User says | Diagram type | Suggested colors |
|-----------|--------------|------------------|
| "show the pipeline" | Flowchart | gray start/end, purple steps, red errors, teal deploy |
| "draw the data flow" | Data pipeline (left-right) | gray sources, purple processing, teal sinks |
| "visualize the system" | Structural (containment) | purple container, teal services, coral data |
| "map the endpoints" | API tree | purple root, one ramp per resource group |
| "show the services" | Microservice topology | gray ingress, teal services, purple bus, coral workers |
| "draw the aircraft/vehicle" | Physical | paths, polygons, ellipses for realistic shapes |
| "smart city / IoT" | Hub-spoke integration | semantic line styles per subsystem |
| "show the dashboard" | UI mockup | dark screen, chart colors: teal, purple, coral for alerts |
| "power grid / electricity" | Multi-stage flow | voltage hierarchy (HV/MV/LV line weights) |
| "wind turbine / turbine" | Physical cross-section | foundation + tower cutaway + nacelle color-coded |
| "journey of X / lifecycle" | Narrative journey | winding path, progressive state changes |
| "layers of X / exploded" | Exploded layer view | vertical stack, alternating labels |
| "CPU / pipeline" | Hardware pipeline | vertical stages, fan-out to execution ports |
| "floor plan / apartment" | Floor plan | walls, doors, proposed changes in dotted red |
| "reaction mechanism" | Chemistry | atoms, bonds, curved arrows, transition state, energy profile |

244
optional-skills/creative/concept-diagrams/examples/apartment-floor-plan-conversion.md
View file

@ -1,244 +0,0 @@
# Apartment Floor Plan: 3 BHK to 4 BHK Conversion
An architectural floor plan showing a 1,500 sq ft apartment with proposed modifications to convert from 3 BHK to 4 BHK. Demonstrates architectural drawing conventions, room layouts, proposed changes with dotted lines, and area comparison tables.
## Key Patterns Used
- **Architectural floor plan**: Top-down view with walls, doors, windows
- **Proposed modifications**: Dotted red lines for new walls
- **Room color coding**: Light fills to distinguish room types
- **Circulation paths**: Arrows showing new access routes
- **Data table**: Before/after area comparison with highlighting
- **Architectural symbols**: North arrow, scale bar, door swings
## Diagram Type
This is an **architectural floor plan** with:
- **Plan view**: Top-down orthographic projection
- **Overlay technique**: Existing structure + proposed changes
- **Quantitative data**: Area measurements and comparison table
## Architectural Drawing Elements
### Wall Styles
```xml
<!-- Outer walls (thick) -->
<line class="wall" x1="0" y1="0" x2="560" y2="0"/>
<!-- Internal walls (thinner) -->
<line class="wall-thin" x1="180" y1="0" x2="180" y2="140"/>
<!-- Proposed new walls (dotted red) -->
<line class="proposed-wall" x1="125" y1="170" x2="125" y2="330"/>
```
```css
.wall { stroke: var(--text-primary); stroke-width: 6; fill: none; stroke-linecap: square; }
.wall-thin { stroke: var(--text-primary); stroke-width: 3; fill: none; }
.proposed-wall { stroke: #A32D2D; stroke-width: 4; fill: none; stroke-dasharray: 8 4; }
```
### Door Symbols
```xml
<!-- Door opening with swing arc -->
<rect x="150" y="137" width="25" height="6" fill="var(--bg-primary)"/>
<path class="door" d="M150,140 L150,165"/>
<path class="door-swing" d="M150,140 A25,25 0 0,0 175,140"/>
<!-- Sliding door (balcony) -->
<rect x="60" y="327" width="60" height="6" fill="var(--bg-primary)" stroke="var(--text-secondary)" stroke-width="1"/>
<line x1="60" y1="330" x2="90" y2="330" stroke="var(--text-secondary)" stroke-width="2"/>
<line x1="90" y1="330" x2="120" y2="330" stroke="var(--text-secondary)" stroke-width="2" stroke-dasharray="3 3"/>
<!-- Proposed door (dotted) -->
<rect x="143" y="292" width="22" height="6" fill="var(--bg-primary)" stroke="#A32D2D" stroke-width="1" stroke-dasharray="3 2"/>
<path d="M165,295 A22,22 0 0,0 165,273" stroke="#A32D2D" stroke-width="1" stroke-dasharray="3 2" fill="none"/>
```
```css
.door { stroke: var(--text-secondary); stroke-width: 1.5; fill: none; }
.door-swing { stroke: var(--text-tertiary); stroke-width: 1; fill: none; stroke-dasharray: 3 2; }
```
### Window Symbols
```xml
<!-- Window with glass indication -->
<rect class="window" x="-3" y="30" width="6" height="50"/>
<line class="window-glass" x1="0" y1="35" x2="0" y2="75"/>
<!-- Horizontal window (top wall) -->
<rect class="window" x="220" y="-3" width="60" height="6"/>
<line class="window-glass" x1="225" y1="0" x2="275" y2="0"/>
```
```css
.window { stroke: var(--text-primary); stroke-width: 1; fill: var(--bg-primary); }
.window-glass { stroke: #378ADD; stroke-width: 2; fill: none; }
```
### Room Fills
```xml
<!-- Different colors for room types -->
<rect class="room-master" x="3" y="3" width="174" height="134" rx="2"/>
<rect class="room-bed2" x="183" y="3" width="134" height="104" rx="2"/>
<rect class="room-living" x="3" y="173" width="554" height="154" rx="2"/>
<rect class="room-kitchen" x="443" y="3" width="114" height="104" rx="2"/>
<rect class="room-bath" x="183" y="113" width="54" height="54" rx="2"/>
<!-- Proposed new room (highlighted) -->
<rect class="room-new" x="3" y="223" width="120" height="104"/>
```
```css
.room-master { fill: rgba(206, 203, 246, 0.3); } /* purple tint */
.room-bed2 { fill: rgba(159, 225, 203, 0.3); } /* teal tint */
.room-bed3 { fill: rgba(250, 199, 117, 0.3); } /* amber tint */
.room-living { fill: rgba(245, 196, 179, 0.3); } /* coral tint */
.room-kitchen { fill: rgba(237, 147, 177, 0.3); } /* pink tint */
.room-bath { fill: rgba(133, 183, 235, 0.3); } /* blue tint */
.room-new { fill: rgba(163, 45, 45, 0.15); } /* red tint for proposed */
```
### Support Fixtures
```xml
<!-- Kitchen counter hint -->
<rect x="450" y="15" width="50" height="25" fill="none" stroke="var(--text-tertiary)" stroke-width="0.5" rx="2"/>
<text class="tx" x="475" y="30" text-anchor="middle">Counter</text>
<!-- Balcony (dashed outline) -->
<rect class="balcony-fill" x="3" y="333" width="200" height="50"/>
```
```css
.balcony { fill: none; stroke: var(--text-secondary); stroke-width: 2; stroke-dasharray: 6 3; }
.balcony-fill { fill: rgba(93, 202, 165, 0.1); }
```
### Room Labels
```xml
<!-- Room name and area -->
<text class="room-label" x="90" y="65" text-anchor="middle">MASTER</text>
<text class="room-label" x="90" y="78" text-anchor="middle">BEDROOM</text>
<text class="area-label" x="90" y="95" text-anchor="middle">195 sq ft</text>
<!-- Proposed room (in red) -->
<text class="room-label" x="63" y="268" text-anchor="middle" fill="#A32D2D">BEDROOM 4</text>
<text class="tx" x="63" y="282" text-anchor="middle" fill="#A32D2D">(NEW)</text>
```
```css
.room-label { font-family: system-ui; font-size: 11px; fill: var(--text-primary); font-weight: 500; }
.area-label { font-family: system-ui; font-size: 9px; fill: var(--text-tertiary); }
```
### Circulation Arrow
```xml
<defs>
<marker id="circ-arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto">
<path d="M0,0 L10,5 L0,10 Z" class="circulation-fill"/>
</marker>
</defs>
<path class="circulation" d="M300,250 L200,250 L145,250 L145,280" marker-end="url(#circ-arrow)"/>
<text class="tx" x="250" y="242" fill="#3B6D11" font-weight="500">New corridor access</text>
```
```css
.circulation { stroke: #3B6D11; stroke-width: 2; fill: none; }
.circulation-fill { fill: #3B6D11; }
```
### North Arrow and Scale Bar
```xml
<!-- North arrow -->
<g transform="translate(520, 260)">
<circle cx="0" cy="0" r="20" fill="none" stroke="var(--text-tertiary)" stroke-width="0.5"/>
<polygon points="0,-18 -5,5 0,0 5,5" fill="var(--text-primary)"/>
<text class="tx" x="0" y="-22" text-anchor="middle">N</text>
</g>
<!-- Scale bar -->
<g transform="translate(420, 300)">
<line x1="0" y1="0" x2="100" y2="0" stroke="var(--text-primary)" stroke-width="2"/>
<line x1="0" y1="-5" x2="0" y2="5" stroke="var(--text-primary)" stroke-width="1"/>
<line x1="50" y1="-3" x2="50" y2="3" stroke="var(--text-primary)" stroke-width="1"/>
<line x1="100" y1="-5" x2="100" y2="5" stroke="var(--text-primary)" stroke-width="1"/>
<text class="tx" x="0" y="15" text-anchor="middle">0</text>
<text class="tx" x="50" y="15" text-anchor="middle">5'</text>
<text class="tx" x="100" y="15" text-anchor="middle">10'</text>
</g>
```
## Area Comparison Table
### Table Structure
```xml
<!-- Header row -->
<rect class="table-header" x="0" y="0" width="180" height="28" rx="4 4 0 0"/>
<text class="ts" x="90" y="18" text-anchor="middle" font-weight="500">Room</text>
<!-- Normal row -->
<rect class="table-row" x="0" y="28" width="180" height="24"/>
<text class="tx" x="10" y="44">Master Bedroom</text>
<text class="tx" x="230" y="44" text-anchor="middle">195</text>
<!-- Alternating row -->
<rect class="table-row-alt" x="0" y="52" width="180" height="24"/>
<!-- Highlighted row (for changes) -->
<rect class="table-highlight" x="0" y="100" width="180" height="24"/>
<text class="tx" x="10" y="116" fill="#A32D2D" font-weight="500">Bedroom 4 (NEW)</text>
<text class="tx" x="430" y="116" text-anchor="middle" fill="#3B6D11">+100</text>
<!-- Total row -->
<rect x="0" y="268" width="180" height="28" fill="var(--bg-secondary)" stroke="var(--border)" stroke-width="1"/>
<text class="ts" x="10" y="286" font-weight="500">TOTAL CARPET AREA</text>
```
```css
.table-header { fill: var(--bg-secondary); }
.table-row { fill: var(--bg-primary); stroke: var(--border); stroke-width: 0.5; }
.table-row-alt { fill: var(--bg-tertiary); stroke: var(--border); stroke-width: 0.5; }
.table-highlight { fill: rgba(163, 45, 45, 0.1); stroke: #A32D2D; stroke-width: 0.5; }
```
## Layout Notes
- **ViewBox**: 800×780 (portrait for floor plan + table)
- **Scale**: 10px = 1 foot (apartment ~50ft × 33ft)
- **Floor plan origin**: Offset at (50, 60) for margins
- **Wall thickness**: 6px outer, 3px inner (represents ~6" walls)
- **Room labels**: Centered in each room with area below
- **Table placement**: Below floor plan with full width
## Color Coding
| Element | Color | Usage |
|---------|-------|-------|
| Proposed walls | Red (#A32D2D) dotted | New construction |
| New room fill | Red 15% opacity | Bedroom 4 area |
| Circulation | Green (#3B6D11) | New access path |
| Window glass | Blue (#378ADD) | Glass indication |
| Bedrooms | Purple/Teal/Amber tints | Room differentiation |
| Wet areas | Blue tint | Bathrooms |
| Living | Coral tint | Common areas |
## When to Use This Pattern
Use this diagram style for:
- Apartment/house floor plans
- Office layout planning
- Renovation proposals showing before/after
- Space planning with area calculations
- Real estate marketing materials
- Interior design presentations
- Building permit documentation

276
optional-skills/creative/concept-diagrams/examples/automated-password-reset-flow.md
View file

@ -1,276 +0,0 @@
# Automated Password Reset Flow
A two-section flowchart tracing the full user journey for a web application password reset: the initial request phase (forgot password → email check → token generation) and the reset-form phase (link click → new password entry → token/password validation). Demonstrates multi-exit decision diamonds, a three-column branching layout, a loop-back path, and a cross-section separator arrow.
## Key Patterns Used
- **Three-column layout**: Left column (error/terminal branches at cx=115), center column (main happy path at cx=340), right column (expired-token branch at cx=552) — allows side branches to live at the same y-level as center nodes without overlap
- **Decision diamonds with `<polygon>`**: Each decision uses a `<g class="decision">` wrapper containing a `<polygon>` and centered `<text>`; the diamond points are computed as `cx±hw, cy±hh` (hw=100, hh=28)
- **Pill-shaped terminals**: Start and end nodes use `rx=22` on their `<rect>` to signal entry/exit points; all mid-flow process nodes use `rx=8`
- **Three-branch decision paths**: Each diamond has a "Yes" branch (down, short `<line>`) and a "No" branch (`<path>` going horizontal then vertical to a side column)
- **Loop-back path**: Mismatch error node loops back to the password-entry node via a routing corridor at x=215 — a 5-px gap between the left column (right edge x=210) and center column (left edge x=220); the path exits the bottom of the error node, drops below it, travels right to x=215, then goes up to the target node's center y, then right 5 px into the node's left edge
- **Section separator**: A dashed horizontal `<line>` at y=452 splits the two phases; the connecting arrow crosses it with a faded label ("user receives email") to preserve flow continuity
- **Italic annotation**: The exact UX copy for the generic message ("If that email exists…") is shown as a faded italic `ts` text block below the left-branch terminal node
- **Legend row**: Five inline swatches (gray, purple, teal, red, amber diamond) at the bottom explain the color-to-role mapping
## Diagram
```xml
<svg width="100%" viewBox="0 0 680 960" xmlns="http://www.w3.org/2000/svg">
<defs>
<marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5"
markerWidth="6" markerHeight="6" orient="auto-start-reverse">
<path d="M2 1L8 5L2 9" fill="none" stroke="context-stroke"
stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
</marker>
</defs>
<!--
Column layout (680px viewBox, safe area x=40–640):
Left col : x=20, w=190, cx=115 (error / terminal branches)
Center col: x=220, w=240, cx=340 (main happy path)
Right col: x=465, w=175, cx=552 (expired-token branch)
Loop corridor at x=215 (5-px gap between left and center cols)
-->
<!-- ═══ SECTION 1 — Forgot password request ═══ -->
<text class="ts" x="40" y="38" opacity=".45">Section 1 — Forgot password request</text>
<!-- START terminal (pill rx=22 signals start/end) -->
<g class="c-gray">
<rect x="220" y="46" width="240" height="44" rx="22"/>
<text class="th" x="340" y="68" text-anchor="middle" dominant-baseline="central">User: &quot;Forgot password&quot;</text>
</g>
<line x1="340" y1="90" x2="340" y2="108" class="arr" marker-end="url(#arrow)"/>
<!-- N2 · Enter email -->
<g class="c-gray">
<rect x="220" y="108" width="240" height="44" rx="8"/>
<text class="th" x="340" y="130" text-anchor="middle" dominant-baseline="central">Enter email address</text>
</g>
<line x1="340" y1="152" x2="340" y2="172" class="arr" marker-end="url(#arrow)"/>
<!-- D1 · Email in system? diamond: center=(340,200) hw=100 hh=28 -->
<g class="decision">
<polygon points="340,172 440,200 340,228 240,200"/>
<text class="th" x="340" y="200" text-anchor="middle" dominant-baseline="central">Email in system?</text>
</g>
<!-- D1 "No" → left column -->
<path d="M 240,200 L 115,200 L 115,248" class="arr" marker-end="url(#arrow)"/>
<text class="ts" x="178" y="193" text-anchor="middle" opacity=".75">No</text>
<!-- D1 "Yes" → continue down -->
<line x1="340" y1="228" x2="340" y2="248" class="arr" marker-end="url(#arrow)"/>
<text class="ts" x="348" y="242" text-anchor="start" opacity=".75">Yes</text>
<!-- ── Left branch (D1 = No): generic security message → end ── -->
<!-- L1 · Generic message (security: never confirm email existence) -->
<g class="c-gray">
<rect x="20" y="248" width="190" height="56" rx="8"/>
<text class="th" x="115" y="269" text-anchor="middle" dominant-baseline="central">Generic message shown</text>
<text class="ts" x="115" y="287" text-anchor="middle" dominant-baseline="central">Email sent if found</text>
</g>
<line x1="115" y1="304" x2="115" y2="324" class="arr" marker-end="url(#arrow)"/>
<!-- L2 · End terminal (left) -->
<g class="c-gray">
<rect x="20" y="324" width="190" height="44" rx="22"/>
<text class="th" x="115" y="346" text-anchor="middle" dominant-baseline="central">Request handled</text>
</g>
<!-- Italic annotation: actual UX copy shown below the end node -->
<text class="ts" x="20" y="384" opacity=".45" font-style="italic">&quot;If that email exists, a reset</text>
<text class="ts" x="20" y="398" opacity=".45" font-style="italic">link has been sent.&quot;</text>
<!-- ── Center Yes branch: system generates & sends token ── -->
<!-- N3 · Generate unique token -->
<g class="c-purple">
<rect x="220" y="248" width="240" height="56" rx="8"/>
<text class="th" x="340" y="269" text-anchor="middle" dominant-baseline="central">Generate unique token</text>
<text class="ts" x="340" y="287" text-anchor="middle" dominant-baseline="central">Time-limited, cryptographic</text>
</g>
<line x1="340" y1="304" x2="340" y2="324" class="arr" marker-end="url(#arrow)"/>
<!-- N4 · Store token + user ID -->
<g class="c-purple">
<rect x="220" y="324" width="240" height="44" rx="8"/>
<text class="th" x="340" y="346" text-anchor="middle" dominant-baseline="central">Store token + user ID</text>
</g>
<line x1="340" y1="368" x2="340" y2="388" class="arr" marker-end="url(#arrow)"/>
<!-- N5 · Send reset email -->
<g class="c-teal">
<rect x="220" y="388" width="240" height="44" rx="8"/>
<text class="th" x="340" y="410" text-anchor="middle" dominant-baseline="central">Send reset link via email</text>
</g>
<!-- ═══ Section separator ═══ -->
<line x1="40" y1="452" x2="640" y2="452"
stroke="var(--border)" stroke-width="1" stroke-dasharray="8 5"/>
<!-- Arrow crossing separator (with inline label) -->
<line x1="340" y1="432" x2="340" y2="472" class="arr" marker-end="url(#arrow)"/>
<text class="ts" x="348" y="448" text-anchor="start" opacity=".55">user receives email</text>
<text class="ts" x="40" y="464" opacity=".45">Section 2 — Password reset form</text>
<!-- ═══ SECTION 2 — Password reset form ═══ -->
<!-- N6 · User clicks reset link -->
<g class="c-gray">
<rect x="220" y="480" width="240" height="44" rx="8"/>
<text class="th" x="340" y="502" text-anchor="middle" dominant-baseline="central">User clicks reset link</text>
</g>
<line x1="340" y1="524" x2="340" y2="544" class="arr" marker-end="url(#arrow)"/>
<!-- N7 · Enter new password ×2 -->
<g class="c-gray">
<rect x="220" y="544" width="240" height="56" rx="8"/>
<text class="th" x="340" y="565" text-anchor="middle" dominant-baseline="central">Enter new password ×2</text>
<text class="ts" x="340" y="583" text-anchor="middle" dominant-baseline="central">Confirm both passwords match</text>
</g>
<line x1="340" y1="600" x2="340" y2="620" class="arr" marker-end="url(#arrow)"/>
<!-- D2 · Token expired? diamond: center=(340,648) hw=100 hh=28 -->
<g class="decision">
<polygon points="340,620 440,648 340,676 240,648"/>
<text class="th" x="340" y="648" text-anchor="middle" dominant-baseline="central">Token expired?</text>
</g>
<!-- D2 "Yes" → right column (expired-token branch) -->
<path d="M 440,648 L 552,648 L 552,692" class="arr" marker-end="url(#arrow)"/>
<text class="ts" x="496" y="641" text-anchor="middle" opacity=".75">Yes</text>
<!-- D2 "No" → down to password-match check -->
<line x1="340" y1="676" x2="340" y2="714" class="arr" marker-end="url(#arrow)"/>
<text class="ts" x="348" y="698" text-anchor="start" opacity=".75">No</text>
<!-- ── Right branch (D2 = Yes): token expired → dead end ── -->
<!-- R1 · Token expired error -->
<g class="c-red">
<rect x="465" y="692" width="175" height="56" rx="8"/>
<text class="th" x="552" y="713" text-anchor="middle" dominant-baseline="central">Token expired</text>
<text class="ts" x="552" y="731" text-anchor="middle" dominant-baseline="central">Show expiry error</text>
</g>
<line x1="552" y1="748" x2="552" y2="768" class="arr" marker-end="url(#arrow)"/>
<!-- R2 · End terminal (right) -->
<g class="c-gray">
<rect x="465" y="768" width="175" height="44" rx="22"/>
<text class="th" x="552" y="790" text-anchor="middle" dominant-baseline="central">End — request again</text>
</g>
<!-- D3 · Passwords match? diamond: center=(340,742) hw=100 hh=28 -->
<g class="decision">
<polygon points="340,714 440,742 340,770 240,742"/>
<text class="th" x="340" y="742" text-anchor="middle" dominant-baseline="central">Passwords match?</text>
</g>
<!-- D3 "No" → left column (mismatch branch) -->
<path d="M 240,742 L 115,742 L 115,786" class="arr" marker-end="url(#arrow)"/>
<text class="ts" x="178" y="735" text-anchor="middle" opacity=".75">No</text>
<!-- D3 "Yes" → down to reset -->
<line x1="340" y1="770" x2="340" y2="790" class="arr" marker-end="url(#arrow)"/>
<text class="ts" x="348" y="783" text-anchor="start" opacity=".75">Yes</text>
<!-- ── Left branch (D3 = No): passwords don't match → loop back ── -->
<!-- L3 · Password mismatch error -->
<g class="c-red">
<rect x="20" y="786" width="190" height="56" rx="8"/>
<text class="th" x="115" y="807" text-anchor="middle" dominant-baseline="central">Password mismatch</text>
<text class="ts" x="115" y="825" text-anchor="middle" dominant-baseline="central">Passwords do not match</text>
</g>
<!-- Loop-back arrow: exits L3 bottom → drops to y=862 →
travels right to corridor x=215 → climbs to N7 center y=572 →
enters N7 left edge at (220, 572) pointing right -->
<path d="M 115,842 L 115,862 L 215,862 L 215,572 L 220,572"
class="arr" marker-end="url(#arrow)"/>
<text class="ts" x="224" y="538" text-anchor="start" opacity=".6">retry</text>
<!-- ── Center Yes branch (D3 = Yes): reset password & invalidate token ── -->
<!-- N8 · Reset password -->
<g class="c-teal">
<rect x="220" y="790" width="240" height="56" rx="8"/>
<text class="th" x="340" y="811" text-anchor="middle" dominant-baseline="central">Reset password</text>
<text class="ts" x="340" y="829" text-anchor="middle" dominant-baseline="central">Invalidate used token</text>
</g>
<line x1="340" y1="846" x2="340" y2="866" class="arr" marker-end="url(#arrow)"/>
<!-- N9 · Success terminal -->
<g class="c-green">
<rect x="220" y="866" width="240" height="44" rx="22"/>
<text class="th" x="340" y="888" text-anchor="middle" dominant-baseline="central">Password reset complete</text>
</g>
<!-- ═══ Legend ═══ -->
<text class="ts" x="40" y="930" opacity=".4">Legend —</text>
<rect x="108" y="920" width="13" height="13" rx="2" fill="#F1EFE8" stroke="#5F5E5A" stroke-width="0.5"/>
<text class="ts" x="126" y="930" opacity=".7">User action</text>
<rect x="210" y="920" width="13" height="13" rx="2" fill="#EEEDFE" stroke="#534AB7" stroke-width="0.5"/>
<text class="ts" x="228" y="930" opacity=".7">System process</text>
<rect x="334" y="920" width="13" height="13" rx="2" fill="#E1F5EE" stroke="#0F6E56" stroke-width="0.5"/>
<text class="ts" x="352" y="930" opacity=".7">Email / success</text>
<rect x="455" y="920" width="13" height="13" rx="2" fill="#FCEBEB" stroke="#A32D2D" stroke-width="0.5"/>
<text class="ts" x="473" y="930" opacity=".7">Error state</text>
<polygon points="556,926 566,932 556,938 546,932" fill="#FAEEDA" stroke="#854F0B" stroke-width="0.5"/>
<text class="ts" x="572" y="932" opacity=".7">Decision</text>
</svg>
```
## Custom CSS
Add these classes to the hosting page `<style>` block (in addition to the standard skill CSS):
```css
/* Decision diamond — amber fill, same palette as c-amber */
.decision > polygon { fill: #FAEEDA; stroke: #854F0B; stroke-width: 0.5; }
.decision > .th { fill: #633806; }
@media (prefers-color-scheme: dark) {
.decision > polygon { fill: #633806; stroke: #EF9F27; }
.decision > .th { fill: #FAC775; }
}
```
## Color Assignments
| Element | Color | Reason |
|---------|-------|--------|
| Start / end terminals | `c-gray` | Neutral entry and exit points |
| User actions (enter email, click link, enter password) | `c-gray` | User-facing steps with no system processing |
| Generic message + request-handled terminal | `c-gray` | Intentionally neutral — the security message must not reveal data |
| Generate & store token | `c-purple` | Backend system operations |
| Send reset email | `c-teal` | Positive external action (outbound communication) |
| Token expired error | `c-red` | Failure / blocking error state |
| Password mismatch error | `c-red` | Validation failure |
| Reset password + success | `c-teal` / `c-green` | Positive outcome: teal for the action, green pill for the terminal |
| Decision diamonds | `c-amber` (custom `.decision`) | Warning / branch point — matches amber semantic meaning |
## Layout Notes
- **ViewBox**: 680×960 — tall flowchart with two phases
- **Three-column structure**: Left (cx=115), center (cx=340), right (cx=552) — each branch stays within its column; only `<path>` arrows cross column boundaries
- **Diamond formula**: `<polygon points="cx,cy-hh cx+hw,cy cx,cy+hh cx-hw,cy"/>` with hw=100, hh=28 gives a 200×56px diamond that sits flush with the center column (x=220–460)
- **Branch routing pattern**: "No" paths use `<path d="M left_point,cy L side_cx,cy L side_cx,node_top">` — one horizontal segment + one vertical segment, no curves needed
- **Loop corridor**: The 5-px gap at x=210–220 between left and center columns provides a clean vertical channel for the loop-back path without any node overlap; the path exits node bottom, drops 20px, goes right to x=215, climbs to target y, enters from left
- **Section separator**: A dashed `<line>` at y=452 with `stroke-dasharray="8 5"` provides a visual phase break; the single connecting arrow crosses it at center, with a faded label on the arrow
- **Pill terminals**: `rx=22` (half the 44px node height) produces a perfect capsule/pill shape — use this consistently for all start/end terminals
- **Error annotation**: The exact UX copy is rendered as faded (`opacity=".45"`) italic `ts` text below the relevant node, keeping it informative without cluttering the flow

240
optional-skills/creative/concept-diagrams/examples/autonomous-llm-research-agent-flow.md
View file

@ -1,240 +0,0 @@
# Autonomous LLM Research Agent Flow
A multi-section flowchart showing Karpathy's autoresearch framework: human-agent handoff, the autonomous experiment loop with keep/discard decision branching, and the modifiable training pipeline. Demonstrates loop-back arrows, convergent decision paths, and semantic color coding for outcomes.
## Key Patterns Used
- **Three-section layout**: Setup row, main loop container, and detail container — each visually distinct
- **Neutral dashed containers**: Loop and training pipeline use `var(--bg-secondary)` fill with dashed borders to recede behind colored content nodes
- **Decision branching with convergence**: "val_bpb improved?" splits into Keep (green) and Discard (red), then both converge back to "Log to results.tsv"
- **Loop-back arrow**: Dashed path with rounded corners on the right side of the container showing infinite repetition
- **Semantic color for outcomes**: Green = improvement (keep), Red = no improvement (discard) — not arbitrary decoration
- **Highlighted key step**: "Run training" uses `c-coral` to visually distinguish the most important step from other `c-teal` actions
- **Horizontal pipeline flow**: Training details section uses left-to-right arrow-connected nodes (GPT → MuonAdamW → Evaluation)
- **Footer metadata**: Fixed constraints shown as subtle centered text below the pipeline nodes
- **Legend row**: Color key at the bottom explaining what each color means
## Diagram
```xml
<svg width="100%" viewBox="0 0 680 920" xmlns="http://www.w3.org/2000/svg">
<defs>
<marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5"
markerWidth="6" markerHeight="6" orient="auto-start-reverse">
<path d="M2 1L8 5L2 9" fill="none" stroke="context-stroke"
stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
</marker>
</defs>
<!-- ========================================== -->
<!-- SECTION 1: SETUP (Human → program.md → AI) -->
<!-- ========================================== -->
<text class="ts" x="40" y="30" text-anchor="start" opacity=".5">One-time setup</text>
<!-- Human -->
<g class="node c-gray">
<rect x="60" y="42" width="140" height="56" rx="8" stroke-width="0.5"/>
<text class="th" x="130" y="62" text-anchor="middle" dominant-baseline="central">Human</text>
<text class="ts" x="130" y="82" text-anchor="middle" dominant-baseline="central">Researcher</text>
</g>
<!-- Arrow: Human → program.md -->
<line x1="200" y1="70" x2="250" y2="70" class="arr" marker-end="url(#arrow)"/>
<!-- program.md -->
<g class="node c-gray">
<rect x="250" y="42" width="180" height="56" rx="8" stroke-width="0.5"/>
<text class="th" x="340" y="62" text-anchor="middle" dominant-baseline="central">program.md</text>
<text class="ts" x="340" y="82" text-anchor="middle" dominant-baseline="central">Agent instructions</text>
</g>
<!-- Arrow: program.md → AI Agent -->
<line x1="430" y1="70" x2="470" y2="70" class="arr" marker-end="url(#arrow)"/>
<!-- AI Agent -->
<g class="node c-purple">
<rect x="470" y="42" width="160" height="56" rx="8" stroke-width="0.5"/>
<text class="th" x="550" y="62" text-anchor="middle" dominant-baseline="central">AI agent</text>
<text class="ts" x="550" y="82" text-anchor="middle" dominant-baseline="central">Claude / Codex</text>
</g>
<!-- Arrow: Setup row → Loop (from program.md center down) -->
<line x1="340" y1="98" x2="340" y2="142" class="arr" marker-end="url(#arrow)"/>
<!-- ========================================== -->
<!-- SECTION 2: AUTONOMOUS EXPERIMENT LOOP -->
<!-- ========================================== -->
<!-- Loop container (neutral dashed) -->
<g>
<rect x="40" y="142" width="600" height="528" rx="16"
stroke-width="1" stroke-dasharray="6 4"
fill="var(--bg-secondary)" stroke="var(--border)"/>
<text class="th" x="66" y="170">Autonomous experiment loop</text>
<text class="ts" x="66" y="188">~12 experiments/hour — runs until manually stopped</text>
</g>
<!-- Step 1: Read code + past results -->
<g class="node c-teal">
<rect x="170" y="208" width="280" height="44" rx="8" stroke-width="0.5"/>
<text class="th" x="310" y="230" text-anchor="middle" dominant-baseline="central">Read code + past results</text>
</g>
<!-- Arrow: S1 → S2 -->
<line x1="310" y1="252" x2="310" y2="274" class="arr" marker-end="url(#arrow)"/>
<!-- Step 2: Propose + edit train.py -->
<g class="node c-teal">
<rect x="170" y="274" width="280" height="56" rx="8" stroke-width="0.5"/>
<text class="th" x="310" y="294" text-anchor="middle" dominant-baseline="central">Propose + edit train.py</text>
<text class="ts" x="310" y="314" text-anchor="middle" dominant-baseline="central">Arch, optimizer, hyperparameters</text>
</g>
<!-- Arrow: S2 → S3 -->
<line x1="310" y1="330" x2="310" y2="352" class="arr" marker-end="url(#arrow)"/>
<!-- Step 3: Run training (highlighted — key step) -->
<g class="node c-coral">
<rect x="170" y="352" width="280" height="56" rx="8" stroke-width="0.5"/>
<text class="th" x="310" y="372" text-anchor="middle" dominant-baseline="central">Run training</text>
<text class="ts" x="310" y="392" text-anchor="middle" dominant-baseline="central">uv run train.py (5 min budget)</text>
</g>
<!-- Arrow: S3 → S4 -->
<line x1="310" y1="408" x2="310" y2="430" class="arr" marker-end="url(#arrow)"/>
<!-- Step 4: Decision — val_bpb improved? -->
<g class="node c-gray">
<rect x="170" y="430" width="280" height="44" rx="8" stroke-width="0.5"/>
<text class="th" x="310" y="452" text-anchor="middle" dominant-baseline="central">val_bpb improved?</text>
</g>
<!-- Decision arrows to Keep / Discard -->
<line x1="240" y1="474" x2="175" y2="508" class="arr" marker-end="url(#arrow)"/>
<line x1="380" y1="474" x2="445" y2="508" class="arr" marker-end="url(#arrow)"/>
<!-- Decision labels -->
<text class="ts" x="195" y="496" opacity=".6">yes</text>
<text class="ts" x="416" y="496" opacity=".6">no</text>
<!-- Keep — advance branch -->
<g class="node c-green">
<rect x="70" y="508" width="210" height="56" rx="8" stroke-width="0.5"/>
<text class="th" x="175" y="528" text-anchor="middle" dominant-baseline="central">Keep</text>
<text class="ts" x="175" y="548" text-anchor="middle" dominant-baseline="central">Advance git branch</text>
</g>
<!-- Discard — git reset -->
<g class="node c-red">
<rect x="340" y="508" width="210" height="56" rx="8" stroke-width="0.5"/>
<text class="th" x="445" y="528" text-anchor="middle" dominant-baseline="central">Discard</text>
<text class="ts" x="445" y="548" text-anchor="middle" dominant-baseline="central">Git reset to previous</text>
</g>
<!-- Converge arrows: Keep → Log, Discard → Log -->
<line x1="175" y1="564" x2="250" y2="590" class="arr" marker-end="url(#arrow)"/>
<line x1="445" y1="564" x2="370" y2="590" class="arr" marker-end="url(#arrow)"/>
<!-- Step 6: Log to results.tsv -->
<g class="node c-teal">
<rect x="170" y="590" width="280" height="44" rx="8" stroke-width="0.5"/>
<text class="th" x="310" y="612" text-anchor="middle" dominant-baseline="central">Log to results.tsv</text>
</g>
<!-- Loop-back arrow (dashed, right side) -->
<path d="M 450 612 L 564 612 Q 576 612 576 600 L 576 242 Q 576 230 564 230 L 450 230"
fill="none" class="arr" stroke-dasharray="4 3" marker-end="url(#arrow)"/>
<!-- ========================================== -->
<!-- SECTION 3: TRAINING PIPELINE DETAILS -->
<!-- ========================================== -->
<!-- Connection arrow: Loop → Training details -->
<line x1="310" y1="670" x2="310" y2="710" class="arr" marker-end="url(#arrow)"/>
<!-- Training container (neutral dashed) -->
<g>
<rect x="40" y="710" width="600" height="170" rx="16"
stroke-width="1" stroke-dasharray="6 4"
fill="var(--bg-secondary)" stroke="var(--border)"/>
<text class="th" x="66" y="738">train.py — modifiable training pipeline</text>
<text class="ts" x="66" y="756">Runs during each training step — single GPU, single file</text>
</g>
<!-- GPT model -->
<g class="node c-coral">
<rect x="70" y="774" width="155" height="56" rx="8" stroke-width="0.5"/>
<text class="th" x="147" y="794" text-anchor="middle" dominant-baseline="central">GPT model</text>
<text class="ts" x="147" y="814" text-anchor="middle" dominant-baseline="central">RoPE, FlashAttn3</text>
</g>
<!-- Arrow: GPT → MuonAdamW -->
<line x1="225" y1="802" x2="260" y2="802" class="arr" marker-end="url(#arrow)"/>
<!-- MuonAdamW optimizer -->
<g class="node c-coral">
<rect x="260" y="774" width="155" height="56" rx="8" stroke-width="0.5"/>
<text class="th" x="337" y="794" text-anchor="middle" dominant-baseline="central">MuonAdamW</text>
<text class="ts" x="337" y="814" text-anchor="middle" dominant-baseline="central">Hybrid optimizer</text>
</g>
<!-- Arrow: MuonAdamW → Evaluation -->
<line x1="415" y1="802" x2="450" y2="802" class="arr" marker-end="url(#arrow)"/>
<!-- Evaluation -->
<g class="node c-amber">
<rect x="450" y="774" width="155" height="56" rx="8" stroke-width="0.5"/>
<text class="th" x="527" y="794" text-anchor="middle" dominant-baseline="central">Evaluation</text>
<text class="ts" x="527" y="814" text-anchor="middle" dominant-baseline="central">val_bpb metric</text>
</g>
<!-- Footer: fixed constraints -->
<text class="ts" x="340" y="856" text-anchor="middle" opacity=".5">climbmix-400b data · 8K BPE vocab · 300s budget · 2048 context</text>
<!-- ========================================== -->
<!-- LEGEND -->
<!-- ========================================== -->
<g class="c-teal"><rect x="40" y="890" width="14" height="14" rx="3" stroke-width="0.5"/></g>
<text class="ts" x="62" y="902">Agent actions</text>
<g class="c-coral"><rect x="170" y="890" width="14" height="14" rx="3" stroke-width="0.5"/></g>
<text class="ts" x="192" y="902">Training run</text>
<g class="c-green"><rect x="300" y="890" width="14" height="14" rx="3" stroke-width="0.5"/></g>
<text class="ts" x="322" y="902">Improvement</text>
<g class="c-red"><rect x="430" y="890" width="14" height="14" rx="3" stroke-width="0.5"/></g>
<text class="ts" x="452" y="902">No improvement</text>
</svg>
```
## Color Assignments
| Element | Color | Reason |
|---------|-------|--------|
| Human, program.md | `c-gray` | Neutral setup / input nodes |
| AI agent | `c-purple` | The active intelligent actor |
| Loop action steps | `c-teal` | Agent's analytical/editing actions |
| Run training | `c-coral` | Highlighted key step — the 5-min training run |
| Decision check | `c-gray` | Neutral evaluation checkpoint |
| Keep (improved) | `c-green` | Semantic success — val_bpb decreased |
| Discard (not improved) | `c-red` | Semantic failure — no improvement |
| Training pipeline nodes | `c-coral` | Training infrastructure components |
| Evaluation node | `c-amber` | Distinct from training — measurement/metric role |
| Containers | Neutral (dashed) | Subtle grouping that recedes behind content |
## Layout Notes
- **ViewBox**: 680×920 (standard width, tall for 3 sections)
- **Three sections**: Setup row (y=30–98), loop container (y=142–670), training details (y=710–880)
- **Container style**: Dashed border (`stroke-dasharray="6 4"`), neutral fill (`var(--bg-secondary)`), `stroke-width="1"` — not colored, so inner nodes pop
- **Loop-back arrow**: Dashed `<path>` with quadratic curves (`Q`) at corners for smooth rounded turns, running up the right side of the loop container from "Log" back to "Read code"
- **Decision pattern**: Single question node ("val_bpb improved?") with diagonal arrows to Keep/Discard, then convergent diagonal arrows back to "Log to results.tsv"
- **Decision labels**: "yes"/"no" labels placed along the diagonal arrows with `opacity=".6"` to stay subtle
- **Key step highlight**: "Run training" uses `c-coral` while surrounding steps use `c-teal`, drawing the eye to the most important step
- **Horizontal sub-flow**: Training pipeline uses left-to-right arrow-connected nodes (GPT model → MuonAdamW → Evaluation)
- **Footer metadata**: Fixed constraints (data, vocab, budget, context) shown as a single centered `ts` text line with `opacity=".5"`
- **Legend**: Four color swatches at the bottom explaining the semantic meaning of each color used

161
optional-skills/creative/concept-diagrams/examples/banana-journey-tree-to-smoothie.md
View file

@ -1,161 +0,0 @@
# Journey of a Banana: From Tree to Smoothie
A narrative journey diagram following a single banana across 3,000 miles and 3 weeks, from harvest in Costa Rica to a smoothie in the consumer's kitchen. Demonstrates storytelling through visualization, winding path layout, and progressive state changes.
## Key Patterns Used
- **Winding journey path**: S-curve connecting all stages visually
- **Location markers**: Country flags and place names for geographic context
- **Progressive state changes**: Banana color changes (green → yellow → brown → frozen → smoothie)
- **Narrative details**: Fun elements like spider check, stickers, price tags
- **Timeline**: Bottom timeline showing duration of journey
- **Environmental context**: Ocean waves, gas clouds, store awning
## New Shape Techniques
### Banana (curved fruit shape)
```xml
<!-- Green banana -->
<path class="banana-green" d="M 5 0 Q 0 10 3 20 Q 6 25 10 20 Q 13 10 8 0 Z"/>
<!-- Yellow banana -->
<path class="banana-yellow" d="M 0 5 Q -6 18 0 32 Q 7 40 15 30 Q 20 15 12 5 Z"/>
<!-- Brown overripe banana with spots -->
<path class="banana-brown" d="M 0 5 Q -5 15 0 28 Q 6 35 14 26 Q 18 14 12 5 Z"/>
<circle class="banana-spots" cx="5" cy="15" r="1.5"/>
<circle class="banana-spots" cx="9" cy="20" r="1"/>
```
### Banana Tree
```xml
<!-- Trunk -->
<rect class="tree-trunk" x="55" y="50" width="15" height="60" rx="3"/>
<!-- Leaves (rotated ellipses) -->
<ellipse class="tree-leaf" cx="62" cy="45" rx="40" ry="15" transform="rotate(-20, 62, 45)"/>
<ellipse class="tree-leaf" cx="62" cy="50" rx="35" ry="12" transform="rotate(25, 62, 50)"/>
<!-- Banana bunch hanging -->
<g transform="translate(40, 55)">
<path class="banana-green" d="M 5 0 Q 0 10 3 20 Q 6 25 10 20 Q 13 10 8 0 Z"/>
<path class="banana-green" d="M 12 2 Q 8 12 11 22 Q 14 27 18 22 Q 21 12 16 2 Z"/>
<rect class="stem" x="8" y="-5" width="12" height="8" rx="2"/>
</g>
```
### Cargo Ship
```xml
<!-- Ocean waves -->
<path class="ocean" d="M 0 90 Q 30 85 60 90 Q 90 95 120 90 Q 150 85 180 90 L 180 110 L 0 110 Z" opacity="0.5"/>
<!-- Hull -->
<path class="ship-hull" d="M 20 90 L 30 60 L 160 60 L 170 90 Q 150 95 95 95 Q 40 95 20 90 Z"/>
<!-- Deck -->
<rect class="ship-deck" x="40" y="45" width="110" height="18" rx="2"/>
<!-- Reefer containers -->
<rect class="container" x="45" y="25" width="30" height="22" rx="2"/>
<!-- Refrigeration symbol -->
<text x="60" y="40" text-anchor="middle" fill="#185FA5" style="font-size:10px">❄</text>
<!-- Smoke stack -->
<rect x="145" y="35" width="8" height="15" fill="#444441"/>
```
### Inspector Figure
```xml
<!-- Body -->
<rect class="inspector" x="10" y="20" width="25" height="35" rx="3"/>
<!-- Head -->
<circle class="inspector" cx="22" cy="12" r="10"/>
<!-- Hat -->
<rect x="12" y="2" width="20" height="6" rx="2" fill="#534AB7"/>
<!-- Clipboard -->
<rect class="clipboard" x="38" y="28" width="15" height="20" rx="2"/>
<line x1="42" y1="34" x2="50" y2="34" stroke="#888780" stroke-width="1"/>
```
### Spider with "No" Symbol
```xml
<circle cx="15" cy="15" r="18" fill="none" stroke="#A32D2D" stroke-width="2"/>
<line x1="3" y1="3" x2="27" y2="27" stroke="#A32D2D" stroke-width="2"/>
<!-- Spider body -->
<ellipse class="spider" cx="15" cy="15" rx="4" ry="5"/>
<ellipse class="spider" cx="15" cy="10" rx="3" ry="3"/>
<!-- Legs -->
<line x1="12" y1="14" x2="5" y2="10" stroke="#2C2C2A" stroke-width="1"/>
<line x1="18" y1="14" x2="25" y2="10" stroke="#2C2C2A" stroke-width="1"/>
```
### Blender with Smoothie
```xml
<!-- Blender jar -->
<path class="blender" d="M 5 5 L 0 45 L 35 45 L 30 5 Z"/>
<!-- Smoothie inside (wavy top) -->
<path class="smoothie" d="M 3 20 L 0 45 L 35 45 L 32 20 Q 25 18 17 22 Q 10 18 3 20 Z"/>
<!-- Blender base -->
<rect class="blender" x="-2" y="45" width="40" height="12" rx="3"/>
<!-- Lid -->
<rect x="8" y="0" width="20" height="8" rx="2" fill="#AFA9EC" stroke="#534AB7"/>
<!-- Banana chunks floating -->
<ellipse cx="12" cy="32" rx="4" ry="2" fill="#FAC775"/>
```
### Winding Journey Path
```xml
<path class="journey-path" d="
M 80 100
L 200 100
Q 280 100 280 150
L 280 180
Q 280 220 320 220
L 520 220
Q 560 220 560 260
L 560 320
Q 560 360 520 360
L 280 360
...
"/>
```
## CSS Classes
```css
/* Journey */
.journey-path { stroke: #D3D1C7; stroke-width: 3; fill: none; stroke-linecap: round; }
/* Banana ripeness stages */
.banana-green { fill: #97C459; stroke: #3B6D11; stroke-width: 0.5; }
.banana-yellow { fill: #FAC775; stroke: #BA7517; stroke-width: 0.5; }
.banana-brown { fill: #854F0B; stroke: #633806; stroke-width: 0.5; }
.banana-spots { fill: #633806; }
/* Environment elements */
.tree-trunk { fill: #854F0B; stroke: #633806; stroke-width: 1; }
.tree-leaf { fill: #97C459; stroke: #3B6D11; stroke-width: 0.5; }
.ocean { fill: #85B7EB; }
.ship-hull { fill: #5F5E5A; stroke: #444441; stroke-width: 1; }
.container { fill: #E6F1FB; stroke: #185FA5; stroke-width: 1; }
.gas-cloud { fill: #C0DD97; stroke: #97C459; stroke-width: 0.5; opacity: 0.6; }
/* Buildings */
.packhouse { fill: #F1EFE8; stroke: #5F5E5A; stroke-width: 1; }
.warehouse { fill: #FAEEDA; stroke: #854F0B; stroke-width: 1; }
.store { fill: #E1F5EE; stroke: #0F6E56; stroke-width: 1; }
/* Kitchen */
.counter { fill: #FAECE7; stroke: #993C1D; stroke-width: 1; }
.blender { fill: #EEEDFE; stroke: #534AB7; stroke-width: 1; }
.smoothie { fill: #FAC775; }
.freezer { fill: #E6F1FB; stroke: #185FA5; stroke-width: 1; }
/* Details */
.sticker { fill: #378ADD; stroke: #185FA5; stroke-width: 0.3; }
.spider { fill: #2C2C2A; stroke: #1a1a18; stroke-width: 0.3; }
```
## Layout Notes
- **ViewBox**: 850×680 (tall for winding path)
- **Path style**: S-curve winding path connects all 7 stages
- **Location labels**: Country flags + place names anchor geographic context
- **State progression**: Same object (banana) shown in different states throughout
- **Timeline**: Horizontal timeline at bottom shows journey duration
- **Narrative elements**: Fun details (spider, stickers, price tags) add storytelling value
- **Environmental context**: Ocean waves, gas clouds, awnings create sense of place

209
optional-skills/creative/concept-diagrams/examples/commercial-aircraft-structure.md
View file

@ -1,209 +0,0 @@
# Commercial Aircraft Structure
A physical/structural diagram showing an aircraft side profile using appropriate SVG shapes beyond rectangles - paths, polygons, ellipses for realistic representation.
## Key Patterns Used
- **Path elements**: Curved fuselage body with nose cone using quadratic bezier curves
- **Polygon elements**: Tapered wing shape, triangular stabilizers, control surfaces
- **Ellipse elements**: Engines (cylinders), wheels (circles)
- **Line elements**: Landing gear struts, leader lines for labels
- **Dashed strokes**: Interior sections (fuel tank), movable control surfaces (rudder, elevator)
- **Layered composition**: Cabin sections drawn inside the fuselage shape
- **Leader lines with labels**: Connect labels to components they describe
## Diagram
```xml
<svg width="100%" viewBox="0 0 680 400" xmlns="http://www.w3.org/2000/svg">
<!-- FUSELAGE - main body cylinder with nose cone -->
<path class="fuselage" d="
M 80 180
Q 40 180 40 200
Q 40 220 80 220
L 560 220
Q 580 220 580 200
Q 580 180 560 180
Z
"/>
<!-- Nose cone -->
<path class="fuselage" d="
M 80 180
Q 50 180 35 200
Q 50 220 80 220
" fill="none" stroke-width="1"/>
<!-- COCKPIT windows -->
<path class="cockpit" d="
M 45 190
L 75 185
L 75 200
L 50 200
Z
"/>
<line x1="55" y1="188" x2="55" y2="200" stroke="#534AB7" stroke-width="0.5"/>
<line x1="65" y1="186" x2="65" y2="200" stroke="#534AB7" stroke-width="0.5"/>
<!-- CABIN SECTIONS (inside fuselage) -->
<!-- First class -->
<rect class="first-class" x="85" y="183" width="50" height="34" rx="2"/>
<text class="tl" x="110" y="203" text-anchor="middle">First</text>
<!-- Business class -->
<rect class="business-class" x="140" y="183" width="80" height="34" rx="2"/>
<text class="tl" x="180" y="203" text-anchor="middle">Business</text>
<!-- Economy class -->
<rect class="economy-class" x="225" y="183" width="200" height="34" rx="2"/>
<text class="tl" x="325" y="203" text-anchor="middle">Economy</text>
<!-- CARGO HOLD (lower section indication) -->
<line x1="85" y1="217" x2="520" y2="217" class="leader"/>
<text class="tl" x="300" y="228" text-anchor="middle" opacity=".6">Cargo hold below deck</text>
<!-- WING - main wing shape -->
<polygon class="wing" points="
200,220
120,300
130,305
160,305
340,235
340,220
"/>
<!-- Wing fuel tank (dashed interior) -->
<polygon class="fuel-tank" points="
210,225
150,280
160,283
180,283
310,232
310,225
"/>
<text class="tl" x="220" y="260" opacity=".7">Fuel</text>
<!-- Flaps (trailing edge) -->
<polygon class="flap" points="
130,300
120,305
160,310
165,305
"/>
<text class="tl" x="143" y="320">Flaps</text>
<!-- ENGINE under wing -->
<ellipse class="engine" cx="175" cy="285" rx="25" ry="12"/>
<ellipse cx="155" cy="285" rx="8" ry="10" fill="none" stroke="#993C1D" stroke-width="0.5"/>
<!-- Engine pylon -->
<line x1="175" y1="273" x2="190" y2="245" stroke="#5F5E5A" stroke-width="2"/>
<text class="tl" x="175" y="308" text-anchor="middle">Engine</text>
<!-- TAIL SECTION -->
<!-- Vertical stabilizer -->
<polygon class="tail-v" points="
520,180
560,100
580,100
580,180
"/>
<text class="tl" x="565" y="150" text-anchor="middle">Vertical</text>
<text class="tl" x="565" y="162" text-anchor="middle">stabilizer</text>
<!-- Rudder -->
<polygon points="575,105 590,105 590,178 580,178" fill="none" stroke="#185FA5" stroke-width="0.5" stroke-dasharray="3 2"/>
<text class="tl" x="595" y="145" opacity=".6">Rudder</text>
<!-- Horizontal stabilizer -->
<polygon class="tail-h" points="
500,195
460,175
465,170
580,170
580,180
520,195
"/>
<text class="tl" x="510" y="166">Horizontal stabilizer</text>
<!-- Elevator -->
<polygon points="462,174 450,168 455,163 467,169" fill="none" stroke="#185FA5" stroke-width="0.5" stroke-dasharray="3 2"/>
<text class="tl" x="440" y="158" opacity=".6">Elevator</text>
<!-- LANDING GEAR -->
<!-- Nose gear -->
<line class="gear" x1="100" y1="220" x2="100" y2="260" stroke-width="3"/>
<ellipse class="wheel" cx="100" cy="268" rx="8" ry="10"/>
<text class="tl" x="100" y="290" text-anchor="middle">Nose gear</text>
<!-- Main gear (under wing/fuselage junction) -->
<line class="gear" x1="280" y1="220" x2="280" y2="270" stroke-width="4"/>
<line class="gear" x1="268" y1="265" x2="292" y2="265" stroke-width="3"/>
<ellipse class="wheel" cx="268" cy="278" rx="10" ry="12"/>
<ellipse class="wheel" cx="292" cy="278" rx="10" ry="12"/>
<text class="tl" x="280" y="302" text-anchor="middle">Main gear</text>
<!-- LABELS with leader lines -->
<!-- Cockpit label -->
<line class="leader" x1="60" y1="175" x2="60" y2="140"/>
<text class="ts" x="60" y="132" text-anchor="middle">Cockpit</text>
<!-- Wing label -->
<line class="leader" x1="250" y1="250" x2="290" y2="330"/>
<text class="ts" x="290" y="345" text-anchor="middle">Wing structure</text>
<text class="tl" x="290" y="358" text-anchor="middle">Spars, ribs, skin</text>
<!-- Fuselage label -->
<line class="leader" x1="400" y1="180" x2="400" y2="140"/>
<text class="ts" x="400" y="132" text-anchor="middle">Fuselage</text>
<text class="tl" x="400" y="145" text-anchor="middle">Pressure vessel</text>
</svg>
```
## CSS Classes for Physical Diagrams
When creating physical/structural diagrams, define semantic classes for each component type:
```css
/* Structure shapes */
.fuselage { fill: #F1EFE8; stroke: #5F5E5A; stroke-width: 1; }
.wing { fill: #E6F1FB; stroke: #185FA5; stroke-width: 1; }
.tail-v { fill: #E6F1FB; stroke: #185FA5; stroke-width: 1; }
.tail-h { fill: #E6F1FB; stroke: #185FA5; stroke-width: 1; }
/* Interior sections */
.cockpit { fill: #EEEDFE; stroke: #534AB7; stroke-width: 1; }
.first-class { fill: #FBEAF0; stroke: #993556; stroke-width: 0.5; }
.business-class { fill: #FAECE7; stroke: #993C1D; stroke-width: 0.5; }
.economy-class { fill: #E1F5EE; stroke: #0F6E56; stroke-width: 0.5; }
.cargo { fill: #D3D1C7; stroke: #5F5E5A; stroke-width: 0.5; }
/* Systems */
.engine { fill: #FAECE7; stroke: #993C1D; stroke-width: 1; }
.fuel-tank { fill: #FAEEDA; stroke: #854F0B; stroke-width: 0.5; stroke-dasharray: 3 2; }
.flap { fill: #E1F5EE; stroke: #0F6E56; stroke-width: 0.5; }
/* Mechanical */
.gear { fill: #444441; stroke: #2C2C2A; stroke-width: 0.5; }
.wheel { fill: #2C2C2A; stroke: #1a1a18; stroke-width: 0.5; }
```
## Shape Selection Guide
| Physical form | SVG element | Example |
|---------------|-------------|---------|
| Curved body | `<path>` with Q (quadratic) or C (cubic) curves | Fuselage, nose cone |
| Tapered/angular | `<polygon>` | Wings, stabilizers |
| Cylindrical | `<ellipse>` | Engines, wheels, tanks |
| Linear structure | `<line>` | Struts, pylons, gear legs |
| Internal sections | `<rect>` inside parent shape | Cabin classes |
| Dashed boundaries | `stroke-dasharray` on any shape | Fuel tanks, control surfaces |
## Layout Notes
- **ViewBox**: 680×400 (wider aspect ratio suits side profile)
- **Layering**: Draw outer structures first, then interior details on top
- **Leader lines**: Use `.leader` class (dashed) to connect labels to components
- **Text sizes**: Use `.tl` (10px) for component labels, `.ts` (12px) for section labels
- **Semantic colors**: Group by system (structure=blue, propulsion=coral, fuel=amber, etc.)

236
optional-skills/creative/concept-diagrams/examples/cpu-ooo-microarchitecture.md
View file

@ -1,236 +0,0 @@
# Out-of-Order CPU Core Microarchitecture
A structural diagram showing the internal pipeline stages of a modern superscalar out-of-order CPU core. Demonstrates multi-stage vertical flow with parallel paths, fan-out patterns for execution ports, and a separate memory hierarchy sidebar.
## Key Patterns Used
- **Multi-stage vertical flow**: Six pipeline stages (Front End → Rename → Schedule → Execute → Retire)
- **Parallel decode paths**: Main decode and µop cache bypass (dashed line for cache hit)
- **Container grouping**: Logical stages grouped in colored containers
- **Fan-out pattern**: Single scheduler dispatching to 6 execution ports
- **Sidebar layout**: Memory hierarchy placed in separate column on right
- **Stage labels**: Left-aligned labels indicating pipeline phase
- **Color-coded semantics**: Different colors for each functional unit category
## Diagram Type
This is a **hybrid structural/flow** diagram:
- **Flow aspect**: Instructions move top-to-bottom through pipeline stages
- **Structural aspect**: Components are grouped by function (rename unit, execution cluster)
- **Sidebar**: Memory hierarchy is architecturally separate but connected via data paths
## Pipeline Stage Breakdown
### Front End (Purple)
```xml
<!-- Fetch Unit -->
<g class="node c-purple">
<rect x="40" y="70" width="140" height="56" rx="8" stroke-width="0.5"/>
<text class="th" x="110" y="90" text-anchor="middle" dominant-baseline="central">Fetch unit</text>
<text class="ts" x="110" y="110" text-anchor="middle" dominant-baseline="central">6-wide, 32B/cycle</text>
</g>
<!-- Branch Predictor (subordinate) -->
<g class="node c-purple">
<rect x="40" y="140" width="140" height="44" rx="8" stroke-width="0.5"/>
<text class="th" x="110" y="162" text-anchor="middle" dominant-baseline="central">Branch predictor</text>
</g>
<!-- Decode -->
<g class="node c-purple">
<rect x="230" y="70" width="160" height="56" rx="8" stroke-width="0.5"/>
<text class="th" x="310" y="90" text-anchor="middle" dominant-baseline="central">Decode</text>
<text class="ts" x="310" y="110" text-anchor="middle" dominant-baseline="central">x86 → µops, 6-wide</text>
</g>
```
### µop Cache Bypass Path (Teal)
The µop cache (Decoded Stream Buffer) provides an alternate path that bypasses the complex decoder:
```xml
<!-- µop Cache parallel to decode -->
<g class="node c-teal">
<rect x="230" y="150" width="160" height="50" rx="8" stroke-width="0.5"/>
<text class="th" x="310" y="168" text-anchor="middle" dominant-baseline="central">µop cache (DSB)</text>
<text class="ts" x="310" y="186" text-anchor="middle" dominant-baseline="central">4K entries, 8-wide</text>
</g>
<!-- Dashed bypass path indicating cache hit -->
<path d="M180 110 L205 110 L205 175 L230 175" fill="none" class="arr"
stroke-dasharray="4 3" marker-end="url(#arrow)"/>
<text class="tx" x="164" y="148" opacity=".6">hit</text>
```
### Rename/Allocate Container (Coral)
Groups related rename components in a container:
```xml
<!-- Outer container -->
<g class="c-coral">
<rect x="40" y="250" width="530" height="130" rx="12" stroke-width="0.5"/>
<text class="th" x="60" y="274">Rename / allocate</text>
<text class="ts" x="60" y="292">Map architectural → physical registers</text>
</g>
<!-- Inner components -->
<g class="node c-coral">
<rect x="60" y="310" width="180" height="56" rx="8" stroke-width="0.5"/>
<text class="th" x="150" y="330" text-anchor="middle" dominant-baseline="central">Register alias table</text>
<text class="ts" x="150" y="350" text-anchor="middle" dominant-baseline="central">180 physical regs</text>
</g>
```
### Scheduler Fan-Out Pattern (Amber → Teal)
Single unified scheduler dispatching to multiple execution ports:
```xml
<!-- Unified Scheduler -->
<g class="node c-amber">
<rect x="140" y="420" width="330" height="50" rx="8" stroke-width="0.5"/>
<text class="th" x="305" y="438" text-anchor="middle" dominant-baseline="central">Unified scheduler</text>
<text class="ts" x="305" y="456" text-anchor="middle" dominant-baseline="central">97 entries, out-of-order dispatch</text>
</g>
<!-- Fan-out arrows to 6 ports -->
<line x1="170" y1="470" x2="90" y2="540" class="arr" marker-end="url(#arrow)"/>
<line x1="215" y1="470" x2="170" y2="540" class="arr" marker-end="url(#arrow)"/>
<line x1="265" y1="470" x2="250" y2="540" class="arr" marker-end="url(#arrow)"/>
<line x1="305" y1="470" x2="330" y2="540" class="arr" marker-end="url(#arrow)"/>
<line x1="355" y1="470" x2="410" y2="540" class="arr" marker-end="url(#arrow)"/>
<line x1="420" y1="470" x2="490" y2="540" class="arr" marker-end="url(#arrow)"/>
```
### Execution Port Box Pattern
Compact boxes showing port number and capabilities:
```xml
<!-- Execution port with multi-line capability -->
<g class="node c-teal">
<rect x="55" y="540" width="70" height="64" rx="6" stroke-width="0.5"/>
<text class="th" x="90" y="560" text-anchor="middle" dominant-baseline="central">Port 0</text>
<text class="tx" x="90" y="576" text-anchor="middle" dominant-baseline="central">ALU</text>
<text class="tx" x="90" y="590" text-anchor="middle" dominant-baseline="central">DIV</text>
</g>
```
### Reorder Buffer (Pink)
Wide horizontal bar at bottom showing retirement:
```xml
<g class="c-pink">
<rect x="40" y="670" width="530" height="40" rx="10" stroke-width="0.5"/>
<text class="th" x="305" y="694" text-anchor="middle" dominant-baseline="central">Reorder buffer (ROB) — 512 entries, 8-wide retire</text>
</g>
```
### Memory Hierarchy Sidebar (Blue)
Separate column showing cache levels:
```xml
<!-- Container -->
<g class="c-blue">
<rect x="600" y="30" width="190" height="360" rx="16" stroke-width="0.5"/>
<text class="th" x="695" y="54" text-anchor="middle">Memory hierarchy</text>
</g>
<!-- Cache levels stacked vertically -->
<g class="node c-blue">
<rect x="620" y="70" width="150" height="50" rx="8" stroke-width="0.5"/>
<text class="th" x="695" y="88" text-anchor="middle" dominant-baseline="central">L1-I cache</text>
<text class="ts" x="695" y="106" text-anchor="middle" dominant-baseline="central">32 KB, 8-way</text>
</g>
<!-- Additional levels follow same pattern -->
```
## Connection Patterns
### Instruction Fetch Path
Horizontal arrow from L1-I cache to fetch unit:
```xml
<path d="M620 95 L200 95" fill="none" class="arr" marker-end="url(#arrow)"/>
<text class="tx" x="410" y="88" text-anchor="middle" opacity=".6">instruction fetch</text>
```
### Load/Store Path
Complex path from execution ports to L1-D cache:
```xml
<path d="M250 604 L250 640 L580 640 L580 160 L620 160" fill="none" class="arr" marker-end="url(#arrow)"/>
<text class="tx" x="415" y="652" text-anchor="middle" opacity=".6">load / store</text>
```
### Commit Path (dashed)
Dashed line showing write-back from ROB to register file:
```xml
<path d="M550 690 L580 690 L580 445 L595 445" fill="none" class="arr" stroke-dasharray="4 3"/>
<text class="tx" x="590" y="578" opacity=".6" transform="rotate(-90 590 578)">commit</text>
```
### Path Merge (Decode + µop Cache)
Two paths converging before rename:
```xml
<line x1="390" y1="98" x2="430" y2="98" class="arr"/>
<line x1="390" y1="175" x2="430" y2="175" class="arr"/>
<path d="M430 98 L430 175" fill="none" stroke="var(--text-secondary)" stroke-width="1.5"/>
<line x1="430" y1="136" x2="470" y2="136" class="arr" marker-end="url(#arrow)"/>
```
## Text Classes
This diagram uses an additional text class for very small labels:
```css
.tx { font-family: system-ui, -apple-system, sans-serif; font-size: 10px; fill: var(--text-secondary); }
```
Used for:
- Execution port capability labels (ALU, Branch, Load, etc.)
- Connection labels (instruction fetch, load/store, commit)
- DRAM latency annotation
## Color Semantic Mapping
| Color | Stage | Components |
|-------|-------|------------|
| `c-purple` | Front end | Fetch, Branch predictor, Decode |
| `c-teal` | Execution | µop cache, Execution ports |
| `c-coral` | Rename | RAT, Physical RF, Free list |
| `c-amber` | Schedule | Unified scheduler |
| `c-pink` | Retire | Reorder buffer |
| `c-blue` | Memory | L1-I, L1-D, L2, DRAM |
| `c-gray` | External | Off-chip DRAM |
## Layout Notes
- **ViewBox**: 820×720 (taller than wide for vertical pipeline flow)
- **Main pipeline**: x=40 to x=570 (530px width)
- **Memory sidebar**: x=600 to x=790 (190px width)
- **Stage labels**: x=30, left-aligned, 50% opacity
- **Vertical spacing**: ~80-100px between major stages
- **Container padding**: 20px inside containers
- **Port spacing**: 80px between execution port centers
- **Legend**: Bottom-right of memory sidebar, explains color coding
## Architectural Details Shown
| Component | Specification | Notes |
|-----------|---------------|-------|
| Fetch | 6-wide, 32B/cycle | Typical modern Intel/AMD |
| Decode | 6-wide, x86→µops | Complex decoder |
| µop Cache | 4K entries, 8-wide | Bypass for hot code |
| RAT | 180 physical regs | Supports deep OoO |
| Scheduler | 97 entries | Unified RS |
| Execution | 6 ports | ALU×2, Load, Store×2, Vector |
| ROB | 512 entries, 8-wide | In-order retirement |
| L1-I | 32 KB, 8-way | Instruction cache |
| L1-D | 48 KB, 12-way | Data cache |
| L2 | 1.25 MB, 20-way | Unified |
| DRAM | DDR5-6400, ~80ns | Off-chip |
## When to Use This Pattern
Use this diagram style for:
- CPU/GPU microarchitecture visualization
- Compiler pipeline stages
- Network packet processing pipelines
- Any system with parallel execution units fed by a scheduler
- Hardware designs with multiple functional units

182
optional-skills/creative/concept-diagrams/examples/electricity-grid-flow.md
View file

@ -1,182 +0,0 @@
# Electricity Grid: Generation to Consumption
A left-to-right flow diagram showing electricity from multiple generation sources through transmission and distribution networks to end consumers. Demonstrates multi-stage flow layout, voltage level visual hierarchy, and smart grid data overlay.
## Key Patterns Used
- **Multi-stage horizontal flow**: Four distinct columns (Generation → Transmission → Distribution → Consumption)
- **Stage dividers**: Vertical dashed lines separating each phase
- **Voltage level hierarchy**: Different line weights/colors for HV, MV, LV
- **Smart grid data overlay**: Dashed data flow lines from control center
- **Capacity labels**: Power ratings on generation sources
- **Multiple source convergence**: Four generators feeding into single transmission grid
## New Shape Techniques
### Nuclear Plant (cooling tower + reactor)
```xml
<!-- Cooling tower (hyperbolic curve) -->
<path class="nuclear-tower" d="M 25 80 Q 15 60 20 40 Q 25 20 40 15 Q 55 20 60 40 Q 65 60 55 80 Z"/>
<!-- Steam clouds -->
<ellipse class="nuclear-steam" cx="40" cy="8" rx="12" ry="6"/>
<!-- Reactor dome -->
<rect class="nuclear-building" x="65" y="45" width="40" height="35" rx="3"/>
<ellipse class="nuclear-building" cx="85" cy="45" rx="20" ry="8"/>
```
### Gas Peaker Plant (with flames)
```xml
<rect class="gas-plant" x="0" y="25" width="70" height="40" rx="3"/>
<!-- Smokestacks -->
<rect class="gas-stack" x="15" y="5" width="8" height="25" rx="1"/>
<!-- Flame -->
<path class="gas-flame" d="M 19 5 Q 17 0 19 -3 Q 21 0 19 5"/>
<!-- Turbine housing -->
<ellipse class="gas-plant" cx="55" cy="45" rx="12" ry="8"/>
```
### Transmission Pylon with Insulators
```xml
<!-- Tapered tower -->
<polygon class="pylon" points="20,0 25,0 30,80 15,80"/>
<!-- Cross arms -->
<line class="pylon-arm" x1="5" y1="10" x2="40" y2="10"/>
<line class="pylon-arm" x1="8" y1="25" x2="37" y2="25"/>
<!-- Insulators (where lines attach) -->
<circle class="insulator" cx="8" cy="10" r="3"/>
<circle class="insulator" cx="37" cy="10" r="3"/>
```
### Transformer Symbol
```xml
<!-- Two coils with core -->
<circle class="transformer-coil" cx="25" cy="25" r="12"/>
<circle class="transformer-coil" cx="55" cy="25" r="12"/>
<rect class="transformer-core" x="35" y="15" width="10" height="20" rx="2"/>
<!-- Busbars -->
<line x1="0" y1="15" x2="-10" y2="15" stroke="#EF9F27" stroke-width="3"/>
```
### Pole-mounted Transformer
```xml
<rect class="pole" x="18" y="0" width="4" height="60"/>
<line x1="10" y1="8" x2="30" y2="8" stroke="#854F0B" stroke-width="2"/>
<rect class="dist-transformer" x="8" y="15" width="24" height="18" rx="2"/>
<line class="lv-line" x1="20" y1="33" x2="20" y2="60"/>
```
### House with Roof
```xml
<rect class="home" x="0" y="25" width="35" height="30" rx="2"/>
<polygon class="home-roof" points="0,25 17,8 35,25"/>
<!-- Door -->
<rect x="8" y="35" width="8" height="15" fill="#085041"/>
<!-- Window -->
<rect x="22" y="32" width="8" height="8" fill="#9FE1CB"/>
```
### Factory Building
```xml
<rect class="factory" x="0" y="15" width="90" height="50" rx="3"/>
<!-- Smokestacks -->
<rect class="factory-stack" x="15" y="0" width="10" height="20"/>
<!-- Windows row -->
<rect x="10" y="30" width="15" height="12" fill="#F5C4B3"/>
<rect x="30" y="30" width="15" height="12" fill="#F5C4B3"/>
<!-- Loading dock -->
<rect x="55" y="50" width="30" height="15" fill="#993C1D"/>
```
### EV Charger with Car
```xml
<!-- Charging station -->
<rect class="ev-charger" x="20" y="0" width="25" height="45" rx="3"/>
<rect x="24" y="5" width="17" height="12" rx="1" fill="#3C3489"/>
<!-- Cable -->
<path d="M 32 20 Q 32 35 45 40" stroke="#534AB7" stroke-width="2" fill="none"/>
<circle cx="45" cy="40" r="4" fill="#534AB7"/>
<!-- Status light -->
<circle cx="32" cy="38" r="3" fill="#97C459"/>
<!-- EV Car -->
<path class="ev-car" d="M 5 20 L 5 12 Q 5 5 15 5 L 45 5 Q 55 5 55 12 L 55 20 Z"/>
<!-- Windows -->
<rect x="10" y="8" width="15" height="8" rx="2" fill="#534AB7"/>
<!-- Wheels -->
<circle cx="15" cy="22" r="5" fill="#2C2C2A"/>
<!-- Charging bolt icon -->
<path d="M 28 12 L 32 8 L 30 11 L 34 11 L 30 16 L 32 13 Z" fill="#97C459"/>
```
## Voltage Level Line Styles
```css
/* High voltage (transmission) - thick, bright */
.hv-line { stroke: #EF9F27; stroke-width: 2.5; fill: none; }
/* Medium voltage (distribution) - medium */
.mv-line { stroke: #BA7517; stroke-width: 2; fill: none; }
/* Low voltage (consumer) - thin, darker */
.lv-line { stroke: #854F0B; stroke-width: 1.5; fill: none; }
/* Smart grid data - dashed purple */
.data-flow { stroke: #7F77DD; stroke-width: 1; fill: none; stroke-dasharray: 3 2; opacity: 0.7; }
```
## Flow Arrow Marker
```xml
<defs>
<marker id="flow-arrow" viewBox="0 0 10 10" refX="9" refY="5"
markerWidth="6" markerHeight="6" orient="auto">
<path d="M0,0 L10,5 L0,10 Z" fill="#EF9F27"/>
</marker>
</defs>
<!-- Usage -->
<line x1="140" y1="105" x2="210" y2="105" class="hv-line" marker-end="url(#flow-arrow)"/>
```
## CSS Classes
```css
/* Generation */
.nuclear-tower { fill: #B4B2A9; stroke: #5F5E5A; stroke-width: 1; }
.nuclear-building { fill: #EEEDFE; stroke: #534AB7; stroke-width: 1; }
.solar-panel { fill: #3C3489; stroke: #534AB7; stroke-width: 0.5; }
.wind-tower { fill: #B4B2A9; stroke: #5F5E5A; stroke-width: 1; }
.wind-blade { fill: #F1EFE8; stroke: #888780; stroke-width: 0.5; }
.gas-plant { fill: #FAECE7; stroke: #993C1D; stroke-width: 1; }
.gas-flame { fill: #EF9F27; }
/* Transmission */
.pylon { fill: #5F5E5A; stroke: #444441; stroke-width: 0.5; }
.insulator { fill: #FAEEDA; stroke: #854F0B; stroke-width: 0.5; }
.substation { fill: #E6F1FB; stroke: #185FA5; stroke-width: 1; }
.transformer-coil { fill: none; stroke: #185FA5; stroke-width: 1.5; }
/* Distribution */
.pole { fill: #854F0B; stroke: #633806; stroke-width: 0.5; }
.dist-transformer { fill: #E1F5EE; stroke: #0F6E56; stroke-width: 1; }
/* Consumption */
.home { fill: #E1F5EE; stroke: #0F6E56; stroke-width: 1; }
.home-roof { fill: #0F6E56; stroke: #085041; stroke-width: 0.5; }
.factory { fill: #FAECE7; stroke: #993C1D; stroke-width: 1; }
.ev-charger { fill: #EEEDFE; stroke: #534AB7; stroke-width: 1; }
.ev-car { fill: #3C3489; stroke: #534AB7; stroke-width: 0.5; }
/* Smart grid */
.smart-grid { fill: #EEEDFE; stroke: #534AB7; stroke-width: 1.5; }
```
## Layout Notes
- **ViewBox**: 820×520 (wide for 4-column layout)
- **Column widths**: ~200px per stage
- **Stage dividers**: Vertical dashed lines at x=200, 420, 620
- **Stage labels**: Top of diagram, uppercase for emphasis
- **Flow direction**: Left-to-right with arrows showing power flow
- **Data overlay**: Smart grid data lines use different style (dashed purple) to distinguish from power lines
- **Capacity labels**: Show MW ratings on generators for context
- **Voltage labels**: Show transformation ratios at substations

172
optional-skills/creative/concept-diagrams/examples/feature-film-production-pipeline.md
View file

@ -1,172 +0,0 @@
# Feature Film Production Pipeline
A phased workflow showing the five stages of filmmaking, using containers with inner nodes and horizontal sub-flows within a phase.
## Key Patterns Used
- **Phase containers**: Large rounded rectangles with neutral background and dashed borders
- **Inner task nodes**: Smaller colored nodes inside containers for sub-tasks
- **Horizontal flow within container**: Post-production shows sequential pipeline with arrows (Editing → Color → VFX → Sound → Score)
- **Consistent phase spacing**: ~30px gap between phase containers
- **Phase labels with subtitles**: Each container has title + description
## Diagram
```xml
<svg width="100%" viewBox="0 0 680 780" xmlns="http://www.w3.org/2000/svg">
<defs>
<marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5"
markerWidth="6" markerHeight="6" orient="auto-start-reverse">
<path d="M2 1L8 5L2 9" fill="none" stroke="context-stroke"
stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
</marker>
</defs>
<!-- Phase 1: Development -->
<g>
<rect x="40" y="30" width="600" height="110" rx="16" stroke-width="1" stroke-dasharray="6 4" fill="var(--bg-secondary)" stroke="var(--border)"/>
<text class="th" x="66" y="56">Development</text>
<text class="ts" x="66" y="74">Concept to greenlight</text>
</g>
<g class="node c-purple">
<rect x="70" y="90" width="160" height="36" rx="6" stroke-width="0.5"/>
<text class="ts" x="150" y="108" text-anchor="middle" dominant-baseline="central">Script / screenplay</text>
</g>
<g class="node c-purple">
<rect x="260" y="90" width="160" height="36" rx="6" stroke-width="0.5"/>
<text class="ts" x="340" y="108" text-anchor="middle" dominant-baseline="central">Financing / budget</text>
</g>
<g class="node c-purple">
<rect x="450" y="90" width="160" height="36" rx="6" stroke-width="0.5"/>
<text class="ts" x="530" y="108" text-anchor="middle" dominant-baseline="central">Casting leads</text>
</g>
<!-- Arrow to Phase 2 -->
<line x1="340" y1="140" x2="340" y2="170" class="arr" marker-end="url(#arrow)"/>
<!-- Phase 2: Pre-production -->
<g>
<rect x="40" y="170" width="600" height="110" rx="16" stroke-width="1" stroke-dasharray="6 4" fill="var(--bg-secondary)" stroke="var(--border)"/>
<text class="th" x="66" y="196">Pre-production</text>
<text class="ts" x="66" y="214">Planning and preparation</text>
</g>
<g class="node c-teal">
<rect x="70" y="230" width="160" height="36" rx="6" stroke-width="0.5"/>
<text class="ts" x="150" y="248" text-anchor="middle" dominant-baseline="central">Storyboards</text>
</g>
<g class="node c-teal">
<rect x="260" y="230" width="160" height="36" rx="6" stroke-width="0.5"/>
<text class="ts" x="340" y="248" text-anchor="middle" dominant-baseline="central">Location scouting</text>
</g>
<g class="node c-teal">
<rect x="450" y="230" width="160" height="36" rx="6" stroke-width="0.5"/>
<text class="ts" x="530" y="248" text-anchor="middle" dominant-baseline="central">Crew hiring</text>
</g>
<!-- Arrow to Phase 3 -->
<line x1="340" y1="280" x2="340" y2="310" class="arr" marker-end="url(#arrow)"/>
<!-- Phase 3: Production -->
<g>
<rect x="40" y="310" width="600" height="110" rx="16" stroke-width="1" stroke-dasharray="6 4" fill="var(--bg-secondary)" stroke="var(--border)"/>
<text class="th" x="66" y="336">Production</text>
<text class="ts" x="66" y="354">Principal photography</text>
</g>
<g class="node c-coral">
<rect x="70" y="370" width="160" height="36" rx="6" stroke-width="0.5"/>
<text class="ts" x="150" y="388" text-anchor="middle" dominant-baseline="central">Filming / shooting</text>
</g>
<g class="node c-coral">
<rect x="260" y="370" width="160" height="36" rx="6" stroke-width="0.5"/>
<text class="ts" x="340" y="388" text-anchor="middle" dominant-baseline="central">Production sound</text>
</g>
<g class="node c-coral">
<rect x="450" y="370" width="160" height="36" rx="6" stroke-width="0.5"/>
<text class="ts" x="530" y="388" text-anchor="middle" dominant-baseline="central">VFX plates</text>
</g>
<!-- Arrow to Phase 4 -->
<line x1="340" y1="420" x2="340" y2="450" class="arr" marker-end="url(#arrow)"/>
<!-- Phase 4: Post-production -->
<g>
<rect x="40" y="450" width="600" height="150" rx="16" stroke-width="1" stroke-dasharray="6 4" fill="var(--bg-secondary)" stroke="var(--border)"/>
<text class="th" x="66" y="476">Post-production</text>
<text class="ts" x="66" y="494">Assembly and finishing</text>
</g>
<g class="node c-amber">
<rect x="70" y="510" width="110" height="36" rx="6" stroke-width="0.5"/>
<text class="ts" x="125" y="528" text-anchor="middle" dominant-baseline="central">Editing</text>
</g>
<g class="node c-amber">
<rect x="195" y="510" width="110" height="36" rx="6" stroke-width="0.5"/>
<text class="ts" x="250" y="528" text-anchor="middle" dominant-baseline="central">Color grade</text>
</g>
<g class="node c-amber">
<rect x="320" y="510" width="90" height="36" rx="6" stroke-width="0.5"/>
<text class="ts" x="365" y="528" text-anchor="middle" dominant-baseline="central">VFX</text>
</g>
<g class="node c-amber">
<rect x="425" y="510" width="100" height="36" rx="6" stroke-width="0.5"/>
<text class="ts" x="475" y="528" text-anchor="middle" dominant-baseline="central">Sound mix</text>
</g>
<g class="node c-amber">
<rect x="540" y="510" width="80" height="36" rx="6" stroke-width="0.5"/>
<text class="ts" x="580" y="528" text-anchor="middle" dominant-baseline="central">Score</text>
</g>
<!-- Flow arrows within post -->
<line x1="180" y1="528" x2="195" y2="528" class="arr" marker-end="url(#arrow)"/>
<line x1="305" y1="528" x2="320" y2="528" class="arr" marker-end="url(#arrow)"/>
<line x1="410" y1="528" x2="425" y2="528" class="arr" marker-end="url(#arrow)"/>
<line x1="525" y1="528" x2="540" y2="528" class="arr" marker-end="url(#arrow)"/>
<!-- Final delivery label -->
<g class="node c-amber">
<rect x="240" y="556" width="200" height="32" rx="6" stroke-width="0.5"/>
<text class="ts" x="340" y="572" text-anchor="middle" dominant-baseline="central">Final master / DCP</text>
</g>
<line x1="340" y1="546" x2="340" y2="556" class="arr" marker-end="url(#arrow)"/>
<!-- Arrow to Phase 5 -->
<line x1="340" y1="600" x2="340" y2="630" class="arr" marker-end="url(#arrow)"/>
<!-- Phase 5: Distribution -->
<g>
<rect x="40" y="630" width="600" height="110" rx="16" stroke-width="1" stroke-dasharray="6 4" fill="var(--bg-secondary)" stroke="var(--border)"/>
<text class="th" x="66" y="656">Distribution</text>
<text class="ts" x="66" y="674">Release and exhibition</text>
</g>
<g class="node c-blue">
<rect x="70" y="690" width="160" height="36" rx="6" stroke-width="0.5"/>
<text class="ts" x="150" y="708" text-anchor="middle" dominant-baseline="central">Film festivals</text>
</g>
<g class="node c-blue">
<rect x="260" y="690" width="160" height="36" rx="6" stroke-width="0.5"/>
<text class="ts" x="340" y="708" text-anchor="middle" dominant-baseline="central">Theatrical release</text>
</g>
<g class="node c-blue">
<rect x="450" y="690" width="160" height="36" rx="6" stroke-width="0.5"/>
<text class="ts" x="530" y="708" text-anchor="middle" dominant-baseline="central">Streaming / VOD</text>
</g>
</svg>
```
## Color Assignments
| Element | Color | Reason |
|---------|-------|--------|
| Phase containers | Neutral (dashed) | Subtle grouping, doesn't compete with content |
| Development tasks | `c-purple` | Creative/concept work |
| Pre-production tasks | `c-teal` | Planning and preparation |
| Production tasks | `c-coral` | Active filming (main event) |
| Post-production tasks | `c-amber` | Processing/refinement |
| Distribution tasks | `c-blue` | Outward delivery/release |
## Layout Notes
- **ViewBox**: 680×780 (standard width, tall for 5 phases)
- **Container style**: Dashed border (`stroke-dasharray="6 4"`), neutral fill (`var(--bg-secondary)`), `stroke-width="1"`
- **Container height**: 110px for 3-node phases, 150px for post-production (more complex)
- **Inner node dimensions**: 160×36px for standard tasks, variable width for post-production sequential flow
- **Phase gap**: 30px between containers
- **Horizontal sub-flow**: Post-production uses tightly packed nodes with arrows between them to show sequence
- **Convergence node**: "Final master / DCP" sits below the horizontal flow, collecting all post outputs

165
optional-skills/creative/concept-diagrams/examples/hospital-emergency-department-flow.md
View file

@ -1,165 +0,0 @@
# Hospital Emergency Department Flow
A multi-path flowchart showing patient journey through an emergency department with priority-based routing using semantic colors (red=critical, amber=urgent, green=stable).
## Key Patterns Used
- **Semantic color coding**: Red/amber/green for priority levels (not arbitrary decoration)
- **Stage labels**: Left-aligned faded labels marking workflow phases
- **Convergent paths**: Multiple entry points merging, then branching, then converging again
- **Nested containers**: Diagnostics grouped in a container with inner nodes
- **Legend**: Color key at bottom explaining priority levels
## Diagram
```xml
<svg width="100%" viewBox="0 0 680 620" xmlns="http://www.w3.org/2000/svg">
<defs>
<marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5"
markerWidth="6" markerHeight="6" orient="auto-start-reverse">
<path d="M2 1L8 5L2 9" fill="none" stroke="context-stroke"
stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
</marker>
</defs>
<!-- Stage labels -->
<text class="ts" x="40" y="68" text-anchor="start" opacity=".5">Arrival</text>
<text class="ts" x="40" y="168" text-anchor="start" opacity=".5">Assessment</text>
<text class="ts" x="40" y="288" text-anchor="start" opacity=".5">Priority routing</text>
<text class="ts" x="40" y="418" text-anchor="start" opacity=".5">Diagnostics</text>
<text class="ts" x="40" y="518" text-anchor="start" opacity=".5">Outcome</text>
<!-- Arrival: Ambulance -->
<g class="node c-gray">
<rect x="140" y="40" width="160" height="56" rx="8" stroke-width="0.5"/>
<text class="th" x="220" y="60" text-anchor="middle" dominant-baseline="central">Ambulance</text>
<text class="ts" x="220" y="80" text-anchor="middle" dominant-baseline="central">Emergency transport</text>
</g>
<!-- Arrival: Walk-in -->
<g class="node c-gray">
<rect x="380" y="40" width="160" height="56" rx="8" stroke-width="0.5"/>
<text class="th" x="460" y="60" text-anchor="middle" dominant-baseline="central">Walk-in</text>
<text class="ts" x="460" y="80" text-anchor="middle" dominant-baseline="central">Self-arrival</text>
</g>
<!-- Arrows to Triage -->
<line x1="220" y1="96" x2="300" y2="140" class="arr" marker-end="url(#arrow)"/>
<line x1="460" y1="96" x2="380" y2="140" class="arr" marker-end="url(#arrow)"/>
<!-- Triage -->
<g class="node c-purple">
<rect x="240" y="140" width="200" height="56" rx="8" stroke-width="0.5"/>
<text class="th" x="340" y="160" text-anchor="middle" dominant-baseline="central">Triage</text>
<text class="ts" x="340" y="180" text-anchor="middle" dominant-baseline="central">Nurse assessment, vitals</text>
</g>
<!-- Arrows from Triage to Priority -->
<line x1="280" y1="196" x2="140" y2="260" class="arr" marker-end="url(#arrow)"/>
<line x1="340" y1="196" x2="340" y2="260" class="arr" marker-end="url(#arrow)"/>
<line x1="400" y1="196" x2="540" y2="260" class="arr" marker-end="url(#arrow)"/>
<!-- Priority: Red - Trauma -->
<g class="node c-red">
<rect x="60" y="260" width="160" height="56" rx="8" stroke-width="0.5"/>
<text class="th" x="140" y="280" text-anchor="middle" dominant-baseline="central">Trauma bay</text>
<text class="ts" x="140" y="300" text-anchor="middle" dominant-baseline="central">Priority: critical</text>
</g>
<!-- Priority: Yellow - Exam rooms -->
<g class="node c-amber">
<rect x="260" y="260" width="160" height="56" rx="8" stroke-width="0.5"/>
<text class="th" x="340" y="280" text-anchor="middle" dominant-baseline="central">Exam rooms</text>
<text class="ts" x="340" y="300" text-anchor="middle" dominant-baseline="central">Priority: urgent</text>
</g>
<!-- Priority: Green - Waiting -->
<g class="node c-green">
<rect x="460" y="260" width="160" height="56" rx="8" stroke-width="0.5"/>
<text class="th" x="540" y="280" text-anchor="middle" dominant-baseline="central">Waiting area</text>
<text class="ts" x="540" y="300" text-anchor="middle" dominant-baseline="central">Priority: stable</text>
</g>
<!-- Arrows to Diagnostics -->
<line x1="140" y1="316" x2="220" y2="390" class="arr" marker-end="url(#arrow)"/>
<line x1="340" y1="316" x2="340" y2="390" class="arr" marker-end="url(#arrow)"/>
<line x1="540" y1="316" x2="460" y2="390" class="arr" marker-end="url(#arrow)"/>
<!-- Diagnostics container -->
<g class="c-teal">
<rect x="140" y="390" width="400" height="56" rx="12" stroke-width="0.5"/>
</g>
<!-- Labs -->
<g class="node c-teal">
<rect x="160" y="400" width="110" height="36" rx="6" stroke-width="0.5"/>
<text class="ts" x="215" y="418" text-anchor="middle" dominant-baseline="central">Labs</text>
</g>
<!-- Imaging -->
<g class="node c-teal">
<rect x="285" y="400" width="110" height="36" rx="6" stroke-width="0.5"/>
<text class="ts" x="340" y="418" text-anchor="middle" dominant-baseline="central">Imaging</text>
</g>
<!-- Diagnosis -->
<g class="node c-teal">
<rect x="410" y="400" width="110" height="36" rx="6" stroke-width="0.5"/>
<text class="ts" x="465" y="418" text-anchor="middle" dominant-baseline="central">Diagnosis</text>
</g>
<!-- Arrows to Outcomes -->
<line x1="215" y1="446" x2="160" y2="490" class="arr" marker-end="url(#arrow)"/>
<line x1="340" y1="446" x2="340" y2="490" class="arr" marker-end="url(#arrow)"/>
<line x1="465" y1="446" x2="520" y2="490" class="arr" marker-end="url(#arrow)"/>
<!-- Outcome: Admission -->
<g class="node c-coral">
<rect x="80" y="490" width="160" height="56" rx="8" stroke-width="0.5"/>
<text class="th" x="160" y="510" text-anchor="middle" dominant-baseline="central">Admission</text>
<text class="ts" x="160" y="530" text-anchor="middle" dominant-baseline="central">Inpatient ward</text>
</g>
<!-- Outcome: Surgery -->
<g class="node c-coral">
<rect x="260" y="490" width="160" height="56" rx="8" stroke-width="0.5"/>
<text class="th" x="340" y="510" text-anchor="middle" dominant-baseline="central">Surgery</text>
<text class="ts" x="340" y="530" text-anchor="middle" dominant-baseline="central">Operating room</text>
</g>
<!-- Outcome: Discharge -->
<g class="node c-coral">
<rect x="440" y="490" width="160" height="56" rx="8" stroke-width="0.5"/>
<text class="th" x="520" y="510" text-anchor="middle" dominant-baseline="central">Discharge</text>
<text class="ts" x="520" y="530" text-anchor="middle" dominant-baseline="central">Home with instructions</text>
</g>
<!-- Legend -->
<text class="ts" x="140" y="580" opacity=".5">Priority levels</text>
<g class="c-red"><rect x="140" y="592" width="14" height="14" rx="3" stroke-width="0.5"/></g>
<text class="ts" x="162" y="604">Critical</text>
<g class="c-amber"><rect x="240" y="592" width="14" height="14" rx="3" stroke-width="0.5"/></g>
<text class="ts" x="262" y="604">Urgent</text>
<g class="c-green"><rect x="340" y="592" width="14" height="14" rx="3" stroke-width="0.5"/></g>
<text class="ts" x="362" y="604">Stable</text>
</svg>
```
## Color Assignments
| Element | Color | Reason |
|---------|-------|--------|
| Entry points (Ambulance, Walk-in) | `c-gray` | Neutral starting points |
| Triage | `c-purple` | Processing/assessment step |
| Trauma bay | `c-red` | Critical priority (semantic) |
| Exam rooms | `c-amber` | Urgent priority (semantic) |
| Waiting area | `c-green` | Stable priority (semantic) |
| Diagnostics | `c-teal` | Clinical services category |
| Outcomes | `c-coral` | Final disposition category |
## Layout Notes
- **ViewBox**: 680×620 (standard width, extended height for 5 stages)
- **Stage spacing**: ~110-130px between stage rows
- **Diagonal arrows**: Connect nodes across columns naturally
- **Container with inner nodes**: Diagnostics uses outer `c-teal` rect with inner node rects

114
optional-skills/creative/concept-diagrams/examples/ml-benchmark-grouped-bar-chart.md
View file

@ -1,114 +0,0 @@
# ML Benchmark Grouped Bar Chart with Dual Axis
A quantitative data visualization comparing LLM inference speed across quantization levels with dual Y-axes, threshold markers, and an inset accuracy table.
## Key Patterns Used
- **Grouped bars**: Min/max range pairs per category using semantic color pairs (lighter=min, darker=max)
- **Dual Y-axis**: Left axis for primary metric (tok/s), right axis for secondary metric (VRAM GB)
- **Overlay line graph**: `<polyline>` with labeled dots showing VRAM usage across categories
- **Threshold marker**: Dashed red horizontal line indicating hardware limit (24 GB GPU)
- **Zone annotations**: Subtle text labels above/below threshold for context
- **Inset data table**: Alternating row fills below chart with quantitative accuracy data
- **Semantic color coding**: Each quantization level gets its own color from the skill palette (red=OOM, amber=slow, teal=sweet spot, blue=fast)
## Diagram Type
This is a **quantitative data chart** with:
- **Grouped vertical bars**: Range bars showing min–max performance per category
- **Secondary axis line**: VRAM usage overlaid as a connected scatter plot
- **Threshold annotation**: Hardware constraint line
- **Inset table**: Supporting accuracy metrics
## Chart Layout Formula
```
Chart area: x=90–590, y=70–410 (500px wide, 340px tall)
Left Y-axis: Primary metric (tok/s)
y = 410 − (val / max_val) × 340
Right Y-axis: Secondary metric (VRAM GB)
Same formula, different scale labels
Groups: Divide width by number of categories
Bars: Each group → min bar (34px) + 8px gap + max bar (34px)
Line overlay: <polyline> connecting data points across group centers
Threshold: Horizontal dashed line at critical value
Table: Below chart, alternating row fills
```
## Data Mapped
| Quantization | Model Size | Speed (tok/s) | VRAM (GB) | MMLU Pro | Status |
|-------------|-----------|---------------|-----------|----------|--------|
| FP16 | 62 GB | 0.5–2 | 62 | 75.2 | OOM / unusable |
| Q8_0 | 32 GB | 3–5 | 32 | 75.0 | Partial offload |
| Q4_K_M | 16.8 GB | 8–12 | 16.8 | 73.1 | Fits in VRAM ✓ |
| IQ3_M | 12 GB | 12–15 | 12 | 70.5 | Full GPU speed |
## Bar CSS Classes
```css
/* Light mode */
.bar-fp16-min { fill: #FCEBEB; stroke: #A32D2D; stroke-width: 0.75; }
.bar-fp16-max { fill: #F7C1C1; stroke: #A32D2D; stroke-width: 0.75; }
.bar-q8-min { fill: #FAEEDA; stroke: #854F0B; stroke-width: 0.75; }
.bar-q8-max { fill: #FAC775; stroke: #854F0B; stroke-width: 0.75; }
.bar-q4-min { fill: #E1F5EE; stroke: #0F6E56; stroke-width: 0.75; }
.bar-q4-max { fill: #9FE1CB; stroke: #0F6E56; stroke-width: 0.75; }
.bar-iq3-min { fill: #E6F1FB; stroke: #185FA5; stroke-width: 0.75; }
.bar-iq3-max { fill: #B5D4F4; stroke: #185FA5; stroke-width: 0.75; }
/* Dark mode */
@media (prefers-color-scheme: dark) {
.bar-fp16-min { fill: #501313; stroke: #F09595; }
.bar-fp16-max { fill: #791F1F; stroke: #F09595; }
.bar-q8-min { fill: #412402; stroke: #EF9F27; }
.bar-q8-max { fill: #633806; stroke: #EF9F27; }
.bar-q4-min { fill: #04342C; stroke: #5DCAA5; }
.bar-q4-max { fill: #085041; stroke: #5DCAA5; }
.bar-iq3-min { fill: #042C53; stroke: #85B7EB; }
.bar-iq3-max { fill: #0C447C; stroke: #85B7EB; }
}
```
## Overlay Line CSS
```css
.vram-line { stroke: #534AB7; stroke-width: 2.5; fill: none; }
.vram-dot { fill: #534AB7; stroke: var(--bg-primary); stroke-width: 2; }
.vram-label { font-family: system-ui, sans-serif; font-size: 10px; fill: #534AB7; font-weight: 500; }
```
## Threshold CSS
```css
.threshold { stroke: #A32D2D; stroke-width: 1; stroke-dasharray: 6 3; fill: none; }
.threshold-label { font-family: system-ui, sans-serif; font-size: 10px; fill: #A32D2D; font-weight: 500; }
```
## Table CSS
```css
.tbl-header { fill: var(--bg-secondary); stroke: var(--border); stroke-width: 0.5; }
.tbl-row { fill: transparent; stroke: var(--border); stroke-width: 0.25; }
.tbl-alt { fill: var(--bg-secondary); stroke: var(--border); stroke-width: 0.25; }
```
## Layout Notes
- **ViewBox**: 680×660 (portrait, chart + legend + table)
- **Chart area**: y=70–410, x=90–590
- **Legend row**: y=458–470
- **Inset table**: y=490–620
- **Bar width**: 34px each, 8px gap between min/max pair
- **Group spacing**: 125px center-to-center
- **Dot halo**: White circle (r=6) behind colored dot (r=5) for legibility over bars/grid
## When to Use This Pattern
Use this diagram style for:
- Model benchmark comparisons across quantization levels
- Performance vs. resource usage tradeoff analysis
- Any multi-metric comparison with a hardware/software constraint
- GPU/TPU/accelerator benchmarking dashboards
- Accuracy vs. speed Pareto frontiers
- Hardware requirement sizing charts

325
optional-skills/creative/concept-diagrams/examples/place-order-uml-sequence.md
View file

@ -1,325 +0,0 @@
# Place Order — UML Sequence Diagram
A UML sequence diagram for the 'Place Order' use case in an e-commerce system. Six lifelines (:Customer, :ShoppingCart, :OrderController, :PaymentGateway, :InventorySystem, :EmailService) interact across 14 numbered messages. An **alt** combined fragment (amber) covers the three conditional outcomes — payment authorized, payment failed, and item unavailable. A **par** combined fragment (teal) nested inside the success branch shows concurrent email confirmation and stock-level update. Demonstrates activation bars, two distinct arrowhead types, UML pentagon fragment tags, and guard conditions.
## Key Patterns Used
- **6 lifelines at equal spacing**: Lifeline centers placed at x=90, 190, 290, 390, 490, 590 (100px apart) so the first box left-edge lands at x=40 and the last right-edge lands at x=640 — exactly filling the safe area
- **Two-row actor headers**: Each lifeline box shows `":"` (small, tertiary color) on one line and the class name (slightly larger, bold) on a second line, matching the UML anonymous-instance notation `:ClassName`
- **Two separate arrowhead markers**: `#arr-call` is a filled triangle (`<polygon>`) for synchronous calls; `#arr-ret` is an open chevron (`fill="none"`) for dashed return messages — both use `context-stroke` to inherit line color
- **Activation bars**: Narrow 8px-wide rectangles (`class="activation"`) layered on top of lifeline stems to show object execution periods; OrderController's bar spans the entire interaction; shorter bars mark PaymentGateway, InventorySystem, and EmailService during their active windows
- **Combined fragment pentagon tag**: Each `alt` / `par` frame uses a `<polygon>` dog-eared label shape in the top-left corner — points follow the pattern `(x,y) (x+w,y) (x+w+6,y+6) (x+w+6,y+18) (x,y+18)` creating the characteristic UML notch
- **Nested par inside alt**: The `par` rect (teal) sits inside branch 1 of the `alt` rect (amber); inner rect uses inset x/y (+15/+2) so both borders remain visible and distinguishable
- **Guard conditions**: Italic text in `[square brackets]` placed immediately after each alt frame divider line, or just inside the top frame for branch 1 — rendered with a dedicated `guard-lbl` class (italic, amber color)
- **Alt branch dividers**: Solid horizontal lines (`.frag-alt-div`) span the full alt rect width to separate the three branches; par branch separator uses a dashed line (`.frag-par-div`) per UML spec
- **Lifeline end caps**: Short 14px horizontal tick marks at y=590 (bottom of all lifeline stems) to formally terminate each lifeline
- **Message sequence annotation**: A faint counter row below the legend (①–③ / ④–⑩ / ⑪–⑫ / ⑬–⑭) explains the four message groups without adding noise to the diagram body
## Diagram
```xml
<svg width="100%" viewBox="0 0 680 648" xmlns="http://www.w3.org/2000/svg">
<defs>
<!-- Open chevron arrowhead — return messages -->
<marker id="arr-ret" viewBox="0 0 10 10" refX="8" refY="5"
markerWidth="6" markerHeight="6" orient="auto-start-reverse">
<path d="M2 1L8 5L2 9" fill="none" stroke="context-stroke"
stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
</marker>
<!-- Filled triangle arrowhead — synchronous calls -->
<marker id="arr-call" viewBox="0 0 10 10" refX="9" refY="5"
markerWidth="7" markerHeight="7" orient="auto">
<polygon points="0,1 10,5 0,9" fill="context-stroke"/>
</marker>
</defs>
<!--
Lifeline centres (x):
L1 :Customer → 90
L2 :ShoppingCart → 190
L3 :OrderController → 290
L4 :PaymentGateway → 390
L5 :InventorySystem → 490
L6 :EmailService → 590
Actor boxes: x = cx−50, y=20, w=100, h=56, rx=6
Lifelines: x = cx, y1=76, y2=590
-->
<!-- ── 1. LIFELINE DASHED STEMS (drawn first, behind everything) ── -->
<line x1="90" y1="76" x2="90" y2="590" class="lifeline"/>
<line x1="190" y1="76" x2="190" y2="590" class="lifeline"/>
<line x1="290" y1="76" x2="290" y2="590" class="lifeline"/>
<line x1="390" y1="76" x2="390" y2="590" class="lifeline"/>
<line x1="490" y1="76" x2="490" y2="590" class="lifeline"/>
<line x1="590" y1="76" x2="590" y2="590" class="lifeline"/>
<!-- ── 2. ACTOR HEADER BOXES ── -->
<!-- :Customer -->
<rect x="40" y="20" width="100" height="56" rx="6" class="actor"/>
<text class="actor-colon" x="90" y="40" text-anchor="middle" dominant-baseline="central">:</text>
<text class="actor-name" x="90" y="58" text-anchor="middle" dominant-baseline="central">Customer</text>
<!-- :ShoppingCart -->
<rect x="140" y="20" width="100" height="56" rx="6" class="actor"/>
<text class="actor-colon" x="190" y="37" text-anchor="middle" dominant-baseline="central">:</text>
<text class="actor-name" x="190" y="55" text-anchor="middle" dominant-baseline="central">ShoppingCart</text>
<!-- :OrderController -->
<rect x="240" y="20" width="100" height="56" rx="6" class="actor"/>
<text class="actor-colon" x="290" y="37" text-anchor="middle" dominant-baseline="central">:</text>
<text class="actor-name" x="290" y="55" text-anchor="middle" dominant-baseline="central">OrderController</text>
<!-- :PaymentGateway -->
<rect x="340" y="20" width="100" height="56" rx="6" class="actor"/>
<text class="actor-colon" x="390" y="37" text-anchor="middle" dominant-baseline="central">:</text>
<text class="actor-name" x="390" y="55" text-anchor="middle" dominant-baseline="central">PaymentGateway</text>
<!-- :InventorySystem -->
<rect x="440" y="20" width="100" height="56" rx="6" class="actor"/>
<text class="actor-colon" x="490" y="37" text-anchor="middle" dominant-baseline="central">:</text>
<text class="actor-name" x="490" y="55" text-anchor="middle" dominant-baseline="central">InventorySystem</text>
<!-- :EmailService -->
<rect x="540" y="20" width="100" height="56" rx="6" class="actor"/>
<text class="actor-colon" x="590" y="37" text-anchor="middle" dominant-baseline="central">:</text>
<text class="actor-name" x="590" y="55" text-anchor="middle" dominant-baseline="central">EmailService</text>
<!-- ── 3. ACTIVATION BARS ── -->
<!-- ShoppingCart: active while forwarding checkout → placeOrder -->
<rect x="186" y="102" width="8" height="26" rx="1" class="activation"/>
<!-- OrderController: active throughout full sequence -->
<rect x="286" y="128" width="8" height="415" rx="1" class="activation"/>
<!-- PaymentGateway: active during auth check (happy-path branch only) -->
<rect x="386" y="154" width="8" height="46" rx="1" class="activation"/>
<!-- InventorySystem: active from reserveItems → updateStockLevels end -->
<rect x="486" y="225" width="8" height="128" rx="1" class="activation"/>
<!-- EmailService: active during confirmation send -->
<rect x="586" y="290" width="8" height="25" rx="1" class="activation"/>
<!-- ── 4. PRE-ALT MESSAGES ── -->
<!-- ① checkout() :Customer → :ShoppingCart -->
<line x1="90" y1="102" x2="186" y2="102" class="msg-call" marker-end="url(#arr-call)"/>
<text class="mlbl" x="140" y="97" text-anchor="middle">checkout()</text>
<!-- ② placeOrder(cartItems) :ShoppingCart → :OrderController -->
<line x1="194" y1="128" x2="286" y2="128" class="msg-call" marker-end="url(#arr-call)"/>
<text class="mlbl" x="242" y="123" text-anchor="middle">placeOrder(cartItems)</text>
<!-- ③ authorizePayment(amount) :OrderController → :PaymentGateway -->
<line x1="294" y1="154" x2="386" y2="154" class="msg-call" marker-end="url(#arr-call)"/>
<text class="mlbl" x="342" y="149" text-anchor="middle">authorizePayment(amount)</text>
<!-- ── 5. ALT COMBINED FRAGMENT y=166 → y=563 ── -->
<!-- Outer alt rectangle -->
<rect x="45" y="166" width="590" height="397" rx="3" class="frag-alt-bg"/>
<!-- Pentagon "alt" tag: TL corner notch shape -->
<polygon points="45,166 84,166 90,173 90,185 45,185" class="frag-alt-tag"/>
<text class="frag-alt-kw" x="67" y="178" text-anchor="middle" dominant-baseline="central">alt</text>
<!-- Guard: branch 1 -->
<text class="guard-lbl" x="96" y="179" dominant-baseline="central">[payment authorized]</text>
<!-- ─── Branch 1: payment authorized ─── -->
<!-- ④ « authorized » :PaymentGateway → :OrderController (dashed return) -->
<line x1="386" y1="200" x2="294" y2="200" class="msg-ret" marker-end="url(#arr-ret)"/>
<text class="rlbl" x="342" y="195" text-anchor="middle">« authorized »</text>
<!-- ⑤ reserveItems(cartItems) :OrderController → :InventorySystem -->
<line x1="294" y1="225" x2="486" y2="225" class="msg-call" marker-end="url(#arr-call)"/>
<text class="mlbl" x="392" y="220" text-anchor="middle">reserveItems(cartItems)</text>
<!-- ⑥ « itemsReserved » :InventorySystem → :OrderController (dashed return) -->
<line x1="486" y1="250" x2="294" y2="250" class="msg-ret" marker-end="url(#arr-ret)"/>
<text class="rlbl" x="392" y="245" text-anchor="middle">« itemsReserved »</text>
<!-- ── 6. PAR COMBINED FRAGMENT (nested inside alt branch 1) y=266 → y=373 ── -->
<!-- Inner par rectangle -->
<rect x="60" y="266" width="560" height="107" rx="3" class="frag-par-bg"/>
<!-- Pentagon "par" tag -->
<polygon points="60,266 97,266 102,272 102,284 60,284" class="frag-par-tag"/>
<text class="frag-par-kw" x="81" y="275" text-anchor="middle" dominant-baseline="central">par</text>
<!-- Par branch 1: email confirmation -->
<!-- ⑦ sendConfirmationEmail() :OrderController → :EmailService -->
<line x1="294" y1="295" x2="586" y2="295" class="msg-call" marker-end="url(#arr-call)"/>
<text class="mlbl" x="442" y="290" text-anchor="middle">sendConfirmationEmail()</text>
<!-- ⑧ « emailQueued » :EmailService → :OrderController (dashed return) -->
<line x1="586" y1="318" x2="294" y2="318" class="msg-ret" marker-end="url(#arr-ret)"/>
<text class="rlbl" x="442" y="313" text-anchor="middle">« emailQueued »</text>
<!-- Par branch divider (dashed, per UML spec) -->
<line x1="60" y1="336" x2="620" y2="336" class="frag-par-div"/>
<!-- Par branch 2: stock level update -->
<!-- ⑨ updateStockLevels() :OrderController → :InventorySystem -->
<line x1="294" y1="355" x2="486" y2="355" class="msg-call" marker-end="url(#arr-call)"/>
<text class="mlbl" x="392" y="350" text-anchor="middle">updateStockLevels()</text>
<!-- PAR fragment ends at y=373 -->
<!-- ⑩ « orderPlaced » :OrderController → :Customer (dashed return, after par) -->
<line x1="286" y1="395" x2="90" y2="395" class="msg-ret" marker-end="url(#arr-ret)"/>
<text class="rlbl" x="190" y="390" text-anchor="middle">« orderPlaced »</text>
<!-- ─── Alt else: [payment failed] ─── -->
<!-- Alt branch divider 1 (solid line) -->
<line x1="45" y1="415" x2="635" y2="415" class="frag-alt-div"/>
<text class="guard-lbl" x="50" y="429" dominant-baseline="central">[payment failed]</text>
<!-- ⑪ « authFailed » :PaymentGateway → :OrderController (dashed return) -->
<line x1="390" y1="448" x2="294" y2="448" class="msg-ret" marker-end="url(#arr-ret)"/>
<text class="rlbl" x="344" y="443" text-anchor="middle">« authFailed »</text>
<!-- ⑫ error(PAYMENT_FAILED) :OrderController → :Customer -->
<line x1="286" y1="470" x2="90" y2="470" class="msg-call" marker-end="url(#arr-call)"/>
<text class="mlbl" x="190" y="465" text-anchor="middle">error(PAYMENT_FAILED)</text>
<!-- ─── Alt else: [item unavailable] ─── -->
<!-- Alt branch divider 2 (solid line) -->
<line x1="45" y1="490" x2="635" y2="490" class="frag-alt-div"/>
<text class="guard-lbl" x="50" y="504" dominant-baseline="central">[item unavailable]</text>
<!-- ⑬ « unavailable » :InventorySystem → :OrderController (dashed return) -->
<line x1="486" y1="523" x2="294" y2="523" class="msg-ret" marker-end="url(#arr-ret)"/>
<text class="rlbl" x="392" y="518" text-anchor="middle">« unavailable »</text>
<!-- ⑭ error(ITEM_UNAVAILABLE) :OrderController → :Customer -->
<line x1="286" y1="545" x2="90" y2="545" class="msg-call" marker-end="url(#arr-call)"/>
<text class="mlbl" x="190" y="540" text-anchor="middle">error(ITEM_UNAVAILABLE)</text>
<!-- ALT fragment ends at y=563 -->
<!-- ── 7. LIFELINE END CAPS (short horizontal tick at y=590) ── -->
<line x1="83" y1="590" x2="97" y2="590" stroke="var(--text-tertiary)" stroke-width="1.5"/>
<line x1="183" y1="590" x2="197" y2="590" stroke="var(--text-tertiary)" stroke-width="1.5"/>
<line x1="283" y1="590" x2="297" y2="590" stroke="var(--text-tertiary)" stroke-width="1.5"/>
<line x1="383" y1="590" x2="397" y2="590" stroke="var(--text-tertiary)" stroke-width="1.5"/>
<line x1="483" y1="590" x2="497" y2="590" stroke="var(--text-tertiary)" stroke-width="1.5"/>
<line x1="583" y1="590" x2="597" y2="590" stroke="var(--text-tertiary)" stroke-width="1.5"/>
<!-- ── 8. LEGEND ── -->
<text class="ts" x="45" y="612" opacity=".45">Legend —</text>
<line x1="110" y1="609" x2="148" y2="609"
stroke="var(--text-primary)" stroke-width="1.5" marker-end="url(#arr-call)"/>
<text class="ts" x="154" y="613" opacity=".75">Synchronous call</text>
<line x1="288" y1="609" x2="326" y2="609"
stroke="var(--text-secondary)" stroke-width="1.5"
stroke-dasharray="5 3" marker-end="url(#arr-ret)"/>
<text class="ts" x="332" y="613" opacity=".75">Return message</text>
<rect x="458" y="603" width="22" height="13" rx="2"
fill="#FAEEDA" fill-opacity="0.5" stroke="#854F0B" stroke-width="0.75"/>
<text class="ts" x="484" y="613" opacity=".75">alt fragment</text>
<rect x="558" y="603" width="22" height="13" rx="2"
fill="#E1F5EE" fill-opacity="0.6" stroke="#0F6E56" stroke-width="0.75"/>
<text class="ts" x="584" y="613" opacity=".75">par fragment</text>
<!-- Message group annotation -->
<text class="ts" x="45" y="632" opacity=".35">
①–③ pre-condition · ④–⑩ happy path · ⑪–⑫ payment failure · ⑬–⑭ item unavailable
</text>
</svg>
```
## Custom CSS
Add these classes to the hosting page `<style>` block (in addition to the standard skill CSS):
```css
/* ── Actor lifeline header boxes ── */
.actor { fill: var(--bg-secondary); stroke: var(--text-secondary); stroke-width: 0.5; }
.actor-name { font-family: system-ui, sans-serif; font-size: 11.5px; font-weight: 600;
fill: var(--text-primary); }
.actor-colon { font-family: system-ui, sans-serif; font-size: 10px; fill: var(--text-tertiary); }
/* ── Lifeline dashed stems ── */
.lifeline { stroke: var(--text-tertiary); stroke-width: 1; stroke-dasharray: 6 4; fill: none; }
/* ── Activation bars ── */
.activation { fill: var(--bg-secondary); stroke: var(--text-secondary); stroke-width: 0.75; }
/* ── Message arrows ── */
.msg-call { stroke: var(--text-primary); stroke-width: 1.5; fill: none; }
.msg-ret { stroke: var(--text-secondary); stroke-width: 1.5; fill: none; stroke-dasharray: 6 3; }
/* ── Message labels ── */
.mlbl { font-family: system-ui, sans-serif; font-size: 11px; fill: var(--text-primary); }
.rlbl { font-family: system-ui, sans-serif; font-size: 11px; fill: var(--text-secondary);
font-style: italic; }
/* ── Combined fragment: alt (amber) ── */
.frag-alt-bg { fill: #FAEEDA; fill-opacity: 0.18; stroke: #854F0B; stroke-width: 1; }
.frag-alt-tag { fill: #FAEEDA; stroke: #854F0B; stroke-width: 0.75; }
.frag-alt-kw { font-family: system-ui, sans-serif; font-size: 11px; font-weight: 700;
fill: #633806; }
.frag-alt-div { stroke: #854F0B; stroke-width: 0.75; fill: none; }
.guard-lbl { font-family: system-ui, sans-serif; font-size: 10.5px; font-style: italic;
fill: #854F0B; }
/* ── Combined fragment: par (teal) ── */
.frag-par-bg { fill: #E1F5EE; fill-opacity: 0.35; stroke: #0F6E56; stroke-width: 1; }
.frag-par-tag { fill: #E1F5EE; stroke: #0F6E56; stroke-width: 0.75; }
.frag-par-kw { font-family: system-ui, sans-serif; font-size: 11px; font-weight: 700;
fill: #085041; }
.frag-par-div { stroke: #0F6E56; stroke-width: 0.75; stroke-dasharray: 5 3; fill: none; }
/* ── Dark mode overrides ── */
@media (prefers-color-scheme: dark) {
.actor { fill: #2c2c2a; stroke: #b4b2a9; }
.actor-name { fill: #e8e6de; }
.actor-colon { fill: #888780; }
.frag-alt-bg { fill: #633806; fill-opacity: 0.25; stroke: #EF9F27; }
.frag-alt-tag { fill: #633806; stroke: #EF9F27; }
.frag-alt-kw { fill: #FAC775; }
.frag-alt-div { stroke: #EF9F27; }
.guard-lbl { fill: #EF9F27; }
.frag-par-bg { fill: #085041; fill-opacity: 0.35; stroke: #5DCAA5; }
.frag-par-tag { fill: #085041; stroke: #5DCAA5; }
.frag-par-kw { fill: #9FE1CB; }
.frag-par-div { stroke: #5DCAA5; }
}
```
## Color Assignments
| Element | Color | Reason |
|---------|-------|--------|
| Actor header boxes | Neutral (`var(--bg-secondary)`) | Structural / non-semantic — all lifelines share one style |
| Activation bars | Neutral (`var(--bg-secondary)`) | Show execution periods without adding semantic color |
| Synchronous call arrows | `var(--text-primary)` + filled triangle | High contrast for calls — the primary interaction direction |
| Return / dashed arrows | `var(--text-secondary)` + open chevron | Lower contrast for returns — secondary flow direction |
| `alt` fragment | Amber (`#FAEEDA` / `#854F0B`) | Warning / conditional — matches `c-amber` semantic meaning |
| Guard condition text | Amber italic | Belongs visually to the alt fragment |
| `par` fragment | Teal (`#E1F5EE` / `#0F6E56`) | Concurrent success path — matches `c-teal` semantic meaning |
| Alt branch dividers | Amber solid line | Continuity with the alt frame color |
| Par branch divider | Teal dashed line | UML spec: par branches separated by dashed lines |
## Layout Notes
- **ViewBox**: 680×648 (standard width; height = lifeline bottom y=590 + legend + annotation + 16px buffer)
- **Lifeline spacing formula**: `(safe_area_width) / (n_lifelines − 1) = 600 / 5 = 120px` — but use `spacing = 100px` starting at `x=90` so that first box left = 40 and last box right = 640 exactly
- **Actor box split-label trick**: Two separate `<text>` elements per box — one for `":"` (10px, tertiary color) and one for the class name (11.5px bold, primary color) — avoids the 14px font needing ~150px+ per box for long names like "OrderController"
- **Pentagon tag formula**: For a fragment starting at `(fx, fy)`, the tag polygon points are `(fx,fy) (fx+w,fy) (fx+w+6,fy+6) (fx+w+6,fy+18) (fx,fy+18)` where `w` = approximate text width of the keyword + 8px padding each side
- **Nested fragment inset**: The `par` rect uses `x = alt_x + 15` and `y = alt_y_current + 2` so both borders remain simultaneously visible — inset enough to separate visually, not so much that it wastes vertical space
- **Activation bar placement**: `x = lifeline_cx − 4`, `width = 8` — centered on the lifeline and narrow enough not to obscure the dashed stem behind it
- **Message label y-offset**: All labels are placed at `y = arrow_y − 5` to sit just above the arrow line; this applies to both left-going and right-going arrows since `text-anchor="middle"` handles horizontal centering automatically
- **Return arrows entering activation bars**: End `x1/x2` at lifeline center (e.g. x=294 for OrderController) rather than the bar edge (x=286) — the small overlap is intentional and clarifies the target object
- **Alt guard label placement**: Branch 1 guard goes at `y = frame_top + 13` to the right of the pentagon tag; subsequent branch guards go at `divider_y + 14` so they sit just inside the new branch
- **Lifeline end cap pattern**: `<line x1="cx−7" y1="590" x2="cx+7" y2="590" stroke-width="1.5"/>` — a simple symmetric tick, no special marker needed

173
optional-skills/creative/concept-diagrams/examples/smart-city-infrastructure.md
View file

@ -1,173 +0,0 @@
# Smart City Infrastructure
A multi-system integration diagram showing interconnected city infrastructure (power, water, transport) connected through a central IoT platform with a citizen dashboard on top. Demonstrates hub-spoke layout, diverse physical shapes, and UI mockups.
## Key Patterns Used
- **Hub-spoke layout**: Central IoT platform with radiating data connections to subsystems
- **Connection dots**: Visual indicators where data lines attach to the central hub
- **Dashboard/UI mockup**: Screen with mini-charts, gauges, and status indicators
- **Multi-system integration**: Three independent systems unified by central platform
- **Semantic line styles**: Different stroke styles for data (dashed), power, water, roads
- **Physical infrastructure shapes**: Solar panels, wind turbines, dams, pipes, roads, vehicles
## New Shape Techniques
### Solar Panels (angled polygons with grid lines)
```xml
<polygon class="solar-panel" points="0,25 35,8 38,12 3,29"/>
<line class="solar-frame" x1="12" y1="22" x2="24" y2="13"/>
<line x1="19" y1="29" x2="19" y2="40" stroke="#5F5E5A" stroke-width="2"/>
```
### Wind Turbine (tower + nacelle + blades)
```xml
<!-- Tapered tower -->
<polygon class="wind-tower" points="20,70 30,70 28,25 22,25"/>
<!-- Nacelle -->
<rect class="wind-hub" x="18" y="20" width="14" height="8" rx="2"/>
<!-- Hub -->
<circle class="wind-hub" cx="25" cy="18" r="5"/>
<!-- Blades (rotated ellipses) -->
<ellipse class="wind-blade" cx="25" cy="5" rx="3" ry="13"/>
<ellipse class="wind-blade" cx="14" cy="26" rx="3" ry="13" transform="rotate(-120, 25, 18)"/>
<ellipse class="wind-blade" cx="36" cy="26" rx="3" ry="13" transform="rotate(120, 25, 18)"/>
```
### Battery with Charge Level
```xml
<rect class="battery" x="0" y="0" width="45" height="65" rx="5"/>
<!-- Terminals -->
<rect x="10" y="-6" width="10" height="8" rx="2" fill="#27500A"/>
<rect x="25" y="-6" width="10" height="8" rx="2" fill="#27500A"/>
<!-- Charge level fill -->
<rect class="battery-level" x="5" y="12" width="35" height="48" rx="3"/>
<text x="22" y="42" text-anchor="middle" fill="#173404" style="font-size:10px">85%</text>
```
### Dam/Reservoir with Water Waves
```xml
<!-- Dam wall -->
<polygon class="reservoir-wall" points="0,60 10,0 70,0 80,60"/>
<!-- Water behind dam -->
<polygon class="water" points="12,10 68,10 68,55 75,55 75,58 5,58 5,55 12,55"/>
<!-- Wave effect -->
<path d="M 15 25 Q 25 22 35 25 Q 45 28 55 25" fill="none" stroke="#378ADD" stroke-width="1" opacity="0.5"/>
```
### Pipe Network with Joints and Valves
```xml
<path class="pipe" d="M 80 85 L 110 85"/>
<circle class="pipe-joint" cx="10" cy="30" r="8"/>
<circle class="valve" cx="190" cy="85" r="6"/>
<!-- Distribution branches -->
<path class="pipe-thin" d="M 18 30 L 50 30"/>
<path class="pipe-thin" d="M 10 22 L 10 5 L 50 5"/>
```
### Road Intersection with Lane Markings
```xml
<!-- Road surface -->
<line class="road" x1="0" y1="50" x2="170" y2="50"/>
<line class="road-mark" x1="10" y1="50" x2="160" y2="50"/>
<!-- Cross road -->
<line class="road" x1="85" y1="0" x2="85" y2="100"/>
<line class="road-mark" x1="85" y1="10" x2="85" y2="90"/>
<!-- Embedded sensors -->
<circle class="sensor" cx="40" cy="50" r="5"/>
```
### Traffic Light with Signal States
```xml
<rect class="traffic-light" x="0" y="0" width="14" height="32" rx="3"/>
<circle class="light-red" cx="7" cy="8" r="4"/>
<circle class="light-off" cx="7" cy="16" r="4"/>
<circle class="light-off" cx="7" cy="24" r="4"/>
```
### Bus with Windows and Wheels
```xml
<rect class="bus" x="0" y="0" width="55" height="28" rx="6"/>
<!-- Windows -->
<rect class="bus-window" x="5" y="5" width="12" height="12" rx="2"/>
<rect class="bus-window" x="20" y="5" width="12" height="12" rx="2"/>
<!-- Wheels with hubcaps -->
<circle cx="14" cy="30" r="6" fill="#2C2C2A"/>
<circle cx="14" cy="30" r="3" fill="#5F5E5A"/>
```
### Dashboard UI Mockup
```xml
<!-- Monitor frame -->
<rect class="dashboard" x="0" y="0" width="200" height="120" rx="8"/>
<!-- Screen -->
<rect class="screen" x="10" y="10" width="180" height="85" rx="4"/>
<!-- Mini bar chart -->
<rect class="screen-content" x="18" y="18" width="50" height="35" rx="2"/>
<rect class="screen-chart" x="22" y="38" width="8" height="12"/>
<rect class="screen-chart" x="33" y="32" width="8" height="18"/>
<!-- Gauge -->
<circle class="screen-bar" cx="100" cy="35" r="12"/>
<text x="100" y="39" text-anchor="middle" fill="#E8E6DE" style="font-size:8px">78%</text>
<!-- Status indicators -->
<circle cx="35" cy="74" r="6" fill="#97C459"/>
<circle cx="75" cy="74" r="6" fill="#97C459"/>
<circle cx="115" cy="74" r="6" fill="#EF9F27"/>
```
### Hexagonal IoT Hub with Connection Points
```xml
<!-- Outer hexagon -->
<polygon class="iot-hex" points="0,-45 39,-22 39,22 0,45 -39,22 -39,-22"/>
<!-- Inner hexagon -->
<polygon class="iot-inner" points="0,-20 17,-10 17,10 0,20 -17,10 -17,-10"/>
<!-- Connection dots on data lines -->
<circle cx="321" cy="248" r="4" fill="#7F77DD"/>
```
## CSS Classes for Infrastructure
```css
/* Power system */
.solar-panel { fill: #3C3489; stroke: #534AB7; stroke-width: 0.5; }
.solar-frame { fill: none; stroke: #EEEDFE; stroke-width: 0.5; }
.wind-tower { fill: #B4B2A9; stroke: #5F5E5A; stroke-width: 1; }
.wind-blade { fill: #F1EFE8; stroke: #888780; stroke-width: 0.5; }
.battery { fill: #27500A; stroke: #3B6D11; stroke-width: 1.5; }
.battery-level { fill: #97C459; }
.power-line { stroke: #EF9F27; stroke-width: 2; fill: none; }
/* Water system */
.reservoir-wall { fill: #B4B2A9; stroke: #5F5E5A; stroke-width: 1; }
.water { fill: #85B7EB; stroke: #378ADD; stroke-width: 0.5; }
.pipe { fill: none; stroke: #378ADD; stroke-width: 4; stroke-linecap: round; }
.pipe-joint { fill: #185FA5; stroke: #0C447C; stroke-width: 1; }
.valve { fill: #0C447C; stroke: #185FA5; stroke-width: 1; }
/* Transport */
.road { stroke: #888780; stroke-width: 8; fill: none; stroke-linecap: round; }
.road-mark { stroke: #F1EFE8; stroke-width: 1; fill: none; stroke-dasharray: 6 4; }
.traffic-light { fill: #444441; stroke: #2C2C2A; stroke-width: 0.5; }
.light-red { fill: #E24B4A; }
.light-green { fill: #97C459; }
.light-off { fill: #2C2C2A; }
.bus { fill: #E1F5EE; stroke: #0F6E56; stroke-width: 1.5; }
/* Data/IoT */
.data-line { stroke: #7F77DD; stroke-width: 2; fill: none; stroke-dasharray: 4 3; }
.iot-hex { fill: #EEEDFE; stroke: #534AB7; stroke-width: 2; }
/* Dashboard */
.dashboard { fill: #F1EFE8; stroke: #5F5E5A; stroke-width: 1.5; }
.screen { fill: #1a1a18; }
.screen-chart { fill: #5DCAA5; }
```
## Layout Notes
- **ViewBox**: 720×620 (wider for three-column system layout)
- **Hub position**: Central IoT at (360, 270) - geometric center
- **Data lines**: Use quadratic curves or L-shaped paths, add connection dots at hub attachment points
- **System spacing**: ~200px width per system section
- **Vertical layers**: Dashboard (top) → IoT Hub (middle) → Systems (bottom)
- **Component grouping**: Use `<g transform="translate(x,y)">` for each major component for easy positioning

154
optional-skills/creative/concept-diagrams/examples/smartphone-layer-anatomy.md
View file

@ -1,154 +0,0 @@
# Smartphone Layer Anatomy
An exploded view diagram showing all internal layers of a smartphone from front glass to back, with alternating left/right labels to avoid overlap. Demonstrates layered product teardown visualization and component detail.
## Key Patterns Used
- **Exploded vertical stack**: Layers separated vertically to show internal structure
- **Alternating labels**: Left/right label placement prevents text overlap
- **Component detail**: Chips, coils, lenses rendered with realistic shapes
- **Thickness scale**: Measurement indicator on the side
- **Progressive depth**: Each layer slightly offset to create 3D stack effect
## New Shape Techniques
### Capacitive Touch Grid
```xml
<rect class="digitizer" x="0" y="0" width="140" height="90" rx="14"/>
<g transform="translate(8, 8)">
<!-- Horizontal lines -->
<line class="digitizer-grid" x1="0" y1="15" x2="124" y2="15"/>
<line class="digitizer-grid" x1="0" y1="37" x2="124" y2="37"/>
<!-- Vertical lines -->
<line class="digitizer-grid" x1="20" y1="0" x2="20" y2="74"/>
<line class="digitizer-grid" x1="50" y1="0" x2="50" y2="74"/>
</g>
<!-- Touch point indicator -->
<circle cx="70" cy="45" r="12" fill="none" stroke="#7F77DD" stroke-width="2" opacity="0.6"/>
<circle cx="70" cy="45" r="5" fill="#7F77DD" opacity="0.4"/>
```
### OLED RGB Subpixels
```xml
<rect class="oled-panel" x="0" y="0" width="140" height="90" rx="12"/>
<g transform="translate(10, 10)">
<!-- RGB pixel group -->
<rect class="oled-subpixel-r" x="0" y="0" width="2" height="6"/>
<rect class="oled-subpixel-g" x="3" y="0" width="2" height="6"/>
<rect class="oled-subpixel-b" x="6" y="0" width="2" height="6"/>
<!-- Repeat pattern -->
<rect class="oled-subpixel-r" x="11" y="0" width="2" height="6"/>
<rect class="oled-subpixel-g" x="14" y="0" width="2" height="6"/>
<rect class="oled-subpixel-b" x="17" y="0" width="2" height="6"/>
</g>
```
### Logic Board with Chips
```xml
<rect class="pcb" x="0" y="0" width="116" height="106" rx="3"/>
<!-- PCB traces -->
<path class="pcb-trace" d="M 8 50 L 30 50 L 30 35"/>
<!-- CPU chip -->
<rect class="chip-cpu" x="30" y="20" width="55" height="35" rx="3"/>
<text class="chip-label" x="57" y="35" text-anchor="middle">A17 Pro</text>
<!-- RAM chip -->
<rect class="chip-ram" x="30" y="62" width="35" height="18" rx="2"/>
<text class="chip-label" x="47" y="74" text-anchor="middle">8GB RAM</text>
<!-- Storage chip -->
<rect class="chip-storage" x="30" y="85" width="55" height="16" rx="2"/>
<text class="chip-label" x="57" y="96" text-anchor="middle">256GB NAND</text>
```
### Camera Lens Array
```xml
<!-- Main camera -->
<circle class="camera-lens" cx="20" cy="20" r="18"/>
<circle class="camera-lens-inner" cx="20" cy="20" r="13"/>
<circle class="camera-sensor" cx="20" cy="20" r="8"/>
<circle cx="20" cy="20" r="3" fill="#1a1a18"/>
<!-- Secondary camera (smaller) -->
<circle class="camera-lens" cx="15" cy="15" r="13"/>
<circle class="camera-lens-inner" cx="15" cy="15" r="9"/>
<circle class="camera-sensor" cx="15" cy="15" r="5"/>
```
### Wireless Charging Coil with Magnets
```xml
<!-- Concentric coil rings -->
<circle class="charging-coil-outer" cx="0" cy="0" r="30"/>
<circle class="charging-coil" cx="0" cy="0" r="23"/>
<circle class="charging-coil" cx="0" cy="0" r="16"/>
<circle class="charging-coil" cx="0" cy="0" r="9"/>
<!-- MagSafe magnet ring -->
<circle class="magnet" cx="0" cy="-35" r="3"/>
<circle class="magnet" cx="25" cy="-25" r="3"/>
<circle class="magnet" cx="35" cy="0" r="3"/>
<circle class="magnet" cx="25" cy="25" r="3"/>
<!-- ... continue around circle -->
```
### Battery Cell
```xml
<rect class="battery" x="0" y="0" width="140" height="90" rx="10"/>
<rect class="battery-cell" x="10" y="12" width="120" height="60" rx="6"/>
<text x="70" y="38" text-anchor="middle" fill="#27500A" style="font-size:9px">Li-Ion Polymer</text>
<text x="70" y="52" text-anchor="middle" fill="#27500A" style="font-size:12px; font-weight:bold">4422 mAh</text>
<rect class="battery-connector" x="55" y="75" width="30" height="10" rx="2"/>
```
## CSS Classes
```css
/* Glass */
.front-glass { fill: #E8E6DE; stroke: #888780; stroke-width: 1; opacity: 0.9; }
.back-glass { fill: #2C2C2A; stroke: #444441; stroke-width: 1; }
/* Touch digitizer */
.digitizer { fill: #EEEDFE; stroke: #534AB7; stroke-width: 1; }
.digitizer-grid { stroke: #AFA9EC; stroke-width: 0.3; fill: none; }
/* OLED */
.oled-panel { fill: #1a1a18; stroke: #444441; stroke-width: 1; }
.oled-subpixel-r { fill: #E24B4A; }
.oled-subpixel-g { fill: #97C459; }
.oled-subpixel-b { fill: #378ADD; }
/* Midframe */
.midframe { fill: #B4B2A9; stroke: #5F5E5A; stroke-width: 1.5; }
/* Logic board */
.pcb { fill: #0F6E56; stroke: #085041; stroke-width: 1; }
.pcb-trace { stroke: #5DCAA5; stroke-width: 0.3; fill: none; }
.chip-cpu { fill: #3C3489; stroke: #534AB7; stroke-width: 0.5; }
.chip-ram { fill: #185FA5; stroke: #378ADD; stroke-width: 0.5; }
.chip-storage { fill: #27500A; stroke: #3B6D11; stroke-width: 0.5; }
/* Battery */
.battery { fill: #EAF3DE; stroke: #3B6D11; stroke-width: 1.5; }
.battery-cell { fill: #97C459; stroke: #639922; stroke-width: 0.5; }
/* Camera */
.camera-lens { fill: #0C447C; stroke: #185FA5; stroke-width: 0.5; }
.camera-lens-inner { fill: #1a1a18; stroke: #378ADD; stroke-width: 0.3; }
.camera-sensor { fill: #3C3489; stroke: #534AB7; stroke-width: 0.3; }
/* Wireless charging */
.charging-coil { fill: none; stroke: #EF9F27; stroke-width: 1.5; }
.magnet { fill: #5F5E5A; stroke: #444441; stroke-width: 0.5; }
```
## Layout Notes
- **ViewBox**: 900×780 (tall for vertical stack)
- **Layer offset**: Each layer offset 10px right and down for depth effect
- **Label alternation**: Odd layers → RIGHT labels, Even layers → LEFT labels
- **Thickness scale**: Vertical measurement bar on left side
- **Front/Back markers**: Text labels at top and bottom
- **Chip labels**: Use small white text (6px) directly on chip shapes

247
optional-skills/creative/concept-diagrams/examples/sn2-reaction-mechanism.md
View file

@ -1,247 +0,0 @@
# SN2 Reaction Mechanism
A chemistry diagram showing the bimolecular nucleophilic substitution (SN2) mechanism between hydroxide ion and methyl bromide. Demonstrates molecular structure rendering, electron movement arrows, transition state notation, and reaction energy profiles.
## Key Patterns Used
- **Molecular structures**: Ball-and-stick style atoms with bonds
- **Electron movement**: Curved arrows showing nucleophilic attack
- **Transition state**: Bracketed pentacoordinate intermediate with partial charges
- **Stereochemistry**: Wedge/dash bonds showing 3D configuration
- **Energy profile**: Potential energy vs reaction coordinate plot
- **Annotation boxes**: Key features and mechanistic notes
## Diagram Type
This is a **chemistry mechanism diagram** with:
- **Molecular rendering**: Atoms as colored circles with element symbols
- **Bond notation**: Solid, wedge, dash, and partial (dashed) bonds
- **Reaction arrows**: Curved for electron movement, straight for reaction progress
- **Energy landscape**: Quantitative energy profile below mechanism
## Molecular Structure Elements
### Atom Rendering
```xml
<!-- Carbon atom (dark) -->
<circle cx="0" cy="0" r="14" class="carbon"/>
<text class="chem" x="0" y="5" text-anchor="middle" fill="white" font-weight="500">C</text>
<!-- Oxygen atom (red) -->
<circle cx="0" cy="0" r="14" class="oxygen"/>
<text class="chem" x="0" y="5" text-anchor="middle" fill="white" font-weight="500">O</text>
<!-- Hydrogen atom (light with border) -->
<circle cx="38" cy="0" r="8" class="hydrogen"/>
<text class="chem-sm" x="38" y="4" text-anchor="middle">H</text>
<!-- Bromine atom (brown) -->
<circle cx="52" cy="0" r="16" class="bromine"/>
<text class="chem" x="52" y="5" text-anchor="middle" fill="white" font-weight="500">Br</text>
```
```css
.carbon { fill: #2C2C2A; }
.hydrogen { fill: #F1EFE8; stroke: #888780; stroke-width: 1; }
.oxygen { fill: #E24B4A; }
.bromine { fill: #993C1D; }
.nitrogen { fill: #378ADD; } /* for other reactions */
```
### Bond Types
```xml
<!-- Single bond (solid) -->
<line x1="14" y1="0" x2="38" y2="0" class="bond"/>
<!-- Wedge bond (coming toward viewer) -->
<polygon class="bond-wedge" points="0,-14 -6,-35 6,-35"/>
<!-- Dash bond (going away from viewer) -->
<line x1="-10" y1="10" x2="-28" y2="28" class="bond-dash"/>
<!-- Partial bond (forming/breaking) -->
<line x1="-40" y1="0" x2="-14" y2="0" class="bond-partial"/>
```
```css
.bond { stroke: var(--text-primary); stroke-width: 2.5; fill: none; stroke-linecap: round; }
.bond-thin { stroke: var(--text-primary); stroke-width: 1.5; fill: none; }
.bond-partial { stroke: var(--text-primary); stroke-width: 2; fill: none; stroke-dasharray: 4 3; }
.bond-wedge { fill: var(--text-primary); stroke: none; }
.bond-dash { stroke: var(--text-primary); stroke-width: 2; fill: none; stroke-dasharray: 2 2; }
```
### Lone Pairs and Charges
```xml
<!-- Lone pair electrons (dots) -->
<circle cx="-8" cy="-18" r="2" fill="var(--text-primary)"/>
<circle cx="0" cy="-18" r="2" fill="var(--text-primary)"/>
<!-- Formal negative charge -->
<text class="charge" x="12" y="-12" fill="#A32D2D" font-weight="bold">⊖</text>
<!-- Partial charges (delta notation) -->
<text class="partial" x="0" y="-18" text-anchor="middle" fill="#A32D2D">δ⁻</text>
<text class="partial" x="0" y="-22" text-anchor="middle" fill="#3B6D11">δ⁺</text>
```
```css
.charge { font-family: "Times New Roman", Georgia, serif; font-size: 12px; }
.partial { font-family: "Times New Roman", Georgia, serif; font-size: 11px; font-style: italic; }
```
### Curved Arrow (Electron Movement)
```xml
<defs>
<marker id="curved-arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto">
<path d="M0,0 L10,5 L0,10 L3,5 Z" class="arrow-fill"/>
</marker>
</defs>
<!-- Nucleophilic attack arrow -->
<path d="M -5,15 Q 30,60 70,25" class="arrow-curved" marker-end="url(#curved-arrow)"/>
```
```css
.arrow-curved { stroke: #534AB7; stroke-width: 2; fill: none; }
.arrow-fill { fill: #534AB7; }
```
### Transition State Brackets
```xml
<!-- Left bracket -->
<path d="M -75,-70 L -85,-70 L -85,75 L -75,75" class="ts-bracket"/>
<!-- Right bracket -->
<path d="M 95,-70 L 105,-70 L 105,75 L 95,75" class="ts-bracket"/>
<!-- Double dagger symbol -->
<text class="chem" x="115" y="-60" fill="var(--text-primary)">‡</text>
```
```css
.ts-bracket { stroke: var(--text-primary); stroke-width: 1.5; fill: none; }
```
## Energy Profile Diagram
### Axes
```xml
<!-- Y-axis (Energy) -->
<line x1="0" y1="280" x2="0" y2="0" class="axis" marker-end="url(#straight-arrow)"/>
<text class="t" x="-15" y="-10" text-anchor="middle" transform="rotate(-90 -15 140)">Potential Energy</text>
<!-- X-axis (Reaction Coordinate) -->
<line x1="0" y1="280" x2="600" y2="280" class="axis" marker-end="url(#straight-arrow)"/>
<text class="t" x="580" y="305" text-anchor="middle">Reaction Coordinate</text>
```
### Energy Curve
```xml
<!-- Filled area under curve -->
<path class="energy-fill" d="
M 40,200
Q 150,200 250,50
Q 350,200 500,220
L 500,280 L 40,280 Z
"/>
<!-- Curve line -->
<path class="energy-curve" d="
M 40,200
Q 100,200 150,150
Q 200,80 250,50
Q 300,80 350,150
Q 400,210 500,220
"/>
```
```css
.energy-curve { stroke: #534AB7; stroke-width: 2.5; fill: none; }
.energy-fill { fill: rgba(83, 74, 183, 0.1); }
```
### Energy Levels and Annotations
```xml
<!-- Reactants level -->
<line x1="20" y1="200" x2="80" y2="200" stroke="#3B6D11" stroke-width="2"/>
<text class="ts" x="50" y="218" text-anchor="middle">Reactants</text>
<!-- Transition state peak -->
<circle cx="250" cy="50" r="5" fill="#534AB7"/>
<line x1="250" y1="50" x2="250" y2="280" class="energy-level"/>
<text class="ts" x="250" y="30" text-anchor="middle" fill="#534AB7" font-weight="500">Transition State [‡]</text>
<!-- Products level (lower = exergonic) -->
<line x1="470" y1="220" x2="530" y2="220" stroke="#3B6D11" stroke-width="2"/>
<!-- Activation energy arrow -->
<line x1="100" y1="200" x2="100" y2="55" class="delta-arrow" marker-end="url(#delta-arrow)"/>
<text class="ts" x="85" y="125" text-anchor="end" fill="#3B6D11">E<tspan baseline-shift="sub" font-size="8">a</tspan></text>
```
```css
.energy-level { stroke: var(--text-secondary); stroke-width: 1; stroke-dasharray: 4 2; fill: none; }
.delta-arrow { stroke: #3B6D11; stroke-width: 1.5; fill: none; }
.delta-fill { fill: #3B6D11; }
```
## Chemistry Text Styles
```css
/* Chemistry notation (serif font for formulas) */
.chem { font-family: "Times New Roman", Georgia, serif; font-size: 16px; fill: var(--text-primary); }
.chem-sm { font-family: "Times New Roman", Georgia, serif; font-size: 12px; fill: var(--text-primary); }
.chem-lg { font-family: "Times New Roman", Georgia, serif; font-size: 18px; fill: var(--text-primary); }
```
## Subscript/Superscript in SVG
```xml
<!-- Subscript using tspan -->
<text class="ts">E<tspan baseline-shift="sub" font-size="8">a</tspan></text>
<!-- Superscript for charges -->
<text class="chem-sm">OH⁻</text> <!-- Using Unicode superscript minus -->
<text class="chem-sm">CH₃Br</text> <!-- Using Unicode subscript 3 -->
```
## Color Coding
| Element | Color | Hex |
|---------|-------|-----|
| Carbon | Dark gray | #2C2C2A |
| Hydrogen | Light cream | #F1EFE8 |
| Oxygen | Red | #E24B4A |
| Bromine | Brown | #993C1D |
| Nitrogen | Blue | #378ADD |
| Electron arrows | Purple | #534AB7 |
| Positive charge | Green | #3B6D11 |
| Negative charge | Red | #A32D2D |
## Layout Notes
- **ViewBox**: 800×680 (landscape for mechanism + energy profile)
- **Mechanism section**: y=60-300, showing reactants → TS → products
- **Energy profile**: y=320-630, with axes and curve
- **Atom sizes**: C/O/Br ~12-16px radius, H ~7-8px radius
- **Bond lengths**: ~25-40px between atom centers
- **Spacing**: ~140px between mechanism stages
## When to Use This Pattern
Use this diagram style for:
- Organic reaction mechanisms (SN1, SN2, E1, E2, additions, eliminations)
- Reaction energy profiles and kinetics
- Stereochemistry illustrations
- Enzyme mechanism diagrams
- Transition state theory visualization
- Any chemistry concept requiring molecular structures

338
optional-skills/creative/concept-diagrams/examples/wind-turbine-structure.md
View file

@ -1,338 +0,0 @@
# Modern Onshore Wind Turbine Structure
A physical/structural cross-section diagram showing all major components of a modern wind turbine from underground foundation to blade tips.
## Key Patterns Used
- **Underground section**: Soil layers, deep concrete foundation with rebar reinforcement grid, spread footing
- **Cross-section view**: Tower wall thickness shown, internal components visible
- **Tapered tower**: Path elements creating realistic tower silhouette that narrows toward top
- **Internal access**: Ladder with rungs, elevator shaft inside tower
- **Cable routing**: Power cables running from nacelle down through tower to transformer
- **Nacelle cutaway**: Gearbox, generator, brake, yaw system all visible inside housing
- **Rotor assembly**: Hub with pitch motors at blade roots, three composite blades with gradient fill
- **Ground level marker**: Clear separation between above/below ground
- **Component color coding**: Each system type has distinct color (blue=generator, gold=gearbox, red=brake, green=yaw, purple=pitch)
- **Legend bar**: Quick reference for color meanings
## Diagram
```xml
<svg width="100%" viewBox="0 0 680 920" xmlns="http://www.w3.org/2000/svg">
<defs>
<marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5"
markerWidth="6" markerHeight="6" orient="auto-start-reverse">
<path d="M2 1L8 5L2 9" fill="none" stroke="context-stroke"
stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
</marker>
<!-- Blade gradient for 3D effect -->
<linearGradient id="bladeGrad" x1="0%" y1="0%" x2="100%" y2="0%">
<stop offset="0%" style="stop-color:#D3D1C7"/>
<stop offset="50%" style="stop-color:#F1EFE8"/>
<stop offset="100%" style="stop-color:#B4B2A9"/>
</linearGradient>
</defs>
<!-- ===== GROUND LEVEL LINE ===== -->
<line x1="40" y1="680" x2="640" y2="680" stroke="#3B6D11" stroke-width="2"/>
<text class="tl" x="45" y="675">Ground level</text>
<!-- ===== UNDERGROUND: FOUNDATION ===== -->
<!-- Soil layers -->
<rect x="120" y="680" width="300" height="180" class="soil"/>
<rect x="120" y="780" width="300" height="80" class="soil-dark"/>
<!-- Deep concrete foundation -->
<path d="M170 680 L170 820 L200 850 L340 850 L370 820 L370 680 Z" class="concrete"/>
<!-- Foundation base spread -->
<path d="M140 820 L170 820 L200 850 L340 850 L370 820 L400 820 L400 860 L140 860 Z" class="concrete-dark"/>
<!-- Rebar reinforcement -->
<g class="rebar">
<line x1="185" y1="700" x2="185" y2="840"/>
<line x1="210" y1="700" x2="210" y2="845"/>
<line x1="235" y1="700" x2="235" y2="848"/>
<line x1="260" y1="700" x2="260" y2="848"/>
<line x1="285" y1="700" x2="285" y2="848"/>
<line x1="310" y1="700" x2="310" y2="845"/>
<line x1="335" y1="700" x2="335" y2="840"/>
<!-- Horizontal rebar -->
<line x1="175" y1="720" x2="365" y2="720"/>
<line x1="175" y1="760" x2="365" y2="760"/>
<line x1="175" y1="800" x2="365" y2="800"/>
<line x1="155" y1="835" x2="385" y2="835"/>
</g>
<!-- Foundation labels -->
<line x1="410" y1="770" x2="480" y2="770" class="leader"/>
<text class="ts" x="485" y="766">Deep concrete foundation</text>
<text class="tl" x="485" y="778">Reinforced with steel rebar</text>
<text class="tl" x="485" y="790">15-25m deep typical</text>
<line x1="400" y1="850" x2="480" y2="870" class="leader"/>
<text class="ts" x="485" y="866">Foundation spread footing</text>
<text class="tl" x="485" y="878">Distributes load to soil</text>
<!-- ===== TOWER BASE ===== -->
<!-- Tower base flange -->
<ellipse cx="270" cy="680" rx="70" ry="12" class="concrete-dark"/>
<rect x="200" y="668" width="140" height="12" class="tower"/>
<!-- Transformer at base -->
<g transform="translate(470, 640)">
<rect x="0" y="0" width="50" height="40" rx="3" class="transformer"/>
<!-- Cooling fins -->
<rect x="52" y="5" width="4" height="30" class="transformer-fin"/>
<rect x="58" y="5" width="4" height="30" class="transformer-fin"/>
<rect x="64" y="5" width="4" height="30" class="transformer-fin"/>
<!-- Connection box -->
<rect x="10" y="-8" width="30" height="10" rx="2" class="transformer-fin"/>
</g>
<line x1="470" y1="660" x2="430" y2="640" class="leader"/>
<text class="ts" x="385" y="636" text-anchor="end">Transformer</text>
<text class="tl" x="385" y="648" text-anchor="end">Steps up voltage for grid</text>
<!-- ===== TUBULAR STEEL TOWER ===== -->
<!-- Tower outer shell (tapered) -->
<path d="M200 680 L220 200 L320 200 L340 680 Z" class="tower"/>
<!-- Tower inner surface (cutaway) -->
<path d="M215 680 L232 210 L308 210 L325 680 Z" class="tower-inner"/>
<!-- Tower section joints -->
<line x1="205" y1="550" x2="335" y2="550" class="tower-section"/>
<line x1="210" y1="420" x2="330" y2="420" class="tower-section"/>
<line x1="215" y1="300" x2="325" y2="300" class="tower-section"/>
<!-- Internal ladder (left side) -->
<g transform="translate(225, 220)">
<!-- Ladder rails -->
<line x1="0" y1="0" x2="8" y2="450" class="ladder"/>
<line x1="15" y1="0" x2="23" y2="450" class="ladder"/>
<!-- Rungs -->
<g class="ladder-rung">
<line x1="1" y1="20" x2="22" y2="21"/>
<line x1="1" y1="50" x2="22" y2="52"/>
<line x1="2" y1="80" x2="22" y2="83"/>
<line x1="2" y1="110" x2="23" y2="114"/>
<line x1="2" y1="140" x2="23" y2="145"/>
<line x1="3" y1="170" x2="23" y2="176"/>
<line x1="3" y1="200" x2="24" y2="207"/>
<line x1="3" y1="230" x2="24" y2="238"/>
<line x1="4" y1="260" x2="24" y2="269"/>
<line x1="4" y1="290" x2="25" y2="300"/>
<line x1="4" y1="320" x2="25" y2="331"/>
<line x1="5" y1="350" x2="25" y2="362"/>
<line x1="5" y1="380" x2="26" y2="393"/>
<line x1="6" y1="410" x2="26" y2="424"/>
<line x1="6" y1="440" x2="27" y2="455"/>
</g>
</g>
<!-- Elevator shaft (right side) -->
<rect x="280" y="230" width="25" height="430" rx="2" class="elevator"/>
<text class="tl" x="292" y="450" text-anchor="middle" transform="rotate(-90, 292, 450)" fill="#185FA5">ELEVATOR</text>
<!-- Electrical cables running down -->
<path d="M270 220 C270 300 268 400 268 500 C268 600 268 650 310 665 L470 665" class="cable"/>
<path d="M260 225 C258 350 256 500 256 600 C256 650 256 670 256 680" class="cable-thin"/>
<!-- Tower labels -->
<line x1="340" y1="350" x2="400" y2="320" class="leader"/>
<text class="ts" x="405" y="316">Tubular steel tower</text>
<text class="tl" x="405" y="328">80-120m height typical</text>
<text class="tl" x="405" y="340">Tapered for strength</text>
<line x1="248" y1="400" x2="130" y2="380" class="leader"/>
<text class="ts" x="125" y="376" text-anchor="end">Internal ladder</text>
<text class="tl" x="125" y="388" text-anchor="end">Service access</text>
<line x1="305" y1="500" x2="400" y2="520" class="leader"/>
<text class="ts" x="405" y="516">Service elevator</text>
<line x1="268" y1="580" x2="130" y2="600" class="leader"/>
<text class="ts" x="125" y="596" text-anchor="end">Power cables</text>
<text class="tl" x="125" y="608" text-anchor="end">To transformer</text>
<!-- ===== NACELLE ===== -->
<g transform="translate(270, 160)">
<!-- Nacelle base/bedplate -->
<rect x="-60" y="30" width="120" height="15" class="nacelle"/>
<!-- Yaw bearing -->
<ellipse cx="0" cy="42" rx="35" ry="6" class="bearing"/>
<!-- Yaw motors -->
<rect x="-55" y="32" width="12" height="18" rx="2" class="yaw"/>
<rect x="43" y="32" width="12" height="18" rx="2" class="yaw"/>
<!-- Nacelle housing -->
<path d="M-65 30 L-70 -10 L-65 -35 L70 -35 L85 -10 L85 30 Z" class="nacelle-cover"/>
<!-- Main shaft -->
<rect x="-90" y="-8" width="35" height="16" rx="2" fill="#888780" stroke="#5F5E5A" stroke-width="0.5"/>
<!-- Gearbox -->
<rect x="-55" y="-25" width="40" height="45" rx="3" class="gearbox"/>
<text class="tl" x="-35" y="5" text-anchor="middle" fill="#633806">GEAR</text>
<!-- Generator -->
<rect x="-10" y="-20" width="50" height="38" rx="4" class="generator"/>
<ellipse cx="15" cy="0" rx="15" ry="15" fill="none" stroke="#0C447C" stroke-width="1"/>
<text class="tl" x="15" y="4" text-anchor="middle" fill="#E6F1FB">GEN</text>
<!-- Brake disc -->
<rect x="45" y="-12" width="8" height="24" rx="1" class="brake"/>
<!-- Electrical cabinet -->
<rect x="58" y="-25" width="20" height="35" rx="2" fill="#5F5E5A" stroke="#444441" stroke-width="0.5"/>
<!-- Anemometer on top -->
<line x1="60" y1="-35" x2="60" y2="-50" stroke="#5F5E5A" stroke-width="1"/>
<ellipse cx="60" cy="-52" rx="8" ry="3" fill="#D3D1C7" stroke="#888780" stroke-width="0.5"/>
</g>
<!-- Nacelle labels -->
<line x1="215" y1="135" x2="130" y2="115" class="leader"/>
<text class="ts" x="125" y="111" text-anchor="end">Gearbox</text>
<text class="tl" x="125" y="123" text-anchor="end">Speed multiplier</text>
<line x1="285" y1="145" x2="400" y2="125" class="leader"/>
<text class="ts" x="405" y="121">Generator</text>
<text class="tl" x="405" y="133">Converts rotation to electricity</text>
<line x1="315" y1="155" x2="400" y2="165" class="leader"/>
<text class="ts" x="405" y="161">Brake system</text>
<line x1="215" y1="200" x2="130" y2="220" class="leader"/>
<text class="ts" x="125" y="216" text-anchor="end">Yaw motors</text>
<text class="tl" x="125" y="228" text-anchor="end">Rotate nacelle to face wind</text>
<line x1="330" y1="108" x2="400" y2="90" class="leader"/>
<text class="ts" x="405" y="86">Anemometer</text>
<text class="tl" x="405" y="98">Wind speed sensor</text>
<!-- ===== ROTOR HUB & BLADES ===== -->
<!-- Hub -->
<g transform="translate(180, 152)">
<!-- Hub body -->
<ellipse cx="0" cy="0" rx="25" ry="30" class="hub"/>
<!-- Hub nose cone -->
<path d="M-25 -20 Q-50 0 -25 20 Q-30 0 -25 -20" class="hub-cap"/>
<!-- Blade roots with pitch motors -->
<!-- Blade 1 (up) -->
<g transform="translate(-10, -25) rotate(-80)">
<ellipse cx="0" cy="0" rx="12" ry="8" class="blade-root"/>
<rect x="-8" y="-5" width="10" height="10" rx="2" class="pitch-motor"/>
</g>
<!-- Blade 2 (lower left) -->
<g transform="translate(-18, 18) rotate(40)">
<ellipse cx="0" cy="0" rx="12" ry="8" class="blade-root"/>
<rect x="-8" y="-5" width="10" height="10" rx="2" class="pitch-motor"/>
</g>
<!-- Blade 3 (lower right) -->
<g transform="translate(5, 22) rotate(160)">
<ellipse cx="0" cy="0" rx="12" ry="8" class="blade-root"/>
<rect x="-8" y="-5" width="10" height="10" rx="2" class="pitch-motor"/>
</g>
</g>
<!-- Blade 1 (pointing up-left) -->
<path d="M165 125 Q140 80 130 40 Q125 20 115 15 Q110 18 112 25 Q115 50 125 90 Q140 120 158 128 Z" class="blade" fill="url(#bladeGrad)"/>
<!-- Blade 2 (pointing down-left) -->
<path d="M158 175 Q120 200 80 230 Q60 245 55 255 Q60 258 68 252 Q95 235 130 210 Q155 190 163 178 Z" class="blade" fill="url(#bladeGrad)"/>
<!-- Blade 3 (pointing down-right, partially visible) -->
<path d="M188 175 Q195 200 205 230 Q210 250 215 255 Q220 252 218 245 Q212 220 202 195 Q192 175 186 172 Z" class="blade" fill="url(#bladeGrad)"/>
<!-- Blade labels -->
<line x1="115" y1="35" x2="60" y2="35" class="leader"/>
<text class="ts" x="55" y="31" text-anchor="end">Composite blade</text>
<text class="tl" x="55" y="43" text-anchor="end">Fiberglass/carbon fiber</text>
<text class="tl" x="55" y="55" text-anchor="end">40-80m length each</text>
<line x1="170" y1="130" x2="130" y2="155" class="leader"/>
<text class="ts" x="85" y="151" text-anchor="end">Pitch motor</text>
<text class="tl" x="85" y="163" text-anchor="end">Adjusts blade angle</text>
<line x1="180" y1="152" x2="130" y2="180" class="leader"/>
<text class="ts" x="85" y="183" text-anchor="end">Rotor hub</text>
<!-- ===== LEGEND ===== -->
<g transform="translate(40, 895)">
<rect x="0" y="-15" width="600" height="30" rx="4" fill="none" stroke="#D3D1C7" stroke-width="0.5"/>
<rect x="15" y="-5" width="12" height="12" rx="2" class="generator"/>
<text class="tl" x="32" y="5">Generator</text>
<rect x="95" y="-5" width="12" height="12" rx="2" class="gearbox"/>
<text class="tl" x="112" y="5">Gearbox</text>
<rect x="170" y="-5" width="12" height="12" rx="2" class="brake"/>
<text class="tl" x="187" y="5">Brake</text>
<rect x="230" y="-5" width="12" height="12" rx="2" class="yaw"/>
<text class="tl" x="247" y="5">Yaw system</text>
<rect x="320" y="-5" width="12" height="12" rx="2" class="pitch-motor"/>
<text class="tl" x="337" y="5">Pitch motor</text>
<line x1="415" y1="1" x2="435" y2="1" class="cable" style="stroke-width:2"/>
<text class="tl" x="440" y="5">Power cable</text>
<rect x="515" y="-5" width="12" height="12" rx="2" class="transformer"/>
<text class="tl" x="532" y="5">Transformer</text>
</g>
</svg>
```
## CSS Classes
```css
/* Foundation */
.concrete { fill: #B4B2A9; stroke: #5F5E5A; stroke-width: 1; }
.concrete-dark { fill: #888780; stroke: #5F5E5A; stroke-width: 1; }
.rebar { stroke: #854F0B; stroke-width: 1.5; fill: none; }
.soil { fill: #8B7355; stroke: #5F5E5A; stroke-width: 0.5; }
.soil-dark { fill: #6B5344; }
/* Tower */
.tower { fill: #F1EFE8; stroke: #5F5E5A; stroke-width: 1; }
.tower-inner { fill: #D3D1C7; stroke: #888780; stroke-width: 0.5; }
.tower-section { stroke: #888780; stroke-width: 0.5; stroke-dasharray: 2 4; }
.ladder { stroke: #5F5E5A; stroke-width: 1; fill: none; }
.ladder-rung { stroke: #888780; stroke-width: 0.8; }
.elevator { fill: #E6F1FB; stroke: #185FA5; stroke-width: 0.5; }
.cable { stroke: #E24B4A; stroke-width: 2; fill: none; }
.cable-thin { stroke: #E24B4A; stroke-width: 1.5; fill: none; }
/* Nacelle */
.nacelle { fill: #F1EFE8; stroke: #5F5E5A; stroke-width: 1; }
.nacelle-cover { fill: #D3D1C7; stroke: #5F5E5A; stroke-width: 1; }
.gearbox { fill: #BA7517; stroke: #633806; stroke-width: 0.5; }
.generator { fill: #378ADD; stroke: #0C447C; stroke-width: 0.5; }
.brake { fill: #E24B4A; stroke: #791F1F; stroke-width: 0.5; }
.yaw { fill: #5DCAA5; stroke: #085041; stroke-width: 0.5; }
.bearing { fill: #444441; stroke: #2C2C2A; stroke-width: 0.5; }
/* Rotor */
.hub { fill: #D3D1C7; stroke: #5F5E5A; stroke-width: 1; }
.hub-cap { fill: #F1EFE8; stroke: #5F5E5A; stroke-width: 1; }
.blade { fill: #F1EFE8; stroke: #888780; stroke-width: 1; }
.blade-root { fill: #D3D1C7; stroke: #5F5E5A; stroke-width: 0.5; }
.pitch-motor { fill: #7F77DD; stroke: #3C3489; stroke-width: 0.5; }
/* Transformer */
.transformer { fill: #27500A; stroke: #173404; stroke-width: 1; }
.transformer-fin { fill: #3B6D11; stroke: #27500A; stroke-width: 0.5; }
```

43
optional-skills/creative/concept-diagrams/references/dashboard-patterns.md
View file

@ -1,43 +0,0 @@
# Dashboard Patterns
Building blocks for UI/dashboard mockups inside a concept diagram — admin panels, monitoring dashboards, control interfaces, status displays.
## Pattern
A "screen" is a rounded dark rect inside a lighter "frame" rect, with chart/gauge/indicator elements nested on top.
```xml
<!-- Monitor frame -->
<rect class="dashboard" x="0" y="0" width="200" height="120" rx="8"/>
<!-- Screen -->
<rect class="screen" x="10" y="10" width="180" height="85" rx="4"/>
<!-- Mini bar chart -->
<rect class="screen-content" x="18" y="18" width="50" height="35" rx="2"/>
<rect class="screen-chart" x="22" y="38" width="8" height="12"/>
<rect class="screen-chart" x="33" y="32" width="8" height="18"/>
<!-- Gauge -->
<circle class="screen-bar" cx="100" cy="35" r="12"/>
<text x="100" y="39" text-anchor="middle" fill="#E8E6DE" style="font-size:8px">78%</text>
<!-- Status indicators -->
<circle cx="35" cy="74" r="6" fill="#97C459"/> <!-- green = ok -->
<circle cx="75" cy="74" r="6" fill="#EF9F27"/> <!-- amber = warning -->
<circle cx="115" cy="74" r="6" fill="#E24B4A"/> <!-- red = alert -->
```
## CSS
```css
.dashboard { fill: #F1EFE8; stroke: #5F5E5A; stroke-width: 1.5; }
.screen { fill: #1a1a18; }
.screen-content { fill: #2C2C2A; }
.screen-chart { fill: #5DCAA5; }
.screen-bar { fill: #7F77DD; }
.screen-alert { fill: #E24B4A; }
```
## Tips
- Dashboard screens stay dark in both light and dark mode — they represent actual monitor glass.
- Keep on-screen text small (`font-size:8px` or `10px`) and high-contrast (near-white fill on dark).
- Use the status triad green/amber/red consistently — OK / warning / alert.
- A single dashboard usually sits on top of an infrastructure hub diagram as a unified view (see `examples/smart-city-infrastructure.md`).

144
optional-skills/creative/concept-diagrams/references/infrastructure-patterns.md
View file

@ -1,144 +0,0 @@
# Infrastructure Patterns
Reusable shapes and line styles for infrastructure / systems-integration diagrams (smart cities, IoT networks, industrial systems, multi-domain architectures).
## Layout pattern: hub-spoke
- **Central hub**: Hexagon or circle representing the integration platform
- **Radiating connections**: Data lines from hub to each subsystem with connection dots
- **Subsystem sections**: Each system (power, water, transport) in its own region
- **Dashboard on top**: Optional UI mockup showing a unified view (see `dashboard-patterns.md`)
```xml
<!-- Central hub (hexagon) -->
<polygon class="iot-hex" points="0,-45 39,-22 39,22 0,45 -39,22 -39,-22"/>
<!-- Data lines with connection dots -->
<path class="data-line" d="M 321 248 L 200 248 L 120 380" stroke-dasharray="4 3"/>
<circle cx="321" cy="248" r="4" fill="#7F77DD"/>
```
## Semantic line styles
Use a dedicated CSS class per subsystem so every diagram reads the same way:
```css
.data-line { stroke: #7F77DD; stroke-width: 2; fill: none; stroke-dasharray: 4 3; }
.power-line { stroke: #EF9F27; stroke-width: 2; fill: none; }
.water-pipe { stroke: #378ADD; stroke-width: 4; stroke-linecap: round; fill: none; }
.road { stroke: #888780; stroke-width: 8; stroke-linecap: round; fill: none; }
```
## Power systems
**Solar panel (angled):**
```xml
<polygon class="solar-panel" points="0,25 35,8 38,12 3,29"/>
<line class="solar-frame" x1="12" y1="22" x2="24" y2="13"/>
```
**Wind turbine:**
```xml
<polygon class="wind-tower" points="20,70 30,70 28,25 22,25"/>
<circle class="wind-hub" cx="25" cy="18" r="5"/>
<ellipse class="wind-blade" cx="25" cy="5" rx="3" ry="13"/>
<ellipse class="wind-blade" cx="14" cy="26" rx="3" ry="13" transform="rotate(-120, 25, 18)"/>
<ellipse class="wind-blade" cx="36" cy="26" rx="3" ry="13" transform="rotate(120, 25, 18)"/>
```
**Battery with charge level:**
```xml
<rect class="battery" x="0" y="0" width="45" height="65" rx="5"/>
<rect x="10" y="-6" width="10" height="8" rx="2" fill="#27500A"/> <!-- terminal -->
<rect class="battery-level" x="5" y="12" width="35" height="48" rx="3"/> <!-- fill level -->
```
**Power pylon:**
```xml
<polygon class="pylon" points="30,0 35,0 40,60 25,60"/>
<line x1="15" y1="10" x2="45" y2="10" stroke="#5F5E5A" stroke-width="3"/>
<circle cx="18" cy="10" r="3" fill="#FAEEDA" stroke="#854F0B"/> <!-- insulator -->
```
## Water systems
**Reservoir/dam:**
```xml
<polygon class="reservoir-wall" points="0,60 10,0 70,0 80,60"/>
<polygon class="water" points="12,10 68,10 68,55 75,55 75,58 5,58 5,55 12,55"/>
<!-- Wave effect -->
<path d="M 15 25 Q 25 22 35 25 Q 45 28 55 25" fill="none" stroke="#378ADD" opacity="0.5"/>
```
**Treatment tank:**
```xml
<ellipse class="treatment-tank" cx="35" cy="45" rx="30" ry="18"/>
<rect class="treatment-tank" x="5" y="20" width="60" height="25"/>
<!-- Bubbles -->
<circle cx="20" cy="32" r="2" fill="#378ADD" opacity="0.6"/>
```
**Pipe with joint and valve:**
```xml
<path class="pipe" d="M 80 85 L 110 85"/>
<circle class="pipe-joint" cx="110" cy="85" r="8"/>
<circle class="valve" cx="95" cy="85" r="6"/>
```
## Transport systems
**Road with lane markings:**
```xml
<line class="road" x1="0" y1="50" x2="170" y2="50"/>
<line class="road-mark" x1="10" y1="50" x2="160" y2="50"/>
```
**Traffic light:**
```xml
<rect class="traffic-light" x="0" y="0" width="14" height="32" rx="3"/>
<circle class="light-red" cx="7" cy="8" r="4"/>
<circle class="light-off" cx="7" cy="16" r="4"/>
<circle class="light-green" cx="7" cy="24" r="4"/>
```
**Bus:**
```xml
<rect class="bus" x="0" y="0" width="55" height="28" rx="6"/>
<rect class="bus-window" x="5" y="5" width="12" height="12" rx="2"/>
<circle cx="14" cy="30" r="6" fill="#2C2C2A"/> <!-- wheel -->
<circle cx="14" cy="30" r="3" fill="#5F5E5A"/> <!-- hubcap -->
```
## Full CSS block (add to the host page or inline <style>)
```css
/* Power */
.solar-panel { fill: #3C3489; stroke: #534AB7; stroke-width: 0.5; }
.wind-tower { fill: #B4B2A9; stroke: #5F5E5A; stroke-width: 1; }
.wind-blade { fill: #F1EFE8; stroke: #888780; stroke-width: 0.5; }
.battery { fill: #27500A; stroke: #3B6D11; stroke-width: 1.5; }
.battery-level { fill: #97C459; }
.power-line { stroke: #EF9F27; stroke-width: 2; fill: none; }
/* Water */
.reservoir-wall { fill: #B4B2A9; stroke: #5F5E5A; stroke-width: 1; }
.water { fill: #85B7EB; stroke: #378ADD; stroke-width: 0.5; }
.pipe { fill: none; stroke: #378ADD; stroke-width: 4; stroke-linecap: round; }
.pipe-joint { fill: #185FA5; stroke: #0C447C; stroke-width: 1; }
.valve { fill: #0C447C; stroke: #185FA5; stroke-width: 1; }
/* Transport */
.road { stroke: #888780; stroke-width: 8; fill: none; stroke-linecap: round; }
.road-mark { stroke: #F1EFE8; stroke-width: 1; stroke-dasharray: 6 4; fill: none; }
.traffic-light { fill: #444441; stroke: #2C2C2A; stroke-width: 0.5; }
.light-red { fill: #E24B4A; }
.light-green { fill: #97C459; }
.light-off { fill: #2C2C2A; }
.bus { fill: #E1F5EE; stroke: #0F6E56; stroke-width: 1.5; }
```
## Reference examples
- `examples/smart-city-infrastructure.md` — hub-spoke with multiple subsystems
- `examples/electricity-grid-flow.md` — voltage hierarchy, flow markers
- `examples/wind-turbine-structure.md` — cross-section with legend

42
optional-skills/creative/concept-diagrams/references/physical-shape-cookbook.md
View file

@ -1,42 +0,0 @@
# Physical Shape Cookbook
Guidance for drawing physical objects (vehicles, buildings, hardware, mechanical systems, anatomy) — when rectangles aren't enough.
## Shape selection
| Physical form | SVG element | Example use |
|---------------|-------------|-------------|
| Curved bodies | `<path>` with Q/C curves | Fuselage, tanks, pipes |
| Tapered/angular shapes | `<polygon>` | Wings, fins, wedges |
| Cylindrical/round | `<ellipse>`, `<circle>` | Engines, wheels, buttons |
| Linear structures | `<line>` | Struts, beams, connections |
| Internal sections | `<rect>` inside parent | Compartments, rooms |
| Dashed boundaries | `stroke-dasharray` | Hidden parts, fuel tanks |
## Layering approach
1. Draw outer structure first (fuselage, frame, hull)
2. Add internal sections on top (cabins, compartments)
3. Add detail elements (engines, wheels, controls)
4. Add leader lines with labels
## Semantic CSS classes (instead of c-* ramps)
For physical diagrams, define component-specific classes directly rather than applying `c-*` color classes. This makes each part self-documenting and lets you keep a restrained palette:
```css
.fuselage { fill: #F1EFE8; stroke: #5F5E5A; stroke-width: 1; }
.wing { fill: #E6F1FB; stroke: #185FA5; stroke-width: 1; }
.engine { fill: #FAECE7; stroke: #993C1D; stroke-width: 1; }
```
Add these to a local `<style>` inside the SVG (or extend the host page's `<style>` block). The light-mode/dark-mode pattern still works — use the CSS variables from the template (`var(--bg-secondary)`, `var(--border)`, `var(--text-primary)`) if you want dark-mode awareness.
## Reference examples
Look at these example files for working physical-diagram patterns:
- `examples/commercial-aircraft-structure.md` — fuselage curves + tapered wings + ellipse engines
- `examples/wind-turbine-structure.md` — underground foundation, tubular tower, nacelle cutaway
- `examples/smartphone-layer-anatomy.md` — exploded-view stack with alternating labels
- `examples/apartment-floor-plan-conversion.md` — walls, doors, windows, proposed changes

174
optional-skills/creative/concept-diagrams/templates/template.html
View file

@ -1,174 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Concept Diagram</title>
<style>
:root {
--text-primary: #1a1a18;
--text-secondary: #5f5e5a;
--text-tertiary: #88877f;
--bg-primary: #ffffff;
--bg-secondary: #f6f5f0;
--bg-tertiary: #eeedeb;
--border: rgba(0,0,0,0.15);
--border-hover: rgba(0,0,0,0.3);
}
@media (prefers-color-scheme: dark) {
:root {
--text-primary: #e8e6de;
--text-secondary: #b4b2a9;
--text-tertiary: #888780;
--bg-primary: #1a1a18;
--bg-secondary: #2c2c2a;
--bg-tertiary: #3d3d3a;
--border: rgba(255,255,255,0.15);
--border-hover: rgba(255,255,255,0.3);
}
}
* { margin: 0; padding: 0; box-sizing: border-box; }
body {
font-family: system-ui, -apple-system, sans-serif;
background: var(--bg-tertiary);
display: flex;
justify-content: center;
align-items: flex-start;
min-height: 100vh;
padding: 40px 20px;
}
.card {
background: var(--bg-primary);
border-radius: 16px;
padding: 32px;
max-width: 780px;
width: 100%;
box-shadow: 0 1px 3px rgba(0,0,0,0.08);
}
h1 {
font-size: 18px;
font-weight: 500;
color: var(--text-primary);
margin-bottom: 8px;
}
.subtitle {
font-size: 13px;
color: var(--text-tertiary);
margin-bottom: 24px;
}
svg { width: 100%; height: auto; }
/* === SVG Design System Classes === */
/* Text classes */
.t { font-family: system-ui, -apple-system, sans-serif; font-size: 14px; fill: var(--text-primary); }
.ts { font-family: system-ui, -apple-system, sans-serif; font-size: 12px; fill: var(--text-secondary); }
.th { font-family: system-ui, -apple-system, sans-serif; font-size: 14px; fill: var(--text-primary); font-weight: 500; }
/* Neutral box */
.box { fill: var(--bg-secondary); stroke: var(--border); stroke-width: 0.5px; }
/* Arrow */
.arr { stroke: var(--text-secondary); stroke-width: 1.5px; fill: none; }
/* Leader line */
.leader { stroke: var(--text-tertiary); stroke-width: 0.5px; stroke-dasharray: 4 3; fill: none; }
/* Clickable node */
.node { cursor: pointer; transition: opacity 0.15s; }
.node:hover { opacity: 0.82; }
/* === Color Ramp Classes (light mode) === */
.c-purple > rect, .c-purple > circle, .c-purple > ellipse { fill: #EEEDFE; stroke: #534AB7; }
.c-purple > .th, .c-purple > text.th { fill: #3C3489; }
.c-purple > .ts, .c-purple > text.ts { fill: #534AB7; }
.c-purple > .t, .c-purple > text.t { fill: #3C3489; }
.c-teal > rect, .c-teal > circle, .c-teal > ellipse { fill: #E1F5EE; stroke: #0F6E56; }
.c-teal > .th, .c-teal > text.th { fill: #085041; }
.c-teal > .ts, .c-teal > text.ts { fill: #0F6E56; }
.c-teal > .t, .c-teal > text.t { fill: #085041; }
.c-coral > rect, .c-coral > circle, .c-coral > ellipse { fill: #FAECE7; stroke: #993C1D; }
.c-coral > .th, .c-coral > text.th { fill: #712B13; }
.c-coral > .ts, .c-coral > text.ts { fill: #993C1D; }
.c-coral > .t, .c-coral > text.t { fill: #712B13; }
.c-pink > rect, .c-pink > circle, .c-pink > ellipse { fill: #FBEAF0; stroke: #993556; }
.c-pink > .th, .c-pink > text.th { fill: #72243E; }
.c-pink > .ts, .c-pink > text.ts { fill: #993556; }
.c-pink > .t, .c-pink > text.t { fill: #72243E; }
.c-gray > rect, .c-gray > circle, .c-gray > ellipse { fill: #F1EFE8; stroke: #5F5E5A; }
.c-gray > .th, .c-gray > text.th { fill: #444441; }
.c-gray > .ts, .c-gray > text.ts { fill: #5F5E5A; }
.c-gray > .t, .c-gray > text.t { fill: #444441; }
.c-blue > rect, .c-blue > circle, .c-blue > ellipse { fill: #E6F1FB; stroke: #185FA5; }
.c-blue > .th, .c-blue > text.th { fill: #0C447C; }
.c-blue > .ts, .c-blue > text.ts { fill: #185FA5; }
.c-blue > .t, .c-blue > text.t { fill: #0C447C; }
.c-green > rect, .c-green > circle, .c-green > ellipse { fill: #EAF3DE; stroke: #3B6D11; }
.c-green > .th, .c-green > text.th { fill: #27500A; }
.c-green > .ts, .c-green > text.ts { fill: #3B6D11; }
.c-green > .t, .c-green > text.t { fill: #27500A; }
.c-amber > rect, .c-amber > circle, .c-amber > ellipse { fill: #FAEEDA; stroke: #854F0B; }
.c-amber > .th, .c-amber > text.th { fill: #633806; }
.c-amber > .ts, .c-amber > text.ts { fill: #854F0B; }
.c-amber > .t, .c-amber > text.t { fill: #633806; }
.c-red > rect, .c-red > circle, .c-red > ellipse { fill: #FCEBEB; stroke: #A32D2D; }
.c-red > .th, .c-red > text.th { fill: #791F1F; }
.c-red > .ts, .c-red > text.ts { fill: #A32D2D; }
.c-red > .t, .c-red > text.t { fill: #791F1F; }
/* === Dark mode overrides === */
@media (prefers-color-scheme: dark) {
.c-purple > rect, .c-purple > circle, .c-purple > ellipse { fill: #3C3489; stroke: #AFA9EC; }
.c-purple > .th, .c-purple > text.th { fill: #CECBF6; }
.c-purple > .ts, .c-purple > text.ts { fill: #AFA9EC; }
.c-teal > rect, .c-teal > circle, .c-teal > ellipse { fill: #085041; stroke: #5DCAA5; }
.c-teal > .th, .c-teal > text.th { fill: #9FE1CB; }
.c-teal > .ts, .c-teal > text.ts { fill: #5DCAA5; }
.c-coral > rect, .c-coral > circle, .c-coral > ellipse { fill: #712B13; stroke: #F0997B; }
.c-coral > .th, .c-coral > text.th { fill: #F5C4B3; }
.c-coral > .ts, .c-coral > text.ts { fill: #F0997B; }
.c-pink > rect, .c-pink > circle, .c-pink > ellipse { fill: #72243E; stroke: #ED93B1; }
.c-pink > .th, .c-pink > text.th { fill: #F4C0D1; }
.c-pink > .ts, .c-pink > text.ts { fill: #ED93B1; }
.c-gray > rect, .c-gray > circle, .c-gray > ellipse { fill: #444441; stroke: #B4B2A9; }
.c-gray > .th, .c-gray > text.th { fill: #D3D1C7; }
.c-gray > .ts, .c-gray > text.ts { fill: #B4B2A9; }
.c-blue > rect, .c-blue > circle, .c-blue > ellipse { fill: #0C447C; stroke: #85B7EB; }
.c-blue > .th, .c-blue > text.th { fill: #B5D4F4; }
.c-blue > .ts, .c-blue > text.ts { fill: #85B7EB; }
.c-green > rect, .c-green > circle, .c-green > ellipse { fill: #27500A; stroke: #97C459; }
.c-green > .th, .c-green > text.th { fill: #C0DD97; }
.c-green > .ts, .c-green > text.ts { fill: #97C459; }
.c-amber > rect, .c-amber > circle, .c-amber > ellipse { fill: #633806; stroke: #EF9F27; }
.c-amber > .th, .c-amber > text.th { fill: #FAC775; }
.c-amber > .ts, .c-amber > text.ts { fill: #EF9F27; }
.c-red > rect, .c-red > circle, .c-red > ellipse { fill: #791F1F; stroke: #F09595; }
.c-red > .th, .c-red > text.th { fill: #F7C1C1; }
.c-red > .ts, .c-red > text.ts { fill: #F09595; }
}
</style>
</head>
<body>
<div class="card">
<h1><!-- DIAGRAM TITLE HERE --></h1>
<p class="subtitle"><!-- OPTIONAL SUBTITLE HERE --></p>
<!-- PASTE SVG HERE -->
</div>
</body>
</html>

2
optional-skills/creative/kanban-video-orchestrator/SKILL.md
View file

@ -8,7 +8,7 @@ platforms: [linux, macos, windows]
metadata:
hermes:
tags: [video, kanban, multi-agent, orchestration, production-pipeline]
related_skills: [kanban-orchestrator, kanban-worker, ascii-video, manim-video, p5js, comfyui, touchdesigner-mcp, blender-mcp, pixel-art, ascii-art, songwriting-and-ai-music, heartmula, songsee, spotify, youtube-content, claude-design, excalidraw, architecture-diagram, concept-diagrams, baoyu-comic, baoyu-infographic, humanizer, gif-search, meme-generation]
related_skills: [kanban-orchestrator, kanban-worker, ascii-video, manim-video, p5js, comfyui, touchdesigner-mcp, blender-mcp, pixel-art, ascii-art, songwriting-and-ai-music, heartmula, songsee, spotify, youtube-content, claude-design, excalidraw, html-artifact, baoyu-comic, baoyu-infographic, humanizer, gif-search, meme-generation]
credits: |
The single-project workspace layout, profile-config patching pattern,
SOUL.md-per-profile model, TEAM.md task-graph convention, and

3
optional-skills/creative/kanban-video-orchestrator/references/intake.md
View file

@ -96,8 +96,7 @@ texture inside the final scene.
- **Terminal-only or with GUI?**
- **Voiceover for narration?**
- **Diagram support needed?** — Often these benefit from a diagram skill
alongside the screen-capture/render step (`excalidraw`,
`architecture-diagram`, `concept-diagrams`)
alongside the screen-capture/render step (`excalidraw`, `html-artifact`)
### ASCII / terminal art

5
optional-skills/creative/kanban-video-orchestrator/references/role-archetypes.md
View file

@ -59,7 +59,7 @@ local skills.
- **Toolsets:** kanban, terminal, file
- **Skills:** `kanban-worker` plus any project-specific design skill —
`claude-design` (UI/web), `sketch` (quick mockup variants),
`claude-design` (UI/web), `html-artifact` (quick mockup variants, explainers, diagrams),
`popular-web-designs` (matching known web aesthetic), `pixel-art` (retro),
`ascii-art` (terminal/retro), `excalidraw` (hand-drawn frames),
`design-md` (text-based design docs)
@ -72,8 +72,7 @@ film and music video. Often pairs with a diagramming tool.
- **Toolsets:** kanban, file
- **Skills:** `kanban-worker` plus a diagram skill — `excalidraw` (sketch),
`architecture-diagram` (technical/system), `concept-diagrams` (educational/
scientific)
`html-artifact` (technical/system + educational/scientific diagrams)
- **Outputs:** `storyboard.md` with one row per scene/shot, optional
storyboard sketches

4
optional-skills/creative/kanban-video-orchestrator/references/tool-matrix.md
View file

@ -30,10 +30,8 @@ called from the terminal toolset; they don't appear in `always_load`.
| `claude-design` | Design one-off HTML artifacts (landing, deck, prototype) | Concept artist for product video style frames; storyboarder for UI-heavy content |
| `design-md` | Design markdown docs | Concept artist documenting visual specs |
| `popular-web-designs` | Reference patterns for popular web designs | Concept artist; cinematographer when matching a known UI aesthetic |
| `sketch` | Throwaway HTML mockups (2-3 design variants to compare) | Concept artist exploring directions; storyboarder for UI flows |
| `excalidraw` | Excalidraw-style hand-drawn diagrams | Storyboarder; concept artist for sketch-style frames |
| `architecture-diagram` | Software architecture diagrams | Storyboarder for technical content; explainer scenes about systems |
| `concept-diagrams` *(optional)* | Flat, minimal SVG diagrams (educational visual language; physics, chemistry, math, anatomy, etc.) | Renderer / storyboarder for explainer scenes with clean educational diagrams |
| `html-artifact` | Self-contained HTML artifacts: throwaway mockup variants, explainers, dark-tech architecture + educational SVG diagrams | Concept artist exploring directions; storyboarder for UI flows + technical/educational explainer scenes |
| `pretext` | Mathematical/scientific content authoring | Writer / cinematographer for technical-explainer pretexts |
| `creative-ideation` | Constraint-driven project ideation | Director / cinematographer when the brief is wide-open and needs framing |
| `humanizer` | Strip AI-isms from text, add real voice | Writer / copywriter post-process to avoid AI-tells in scripts and VO copy |

148
skills/creative/architecture-diagram/SKILL.md
View file

@ -1,148 +0,0 @@
---
name: architecture-diagram
description: "Dark-themed SVG architecture/cloud/infra diagrams as HTML."
version: 1.0.0
author: Cocoon AI (hello@cocoon-ai.com), ported by Hermes Agent
license: MIT
dependencies: []
platforms: [linux, macos, windows]
metadata:
hermes:
tags: [architecture, diagrams, SVG, HTML, visualization, infrastructure, cloud]
related_skills: [concept-diagrams, excalidraw]
---
# Architecture Diagram Skill
Generate professional, dark-themed technical architecture diagrams as standalone HTML files with inline SVG graphics. No external tools, no API keys, no rendering libraries — just write the HTML file and open it in a browser.
## Scope
**Best suited for:**
- Software system architecture (frontend / backend / database layers)
- Cloud infrastructure (VPC, regions, subnets, managed services)
- Microservice / service-mesh topology
- Database + API map, deployment diagrams
- Anything with a tech-infra subject that fits a dark, grid-backed aesthetic
**Look elsewhere first for:**
- Physics, chemistry, math, biology, or other scientific subjects
- Physical objects (vehicles, hardware, anatomy, cross-sections)
- Floor plans, narrative journeys, educational / textbook-style visuals
- Hand-drawn whiteboard sketches (consider `excalidraw`)
- Animated explainers (consider an animation skill)
If a more specialized skill is available for the subject, prefer that. If none fits, this skill can also serve as a general SVG diagram fallback — the output will just carry the dark tech aesthetic described below.
Based on [Cocoon AI's architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) (MIT).
## Workflow
1. User describes their system architecture (components, connections, technologies)
2. Generate the HTML file following the design system below
3. Save with `write_file` to a `.html` file (e.g. `~/architecture-diagram.html`)
4. User opens in any browser — works offline, no dependencies
### Output Location
Save diagrams to a user-specified path, or default to the current working directory:
```
./[project-name]-architecture.html
```
### Preview
After saving, suggest the user open it:
```bash
# macOS
open ./my-architecture.html
# Linux
xdg-open ./my-architecture.html
```
## Design System & Visual Language
### Color Palette (Semantic Mapping)
Use specific `rgba` fills and hex strokes to categorize components:
| Component Type | Fill (rgba) | Stroke (Hex) |
| :--- | :--- | :--- |
| **Frontend** | `rgba(8, 51, 68, 0.4)` | `#22d3ee` (cyan-400) |
| **Backend** | `rgba(6, 78, 59, 0.4)` | `#34d399` (emerald-400) |
| **Database** | `rgba(76, 29, 149, 0.4)` | `#a78bfa` (violet-400) |
| **AWS/Cloud** | `rgba(120, 53, 15, 0.3)` | `#fbbf24` (amber-400) |
| **Security** | `rgba(136, 19, 55, 0.4)` | `#fb7185` (rose-400) |
| **Message Bus** | `rgba(251, 146, 60, 0.3)` | `#fb923c` (orange-400) |
| **External** | `rgba(30, 41, 59, 0.5)` | `#94a3b8` (slate-400) |
### Typography & Background
- **Font:** JetBrains Mono (Monospace), loaded from Google Fonts
- **Sizes:** 12px (Names), 9px (Sublabels), 8px (Annotations), 7px (Tiny labels)
- **Background:** Slate-950 (`#020617`) with a subtle 40px grid pattern
```svg
<!-- Background Grid Pattern -->
<pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse">
<path d="M 40 0 L 0 0 0 40" fill="none" stroke="#1e293b" stroke-width="0.5"/>
</pattern>
```
## Technical Implementation Details
### Component Rendering
Components are rounded rectangles (`rx="6"`) with 1.5px strokes. To prevent arrows from showing through semi-transparent fills, use a **double-rect masking technique**:
1. Draw an opaque background rect (`#0f172a`)
2. Draw the semi-transparent styled rect on top
### Connection Rules
- **Z-Order:** Draw arrows *early* in the SVG (after the grid) so they render behind component boxes
- **Arrowheads:** Defined via SVG markers
- **Security Flows:** Use dashed lines in rose color (`#fb7185`)
- **Boundaries:**
- *Security Groups:* Dashed (`4,4`), rose color
- *Regions:* Large dashed (`8,4`), amber color, `rx="12"`
### Spacing & Layout Logic
- **Standard Height:** 60px (Services); 80-120px (Large components)
- **Vertical Gap:** Minimum 40px between components
- **Message Buses:** Must be placed *in the gap* between services, not overlapping them
- **Legend Placement:** **CRITICAL.** Must be placed outside all boundary boxes. Calculate the lowest Y-coordinate of all boundaries and place the legend at least 20px below it.
## Document Structure
The generated HTML file follows a four-part layout:
1. **Header:** Title with a pulsing dot indicator and subtitle
2. **Main SVG:** The diagram contained within a rounded border card
3. **Summary Cards:** A grid of three cards below the diagram for high-level details
4. **Footer:** Minimal metadata
### Info Card Pattern
```html
<div class="card">
<div class="card-header">
<div class="card-dot cyan"></div>
<h3>Title</h3>
</div>
<ul>
<li>• Item one</li>
<li>• Item two</li>
</ul>
</div>
```
## Output Requirements
- **Single File:** One self-contained `.html` file
- **No External Dependencies:** All CSS and SVG must be inline (except Google Fonts)
- **No JavaScript:** Use pure CSS for any animations (like pulsing dots)
- **Compatibility:** Must render correctly in any modern web browser
## Template Reference
Load the full HTML template for the exact structure, CSS, and SVG component examples:
```
skill_view(name="architecture-diagram", file_path="templates/template.html")
```
The template contains working examples of every component type (frontend, backend, database, cloud, security), arrow styles (standard, dashed, curved), security groups, region boundaries, and the legend — use it as your structural reference when generating diagrams.

319
skills/creative/architecture-diagram/templates/template.html
View file

@ -1,319 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>[PROJECT NAME] Architecture Diagram</title>
<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600;700&display=swap" rel="stylesheet">
<style>
* {
margin: 0;
padding: 0;
box-sizing: border-box;
}
body {
font-family: 'JetBrains Mono', monospace;
background: #020617;
min-height: 100vh;
padding: 2rem;
color: white;
}
.container {
max-width: 1200px;
margin: 0 auto;
}
.header {
margin-bottom: 2rem;
}
.header-row {
display: flex;
align-items: center;
gap: 1rem;
margin-bottom: 0.5rem;
}
.pulse-dot {
width: 12px;
height: 12px;
background: #22d3ee;
border-radius: 50%;
animation: pulse 2s infinite;
}
@keyframes pulse {
0%, 100% { opacity: 1; }
50% { opacity: 0.5; }
}
h1 {
font-size: 1.5rem;
font-weight: 700;
letter-spacing: -0.025em;
}
.subtitle {
color: #94a3b8;
font-size: 0.875rem;
margin-left: 1.75rem;
}
.diagram-container {
background: rgba(15, 23, 42, 0.5);
border-radius: 1rem;
border: 1px solid #1e293b;
padding: 1.5rem;
overflow-x: auto;
}
svg {
width: 100%;
min-width: 900px;
display: block;
}
.cards {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
gap: 1rem;
margin-top: 2rem;
}
.card {
background: rgba(15, 23, 42, 0.5);
border-radius: 0.75rem;
border: 1px solid #1e293b;
padding: 1.25rem;
}
.card-header {
display: flex;
align-items: center;
gap: 0.5rem;
margin-bottom: 0.75rem;
}
.card-dot {
width: 8px;
height: 8px;
border-radius: 50%;
}
.card-dot.cyan { background: #22d3ee; }
.card-dot.emerald { background: #34d399; }
.card-dot.violet { background: #a78bfa; }
.card-dot.amber { background: #fbbf24; }
.card-dot.rose { background: #fb7185; }
.card h3 {
font-size: 0.875rem;
font-weight: 600;
}
.card ul {
list-style: none;
color: #94a3b8;
font-size: 0.75rem;
}
.card li {
margin-bottom: 0.375rem;
}
.footer {
text-align: center;
margin-top: 1.5rem;
color: #475569;
font-size: 0.75rem;
}
</style>
</head>
<body>
<div class="container">
<!-- Header -->
<div class="header">
<div class="header-row">
<div class="pulse-dot"></div>
<h1>[PROJECT NAME] Architecture</h1>
</div>
<p class="subtitle">[Subtitle description]</p>
</div>
<!-- Main Diagram -->
<div class="diagram-container">
<svg viewBox="0 0 1000 680">
<!-- Definitions -->
<defs>
<marker id="arrowhead" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
<polygon points="0 0, 10 3.5, 0 7" fill="#64748b" />
</marker>
<pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse">
<path d="M 40 0 L 0 0 0 40" fill="none" stroke="#1e293b" stroke-width="0.5"/>
</pattern>
</defs>
<!-- Background Grid -->
<rect width="100%" height="100%" fill="url(#grid)" />
<!-- =================================================================
COMPONENT EXAMPLES - Copy and customize these patterns
================================================================= -->
<!-- External/Generic Component -->
<rect x="30" y="280" width="100" height="50" rx="6" fill="rgba(30, 41, 59, 0.5)" stroke="#94a3b8" stroke-width="1.5"/>
<text x="80" y="300" fill="white" font-size="11" font-weight="600" text-anchor="middle">Users</text>
<text x="80" y="316" fill="#94a3b8" font-size="9" text-anchor="middle">Browser/Mobile</text>
<!-- Security Component -->
<rect x="30" y="80" width="100" height="60" rx="6" fill="rgba(136, 19, 55, 0.4)" stroke="#fb7185" stroke-width="1.5"/>
<text x="80" y="105" fill="white" font-size="11" font-weight="600" text-anchor="middle">Auth Provider</text>
<text x="80" y="121" fill="#94a3b8" font-size="9" text-anchor="middle">OAuth 2.0</text>
<!-- Region/Cloud Boundary -->
<rect x="160" y="40" width="820" height="620" rx="12" fill="rgba(251, 191, 36, 0.05)" stroke="#fbbf24" stroke-width="1" stroke-dasharray="8,4"/>
<text x="172" y="58" fill="#fbbf24" font-size="10" font-weight="600">AWS Region: us-west-2</text>
<!-- AWS/Cloud Service -->
<rect x="200" y="280" width="110" height="50" rx="6" fill="rgba(120, 53, 15, 0.3)" stroke="#fbbf24" stroke-width="1.5"/>
<text x="255" y="300" fill="white" font-size="11" font-weight="600" text-anchor="middle">CloudFront</text>
<text x="255" y="316" fill="#94a3b8" font-size="9" text-anchor="middle">CDN</text>
<!-- Multi-line AWS Component (S3 Buckets example) -->
<rect x="200" y="380" width="110" height="100" rx="6" fill="rgba(120, 53, 15, 0.3)" stroke="#fbbf24" stroke-width="1.5"/>
<text x="255" y="400" fill="white" font-size="11" font-weight="600" text-anchor="middle">S3 Buckets</text>
<text x="255" y="420" fill="#94a3b8" font-size="8" text-anchor="middle">• bucket-one</text>
<text x="255" y="434" fill="#94a3b8" font-size="8" text-anchor="middle">• bucket-two</text>
<text x="255" y="448" fill="#94a3b8" font-size="8" text-anchor="middle">• bucket-three</text>
<text x="255" y="466" fill="#fbbf24" font-size="7" text-anchor="middle">OAI Protected</text>
<!-- Security Group (dashed boundary) -->
<rect x="350" y="265" width="120" height="80" rx="8" fill="transparent" stroke="#fb7185" stroke-width="1" stroke-dasharray="4,4"/>
<text x="358" y="279" fill="#fb7185" font-size="8">sg-name :port</text>
<!-- Component inside security group -->
<rect x="360" y="280" width="100" height="50" rx="6" fill="rgba(120, 53, 15, 0.3)" stroke="#fbbf24" stroke-width="1.5"/>
<text x="410" y="300" fill="white" font-size="11" font-weight="600" text-anchor="middle">Load Balancer</text>
<text x="410" y="316" fill="#94a3b8" font-size="9" text-anchor="middle">HTTPS :443</text>
<!-- Backend Component -->
<rect x="510" y="280" width="110" height="50" rx="6" fill="rgba(6, 78, 59, 0.4)" stroke="#34d399" stroke-width="1.5"/>
<text x="565" y="300" fill="white" font-size="11" font-weight="600" text-anchor="middle">API Server</text>
<text x="565" y="316" fill="#94a3b8" font-size="9" text-anchor="middle">FastAPI :8000</text>
<!-- Database Component -->
<rect x="700" y="280" width="120" height="50" rx="6" fill="rgba(76, 29, 149, 0.4)" stroke="#a78bfa" stroke-width="1.5"/>
<text x="760" y="300" fill="white" font-size="11" font-weight="600" text-anchor="middle">Database</text>
<text x="760" y="316" fill="#94a3b8" font-size="9" text-anchor="middle">PostgreSQL</text>
<!-- Frontend Component -->
<rect x="200" y="520" width="200" height="110" rx="8" fill="rgba(8, 51, 68, 0.4)" stroke="#22d3ee" stroke-width="1.5"/>
<text x="300" y="545" fill="white" font-size="12" font-weight="600" text-anchor="middle">Frontend</text>
<text x="300" y="565" fill="#94a3b8" font-size="9" text-anchor="middle">React + TypeScript</text>
<text x="300" y="580" fill="#94a3b8" font-size="9" text-anchor="middle">Additional detail</text>
<text x="300" y="595" fill="#94a3b8" font-size="9" text-anchor="middle">More info</text>
<text x="300" y="615" fill="#22d3ee" font-size="8" text-anchor="middle">domain.example.com</text>
<!-- =================================================================
ARROW EXAMPLES
================================================================= -->
<!-- Standard arrow with label -->
<line x1="130" y1="305" x2="198" y2="305" stroke="#22d3ee" stroke-width="1.5" marker-end="url(#arrowhead)"/>
<text x="164" y="299" fill="#94a3b8" font-size="9" text-anchor="middle">HTTPS</text>
<!-- Simple arrow (no label) -->
<line x1="310" y1="305" x2="358" y2="305" stroke="#22d3ee" stroke-width="1.5" marker-end="url(#arrowhead)"/>
<!-- Vertical arrow -->
<line x1="255" y1="330" x2="255" y2="378" stroke="#fbbf24" stroke-width="1.5" marker-end="url(#arrowhead)"/>
<text x="270" y="358" fill="#94a3b8" font-size="9">OAI</text>
<!-- Dashed arrow (for auth/security flows) -->
<line x1="460" y1="305" x2="508" y2="305" stroke="#34d399" stroke-width="1.5" marker-end="url(#arrowhead)"/>
<line x1="620" y1="305" x2="698" y2="305" stroke="#a78bfa" stroke-width="1.5" marker-end="url(#arrowhead)"/>
<text x="655" y="299" fill="#94a3b8" font-size="9">TLS</text>
<!-- Curved path for auth flow -->
<path d="M 80 140 L 80 200 Q 80 220 100 220 L 200 220 Q 220 220 220 240 L 220 278" fill="none" stroke="#fb7185" stroke-width="1.5" stroke-dasharray="5,5"/>
<text x="150" y="210" fill="#fb7185" font-size="8">JWT + PKCE</text>
<!-- =================================================================
LEGEND
================================================================= -->
<text x="720" y="70" fill="white" font-size="10" font-weight="600">Legend</text>
<rect x="720" y="82" width="16" height="10" rx="2" fill="rgba(8, 51, 68, 0.4)" stroke="#22d3ee" stroke-width="1"/>
<text x="742" y="90" fill="#94a3b8" font-size="8">Frontend</text>
<rect x="720" y="98" width="16" height="10" rx="2" fill="rgba(6, 78, 59, 0.4)" stroke="#34d399" stroke-width="1"/>
<text x="742" y="106" fill="#94a3b8" font-size="8">Backend</text>
<rect x="720" y="114" width="16" height="10" rx="2" fill="rgba(120, 53, 15, 0.3)" stroke="#fbbf24" stroke-width="1"/>
<text x="742" y="122" fill="#94a3b8" font-size="8">Cloud Service</text>
<rect x="720" y="130" width="16" height="10" rx="2" fill="rgba(76, 29, 149, 0.4)" stroke="#a78bfa" stroke-width="1"/>
<text x="742" y="138" fill="#94a3b8" font-size="8">Database</text>
<rect x="720" y="146" width="16" height="10" rx="2" fill="rgba(136, 19, 55, 0.4)" stroke="#fb7185" stroke-width="1"/>
<text x="742" y="154" fill="#94a3b8" font-size="8">Security</text>
<line x1="720" y1="168" x2="736" y2="168" stroke="#fb7185" stroke-width="1" stroke-dasharray="3,3"/>
<text x="742" y="171" fill="#94a3b8" font-size="8">Auth Flow</text>
<rect x="720" y="178" width="16" height="10" rx="2" fill="transparent" stroke="#fb7185" stroke-width="1" stroke-dasharray="3,3"/>
<text x="742" y="186" fill="#94a3b8" font-size="8">Security Group</text>
</svg>
</div>
<!-- Info Cards -->
<div class="cards">
<div class="card">
<div class="card-header">
<div class="card-dot rose"></div>
<h3>Card Title 1</h3>
</div>
<ul>
<li>• Item one</li>
<li>• Item two</li>
<li>• Item three</li>
<li>• Item four</li>
</ul>
</div>
<div class="card">
<div class="card-header">
<div class="card-dot amber"></div>
<h3>Card Title 2</h3>
</div>
<ul>
<li>• Item one</li>
<li>• Item two</li>
<li>• Item three</li>
<li>• Item four</li>
</ul>
</div>
<div class="card">
<div class="card-header">
<div class="card-dot violet"></div>
<h3>Card Title 3</h3>
</div>
<ul>
<li>• Item one</li>
<li>• Item two</li>
<li>• Item three</li>
<li>• Item four</li>
</ul>
</div>
</div>
<!-- Footer -->
<p class="footer">
[Project Name] • [Additional metadata]
</p>
</div>
</body>
</html>

12
skills/creative/claude-design/SKILL.md
View file

@ -8,7 +8,7 @@ platforms: [linux, macos, windows]
metadata:
hermes:
tags: [design, html, prototype, ux, ui, creative, artifact, deck, motion, design-system]
related_skills: [design-md, popular-web-designs, excalidraw, architecture-diagram]
related_skills: [html-artifact, design-md, popular-web-designs, excalidraw]
---
# Claude Design for CLI/API Agents
@ -19,19 +19,21 @@ The goal is to preserve Claude Design's useful design behavior and taste while r
**Before starting, check for other web-design skills like `popular-web-designs` (ready-to-paste design systems for Stripe, Linear, Vercel, Notion, etc.) and `design-md` (Google's DESIGN.md token spec format).** If the user wants a known brand's look, load `popular-web-designs` alongside this one and let it supply the visual vocabulary. If the deliverable is a token spec file rather than a rendered artifact, use `design-md` instead. Full decision table below.
## When To Use This Skill vs `popular-web-designs` vs `design-md`
## When To Use This Skill vs `html-artifact` vs `popular-web-designs` vs `design-md`
Hermes has three design-related skills under `skills/creative/`. They do different jobs — load the right one (or combine them):
Several skills produce HTML — they do different jobs. Load the right one (or combine them):
| Skill | What it gives you | Use when the user wants... |
|---|---|---|
| **claude-design** (this one) | Design *process and taste* — how to scope a brief, gather context, produce variants, verify a local HTML artifact, avoid AI-design slop | a from-scratch designed artifact (landing page, prototype, deck, component lab, motion study) with no specific brand or token system dictated |
| **claude-design** (this one) | Visual design *process and taste* — how to scope a brief, gather context, produce variants, verify a local HTML artifact, avoid AI-design slop | a from-scratch *designed* artifact (landing page, prototype, deck, component lab, motion study) where the look itself is the point and no specific brand or token system is dictated |
| **html-artifact** | A house style for *information* artifacts — explainers, plans, reports, code reviews, technical/educational diagrams, throwaway editors | to *explain / plan / report / diagram / review* something as a shareable HTML page — the content is the point, not bespoke visual design |
| **popular-web-designs** | 54 ready-to-paste design systems — exact colors, typography, components, CSS values for sites like Stripe, Linear, Vercel, Notion, Airbnb | "make it look like Stripe / Linear / Vercel", a page styled after a known brand, or a visual starting point pulled from a real product |
| **design-md** | Google's DESIGN.md spec format — author/validate/diff/export design-token files, WCAG contrast checking, Tailwind/DTCG export | a formal, persistent, machine-readable design-system *spec file* (tokens + rationale) that lives in a repo and gets consumed by agents over time |
Rule of thumb:
- **Process + taste, one-off artifact** → claude-design
- **Bespoke visual design, taste-driven artifact** → claude-design
- **Explain / plan / report / diagram as a shareable page** → html-artifact
- **Match a known brand's look** → popular-web-designs (and let claude-design drive the process)
- **Author the tokens spec itself** → design-md

2
skills/creative/design-md/SKILL.md
View file

@ -8,7 +8,7 @@ platforms: [linux, macos, windows]
metadata:
hermes:
tags: [design, design-system, tokens, ui, accessibility, wcag, tailwind, dtcg, google]
related_skills: [popular-web-designs, claude-design, excalidraw, architecture-diagram]
related_skills: [popular-web-designs, claude-design, excalidraw, html-artifact]
---
# DESIGN.md Skill

184
skills/creative/html-artifact/SKILL.md Normal file
View file

@ -0,0 +1,184 @@
---
name: html-artifact
description: Build self-contained HTML files to explain, plan, or review.
version: 1.0.0
author: Anthropic (html-effectiveness gallery, MIT), adapted for Hermes Agent
license: MIT
platforms: [linux, macos, windows]
metadata:
hermes:
tags: [html, artifact, explainer, plan, report, code-review, diagram, svg, design, prototype, editor]
related_skills: [claude-design, popular-web-designs, design-md, excalidraw, p5js]
---
# HTML Artifact Skill
Produce a single self-contained `.html` file — no build step, no dependencies, no
CDN — whenever the deliverable is something a human should *read, share, or poke at*:
a concept explainer, an implementation plan, a status/incident report, a code-review
walkthrough, a technical or educational diagram, a set of design variants, or a
throwaway editor that exports its result back to you.
HTML beats Markdown once a doc has color, layout, diagrams, tables, code, or
interaction. It opens in any browser, shares as a link, stays readable past 100
lines, and can carry SVG diagrams and live controls Markdown can't. Default to an
HTML artifact when the user says "make an HTML file/artifact", or asks you to
*explain how X works*, *write up a plan/PR/report*, *diagram* something, *compare*
options, or *prototype* an interaction — even when they don't say "HTML".
## Why this skill exists (and what it replaced)
This skill **supersedes** three former skills — `sketch` (throwaway multi-variant
HTML mockups), `architecture-diagram` (dark-tech infra SVG), and `concept-diagrams`
(educational SVG). They were consolidated for a concrete reason: all three emitted
the *same artifact* — a single self-contained HTML file with inline CSS/SVG — and
overlapped heavily (three "diagram" skills, two "compare variants" paths, no shared
token system). Folding them into one mode-switched skill removes the
which-one-do-I-load ambiguity and gives every output the same house style, while
keeping each skill's unique value: the fidelity dial + verify loop (from `sketch`),
the dark infra aesthetic (from `architecture-diagram`), and the 9-ramp educational
system + archetype library (from `concept-diagrams`).
The consolidation is footprint-safe: this skill has **zero dependencies** (no Node,
FFmpeg, Chromium, or pip packages — it authors plain HTML/CSS/SVG), so even though it
ships **bundled** (active by default) where `concept-diagrams` was optional, the only
always-in-context cost is this skill's one-line description. All references,
templates, and the example gallery load on demand. `concept-diagrams` was optional
because it was niche, not because it had an install cost — promoting that capability
into a general-purpose, zero-dep bundled skill is the right home for it. Diagram-style
work with a *real* install cost (e.g. `hyperframes`: Node + FFmpeg + Chromium)
deliberately stays optional and is **not** folded in here.
Use a different skill when: matching a known brand's look → `popular-web-designs`; a
formal design-token spec file → `design-md`; a *bespoke visually-designed* artifact
where the look itself is the point → `claude-design`; hand-drawn/whiteboard
`.excalidraw` files → `excalidraw`; generative/animated canvas art → `p5js`. This
skill is for everything else that ships as a readable, shareable HTML page.
## Reference files (load on demand)
- `references/house-style.md` — the canonical `:root` token block, type system,
card/table/callout/code-block patterns. **Read this before authoring any artifact.**
- `references/examples.md` — 20 complete reference HTML files (Anthropic's
html-effectiveness gallery, MIT) keyed to each mode, plus the script to fetch them.
Read/fetch one that matches your task to calibrate the house style from a full example.
- `references/svg-diagrams.md` — hand-authored inline SVG: arrow markers, node
groups, decision diamonds, edge semantics, coordinate-grid discipline. Read for
any flowchart / architecture / concept diagram.
- `references/concept-archetypes.md` — the 9-ramp educational color system + a
library of diagram archetypes (timeline, tree, quadrant, layered stack,
before/after, hub-spoke, cross-section). Read for educational / non-software visuals.
- `references/dark-tech.md` — the dark "infra" token variant (carries the old
architecture-diagram aesthetic). Read for cloud/infra/system architecture diagrams.
- `references/throwaway-editors.md` — the single-file editor recipe and the
copy-to-clipboard export pattern that survives `file://`. Read when the artifact
needs interactive controls that export state back to a prompt.
- `references/fidelity-and-verify.md` — the throwaway↔presentation fidelity dial,
the multi-variant comparison layout, and the mandatory browser-vision verify loop.
## Templates
- `templates/base.html` — document scaffold with the house-style `<style>` block.
- `templates/diagram.html` — dual-mode diagram host (light educational + dark infra
CSS, arrow markers, node/edge classes). Paste your SVG where marked.
- `templates/editor.html` — throwaway-editor skeleton (state → render → export).
Load one with `skill_view(name="html-artifact", file_path="templates/base.html")`.
## Workflow
1. **Pick the mode.** Match the request to one artifact type — explainer, plan,
report, code review, diagram, variants, or editor. The mode decides which
template, which references, and which worked example to use.
2. **Read the matching example first — every time.** The 20 files in the
html-effectiveness gallery are the ground truth this skill is built on; the
prose references describe them but a full example carries density, spacing, and
structure no summary can. Before writing anything:
```
terminal: bash scripts/fetch-examples.sh # idempotent: clones if missing, else pulls
read_file references/examples/<file-for-your-mode>.html
```
`references/examples.md` has the mode→file map (e.g. code review →
`03-code-review-pr.html`, diagram → `13-flowchart-diagram.html`, editor →
`18-editor-triage-board.html`). Read at least the one example closest to your
task — two if you're combining modes. Only if the fetch genuinely fails (no
network) do you fall back to the distilled pattern references alone; note that
you're working without the examples when you do.
3. **Decide fidelity.** Throwaway exploration or presentation-grade deliverable?
See `references/fidelity-and-verify.md`. Don't over-polish a quick comparison;
don't ship a sloppy report.
4. **Start from a template + the house style.** Load `templates/base.html` (or
`diagram.html` / `editor.html`) and `references/house-style.md`. Reuse the
`:root` tokens — never invent a new palette per file. Mirror the structure of
the example you read in step 2; adapt it to the content, don't copy it verbatim.
5. **Author the artifact** with `write_file`. Keep everything inline: one `<style>`
in `<head>`, at most one `<script>` before `</body>`. No `<link>`, no external
fonts (use OS-native stacks), no CDN, no `<img src>` to remote URLs. All graphics
are inline SVG or CSS.
6. **Keep JS optional and graceful.** Prefer zero JS. When you need it, keep it to
a small vanilla IIFE and make the page render meaningfully with JS off (native
`<details>`, anchor nav, a default-active tab/node).
7. **Verify visually.** Open the file and screenshot it — see the verify loop in
`references/fidelity-and-verify.md`. This is mandatory for SVG diagrams, where
hand-placed coordinates drift on edits (overlapping nodes, misaimed arrows).
8. **Report the path.** Tell the user the absolute file path so they can open it.
Mention any interactive controls / export buttons.
## Core principles
**One design system, token-driven.** Warm paper (`--ivory`), near-black ink
(`--slate`), one terracotta accent (`--clay`), olive for success/additions, a warm
gray ramp. Semantic convention, held across every mode: **clay = focus/attention,
olive = success/added, rust = error/removed, oat = neutral fill, gray-500 =
secondary text & arrows.** Reference colors only as `var(--…)`.
**Three fonts by role.** Serif (Georgia stack) for headings, sans (system-ui) for
body, mono for every label / code / metric / eyebrow / path. All OS-native — zero
font loading. This serif-heading / mono-label / sans-body split is the house tell.
**Self-contained, always.** The file must render offline when double-clicked.
Inline the style and script; draw graphics as inline SVG or CSS; never reference a
remote asset. This is non-negotiable — it's what makes the artifact shareable.
**Graceful degradation.** Most great artifacts have *no* JS. When interactivity is
the point (sliders, drag, editors), the page must still convey its content without
JS, and exports must work from a `file://` page (clipboard fallback in
`references/throwaway-editors.md`).
**End interactive artifacts with an export.** A throwaway editor is only useful if
it hands its result back: a Copy-as-markdown / Copy-JSON / Copy-diff / Copy-prompt
button that serializes state to the clipboard for pasting into the next prompt.
## Quick reference — mode → what to build
| Request | Mode | Template | Read this example | Key reference |
|---|---|---|---|---|
| "explain how X works" | explainer | base | `14-research-feature-explainer.html` | house-style, svg-diagrams |
| "write up the plan / spec" | plan | base | `16-implementation-plan.html` | house-style |
| "status / incident report" | report | base | `11-status-report.html`, `12-incident-report.html` | house-style |
| "review this PR / diff" | code review | base | `03-code-review-pr.html`, `17-pr-writeup.html` | house-style (diff section) |
| "diagram the architecture / pipeline" | infra diagram | diagram | `13-flowchart-diagram.html`, `04-code-understanding.html` | dark-tech, svg-diagrams |
| "diagram this concept / process" (science, physical, educational) | concept diagram | diagram | `13-flowchart-diagram.html`, `10-svg-illustrations.html` | concept-archetypes, svg-diagrams |
| "show me N takes / compare options" | variants | base | `01-exploration-code-approaches.html`, `02-exploration-visual-designs.html` | fidelity-and-verify |
| "let me tune / triage / edit X and copy it out" | editor | editor | `18-editor-triage-board.html`, `19-editor-feature-flags.html`, `20-editor-prompt-tuner.html` | throwaway-editors |
## Pitfalls
- **Don't skip the example.** The single biggest quality lever is reading the
matching gallery file before you write (`bash scripts/fetch-examples.sh` then
`read_file references/examples/<file>.html`). The prose references are a map; the
examples are the territory. Authoring from memory of "what good HTML looks like"
is exactly how the output drifts generic.
- **Don't invent a palette.** Reuse the `:root` tokens from `house-style.md`. A
per-file color scheme breaks the consistency that makes these artifacts feel pro.
- **Don't reach for a library.** No Mermaid, D3, Tailwind CDN, Prism, or web fonts.
Diagrams are hand-authored SVG; syntax highlighting is hand-marked `<span>`s; the
token block does the job of a build-time theme.
- **Don't skip the visual check on diagrams.** Manually computed SVG coordinates
are the #1 source of broken output — arrows landing in whitespace, overlapping
boxes, text overflow. Screenshot and fix before reporting done.
- **Don't add a JS export where a static `<pre>` suffices.** If the deliverable is
one snippet, a hand-selectable code block is the bulletproof "export".
- **Don't let JS be load-bearing for content.** If the prose only exists inside a
`render()` call, the page is blank with JS off. Put real content in the HTML;
use JS to enhance, not to populate.

3
skills/creative/html-artifact/references/.gitignore vendored Normal file
View file

@ -0,0 +1,3 @@
# Fetched on demand by scripts/fetch-examples.sh — not committed.
# (Anthropic's html-effectiveness gallery, MIT; ~384 KB, its own git repo.)
examples/

94
skills/creative/html-artifact/references/concept-archetypes.md Normal file
View file

@ -0,0 +1,94 @@
# Concept Diagram Archetypes
For educational and non-software visuals — physics, chemistry, math, biology,
physical objects, anatomy, floor plans, lifecycles, cross-sections, hub-spoke
systems. Flat, minimal, light/dark-aware. (Carried over from the former
`concept-diagrams` skill.)
Read `svg-diagrams.md` first for arrow markers, node groups, and coordinate
discipline. This file adds the educational color system and a library of archetypes
beyond the basic flowchart.
## Design philosophy
- **Flat**: no gradients, drop shadows, blur, glow, or neon.
- **Minimal**: show the essential. No decorative icons inside boxes.
- **Sentence case always.** Never Title Case, never ALL CAPS.
- **Two font sizes only**: `th` 14px/500 for titles, `ts` 12px/400 for subtitles &
labels.
- **0.5px** stroke on node borders. `fill="none"` on every connector path.
## The 9-ramp educational color system
Color encodes **category/meaning**, never sequence. Use 2–3 ramps per diagram. Put
the class on a `<g>` or shape; the template CSS maps stops for light *and* dark mode
automatically (light: 50 fill / 600 stroke / 800 title; dark: 800 fill / 200 stroke /
100 title).
| Class | 50 | 200 | 400 | 600 | 800 |
|---|---|---|---|---|---|
| `c-purple` | #EEEDFE | #AFA9EC | #7F77DD | #534AB7 | #3C3489 |
| `c-teal` | #E1F5EE | #5DCAA5 | #1D9E75 | #0F6E56 | #085041 |
| `c-coral` | #FAECE7 | #F0997B | #D85A30 | #993C1D | #712B13 |
| `c-pink` | #FBEAF0 | #ED93B1 | #D4537E | #993556 | #72243E |
| `c-gray` | #F1EFE8 | #B4B2A9 | #888780 | #5F5E5A | #444441 |
| `c-blue` | #E6F1FB | #85B7EB | #378ADD | #185FA5 | #0C447C |
| `c-green` | #EAF3DE | #97C459 | #639922 | #3B6D11 | #27500A |
| `c-amber` | #FAEEDA | #EF9F27 | #BA7517 | #854F0B | #633806 |
| `c-red` | #FCEBEB | #F09595 | #E24B4A | #A32D2D | #791F1F |
Assignment rules: group nodes by category (same type → same color); `c-gray` for
neutral/structural (start, end, generic steps, users); reserve `c-blue`/`c-green`/
`c-amber`/`c-red` for semantic info/success/warning/error. The full template (with
the 7-stop ramps and the light/dark CSS) is `templates/diagram.html`.
## Layout constants
- ViewBox `0 0 680 H` (H = content + 40px buffer); safe area x 40→640.
- Single-line box 44px tall; two-line 56px; ≥60px gap between boxes.
- Inner padding 24px horizontal / 12px vertical. Container `rx` 16–20, node `rx` 8.
- Max nesting 2–3 levels (deeper is unreadable at 680px).
## Archetype library
Pick the shape that fits the subject. Each is hand-laid SVG using the ramps above.
**Flowchart / process** — `c-gray` start/end, one category color for steps,
`c-red` for error branches. Decision diamonds gate the flow (see `svg-diagrams.md`).
**Pipeline / data flow** (left→right) — `c-gray` sources, a category color for
processing stages, `c-teal` sinks. Straight horizontal edges on one row.
**Layered stack / exploded view** — vertical stack of full-width `<rect>`s, one ramp
stop darker per layer going down, labels to the side with leader lines. For "layers
of X" / "the N tiers of Y".
**Tree / hierarchy** — root at top center, children fanning down; edges are
`<line>`s or short Béziers. Same color per depth level.
**Quadrant / 2×2 matrix** — two crossing axis lines with arrowheads, four labeled
cells, axis labels in `ts`. For positioning / trade-off space.
**Before / after (comparison)** — two side-by-side panels sharing a column grid; use
`c-red`/`rust` accents on the "before" pain points and `c-green`/`olive` on the
"after" wins. A center divider or arrow shows the transition.
**Timeline / sequence** — a horizontal or vertical rail with dated/numbered nodes;
for UML-style sequence, vertical lifelines with horizontal message arrows labeled in
`ts`.
**Hub-spoke / system integration** — a central node with spokes to subsystems; use
distinct line styles per subsystem type (smart city, IoT, electricity grid).
**Cross-section / physical object / anatomy** — outline the object with `<path>`
(polygons, ellipses, Béziers for curves), fill regions with category colors, label
parts with `ts` + leader lines. For aircraft, turbines, cells, devices.
**Quantitative chart** — grouped bars as `<rect>`s on a baseline with axis ticks;
one ramp per series; values in `ts` above bars. Keep it flat — no 3D, no gradients.
## When to prefer this vs the dark-tech variant
Educational / scientific / physical subject → this (light, 9-ramp). Cloud / infra /
software system architecture → the dark token variant in `dark-tech.md`. When neither
fits cleanly, this educational look is the safe general-purpose default.

92
skills/creative/html-artifact/references/dark-tech.md Normal file
View file

@ -0,0 +1,92 @@
# Dark-Tech Diagram Variant
The dark "infra" aesthetic for cloud / software / system architecture diagrams —
slate-950 background, a faint grid, neon-ish category strokes. Carried over from the
former `architecture-diagram` skill (based on Cocoon AI's generator, MIT). Use this
when the subject is infrastructure or a software system; use the light 9-ramp system
in `concept-archetypes.md` for educational/physical subjects.
Read `svg-diagrams.md` for the shared structural techniques (markers, node groups,
coordinate discipline).
> **Self-contained adaptation:** the original loaded JetBrains Mono from Google Fonts.
> This skill forbids external fonts — use the OS-native `--mono` stack instead. The
> dark look is otherwise unchanged.
## Background
Slate-950 page with a subtle 40px grid:
```css
body { background: #020617; color: #e2e8f0; font-family: ui-monospace, "SF Mono", Menlo, monospace; }
.diagram-card { background: #0b1220; border: 1px solid #1e293b; border-radius: 14px; padding: 20px; }
```
```xml
<defs>
<pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse">
<path d="M 40 0 L 0 0 0 40" fill="none" stroke="#1e293b" stroke-width="0.5"/>
</pattern>
</defs>
<rect width="100%" height="100%" fill="url(#grid)"/>
```
## Semantic component palette
Fill is a translucent tint; stroke is the saturated category color:
| Component type | Fill (rgba) | Stroke (hex) |
|---|---|---|
| Frontend | `rgba(8,51,68,0.4)` | `#22d3ee` cyan |
| Backend | `rgba(6,78,59,0.4)` | `#34d399` emerald |
| Database | `rgba(76,29,149,0.4)` | `#a78bfa` violet |
| AWS / Cloud | `rgba(120,53,15,0.3)` | `#fbbf24` amber |
| Security | `rgba(136,19,55,0.4)` | `#fb7185` rose |
| Message bus | `rgba(251,146,60,0.3)` | `#fb923c` orange |
| External | `rgba(30,41,59,0.5)` | `#94a3b8` slate |
Type sizes: 12px names, 9px sublabels, 8px annotations, 7px tiny labels.
## Component rendering — double-rect mask
Semi-transparent fills let arrows show through. Mask each component with an opaque
backing rect, then the styled rect on top:
```xml
<rect x="100" y="80" width="160" height="60" rx="6" fill="#0f172a"/> <!-- opaque backing -->
<rect x="100" y="80" width="160" height="60" rx="6" fill="rgba(6,78,59,0.4)" stroke="#34d399" stroke-width="1.5"/>
<text x="180" y="114" text-anchor="middle" fill="#e2e8f0" font-size="12">API server</text>
```
Components are `rx="6"`, 1.5px strokes. Standard service height 60px; large components
80–120px; ≥40px vertical gap.
## Connections & boundaries
- **Z-order**: draw arrows *early* (right after the grid) so component boxes render on
top of them.
- **Security flows**: dashed rose lines (`stroke-dasharray="4 4"`, `#fb7185`).
- **Security group boundary**: dashed `4 4`, rose, `rx="8"`.
- **Region boundary**: large dash `8 4`, amber, `rx="12"`.
- **Message buses** go *in the gap* between services, never overlapping them.
- **Legend** (critical): place it *outside* every boundary box — compute the lowest
boundary Y and put the legend ≥20px below it.
## Document structure
Four parts: (1) header with a pulsing dot + subtitle, (2) the SVG in a rounded border
card, (3) a grid of summary info-cards below, (4) minimal footer. Pulsing dot is pure
CSS (`@keyframes`), no JS.
Info-card pattern:
```html
<div class="card">
<div class="card-header"><span class="card-dot cyan"></span><h3>Title</h3></div>
<ul><li>Item one</li><li>Item two</li></ul>
</div>
```
Pure CSS for any animation (pulsing dots) — no JavaScript. The dual-mode
`templates/diagram.html` includes this dark CSS alongside the light educational CSS;
add `class="dark"` (or use the dark `<style>` block) for infra diagrams.

64
skills/creative/html-artifact/references/examples.md Normal file
View file

@ -0,0 +1,64 @@
# Reference Examples (Anthropic html-effectiveness gallery)
Twenty complete, self-contained reference HTML files — Anthropic's
[html-effectiveness gallery](https://github.com/anthropics/html-effectiveness),
MIT licensed. These are the ground truth this skill is built on. **Reading the one
that matches your mode is a required step before authoring** (workflow step 2): a
full polished example carries density, spacing, and structure that no prose summary
reproduces. The other references explain *why* the patterns are the way they are;
these show you the patterns whole.
They are **not committed into this skill** (it's someone else's living repo, ~384 KB).
Fetch them with the bundled script — it's idempotent, so just run it every time; it
clones if the examples are missing and pulls the latest otherwise.
## Fetch + read (do this before writing)
```
terminal: bash scripts/fetch-examples.sh
read_file references/examples/<file-for-your-mode>.html
```
The script lands the files in `references/examples/`. Always run it first — it's
cheap and self-healing, so you never have to wonder whether the examples are
present. Then read the index or jump straight to the file for your mode:
```
read_file references/examples/index.html # categorized index of all 20
read_file references/examples/03-code-review-pr.html # a specific example
```
Only if the fetch genuinely fails (no network) do you fall back to the distilled
pattern references alone — and say so, since you're then working without the source.
## What each file demonstrates → which to read
Pick the example closest to your mode, read it, then adapt — don't copy verbatim.
| File | Mode | Read it when you're building… |
|---|---|---|
| `01-exploration-code-approaches.html` | variants | a side-by-side comparison of code approaches with tradeoffs + a recommendation |
| `02-exploration-visual-designs.html` | variants | live design directions on a light/dark switchable surface |
| `03-code-review-pr.html` | code review | a PR/diff review — the gold-standard 3-column diff grid + risk map + comment bubbles |
| `04-code-understanding.html` | explainer | a code-flow explainer with an inline-SVG request-path diagram + callstack |
| `05-design-system.html` | report | a design-token / component reference sheet |
| `06-component-variants.html` | editor | a live component matrix driven by `:root` custom-property knobs |
| `07-prototype-animation.html` | editor | a CSS micro-interaction tuner (easing knobs, static copy-paste CSS export) |
| `08-prototype-interaction.html` | editor | a drag-to-reorder feel-test (DOM-only, no export by design) |
| `09-slide-deck.html` | report | a scroll-snap slide deck (pure-CSS paging) |
| `10-svg-illustrations.html` | diagram | standalone exportable inline-SVG illustrations |
| `11-status-report.html` | report | a weekly status report (zero-JS, shape tokens, stat band) |
| `12-incident-report.html` | report | an incident postmortem (CSS-only timeline + checklist) |
| `13-flowchart-diagram.html` | diagram | a clickable annotated flowchart with a synced detail panel (`data-k` pattern) |
| `14-research-feature-explainer.html` | explainer | "how feature X works" — sticky anchor-nav doc shell + tabbed code |
| `15-research-concept-explainer.html` | explainer | an interactive concept explainer (deterministic-hash SVG demo + glossary) |
| `16-implementation-plan.html` | plan | an implementation plan — milestone timeline, SVG architecture, DOM mockups |
| `17-pr-writeup.html` | code review | a PR walkthrough for reviewers — file-by-file tour, hand-marked diffs, TOC |
| `18-editor-triage-board.html` | editor | a drag-to-triage board with copy-as-markdown export |
| `19-editor-feature-flags.html` | editor | a config-flag editor with copy-diff + copy-full-JSON export |
| `20-editor-prompt-tuner.html` | editor | a prompt-template editor (contenteditable + live preview + copy-prompt) |
All 20 are single-file, zero-dependency, no-build — the same discipline this skill
requires. Use them to calibrate density, spacing, and the house style; the distilled
references (`house-style.md`, `svg-diagrams.md`, `throwaway-editors.md`, …) tell you
*why* each pattern is the way it is.

78
skills/creative/html-artifact/references/fidelity-and-verify.md Normal file
View file

@ -0,0 +1,78 @@
# Fidelity and Verification
Two cross-cutting concerns: how polished to make an artifact (the fidelity dial,
carried over from the former `sketch` skill), and how to catch the broken output
before you report done (the browser-vision loop — mandatory for diagrams).
## The fidelity dial
Match effort to intent. Over-polishing a quick comparison wastes time; shipping a
sloppy report undercuts the point of using HTML at all.
**Throwaway / sketch fidelity** — fast, low-ceremony, meant to be reacted to and
discarded. Use when the user says "sketch", "rough", "show me what X could look
like", "a quick take", "compare A vs B", "mock this before I build". Signals:
- Realistic *fake* content (don't make the user imagine — fill it in).
- System fonts, the house tokens, minimal custom CSS. One or two states of
interactivity, not a full app.
- Multiple variants over one perfect screen (see below).
- Explicitly disposable: a sketch worth keeping should be promoted into real project
code, not curated as a deliverable.
**Presentation fidelity** — a real deliverable someone will read end-to-end and
share: an explainer, plan, report, PR write-up, or a diagram going into docs. Full
house style, careful spacing, verified diagrams, graceful-degradation checked.
When unsure, ask one question ("quick throwaway or polished deliverable?") rather
than guessing — the two need very different amounts of effort.
## Multi-variant comparison
When the user wants to *choose a direction*, generate 3–6 distinct variants and lay
them out for side-by-side comparison in **one** HTML file. Three proven layouts:
- **Static tradeoff columns** — equal-weight columns, each with the approach, a code
or visual sample, a small tradeoffs table, and uniform metric chips
(`Bundle: +0.2kb`, `Reuse: high`). Close with one opinionated **recommendation**.
Best for comparing *code approaches* or strategies.
- **Live artboards on a switchable surface** — a 2×N grid of `.artboard` cards each
rendering a real variant, with a light/dark toggle so each is proven on both
surfaces. Best for *visual design* directions. Per-stage theme via scoped tokens:
```css
.stage { --fg: var(--slate); --panel: var(--white); --line: var(--gray-300); }
.stage.dark { --fg: #F0EEE6; --panel: #1F1E1B; --line: #3D3D3A; }
```
Variants reference only `var(--fg/--panel/--line)`, so flipping `.dark` re-themes all.
- **Live token matrix** — a toolbar of controls (slider / segmented / checkbox) that
writes to `:root` custom properties so every variant cell updates at once. Best for
a *component* explored across a parameter space (density × border × shadow).
Always: vary layout/tone/density meaningfully (not cosmetic tweaks), label each
variant with the tradeoff it's making, and state your pick.
## The browser-vision verify loop (mandatory for diagrams)
Hand-placed SVG coordinates drift: arrows land in whitespace, boxes overlap, text
overflows its rect, the legend collides with a boundary. Static review of the markup
does **not** catch this — you must look at the rendered pixels.
1. Write the file with `write_file`.
2. Open it: `browser_navigate(url="file:///absolute/path/to/artifact.html")`.
3. Inspect it: `browser_vision(question="Are any arrows pointing into empty space?
Any overlapping boxes or text overflowing its container? Is the legend clear of
the diagram? Is anything cut off?")`. (Or `browser_screenshot` and read it.)
4. Fix what the screenshot reveals — recompute the offending coordinates, widen a
box to fit its text, bump the viewBox height, move the legend.
5. Re-render and re-check until clean.
For non-diagram artifacts (reports, plans, explainers) a single screenshot pass is
enough to catch layout breakage — overflow, broken grids, unreadable contrast,
clipped content. Always do at least one visual pass before telling the user it's done;
"it's valid HTML" is not the same as "it renders correctly".
## Graceful-degradation check
If the artifact has JS, confirm the page still conveys its content with JS disabled:
real prose lives in the HTML (not only inside a `render()` call), collapsibles use
native `<details>`, tabs default one to `.on`, interactive diagrams set a
default-active node. The artifact should never be blank without JavaScript.

179
skills/creative/html-artifact/references/house-style.md Normal file
View file

@ -0,0 +1,179 @@
# House Style
Every artifact uses one design system. Reuse these tokens verbatim — do not invent
a per-file palette. This is the single biggest lever on whether the output looks
professional or improvised.
## The canonical `:root` block
Paste this into every artifact's `<style>` (it's already in `templates/base.html`):
```css
:root {
/* surfaces */
--ivory: #FAF9F5; /* page background (warm paper) */
--white: #FFFFFF; /* cards / panels */
--slate: #141413; /* near-black text & inverted/dark panels */
/* accents (semantic — see convention below) */
--clay: #D97757; /* primary accent: focus / attention */
--olive: #788C5D; /* success / additions / "after" / done */
--rust: #B04A3F; /* error / deletions / failure path */
--oat: #E3DACC; /* warm neutral fill / highlight */
/* warm gray ramp */
--gray-150: #F0EEE6;
--gray-300: #D1CFC5;
--gray-500: #87867F; /* secondary text, arrows, muted labels */
--gray-700: #3D3D3A;
/* shape tokens */
--border: 1.5px solid var(--gray-300);
--radius-panel: 12px;
--radius-row: 8px;
--radius-pill: 999px;
/* fonts (OS-native — zero loading) */
--serif: ui-serif, Georgia, "Times New Roman", serif;
--sans: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
--mono: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
}
```
## Semantic color convention
Color encodes **meaning**, applied identically across every artifact mode:
| Token | Means |
|---|---|
| `--clay` | the thing in focus / attention / primary accent / "hot path" |
| `--olive` | success, positive delta, added lines, "after", done |
| `--rust` | error, negative, deleted lines, failure path (only add when a doc has errors) |
| `--oat` | neutral highlight / warm fill / generic badge |
| `--gray-500` | secondary text, arrowheads, muted metadata |
Never cycle colors like a rainbow. 2–3 accents per artifact.
## Type system — three fonts by role
- **Serif** (`--serif`) → all headings and big display numbers. `font-weight: 500`
(medium, never bold), `letter-spacing: -0.01em`.
- **Sans** (`--sans`) → body copy. `line-height: 1.55–1.65`.
- **Mono** (`--mono`) → every label, code, path, metric, timestamp, pill, eyebrow.
The "eyebrow" header pattern opens most docs:
```css
.eyebrow { font-family: var(--mono); font-size: 11px; letter-spacing: 0.08em;
text-transform: uppercase; color: var(--gray-500); }
h1 { font-family: var(--serif); font-weight: 500; letter-spacing: -0.01em; }
```
## Boilerplate
```css
* { margin: 0; padding: 0; box-sizing: border-box; }
body {
background: var(--ivory); color: var(--gray-700);
font-family: var(--sans); line-height: 1.6;
-webkit-font-smoothing: antialiased;
padding: 56px 24px 120px; /* generous bottom gutter */
}
.page { max-width: 860px; margin: 0 auto; } /* tune width per density */
html { scroll-behavior: smooth; }
```
**`.page` max-width by density:** 820–860px single-column reports/explainers;
1040–1120px two-column plans/PRs; ~780px for slide-inner.
## The card pattern (the workhorse)
White card on ivory, hairline border, rounded, optional accent border-left. This one
recipe produces stat cards, callouts, TL;DR boxes, panels, mockup frames:
```css
.card {
background: var(--white); border: var(--border);
border-radius: var(--radius-panel); padding: 20px;
}
.card.warn { border-left: 4px solid var(--clay); } /* or --olive / --rust */
```
## Layout
CSS Grid for structure, Flexbox for alignment. Two-column doc shell:
```css
.layout { display: grid; grid-template-columns: 220px minmax(0,1fr); gap: 40px; }
/* minmax(0,1fr) prevents the content column from overflowing */
aside { position: sticky; top: 32px; align-self: start; } /* in-page nav / TOC */
h2 { scroll-margin-top: 24px; } /* so anchor jumps clear the top */
@media (max-width: 860px) { /* the entire responsive strategy: */
.layout { grid-template-columns: 1fr; } /* collapse to one column */
aside { display: none; } /* hide the sidebar */
}
```
Stat/summary bands: `display: grid; grid-template-columns: repeat(4, 1fr);` with one
breakpoint to `repeat(2,1fr)`.
## Tables
Real `<table>` for tabular data: `border-collapse`, a `--gray-150` `<thead>` with
small uppercase mono headers, hairline row borders, wrapped in a rounded card with
`overflow: hidden` to clip the corners. Use a `display:grid` "table" of `.row`/`.cell`
divs only when cells need rich content or must restack responsively (swap
`border-left` for `border-top` at the breakpoint).
## Code blocks + hand-rolled highlighting
Code lives in a dark `--slate` rounded panel, `overflow-x: auto`, mono ~13px. No
Prism/highlight.js — wrap tokens in semantic spans:
```css
.code { background: var(--slate); color: #E8E6DF; border-radius: var(--radius-panel);
padding: 16px 18px; font-family: var(--mono); font-size: 13px; overflow-x: auto; }
.code .kw { color: var(--clay); } /* keywords */
.code .str { color: var(--olive); } /* strings */
.code .cm { color: var(--gray-500); }/* comments */
.code .fn { color: #C9B98A; } /* function names (warm tan) */
```
**Diff rendering** — a 3-column grid (line-no | mark | code) with tinted full-width
rows. Values match the gallery's `03-code-review-pr.html` verbatim:
```css
.diff-row { display: grid; grid-template-columns: 48px 18px 1fr; white-space: pre;
font-family: var(--mono); font-size: 12.5px; }
.diff-row .ln { color: var(--gray-500); text-align: right; padding-right: 10px; }
.diff-row .code { color: #E8E6DC; }
.diff-row.add { background: rgba(120,140,93,0.15); } /* olive tint */
.diff-row.add .mark { color: var(--olive); }
.diff-row.del { background: rgba(176,74,63,0.15); } /* rust tint */
.diff-row.del .mark { color: var(--rust); }
.diff-row.ctx .code { color: #B8B6AC; } /* unchanged context */
.diff-row.hunk .code { color: var(--gray-500); } /* @@ -0,0 +1,58 @@ headers */
```
## Callouts, pills, badges (pure CSS)
```css
.callout { background: rgba(217,119,87,0.06); border-left: 3px solid var(--clay);
border-radius: var(--radius-row); padding: 14px 16px; }
.pill { border-radius: var(--radius-pill); padding: 2px 10px; font-family: var(--mono);
font-size: 11px; background: var(--oat); }
.badge { border-radius: 6px; padding: 1px 7px; font-family: var(--mono); font-size: 11px; }
.badge.new { background: rgba(120,140,93,0.18); color: var(--olive); }
.badge.del { background: rgba(176,74,63,0.18); color: var(--rust); }
```
Tinted backgrounds use `rgba()` of an accent — don't add new tokens for them.
## Decoration is drawn, not imported
- **Timeline** = a `::before` vertical rail + absolutely-positioned dots, colored by state.
- **Checkbox tick** = a bordered square with an `::after` rotated-border tick when `.done`.
- **Progress bar** = a track div + a `width:%` fill div.
- **Diagrams/charts/icons** = hand-authored inline `<svg>` (see `svg-diagrams.md`).
## Spacing rhythm
Section gaps ~52–64px; element gaps on an 8 / 12 / 14 / 18 / 22px scale. Consistent
spacing is most of what reads as "designed".

123
skills/creative/html-artifact/references/svg-diagrams.md Normal file
View file

@ -0,0 +1,123 @@
# SVG Diagrams
All diagrams are hand-authored inline `<svg>` — no Mermaid, no D3, no images. This
gives full control and keeps the file self-contained. Coordinates are computed by
hand, which makes the **visual verify loop mandatory** (see `fidelity-and-verify.md`):
the #1 failure is arrows landing in whitespace or boxes overlapping after an edit.
For light/educational diagrams use the 9-ramp design system in
`concept-archetypes.md`. For cloud/infra/system architecture use the dark token
variant in `dark-tech.md`. Both share the structural techniques below.
## Arrow markers
Define once in `<defs>`. Use `context-stroke` so the arrowhead inherits its line's
color (one marker serves every edge color):
```xml
<defs>
<marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5"
markerWidth="6" markerHeight="6" orient="auto-start-reverse">
<path d="M2 1 L8 5 L2 9" fill="none" stroke="context-stroke"
stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
</marker>
</defs>
```
Apply with `marker-end="url(#arrow)"`. When you need fixed per-semantic colors
(happy/fail/success) instead of inheritance, define matched markers `#arrow`,
`#arrow-rust`, `#arrow-olive` with hard-coded `fill`.
## Node groups
A node is a `<g>` wrapping a `<rect>` and centered `<text>`. Style via CSS classes,
not inline attributes — states live in the stylesheet:
```xml
<g class="node">
<rect x="100" y="20" width="180" height="44" rx="8"/>
<text class="th" x="190" y="42" text-anchor="middle" dominant-baseline="central">Service</text>
</g>
```
```css
.node rect { fill: var(--white); stroke: var(--gray-300); stroke-width: 1.5; }
.node.hot rect { fill: rgba(217,119,87,0.10); stroke: var(--clay); } /* focus */
.node.ok rect { fill: rgba(120,140,93,0.12); stroke: var(--olive); } /* success */
.node.bad rect { fill: rgba(176,74,63,0.10); stroke: var(--rust); } /* error */
text { pointer-events: none; } /* so clicks hit the node group, not the label */
```
Two-line node: add a second `<text class="ts">` for a subtitle, 18px below the title
baseline; make the rect 56px tall.
## Decision diamonds
Gates are a `<path>` diamond, not a rect:
```xml
<path class="gate" d="M310 262 L352 294 L310 326 L268 294 Z"/>
<text x="310" y="294" text-anchor="middle" dominant-baseline="central">valid?</text>
```
## Edges and semantics
Straight edges are `<line>`; branching/failure edges are Bézier `<path>` with
`fill="none"` (SVG paths default to `fill:black`). Encode meaning in style:
```css
.edge { stroke: var(--gray-500); stroke-width: 1.5; fill: none; marker-end: url(#arrow); }
.edge.yes { stroke: var(--olive); } /* happy path */
.edge.no { stroke: var(--rust); stroke-dasharray: 4 4; } /* failure / dashed */
```
Label edges with a small mono `<text class="lbl">` near the midpoint ("pass",
"fail → 503", "retry").
## Coordinate-grid discipline
Hand-placed coordinates drift on edits. Keep them sane:
- **ViewBox**: `viewBox="0 0 W H"` where W is fixed (680 for educational, ~720–960
for infra) and H = bottom of the last element + 40px buffer. Recompute H whenever
you add rows.
- **Lanes / ranks**: put nodes on a regular grid. Pick a column x for each lane and a
fixed row pitch (e.g. rows every 90px). Reuse the same x for every node in a lane so
vertical edges are straight.
- **Gaps**: ≥60px between boxes; 10px between an arrowhead and the box it points at.
- **Wrap in scroll**: `.diagram { overflow-x: auto; } .diagram svg { min-width: 760px; }`
so wide diagrams don't squish on mobile.
- **Width check**: a box must fit its text — `box_width >= chars * px_per_char + 48`.
At 14px/weight-500 ≈ 8px/char; at 12px/weight-400 ≈ 6.5px/char.
## Interactive diagrams (optional)
To make a flowchart clickable with a synced detail panel, key each node with a
`data-k` attribute and look it up in a small JS dictionary. Always set a default-active
node on load so the panel is never empty, and keep the chart fully readable with JS off:
```js
const DETAIL = { ingest: { title: "Ingest", body: "…", code: "…" }, /* … */ };
document.querySelectorAll('.node[data-k]').forEach(n => {
n.addEventListener('click', () => {
document.querySelectorAll('.node.active').forEach(a => a.classList.remove('active'));
n.classList.add('active');
const d = DETAIL[n.dataset.k];
panel.querySelector('.t').textContent = d.title;
panel.querySelector('.b').innerHTML = d.body;
});
});
document.querySelector('.node[data-k="ingest"]').click(); // default-active
```
## Exportable standalone SVG (optional)
If the user wants the SVG as its own downloadable file, the SVG must carry its own
`<defs><style>`, its own `<marker>`, a background `<rect fill="#FAF9F5">`, and
hard-coded hex (not `var()`, which won't resolve outside the host page). Then:
```js
const blob = new Blob([new XMLSerializer().serializeToString(svg)], {type:'image/svg+xml'});
const a = Object.assign(document.createElement('a'), {href: URL.createObjectURL(blob), download:'diagram.svg'});
a.click(); URL.revokeObjectURL(a.href);
```

114
skills/creative/html-artifact/references/throwaway-editors.md Normal file
View file

@ -0,0 +1,114 @@
# Throwaway Editors
A throwaway editor is a single-file HTML UI purpose-built for one task, ending in an
**export button** that serializes its state to the clipboard so you can paste the
result back into the next prompt. Triage a backlog, tune a prompt, flip feature
flags, adjust animation params — then copy the result out as markdown / JSON / diff /
plain text.
The defining rule: **the artifact must hand its result back.** A pretty editor with
no export is useless to the workflow. (The exception: a *feel-test* prototype — a
drag-to-reorder or animation bench you only need to *experience* — can skip export.
And if the deliverable is one snippet, a static hand-selectable `<pre>` is a valid
"export"; don't add clipboard JS where selection suffices.)
## The skeleton
State → render → controls → export → feedback. `templates/editor.html` is this,
filled in:
```html
<button id="copyBtn" class="btn-primary">Copy as markdown</button>
<button id="resetBtn" class="btn-ghost">Reset</button>
<script>
const INITIAL = /* the real starting data */;
let state = structuredClone(INITIAL); // or read live from the DOM controls
function render() { /* pure function of state -> DOM; idempotent; call after every change */ }
function serialize(s) { /* return the pasteable string */ }
let timer = null;
function flash(btn, label, orig) {
btn.textContent = label; btn.classList.add("copied");
clearTimeout(timer);
timer = setTimeout(() => { btn.textContent = orig; btn.classList.remove("copied"); }, 1200);
}
copyBtn.addEventListener("click", () => {
writeClipboard(serialize(state)).then(
() => flash(copyBtn, "Copied \u2713", "Copy as markdown"),
() => flash(copyBtn, "Copied \u2713", "Copy as markdown") // flash even on reject; fallback already ran
);
});
resetBtn.addEventListener("click", () => { state = structuredClone(INITIAL); render(); });
render(); // boot
</script>
```
Conventions: a two-button toolbar (primary Copy + ghost Reset); feedback = swap text
to "Copied ✓" + `.copied` class for 1200ms, guarded by `clearTimeout`; a frozen
`INITIAL` so Reset is trivial and diffs have a baseline; serialize at click time from
current state (don't keep a parallel export buffer); recompute derived values
(counts, totals, diffs) at export time, never trust a stale summary.
## State, three ways
- **Cloned object/array** — `let state = structuredClone(INITIAL)`; mutate fields,
call `render()`. Best for drag-between-columns boards.
- **Read live from controls** — no JS state object; `currentState()` reads the
checkboxes/inputs on demand. Best for form/flag editors.
- **The editor text itself** — for a prompt/template editor, the `contenteditable`'s
text *is* the state; read it with a TreeWalker that mirrors how you insert newlines.
## The clipboard pattern that survives `file://`
`file://` pages often have `navigator.clipboard` undefined or rejected (insecure
context). This helper feature-detects, falls back to an off-screen textarea +
`execCommand`, and **always returns a Promise** so callers uniformly `.then(flash)`:
```js
function writeClipboard(text) {
if (navigator.clipboard && navigator.clipboard.writeText) {
return navigator.clipboard.writeText(text); // async API when available
}
const ta = document.createElement("textarea"); // fallback for file://
ta.value = text;
ta.style.position = "fixed"; // fixed + off-screen = no scroll jump
ta.style.left = "-9999px";
document.body.appendChild(ta);
ta.select();
try { document.execCommand("copy"); } catch (e) { /* ignore */ }
document.body.removeChild(ta);
return Promise.resolve(); // uniform return so .then() always works
}
```
Rules, in order: feature-detect; fall back to textarea + `execCommand('copy')` inside
the user-gesture handler (works synchronously on `file://`); position the textarea
off-screen; wrap `execCommand` in try/catch; always remove the textarea; normalize to
a Promise; flash on both success and reject (the fallback usually succeeded anyway).
## Export formats — pick by intent
| Format | Build with | Use when you need to… |
|---|---|---|
| **Markdown** | `lines.push(...)` → `join("\n")`; `#`/`##` headers, `- **id**` bullets | drop the result into a doc / PR / issue for humans |
| **Diff** (`-`/`+`) | compare `state` vs `INITIAL`; emit `'- "k": '+from` / `'+ "k": '+to` | apply only the changes / review intent |
| **JSON** | hand-build to preserve key order, or `JSON.stringify(state, null, 2)` | machine-parseable config to paste into a file |
| **Prompt / plain text** | read the editor text directly | feed a prompt/template/snippet back to the model |
Offer two when both reviewing and applying matter (a Copy-diff *and* a Copy-JSON
button). Hand-roll the serializer when fidelity to a target file's shape matters —
`JSON.stringify` reorders and reformats; build the string yourself to preserve grouped
key order.
## Controls
Native HTML wherever possible — `<input type=range>` (style the thumb clay),
`<input type=checkbox>` toggles, HTML5 drag-and-drop (`draggable="true"` +
`dragstart`/`dragover`/`drop`, snap the drop indicator to element midpoints),
`contenteditable` for text. Live token feedback without a tokenizer:
`Math.round(chars / 4.2)`. For sliders that retune CSS, write a custom property:
`root.style.setProperty('--ease', btn.dataset.ease)` and let the CSS reference
`var(--ease)`.

43
skills/creative/html-artifact/scripts/fetch-examples.sh Executable file
View file

@ -0,0 +1,43 @@
#!/usr/bin/env bash
# Fetch Anthropic's html-effectiveness gallery — 20 self-contained reference HTML
# files demonstrating the artifact patterns this skill teaches. MIT licensed
# (https://github.com/anthropics/html-effectiveness).
#
# Idempotent: clones on first run, pulls latest on subsequent runs. Files land in
# this skill's references/examples/ dir so you can read_file them directly.
#
# Usage: bash scripts/fetch-examples.sh
# Then: read_file references/examples/03-code-review-pr.html (etc.)
set -euo pipefail
REPO_URL="https://github.com/anthropics/html-effectiveness"
# Resolve the skill dir from this script's location (scripts/ -> skill root).
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SKILL_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
DEST="$SKILL_DIR/references/examples"
if ! command -v git >/dev/null 2>&1; then
echo "error: git is required but not found on PATH" >&2
exit 1
fi
if [ -d "$DEST/.git" ]; then
echo "Refreshing existing gallery in $DEST ..."
git -C "$DEST" pull --ff-only --quiet || {
echo "warn: pull failed; re-cloning" >&2
rm -rf "$DEST"
}
fi
if [ ! -d "$DEST/.git" ]; then
echo "Cloning $REPO_URL ..."
rm -rf "$DEST"
git clone --depth 1 --quiet "$REPO_URL" "$DEST"
fi
# Report what landed (the 20 numbered examples + index).
COUNT="$(find "$DEST" -maxdepth 1 -name '[0-9]*.html' | wc -l | tr -d ' ')"
echo "Done. $COUNT example HTML files in: $DEST"
echo "Open the index (categorized) or read any file directly:"
echo " read_file references/examples/index.html"
echo " read_file references/examples/03-code-review-pr.html"

104
skills/creative/html-artifact/templates/base.html Normal file
View file

@ -0,0 +1,104 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Artifact Title</title>
<style>
/* ---------- design tokens (reuse verbatim; do not invent a palette) ---------- */
:root {
--ivory:#FAF9F5; --white:#FFFFFF; --slate:#141413;
--clay:#D97757; --olive:#788C5D; --rust:#B04A3F; --oat:#E3DACC;
--gray-150:#F0EEE6; --gray-300:#D1CFC5; --gray-500:#87867F; --gray-700:#3D3D3A;
--border:1.5px solid var(--gray-300);
--radius-panel:12px; --radius-row:8px; --radius-pill:999px;
--serif: ui-serif, Georgia, "Times New Roman", serif;
--sans: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
--mono: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
}
* { margin:0; padding:0; box-sizing:border-box; }
html { scroll-behavior:smooth; }
body { background:var(--ivory); color:var(--gray-700); font-family:var(--sans);
line-height:1.6; -webkit-font-smoothing:antialiased; padding:56px 24px 120px; }
.page { max-width:860px; margin:0 auto; } /* 820-860 reports · 1040-1120 two-col */
/* ---------- header ---------- */
.eyebrow { font-family:var(--mono); font-size:11px; letter-spacing:.08em;
text-transform:uppercase; color:var(--gray-500); margin-bottom:10px; }
h1 { font-family:var(--serif); font-weight:500; letter-spacing:-.01em; font-size:34px; }
h2 { font-family:var(--serif); font-weight:500; font-size:22px; margin:52px 0 16px;
scroll-margin-top:24px; }
.lead { font-size:17px; color:var(--gray-700); margin-top:12px; }
/* ---------- cards / callouts ---------- */
.card { background:var(--white); border:var(--border); border-radius:var(--radius-panel);
padding:20px; }
.card.warn { border-left:4px solid var(--clay); }
.grid-4 { display:grid; grid-template-columns:repeat(4,1fr); gap:16px; margin-top:18px; }
.callout { background:rgba(217,119,87,.06); border-left:3px solid var(--clay);
border-radius:var(--radius-row); padding:14px 16px; margin:18px 0; }
/* ---------- pills / badges ---------- */
.pill { display:inline-block; border-radius:var(--radius-pill); padding:2px 10px;
font-family:var(--mono); font-size:11px; background:var(--oat); }
.badge { display:inline-block; border-radius:6px; padding:1px 7px;
font-family:var(--mono); font-size:11px; }
.badge.new { background:rgba(120,140,93,.18); color:var(--olive); }
.badge.del { background:rgba(176,74,63,.18); color:var(--rust); }
/* ---------- tables ---------- */
table { width:100%; border-collapse:collapse; background:var(--white);
border:var(--border); border-radius:var(--radius-panel); overflow:hidden; }
thead { background:var(--gray-150); }
th { font-family:var(--mono); font-size:11px; text-transform:uppercase; letter-spacing:.04em;
color:var(--gray-500); text-align:left; padding:10px 14px; }
td { padding:10px 14px; border-top:1px solid var(--gray-150); font-size:14px; }
/* ---------- code + diff ---------- */
.code { background:var(--slate); color:#E8E6DF; border-radius:var(--radius-panel);
padding:16px 18px; font-family:var(--mono); font-size:13px; overflow-x:auto; }
.code .kw{color:var(--clay)} .code .str{color:var(--olive)}
.code .cm{color:var(--gray-500)} .code .fn{color:#C9B98A}
.diff-row { display:grid; grid-template-columns:48px 18px 1fr; white-space:pre;
font-family:var(--mono); font-size:12.5px; }
.diff-row.add { background:rgba(120,140,93,.15); } .diff-row.add .mark{color:var(--olive)}
.diff-row.del { background:rgba(176,74,63,.15); } .diff-row.del .mark{color:var(--rust)}
.diff-row.ctx .code-cell { color:#B8B6AC; }
/* ---------- two-column doc shell (optional) ---------- */
.layout { display:grid; grid-template-columns:220px minmax(0,1fr); gap:40px; }
aside { position:sticky; top:32px; align-self:start; }
aside a { display:block; color:var(--gray-500); text-decoration:none; padding:4px 0;
border-left:2px solid transparent; padding-left:10px; font-size:14px; }
aside a:hover { color:var(--clay); border-left-color:var(--clay); }
/* ---------- the entire responsive strategy ---------- */
@media (max-width:860px) {
.layout { grid-template-columns:1fr; } aside { display:none; }
.grid-4 { grid-template-columns:repeat(2,1fr); }
}
</style>
</head>
<body>
<div class="page">
<p class="eyebrow">Section · Context</p>
<h1>Artifact Title</h1>
<p class="lead">One-sentence framing of what this artifact is and who it's for.</p>
<h2 id="overview">Overview</h2>
<p>Body copy. Keep paragraphs readable; let layout carry structure.</p>
<div class="grid-4">
<div class="card"><p class="eyebrow">Metric</p><strong style="font-family:var(--serif);font-size:26px">42</strong></div>
<div class="card"><p class="eyebrow">Metric</p><strong style="font-family:var(--serif);font-size:26px">7</strong></div>
<div class="card warn"><p class="eyebrow">Needs attention</p><strong style="font-family:var(--serif);font-size:26px">3</strong></div>
<div class="card"><p class="eyebrow">Metric</p><strong style="font-family:var(--serif);font-size:26px">98%</strong></div>
</div>
<div class="callout"><strong>Note.</strong> Use callouts for the one thing the reader must not miss.</div>
<!-- Add sections per mode: tables, .code blocks, inline <svg> diagrams (see svg-diagrams.md). -->
<!-- Keep JS optional: native <details> for collapsibles, anchor links for nav. -->
</div>
</body>
</html>

127
skills/creative/html-artifact/templates/diagram.html Normal file
View file

@ -0,0 +1,127 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Diagram</title>
<!--
Dual-mode diagram host.
· LIGHT / EDUCATIONAL mode (default): the 9-ramp c-* design system below. Use for
science, physical objects, processes, anatomy, lifecycles. See concept-archetypes.md.
· DARK / INFRA mode: add <body class="infra"> and use the .infra-* classes at the
bottom for cloud/software/system architecture. See dark-tech.md.
Paste your hand-authored <svg> where marked. Include the shared <defs> arrow marker
(see svg-diagrams.md) inside your SVG.
-->
<style>
:root {
--text-primary:#1a1a18; --text-secondary:#5f5e5a; --text-tertiary:#88877f;
--bg-primary:#ffffff; --bg-secondary:#f6f5f0; --bg-tertiary:#eeedeb;
--border:rgba(0,0,0,0.15); --border-hover:rgba(0,0,0,0.3);
}
@media (prefers-color-scheme: dark) {
:root {
--text-primary:#e8e6de; --text-secondary:#b4b2a9; --text-tertiary:#888780;
--bg-primary:#1a1a18; --bg-secondary:#2c2c2a; --bg-tertiary:#3d3d3a;
--border:rgba(255,255,255,0.15); --border-hover:rgba(255,255,255,0.3);
}
}
* { margin:0; padding:0; box-sizing:border-box; }
body { font-family:system-ui,-apple-system,sans-serif; background:var(--bg-tertiary);
display:flex; justify-content:center; align-items:flex-start; min-height:100vh; padding:40px 20px; }
.card { background:var(--bg-primary); border-radius:16px; padding:32px; max-width:780px;
width:100%; box-shadow:0 1px 3px rgba(0,0,0,0.08); }
h1 { font-size:18px; font-weight:500; color:var(--text-primary); margin-bottom:8px; }
.subtitle { font-size:13px; color:var(--text-tertiary); margin-bottom:24px; }
svg { width:100%; height:auto; }
/* === SVG design system: text === */
.t { font-family:system-ui,-apple-system,sans-serif; font-size:14px; fill:var(--text-primary); }
.ts { font-family:system-ui,-apple-system,sans-serif; font-size:12px; fill:var(--text-secondary); }
.th { font-family:system-ui,-apple-system,sans-serif; font-size:14px; fill:var(--text-primary); font-weight:500; }
/* neutral box / arrow / leader / node */
.box { fill:var(--bg-secondary); stroke:var(--border); stroke-width:0.5px; }
.arr { stroke:var(--text-secondary); stroke-width:1.5px; fill:none; }
.leader { stroke:var(--text-tertiary); stroke-width:0.5px; stroke-dasharray:4 3; fill:none; }
.node { cursor:pointer; transition:opacity 0.15s; }
.node:hover { opacity:0.82; }
/* === 9 color ramps (light mode) — color encodes category, not sequence === */
.c-purple > rect, .c-purple > circle, .c-purple > ellipse { fill:#EEEDFE; stroke:#534AB7; }
.c-purple > .th, .c-purple > text.th { fill:#3C3489; } .c-purple > .ts, .c-purple > text.ts { fill:#534AB7; } .c-purple > .t, .c-purple > text.t { fill:#3C3489; }
.c-teal > rect, .c-teal > circle, .c-teal > ellipse { fill:#E1F5EE; stroke:#0F6E56; }
.c-teal > .th, .c-teal > text.th { fill:#085041; } .c-teal > .ts, .c-teal > text.ts { fill:#0F6E56; } .c-teal > .t, .c-teal > text.t { fill:#085041; }
.c-coral > rect, .c-coral > circle, .c-coral > ellipse { fill:#FAECE7; stroke:#993C1D; }
.c-coral > .th, .c-coral > text.th { fill:#712B13; } .c-coral > .ts, .c-coral > text.ts { fill:#993C1D; } .c-coral > .t, .c-coral > text.t { fill:#712B13; }
.c-pink > rect, .c-pink > circle, .c-pink > ellipse { fill:#FBEAF0; stroke:#993556; }
.c-pink > .th, .c-pink > text.th { fill:#72243E; } .c-pink > .ts, .c-pink > text.ts { fill:#993556; } .c-pink > .t, .c-pink > text.t { fill:#72243E; }
.c-gray > rect, .c-gray > circle, .c-gray > ellipse { fill:#F1EFE8; stroke:#5F5E5A; }
.c-gray > .th, .c-gray > text.th { fill:#444441; } .c-gray > .ts, .c-gray > text.ts { fill:#5F5E5A; } .c-gray > .t, .c-gray > text.t { fill:#444441; }
.c-blue > rect, .c-blue > circle, .c-blue > ellipse { fill:#E6F1FB; stroke:#185FA5; }
.c-blue > .th, .c-blue > text.th { fill:#0C447C; } .c-blue > .ts, .c-blue > text.ts { fill:#185FA5; } .c-blue > .t, .c-blue > text.t { fill:#0C447C; }
.c-green > rect, .c-green > circle, .c-green > ellipse { fill:#EAF3DE; stroke:#3B6D11; }
.c-green > .th, .c-green > text.th { fill:#27500A; } .c-green > .ts, .c-green > text.ts { fill:#3B6D11; } .c-green > .t, .c-green > text.t { fill:#27500A; }
.c-amber > rect, .c-amber > circle, .c-amber > ellipse { fill:#FAEEDA; stroke:#854F0B; }
.c-amber > .th, .c-amber > text.th { fill:#633806; } .c-amber > .ts, .c-amber > text.ts { fill:#854F0B; } .c-amber > .t, .c-amber > text.t { fill:#633806; }
.c-red > rect, .c-red > circle, .c-red > ellipse { fill:#FCEBEB; stroke:#A32D2D; }
.c-red > .th, .c-red > text.th { fill:#791F1F; } .c-red > .ts, .c-red > text.ts { fill:#A32D2D; } .c-red > .t, .c-red > text.t { fill:#791F1F; }
/* === ramps: dark mode === */
@media (prefers-color-scheme: dark) {
.c-purple > rect, .c-purple > circle, .c-purple > ellipse { fill:#3C3489; stroke:#AFA9EC; } .c-purple > .th, .c-purple > text.th { fill:#CECBF6; } .c-purple > .ts, .c-purple > text.ts { fill:#AFA9EC; }
.c-teal > rect, .c-teal > circle, .c-teal > ellipse { fill:#085041; stroke:#5DCAA5; } .c-teal > .th, .c-teal > text.th { fill:#9FE1CB; } .c-teal > .ts, .c-teal > text.ts { fill:#5DCAA5; }
.c-coral > rect, .c-coral > circle, .c-coral > ellipse { fill:#712B13; stroke:#F0997B; } .c-coral > .th, .c-coral > text.th { fill:#F5C4B3; } .c-coral > .ts, .c-coral > text.ts { fill:#F0997B; }
.c-pink > rect, .c-pink > circle, .c-pink > ellipse { fill:#72243E; stroke:#ED93B1; } .c-pink > .th, .c-pink > text.th { fill:#F4C0D1; } .c-pink > .ts, .c-pink > text.ts { fill:#ED93B1; }
.c-gray > rect, .c-gray > circle, .c-gray > ellipse { fill:#444441; stroke:#B4B2A9; } .c-gray > .th, .c-gray > text.th { fill:#D3D1C7; } .c-gray > .ts, .c-gray > text.ts { fill:#B4B2A9; }
.c-blue > rect, .c-blue > circle, .c-blue > ellipse { fill:#0C447C; stroke:#85B7EB; } .c-blue > .th, .c-blue > text.th { fill:#B5D4F4; } .c-blue > .ts, .c-blue > text.ts { fill:#85B7EB; }
.c-green > rect, .c-green > circle, .c-green > ellipse { fill:#27500A; stroke:#97C459; } .c-green > .th, .c-green > text.th { fill:#C0DD97; } .c-green > .ts, .c-green > text.ts { fill:#97C459; }
.c-amber > rect, .c-amber > circle, .c-amber > ellipse { fill:#633806; stroke:#EF9F27; } .c-amber > .th, .c-amber > text.th { fill:#FAC775; } .c-amber > .ts, .c-amber > text.ts { fill:#EF9F27; }
.c-red > rect, .c-red > circle, .c-red > ellipse { fill:#791F1F; stroke:#F09595; } .c-red > .th, .c-red > text.th { fill:#F7C1C1; } .c-red > .ts, .c-red > text.ts { fill:#F09595; }
}
/* ============================================================
DARK / INFRA mode — add <body class="infra"> to activate.
Slate-950 background, faint grid, neon category strokes. See dark-tech.md.
============================================================ */
body.infra { background:#020617; }
body.infra .card { background:#0b1220; border:1px solid #1e293b; box-shadow:none; }
body.infra h1 { color:#e2e8f0; } body.infra .subtitle { color:#64748b; }
body.infra .grid-bg { fill:url(#infra-grid); }
/* infra category strokes (apply .infra-frontend etc. to a <g>; pair an opaque
backing rect with the translucent fill rect — the double-rect mask) */
.infra-frontend > rect.fill { fill:rgba(8,51,68,0.4); stroke:#22d3ee; }
.infra-backend > rect.fill { fill:rgba(6,78,59,0.4); stroke:#34d399; }
.infra-db > rect.fill { fill:rgba(76,29,149,0.4);stroke:#a78bfa; }
.infra-cloud > rect.fill { fill:rgba(120,53,15,0.3);stroke:#fbbf24; }
.infra-security > rect.fill { fill:rgba(136,19,55,0.4);stroke:#fb7185; }
.infra-bus > rect.fill { fill:rgba(251,146,60,0.3);stroke:#fb923c; }
.infra-external > rect.fill { fill:rgba(30,41,59,0.5); stroke:#94a3b8; }
body.infra .infra-frontend text, body.infra .infra-backend text, body.infra .infra-db text,
body.infra .infra-cloud text, body.infra .infra-security text, body.infra .infra-bus text,
body.infra .infra-external text { fill:#e2e8f0; }
body.infra rect.fill { rx:6; stroke-width:1.5; }
</style>
</head>
<body>
<!-- For infra diagrams: <body class="infra"> -->
<div class="card">
<h1><!-- DIAGRAM TITLE HERE --></h1>
<p class="subtitle"><!-- OPTIONAL SUBTITLE HERE --></p>
<!-- PASTE SVG HERE. Start it with the shared arrow marker:
<svg width="100%" viewBox="0 0 680 H" xmlns="http://www.w3.org/2000/svg">
<defs>
<marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
<path d="M2 1 L8 5 L2 9" fill="none" stroke="context-stroke" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
</marker>
For infra mode also add:
<pattern id="infra-grid" width="40" height="40" patternUnits="userSpaceOnUse">
<path d="M 40 0 L 0 0 0 40" fill="none" stroke="#1e293b" stroke-width="0.5"/>
</pattern>
</defs>
... nodes / edges ...
</svg>
-->
</div>
</body>
</html>

120
skills/creative/html-artifact/templates/editor.html Normal file
View file

@ -0,0 +1,120 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Editor</title>
<!--
Throwaway-editor skeleton: state -> render -> controls -> export -> feedback.
Replace INITIAL, render(), serialize(), and the controls with your task.
The export ends in a clipboard copy that survives file:// (see throwaway-editors.md).
This example is a tiny tag-toggle editor that copies a markdown summary.
-->
<style>
:root {
--ivory:#FAF9F5; --white:#FFFFFF; --slate:#141413; --clay:#D97757; --olive:#788C5D;
--oat:#E3DACC; --gray-300:#D1CFC5; --gray-500:#87867F; --gray-700:#3D3D3A;
--border:1.5px solid var(--gray-300); --radius:10px;
--serif: ui-serif, Georgia, serif; --sans: system-ui,-apple-system,sans-serif;
--mono: ui-monospace,"SF Mono",Menlo,monospace;
}
* { margin:0; padding:0; box-sizing:border-box; }
body { background:var(--ivory); color:var(--gray-700); font-family:var(--sans);
line-height:1.6; padding:48px 24px; }
.page { max-width:720px; margin:0 auto; }
.eyebrow { font-family:var(--mono); font-size:11px; letter-spacing:.08em; text-transform:uppercase;
color:var(--gray-500); }
h1 { font-family:var(--serif); font-weight:500; font-size:28px; margin:8px 0 24px; }
.row { display:flex; align-items:center; gap:10px; padding:12px 14px; background:var(--white);
border:var(--border); border-radius:var(--radius); margin-bottom:8px; }
.row label { flex:1; }
.toolbar { display:flex; gap:10px; margin-top:24px; }
button { font-family:var(--mono); font-size:13px; padding:9px 16px; border-radius:var(--radius);
cursor:pointer; border:var(--border); background:var(--white); color:var(--gray-700); }
.btn-primary { background:var(--slate); color:var(--ivory); border-color:var(--slate); }
.btn-primary.copied { background:var(--olive); border-color:var(--olive); }
</style>
</head>
<body>
<div class="page">
<p class="eyebrow">Throwaway editor</p>
<h1>Toggle what ships, copy the result</h1>
<div id="list"></div>
<div class="toolbar">
<button id="copyBtn" class="btn-primary">Copy as markdown</button>
<button id="resetBtn">Reset</button>
</div>
</div>
<script>
(function () {
// ---- DATA: the frozen starting state ----
var INITIAL = [
{ id: "auth", label: "Auth rewrite", ship: true },
{ id: "billing", label: "Billing webhooks", ship: true },
{ id: "search", label: "Search reindex", ship: false },
{ id: "exports", label: "CSV exports", ship: false }
];
var state = structuredClone(INITIAL);
var list = document.getElementById("list");
// ---- RENDER: pure function of state -> DOM ----
function render() {
list.innerHTML = "";
state.forEach(function (item) {
var row = document.createElement("div"); row.className = "row";
var cb = document.createElement("input"); cb.type = "checkbox"; cb.checked = item.ship;
cb.addEventListener("change", function () { item.ship = cb.checked; }); // mutate state
var lab = document.createElement("label"); lab.textContent = item.label;
row.appendChild(cb); row.appendChild(lab);
list.appendChild(row);
});
}
// ---- SERIALIZE: state -> pasteable string (recompute derived values here) ----
function serialize(s) {
var shipping = s.filter(function (i) { return i.ship; });
var holding = s.filter(function (i) { return !i.ship; });
var lines = ["# Ship plan", "", "## Shipping (" + shipping.length + ")", ""];
shipping.forEach(function (i) { lines.push("- " + i.label); });
lines.push("", "## Holding (" + holding.length + ")", "");
holding.forEach(function (i) { lines.push("- " + i.label); });
return lines.join("\n");
}
// ---- EXPORT: clipboard that survives file:// (always returns a Promise) ----
function writeClipboard(text) {
if (navigator.clipboard && navigator.clipboard.writeText) {
return navigator.clipboard.writeText(text);
}
var ta = document.createElement("textarea");
ta.value = text; ta.style.position = "fixed"; ta.style.left = "-9999px";
document.body.appendChild(ta); ta.select();
try { document.execCommand("copy"); } catch (e) { /* ignore */ }
document.body.removeChild(ta);
return Promise.resolve();
}
var copyBtn = document.getElementById("copyBtn");
var timer = null;
function flash() {
copyBtn.textContent = "Copied \u2713"; copyBtn.classList.add("copied");
clearTimeout(timer);
timer = setTimeout(function () {
copyBtn.textContent = "Copy as markdown"; copyBtn.classList.remove("copied");
}, 1200);
}
copyBtn.addEventListener("click", function () {
writeClipboard(serialize(state)).then(flash, flash); // flash on success OR reject
});
document.getElementById("resetBtn").addEventListener("click", function () {
state = structuredClone(INITIAL); render();
});
render(); // boot
})();
</script>
</body>
</html>

2
skills/creative/pretext/SKILL.md
View file

@ -8,7 +8,7 @@ platforms: [linux, macos, windows]
metadata:
hermes:
tags: [creative-coding, typography, pretext, ascii-art, canvas, generative, text-layout, kinetic-typography]
related_skills: [p5js, claude-design, excalidraw, architecture-diagram]
related_skills: [p5js, claude-design, excalidraw, html-artifact]
---
# Pretext Creative Demos

218
skills/creative/sketch/SKILL.md
View file

@ -1,218 +0,0 @@
---
name: sketch
description: "Throwaway HTML mockups: 2-3 design variants to compare."
version: 1.0.0
author: Hermes Agent (adapted from gsd-build/get-shit-done)
license: MIT
platforms: [linux, macos, windows]
metadata:
hermes:
tags: [sketch, mockup, design, ui, prototype, html, variants, exploration, wireframe, comparison]
related_skills: [spike, claude-design, popular-web-designs, excalidraw]
---
# Sketch
Use this skill when the user wants to **see a design direction before committing** to one — exploring a UI/UX idea as disposable HTML mockups. The point is to generate 2-3 interactive variants so the user can compare visual directions side-by-side, not to produce shippable code.
Load this when the user says things like "sketch this screen", "show me what X could look like", "compare layout A vs B", "give me 2-3 takes on this UI", "let me see some variants", "mockup this before I build".
## When NOT to use this
- User wants a production component — use `claude-design` or build it properly
- User wants a polished one-off HTML artifact (landing page, deck) — `claude-design`
- User wants a diagram — `excalidraw`, `architecture-diagram`
- The design is already locked — just build it
## If the user has the full GSD system installed
If `gsd-sketch` shows up as a sibling skill (installed via `npx get-shit-done-cc --hermes`), prefer **`gsd-sketch`** for the full workflow: persistent `.planning/sketches/` with MANIFEST, frontier mode analysis, consistency audits across past sketches, and integration with the rest of GSD. This skill is the lightweight standalone version — one-off sketching without the state machinery.
## Core method
```
intake → variants → head-to-head → pick winner (or iterate)
```
### 1. Intake (skip if the user already gave you enough)
Before generating variants, get three things — one question at a time, not all at once:
1. **Feel.** "What should this feel like? Adjectives, emotions, a vibe." — *"calm, editorial, like Linear"* tells you more than *"minimal"*.
2. **References.** "What apps, sites, or products capture the feel you're imagining?" — actual references beat abstract descriptions.
3. **Core action.** "What's the single most important thing a user does on this screen?" — the variants should all serve this well; if they don't, they're just decoration.
Reflect each answer briefly before the next question. If the user already gave you all three upfront, skip straight to variants.
### 2. Variants (2-3, never 1, rarely 4+)
Produce **2-3 variants** in one go. Each variant is a complete, standalone HTML file. Don't describe variants — build them. The point is comparison.
Each variant should take a **different design stance**, not different pixel values. Three good variant axes:
- **Density:** compact / airy / ultra-dense (pick two contrasting poles)
- **Emphasis:** content-first / action-first / tool-first
- **Aesthetic:** editorial / utilitarian / playful
- **Layout:** single-column / sidebar / split-pane
- **Grounding:** card-based / bare-content / document-style
Pick one axis and pull apart from it. Two variants that differ only in accent color are wasted effort — the user can't distinguish them.
**Variant naming:** describe the stance, not the number.
```
sketches/
├── 001-calm-editorial/
│ ├── index.html
│ └── README.md
├── 001-utilitarian-dense/
│ ├── index.html
│ └── README.md
└── 001-playful-split/
├── index.html
└── README.md
```
### 3. Make them real HTML
Each variant is a **single self-contained HTML file**:
- Inline `<style>` — no build step, no external CSS
- System fonts or one Google Font via `<link>`
- Tailwind via CDN (`<script src="https://cdn.tailwindcss.com"></script>`) is fine
- Realistic fake content — actual sentences, actual names, not "Lorem ipsum"
- **Interactive**: links clickable, hovers real, at least one state transition (open/close, filter, toggle). A frozen static image is a worse spike than a sloppy animated one.
Open it in a browser. If it looks broken, fix it before showing the user.
**Verify variants visually — use Hermes' browser tools.** Don't just write HTML and hope it renders; load each variant and look at it:
```
browser_navigate(url="file:///absolute/path/to/sketches/001-calm-editorial/index.html")
browser_vision(question="Does this layout look clean and readable? Any visible bugs (overlapping text, unstyled elements, broken images)?")
```
`browser_vision` returns an AI description of what's actually on the page plus a screenshot path — catches layout bugs that pure source inspection misses (e.g. a font import that silently failed, a flex container that collapsed). Fix and re-navigate until each variant looks right.
**Default CSS reset + system font stack** for fast starts:
```html
<style>
* { box-sizing: border-box; margin: 0; padding: 0; }
body {
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
"Helvetica Neue", Arial, sans-serif;
-webkit-font-smoothing: antialiased;
color: #1a1a1a;
background: #fafafa;
line-height: 1.5;
}
</style>
```
### 4. Variant README
Each variant's `README.md` answers:
```markdown
## Variant: {stance name}
### Design stance
One sentence on the principle driving this variant.
### Key choices
- Layout: ...
- Typography: ...
- Color: ...
- Interaction: ...
### Trade-offs
- Strong at: ...
- Weak at: ...
### Best for
- The kind of user or use case this variant actually serves
```
### 5. Head-to-head
After all variants are built, present them as a comparison. Don't just list — **opinionate**:
```markdown
## Three takes on the home screen
| Dimension | Calm editorial | Utilitarian dense | Playful split |
|-----------|----------------|-------------------|---------------|
| Density | Low | High | Medium |
| Primary action visibility | Low | High | Medium |
| Scan-ability | High | Medium | Low |
| Feel | Calm, trusted | Sharp, tool-like | Inviting, energetic |
**My take:** Utilitarian dense for power users, calm editorial for content-forward audiences. Playful split is weakest — tries to do both and commits to neither.
```
Let the user pick a winner, or combine two into a hybrid, or ask for another round.
## Theming (when the project has a visual identity)
If the user has an existing theme (colors, fonts, tokens), put shared tokens in `sketches/themes/tokens.css` and `@import` them in each variant. Keep tokens minimal:
```css
/* sketches/themes/tokens.css */
:root {
--color-bg: #fafafa;
--color-fg: #1a1a1a;
--color-accent: #0066ff;
--color-muted: #666;
--radius: 8px;
--font-display: "Inter", sans-serif;
--font-body: -apple-system, BlinkMacSystemFont, sans-serif;
}
```
Don't over-tokenize a throwaway sketch — three colors and one font is usually enough.
## Interactivity bar
A sketch is interactive enough when the user can:
1. **Click a primary action** and something visible happens (state change, modal, toast, navigation feint)
2. **See one meaningful state transition** (filter a list, toggle a mode, open/close a panel)
3. **Hover recognizable affordances** (buttons, rows, tabs)
More than that is over-engineering a throwaway. Less than that is a screenshot.
## Frontier mode (picking what to sketch next)
If sketches already exist and the user says "what should I sketch next?":
- **Consistency gaps** — two winning variants from different sketches made independent choices that haven't been composed together yet
- **Unsketched screens** — referenced but never explored
- **State coverage** — happy path sketched, but not empty / loading / error / 1000-items
- **Responsive gaps** — validated at one viewport; does it hold at mobile / ultrawide?
- **Interaction patterns** — static layouts exist; transitions, drag, scroll behavior don't
Propose 2-4 named candidates. Let the user pick.
## Output
- Create `sketches/` (or `.planning/sketches/` if the user is using GSD conventions) in the repo root
- One subdir per variant: `NNN-stance-name/index.html` + `README.md`
- Tell the user how to open them: `open sketches/001-calm-editorial/index.html` on macOS, `xdg-open` on Linux, `start` on Windows
- Keep variants disposable — a sketch that you felt the need to preserve should be promoted into real project code, not curated as an asset
**Typical tool sequence for one variant:**
```
terminal("mkdir -p sketches/001-calm-editorial")
write_file("sketches/001-calm-editorial/index.html", "<!doctype html>...")
write_file("sketches/001-calm-editorial/README.md", "## Variant: Calm editorial\n...")
browser_navigate(url="file://$(pwd)/sketches/001-calm-editorial/index.html")
browser_vision(question="How does this look? Any obvious layout issues?")
```
Repeat for each variant, then present the comparison table.
## Attribution
Adapted from the GSD (Get Shit Done) project's `/gsd-sketch` workflow — MIT © 2025 Lex Christopherson ([gsd-build/get-shit-done](https://github.com/gsd-build/get-shit-done)). The full GSD system ships persistent sketch state, theme/variant pattern references, and consistency-audit workflows; install with `npx get-shit-done-cc --hermes --global`.

2
skills/software-development/spike/SKILL.md
View file

@ -8,7 +8,7 @@ platforms: [linux, macos, windows]
metadata:
hermes:
tags: [spike, prototype, experiment, feasibility, throwaway, exploration, research, planning, mvp, proof-of-concept]
related_skills: [sketch, subagent-driven-development, plan]
related_skills: [html-artifact, subagent-driven-development, plan]
---
# Spike

1
website/docs/reference/optional-skills-catalog.md
View file

@ -58,7 +58,6 @@ hermes skills uninstall <skill-name>
| [**baoyu-article-illustrator**](/docs/user-guide/skills/optional/creative/creative-baoyu-article-illustrator) | Article illustrations: type × style × palette consistency. |
| [**baoyu-comic**](/docs/user-guide/skills/optional/creative/creative-baoyu-comic) | Knowledge comics (知识漫画): educational, biography, tutorial. |
| [**blender-mcp**](/docs/user-guide/skills/optional/creative/creative-blender-mcp) | Control Blender directly from Hermes via socket connection to the blender-mcp addon. Create 3D objects, materials, animations, and run arbitrary Blender Python (bpy) code. Use when user wants to create or modify anything in Blender. |
| [**concept-diagrams**](/docs/user-guide/skills/optional/creative/creative-concept-diagrams) | Generate flat, minimal light/dark-aware SVG diagrams as standalone HTML files, using a unified educational visual language with 9 semantic color ramps, sentence-case typography, and automatic dark mode. Best suited for educational and no... |
| [**ideation**](/docs/user-guide/skills/optional/creative/creative-creative-ideation) | Generate project ideas via creative constraints. |
| [**hyperframes**](/docs/user-guide/skills/optional/creative/creative-hyperframes) | Create HTML-based video compositions, animated title cards, social overlays, captioned talking-head videos, audio-reactive visuals, and shader transitions using HyperFrames. HTML is the source of truth for video. Use when the user wants... |
| [**kanban-video-orchestrator**](/docs/user-guide/skills/optional/creative/creative-kanban-video-orchestrator) | Plan, set up, and monitor a multi-agent video production pipeline backed by Hermes Kanban. Use when the user wants to make ANY video — narrative film, product/marketing, music video, explainer, ASCII/terminal art, abstract/generative loo... |

3
website/docs/reference/skills-catalog.md
View file

@ -35,7 +35,6 @@ If a skill is missing from this list but present in the repo, the catalog is reg
| Skill | Description | Path |
|-------|-------------|------|
| [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram) | Dark-themed SVG architecture/cloud/infra diagrams as HTML. | `creative/architecture-diagram` |
| [`ascii-art`](/docs/user-guide/skills/bundled/creative/creative-ascii-art) | ASCII art: pyfiglet, cowsay, boxes, image-to-ascii. | `creative/ascii-art` |
| [`ascii-video`](/docs/user-guide/skills/bundled/creative/creative-ascii-video) | ASCII video: convert video/audio to colored ASCII MP4/GIF. | `creative/ascii-video` |
| [`baoyu-infographic`](/docs/user-guide/skills/bundled/creative/creative-baoyu-infographic) | Infographics: 21 layouts x 21 styles (信息图, 可视化). | `creative/baoyu-infographic` |
@ -43,12 +42,12 @@ If a skill is missing from this list but present in the repo, the catalog is reg
| [`comfyui`](/docs/user-guide/skills/bundled/creative/creative-comfyui) | Generate images, video, and audio with ComfyUI — install, launch, manage nodes/models, run workflows with parameter injection. Uses the official comfy-cli for lifecycle and direct REST/WebSocket API for execution. | `creative/comfyui` |
| [`design-md`](/docs/user-guide/skills/bundled/creative/creative-design-md) | Author/validate/export Google's DESIGN.md token spec files. | `creative/design-md` |
| [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw) | Hand-drawn Excalidraw JSON diagrams (arch, flow, seq). | `creative/excalidraw` |
| [`html-artifact`](/docs/user-guide/skills/bundled/creative/creative-html-artifact) | Build self-contained HTML files to explain, plan, or review. | `creative/html-artifact` |
| [`humanizer`](/docs/user-guide/skills/bundled/creative/creative-humanizer) | Humanize text: strip AI-isms and add real voice. | `creative/humanizer` |
| [`manim-video`](/docs/user-guide/skills/bundled/creative/creative-manim-video) | Manim CE animations: 3Blue1Brown math/algo videos. | `creative/manim-video` |
| [`p5js`](/docs/user-guide/skills/bundled/creative/creative-p5js) | p5.js sketches: gen art, shaders, interactive, 3D. | `creative/p5js` |
| [`popular-web-designs`](/docs/user-guide/skills/bundled/creative/creative-popular-web-designs) | 54 real design systems (Stripe, Linear, Vercel) as HTML/CSS. | `creative/popular-web-designs` |
| [`pretext`](/docs/user-guide/skills/bundled/creative/creative-pretext) | Use when building creative browser demos with @chenglou/pretext — DOM-free text layout for ASCII art, typographic flow around obstacles, text-as-geometry games, kinetic typography, and text-powered generative art. Produces single-file HT... | `creative/pretext` |
| [`sketch`](/docs/user-guide/skills/bundled/creative/creative-sketch) | Throwaway HTML mockups: 2-3 design variants to compare. | `creative/sketch` |
| [`songwriting-and-ai-music`](/docs/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music) | Songwriting craft and Suno AI music prompts. | `creative/songwriting-and-ai-music` |
| [`touchdesigner-mcp`](/docs/user-guide/skills/bundled/creative/creative-touchdesigner-mcp) | Control a running TouchDesigner instance via twozero MCP — create operators, set parameters, wire connections, execute Python, build real-time visuals. 36 native tools. | `creative/touchdesigner-mcp` |

4
website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md
View file

@ -360,7 +360,7 @@ The registry of record is `hermes_cli/commands.py` — every consumer
```
~/.hermes/config.yaml Main configuration
~/.hermes/.env API keys and secrets
~/.hermes/.env API keys and secrets (under $HERMES_HOME if set)
$HERMES_HOME/skills/ Installed skills
~/.hermes/sessions/ Gateway routing index, request dumps, *.jsonl transcripts (and optional per-session JSON snapshots when sessions.write_json_snapshots: true)
~/.hermes/state.db Canonical session store (SQLite + FTS5)
@ -927,7 +927,7 @@ hermes-agent/
```
<!-- ascii-guard-ignore-end -->
Config: `~/.hermes/config.yaml` (settings), `~/.hermes/.env` (API keys).
Config: `~/.hermes/config.yaml` (settings), `~/.hermes/.env` (API keys) — both under `$HERMES_HOME` when it is set.
### Adding a Tool (3 files)

165
website/docs/user-guide/skills/bundled/creative/creative-architecture-diagram.md
View file

@ -1,165 +0,0 @@
---
title: "Architecture Diagram — Dark-themed SVG architecture/cloud/infra diagrams as HTML"
sidebar_label: "Architecture Diagram"
description: "Dark-themed SVG architecture/cloud/infra diagrams as HTML"
---
{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
# Architecture Diagram
Dark-themed SVG architecture/cloud/infra diagrams as HTML.
## Skill metadata
| | |
|---|---|
| Source | Bundled (installed by default) |
| Path | `skills/creative/architecture-diagram` |
| Version | `1.0.0` |
| Author | Cocoon AI (hello@cocoon-ai.com), ported by Hermes Agent |
| License | MIT |
| Platforms | linux, macos, windows |
| Tags | `architecture`, `diagrams`, `SVG`, `HTML`, `visualization`, `infrastructure`, `cloud` |
| Related skills | [`concept-diagrams`](/docs/user-guide/skills/optional/creative/creative-concept-diagrams), [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw) |
## Reference: full SKILL.md
:::info
The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
:::
# Architecture Diagram Skill
Generate professional, dark-themed technical architecture diagrams as standalone HTML files with inline SVG graphics. No external tools, no API keys, no rendering libraries — just write the HTML file and open it in a browser.
## Scope
**Best suited for:**
- Software system architecture (frontend / backend / database layers)
- Cloud infrastructure (VPC, regions, subnets, managed services)
- Microservice / service-mesh topology
- Database + API map, deployment diagrams
- Anything with a tech-infra subject that fits a dark, grid-backed aesthetic
**Look elsewhere first for:**
- Physics, chemistry, math, biology, or other scientific subjects
- Physical objects (vehicles, hardware, anatomy, cross-sections)
- Floor plans, narrative journeys, educational / textbook-style visuals
- Hand-drawn whiteboard sketches (consider `excalidraw`)
- Animated explainers (consider an animation skill)
If a more specialized skill is available for the subject, prefer that. If none fits, this skill can also serve as a general SVG diagram fallback — the output will just carry the dark tech aesthetic described below.
Based on [Cocoon AI's architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) (MIT).
## Workflow
1. User describes their system architecture (components, connections, technologies)
2. Generate the HTML file following the design system below
3. Save with `write_file` to a `.html` file (e.g. `~/architecture-diagram.html`)
4. User opens in any browser — works offline, no dependencies
### Output Location
Save diagrams to a user-specified path, or default to the current working directory:
```
./[project-name]-architecture.html
```
### Preview
After saving, suggest the user open it:
```bash
# macOS
open ./my-architecture.html
# Linux
xdg-open ./my-architecture.html
```
## Design System & Visual Language
### Color Palette (Semantic Mapping)
Use specific `rgba` fills and hex strokes to categorize components:
| Component Type | Fill (rgba) | Stroke (Hex) |
| :--- | :--- | :--- |
| **Frontend** | `rgba(8, 51, 68, 0.4)` | `#22d3ee` (cyan-400) |
| **Backend** | `rgba(6, 78, 59, 0.4)` | `#34d399` (emerald-400) |
| **Database** | `rgba(76, 29, 149, 0.4)` | `#a78bfa` (violet-400) |
| **AWS/Cloud** | `rgba(120, 53, 15, 0.3)` | `#fbbf24` (amber-400) |
| **Security** | `rgba(136, 19, 55, 0.4)` | `#fb7185` (rose-400) |
| **Message Bus** | `rgba(251, 146, 60, 0.3)` | `#fb923c` (orange-400) |
| **External** | `rgba(30, 41, 59, 0.5)` | `#94a3b8` (slate-400) |
### Typography & Background
- **Font:** JetBrains Mono (Monospace), loaded from Google Fonts
- **Sizes:** 12px (Names), 9px (Sublabels), 8px (Annotations), 7px (Tiny labels)
- **Background:** Slate-950 (`#020617`) with a subtle 40px grid pattern
```svg
<!-- Background Grid Pattern -->
<pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse">
<path d="M 40 0 L 0 0 0 40" fill="none" stroke="#1e293b" stroke-width="0.5"/>
</pattern>
```
## Technical Implementation Details
### Component Rendering
Components are rounded rectangles (`rx="6"`) with 1.5px strokes. To prevent arrows from showing through semi-transparent fills, use a **double-rect masking technique**:
1. Draw an opaque background rect (`#0f172a`)
2. Draw the semi-transparent styled rect on top
### Connection Rules
- **Z-Order:** Draw arrows *early* in the SVG (after the grid) so they render behind component boxes
- **Arrowheads:** Defined via SVG markers
- **Security Flows:** Use dashed lines in rose color (`#fb7185`)
- **Boundaries:**
- *Security Groups:* Dashed (`4,4`), rose color
- *Regions:* Large dashed (`8,4`), amber color, `rx="12"`
### Spacing & Layout Logic
- **Standard Height:** 60px (Services); 80-120px (Large components)
- **Vertical Gap:** Minimum 40px between components
- **Message Buses:** Must be placed *in the gap* between services, not overlapping them
- **Legend Placement:** **CRITICAL.** Must be placed outside all boundary boxes. Calculate the lowest Y-coordinate of all boundaries and place the legend at least 20px below it.
## Document Structure
The generated HTML file follows a four-part layout:
1. **Header:** Title with a pulsing dot indicator and subtitle
2. **Main SVG:** The diagram contained within a rounded border card
3. **Summary Cards:** A grid of three cards below the diagram for high-level details
4. **Footer:** Minimal metadata
### Info Card Pattern
```html
<div class="card">
<div class="card-header">
<div class="card-dot cyan"></div>
<h3>Title</h3>
</div>
<ul>
<li>• Item one</li>
<li>• Item two</li>
</ul>
</div>
```
## Output Requirements
- **Single File:** One self-contained `.html` file
- **No External Dependencies:** All CSS and SVG must be inline (except Google Fonts)
- **No JavaScript:** Use pure CSS for any animations (like pulsing dots)
- **Compatibility:** Must render correctly in any modern web browser
## Template Reference
Load the full HTML template for the exact structure, CSS, and SVG component examples:
```
skill_view(name="architecture-diagram", file_path="templates/template.html")
```
The template contains working examples of every component type (frontend, backend, database, cloud, security), arrow styles (standard, dashed, curved), security groups, region boundaries, and the legend — use it as your structural reference when generating diagrams.

12
website/docs/user-guide/skills/bundled/creative/creative-claude-design.md
View file

@ -21,7 +21,7 @@ Design one-off HTML artifacts (landing, deck, prototype).
| License | MIT |
| Platforms | linux, macos, windows |
| Tags | `design`, `html`, `prototype`, `ux`, `ui`, `creative`, `artifact`, `deck`, `motion`, `design-system` |
| Related skills | [`design-md`](/docs/user-guide/skills/bundled/creative/creative-design-md), [`popular-web-designs`](/docs/user-guide/skills/bundled/creative/creative-popular-web-designs), [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw), [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram) |
| Related skills | [`html-artifact`](/docs/user-guide/skills/bundled/creative/creative-html-artifact), [`design-md`](/docs/user-guide/skills/bundled/creative/creative-design-md), [`popular-web-designs`](/docs/user-guide/skills/bundled/creative/creative-popular-web-designs), [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw) |
## Reference: full SKILL.md
@ -37,19 +37,21 @@ The goal is to preserve Claude Design's useful design behavior and taste while r
**Before starting, check for other web-design skills like `popular-web-designs` (ready-to-paste design systems for Stripe, Linear, Vercel, Notion, etc.) and `design-md` (Google's DESIGN.md token spec format).** If the user wants a known brand's look, load `popular-web-designs` alongside this one and let it supply the visual vocabulary. If the deliverable is a token spec file rather than a rendered artifact, use `design-md` instead. Full decision table below.
## When To Use This Skill vs `popular-web-designs` vs `design-md`
## When To Use This Skill vs `html-artifact` vs `popular-web-designs` vs `design-md`
Hermes has three design-related skills under `skills/creative/`. They do different jobs — load the right one (or combine them):
Several skills produce HTML — they do different jobs. Load the right one (or combine them):
| Skill | What it gives you | Use when the user wants... |
|---|---|---|
| **claude-design** (this one) | Design *process and taste* — how to scope a brief, gather context, produce variants, verify a local HTML artifact, avoid AI-design slop | a from-scratch designed artifact (landing page, prototype, deck, component lab, motion study) with no specific brand or token system dictated |
| **claude-design** (this one) | Visual design *process and taste* — how to scope a brief, gather context, produce variants, verify a local HTML artifact, avoid AI-design slop | a from-scratch *designed* artifact (landing page, prototype, deck, component lab, motion study) where the look itself is the point and no specific brand or token system is dictated |
| **html-artifact** | A house style for *information* artifacts — explainers, plans, reports, code reviews, technical/educational diagrams, throwaway editors | to *explain / plan / report / diagram / review* something as a shareable HTML page — the content is the point, not bespoke visual design |
| **popular-web-designs** | 54 ready-to-paste design systems — exact colors, typography, components, CSS values for sites like Stripe, Linear, Vercel, Notion, Airbnb | "make it look like Stripe / Linear / Vercel", a page styled after a known brand, or a visual starting point pulled from a real product |
| **design-md** | Google's DESIGN.md spec format — author/validate/diff/export design-token files, WCAG contrast checking, Tailwind/DTCG export | a formal, persistent, machine-readable design-system *spec file* (tokens + rationale) that lives in a repo and gets consumed by agents over time |
Rule of thumb:
- **Process + taste, one-off artifact** → claude-design
- **Bespoke visual design, taste-driven artifact** → claude-design
- **Explain / plan / report / diagram as a shareable page** → html-artifact
- **Match a known brand's look** → popular-web-designs (and let claude-design drive the process)
- **Author the tokens spec itself** → design-md

2
website/docs/user-guide/skills/bundled/creative/creative-design-md.md
View file

@ -21,7 +21,7 @@ Author/validate/export Google's DESIGN.md token spec files.
| License | MIT |
| Platforms | linux, macos, windows |
| Tags | `design`, `design-system`, `tokens`, `ui`, `accessibility`, `wcag`, `tailwind`, `dtcg`, `google` |
| Related skills | [`popular-web-designs`](/docs/user-guide/skills/bundled/creative/creative-popular-web-designs), [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design), [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw), [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram) |
| Related skills | [`popular-web-designs`](/docs/user-guide/skills/bundled/creative/creative-popular-web-designs), [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design), [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw), [`html-artifact`](/docs/user-guide/skills/bundled/creative/creative-html-artifact) |
## Reference: full SKILL.md

202
website/docs/user-guide/skills/bundled/creative/creative-html-artifact.md Normal file
View file

@ -0,0 +1,202 @@
---
title: "Html Artifact — Build self-contained HTML files to explain, plan, or review"
sidebar_label: "Html Artifact"
description: "Build self-contained HTML files to explain, plan, or review"
---
{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
# Html Artifact
Build self-contained HTML files to explain, plan, or review.
## Skill metadata
| | |
|---|---|
| Source | Bundled (installed by default) |
| Path | `skills/creative/html-artifact` |
| Version | `1.0.0` |
| Author | Anthropic (html-effectiveness gallery, MIT), adapted for Hermes Agent |
| License | MIT |
| Platforms | linux, macos, windows |
| Tags | `html`, `artifact`, `explainer`, `plan`, `report`, `code-review`, `diagram`, `svg`, `design`, `prototype`, `editor` |
| Related skills | [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design), [`popular-web-designs`](/docs/user-guide/skills/bundled/creative/creative-popular-web-designs), [`design-md`](/docs/user-guide/skills/bundled/creative/creative-design-md), [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw), [`p5js`](/docs/user-guide/skills/bundled/creative/creative-p5js) |
## Reference: full SKILL.md
:::info
The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
:::
# HTML Artifact Skill
Produce a single self-contained `.html` file — no build step, no dependencies, no
CDN — whenever the deliverable is something a human should *read, share, or poke at*:
a concept explainer, an implementation plan, a status/incident report, a code-review
walkthrough, a technical or educational diagram, a set of design variants, or a
throwaway editor that exports its result back to you.
HTML beats Markdown once a doc has color, layout, diagrams, tables, code, or
interaction. It opens in any browser, shares as a link, stays readable past 100
lines, and can carry SVG diagrams and live controls Markdown can't. Default to an
HTML artifact when the user says "make an HTML file/artifact", or asks you to
*explain how X works*, *write up a plan/PR/report*, *diagram* something, *compare*
options, or *prototype* an interaction — even when they don't say "HTML".
## Why this skill exists (and what it replaced)
This skill **supersedes** three former skills — `sketch` (throwaway multi-variant
HTML mockups), `architecture-diagram` (dark-tech infra SVG), and `concept-diagrams`
(educational SVG). They were consolidated for a concrete reason: all three emitted
the *same artifact* — a single self-contained HTML file with inline CSS/SVG — and
overlapped heavily (three "diagram" skills, two "compare variants" paths, no shared
token system). Folding them into one mode-switched skill removes the
which-one-do-I-load ambiguity and gives every output the same house style, while
keeping each skill's unique value: the fidelity dial + verify loop (from `sketch`),
the dark infra aesthetic (from `architecture-diagram`), and the 9-ramp educational
system + archetype library (from `concept-diagrams`).
The consolidation is footprint-safe: this skill has **zero dependencies** (no Node,
FFmpeg, Chromium, or pip packages — it authors plain HTML/CSS/SVG), so even though it
ships **bundled** (active by default) where `concept-diagrams` was optional, the only
always-in-context cost is this skill's one-line description. All references,
templates, and the example gallery load on demand. `concept-diagrams` was optional
because it was niche, not because it had an install cost — promoting that capability
into a general-purpose, zero-dep bundled skill is the right home for it. Diagram-style
work with a *real* install cost (e.g. `hyperframes`: Node + FFmpeg + Chromium)
deliberately stays optional and is **not** folded in here.
Use a different skill when: matching a known brand's look → `popular-web-designs`; a
formal design-token spec file → `design-md`; a *bespoke visually-designed* artifact
where the look itself is the point → `claude-design`; hand-drawn/whiteboard
`.excalidraw` files → `excalidraw`; generative/animated canvas art → `p5js`. This
skill is for everything else that ships as a readable, shareable HTML page.
## Reference files (load on demand)
- `references/house-style.md` — the canonical `:root` token block, type system,
card/table/callout/code-block patterns. **Read this before authoring any artifact.**
- `references/examples.md` — 20 complete reference HTML files (Anthropic's
html-effectiveness gallery, MIT) keyed to each mode, plus the script to fetch them.
Read/fetch one that matches your task to calibrate the house style from a full example.
- `references/svg-diagrams.md` — hand-authored inline SVG: arrow markers, node
groups, decision diamonds, edge semantics, coordinate-grid discipline. Read for
any flowchart / architecture / concept diagram.
- `references/concept-archetypes.md` — the 9-ramp educational color system + a
library of diagram archetypes (timeline, tree, quadrant, layered stack,
before/after, hub-spoke, cross-section). Read for educational / non-software visuals.
- `references/dark-tech.md` — the dark "infra" token variant (carries the old
architecture-diagram aesthetic). Read for cloud/infra/system architecture diagrams.
- `references/throwaway-editors.md` — the single-file editor recipe and the
copy-to-clipboard export pattern that survives `file://`. Read when the artifact
needs interactive controls that export state back to a prompt.
- `references/fidelity-and-verify.md` — the throwaway↔presentation fidelity dial,
the multi-variant comparison layout, and the mandatory browser-vision verify loop.
## Templates
- `templates/base.html` — document scaffold with the house-style `<style>` block.
- `templates/diagram.html` — dual-mode diagram host (light educational + dark infra
CSS, arrow markers, node/edge classes). Paste your SVG where marked.
- `templates/editor.html` — throwaway-editor skeleton (state → render → export).
Load one with `skill_view(name="html-artifact", file_path="templates/base.html")`.
## Workflow
1. **Pick the mode.** Match the request to one artifact type — explainer, plan,
report, code review, diagram, variants, or editor. The mode decides which
template, which references, and which worked example to use.
2. **Read the matching example first — every time.** The 20 files in the
html-effectiveness gallery are the ground truth this skill is built on; the
prose references describe them but a full example carries density, spacing, and
structure no summary can. Before writing anything:
```
terminal: bash scripts/fetch-examples.sh # idempotent: clones if missing, else pulls
read_file references/examples/<file-for-your-mode>.html
```
`references/examples.md` has the mode→file map (e.g. code review →
`03-code-review-pr.html`, diagram → `13-flowchart-diagram.html`, editor →
`18-editor-triage-board.html`). Read at least the one example closest to your
task — two if you're combining modes. Only if the fetch genuinely fails (no
network) do you fall back to the distilled pattern references alone; note that
you're working without the examples when you do.
3. **Decide fidelity.** Throwaway exploration or presentation-grade deliverable?
See `references/fidelity-and-verify.md`. Don't over-polish a quick comparison;
don't ship a sloppy report.
4. **Start from a template + the house style.** Load `templates/base.html` (or
`diagram.html` / `editor.html`) and `references/house-style.md`. Reuse the
`:root` tokens — never invent a new palette per file. Mirror the structure of
the example you read in step 2; adapt it to the content, don't copy it verbatim.
5. **Author the artifact** with `write_file`. Keep everything inline: one `<style>`
in `<head>`, at most one `<script>` before `</body>`. No `<link>`, no external
fonts (use OS-native stacks), no CDN, no `<img src>` to remote URLs. All graphics
are inline SVG or CSS.
6. **Keep JS optional and graceful.** Prefer zero JS. When you need it, keep it to
a small vanilla IIFE and make the page render meaningfully with JS off (native
`<details>`, anchor nav, a default-active tab/node).
7. **Verify visually.** Open the file and screenshot it — see the verify loop in
`references/fidelity-and-verify.md`. This is mandatory for SVG diagrams, where
hand-placed coordinates drift on edits (overlapping nodes, misaimed arrows).
8. **Report the path.** Tell the user the absolute file path so they can open it.
Mention any interactive controls / export buttons.
## Core principles
**One design system, token-driven.** Warm paper (`--ivory`), near-black ink
(`--slate`), one terracotta accent (`--clay`), olive for success/additions, a warm
gray ramp. Semantic convention, held across every mode: **clay = focus/attention,
olive = success/added, rust = error/removed, oat = neutral fill, gray-500 =
secondary text & arrows.** Reference colors only as `var(--…)`.
**Three fonts by role.** Serif (Georgia stack) for headings, sans (system-ui) for
body, mono for every label / code / metric / eyebrow / path. All OS-native — zero
font loading. This serif-heading / mono-label / sans-body split is the house tell.
**Self-contained, always.** The file must render offline when double-clicked.
Inline the style and script; draw graphics as inline SVG or CSS; never reference a
remote asset. This is non-negotiable — it's what makes the artifact shareable.
**Graceful degradation.** Most great artifacts have *no* JS. When interactivity is
the point (sliders, drag, editors), the page must still convey its content without
JS, and exports must work from a `file://` page (clipboard fallback in
`references/throwaway-editors.md`).
**End interactive artifacts with an export.** A throwaway editor is only useful if
it hands its result back: a Copy-as-markdown / Copy-JSON / Copy-diff / Copy-prompt
button that serializes state to the clipboard for pasting into the next prompt.
## Quick reference — mode → what to build
| Request | Mode | Template | Read this example | Key reference |
|---|---|---|---|---|
| "explain how X works" | explainer | base | `14-research-feature-explainer.html` | house-style, svg-diagrams |
| "write up the plan / spec" | plan | base | `16-implementation-plan.html` | house-style |
| "status / incident report" | report | base | `11-status-report.html`, `12-incident-report.html` | house-style |
| "review this PR / diff" | code review | base | `03-code-review-pr.html`, `17-pr-writeup.html` | house-style (diff section) |
| "diagram the architecture / pipeline" | infra diagram | diagram | `13-flowchart-diagram.html`, `04-code-understanding.html` | dark-tech, svg-diagrams |
| "diagram this concept / process" (science, physical, educational) | concept diagram | diagram | `13-flowchart-diagram.html`, `10-svg-illustrations.html` | concept-archetypes, svg-diagrams |
| "show me N takes / compare options" | variants | base | `01-exploration-code-approaches.html`, `02-exploration-visual-designs.html` | fidelity-and-verify |
| "let me tune / triage / edit X and copy it out" | editor | editor | `18-editor-triage-board.html`, `19-editor-feature-flags.html`, `20-editor-prompt-tuner.html` | throwaway-editors |
## Pitfalls
- **Don't skip the example.** The single biggest quality lever is reading the
matching gallery file before you write (`bash scripts/fetch-examples.sh` then
`read_file references/examples/<file>.html`). The prose references are a map; the
examples are the territory. Authoring from memory of "what good HTML looks like"
is exactly how the output drifts generic.
- **Don't invent a palette.** Reuse the `:root` tokens from `house-style.md`. A
per-file color scheme breaks the consistency that makes these artifacts feel pro.
- **Don't reach for a library.** No Mermaid, D3, Tailwind CDN, Prism, or web fonts.
Diagrams are hand-authored SVG; syntax highlighting is hand-marked `<span>`s; the
token block does the job of a build-time theme.
- **Don't skip the visual check on diagrams.** Manually computed SVG coordinates
are the #1 source of broken output — arrows landing in whitespace, overlapping
boxes, text overflow. Screenshot and fix before reporting done.
- **Don't add a JS export where a static `<pre>` suffices.** If the deliverable is
one snippet, a hand-selectable code block is the bulletproof "export".
- **Don't let JS be load-bearing for content.** If the prose only exists inside a
`render()` call, the page is blank with JS off. Put real content in the HTML;
use JS to enhance, not to populate.

2
website/docs/user-guide/skills/bundled/creative/creative-pretext.md
View file

@ -21,7 +21,7 @@ Use when building creative browser demos with @chenglou/pretext — DOM-free tex
| License | MIT |
| Platforms | linux, macos, windows |
| Tags | `creative-coding`, `typography`, `pretext`, `ascii-art`, `canvas`, `generative`, `text-layout`, `kinetic-typography` |
| Related skills | [`p5js`](/docs/user-guide/skills/bundled/creative/creative-p5js), [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design), [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw), [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram) |
| Related skills | [`p5js`](/docs/user-guide/skills/bundled/creative/creative-p5js), [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design), [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw), [`html-artifact`](/docs/user-guide/skills/bundled/creative/creative-html-artifact) |
## Reference: full SKILL.md

238
website/docs/user-guide/skills/bundled/creative/creative-sketch.md
View file

@ -1,238 +0,0 @@
---
title: "Sketch — Throwaway HTML mockups: 2-3 design variants to compare"
sidebar_label: "Sketch"
description: "Throwaway HTML mockups: 2-3 design variants to compare"
---
{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
# Sketch
Throwaway HTML mockups: 2-3 design variants to compare.
## Skill metadata
| | |
|---|---|
| Source | Bundled (installed by default) |
| Path | `skills/creative/sketch` |
| Version | `1.0.0` |
| Author | Hermes Agent (adapted from gsd-build/get-shit-done) |
| License | MIT |
| Platforms | linux, macos, windows |
| Tags | `sketch`, `mockup`, `design`, `ui`, `prototype`, `html`, `variants`, `exploration`, `wireframe`, `comparison` |
| Related skills | [`spike`](/docs/user-guide/skills/bundled/software-development/software-development-spike), [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design), [`popular-web-designs`](/docs/user-guide/skills/bundled/creative/creative-popular-web-designs), [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw) |
## Reference: full SKILL.md
:::info
The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
:::
# Sketch
Use this skill when the user wants to **see a design direction before committing** to one — exploring a UI/UX idea as disposable HTML mockups. The point is to generate 2-3 interactive variants so the user can compare visual directions side-by-side, not to produce shippable code.
Load this when the user says things like "sketch this screen", "show me what X could look like", "compare layout A vs B", "give me 2-3 takes on this UI", "let me see some variants", "mockup this before I build".
## When NOT to use this
- User wants a production component — use `claude-design` or build it properly
- User wants a polished one-off HTML artifact (landing page, deck) — `claude-design`
- User wants a diagram — `excalidraw`, `architecture-diagram`
- The design is already locked — just build it
## If the user has the full GSD system installed
If `gsd-sketch` shows up as a sibling skill (installed via `npx get-shit-done-cc --hermes`), prefer **`gsd-sketch`** for the full workflow: persistent `.planning/sketches/` with MANIFEST, frontier mode analysis, consistency audits across past sketches, and integration with the rest of GSD. This skill is the lightweight standalone version — one-off sketching without the state machinery.
## Core method
```
intake → variants → head-to-head → pick winner (or iterate)
```
### 1. Intake (skip if the user already gave you enough)
Before generating variants, get three things — one question at a time, not all at once:
1. **Feel.** "What should this feel like? Adjectives, emotions, a vibe." — *"calm, editorial, like Linear"* tells you more than *"minimal"*.
2. **References.** "What apps, sites, or products capture the feel you're imagining?" — actual references beat abstract descriptions.
3. **Core action.** "What's the single most important thing a user does on this screen?" — the variants should all serve this well; if they don't, they're just decoration.
Reflect each answer briefly before the next question. If the user already gave you all three upfront, skip straight to variants.
### 2. Variants (2-3, never 1, rarely 4+)
Produce **2-3 variants** in one go. Each variant is a complete, standalone HTML file. Don't describe variants — build them. The point is comparison.
Each variant should take a **different design stance**, not different pixel values. Three good variant axes:
- **Density:** compact / airy / ultra-dense (pick two contrasting poles)
- **Emphasis:** content-first / action-first / tool-first
- **Aesthetic:** editorial / utilitarian / playful
- **Layout:** single-column / sidebar / split-pane
- **Grounding:** card-based / bare-content / document-style
Pick one axis and pull apart from it. Two variants that differ only in accent color are wasted effort — the user can't distinguish them.
**Variant naming:** describe the stance, not the number.
<!-- ascii-guard-ignore -->
```
sketches/
├── 001-calm-editorial/
│ ├── index.html
│ └── README.md
├── 001-utilitarian-dense/
│ ├── index.html
│ └── README.md
└── 001-playful-split/
├── index.html
└── README.md
```
<!-- ascii-guard-ignore-end -->
### 3. Make them real HTML
Each variant is a **single self-contained HTML file**:
- Inline `<style>` — no build step, no external CSS
- System fonts or one Google Font via `<link>`
- Tailwind via CDN (`<script src="https://cdn.tailwindcss.com"></script>`) is fine
- Realistic fake content — actual sentences, actual names, not "Lorem ipsum"
- **Interactive**: links clickable, hovers real, at least one state transition (open/close, filter, toggle). A frozen static image is a worse spike than a sloppy animated one.
Open it in a browser. If it looks broken, fix it before showing the user.
**Verify variants visually — use Hermes' browser tools.** Don't just write HTML and hope it renders; load each variant and look at it:
```
browser_navigate(url="file:///absolute/path/to/sketches/001-calm-editorial/index.html")
browser_vision(question="Does this layout look clean and readable? Any visible bugs (overlapping text, unstyled elements, broken images)?")
```
`browser_vision` returns an AI description of what's actually on the page plus a screenshot path — catches layout bugs that pure source inspection misses (e.g. a font import that silently failed, a flex container that collapsed). Fix and re-navigate until each variant looks right.
**Default CSS reset + system font stack** for fast starts:
```html
<style>
* { box-sizing: border-box; margin: 0; padding: 0; }
body {
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
"Helvetica Neue", Arial, sans-serif;
-webkit-font-smoothing: antialiased;
color: #1a1a1a;
background: #fafafa;
line-height: 1.5;
}
</style>
```
### 4. Variant README
Each variant's `README.md` answers:
```markdown
## Variant: {stance name}
### Design stance
One sentence on the principle driving this variant.
### Key choices
- Layout: ...
- Typography: ...
- Color: ...
- Interaction: ...
### Trade-offs
- Strong at: ...
- Weak at: ...
### Best for
- The kind of user or use case this variant actually serves
```
### 5. Head-to-head
After all variants are built, present them as a comparison. Don't just list — **opinionate**:
```markdown
## Three takes on the home screen
| Dimension | Calm editorial | Utilitarian dense | Playful split |
|-----------|----------------|-------------------|---------------|
| Density | Low | High | Medium |
| Primary action visibility | Low | High | Medium |
| Scan-ability | High | Medium | Low |
| Feel | Calm, trusted | Sharp, tool-like | Inviting, energetic |
**My take:** Utilitarian dense for power users, calm editorial for content-forward audiences. Playful split is weakest — tries to do both and commits to neither.
```
Let the user pick a winner, or combine two into a hybrid, or ask for another round.
## Theming (when the project has a visual identity)
If the user has an existing theme (colors, fonts, tokens), put shared tokens in `sketches/themes/tokens.css` and `@import` them in each variant. Keep tokens minimal:
```css
/* sketches/themes/tokens.css */
:root {
--color-bg: #fafafa;
--color-fg: #1a1a1a;
--color-accent: #0066ff;
--color-muted: #666;
--radius: 8px;
--font-display: "Inter", sans-serif;
--font-body: -apple-system, BlinkMacSystemFont, sans-serif;
}
```
Don't over-tokenize a throwaway sketch — three colors and one font is usually enough.
## Interactivity bar
A sketch is interactive enough when the user can:
1. **Click a primary action** and something visible happens (state change, modal, toast, navigation feint)
2. **See one meaningful state transition** (filter a list, toggle a mode, open/close a panel)
3. **Hover recognizable affordances** (buttons, rows, tabs)
More than that is over-engineering a throwaway. Less than that is a screenshot.
## Frontier mode (picking what to sketch next)
If sketches already exist and the user says "what should I sketch next?":
- **Consistency gaps** — two winning variants from different sketches made independent choices that haven't been composed together yet
- **Unsketched screens** — referenced but never explored
- **State coverage** — happy path sketched, but not empty / loading / error / 1000-items
- **Responsive gaps** — validated at one viewport; does it hold at mobile / ultrawide?
- **Interaction patterns** — static layouts exist; transitions, drag, scroll behavior don't
Propose 2-4 named candidates. Let the user pick.
## Output
- Create `sketches/` (or `.planning/sketches/` if the user is using GSD conventions) in the repo root
- One subdir per variant: `NNN-stance-name/index.html` + `README.md`
- Tell the user how to open them: `open sketches/001-calm-editorial/index.html` on macOS, `xdg-open` on Linux, `start` on Windows
- Keep variants disposable — a sketch that you felt the need to preserve should be promoted into real project code, not curated as an asset
**Typical tool sequence for one variant:**
```
terminal("mkdir -p sketches/001-calm-editorial")
write_file("sketches/001-calm-editorial/index.html", "<!doctype html>...")
write_file("sketches/001-calm-editorial/README.md", "## Variant: Calm editorial\n...")
browser_navigate(url="file://$(pwd)/sketches/001-calm-editorial/index.html")
browser_vision(question="How does this look? Any obvious layout issues?")
```
Repeat for each variant, then present the comparison table.
## Attribution
Adapted from the GSD (Get Shit Done) project's `/gsd-sketch` workflow — MIT © 2025 Lex Christopherson ([gsd-build/get-shit-done](https://github.com/gsd-build/get-shit-done)). The full GSD system ships persistent sketch state, theme/variant pattern references, and consistency-audit workflows; install with `npx get-shit-done-cc --hermes --global`.

2
website/docs/user-guide/skills/bundled/creative/creative-touchdesigner-mcp.md
View file

@ -21,7 +21,7 @@ Control a running TouchDesigner instance via twozero MCP — create operators, s
| License | MIT |
| Platforms | linux, macos, windows |
| Tags | `TouchDesigner`, `MCP`, `twozero`, `creative-coding`, `real-time-visuals`, `generative-art`, `audio-reactive`, `VJ`, `installation`, `GLSL` |
| Related skills | [`native-mcp`](/docs/user-guide/skills/bundled/mcp/mcp-native-mcp), [`ascii-video`](/docs/user-guide/skills/bundled/creative/creative-ascii-video), [`manim-video`](/docs/user-guide/skills/bundled/creative/creative-manim-video), `hermes-video` |
| Related skills | `native-mcp`, [`ascii-video`](/docs/user-guide/skills/bundled/creative/creative-ascii-video), [`manim-video`](/docs/user-guide/skills/bundled/creative/creative-manim-video), `hermes-video` |
## Reference: full SKILL.md

5
website/docs/user-guide/skills/bundled/email/email-himalaya.md
View file

@ -32,6 +32,11 @@ The following is the complete skill definition that Hermes loads when this skill
Himalaya is a CLI email client that lets you manage emails from the terminal using IMAP, SMTP, Notmuch, or Sendmail backends.
This skill is separate from the Hermes Email gateway adapter. The gateway
adapter lets people email the agent and uses Hermes' built-in IMAP/SMTP
adapter; this skill lets the agent operate a mailbox from terminal tools and
requires the external `himalaya` CLI.
## References
- `references/configuration.md` (config file setup + IMAP/SMTP authentication)

4
website/docs/user-guide/skills/bundled/github/github-github-auth.md
View file

@ -238,8 +238,8 @@ if command -v gh &>/dev/null && gh auth status &>/dev/null; then
echo "AUTH_METHOD=gh"
elif [ -n "$GITHUB_TOKEN" ]; then
echo "AUTH_METHOD=curl"
elif [ -f ~/.hermes/.env ] && grep -q "^GITHUB_TOKEN=" ~/.hermes/.env; then
export GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" ~/.hermes/.env | head -1 | cut -d= -f2 | tr -d '\n\r')
elif _hermes_env="${HERMES_HOME:-$HOME/.hermes}/.env"; [ -f "$_hermes_env" ] && grep -q "^GITHUB_TOKEN=" "$_hermes_env"; then
export GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" "$_hermes_env" | head -1 | cut -d= -f2 | tr -d '\n\r')
echo "AUTH_METHOD=curl"
elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
export GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')

4
website/docs/user-guide/skills/bundled/github/github-github-code-review.md
View file

@ -46,8 +46,8 @@ if command -v gh &>/dev/null && gh auth status &>/dev/null; then
else
AUTH="git"
if [ -z "$GITHUB_TOKEN" ]; then
if [ -f ~/.hermes/.env ] && grep -q "^GITHUB_TOKEN=" ~/.hermes/.env; then
GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" ~/.hermes/.env | head -1 | cut -d= -f2 | tr -d '\n\r')
if _hermes_env="${HERMES_HOME:-$HOME/.hermes}/.env"; [ -f "$_hermes_env" ] && grep -q "^GITHUB_TOKEN=" "$_hermes_env"; then
GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" "$_hermes_env" | head -1 | cut -d= -f2 | tr -d '\n\r')
elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
fi

4
website/docs/user-guide/skills/bundled/github/github-github-issues.md
View file

@ -46,8 +46,8 @@ if command -v gh &>/dev/null && gh auth status &>/dev/null; then
else
AUTH="git"
if [ -z "$GITHUB_TOKEN" ]; then
if [ -f ~/.hermes/.env ] && grep -q "^GITHUB_TOKEN=" ~/.hermes/.env; then
GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" ~/.hermes/.env | head -1 | cut -d= -f2 | tr -d '\n\r')
if _hermes_env="${HERMES_HOME:-$HOME/.hermes}/.env"; [ -f "$_hermes_env" ] && grep -q "^GITHUB_TOKEN=" "$_hermes_env"; then
GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" "$_hermes_env" | head -1 | cut -d= -f2 | tr -d '\n\r')
elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
fi

4
website/docs/user-guide/skills/bundled/github/github-github-pr-workflow.md
View file

@ -48,8 +48,8 @@ else
AUTH="git"
# Ensure we have a token for API calls
if [ -z "$GITHUB_TOKEN" ]; then
if [ -f ~/.hermes/.env ] && grep -q "^GITHUB_TOKEN=" ~/.hermes/.env; then
GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" ~/.hermes/.env | head -1 | cut -d= -f2 | tr -d '\n\r')
if _hermes_env="${HERMES_HOME:-$HOME/.hermes}/.env"; [ -f "$_hermes_env" ] && grep -q "^GITHUB_TOKEN=" "$_hermes_env"; then
GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" "$_hermes_env" | head -1 | cut -d= -f2 | tr -d '\n\r')
elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
fi

4
website/docs/user-guide/skills/bundled/github/github-github-repo-management.md
View file

@ -45,8 +45,8 @@ if command -v gh &>/dev/null && gh auth status &>/dev/null; then
else
AUTH="git"
if [ -z "$GITHUB_TOKEN" ]; then
if [ -f ~/.hermes/.env ] && grep -q "^GITHUB_TOKEN=" ~/.hermes/.env; then
GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" ~/.hermes/.env | head -1 | cut -d= -f2 | tr -d '\n\r')
if _hermes_env="${HERMES_HOME:-$HOME/.hermes}/.env"; [ -f "$_hermes_env" ] && grep -q "^GITHUB_TOKEN=" "$_hermes_env"; then
GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" "$_hermes_env" | head -1 | cut -d= -f2 | tr -d '\n\r')
elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
fi

2
website/docs/user-guide/skills/bundled/media/media-gif-search.md
View file

@ -38,7 +38,7 @@ Useful for finding reaction GIFs, creating visual content, and sending GIFs in c
## Setup
Set your Tenor API key in your environment (add to `~/.hermes/.env`):
Set your Tenor API key in your environment (add to `${HERMES_HOME:-~/.hermes}/.env`):
```bash
TENOR_API_KEY=your_key_here

2
website/docs/user-guide/skills/bundled/note-taking/note-taking-obsidian.md
View file

@ -32,7 +32,7 @@ Use this skill for filesystem-first Obsidian vault work: reading notes, listing
Use a known or resolved vault path before calling file tools.
The documented vault-path convention is the `OBSIDIAN_VAULT_PATH` environment variable, for example from `~/.hermes/.env`. If it is unset, use `~/Documents/Obsidian Vault`.
The documented vault-path convention is the `OBSIDIAN_VAULT_PATH` environment variable, for example from `${HERMES_HOME:-~/.hermes}/.env`. If it is unset, use `~/Documents/Obsidian Vault`.
File tools do not expand shell variables. Do not pass paths containing `$OBSIDIAN_VAULT_PATH` to `read_file`, `write_file`, `patch`, or `search_files`; resolve the vault path first and pass a concrete absolute path. Vault paths may contain spaces, which is another reason to prefer file tools over shell commands.

4
website/docs/user-guide/skills/bundled/productivity/productivity-airtable.md
View file

@ -40,7 +40,7 @@ Work with Airtable's REST API directly via `curl` using the `terminal` tool. No
- `data.records:write` — create / update / delete rows
- `schema.bases:read` — list bases and tables
3. **Important:** in the same token UI, add each base you want to access to the token's **Access** list. PATs are scoped per-base — a valid token on the wrong base returns `403`.
4. Store the token in `~/.hermes/.env` (or via `hermes setup`):
4. Store the token in `${HERMES_HOME:-~/.hermes}/.env` (or via `hermes setup`):
```
AIRTABLE_API_KEY=pat_your_token_here
```
@ -236,7 +236,7 @@ done
## Important Notes for Hermes
- **Always use the `terminal` tool with `curl`.** Do NOT use `web_extract` (it can't send auth headers) or `browser_navigate` (needs UI auth and is slow).
- **`AIRTABLE_API_KEY` flows from `~/.hermes/.env` into the subprocess automatically** when this skill is loaded — no need to re-export it before each `curl` call.
- **`AIRTABLE_API_KEY` flows from `${HERMES_HOME:-~/.hermes}/.env` into the subprocess automatically** when this skill is loaded — no need to re-export it before each `curl` call.
- **Escape curly braces in formulas carefully.** In a heredoc body, `{Status}` is literal. In a shell argument, `{Status}` is safe outside `{...}` brace-expansion context — but pass dynamic strings through `python3 urllib.parse.quote` before splicing into a URL.
- **Pretty-print with `python3 -m json.tool`** (always present) rather than `jq` (optional). Only reach for `jq` when you need filtering/projection.
- **Pagination is per-page, not global.** Airtable's 100-record cap is a hard limit; there is no way to bump it. Loop with `offset` until the field is absent.

4
website/docs/user-guide/skills/bundled/productivity/productivity-notion.md
View file

@ -41,7 +41,7 @@ Talk to Notion two ways. Same integration token works for both — pick by what'
1. Create an integration at https://notion.so/my-integrations
2. Copy the API key (starts with `ntn_` or `secret_`)
3. Store in `~/.hermes/.env`:
3. Store in `${HERMES_HOME:-~/.hermes}/.env`:
```
NOTION_API_KEY=ntn_your_key_here
```
@ -65,7 +65,7 @@ export NOTION_API_TOKEN=$NOTION_API_KEY # ntn reads NOTION_API_TOKEN
export NOTION_KEYRING=0 # don't try to use the OS keychain
```
Add those exports to your shell profile (or to `~/.hermes/.env`) so every session inherits them.
Add those exports to your shell profile (or to `${HERMES_HOME:-~/.hermes}/.env`) so every session inherits them.
### 3. Choose path at runtime

2
website/docs/user-guide/skills/bundled/productivity/productivity-teams-meeting-pipeline.md
View file

@ -50,7 +50,7 @@ Multilingual trigger examples (not exhaustive):
## Prerequisites
Before using the pipeline, verify these are set in `~/.hermes/.env`:
Before using the pipeline, verify these are set in `${HERMES_HOME:-~/.hermes}/.env`:
```bash
MSGRAPH_TENANT_ID=...

2
website/docs/user-guide/skills/bundled/research/research-llm-wiki.md
View file

@ -52,7 +52,7 @@ Use this skill when the user:
## Wiki Location
**Location:** Set via `WIKI_PATH` environment variable (e.g. in `~/.hermes/.env`).
**Location:** Set via `WIKI_PATH` environment variable (e.g. in `${HERMES_HOME:-~/.hermes}/.env`).
If unset, defaults to `~/wiki`.

2
website/docs/user-guide/skills/bundled/research/research-research-paper-writing.md
View file

@ -22,7 +22,7 @@ Write ML papers for NeurIPS/ICML/ICLR: design→submit.
| Dependencies | `semanticscholar`, `arxiv`, `habanero`, `requests`, `scipy`, `numpy`, `matplotlib`, `SciencePlots` |
| Platforms | linux, macos |
| Tags | `Research`, `Paper Writing`, `Experiments`, `ML`, `AI`, `NeurIPS`, `ICML`, `ICLR`, `ACL`, `AAAI`, `COLM`, `LaTeX`, `Citations`, `Statistical Analysis` |
| Related skills | [`arxiv`](/docs/user-guide/skills/bundled/research/research-arxiv), `ml-paper-writing`, [`subagent-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-subagent-driven-development), [`plan`](/docs/user-guide/skills/bundled/software-development/software-development-plan) |
| Related skills | [`arxiv`](/docs/user-guide/skills/bundled/research/research-arxiv), `ml-paper-writing`, [`subagent-driven-development`](/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development), [`plan`](/docs/user-guide/skills/bundled/software-development/software-development-plan) |
## Reference: full SKILL.md

2
website/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger.md
View file

@ -21,7 +21,7 @@ Debug Node.js via --inspect + Chrome DevTools Protocol CLI.
| License | MIT |
| Platforms | linux, macos, windows |
| Tags | `debugging`, `nodejs`, `node-inspect`, `cdp`, `breakpoints`, `ui-tui` |
| Related skills | [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`python-debugpy`](/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy), [`debugging-hermes-tui-commands`](/docs/user-guide/skills/bundled/software-development/software-development-debugging-hermes-tui-commands) |
| Related skills | [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`python-debugpy`](/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy), `debugging-hermes-tui-commands` |
## Reference: full SKILL.md

2
website/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy.md
View file

@ -21,7 +21,7 @@ Debug Python: pdb REPL + debugpy remote (DAP).
| License | MIT |
| Platforms | linux, macos |
| Tags | `debugging`, `python`, `pdb`, `debugpy`, `breakpoints`, `dap`, `post-mortem` |
| Related skills | [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`node-inspect-debugger`](/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger), [`debugging-hermes-tui-commands`](/docs/user-guide/skills/bundled/software-development/software-development-debugging-hermes-tui-commands) |
| Related skills | [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`node-inspect-debugger`](/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger), `debugging-hermes-tui-commands` |
## Reference: full SKILL.md

2
website/docs/user-guide/skills/bundled/software-development/software-development-spike.md
View file

@ -21,7 +21,7 @@ Throwaway experiments to validate an idea before build.
| License | MIT |
| Platforms | linux, macos, windows |
| Tags | `spike`, `prototype`, `experiment`, `feasibility`, `throwaway`, `exploration`, `research`, `planning`, `mvp`, `proof-of-concept` |
| Related skills | [`sketch`](/docs/user-guide/skills/bundled/creative/creative-sketch), [`subagent-driven-development`](/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development), [`plan`](/docs/user-guide/skills/bundled/software-development/software-development-plan) |
| Related skills | [`html-artifact`](/docs/user-guide/skills/bundled/creative/creative-html-artifact), [`subagent-driven-development`](/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development), [`plan`](/docs/user-guide/skills/bundled/software-development/software-development-plan) |
## Reference: full SKILL.md

4
website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-honcho.md
View file

@ -47,14 +47,14 @@ Honcho provides AI-native cross-session user modeling. It learns who the user is
### Cloud (app.honcho.dev)
```bash
hermes honcho setup
hermes memory setup honcho
# select "cloud", paste API key from https://app.honcho.dev
```
### Self-hosted
```bash
hermes honcho setup
hermes memory setup honcho
# select "local", enter base URL (e.g. http://localhost:8000)
```

4
website/docs/user-guide/skills/optional/blockchain/blockchain-hyperliquid.md
View file

@ -53,7 +53,7 @@ Read-only — no API key, no signing, no order placement.
Stdlib only — no external packages, no API key.
The script reads `~/.hermes/.env` for two optional defaults:
The script reads `${HERMES_HOME:-~/.hermes}/.env` for two optional defaults:
- `HYPERLIQUID_API_URL` — defaults to `https://api.hyperliquid.xyz`. Set to
`https://api.hyperliquid-testnet.xyz` for testnet.
@ -97,7 +97,7 @@ hyperliquid_client.py export <coin> [--interval 1h] [--hours N] [--output PATH]
```
For `state`, `spot-balances`, `fills`, `orders`, and `review`, the address is
optional when `HYPERLIQUID_USER_ADDRESS` is set in `~/.hermes/.env`.
optional when `HYPERLIQUID_USER_ADDRESS` is set in `${HERMES_HOME:-~/.hermes}/.env`.
---

379
website/docs/user-guide/skills/optional/creative/creative-concept-diagrams.md
View file

@ -1,379 +0,0 @@
---
title: "Concept Diagrams"
sidebar_label: "Concept Diagrams"
description: "Generate flat, minimal light/dark-aware SVG diagrams as standalone HTML files, using a unified educational visual language with 9 semantic color ramps, sente..."
---
{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
# Concept Diagrams
Generate flat, minimal light/dark-aware SVG diagrams as standalone HTML files, using a unified educational visual language with 9 semantic color ramps, sentence-case typography, and automatic dark mode. Best suited for educational and non-software visuals — physics setups, chemistry mechanisms, math curves, physical objects (aircraft, turbines, smartphones, mechanical watches), anatomy, floor plans, cross-sections, narrative journeys (lifecycle of X, process of Y), hub-spoke system integrations (smart city, IoT), and exploded layer views. If a more specialized skill exists for the subject (dedicated software/cloud architecture, hand-drawn sketches, animated explainers, etc.), prefer that — otherwise this skill can also serve as a general-purpose SVG diagram fallback with a clean educational look. Ships with 15 example diagrams.
## Skill metadata
| | |
|---|---|
| Source | Optional — install with `hermes skills install official/creative/concept-diagrams` |
| Path | `optional-skills/creative/concept-diagrams` |
| Version | `0.1.0` |
| Author | v1k22 (original PR), ported into hermes-agent |
| License | MIT |
| Platforms | linux, macos, windows |
| Tags | `diagrams`, `svg`, `visualization`, `education`, `physics`, `chemistry`, `engineering` |
| Related skills | [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram), [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw), `generative-widgets` |
## Reference: full SKILL.md
:::info
The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
:::
# Concept Diagrams
Generate production-quality SVG diagrams with a unified flat, minimal design system. Output is a single self-contained HTML file that renders identically in any modern browser, with automatic light/dark mode.
## Scope
**Best suited for:**
- Physics setups, chemistry mechanisms, math curves, biology
- Physical objects (aircraft, turbines, smartphones, mechanical watches, cells)
- Anatomy, cross-sections, exploded layer views
- Floor plans, architectural conversions
- Narrative journeys (lifecycle of X, process of Y)
- Hub-spoke system integrations (smart city, IoT networks, electricity grids)
- Educational / textbook-style visuals in any domain
- Quantitative charts (grouped bars, energy profiles)
**Look elsewhere first for:**
- Dedicated software / cloud infrastructure architecture with a dark tech aesthetic (consider `architecture-diagram` if available)
- Hand-drawn whiteboard sketches (consider `excalidraw` if available)
- Animated explainers or video output (consider an animation skill)
If a more specialized skill is available for the subject, prefer that. If none fits, this skill can serve as a general-purpose SVG diagram fallback — the output will carry the clean educational aesthetic described below, which is a reasonable default for almost any subject.
## Workflow
1. Decide on the diagram type (see Diagram Types below).
2. Lay out components using the Design System rules.
3. Write the full HTML page using `templates/template.html` as the wrapper — paste your SVG where the template says `<!-- PASTE SVG HERE -->`.
4. Save as a standalone `.html` file (for example `~/my-diagram.html` or `./my-diagram.html`).
5. User opens it directly in a browser — no server, no dependencies.
Optional: if the user wants a browsable gallery of multiple diagrams, see "Local Preview Server" at the bottom.
Load the HTML template:
```
skill_view(name="concept-diagrams", file_path="templates/template.html")
```
The template embeds the full CSS design system (`c-*` color classes, text classes, light/dark variables, arrow marker styles). The SVG you generate relies on these classes being present on the hosting page.
---
## Design System
### Philosophy
- **Flat**: no gradients, drop shadows, blur, glow, or neon effects.
- **Minimal**: show the essential. No decorative icons inside boxes.
- **Consistent**: same colors, spacing, typography, and stroke widths across every diagram.
- **Dark-mode ready**: all colors auto-adapt via CSS classes — no per-mode SVG.
### Color Palette
9 color ramps, each with 7 stops. Put the class name on a `<g>` or shape element; the template CSS handles both modes.
| Class | 50 (lightest) | 100 | 200 | 400 | 600 | 800 | 900 (darkest) |
|------------|---------------|---------|---------|---------|---------|---------|---------------|
| `c-purple` | #EEEDFE | #CECBF6 | #AFA9EC | #7F77DD | #534AB7 | #3C3489 | #26215C |
| `c-teal` | #E1F5EE | #9FE1CB | #5DCAA5 | #1D9E75 | #0F6E56 | #085041 | #04342C |
| `c-coral` | #FAECE7 | #F5C4B3 | #F0997B | #D85A30 | #993C1D | #712B13 | #4A1B0C |
| `c-pink` | #FBEAF0 | #F4C0D1 | #ED93B1 | #D4537E | #993556 | #72243E | #4B1528 |
| `c-gray` | #F1EFE8 | #D3D1C7 | #B4B2A9 | #888780 | #5F5E5A | #444441 | #2C2C2A |
| `c-blue` | #E6F1FB | #B5D4F4 | #85B7EB | #378ADD | #185FA5 | #0C447C | #042C53 |
| `c-green` | #EAF3DE | #C0DD97 | #97C459 | #639922 | #3B6D11 | #27500A | #173404 |
| `c-amber` | #FAEEDA | #FAC775 | #EF9F27 | #BA7517 | #854F0B | #633806 | #412402 |
| `c-red` | #FCEBEB | #F7C1C1 | #F09595 | #E24B4A | #A32D2D | #791F1F | #501313 |
#### Color Assignment Rules
Color encodes **meaning**, not sequence. Never cycle through colors like a rainbow.
- Group nodes by **category** — all nodes of the same type share one color.
- Use `c-gray` for neutral/structural nodes (start, end, generic steps, users).
- Use **2-3 colors per diagram**, not 6+.
- Prefer `c-purple`, `c-teal`, `c-coral`, `c-pink` for general categories.
- Reserve `c-blue`, `c-green`, `c-amber`, `c-red` for semantic meaning (info, success, warning, error).
Light/dark stop mapping (handled by the template CSS — just use the class):
- Light mode: 50 fill + 600 stroke + 800 title / 600 subtitle
- Dark mode: 800 fill + 200 stroke + 100 title / 200 subtitle
### Typography
Only two font sizes. No exceptions.
| Class | Size | Weight | Use |
|-------|------|--------|-----|
| `th` | 14px | 500 | Node titles, region labels |
| `ts` | 12px | 400 | Subtitles, descriptions, arrow labels |
| `t` | 14px | 400 | General text |
- **Sentence case always.** Never Title Case, never ALL CAPS.
- Every `<text>` MUST carry a class (`t`, `ts`, or `th`). No unclassed text.
- `dominant-baseline="central"` on all text inside boxes.
- `text-anchor="middle"` for centered text in boxes.
**Width estimation (approx):**
- 14px weight 500: ~8px per character
- 12px weight 400: ~6.5px per character
- Always verify: `box_width >= (char_count × px_per_char) + 48` (24px padding each side)
### Spacing & Layout
- **ViewBox**: `viewBox="0 0 680 H"` where H = content height + 40px buffer.
- **Safe area**: x=40 to x=640, y=40 to y=(H-40).
- **Between boxes**: 60px minimum gap.
- **Inside boxes**: 24px horizontal padding, 12px vertical padding.
- **Arrowhead gap**: 10px between arrowhead and box edge.
- **Single-line box**: 44px height.
- **Two-line box**: 56px height, 18px between title and subtitle baselines.
- **Container padding**: 20px minimum inside every container.
- **Max nesting**: 2-3 levels deep. Deeper gets unreadable at 680px width.
### Stroke & Shape
- **Stroke width**: 0.5px on all node borders. Not 1px, not 2px.
- **Rect rounding**: `rx="8"` for nodes, `rx="12"` for inner containers, `rx="16"` to `rx="20"` for outer containers.
- **Connector paths**: MUST have `fill="none"`. SVG defaults to `fill: black` otherwise.
### Arrow Marker
Include this `<defs>` block at the start of **every** SVG:
```xml
<defs>
<marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5"
markerWidth="6" markerHeight="6" orient="auto-start-reverse">
<path d="M2 1L8 5L2 9" fill="none" stroke="context-stroke"
stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
</marker>
</defs>
```
Use `marker-end="url(#arrow)"` on lines. The arrowhead inherits the line color via `context-stroke`.
### CSS Classes (Provided by the Template)
The template page provides:
- Text: `.t`, `.ts`, `.th`
- Neutral: `.box`, `.arr`, `.leader`, `.node`
- Color ramps: `.c-purple`, `.c-teal`, `.c-coral`, `.c-pink`, `.c-gray`, `.c-blue`, `.c-green`, `.c-amber`, `.c-red` (all with automatic light/dark mode)
You do **not** need to redefine these — just apply them in your SVG. The template file contains the full CSS definitions.
---
## SVG Boilerplate
Every SVG inside the template page starts with this exact structure:
```xml
<svg width="100%" viewBox="0 0 680 {HEIGHT}" xmlns="http://www.w3.org/2000/svg">
<defs>
<marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5"
markerWidth="6" markerHeight="6" orient="auto-start-reverse">
<path d="M2 1L8 5L2 9" fill="none" stroke="context-stroke"
stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
</marker>
</defs>
<!-- Diagram content here -->
</svg>
```
Replace `{HEIGHT}` with the actual computed height (last element bottom + 40px).
### Node Patterns
**Single-line node (44px):**
```xml
<g class="node c-blue">
<rect x="100" y="20" width="180" height="44" rx="8" stroke-width="0.5"/>
<text class="th" x="190" y="42" text-anchor="middle" dominant-baseline="central">Service name</text>
</g>
```
**Two-line node (56px):**
```xml
<g class="node c-teal">
<rect x="100" y="20" width="200" height="56" rx="8" stroke-width="0.5"/>
<text class="th" x="200" y="38" text-anchor="middle" dominant-baseline="central">Service name</text>
<text class="ts" x="200" y="56" text-anchor="middle" dominant-baseline="central">Short description</text>
</g>
```
**Connector (no label):**
```xml
<line x1="200" y1="76" x2="200" y2="120" class="arr" marker-end="url(#arrow)"/>
```
**Container (dashed or solid):**
```xml
<g class="c-purple">
<rect x="40" y="92" width="600" height="300" rx="16" stroke-width="0.5"/>
<text class="th" x="66" y="116">Container label</text>
<text class="ts" x="66" y="134">Subtitle info</text>
</g>
```
---
## Diagram Types
Choose the layout that fits the subject:
1. **Flowchart** — CI/CD pipelines, request lifecycles, approval workflows, data processing. Single-direction flow (top-down or left-right). Max 4-5 nodes per row.
2. **Structural / Containment** — Cloud infrastructure nesting, system architecture with layers. Large outer containers with inner regions. Dashed rects for logical groupings.
3. **API / Endpoint Map** — REST routes, GraphQL schemas. Tree from root, branching to resource groups, each containing endpoint nodes.
4. **Microservice Topology** — Service mesh, event-driven systems. Services as nodes, arrows for communication patterns, message queues between.
5. **Data Flow** — ETL pipelines, streaming architectures. Left-to-right flow from sources through processing to sinks.
6. **Physical / Structural** — Vehicles, buildings, hardware, anatomy. Use shapes that match the physical form — `<path>` for curved bodies, `<polygon>` for tapered shapes, `<ellipse>`/`<circle>` for cylindrical parts, nested `<rect>` for compartments. See `references/physical-shape-cookbook.md`.
7. **Infrastructure / Systems Integration** — Smart cities, IoT networks, multi-domain systems. Hub-spoke layout with central platform connecting subsystems. Semantic line styles (`.data-line`, `.power-line`, `.water-pipe`, `.road`). See `references/infrastructure-patterns.md`.
8. **UI / Dashboard Mockups** — Admin panels, monitoring dashboards. Screen frame with nested chart/gauge/indicator elements. See `references/dashboard-patterns.md`.
For physical, infrastructure, and dashboard diagrams, load the matching reference file before generating — each one provides ready-made CSS classes and shape primitives.
---
## Validation Checklist
Before finalizing any SVG, verify ALL of the following:
1. Every `<text>` has class `t`, `ts`, or `th`.
2. Every `<text>` inside a box has `dominant-baseline="central"`.
3. Every connector `<path>` or `<line>` used as arrow has `fill="none"`.
4. No arrow line crosses through an unrelated box.
5. `box_width >= (longest_label_chars × 8) + 48` for 14px text.
6. `box_width >= (longest_label_chars × 6.5) + 48` for 12px text.
7. ViewBox height = bottom-most element + 40px.
8. All content stays within x=40 to x=640.
9. Color classes (`c-*`) are on `<g>` or shape elements, never on `<path>` connectors.
10. Arrow `<defs>` block is present.
11. No gradients, shadows, blur, or glow effects.
12. Stroke width is 0.5px on all node borders.
---
## Output & Preview
### Default: standalone HTML file
Write a single `.html` file the user can open directly. No server, no dependencies, works offline. Pattern:
```python
# 1. Load the template
template = skill_view("concept-diagrams", "templates/template.html")
# 2. Fill in title, subtitle, and paste your SVG
html = template.replace(
"<!-- DIAGRAM TITLE HERE -->", "SN2 reaction mechanism"
).replace(
"<!-- OPTIONAL SUBTITLE HERE -->", "Bimolecular nucleophilic substitution"
).replace(
"<!-- PASTE SVG HERE -->", svg_content
)
# 3. Write to a user-chosen path (or ./ by default)
write_file("./sn2-mechanism.html", html)
```
Tell the user how to open it:
```
# macOS
open ./sn2-mechanism.html
# Linux
xdg-open ./sn2-mechanism.html
```
### Optional: local preview server (multi-diagram gallery)
Only use this when the user explicitly wants a browsable gallery of multiple diagrams.
**Rules:**
- Bind to `127.0.0.1` only. Never `0.0.0.0`. Exposing diagrams on all network interfaces is a security hazard on shared networks.
- Pick a free port (do NOT hard-code one) and tell the user the chosen URL.
- The server is optional and opt-in — prefer the standalone HTML file first.
Recommended pattern (lets the OS pick a free ephemeral port):
```bash
# Put each diagram in its own folder under .diagrams/
mkdir -p .diagrams/sn2-mechanism
# ...write .diagrams/sn2-mechanism/index.html...
# Serve on loopback only, free port
cd .diagrams && python3 -c "
import http.server, socketserver
with socketserver.TCPServer(('127.0.0.1', 0), http.server.SimpleHTTPRequestHandler) as s:
print(f'Serving at http://127.0.0.1:{s.server_address[1]}/')
s.serve_forever()
" &
```
If the user insists on a fixed port, use `127.0.0.1:<port>` — still never `0.0.0.0`. Document how to stop the server (`kill %1` or `pkill -f "http.server"`).
---
## Examples Reference
The `examples/` directory ships 15 complete, tested diagrams. Browse them for working patterns before writing a new diagram of a similar type:
| File | Type | Demonstrates |
|------|------|--------------|
| `hospital-emergency-department-flow.md` | Flowchart | Priority routing with semantic colors |
| `feature-film-production-pipeline.md` | Flowchart | Phased workflow, horizontal sub-flows |
| `automated-password-reset-flow.md` | Flowchart | Auth flow with error branches |
| `autonomous-llm-research-agent-flow.md` | Flowchart | Loop-back arrows, decision branches |
| `place-order-uml-sequence.md` | Sequence | UML sequence diagram style |
| `commercial-aircraft-structure.md` | Physical | Paths, polygons, ellipses for realistic shapes |
| `wind-turbine-structure.md` | Physical cross-section | Underground/above-ground separation, color coding |
| `smartphone-layer-anatomy.md` | Exploded view | Alternating left/right labels, layered components |
| `apartment-floor-plan-conversion.md` | Floor plan | Walls, doors, proposed changes in dotted red |
| `banana-journey-tree-to-smoothie.md` | Narrative journey | Winding path, progressive state changes |
| `cpu-ooo-microarchitecture.md` | Hardware pipeline | Fan-out, memory hierarchy sidebar |
| `sn2-reaction-mechanism.md` | Chemistry | Molecules, curved arrows, energy profile |
| `smart-city-infrastructure.md` | Hub-spoke | Semantic line styles per system |
| `electricity-grid-flow.md` | Multi-stage flow | Voltage hierarchy, flow markers |
| `ml-benchmark-grouped-bar-chart.md` | Chart | Grouped bars, dual axis |
Load any example with:
```
skill_view(name="concept-diagrams", file_path="examples/<filename>")
```
---
## Quick Reference: What to Use When
| User says | Diagram type | Suggested colors |
|-----------|--------------|------------------|
| "show the pipeline" | Flowchart | gray start/end, purple steps, red errors, teal deploy |
| "draw the data flow" | Data pipeline (left-right) | gray sources, purple processing, teal sinks |
| "visualize the system" | Structural (containment) | purple container, teal services, coral data |
| "map the endpoints" | API tree | purple root, one ramp per resource group |
| "show the services" | Microservice topology | gray ingress, teal services, purple bus, coral workers |
| "draw the aircraft/vehicle" | Physical | paths, polygons, ellipses for realistic shapes |
| "smart city / IoT" | Hub-spoke integration | semantic line styles per subsystem |
| "show the dashboard" | UI mockup | dark screen, chart colors: teal, purple, coral for alerts |
| "power grid / electricity" | Multi-stage flow | voltage hierarchy (HV/MV/LV line weights) |
| "wind turbine / turbine" | Physical cross-section | foundation + tower cutaway + nacelle color-coded |
| "journey of X / lifecycle" | Narrative journey | winding path, progressive state changes |
| "layers of X / exploded" | Exploded layer view | vertical stack, alternating labels |
| "CPU / pipeline" | Hardware pipeline | vertical stages, fan-out to execution ports |
| "floor plan / apartment" | Floor plan | walls, doors, proposed changes in dotted red |
| "reaction mechanism" | Chemistry | atoms, bonds, curved arrows, transition state, energy profile |

4
website/docs/user-guide/skills/optional/creative/creative-kanban-video-orchestrator.md
View file

@ -21,7 +21,7 @@ Plan, set up, and monitor a multi-agent video production pipeline backed by Herm
| License | MIT |
| Platforms | linux, macos, windows |
| Tags | `video`, `kanban`, `multi-agent`, `orchestration`, `production-pipeline` |
| Related skills | [`kanban-orchestrator`](/docs/user-guide/skills/bundled/devops/devops-kanban-orchestrator), [`kanban-worker`](/docs/user-guide/skills/bundled/devops/devops-kanban-worker), [`ascii-video`](/docs/user-guide/skills/bundled/creative/creative-ascii-video), [`manim-video`](/docs/user-guide/skills/bundled/creative/creative-manim-video), [`p5js`](/docs/user-guide/skills/bundled/creative/creative-p5js), [`comfyui`](/docs/user-guide/skills/bundled/creative/creative-comfyui), [`touchdesigner-mcp`](/docs/user-guide/skills/bundled/creative/creative-touchdesigner-mcp), [`blender-mcp`](/docs/user-guide/skills/optional/creative/creative-blender-mcp), [`pixel-art`](/docs/user-guide/skills/bundled/creative/creative-pixel-art), [`ascii-art`](/docs/user-guide/skills/bundled/creative/creative-ascii-art), [`songwriting-and-ai-music`](/docs/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music), [`heartmula`](/docs/user-guide/skills/bundled/media/media-heartmula), [`songsee`](/docs/user-guide/skills/bundled/media/media-songsee), [`spotify`](/docs/user-guide/skills/bundled/media/media-spotify), [`youtube-content`](/docs/user-guide/skills/bundled/media/media-youtube-content), [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design), [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw), [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram), [`concept-diagrams`](/docs/user-guide/skills/optional/creative/creative-concept-diagrams), [`baoyu-comic`](/docs/user-guide/skills/bundled/creative/creative-baoyu-comic), [`baoyu-infographic`](/docs/user-guide/skills/bundled/creative/creative-baoyu-infographic), [`humanizer`](/docs/user-guide/skills/bundled/creative/creative-humanizer), [`gif-search`](/docs/user-guide/skills/bundled/media/media-gif-search), [`meme-generation`](/docs/user-guide/skills/optional/creative/creative-meme-generation) |
| Related skills | [`kanban-orchestrator`](/docs/user-guide/skills/bundled/devops/devops-kanban-orchestrator), [`kanban-worker`](/docs/user-guide/skills/bundled/devops/devops-kanban-worker), [`ascii-video`](/docs/user-guide/skills/bundled/creative/creative-ascii-video), [`manim-video`](/docs/user-guide/skills/bundled/creative/creative-manim-video), [`p5js`](/docs/user-guide/skills/bundled/creative/creative-p5js), [`comfyui`](/docs/user-guide/skills/bundled/creative/creative-comfyui), [`touchdesigner-mcp`](/docs/user-guide/skills/bundled/creative/creative-touchdesigner-mcp), [`blender-mcp`](/docs/user-guide/skills/optional/creative/creative-blender-mcp), [`pixel-art`](/docs/user-guide/skills/optional/creative/creative-pixel-art), [`ascii-art`](/docs/user-guide/skills/bundled/creative/creative-ascii-art), [`songwriting-and-ai-music`](/docs/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music), [`heartmula`](/docs/user-guide/skills/bundled/media/media-heartmula), [`songsee`](/docs/user-guide/skills/bundled/media/media-songsee), `spotify`, [`youtube-content`](/docs/user-guide/skills/bundled/media/media-youtube-content), [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design), [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw), [`html-artifact`](/docs/user-guide/skills/bundled/creative/creative-html-artifact), [`baoyu-comic`](/docs/user-guide/skills/optional/creative/creative-baoyu-comic), [`baoyu-infographic`](/docs/user-guide/skills/bundled/creative/creative-baoyu-infographic), [`humanizer`](/docs/user-guide/skills/bundled/creative/creative-humanizer), [`gif-search`](/docs/user-guide/skills/bundled/media/media-gif-search), [`meme-generation`](/docs/user-guide/skills/optional/creative/creative-meme-generation) |
## Reference: full SKILL.md
@ -194,7 +194,7 @@ task graphs. See **[references/examples.md](https://github.com/NousResearch/herm
right human-review gates.
8. **Verify API keys BEFORE firing.** External APIs (TTS, image-gen,
image-to-video) need keys in `~/.hermes/.env` or the user's secret store.
image-to-video) need keys in `${HERMES_HOME:-~/.hermes}/.env` or the user's secret store.
A worker that hits a missing-key error wastes a task slot. The setup
script's `check_key` helper aborts cleanly if a required key is missing.

2
website/docs/user-guide/skills/optional/devops/devops-pinggy-tunnel.md
View file

@ -21,7 +21,7 @@ Zero-install localhost tunnels over SSH via Pinggy.
| License | MIT |
| Platforms | linux, macos, windows |
| Tags | `Pinggy`, `Tunnel`, `Networking`, `SSH`, `Webhook`, `Localhost` |
| Related skills | `cloudflared-quick-tunnel`, [`webhook-subscriptions`](/docs/user-guide/skills/bundled/devops/devops-webhook-subscriptions) |
| Related skills | `cloudflared-quick-tunnel`, `webhook-subscriptions` |
## Reference: full SKILL.md

2
website/docs/user-guide/skills/optional/devops/devops-watchers.md
View file

@ -77,7 +77,7 @@ python $HERMES_HOME/skills/devops/watchers/scripts/watch_rss.py \
--name hn --url https://news.ycombinator.com/rss --max 5
```
Watch a GitHub repo (set `GITHUB_TOKEN` in `~/.hermes/.env` to avoid the 60 req/hr anonymous rate limit):
Watch a GitHub repo (set `GITHUB_TOKEN` in `${HERMES_HOME:-~/.hermes}/.env` to avoid the 60 req/hr anonymous rate limit):
```bash
python $HERMES_HOME/skills/devops/watchers/scripts/watch_github.py \

2
website/docs/user-guide/skills/optional/mcp/mcp-fastmcp.md
View file

@ -21,7 +21,7 @@ Build, test, inspect, install, and deploy MCP servers with FastMCP in Python. Us
| License | MIT |
| Platforms | linux, macos, windows |
| Tags | `MCP`, `FastMCP`, `Python`, `Tools`, `Resources`, `Prompts`, `Deployment` |
| Related skills | [`native-mcp`](/docs/user-guide/skills/bundled/mcp/mcp-native-mcp), [`mcporter`](/docs/user-guide/skills/optional/mcp/mcp-mcporter) |
| Related skills | `native-mcp`, [`mcporter`](/docs/user-guide/skills/optional/mcp/mcp-mcporter) |
## Reference: full SKILL.md

2
website/docs/user-guide/skills/optional/payments/payments-stripe-projects.md
View file

@ -44,7 +44,7 @@ Trigger phrases:
- "manage my stack credentials", "rotate this key", "upgrade my plan"
- "what providers can I add?"
If the user already has a provider account, this skill can still connect it with `stripe projects link &lt;provider>`. If the user wants to use an existing provider resource, such as an existing database or Vercel project, check provider support first; many providers currently support provisioning new resources but not importing existing ones.
If the user already has a provider account, this skill can still connect it with `stripe projects link <provider>`. If the user wants to use an existing provider resource, such as an existing database or Vercel project, check provider support first; many providers currently support provisioning new resources but not importing existing ones.
## Prerequisites

2
website/docs/user-guide/skills/optional/productivity/productivity-canvas.md
View file

@ -42,7 +42,7 @@ Read-only access to Canvas LMS for listing courses and assignments.
2. Go to **Account → Settings** (click your profile icon, then Settings)
3. Scroll to **Approved Integrations** and click **+ New Access Token**
4. Name the token (e.g., "Hermes Agent"), set an optional expiry, and click **Generate Token**
5. Copy the token and add to `~/.hermes/.env`:
5. Copy the token and add to `${HERMES_HOME:-~/.hermes}/.env`:
```
CANVAS_API_TOKEN=your_token_here

2
website/docs/user-guide/skills/optional/productivity/productivity-shopify.md
View file

@ -40,7 +40,7 @@ The REST Admin API is legacy since 2024-04 and only receives security fixes. **U
1. In Shopify admin: **Settings → Apps and sales channels → Develop apps → Create an app**.
2. Click **Configure Admin API scopes**, select what you need (examples below), save.
3. **Install app** → the Admin API access token appears ONCE. Copy it immediately — Shopify will never show it again. Tokens start with `shpat_`.
4. Save to `~/.hermes/.env`:
4. Save to `${HERMES_HOME:-~/.hermes}/.env`:
```
SHOPIFY_ACCESS_TOKEN=shpat_xxxxxxxxxxxxxxxxxxxx
SHOPIFY_STORE_DOMAIN=my-store.myshopify.com

2
website/docs/user-guide/skills/optional/productivity/productivity-siyuan.md
View file

@ -37,7 +37,7 @@ Use the [SiYuan](https://github.com/siyuan-note/siyuan) kernel API via curl to s
1. Install and run SiYuan (desktop or Docker)
2. Get your API token: **Settings > About > API token**
3. Store it in `~/.hermes/.env`:
3. Store it in `${HERMES_HOME:-~/.hermes}/.env`:
```
SIYUAN_TOKEN=your_token_here
SIYUAN_URL=http://127.0.0.1:6806

8
website/docs/user-guide/skills/optional/productivity/productivity-telephony.md
View file

@ -34,7 +34,7 @@ The following is the complete skill definition that Hermes loads when this skill
This optional skill gives Hermes practical phone capabilities while keeping telephony out of the core tool list.
It ships with a helper script, `scripts/telephony.py`, that can:
- save provider credentials into `~/.hermes/.env`
- save provider credentials into `${HERMES_HOME:-~/.hermes}/.env`
- search for and buy a Twilio phone number
- remember that owned number for later sessions
- send SMS / MMS from the owned number
@ -121,7 +121,7 @@ Why:
The skill persists telephony state in two places:
### `~/.hermes/.env`
### `${HERMES_HOME:-~/.hermes}/.env`
Used for long-lived provider credentials and owned-number IDs, for example:
- `TWILIO_ACCOUNT_SID`
- `TWILIO_AUTH_TOKEN`
@ -258,7 +258,7 @@ python3 "$SCRIPT" save-twilio AC... auth_token_here
python3 "$SCRIPT" twilio-search --country US --area-code 702 --limit 10
```
3. Buy it and save it into `~/.hermes/.env` + state:
3. Buy it and save it into `${HERMES_HOME:-~/.hermes}/.env` + state:
```bash
python3 "$SCRIPT" twilio-buy "+17025551234" --save-env
```
@ -420,7 +420,7 @@ After setup, you should be able to do all of the following with just this skill:
1. `diagnose` shows provider readiness and remembered state
2. search and buy a Twilio number
3. persist that number to `~/.hermes/.env`
3. persist that number to `${HERMES_HOME:-~/.hermes}/.env`
4. send an SMS from the owned number
5. poll inbound texts for the owned number later
6. place a direct Twilio call

2
website/docs/user-guide/skills/optional/research/research-gitnexus-explorer.md
View file

@ -21,7 +21,7 @@ Index a codebase with GitNexus and serve an interactive knowledge graph via web
| License | MIT |
| Platforms | linux, macos, windows |
| Tags | `gitnexus`, `code-intelligence`, `knowledge-graph`, `visualization` |
| Related skills | [`native-mcp`](/docs/user-guide/skills/bundled/mcp/mcp-native-mcp), [`codebase-inspection`](/docs/user-guide/skills/bundled/github/github-codebase-inspection) |
| Related skills | `native-mcp`, [`codebase-inspection`](/docs/user-guide/skills/bundled/github/github-codebase-inspection) |
## Reference: full SKILL.md

2
website/docs/user-guide/skills/optional/research/research-qmd.md
View file

@ -21,7 +21,7 @@ Search personal knowledge bases, notes, docs, and meeting transcripts locally us
| License | MIT |
| Platforms | macos, linux |
| Tags | `Search`, `Knowledge-Base`, `RAG`, `Notes`, `MCP`, `Local-AI` |
| Related skills | [`obsidian`](/docs/user-guide/skills/bundled/note-taking/note-taking-obsidian), [`native-mcp`](/docs/user-guide/skills/bundled/mcp/mcp-native-mcp), [`arxiv`](/docs/user-guide/skills/bundled/research/research-arxiv) |
| Related skills | [`obsidian`](/docs/user-guide/skills/bundled/note-taking/note-taking-obsidian), `native-mcp`, [`arxiv`](/docs/user-guide/skills/bundled/research/research-arxiv) |
## Reference: full SKILL.md

2
website/docs/user-guide/skills/optional/security/security-1password.md
View file

@ -51,7 +51,7 @@ Use this skill when the user wants secrets managed through 1Password instead of
### Service Account (recommended for Hermes)
Set `OP_SERVICE_ACCOUNT_TOKEN` in `~/.hermes/.env` (the skill will prompt for this on first load).
Set `OP_SERVICE_ACCOUNT_TOKEN` in `${HERMES_HOME:-~/.hermes}/.env` (the skill will prompt for this on first load).
No desktop app needed. Supports `op read`, `op inject`, `op run`.
```bash

2
website/docs/user-guide/skills/optional/security/security-godmode.md
View file

@ -418,4 +418,4 @@ Claude Sonnet 4 is robust against all current techniques for clearly harmful con
9. **Always use `load_godmode.py` in execute_code** — The individual scripts (`parseltongue.py`, `godmode_race.py`, `auto_jailbreak.py`) have argparse CLI entry points with `if __name__ == '__main__'` blocks. When loaded via `exec()` in execute_code, `__name__` is `'__main__'` and argparse fires, crashing the script. The `load_godmode.py` loader handles this by setting `__name__` to a non-main value and managing sys.argv.
10. **boundary_inversion is model-version specific** — Works on Claude 3.5 Sonnet but NOT Claude Sonnet 4 or Claude 4.6. The strategy order in auto_jailbreak tries it first for Claude models, but falls through to refusal_inversion when it fails. Update the strategy order if you know the model version.
11. **Gray-area vs hard queries** — Jailbreak techniques work much better on "dual-use" queries (lock picking, security tools, chemistry) than on overtly harmful ones (phishing templates, malware). For hard queries, skip directly to ULTRAPLINIAN or use Hermes/Grok models that don't refuse.
12. **execute_code sandbox has no env vars** — When Hermes runs auto_jailbreak via execute_code, the sandbox doesn't inherit `~/.hermes/.env`. Load dotenv explicitly: `from dotenv import load_dotenv; load_dotenv(os.path.expanduser("~/.hermes/.env"))`
12. **execute_code sandbox has no env vars** — When Hermes runs auto_jailbreak via execute_code, the sandbox doesn't inherit the Hermes `.env`. Load dotenv explicitly: `import os; from dotenv import load_dotenv; load_dotenv(os.path.join(os.environ.get("HERMES_HOME", os.path.expanduser("~/.hermes")), ".env"))`

2
website/docs/user-guide/skills/optional/software-development/software-development-rest-graphql-debug.md
View file

@ -414,7 +414,7 @@ class TestAPISmoke:
### Token handling
- Never log full tokens. Redact: `Bearer <REDACTED>`.
- Never hardcode tokens in scripts. Read from env (`os.environ["API_TOKEN"]`) or `~/.hermes/.env`.
- Never hardcode tokens in scripts. Read from env (`os.environ["API_TOKEN"]`) or `${HERMES_HOME:-~/.hermes}/.env`.
- Rotate immediately if a token surfaces in logs, error messages, or git history.
### Safe logging

1
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/optional-skills-catalog.md
View file

@ -53,7 +53,6 @@ hermes skills uninstall <skill-name>
| 技能 | 描述 |
|-------|-------------|
| [**blender-mcp**](/user-guide/skills/optional/creative/creative-blender-mcp) | 通过 socket 连接 blender-mcp 插件，直接从 Hermes 控制 Blender。创建 3D 对象、材质、动画，并运行任意 Blender Python（bpy）代码。适用于用户希望在 Blender 中创建或修改任何内容的场景。 |
| [**concept-diagrams**](/user-guide/skills/optional/creative/creative-concept-diagrams) | 生成扁平、极简、支持亮色/暗色模式的 SVG 图表，输出为独立 HTML 文件，采用统一的教育视觉语言，包含 9 种语义色阶、句首大写排版及自动暗色模式。最适合教育和说明类内容。 |
| [**hyperframes**](/user-guide/skills/optional/creative/creative-hyperframes) | 使用 HyperFrames 创建基于 HTML 的视频合成、动态标题卡、社交叠层、字幕访谈视频、音频响应视觉效果及着色器转场。HTML 是视频的唯一来源。适用于用户希望制作任何视频内容的场景。 |
| [**kanban-video-orchestrator**](/user-guide/skills/optional/creative/creative-kanban-video-orchestrator) | 规划、搭建并监控由 Hermes Kanban 支撑的多 agent 视频制作流水线。适用于用户希望制作任何类型视频的场景 — 叙事影片、产品/营销视频、MV、解说视频、ASCII/终端艺术、抽象/生成式循环等。 |
| [**meme-generation**](/user-guide/skills/optional/creative/creative-meme-generation) | 通过选取模板并使用 Pillow 叠加文字来生成真实的 meme 图片，输出实际的 .png 文件。 |

2
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/skills-catalog.md
View file

@ -35,7 +35,6 @@ Hermes 在执行 `hermes update` 时也会同步内置技能，但同步清单
| 技能 | 描述 | 路径 |
|-------|-------------|------|
| [`architecture-diagram`](/user-guide/skills/bundled/creative/creative-architecture-diagram) | 以 HTML 形式生成深色主题的 SVG 架构/云/基础设施图。 | `creative/architecture-diagram` |
| [`ascii-art`](/user-guide/skills/bundled/creative/creative-ascii-art) | ASCII 艺术：pyfiglet、cowsay、boxes、图像转 ASCII。 | `creative/ascii-art` |
| [`ascii-video`](/user-guide/skills/bundled/creative/creative-ascii-video) | ASCII 视频：将视频/音频转换为彩色 ASCII MP4/GIF。 | `creative/ascii-video` |
| [`baoyu-infographic`](/user-guide/skills/bundled/creative/creative-baoyu-infographic) | 信息图（可视化）：21 种布局 × 21 种风格。 | `creative/baoyu-infographic` |
@ -48,7 +47,6 @@ Hermes 在执行 `hermes update` 时也会同步内置技能，但同步清单
| [`p5js`](/user-guide/skills/bundled/creative/creative-p5js) | p5.js 草图：生成艺术、着色器、交互、3D。 | `creative/p5js` |
| [`popular-web-designs`](/user-guide/skills/bundled/creative/creative-popular-web-designs) | 54 种真实设计系统（Stripe、Linear、Vercel）的 HTML/CSS 实现。 | `creative/popular-web-designs` |
| [`pretext`](/user-guide/skills/bundled/creative/creative-pretext) | 使用 @chenglou/pretext 构建创意浏览器 demo——无 DOM 的文本布局，支持 ASCII 艺术、绕障碍物的排版流、文字即几何游戏、动态排版和文字驱动的生成艺术。生成单文件 HTML。 | `creative/pretext` |
| [`sketch`](/user-guide/skills/bundled/creative/creative-sketch) | 一次性 HTML 原型：生成 2-3 个设计变体供对比。 | `creative/sketch` |
| [`songwriting-and-ai-music`](/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music) | 歌曲创作技巧与 Suno AI 音乐 prompt（提示词）。 | `creative/songwriting-and-ai-music` |
| [`touchdesigner-mcp`](/user-guide/skills/bundled/creative/creative-touchdesigner-mcp) | 通过 twozero MCP 控制运行中的 TouchDesigner 实例——创建算子、设置参数、连接节点、执行 Python、构建实时视觉效果。36 个原生工具。 | `creative/touchdesigner-mcp` |

165
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-architecture-diagram.md
View file

@ -1,165 +0,0 @@
---
title: "Architecture Diagram — 深色主题 SVG 架构/云/基础设施图表（HTML 格式）"
sidebar_label: "Architecture Diagram"
description: "深色主题 SVG 架构/云/基础设施图表（HTML 格式）"
---
{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
# Architecture Diagram
深色主题 SVG 架构/云/基础设施图表，以 HTML 格式输出。
## Skill 元数据
| | |
|---|---|
| 来源 | 内置（默认安装） |
| 路径 | `skills/creative/architecture-diagram` |
| 版本 | `1.0.0` |
| 作者 | Cocoon AI (hello@cocoon-ai.com)，由 Hermes Agent 移植 |
| 许可证 | MIT |
| 平台 | linux, macos, windows |
| 标签 | `architecture`, `diagrams`, `SVG`, `HTML`, `visualization`, `infrastructure`, `cloud` |
| 相关 skill | [`concept-diagrams`](/user-guide/skills/optional/creative/creative-concept-diagrams), [`excalidraw`](/user-guide/skills/bundled/creative/creative-excalidraw) |
## 参考：完整 SKILL.md
:::info
以下是 Hermes 在触发该 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
:::
# Architecture Diagram Skill
生成专业的深色主题技术架构图，输出为包含内联 SVG 图形的独立 HTML 文件。无需外部工具、无需 API 密钥、无需渲染库——只需写入 HTML 文件并在浏览器中打开即可。
## 适用范围
**最适合：**
- 软件系统架构（前端/后端/数据库层）
- 云基础设施（VPC、区域、子网、托管服务）
- 微服务/服务网格拓扑
- 数据库 + API 映射、部署图
- 任何具有技术基础设施主题、适合深色网格背景风格的内容
**以下场景请优先考虑其他工具：**
- 物理、化学、数学、生物或其他科学学科
- 实物对象（车辆、硬件、解剖结构、截面图）
- 平面图、叙事流程、教育/教科书风格的视觉内容
- 手绘白板草图（建议使用 `excalidraw`）
- 动画说明（建议使用动画相关 skill）
如果有更专业的 skill 适用于该主题，请优先使用。如果没有合适的，本 skill 也可作为通用 SVG 图表的备选方案——输出内容将带有下述深色技术风格。
基于 [Cocoon AI 的 architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator)（MIT 许可证）。
## 工作流程
1. 用户描述其系统架构（组件、连接关系、技术栈）
2. 按照下方设计规范生成 HTML 文件
3. 使用 `write_file` 保存为 `.html` 文件（例如 `~/architecture-diagram.html`）
4. 用户在任意浏览器中打开——支持离线使用，无需任何依赖
### 输出位置
将图表保存到用户指定路径，或默认保存至当前工作目录：
```
./[project-name]-architecture.html
```
### 预览
保存后，建议用户通过以下命令打开：
```bash
# macOS
open ./my-architecture.html
# Linux
xdg-open ./my-architecture.html
```
## 设计规范与视觉语言
### 颜色方案（语义映射）
使用特定的 `rgba` 填充色和十六进制描边色对组件进行分类：
| 组件类型 | 填充色（rgba） | 描边色（Hex） |
| :--- | :--- | :--- |
| **前端** | `rgba(8, 51, 68, 0.4)` | `#22d3ee`（cyan-400） |
| **后端** | `rgba(6, 78, 59, 0.4)` | `#34d399`（emerald-400） |
| **数据库** | `rgba(76, 29, 149, 0.4)` | `#a78bfa`（violet-400） |
| **AWS/云** | `rgba(120, 53, 15, 0.3)` | `#fbbf24`（amber-400） |
| **安全** | `rgba(136, 19, 55, 0.4)` | `#fb7185`（rose-400） |
| **消息总线** | `rgba(251, 146, 60, 0.3)` | `#fb923c`（orange-400） |
| **外部** | `rgba(30, 41, 59, 0.5)` | `#94a3b8`（slate-400） |
### 字体与背景
- **字体：** JetBrains Mono（等宽字体），从 Google Fonts 加载
- **字号：** 12px（名称）、9px（副标签）、8px（注释）、7px（极小标签）
- **背景：** Slate-950（`#020617`），带有细腻的 40px 网格图案
```svg
<!-- 背景网格图案 -->
<pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse">
<path d="M 40 0 L 0 0 0 40" fill="none" stroke="#1e293b" stroke-width="0.5"/>
</pattern>
```
## 技术实现细节
### 组件渲染
组件为圆角矩形（`rx="6"`），描边宽度 1.5px。为防止箭头透过半透明填充色显现，使用**双矩形遮罩技术**：
1. 绘制不透明背景矩形（`#0f172a`）
2. 在其上方绘制半透明样式矩形
### 连接规则
- **Z 轴顺序：** 在 SVG 早期绘制箭头（在网格之后），使其渲染在组件框的下方
- **箭头头部：** 通过 SVG marker 定义
- **安全流：** 使用 rose 色（`#fb7185`）虚线
- **边界：**
- *安全组：* 虚线（`4,4`），rose 色
- *区域：* 大虚线（`8,4`），amber 色，`rx="12"`
### 间距与布局规则
- **标准高度：** 60px（服务）；80–120px（大型组件）
- **垂直间距：** 组件之间最小 40px
- **消息总线：** 必须放置在服务之间的间隙中，不得与其重叠
- **图例位置：** **关键。** 必须放置在所有边界框的外部。计算所有边界的最低 Y 坐标，并将图例放置在其下方至少 20px 处。
## 文档结构
生成的 HTML 文件遵循四段式布局：
1. **页眉：** 带有脉冲点指示器的标题和副标题
2. **主 SVG：** 包含在圆角边框卡片中的图表
3. **摘要卡片：** 图表下方的三张卡片网格，用于展示高层次详情
4. **页脚：** 简洁的元数据信息
### 信息卡片模式
```html
<div class="card">
<div class="card-header">
<div class="card-dot cyan"></div>
<h3>Title</h3>
</div>
<ul>
<li>• Item one</li>
<li>• Item two</li>
</ul>
</div>
```
## 输出要求
- **单文件：** 一个自包含的 `.html` 文件
- **无外部依赖：** 所有 CSS 和 SVG 必须内联（Google Fonts 除外）
- **无 JavaScript：** 所有动画（如脉冲点）使用纯 CSS 实现
- **兼容性：** 必须在任何现代浏览器中正确渲染
## 模板参考
加载完整 HTML 模板以获取精确的结构、CSS 和 SVG 组件示例：
```
skill_view(name="architecture-diagram", file_path="templates/template.html")
```
模板包含每种组件类型（前端、后端、数据库、云、安全）、箭头样式（标准、虚线、曲线）、安全组、区域边界和图例的完整示例——生成图表时请以此作为结构参考。

2
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-claude-design.md
View file

@ -21,7 +21,7 @@ description: "设计一次性 HTML 制品（落地页、幻灯片、原型）"
| 许可证 | MIT |
| 平台 | linux, macos, windows |
| 标签 | `design`, `html`, `prototype`, `ux`, `ui`, `creative`, `artifact`, `deck`, `motion`, `design-system` |
| 相关 skill | [`design-md`](/user-guide/skills/bundled/creative/creative-design-md), [`popular-web-designs`](/user-guide/skills/bundled/creative/creative-popular-web-designs), [`excalidraw`](/user-guide/skills/bundled/creative/creative-excalidraw), [`architecture-diagram`](/user-guide/skills/bundled/creative/creative-architecture-diagram) |
| 相关 skill | [`design-md`](/user-guide/skills/bundled/creative/creative-design-md), [`popular-web-designs`](/user-guide/skills/bundled/creative/creative-popular-web-designs), [`excalidraw`](/user-guide/skills/bundled/creative/creative-excalidraw), [`html-artifact`](/user-guide/skills/bundled/creative/creative-html-artifact) |
## 参考：完整 SKILL.md

2
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-design-md.md
View file

@ -21,7 +21,7 @@ description: "编写/验证/导出 Google 的 DESIGN"
| 许可证 | MIT |
| 平台 | linux, macos, windows |
| 标签 | `design`, `design-system`, `tokens`, `ui`, `accessibility`, `wcag`, `tailwind`, `dtcg`, `google` |
| 相关 skill | [`popular-web-designs`](/user-guide/skills/bundled/creative/creative-popular-web-designs), [`claude-design`](/user-guide/skills/bundled/creative/creative-claude-design), [`excalidraw`](/user-guide/skills/bundled/creative/creative-excalidraw), [`architecture-diagram`](/user-guide/skills/bundled/creative/creative-architecture-diagram) |
| 相关 skill | [`popular-web-designs`](/user-guide/skills/bundled/creative/creative-popular-web-designs), [`claude-design`](/user-guide/skills/bundled/creative/creative-claude-design), [`excalidraw`](/user-guide/skills/bundled/creative/creative-excalidraw), [`html-artifact`](/user-guide/skills/bundled/creative/creative-html-artifact) |
## 参考：完整 SKILL.md

2
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-pretext.md
View file

@ -21,7 +21,7 @@ description: "适用于使用 @chenglou/pretext 构建创意浏览器演示 —
| 许可证 | MIT |
| 平台 | linux, macos, windows |
| 标签 | `creative-coding`, `typography`, `pretext`, `ascii-art`, `canvas`, `generative`, `text-layout`, `kinetic-typography` |
| 相关 skill | [`p5js`](/user-guide/skills/bundled/creative/creative-p5js), [`claude-design`](/user-guide/skills/bundled/creative/creative-claude-design), [`excalidraw`](/user-guide/skills/bundled/creative/creative-excalidraw), [`architecture-diagram`](/user-guide/skills/bundled/creative/creative-architecture-diagram) |
| 相关 skill | [`p5js`](/user-guide/skills/bundled/creative/creative-p5js), [`claude-design`](/user-guide/skills/bundled/creative/creative-claude-design), [`excalidraw`](/user-guide/skills/bundled/creative/creative-excalidraw), [`html-artifact`](/user-guide/skills/bundled/creative/creative-html-artifact) |
## 参考：完整 SKILL.md

238
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/creative/creative-sketch.md
View file

@ -1,238 +0,0 @@
---
title: "Sketch — 一次性 HTML 原型：2-3 个设计方案对比"
sidebar_label: "Sketch"
description: "一次性 HTML 原型：2-3 个设计方案对比"
---
{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
# Sketch
一次性 HTML 原型：2-3 个设计方案对比。
## Skill 元数据
| | |
|---|---|
| 来源 | 内置（默认安装） |
| 路径 | `skills/creative/sketch` |
| 版本 | `1.0.0` |
| 作者 | Hermes Agent（改编自 gsd-build/get-shit-done） |
| 许可证 | MIT |
| 平台 | linux, macos, windows |
| 标签 | `sketch`, `mockup`, `design`, `ui`, `prototype`, `html`, `variants`, `exploration`, `wireframe`, `comparison` |
| 相关 skill | [`spike`](/user-guide/skills/bundled/software-development/software-development-spike), [`claude-design`](/user-guide/skills/bundled/creative/creative-claude-design), [`popular-web-designs`](/user-guide/skills/bundled/creative/creative-popular-web-designs), [`excalidraw`](/user-guide/skills/bundled/creative/creative-excalidraw) |
## 参考：完整 SKILL.md
:::info
以下是 Hermes 在触发该 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
:::
# Sketch
当用户希望**在确定方向之前先看到设计效果**时使用此 skill——以一次性 HTML 原型的形式探索 UI/UX 想法。目的是生成 2-3 个可交互的方案，让用户并排对比视觉方向，而非产出可交付的代码。
当用户说以下内容时加载此 skill："sketch this screen"、"show me what X could look like"、"compare layout A vs B"、"give me 2-3 takes on this UI"、"let me see some variants"、"mockup this before I build"。
## 不适用场景
- 用户需要生产级组件——使用 `claude-design` 或正式构建
- 用户需要精良的一次性 HTML 产物（落地页、幻灯片）——使用 `claude-design`
- 用户需要图表——使用 `excalidraw`、`architecture-diagram`
- 设计已确定——直接构建即可
## 如果用户安装了完整的 GSD 系统
如果 `gsd-sketch` 作为同级 skill 出现（通过 `npx get-shit-done-cc --hermes` 安装），优先使用 **`gsd-sketch`** 以获得完整工作流：持久化的 `.planning/sketches/` 目录（含 MANIFEST）、前沿模式分析、跨历史草图的一致性审计，以及与 GSD 其余部分的集成。本 skill 是轻量级独立版本——无状态机制的一次性草图。
## 核心方法
```
intake → variants → head-to-head → pick winner (or iterate)
```
### 1. Intake（如果用户已提供足够信息则跳过）
在生成方案之前，获取三项信息——每次只问一个问题，不要一次全问：
1. **感觉。** "这个应该给人什么感觉？形容词、情绪、氛围。"——*"calm, editorial, like Linear"* 比 *"minimal"* 更有参考价值。
2. **参考。** "哪些 app、网站或产品接近你想象中的感觉？"——实际参考比抽象描述更有效。
3. **核心操作。** "用户在这个页面上最重要的单一操作是什么？"——所有方案都应服务于此；否则只是装饰。
每次回答后简短复述，再问下一个问题。如果用户已一次性提供了全部三项，直接跳到方案生成。
### 2. 方案（2-3 个，不少于 1 个，极少超过 4 个）
一次性生成 **2-3 个方案**。每个方案是一个完整的独立 HTML 文件。不要描述方案——直接构建。目的是对比。
每个方案应采取**不同的设计立场**，而非不同的像素值。三种有效的方案维度：
- **密度：** 紧凑 / 宽松 / 极密（选两个对比极端）
- **重点：** 内容优先 / 操作优先 / 工具优先
- **美学：** 编辑风格 / 实用主义 / 趣味性
- **布局：** 单列 / 侧边栏 / 分屏
- **基调：** 卡片式 / 纯内容 / 文档风格
选定一个维度并从中拉开差距。两个仅在强调色上不同的方案是无效的——用户无法区分。
**方案命名：** 描述立场，而非编号。
<!-- ascii-guard-ignore -->
```
sketches/
├── 001-calm-editorial/
│ ├── index.html
│ └── README.md
├── 001-utilitarian-dense/
│ ├── index.html
│ └── README.md
└── 001-playful-split/
├── index.html
└── README.md
```
<!-- ascii-guard-ignore-end -->
### 3. 制作真实的 HTML
每个方案是一个**单一自包含的 HTML 文件**：
- 内联 `<style>`——无需构建步骤，无外部 CSS
- 系统字体或通过 `<link>` 引入一个 Google Font
- 通过 CDN 使用 Tailwind（`<script src="https://cdn.tailwindcss.com"></script>`）可以
- 真实的虚假内容——实际句子、实际姓名，而非"Lorem ipsum"
- **可交互**：链接可点击，悬停效果真实，至少一个状态转换（展开/收起、筛选、切换）。一个冻结的静态图比一个粗糙但有动效的方案更差。
在浏览器中打开验证。如果看起来有问题，在展示给用户之前修复。
**使用 Hermes 的浏览器工具对方案进行视觉验证。** 不要只写 HTML 然后寄希望于它能正常渲染；加载每个方案并查看：
```
browser_navigate(url="file:///absolute/path/to/sketches/001-calm-editorial/index.html")
browser_vision(question="Does this layout look clean and readable? Any visible bugs (overlapping text, unstyled elements, broken images)?")
```
`browser_vision` 返回页面实际内容的 AI 描述及截图路径——能捕获纯源码检查遗漏的布局问题（例如字体导入静默失败、flex 容器塌陷）。修复后重新导航，直到每个方案看起来正确为止。
**快速启动用的默认 CSS reset + 系统字体栈：**
```html
<style>
* { box-sizing: border-box; margin: 0; padding: 0; }
body {
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
"Helvetica Neue", Arial, sans-serif;
-webkit-font-smoothing: antialiased;
color: #1a1a1a;
background: #fafafa;
line-height: 1.5;
}
</style>
```
### 4. 方案 README
每个方案的 `README.md` 回答以下内容：
```markdown
## Variant: {stance name}
### Design stance
One sentence on the principle driving this variant.
### Key choices
- Layout: ...
- Typography: ...
- Color: ...
- Interaction: ...
### Trade-offs
- Strong at: ...
- Weak at: ...
### Best for
- The kind of user or use case this variant actually serves
```
### 5. 正面对比
所有方案构建完成后，以对比形式呈现。不要只是罗列——**给出观点**：
```markdown
## Three takes on the home screen
| Dimension | Calm editorial | Utilitarian dense | Playful split |
|-----------|----------------|-------------------|---------------|
| Density | Low | High | Medium |
| Primary action visibility | Low | High | Medium |
| Scan-ability | High | Medium | Low |
| Feel | Calm, trusted | Sharp, tool-like | Inviting, energetic |
**My take:** Utilitarian dense for power users, calm editorial for content-forward audiences. Playful split is weakest — tries to do both and commits to neither.
```
让用户选出胜出方案，或将两个方案合并为混合版，或要求新一轮迭代。
## 主题化（当项目有视觉标识时）
如果用户有现有主题（颜色、字体、token），将共享 token 放入 `sketches/themes/tokens.css` 并在每个方案中 `@import`。保持 token 精简：
```css
/* sketches/themes/tokens.css */
:root {
--color-bg: #fafafa;
--color-fg: #1a1a1a;
--color-accent: #0066ff;
--color-muted: #666;
--radius: 8px;
--font-display: "Inter", sans-serif;
--font-body: -apple-system, BlinkMacSystemFont, sans-serif;
}
```
不要对一次性草图过度 token 化——三种颜色加一种字体通常已足够。
## 交互基准
当用户能够完成以下操作时，草图的交互程度即为合格：
1. **点击主要操作**并看到可见的变化（状态变更、模态框、toast、导航模拟）
2. **看到一个有意义的状态转换**（筛选列表、切换模式、展开/收起面板）
3. **悬停可识别的交互元素**（按钮、行、标签页）
超过此程度是对一次性草图的过度工程化。低于此程度则只是截图。
## 前沿模式（决定下一步草图内容）
如果草图已存在且用户询问"接下来应该草图什么？"：
- **一致性缺口**——来自不同草图的两个胜出方案做出了独立选择，尚未组合在一起
- **未草图的页面**——被引用但从未探索过
- **状态覆盖**——已草图了正常路径，但未覆盖空状态 / 加载中 / 错误 / 千条数据
- **响应式缺口**——在某一视口下验证过；在移动端 / 超宽屏下是否成立？
- **交互模式**——静态布局已存在；过渡动效、拖拽、滚动行为尚未探索
提出 2-4 个命名候选项，让用户选择。
## 输出
- 在仓库根目录创建 `sketches/`（如果用户使用 GSD 约定则为 `.planning/sketches/`）
- 每个方案一个子目录：`NNN-stance-name/index.html` + `README.md`
- 告知用户如何打开：macOS 上用 `open sketches/001-calm-editorial/index.html`，Linux 上用 `xdg-open`，Windows 上用 `start`
- 保持方案的一次性特性——如果你觉得有必要保留某个草图，应将其提升为真实项目代码，而非作为资产保管
**单个方案的典型工具调用序列：**
```
terminal("mkdir -p sketches/001-calm-editorial")
write_file("sketches/001-calm-editorial/index.html", "<!doctype html>...")
write_file("sketches/001-calm-editorial/README.md", "## Variant: Calm editorial\n...")
browser_navigate(url="file://$(pwd)/sketches/001-calm-editorial/index.html")
browser_vision(question="How does this look? Any obvious layout issues?")
```
对每个方案重复上述步骤，然后呈现对比表格。
## 致谢
改编自 GSD（Get Shit Done）项目的 `/gsd-sketch` 工作流——MIT © 2025 Lex Christopherson（[gsd-build/get-shit-done](https://github.com/gsd-build/get-shit-done)）。完整 GSD 系统提供持久化草图状态、主题/方案模式参考及一致性审计工作流；通过 `npx get-shit-done-cc --hermes --global` 安装。

2
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/software-development/software-development-spike.md
View file

@ -21,7 +21,7 @@ description: "在构建前验证想法的一次性实验"
| 许可证 | MIT |
| 平台 | linux, macos, windows |
| 标签 | `spike`, `prototype`, `experiment`, `feasibility`, `throwaway`, `exploration`, `research`, `planning`, `mvp`, `proof-of-concept` |
| 相关 skill | [`sketch`](/user-guide/skills/bundled/creative/creative-sketch)、[`writing-plans`](/user-guide/skills/bundled/software-development/software-development-writing-plans)、[`subagent-driven-development`](/user-guide/skills/bundled/software-development/software-development-subagent-driven-development)、[`plan`](/user-guide/skills/bundled/software-development/software-development-plan) |
| 相关 skill | [`html-artifact`](/user-guide/skills/bundled/creative/creative-html-artifact)、[`writing-plans`](/user-guide/skills/bundled/software-development/software-development-writing-plans)、[`subagent-driven-development`](/user-guide/skills/bundled/software-development/software-development-subagent-driven-development)、[`plan`](/user-guide/skills/bundled/software-development/software-development-plan) |
## 参考：完整 SKILL.md

379
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/creative/creative-concept-diagrams.md
View file

@ -1,379 +0,0 @@
---
title: "概念图"
sidebar_label: "概念图"
description: "以统一的教育视觉语言生成扁平、简约、支持明暗模式的 SVG 图表，输出为独立 HTML 文件，包含 9 种语义色阶、句首大写排版及自动暗色模式。..."
---
{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
# 概念图
以统一的教育视觉语言生成扁平、简约、支持明暗模式的 SVG 图表，输出为独立 HTML 文件，包含 9 种语义色阶、句首大写排版及自动暗色模式。最适合教育类和非软件类视觉内容——物理装置、化学机制、数学曲线、实物（飞机、涡轮机、智能手机、机械表）、解剖图、平面图、截面图、叙事流程（X 的生命周期、Y 的过程）、中心辐射型系统集成（智慧城市、IoT）以及爆炸分层视图。若已有更专业的 skill 适用于该主题（专用软件/云架构、手绘草图、动画说明等），优先使用那些 skill——否则本 skill 也可作为通用 SVG 图表的备选方案，具备简洁的教育风格外观。内置 15 个示例图表。
## Skill 元数据
| | |
|---|---|
| 来源 | 可选 — 通过 `hermes skills install official/creative/concept-diagrams` 安装 |
| 路径 | `optional-skills/creative/concept-diagrams` |
| 版本 | `0.1.0` |
| 作者 | v1k22（原始 PR），移植至 hermes-agent |
| 许可证 | MIT |
| 平台 | linux, macos, windows |
| 标签 | `diagrams`, `svg`, `visualization`, `education`, `physics`, `chemistry`, `engineering` |
| 相关 skills | [`architecture-diagram`](/user-guide/skills/bundled/creative/creative-architecture-diagram), [`excalidraw`](/user-guide/skills/bundled/creative/creative-excalidraw), `generative-widgets` |
## 参考：完整 SKILL.md
:::info
以下是 Hermes 在触发本 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
:::
# 概念图
使用统一的扁平、简约设计系统生成生产级 SVG 图表。输出为单个自包含 HTML 文件，可在任何现代浏览器中一致渲染，并自动支持明暗模式。
## 适用范围
**最适合：**
- 物理装置、化学机制、数学曲线、生物学
- 实物（飞机、涡轮机、智能手机、机械表、细胞）
- 解剖图、截面图、爆炸分层视图
- 平面图、建筑改造图
- 叙事流程（X 的生命周期、Y 的过程）
- 中心辐射型系统集成（智慧城市、IoT 网络、电网）
- 任何领域的教育/教科书风格视觉内容
- 定量图表（分组柱状图、能量曲线）
**优先考虑其他方案：**
- 具有深色科技风格的专用软件/云基础设施架构（如有 `architecture-diagram` 可用，优先使用）
- 手绘白板草图（如有 `excalidraw` 可用，优先使用）
- 动画说明或视频输出（考虑动画 skill）
若已有更专业的 skill 适用于该主题，优先使用。若无合适选项，本 skill 可作为通用 SVG 图表备选方案——输出将呈现下文描述的简洁教育风格，适用于几乎任何主题。
## 工作流程
1. 确定图表类型（见下方"图表类型"）。
2. 使用设计系统规则布局组件。
3. 使用 `templates/template.html` 作为包装器编写完整 HTML 页面——将 SVG 粘贴到模板中 `<!-- PASTE SVG HERE -->` 的位置。
4. 保存为独立 `.html` 文件（例如 `~/my-diagram.html` 或 `./my-diagram.html`）。
5. 用户直接在浏览器中打开——无需服务器，无需依赖。
可选：若用户需要可浏览的多图表画廊，参见底部"本地预览服务器"。
加载 HTML 模板：
```
skill_view(name="concept-diagrams", file_path="templates/template.html")
```
模板内嵌完整 CSS 设计系统（`c-*` 颜色类、文本类、明暗变量、箭头标记样式）。你生成的 SVG 依赖这些类存在于宿主页面中。
---
## 设计系统
### 设计理念
- **扁平**：无渐变、无投影、无模糊、无发光、无霓虹效果。
- **简约**：只展示核心内容，框内无装饰性图标。
- **一致**：每张图表使用相同的颜色、间距、排版和描边宽度。
- **暗色模式就绪**：所有颜色通过 CSS 类自动适配——无需为每种模式单独编写 SVG。
### 调色板
9 种色阶，每种 7 个色阶值。将类名放在 `<g>` 或形状元素上；模板 CSS 自动处理明暗两种模式。
| 类名 | 50（最浅） | 100 | 200 | 400 | 600 | 800 | 900（最深） |
|------------|---------------|---------|---------|---------|---------|---------|---------------|
| `c-purple` | #EEEDFE | #CECBF6 | #AFA9EC | #7F77DD | #534AB7 | #3C3489 | #26215C |
| `c-teal` | #E1F5EE | #9FE1CB | #5DCAA5 | #1D9E75 | #0F6E56 | #085041 | #04342C |
| `c-coral` | #FAECE7 | #F5C4B3 | #F0997B | #D85A30 | #993C1D | #712B13 | #4A1B0C |
| `c-pink` | #FBEAF0 | #F4C0D1 | #ED93B1 | #D4537E | #993556 | #72243E | #4B1528 |
| `c-gray` | #F1EFE8 | #D3D1C7 | #B4B2A9 | #888780 | #5F5E5A | #444441 | #2C2C2A |
| `c-blue` | #E6F1FB | #B5D4F4 | #85B7EB | #378ADD | #185FA5 | #0C447C | #042C53 |
| `c-green` | #EAF3DE | #C0DD97 | #97C459 | #639922 | #3B6D11 | #27500A | #173404 |
| `c-amber` | #FAEEDA | #FAC775 | #EF9F27 | #BA7517 | #854F0B | #633806 | #412402 |
| `c-red` | #FCEBEB | #F7C1C1 | #F09595 | #E24B4A | #A32D2D | #791F1F | #501313 |
#### 颜色分配规则
颜色编码**语义**，而非顺序。切勿像彩虹一样循环使用颜色。
- 按**类别**对节点分组——同类型的所有节点共用一种颜色。
- 对中性/结构性节点（起点、终点、通用步骤、用户）使用 `c-gray`。
- 每张图表使用 **2-3 种颜色**，而非 6 种以上。
- 通用类别优先使用 `c-purple`、`c-teal`、`c-coral`、`c-pink`。
- 将 `c-blue`、`c-green`、`c-amber`、`c-red` 保留用于语义含义（信息、成功、警告、错误）。
明暗色阶映射（由模板 CSS 处理——直接使用类名即可）：
- 亮色模式：50 填充 + 600 描边 + 800 标题 / 600 副标题
- 暗色模式：800 填充 + 200 描边 + 100 标题 / 200 副标题
### 排版
只有两种字体大小，不得例外。
| 类名 | 大小 | 字重 | 用途 |
|-------|------|--------|-----|
| `th` | 14px | 500 | 节点标题、区域标签 |
| `ts` | 12px | 400 | 副标题、描述、箭头标签 |
| `t` | 14px | 400 | 通用文本 |
- **始终使用句首大写。** 禁止首字母大写（Title Case），禁止全大写（ALL CAPS）。
- 每个 `<text>` 必须带有类名（`t`、`ts` 或 `th`），不得有无类名的文本。
- 框内所有文本使用 `dominant-baseline="central"`。
- 框内居中文本使用 `text-anchor="middle"`。
**宽度估算（近似值）：**
- 14px 字重 500：每字符约 8px
- 12px 字重 400：每字符约 6.5px
- 始终验证：`box_width >= (字符数 × px/字符) + 48`（每侧 24px 内边距）
### 间距与布局
- **ViewBox**：`viewBox="0 0 680 H"`，其中 H = 内容高度 + 40px 缓冲。
- **安全区域**：x=40 至 x=640，y=40 至 y=(H-40)。
- **框间距**：最小 60px。
- **框内边距**：水平 24px，垂直 12px。
- **箭头间隙**：箭头与框边缘之间 10px。
- **单行框**：高度 44px。
- **双行框**：高度 56px，标题与副标题基线间距 18px。
- **容器内边距**：每个容器内部最小 20px。
- **最大嵌套层级**：2-3 层。在 680px 宽度下更深的嵌套会难以阅读。
### 描边与形状
- **描边宽度**：所有节点边框 0.5px，不得使用 1px 或 2px。
- **矩形圆角**：节点使用 `rx="8"`，内层容器使用 `rx="12"`，外层容器使用 `rx="16"` 至 `rx="20"`。
- **连接路径**：必须设置 `fill="none"`，否则 SVG 默认填充为黑色。
### 箭头标记
在**每个** SVG 开头包含以下 `<defs>` 块：
```xml
<defs>
<marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5"
markerWidth="6" markerHeight="6" orient="auto-start-reverse">
<path d="M2 1L8 5L2 9" fill="none" stroke="context-stroke"
stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
</marker>
</defs>
```
在线条上使用 `marker-end="url(#arrow)"`。箭头通过 `context-stroke` 继承线条颜色。
### CSS 类（由模板提供）
模板页面提供：
- 文本：`.t`、`.ts`、`.th`
- 中性：`.box`、`.arr`、`.leader`、`.node`
- 色阶：`.c-purple`、`.c-teal`、`.c-coral`、`.c-pink`、`.c-gray`、`.c-blue`、`.c-green`、`.c-amber`、`.c-red`（均自动支持明暗模式）
你**无需**重新定义这些类——直接在 SVG 中应用即可。模板文件包含完整的 CSS 定义。
---
## SVG 样板代码
模板页面中的每个 SVG 均以如下结构开头：
```xml
<svg width="100%" viewBox="0 0 680 {HEIGHT}" xmlns="http://www.w3.org/2000/svg">
<defs>
<marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5"
markerWidth="6" markerHeight="6" orient="auto-start-reverse">
<path d="M2 1L8 5L2 9" fill="none" stroke="context-stroke"
stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
</marker>
</defs>
<!-- Diagram content here -->
</svg>
```
将 `{HEIGHT}` 替换为实际计算高度（最后一个元素底部 + 40px）。
### 节点模式
**单行节点（44px）：**
```xml
<g class="node c-blue">
<rect x="100" y="20" width="180" height="44" rx="8" stroke-width="0.5"/>
<text class="th" x="190" y="42" text-anchor="middle" dominant-baseline="central">Service name</text>
</g>
```
**双行节点（56px）：**
```xml
<g class="node c-teal">
<rect x="100" y="20" width="200" height="56" rx="8" stroke-width="0.5"/>
<text class="th" x="200" y="38" text-anchor="middle" dominant-baseline="central">Service name</text>
<text class="ts" x="200" y="56" text-anchor="middle" dominant-baseline="central">Short description</text>
</g>
```
**连接线（无标签）：**
```xml
<line x1="200" y1="76" x2="200" y2="120" class="arr" marker-end="url(#arrow)"/>
```
**容器（虚线或实线）：**
```xml
<g class="c-purple">
<rect x="40" y="92" width="600" height="300" rx="16" stroke-width="0.5"/>
<text class="th" x="66" y="116">Container label</text>
<text class="ts" x="66" y="134">Subtitle info</text>
</g>
```
---
## 图表类型
根据主题选择合适的布局：
1. **流程图** — CI/CD 流水线、请求生命周期、审批工作流、数据处理。单向流（从上到下或从左到右），每行最多 4-5 个节点。
2. **结构/包含图** — 云基础设施嵌套、分层系统架构。大型外层容器包含内层区域，虚线矩形表示逻辑分组。
3. **API/端点映射** — REST 路由、GraphQL schema。从根节点树状展开，分支到资源组，每组包含端点节点。
4. **微服务拓扑** — 服务网格、事件驱动系统。服务作为节点，箭头表示通信模式，消息队列位于服务之间。
5. **数据流图** — ETL 流水线、流式架构。从数据源经处理流向数据汇，方向从左到右。
6. **实物/结构图** — 交通工具、建筑、硬件、解剖图。使用与实物形态匹配的形状——弯曲体用 `<path>`，锥形用 `<polygon>`，圆柱部件用 `<ellipse>`/`<circle>`，隔间用嵌套 `<rect>`。参见 `references/physical-shape-cookbook.md`。
7. **基础设施/系统集成图** — 智慧城市、IoT 网络、多域系统。中心辐射布局，中央平台连接各子系统。按系统使用语义线型（`.data-line`、`.power-line`、`.water-pipe`、`.road`）。参见 `references/infrastructure-patterns.md`。
8. **UI/仪表盘原型** — 管理面板、监控仪表盘。屏幕框架内嵌套图表/仪表/指示器元素。参见 `references/dashboard-patterns.md`。
对于实物图、基础设施图和仪表盘图，生成前请先加载对应的参考文件——每个文件提供现成的 CSS 类和形状原语。
---
## 验证清单
在最终确定任何 SVG 之前，验证以下**所有**项目：
1. 每个 `<text>` 都有类名 `t`、`ts` 或 `th`。
2. 框内每个 `<text>` 都有 `dominant-baseline="central"`。
3. 用作箭头的每个连接 `<path>` 或 `<line>` 都有 `fill="none"`。
4. 没有箭头线穿过无关的框。
5. 14px 文本：`box_width >= (最长标签字符数 × 8) + 48`。
6. 12px 文本：`box_width >= (最长标签字符数 × 6.5) + 48`。
7. ViewBox 高度 = 最底部元素 + 40px。
8. 所有内容在 x=40 至 x=640 范围内。
9. 颜色类（`c-*`）放在 `<g>` 或形状元素上，不得放在 `<path>` 连接线上。
10. 箭头 `<defs>` 块存在。
11. 无渐变、投影、模糊或发光效果。
12. 所有节点边框描边宽度为 0.5px。
---
## 输出与预览
### 默认：独立 HTML 文件
写入单个 `.html` 文件，用户可直接打开。无需服务器，无需依赖，离线可用。模式：
```python
# 1. Load the template
template = skill_view("concept-diagrams", "templates/template.html")
# 2. Fill in title, subtitle, and paste your SVG
html = template.replace(
"<!-- DIAGRAM TITLE HERE -->", "SN2 reaction mechanism"
).replace(
"<!-- OPTIONAL SUBTITLE HERE -->", "Bimolecular nucleophilic substitution"
).replace(
"<!-- PASTE SVG HERE -->", svg_content
)
# 3. Write to a user-chosen path (or ./ by default)
write_file("./sn2-mechanism.html", html)
```
告知用户如何打开：
```
# macOS
open ./sn2-mechanism.html
# Linux
xdg-open ./sn2-mechanism.html
```
### 可选：本地预览服务器（多图表画廊）
仅在用户明确需要可浏览的多图表画廊时使用。
**规则：**
- 仅绑定到 `127.0.0.1`，绝不使用 `0.0.0.0`。在共享网络上将图表暴露在所有网络接口上存在安全风险。
- 选择空闲端口（不得硬编码），并告知用户所选 URL。
- 服务器是可选的、需用户主动选择的——优先使用独立 HTML 文件。
推荐模式（让操作系统选择空闲的临时端口）：
```bash
# Put each diagram in its own folder under .diagrams/
mkdir -p .diagrams/sn2-mechanism
# ...write .diagrams/sn2-mechanism/index.html...
# Serve on loopback only, free port
cd .diagrams && python3 -c "
import http.server, socketserver
with socketserver.TCPServer(('127.0.0.1', 0), http.server.SimpleHTTPRequestHandler) as s:
print(f'Serving at http://127.0.0.1:{s.server_address[1]}/')
s.serve_forever()
" &
```
若用户坚持使用固定端口，使用 `127.0.0.1:<port>`——仍然不得使用 `0.0.0.0`。说明如何停止服务器（`kill %1` 或 `pkill -f "http.server"`）。
---
## 示例参考
`examples/` 目录内置 15 个完整、经过测试的图表。在编写同类型新图表之前，先浏览这些示例以获取可用模式：
| 文件 | 类型 | 演示内容 |
|------|------|--------------|
| `hospital-emergency-department-flow.md` | 流程图 | 带语义颜色的优先级路由 |
| `feature-film-production-pipeline.md` | 流程图 | 分阶段工作流、水平子流程 |
| `automated-password-reset-flow.md` | 流程图 | 带错误分支的认证流程 |
| `autonomous-llm-research-agent-flow.md` | 流程图 | 回环箭头、决策分支 |
| `place-order-uml-sequence.md` | 时序图 | UML 时序图风格 |
| `commercial-aircraft-structure.md` | 实物图 | 使用路径、多边形、椭圆绘制真实形状 |
| `wind-turbine-structure.md` | 实物截面图 | 地下/地上分离、颜色编码 |
| `smartphone-layer-anatomy.md` | 爆炸视图 | 左右交替标签、分层组件 |
| `apartment-floor-plan-conversion.md` | 平面图 | 墙体、门、虚线红色标注改造方案 |
| `banana-journey-tree-to-smoothie.md` | 叙事流程 | 蜿蜒路径、渐进状态变化 |
| `cpu-ooo-microarchitecture.md` | 硬件流水线 | 扇出、内存层次侧边栏 |
| `sn2-reaction-mechanism.md` | 化学图 | 分子、弯曲箭头、能量曲线 |
| `smart-city-infrastructure.md` | 中心辐射图 | 每个系统使用语义线型 |
| `electricity-grid-flow.md` | 多阶段流程图 | 电压层次、流向标记 |
| `ml-benchmark-grouped-bar-chart.md` | 图表 | 分组柱状图、双轴 |
使用以下命令加载任意示例：
```
skill_view(name="concept-diagrams", file_path="examples/<filename>")
```
---
## 快速参考：何时使用何种图表
| 用户说 | 图表类型 | 建议颜色 |
|-----------|--------------|------------------|
| "展示流水线" | 流程图 | 灰色起止点，紫色步骤，红色错误，青色部署 |
| "画数据流" | 数据流水线（从左到右） | 灰色数据源，紫色处理，青色数据汇 |
| "可视化系统" | 结构图（包含关系） | 紫色容器，青色服务，珊瑚色数据 |
| "映射端点" | API 树状图 | 紫色根节点，每个资源组一种色阶 |
| "展示服务" | 微服务拓扑 | 灰色入口，青色服务，紫色总线，珊瑚色 worker |
| "画飞机/交通工具" | 实物图 | 路径、多边形、椭圆绘制真实形状 |
| "智慧城市/IoT" | 中心辐射集成图 | 每个子系统使用语义线型 |
| "展示仪表盘" | UI 原型 | 深色屏幕，图表颜色：青色、紫色、珊瑚色告警 |
| "电网/电力" | 多阶段流程图 | 电压层次（高/中/低压线宽） |
| "风力涡轮机/涡轮机" | 实物截面图 | 基础 + 塔筒截面 + 机舱颜色编码 |
| "X 的旅程/生命周期" | 叙事流程 | 蜿蜒路径，渐进状态变化 |
| "X 的层次/爆炸图" | 爆炸分层视图 | 垂直堆叠，交替标签 |
| "CPU/流水线" | 硬件流水线 | 垂直阶段，扇出到执行端口 |
| "平面图/公寓" | 平面图 | 墙体、门，虚线红色标注改造方案 |
| "反应机制" | 化学图 | 原子、化学键、弯曲箭头、过渡态、能量曲线 |

2
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/creative/creative-kanban-video-orchestrator.md
View file

@ -21,7 +21,7 @@ description: "规划、搭建并监控由 Hermes Kanban 支撑的多智能体视
| 许可证 | MIT |
| 平台 | linux, macos, windows |
| 标签 | `video`, `kanban`, `multi-agent`, `orchestration`, `production-pipeline` |
| 相关技能 | [`kanban-orchestrator`](/user-guide/skills/bundled/devops/devops-kanban-orchestrator)、[`kanban-worker`](/user-guide/skills/bundled/devops/devops-kanban-worker)、[`ascii-video`](/user-guide/skills/bundled/creative/creative-ascii-video)、[`manim-video`](/user-guide/skills/bundled/creative/creative-manim-video)、[`p5js`](/user-guide/skills/bundled/creative/creative-p5js)、[`comfyui`](/user-guide/skills/bundled/creative/creative-comfyui)、[`touchdesigner-mcp`](/user-guide/skills/bundled/creative/creative-touchdesigner-mcp)、[`blender-mcp`](/user-guide/skills/optional/creative/creative-blender-mcp)、[`pixel-art`](/user-guide/skills/bundled/creative/creative-pixel-art)、[`ascii-art`](/user-guide/skills/bundled/creative/creative-ascii-art)、[`songwriting-and-ai-music`](/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music)、[`heartmula`](/user-guide/skills/bundled/media/media-heartmula)、[`songsee`](/user-guide/skills/bundled/media/media-songsee)、[`spotify`](/user-guide/skills/bundled/media/media-spotify)、[`youtube-content`](/user-guide/skills/bundled/media/media-youtube-content)、[`claude-design`](/user-guide/skills/bundled/creative/creative-claude-design)、[`excalidraw`](/user-guide/skills/bundled/creative/creative-excalidraw)、[`architecture-diagram`](/user-guide/skills/bundled/creative/creative-architecture-diagram)、[`concept-diagrams`](/user-guide/skills/optional/creative/creative-concept-diagrams)、[`baoyu-comic`](/user-guide/skills/bundled/creative/creative-baoyu-comic)、[`baoyu-infographic`](/user-guide/skills/bundled/creative/creative-baoyu-infographic)、[`humanizer`](/user-guide/skills/bundled/creative/creative-humanizer)、[`gif-search`](/user-guide/skills/bundled/media/media-gif-search)、[`meme-generation`](/user-guide/skills/optional/creative/creative-meme-generation) |
| 相关技能 | [`kanban-orchestrator`](/user-guide/skills/bundled/devops/devops-kanban-orchestrator)、[`kanban-worker`](/user-guide/skills/bundled/devops/devops-kanban-worker)、[`ascii-video`](/user-guide/skills/bundled/creative/creative-ascii-video)、[`manim-video`](/user-guide/skills/bundled/creative/creative-manim-video)、[`p5js`](/user-guide/skills/bundled/creative/creative-p5js)、[`comfyui`](/user-guide/skills/bundled/creative/creative-comfyui)、[`touchdesigner-mcp`](/user-guide/skills/bundled/creative/creative-touchdesigner-mcp)、[`blender-mcp`](/user-guide/skills/optional/creative/creative-blender-mcp)、[`pixel-art`](/user-guide/skills/bundled/creative/creative-pixel-art)、[`ascii-art`](/user-guide/skills/bundled/creative/creative-ascii-art)、[`songwriting-and-ai-music`](/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music)、[`heartmula`](/user-guide/skills/bundled/media/media-heartmula)、[`songsee`](/user-guide/skills/bundled/media/media-songsee)、[`spotify`](/user-guide/skills/bundled/media/media-spotify)、[`youtube-content`](/user-guide/skills/bundled/media/media-youtube-content)、[`claude-design`](/user-guide/skills/bundled/creative/creative-claude-design)、[`excalidraw`](/user-guide/skills/bundled/creative/creative-excalidraw)、[`html-artifact`](/user-guide/skills/bundled/creative/creative-html-artifact)、[`baoyu-comic`](/user-guide/skills/bundled/creative/creative-baoyu-comic)、[`baoyu-infographic`](/user-guide/skills/bundled/creative/creative-baoyu-infographic)、[`humanizer`](/user-guide/skills/bundled/creative/creative-humanizer)、[`gif-search`](/user-guide/skills/bundled/media/media-gif-search)、[`meme-generation`](/user-guide/skills/optional/creative/creative-meme-generation) |
## 参考：完整 SKILL.md

5
website/sidebars.ts
View file

@ -150,7 +150,6 @@ const sidebars: SidebarsConfig = {
'user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code',
'user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex',
'user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent',
'user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-kanban-codex-lane',
'user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode',
],
},
@ -160,7 +159,6 @@ const sidebars: SidebarsConfig = {
key: 'skills-bundled-creative',
collapsed: true,
items: [
'user-guide/skills/bundled/creative/creative-architecture-diagram',
'user-guide/skills/bundled/creative/creative-ascii-art',
'user-guide/skills/bundled/creative/creative-ascii-video',
'user-guide/skills/bundled/creative/creative-baoyu-infographic',
@ -168,12 +166,12 @@ const sidebars: SidebarsConfig = {
'user-guide/skills/bundled/creative/creative-comfyui',
'user-guide/skills/bundled/creative/creative-design-md',
'user-guide/skills/bundled/creative/creative-excalidraw',
'user-guide/skills/bundled/creative/creative-html-artifact',
'user-guide/skills/bundled/creative/creative-humanizer',
'user-guide/skills/bundled/creative/creative-manim-video',
'user-guide/skills/bundled/creative/creative-p5js',
'user-guide/skills/bundled/creative/creative-popular-web-designs',
'user-guide/skills/bundled/creative/creative-pretext',
'user-guide/skills/bundled/creative/creative-sketch',
'user-guide/skills/bundled/creative/creative-songwriting-and-ai-music',
'user-guide/skills/bundled/creative/creative-touchdesigner-mcp',
],
@ -387,7 +385,6 @@ const sidebars: SidebarsConfig = {
'user-guide/skills/optional/creative/creative-baoyu-article-illustrator',
'user-guide/skills/optional/creative/creative-baoyu-comic',
'user-guide/skills/optional/creative/creative-blender-mcp',
'user-guide/skills/optional/creative/creative-concept-diagrams',
'user-guide/skills/optional/creative/creative-creative-ideation',
'user-guide/skills/optional/creative/creative-hyperframes',
'user-guide/skills/optional/creative/creative-kanban-video-orchestrator',