@kinqs/brainrouter-mcp-server 0.3.4

package/skills/design/concept-diagrams/examples/wind-turbine-structure.md

@@ -0,0 +1,338 @@
+# 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; }
+```

package/skills/design/concept-diagrams/references/dashboard-patterns.md

@@ -0,0 +1,43 @@
+# 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`).

package/skills/design/concept-diagrams/references/infrastructure-patterns.md

@@ -0,0 +1,144 @@
+# 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

package/skills/design/concept-diagrams/references/physical-shape-cookbook.md

@@ -0,0 +1,42 @@
+# 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