diff --git a/optional-skills/creative/architecture-visualization-svg-diagrams/SKILL.md b/optional-skills/creative/architecture-visualization-svg-diagrams/SKILL.md new file mode 100644 index 0000000000..8f3c979e70 --- /dev/null +++ b/optional-skills/creative/architecture-visualization-svg-diagrams/SKILL.md @@ -0,0 +1,1541 @@ +--- +name: architecture-visualization-svg-diagrams +description: Generate beautiful, consistent SVG architecture diagrams and host them as interactive web pages. Use this skill whenever the user asks to visualize, diagram, draw, or illustrate any system architecture, infrastructure layout, API map, data flow, CI/CD pipeline, microservice topology, deployment diagram, network topology, or any technical system overview. Also trigger when the user says "show me the architecture", "draw what you built", "visualize the system", "diagram this", or asks for a visual summary of code, infrastructure, or services. After generating the diagram, automatically host it on 0.0.0.0:22223 so the user can view it in a browser. Always use this skill even for simple architecture requests — it ensures visual consistency across all diagrams. +--- + +# Architecture Diagram Skill + +Generate production-quality SVG architecture diagrams with a unified design system, then host them as interactive web pages on `0.0.0.0:22223`. + +Every diagram you produce MUST follow this design system exactly. No exceptions. This ensures visual consistency regardless of subject matter. + +--- + +## Design System + +### Philosophy + +- **Flat**: No gradients, drop shadows, blur, glow, or neon effects. Clean flat surfaces only. +- **Minimal**: Show the essential. No decorative icons, illustrations inside boxes, or ornamental elements. +- **Consistent**: Same colors, spacing, typography, and stroke widths across every diagram. +- **Dark-mode ready**: All colors auto-adapt to light and dark modes via CSS classes. + +### Color Palette + +9 color ramps, each with 7 stops. Use the class names (`c-purple`, `c-teal`, etc.) on SVG group (``) or shape elements — they handle light/dark mode automatically. + +| 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 **gray** (`c-gray`) for neutral/structural nodes (start, end, generic steps, users). +- Use **2-3 colors per diagram**, not 6+. More colors = more noise. +- 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 mode stops:** +- 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 (medium) | Node titles, region labels | +| `ts` | 12px | 400 (regular) | Subtitles, descriptions, arrow labels | +| `t` | 14px | 400 (regular) | General text | + +- **Sentence case always.** Never Title Case, never ALL CAPS. +- Every `` element 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. + +**Font width estimation** (Anthropic Sans): +- 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**: Always `viewBox="0 0 680 H"` where H is 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 for all borders and edges. 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 `` block at the start of **every** SVG: + +```xml + + + + + +``` + +Use `marker-end="url(#arrow)"` on lines. The head inherits the line color via `context-stroke`. + +### CSS Classes (Embedded in Host Page) + +The hosting HTML page includes these styles. Use these class names directly in your SVG: + +```css +/* 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 line */ +.arr { stroke: var(--text-secondary); stroke-width: 1.5px; fill: none; } + +/* Clickable node hover */ +.node { cursor: pointer; } +.node:hover { opacity: 0.85; } + +/* Dashed leader line */ +.leader { stroke: var(--text-tertiary); stroke-width: 0.5px; stroke-dasharray: 4 3; fill: none; } +``` + +### Node Patterns + +#### Single-line node (44px) + +```xml + + + Service name + +``` + +#### Two-line node (56px) + +```xml + + + Service name + Short description + +``` + +#### Connector (no label) + +```xml + +``` + +#### Container (dashed or solid) + +```xml + + + Container label + Subtitle info + +``` + +--- + +## SVG Boilerplate + +Every diagram MUST start with this exact structure: + +```xml + + + + + + + + + + +``` + +Replace `{HEIGHT}` with the actual computed height (last element bottom + 40px). + +--- + +## Diagram Types + +### 1. Flowchart +For: CI/CD pipelines, request lifecycles, approval workflows, data processing. +Layout: Single-direction flow (top-down or left-right). Max 4-5 nodes per row. + +### 2. Structural / Containment +For: Cloud infrastructure (VPC/subnet/instance), system architecture with nesting. +Layout: Large outer containers with inner regions. Dashed rects for logical groupings. + +### 3. API / Endpoint Map +For: REST API routes, GraphQL schema overview, service endpoint inventory. +Layout: Tree from root, branching to resource groups, each containing endpoint nodes. + +### 4. Microservice Topology +For: Service mesh, inter-service communication, event-driven systems. +Layout: Services as nodes, arrows showing communication patterns, message queues between. + +### 5. Data Flow +For: ETL pipelines, streaming architectures, data lake layouts. +Layout: Left-to-right flow from sources through processing to sinks. + +### 6. Physical / Structural +For: Physical objects, vehicles, buildings, hardware, mechanical systems, anatomical diagrams. +Layout: Use shapes that match the physical form — not just rectangles. + +**Go beyond boxes** — when diagramming physical objects, use appropriate SVG elements: + +| Physical form | SVG element | Example use | +|---------------|-------------|-------------| +| Curved bodies | `` with Q/C curves | Fuselage, tanks, pipes | +| Tapered/angular shapes | `` | Wings, fins, wedges | +| Cylindrical/round | ``, `` | Engines, wheels, buttons | +| Linear structures | `` | Struts, beams, connections | +| Internal sections | `` 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 + +**CSS classes for physical diagrams:** +Define semantic classes per component type instead of using `c-*` color classes: +```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; } +``` + +### 7. Infrastructure / Systems Integration +For: Smart cities, IoT networks, industrial systems, multi-domain architectures. +Layout: Hub-spoke with central platform connecting multiple subsystems. + +**Key patterns:** +- **Central hub**: Hexagon or circle representing integration platform +- **Radiating connections**: Data lines from hub to each subsystem with connection dots +- **Subsystem sections**: Each system (power, water, transport, etc.) in its own region +- **Dashboard on top**: Optional UI mockup showing unified view + +**Hub-spoke layout:** +```xml + + + + + + +``` + +**Semantic line styles for different systems:** +```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; } +``` + +### 8. UI / Dashboard Mockups +For: Admin panels, monitoring dashboards, control interfaces, status displays. +Layout: Screen frame with nested chart/gauge/indicator elements. + +**Dashboard structure:** +```xml + + + + + + + + + + +78% + + + +``` + +**Dashboard 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; } +``` + +--- + +## Infrastructure Component Library + +Reusable shapes for infrastructure diagrams: + +### Power Systems + +**Solar panel (angled):** +```xml + + +``` + +**Wind turbine:** +```xml + + + + + +``` + +**Battery with charge level:** +```xml + + + +``` + +**Power pylon:** +```xml + + + +``` + +### Water Systems + +**Reservoir/dam:** +```xml + + + + +``` + +**Treatment tank:** +```xml + + + + +``` + +**Pipe with joint and valve:** +```xml + + + +``` + +### Transport Systems + +**Road with lane markings:** +```xml + + +``` + +**Traffic light:** +```xml + + + + +``` + +**Bus:** +```xml + + + + +``` + +### Infrastructure CSS + +```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; } +``` + +--- + +## Validation Checklist + +Before finalizing any SVG, verify ALL of the following: + +1. Every `` has class `t`, `ts`, or `th`. +2. Every `` inside a box has `dominant-baseline="central"`. +3. Every connector `` or `` 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 `` or shape elements, never on `` connectors. +10. Arrow `` block is present. +11. No gradients, shadows, blur, or glow effects. +12. Stroke width is 0.5px on all node borders. + +--- + +## Examples + +Below are complete architecture diagram examples. Use these as templates. + +### Example 1: Data pipeline (ETL flow) + +```xml + + + + + + + + + Clients + Gateway + Services + Data + + + + + React SPA + Next.js frontend + + + + Mobile app + React Native + + + + CLI + Node.js + + + + + + + + + + + API gateway + Auth, rate limiting, routing + + + + + + + + + + + User service + Auth, profiles + + + + Order service + Cart, checkout + + + + Notification svc + Email, push, SMS + + + + + + + + + + + + PostgreSQL + Users, orders, products + + + + Redis + Sessions, queue + + +``` + +### Example 2: ML inference pipeline + +```xml + + + + + + + + + + + Client request + REST / gRPC + + + + + + + Preprocessor + Tokenize, embed + + + + + + + Model server + + + + GPU inference + vLLM / TensorRT + + + + Model registry + MLflow versioning + + + + A/B router + + + + + + + Response + metrics + + + + + + Redis cache + Prompt cache + + + cache hit + + + + + Prometheus + Latency, errors + + + +``` + +### Example 3: Commercial aircraft structure (physical/structural) + +```xml + + + + + + + + + + + + + + + + + First + + + + Business + + + + Economy + + + + Cargo hold below deck + + + + + + + Fuel + + + + Flaps + + + + + + + Engine + + + + + Vertical + stabilizer + + + + Rudder + + + + Horizontal stabilizer + + + + Elevator + + + + + + Nose gear + + + + + + + Main gear + + + + + Cockpit + + + + Wing structure + Spars, ribs, skin + + + + Fuselage + Pressure vessel + + +``` + +**Aircraft CSS classes (add to hosting page):** + +```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; } + +/* 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 for physical diagrams:** + +| Physical form | SVG element | Example | +|---------------|-------------|--------| +| Curved body | `` with Q/C curves | Fuselage, nose cone | +| Tapered/angular | `` | Wings, stabilizers | +| Cylindrical | `` | Engines, wheels | +| Linear structure | `` | Struts, pylons, gear legs | +| Internal sections | `` inside parent | Cabin classes | +| Dashed boundaries | `stroke-dasharray` | Fuel tanks, control surfaces | + +### Example 4: SN2 reaction mechanism (chemistry) + +**Chemistry CSS classes (add to hosting page):** + +```css +/* Atom colors */ +.carbon { fill: #2C2C2A; } +.hydrogen { fill: #F1EFE8; stroke: #888780; stroke-width: 1; } +.oxygen { fill: #E24B4A; } +.bromine { fill: #993C1D; } +.nitrogen { fill: #378ADD; } + +/* Bond types */ +.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; } + +/* Electron movement arrows */ +.arrow-curved { stroke: #534AB7; stroke-width: 2; fill: none; } +.arrow-fill { fill: #534AB7; } + +/* Transition state brackets */ +.ts-bracket { stroke: var(--text-primary); stroke-width: 1.5; fill: none; } + +/* Energy profile */ +.energy-curve { stroke: #534AB7; stroke-width: 2.5; fill: none; } +.energy-fill { fill: rgba(83, 74, 183, 0.1); } +.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; } + +/* Chemistry text */ +.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); } +.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; } +``` + +**Molecular structure building blocks:** + +```xml + + +C + + +O + + +H + + +Br +``` + +**Bond types:** + +```xml + + + + + + + + + + + +``` + +**Lone pairs and charges:** + +```xml + + + + + +⊖ + + +δ⁻ +δ⁺ +``` + +**Curved arrow (electron movement):** + +```xml + + + + + + + + +``` + +**Transition state brackets:** + +```xml + + + + + + + +‡ +``` + +**Energy profile diagram (goes below the mechanism):** + +```xml + + +Potential Energy + +Reaction Coordinate + + + + + + + + + +Reactants + + + + +Transition State [‡] + + + + + + +Ea +``` + +**Chemistry 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 for chemistry diagrams:** + +- **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 + +### Example 5: ML benchmark grouped bar chart with dual axis + +```xml + + + + + + + + + + + + + + + + + + + + + + + + + 16 + 12 + 8 + 4 + 0 + Tokens per second + + + + + + + + 64 + 48 + 32 + 16 + 0 + VRAM usage (GB) + + + + RTX 4090 — 24 GB VRAM limit + Exceeds VRAM — offload to CPU + Fits in VRAM — full GPU speed + + + + + + + + + + + + + + + + 0.5–2 tok/s + OOM / unusable + 3–5 tok/s + Partial offload + 8–12 tok/s + Fits in VRAM + 12–15 tok/s + Full GPU speed + ▼ Best balance + + + FP16 + ~62 GB + Q8_0 + ~32 GB + Q4_K_M + ~16.8 GB + IQ3_M + ~12 GB + + + + + + + + + + + + 62 GB + 32 GB + 16.8 GB + 12 GB + + + + Min speed + + Max speed + + + VRAM usage + + 24 GB limit + + + + Quantization + Model size + Speed (tok/s) + MMLU Pro + + FP16 + 62.0 GB + ~1 (OOM) + 75.2 + + Q8_0 + 32.0 GB + 3–5 + 75.0 + + Q4_K_M + 16.8 GB + 8–12 + 73.1 + + IQ3_M + 12.0 GB + 12–15 + 70.5 + MMLU Pro = Massive Multitask Language Understanding (Professional). Higher is better. + +``` + +**Chart CSS classes (add to hosting page):** + +```css +/* Grid and axes */ +.grid { stroke: var(--border); stroke-width: 0.5; stroke-dasharray: 4 3; fill: none; } +.axis { stroke: var(--text-secondary); stroke-width: 1; fill: none; } +.axis-tick { stroke: var(--text-secondary); stroke-width: 0.75; } + +/* Bar fills per category — 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 bars */ +@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; } +} + +/* VRAM overlay */ +.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 line */ +.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; } + +/* Inset table */ +.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; } +``` + +**Chart layout formula:** + +- **Chart area**: x=90–590, y=70–410 (500px wide, 340px tall) +- **Left Y-axis**: Primary metric (tok/s). Scale: `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. Each group gets min bar + gap + max bar +- **Bars**: `rx="3"` for rounded tops, width ~34px each +- **VRAM line**: `` connecting data points across group centers +- **Threshold**: Horizontal dashed line at the critical value (e.g., 24 GB GPU limit) +- **Inset table**: Below the chart, alternating row fills (`.tbl-alt` / `.tbl-row`) +- **Semantic bar colors**: Each category gets its own color pair (lighter=min, darker=max) using the skill color palette + +--- + +## Hosting Diagrams + +After generating an SVG diagram, host it as an interactive web page. Each diagram gets its own directory for easy organization and browsing. + +### Directory Structure + +Use this structure to support multiple diagrams: + +``` +.diagrams/ +├── hospital-emergency-flow/ +│ └── index.html +├── smart-city-infrastructure/ +│ └── index.html +├── electricity-grid-flow/ +│ └── index.html +├── banana-journey/ +│ └── index.html +└── smartphone-layers/ + └── index.html +``` + +### Step 1: Create the diagram directory + +Create a directory for each diagram using kebab-case naming: + +```bash +mkdir -p .diagrams/ +``` + +**Naming conventions:** +- Use lowercase kebab-case: `smart-city-infrastructure`, `electricity-grid-flow` +- Be descriptive but concise: `user-auth-flow` not `diagram-1` +- Include the diagram type if helpful: `banana-journey`, `smartphone-layers` + +### Step 2: Create the HTML page + +Create `.diagrams//index.html` with the following template. This page includes the full CSS design system that makes the `c-*` classes, text classes, and dark mode work. + +```html + + + + + +Architecture Diagram + + + +
+

+

+ +
+ + +``` + +### Step 3: Start the HTTP server + +Start the server at the `.diagrams/` root directory. This serves all diagram directories and provides a browsable listing: + +```bash +cd .diagrams && python3 -m http.server 22223 --bind 0.0.0.0 & +``` + +**Important:** Start the server at `.diagrams/`, NOT inside a specific diagram folder. This way: +- `http://0.0.0.0:22223/` shows a directory listing of all diagrams +- `http://0.0.0.0:22223/smart-city-infrastructure/` opens that specific diagram +- Users can browse and switch between diagrams easily + +### Step 4: Confirm + +Print a message to the user: + +``` +Diagram hosted at http://0.0.0.0:22223// +Browse all diagrams at http://0.0.0.0:22223/ +``` + +### Complete Workflow + +Here is the complete workflow for creating a new diagram: + +```bash +# 1. Create diagram directory (use descriptive kebab-case name) +mkdir -p .diagrams/smart-city-infrastructure + +# 2. Create the HTML file with embedded SVG +cat > .diagrams/smart-city-infrastructure/index.html << 'EOF' + + + + Smart City Infrastructure + + + +
+

Smart City Infrastructure

+

Description here

+ +
+ + +EOF + +# 3. Start server (only needed once, serves all diagrams) +cd .diagrams && python3 -m http.server 22223 --bind 0.0.0.0 & + +# 4. Confirm +echo "Diagram: http://0.0.0.0:22223/smart-city-infrastructure/" +echo "All diagrams: http://0.0.0.0:22223/" +``` + +### Adding More Diagrams + +To add another diagram, simply create a new directory: + +```bash +mkdir -p .diagrams/electricity-grid-flow +# Create .diagrams/electricity-grid-flow/index.html +``` + +The server (if already running) will automatically serve the new diagram. No restart needed. + +### Browsing Diagrams + +When you navigate to `http://0.0.0.0:22223/`, Python's HTTP server shows a directory listing: + +``` +Directory listing for / + +• banana-journey/ +• electricity-grid-flow/ +• hospital-emergency-flow/ +• smart-city-infrastructure/ +• smartphone-layers/ +``` + +Click any folder to view that diagram. + +--- + +## Quick Reference: What to Use When + +| User says | Diagram type | Color scheme | +|-----------|-------------|--------------| +| "show the architecture" | Structural (containment) | purple container, teal services, coral data | +| "draw the pipeline" | Flowchart (left-right or top-down) | gray start/end, purple steps, red errors, teal deploy | +| "map the endpoints" | API endpoint map (tree) | purple root, one ramp per resource group | +| "show the services" | Microservice topology | gray ingress, teal services, purple bus, coral workers | +| "visualize the data flow" | Data pipeline (left-right) | gray sources, purple processing, teal sinks | +| "draw the infrastructure" | Structural (VPC/subnet nesting) | purple VPC, teal public, coral private | +| "show the ML pipeline" | Flowchart + structural hybrid | gray input, purple preprocessing, teal model server, coral output | +| "draw the aircraft/vehicle" | Physical / Structural | Use paths, polygons, ellipses for realistic shapes | +| "smart city/IoT system" | Infrastructure / Systems Integration | Hub-spoke layout, semantic line styles per system | +| "show the dashboard" | UI / Dashboard Mockup | Dark screen, chart colors: teal, purple, coral for alerts | +| "power grid/electricity flow" | Multi-stage Flow | Left-to-right stages, voltage hierarchy (HV/MV/LV line weights) | +| "wind turbine" / "turbine structure" | Physical Cross-section | Underground foundation, tower cutaway, nacelle components color-coded | +| "journey of X" / "lifecycle" | Narrative Journey | Winding path, progressive state changes, timeline | +| "layers of X" / "exploded view" | Exploded Layer View | Vertical stack, alternating labels, component detail | +| "CPU microarchitecture" / "pipeline" | Hardware Pipeline | Vertical stages, fan-out to execution ports, sidebar for memory | +| "floor plan" / "apartment layout" | Architectural Floor Plan | Walls, doors, windows, room fills, proposed changes in dotted red | +| "reaction mechanism" / "chemistry" | Chemistry Mechanism | Atoms, bonds, curved arrows, transition state brackets, energy profile | + +--- + +## Examples Reference + +See the `examples/` directory for complete, tested diagram templates: + +### hospital-emergency-department-flow.md +Multi-path flowchart with priority-based routing using semantic colors (red=critical, amber=urgent, green=stable). Demonstrates convergent/divergent flows, stage labels, and color-coded legends. + +### feature-film-production-pipeline.md +Phased workflow with neutral dashed containers and colored inner nodes. Shows horizontal sub-flows within a phase (post-production pipeline) and the pattern of containers receding while content pops. + +### commercial-aircraft-structure.md +Physical/structural diagram using paths, polygons, and ellipses to draw realistic shapes. Demonstrates going beyond rectangles for physical objects, layered composition, and leader lines with labels. + +### smart-city-infrastructure.md +Multi-system integration diagram with hub-spoke layout. Central IoT platform connects power grid (solar, wind, battery), water system (reservoir, treatment, pipes), and transport (roads, signals, buses). Includes dashboard UI mockup and demonstrates semantic line styles for different infrastructure types. + +### electricity-grid-flow.md +Left-to-right multi-stage flow showing electricity from generation (nuclear, solar, wind, gas) through transmission (pylons, substations) to distribution (pole transformers) and consumption (homes, factories, EV chargers). Demonstrates voltage level visual hierarchy, smart grid data overlay, and flow arrow markers. + +### wind-turbine-structure.md +Physical cross-section of a modern onshore wind turbine from underground foundation to blade tips. Shows deep concrete foundation with rebar grid, tapered tubular steel tower with internal ladder and elevator, nacelle cutaway with gearbox (gold), generator (blue), brake (red), and yaw system (green), rotor hub with pitch motors (purple) at blade roots, and power cables running to transformer at base. Demonstrates underground/above-ground separation, component color coding with legend, cross-section layering, and mechanical system visualization. + +### banana-journey-tree-to-smoothie.md +Narrative journey diagram following a banana from Costa Rica harvest through shipping, inspection, ripening, retail, and finally the consumer's kitchen (overripe → frozen → smoothie). Demonstrates storytelling visualization, winding path layout, progressive state changes (green → yellow → brown), and fun narrative details like spider inspection and price tags. + +### smartphone-layer-anatomy.md +Exploded view showing 7 internal layers of a smartphone from front glass to back. Features alternating left/right labels to prevent overlap, detailed component rendering (PCB with chips, camera lenses, wireless coil), and thickness scale. Demonstrates product teardown visualization. + +### cpu-ooo-microarchitecture.md +Out-of-order CPU core microarchitecture showing full superscalar pipeline: Fetch → Decode (with µop cache bypass) → Rename/Allocate (RAT, Physical RF) → Unified Scheduler → 6 Execution Ports (ALU, Branch, Load, Store, Vector) → Reorder Buffer. Memory hierarchy sidebar shows L1-I, L1-D, L2, and DRAM. Demonstrates fan-out patterns, path merging, container grouping, and hardware pipeline visualization. + +### apartment-floor-plan-conversion.md +Architectural floor plan showing 3 BHK to 4 BHK apartment conversion. Features room color coding, door swings, window symbols, proposed walls in dotted red, circulation arrows for new access paths, and area comparison table. Demonstrates architectural drawing conventions, overlay technique for renovation proposals, and quantitative data integration with floor plans. + +### sn2-reaction-mechanism.md +Organic chemistry SN2 reaction mechanism (OH⁻ + CH₃Br → CH₃OH + Br⁻). Shows ball-and-stick molecular structures, curved electron-pushing arrows, pentacoordinate transition state with partial charges (δ⁺/δ⁻), wedge/dash stereochemistry, and Walden inversion. Includes reaction energy profile with activation energy and exergonic product formation. Demonstrates chemistry notation, molecular rendering, and energy diagrams. + +### autonomous-llm-research-agent-flow.md +Multi-section flowchart of Karpathy's autoresearch framework: human-agent handoff, autonomous experiment loop with keep/discard decision branching, and modifiable training pipeline. Demonstrates loop-back arrows with rounded corners for infinite repetition, convergent decision paths (green=keep, red=discard), semantic color coding for outcomes, highlighted key steps using contrasting color (coral "Run training" among teal action steps), neutral dashed containers, horizontal sub-flows within a detail section, and footer metadata for fixed constraints. + +### ml-benchmark-grouped-bar-chart.md +Grouped bar chart comparing LLM inference speed across quantization levels (FP16, Q8_0, Q4_K_M, IQ3_M) with min/max range bars per category. Features dual Y-axis (tok/s left, VRAM GB right), VRAM usage overlay as a polyline with labeled dots, dashed red threshold line for GPU VRAM limit, semantic color coding per quantization level, zone annotations (exceeds/fits VRAM), inset data table with MMLU Pro accuracy scores and delta from baseline, and full dark mode support. Demonstrates quantitative data visualization, grouped bar layout, secondary axis line graph, threshold markers, and tabular data integration. \ No newline at end of file diff --git a/optional-skills/creative/architecture-visualization-svg-diagrams/examples/apartment-floor-plan-conversion.md b/optional-skills/creative/architecture-visualization-svg-diagrams/examples/apartment-floor-plan-conversion.md new file mode 100644 index 0000000000..7c11d3401e --- /dev/null +++ b/optional-skills/creative/architecture-visualization-svg-diagrams/examples/apartment-floor-plan-conversion.md @@ -0,0 +1,244 @@ +# 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 + + + + + + + + +``` + +```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 + + + + + + + + + + + + + +``` + +```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 + + + + + + + +``` + +```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 + + + + + + + + + +``` + +```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 + + +Counter + + + +``` + +```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 + +MASTER +BEDROOM +195 sq ft + + +BEDROOM 4 +(NEW) +``` + +```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 + + + + + + + +New corridor access +``` + +```css +.circulation { stroke: #3B6D11; stroke-width: 2; fill: none; } +.circulation-fill { fill: #3B6D11; } +``` + +### North Arrow and Scale Bar + +```xml + + + + + N + + + + + + + + + 0 + 5' + 10' + +``` + +## Area Comparison Table + +### Table Structure + +```xml + + +Room + + + +Master Bedroom +195 + + + + + + +Bedroom 4 (NEW) ++100 + + + +TOTAL CARPET AREA +``` + +```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 diff --git a/optional-skills/creative/architecture-visualization-svg-diagrams/examples/automated-password-reset-flow.md b/optional-skills/creative/architecture-visualization-svg-diagrams/examples/automated-password-reset-flow.md new file mode 100644 index 0000000000..86cd1cc078 --- /dev/null +++ b/optional-skills/creative/architecture-visualization-svg-diagrams/examples/automated-password-reset-flow.md @@ -0,0 +1,276 @@ +# 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 ``**: Each decision uses a `` wrapper containing a `` and centered ``; 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 `` 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 ``) and a "No" branch (`` 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 `` 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 + + + + + + + + + + + Section 1 — Forgot password request + + + + + User: "Forgot password" + + + + + + + + Enter email address + + + + + + + + Email in system? + + + + + No + + + + Yes + + + + + + + Generic message shown + Email sent if found + + + + + + + + Request handled + + + + "If that email exists, a reset + link has been sent." + + + + + + + Generate unique token + Time-limited, cryptographic + + + + + + + + Store token + user ID + + + + + + + + Send reset link via email + + + + + + + + user receives email + + Section 2 — Password reset form + + + + + + + User clicks reset link + + + + + + + + Enter new password ×2 + Confirm both passwords match + + + + + + + + Token expired? + + + + + Yes + + + + No + + + + + + + Token expired + Show expiry error + + + + + + + + End — request again + + + + + + Passwords match? + + + + + No + + + + Yes + + + + + + + Password mismatch + Passwords do not match + + + + + retry + + + + + + + Reset password + Invalidate used token + + + + + + + + Password reset complete + + + + Legend — + + User action + + System process + + Email / success + + Error state + + Decision + + +``` + +## Custom CSS + +Add these classes to the hosting page `