fix: architecture diagram unreadable in dark mode (#3752)

bartlomieju · claude · web-flow · commit 895bcacdae4b · 2026-04-07T11:08:11.000+02:00
## Summary
- The inline HTML/CSS flow diagram in `docs/concepts/architecture` was
broken — marked's smartypants text transforms corrupted the `&lt;style&gt;`
block, stripping all styling
- Replaced with a standalone SVG
(`www/static/docs/architecture-flow-v2.svg`) using theme-neutral
mid-gray colors that are readable on both light and dark backgrounds

Co-authored-by: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/docs/latest/concepts/architecture.md b/docs/latest/concepts/architecture.md
@@ -9,91 +9,7 @@ browser. This page explains how a request flows through the framework.
 
 ## Request lifecycle
 
-<div style="max-width:620px;font-family:system-ui,-apple-system,sans-serif;font-size:14px;color:#1a1a1a;">
-  <style>
-    .flow-step{display:flex;align-items:flex-start;gap:16px}
-    .flow-box{flex-shrink:0;width:200px;padding:10px 14px;border:1.5px solid #333;border-radius:6px;background:#f8f9fa;text-align:center}
-    .flow-box strong{display:block;font-size:14px}
-    .flow-box small{font-size:11px;color:#777}
-    .flow-box.accent{background:#eef6ff}
-    .flow-box.green{background:#f0faf0}
-    .flow-desc{padding-top:10px;font-size:12.5px;color:#555;line-height:1.5}
-    .flow-arrow{text-align:center;width:200px;color:#666;font-size:18px;line-height:1;padding:4px 0}
-    .flow-arrow-label{text-align:center;width:200px;padding:2px 0}
-    .flow-arrow-label em{font-size:11px;color:#777}
-    .flow-divider{margin:12px 0 8px;padding-top:8px;border-top:1px dashed #e0e0e0;font-size:11px;color:#999;font-weight:600;letter-spacing:0.5px;text-transform:uppercase}
-  </style>
-  <!-- Browser Request -->
-  <div class="flow-step">
-    <div class="flow-box accent"><strong>Browser Request</strong></div>
-  </div>
-  <div class="flow-arrow">&#x2193;</div>
-  <!-- Static Files -->
-  <div class="flow-step">
-    <div class="flow-box"><strong>Static Files</strong></div>
-    <div class="flow-desc">Serve file directly if path matches a static asset</div>
-  </div>
-  <div class="flow-arrow-label"><em>no match</em></div>
-  <div class="flow-arrow">&#x2193;</div>
-  <!-- Global Middleware -->
-  <div class="flow-step">
-    <div class="flow-box"><strong>Global Middleware</strong><small>runs in registration order</small></div>
-    <div class="flow-desc">Can modify request/response, set state, or short&#8209;circuit with a Response</div>
-  </div>
-  <div class="flow-arrow">&#x2193;</div>
-  <!-- Router -->
-  <div class="flow-step">
-    <div class="flow-box"><strong>Router</strong></div>
-    <div class="flow-desc">Match URL pattern + HTTP method. Static routes checked first, then dynamic.</div>
-  </div>
-  <div class="flow-arrow">&#x2193;</div>
-  <!-- Scoped Middleware -->
-  <div class="flow-step">
-    <div class="flow-box"><strong>Scoped Middleware</strong></div>
-    <div class="flow-desc">Middleware that only runs for matching path prefixes (e.g. /admin/*). Used for auth, logging, or other route&#8209;specific logic.</div>
-  </div>
-  <div class="flow-arrow">&#x2193;</div>
-  <!-- Handler -->
-  <div class="flow-step">
-    <div class="flow-box"><strong>Handler</strong></div>
-    <div class="flow-desc">API route? Return Response directly (JSON, redirect, etc.)</div>
-  </div>
-  <div class="flow-arrow-label"><em>has component</em></div>
-  <div class="flow-arrow">&#x2193;</div>
-  <!-- Rendering section -->
-  <div class="flow-divider">Rendering</div>
-  <!-- App Wrapper -->
-  <div class="flow-step">
-    <div class="flow-box"><strong>App Wrapper</strong></div>
-    <div class="flow-desc">Outer &lt;html&gt;/&lt;head&gt;/&lt;body&gt; structure</div>
-  </div>
-  <div class="flow-arrow">&#x2193;</div>
-  <!-- Layouts -->
-  <div class="flow-step">
-    <div class="flow-box"><strong>Layouts</strong></div>
-    <div class="flow-desc">Nested layout components (inherited from parent directories)</div>
-  </div>
-  <div class="flow-arrow">&#x2193;</div>
-  <!-- Page Component -->
-  <div class="flow-step">
-    <div class="flow-box"><strong>Page Component</strong></div>
-    <div class="flow-desc">Route component receives props.data from handler</div>
-  </div>
-  <div class="flow-arrow">&#x2193;</div>
-  <!-- HTML Response -->
-  <div class="flow-step">
-    <div class="flow-box accent"><strong>HTML + JS Response</strong><small>sent to browser</small></div>
-    <div class="flow-desc">Server&#8209;rendered HTML with island props <a href="/docs/advanced/serialization">serialized</a> inline</div>
-  </div>
-  <!-- Client section -->
-  <div class="flow-divider">Client (Browser)</div>
-  <div class="flow-arrow">&#x2193;</div>
-  <!-- Hydration -->
-  <div class="flow-step">
-    <div class="flow-box green"><strong>Island Hydration</strong><small>only islands receive JS</small></div>
-    <div class="flow-desc">Rest of the page stays static HTML. No JavaScript for non&#8209;island components.</div>
-  </div>
-</div>
+![Request lifecycle flow diagram](/docs/architecture-flow-v2.svg)
 
 ## Key concepts
 
diff --git a/www/static/docs/architecture-flow-v2.svg b/www/static/docs/architecture-flow-v2.svg
@@ -0,0 +1,108 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 620 1020" font-family="system-ui,-apple-system,sans-serif" font-size="14">
+  <style>
+    .box{fill:none;stroke:#999;stroke-width:1}
+    .box-accent{fill:none;stroke:#7a9fbf;stroke-width:1}
+    .box-green{fill:none;stroke:#7aaa7a;stroke-width:1}
+    .label{font-weight:600;font-size:14px;fill:#999}
+    .sublabel{font-size:11px;fill:#999}
+    .desc{font-size:12.5px;fill:#999}
+    .arrow{fill:#999;font-size:18px}
+    .arrow-label{font-size:11px;fill:#999;font-style:italic}
+    .divider-line{stroke:#999;stroke-dasharray:4 3}
+    .divider-text{font-size:11px;fill:#999;font-weight:600;letter-spacing:0.5px;text-transform:uppercase}
+    .link{fill:#6ca6d4}
+  </style>
+
+  <!-- Browser Request -->
+  <rect class="box-accent" x="0" y="0" width="200" height="40" rx="6"/>
+  <text class="label" x="100" y="25" text-anchor="middle">Browser Request</text>
+
+  <text class="arrow" x="100" y="58" text-anchor="middle">&#x2193;</text>
+
+  <!-- Static Files -->
+  <rect class="box" x="0" y="68" width="200" height="40" rx="6"/>
+  <text class="label" x="100" y="93" text-anchor="middle">Static Files</text>
+  <text class="desc" x="224" y="93">Serve file directly if path matches a static asset</text>
+
+  <text class="arrow-label" x="100" y="123" text-anchor="middle">no match</text>
+  <text class="arrow" x="100" y="142" text-anchor="middle">&#x2193;</text>
+
+  <!-- Global Middleware -->
+  <rect class="box" x="0" y="152" width="200" height="50" rx="6"/>
+  <text class="label" x="100" y="173" text-anchor="middle">Global Middleware</text>
+  <text class="sublabel" x="100" y="190" text-anchor="middle">runs in registration order</text>
+  <text class="desc" x="224" y="173">Can modify request/response, set state,</text>
+  <text class="desc" x="224" y="190">or short-circuit with a Response</text>
+
+  <text class="arrow" x="100" y="222" text-anchor="middle">&#x2193;</text>
+
+  <!-- Router -->
+  <rect class="box" x="0" y="232" width="200" height="40" rx="6"/>
+  <text class="label" x="100" y="257" text-anchor="middle">Router</text>
+  <text class="desc" x="224" y="250">Match URL pattern + HTTP method.</text>
+  <text class="desc" x="224" y="267">Static routes checked first, then dynamic.</text>
+
+  <text class="arrow" x="100" y="292" text-anchor="middle">&#x2193;</text>
+
+  <!-- Scoped Middleware -->
+  <rect class="box" x="0" y="302" width="200" height="40" rx="6"/>
+  <text class="label" x="100" y="327" text-anchor="middle">Scoped Middleware</text>
+  <text class="desc" x="224" y="316">Middleware that only runs for matching path</text>
+  <text class="desc" x="224" y="333">prefixes (e.g. /admin/*). Used for auth, logging,</text>
+  <text class="desc" x="224" y="350">or other route-specific logic.</text>
+
+  <text class="arrow" x="100" y="372" text-anchor="middle">&#x2193;</text>
+
+  <!-- Handler -->
+  <rect class="box" x="0" y="382" width="200" height="40" rx="6"/>
+  <text class="label" x="100" y="407" text-anchor="middle">Handler</text>
+  <text class="desc" x="224" y="407">API route? Return Response directly (JSON, redirect, etc.)</text>
+
+  <text class="arrow-label" x="100" y="437" text-anchor="middle">has component</text>
+  <text class="arrow" x="100" y="456" text-anchor="middle">&#x2193;</text>
+
+  <!-- Rendering divider -->
+  <line class="divider-line" x1="0" y1="470" x2="600" y2="470"/>
+  <text class="divider-text" x="0" y="488">RENDERING</text>
+
+  <!-- App Wrapper -->
+  <rect class="box" x="0" y="498" width="200" height="40" rx="6"/>
+  <text class="label" x="100" y="523" text-anchor="middle">App Wrapper</text>
+  <text class="desc" x="224" y="523">&lt;html&gt;/&lt;head&gt;/&lt;body&gt; structure</text>
+
+  <text class="arrow" x="100" y="558" text-anchor="middle">&#x2193;</text>
+
+  <!-- Layouts -->
+  <rect class="box" x="0" y="568" width="200" height="40" rx="6"/>
+  <text class="label" x="100" y="593" text-anchor="middle">Layouts</text>
+  <text class="desc" x="224" y="593">Nested layout components (inherited from parent directories)</text>
+
+  <text class="arrow" x="100" y="628" text-anchor="middle">&#x2193;</text>
+
+  <!-- Page Component -->
+  <rect class="box" x="0" y="638" width="200" height="40" rx="6"/>
+  <text class="label" x="100" y="663" text-anchor="middle">Page Component</text>
+  <text class="desc" x="224" y="663">Route component receives props.data from handler</text>
+
+  <text class="arrow" x="100" y="698" text-anchor="middle">&#x2193;</text>
+
+  <!-- HTML + JS Response -->
+  <rect class="box-accent" x="0" y="708" width="200" height="50" rx="6"/>
+  <text class="label" x="100" y="729" text-anchor="middle">HTML + JS Response</text>
+  <text class="sublabel" x="100" y="746" text-anchor="middle">sent to browser</text>
+  <text class="desc" x="224" y="733">Server-rendered HTML with island props</text>
+  <text class="desc" x="224" y="750">serialized inline</text>
+
+  <!-- Client divider -->
+  <line class="divider-line" x1="0" y1="778" x2="600" y2="778"/>
+  <text class="divider-text" x="0" y="796">CLIENT (BROWSER)</text>
+
+  <text class="arrow" x="100" y="820" text-anchor="middle">&#x2193;</text>
+
+  <!-- Island Hydration -->
+  <rect class="box-green" x="0" y="830" width="200" height="50" rx="6"/>
+  <text class="label" x="100" y="851" text-anchor="middle">Island Hydration</text>
+  <text class="sublabel" x="100" y="868" text-anchor="middle">only islands receive JS</text>
+  <text class="desc" x="224" y="851">Rest of the page stays static HTML.</text>
+  <text class="desc" x="224" y="868">No JavaScript for non-island components.</text>
+</svg>
