From 09947262a5448848a702e318ef3e4cc84d8b28ab Mon Sep 17 00:00:00 2001
From: giles <giles.bradshaw@rose-ash.com>
Date: Sun, 8 Mar 2026 00:15:39 +0000
Subject: [PATCH] Add CSSX as top-level docs section with patterns, async, and
 live examples

New top-level section in sx-docs: /cssx/ with 6 pages:
- Overview: the idea, what changed, advantages
- Patterns: class mapping, data-driven, style functions, responsive, emitting CSS
- Async CSS: components that fetch/cache CSS before rendering via ~suspense
- Live Styles: SSE/WS examples for real-time style updates (noted as future)
- Comparisons: vs styled-components, CSS Modules, Tailwind, Vanilla Extract
- Philosophy: proof by deletion, the right abstraction level

Also:
- Remove CSSX from specs nav (spec file deleted)
- Fix renderer spec prose (no longer mentions StyleValue)
- Update On-Demand CSS essay summary
- Mark CSSX Components plan as done

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 sx/sx/cssx.sx        | 354 +++++++++++++++++++++++++++++++++++++++++++
 sx/sx/layouts.sx     |   1 +
 sx/sx/nav-data.sx    |  15 +-
 sx/sxc/pages/docs.sx |  33 ++++
 4 files changed, 399 insertions(+), 4 deletions(-)
 create mode 100644 sx/sx/cssx.sx

diff --git a/sx/sx/cssx.sx b/sx/sx/cssx.sx
new file mode 100644
index 0000000..20e2d1b
--- /dev/null
+++ b/sx/sx/cssx.sx
@@ -0,0 +1,354 @@
+;; CSSX — Styling as Components
+;; Documentation for the CSSX approach: no parallel style infrastructure,
+;; just defcomp components that decide how to style their children.
+
+;; ---------------------------------------------------------------------------
+;; Overview
+;; ---------------------------------------------------------------------------
+
+(defcomp ~cssx-overview-content ()
+  (~doc-page :title "CSSX Components"
+
+    (~doc-section :title "The Idea" :id "idea"
+      (p (strong "Styling is just components.") " A CSSX component is a regular "
+         (code "defcomp") " that decides how to style its children. It might apply "
+         "Tailwind classes, or hand-written CSS classes, or inline styles, or generate "
+         "rules at runtime. The implementation is the component's private business. "
+         "The consumer just calls " (code "(~btn :variant \"primary\" \"Submit\")") " and doesn't care.")
+      (p "Because it's " (code "defcomp") ", you get everything for free: caching, bundling, "
+         "dependency scanning, server/client rendering, composition. No parallel infrastructure."))
+
+    (~doc-section :title "Why Not a Style Dictionary?" :id "why"
+      (p "SX previously had a parallel CSS system: a style dictionary (JSON blob of "
+         "atom-to-declaration mappings), a " (code "StyleValue") " type threaded through "
+         "the evaluator and renderer, content-addressed hash class names (" (code "sx-a3f2b1")
+         "), runtime CSS injection, and a separate caching pipeline (cookies, localStorage).")
+      (p "This was ~3,000 lines of code across the spec, bootstrappers, and host implementations. "
+         "It was never adopted. The codebase voted with its feet: " (code ":class") " strings "
+         "with " (code "defcomp") " already covered every real use case.")
+      (p "The result of that system: elements in the DOM got opaque class names like "
+         (code "class=\"sx-a3f2b1\"") ". DevTools became useless. You couldn't inspect an "
+         "element and understand its styling. " (strong "That was a deal breaker.")))
+
+    (~doc-section :title "Key Advantages" :id "advantages"
+      (ul :class "list-disc pl-5 space-y-2 text-stone-700"
+        (li (strong "Readable DOM: ") "Elements have real class names, not content-addressed "
+            "hashes. DevTools works.")
+        (li (strong "Data-driven styling: ") "Components receive data and decide styling. "
+            (code "(~metric :value 150)") " renders red because " (code "value > 100")
+            " — logic lives in the component, not a CSS preprocessor.")
+        (li (strong "One system: ") "No separate " (code "StyleValue") " type, no style "
+            "dictionary JSON, no injection pipeline. Components ARE the styling abstraction.")
+        (li (strong "One cache: ") "Component hash/localStorage handles everything. No "
+            "separate style dict caching.")
+        (li (strong "Composable: ") (code "(~card :elevated true (~metric :value v))")
+            " — styling composes like any other component.")
+        (li (strong "Strategy-agnostic: ") "A component can apply Tailwind classes, emit "
+            (code "<style>") " blocks, use inline styles, generate CSS custom properties, or "
+            "any combination. Swap strategies without touching call sites.")))
+
+    (~doc-section :title "What Changed" :id "changes"
+      (~doc-subsection :title "Removed (~3,000 lines)"
+        (ul :class "list-disc pl-5 space-y-1 text-stone-600 text-sm"
+          (li (code "StyleValue") " type and all plumbing (type checks in eval, render, serialize)")
+          (li (code "cssx.sx") " spec module (resolve-style, resolve-atom, split-variant, hash, injection)")
+          (li "Style dictionary JSON format, loading, caching (" (code "<script type=\"text/sx-styles\">") ", localStorage)")
+          (li (code "style_dict.py") " (782 lines) and " (code "style_resolver.py") " (254 lines)")
+          (li (code "css") " and " (code "merge-styles") " primitives")
+          (li "Platform interface: " (code "fnv1a-hash") ", " (code "compile-regex") ", " (code "make-style-value") ", " (code "inject-style-value"))
+          (li (code "defkeyframes") " special form")
+          (li "Style dict cookies and localStorage keys")))
+
+      (~doc-subsection :title "Kept"
+        (ul :class "list-disc pl-5 space-y-1 text-stone-600 text-sm"
+          (li (code "defstyle") " — simplified to bind any value (string, function, etc.)")
+          (li (code "tw.css") " — the compiled Tailwind stylesheet, delivered via CSS class tracking")
+          (li (code ":class") " attribute — just takes strings, no special-casing")
+          (li "CSS class delivery (" (code "SX-Css") " headers, " (code "<style id=\"sx-css\">") ")")
+          (li "All component infrastructure (defcomp, caching, bundling, deps)")))
+
+      (~doc-subsection :title "Added"
+        (p "Nothing. CSSX components are just " (code "defcomp") ". The only new thing is "
+           "a convention: components whose primary purpose is styling.")))))
+
+
+;; ---------------------------------------------------------------------------
+;; Patterns
+;; ---------------------------------------------------------------------------
+
+(defcomp ~cssx-patterns-content ()
+  (~doc-page :title "Patterns"
+
+    (~doc-section :title "Class Mapping" :id "class-mapping"
+      (p "The simplest pattern: a component that maps semantic keywords to class strings.")
+      (highlight
+        "(defcomp ~btn (&key variant disabled &rest children)\n  (button\n    :class (str \"px-4 py-2 rounded font-medium transition \"\n               (case variant\n                 \"primary\" \"bg-blue-600 text-white hover:bg-blue-700\"\n                 \"danger\"  \"bg-red-600 text-white hover:bg-red-700\"\n                 \"ghost\"   \"bg-transparent hover:bg-stone-100\"\n                 \"bg-stone-200 hover:bg-stone-300\")\n               (when disabled \" opacity-50 cursor-not-allowed\"))\n    :disabled disabled\n    children))"
+        "lisp")
+      (p "Consumers call " (code "(~btn :variant \"primary\" \"Submit\")") ". The Tailwind "
+         "classes are readable in DevTools but never repeated across call sites."))
+
+    (~doc-section :title "Data-Driven Styling" :id "data-driven"
+      (p "Styling that responds to data values — impossible with static CSS:")
+      (highlight
+        "(defcomp ~metric (&key value label threshold)\n  (let ((t (or threshold 10)))\n    (div :class (str \"p-3 rounded font-bold \"\n                 (cond\n                   ((> value (* t 10)) \"bg-red-500 text-white\")\n                   ((> value t)        \"bg-amber-200 text-amber-900\")\n                   (:else              \"bg-green-100 text-green-800\")))\n      (span :class \"text-sm\" label) \": \" (span (str value)))))"
+        "lisp")
+      (p "The component makes a " (em "decision") " about styling based on data. "
+         "No CSS preprocessor or class name convention can express \"red when value > 100\"."))
+
+    (~doc-section :title "Style Functions" :id "style-functions"
+      (p "Reusable style logic that returns class strings — no wrapping element needed:")
+      (highlight
+        "(define card-classes\n  (fn (&key elevated bordered)\n    (str \"rounded-lg p-4 \"\n         (if elevated \"shadow-lg\" \"shadow-sm\")\n         (when bordered \" border border-stone-200\"))))\n\n;; Usage:\n(div :class (card-classes :elevated true) ...)\n(article :class (card-classes :bordered true) ...)"
+        "lisp")
+      (p "Or with " (code "defstyle") " for named bindings:")
+      (highlight
+        "(defstyle card-base \"rounded-lg p-4 shadow-sm\")\n(defstyle card-elevated \"rounded-lg p-4 shadow-lg\")\n\n(div :class card-base ...)"
+        "lisp"))
+
+    (~doc-section :title "Responsive Layouts" :id "responsive"
+      (p "Components that encode responsive breakpoints:")
+      (highlight
+        "(defcomp ~responsive-grid (&key cols &rest children)\n  (div :class (str \"grid gap-4 \"\n               (case (or cols 3)\n                 1 \"grid-cols-1\"\n                 2 \"grid-cols-1 md:grid-cols-2\"\n                 3 \"grid-cols-1 md:grid-cols-2 lg:grid-cols-3\"\n                 4 \"grid-cols-2 md:grid-cols-3 lg:grid-cols-4\"))\n    children))"
+        "lisp"))
+
+    (~doc-section :title "Emitting CSS Directly" :id "emitting-css"
+      (p "Components are not limited to referencing existing classes. They can generate "
+         "CSS — " (code "<style>") " tags, keyframes, custom properties — as part of their output:")
+      (highlight
+        "(defcomp ~pulse (&key color duration &rest children)\n  (<>\n    (style (str \"@keyframes sx-pulse {\"\n               \"0%,100% { opacity:1 } 50% { opacity:.5 } }\"))\n    (div :style (str \"animation: sx-pulse \" (or duration \"2s\") \" infinite;\"\n                    \"color:\" (or color \"inherit\"))\n      children)))"
+        "lisp")
+      (highlight
+        "(defcomp ~theme (&key primary surface &rest children)\n  (<>\n    (style (str \":root {\"\n               \"--color-primary:\" (or primary \"#7c3aed\") \";\"\n               \"--color-surface:\" (or surface \"#fafaf9\") \"}\"))\n    children))"
+        "lisp")
+      (p "The CSS strategy is the component's private implementation detail. Consumers call "
+         (code "(~pulse :color \"red\" \"Loading...\")") " or "
+         (code "(~theme :primary \"#2563eb\" ...)") " without knowing or caring whether the "
+         "component uses classes, inline styles, generated rules, or all three."))))
+
+
+;; ---------------------------------------------------------------------------
+;; Async CSS
+;; ---------------------------------------------------------------------------
+
+(defcomp ~cssx-async-content ()
+  (~doc-page :title "Async CSS"
+
+    (~doc-section :title "The Pattern" :id "pattern"
+      (p "A CSSX component that needs CSS it doesn't have yet can "
+         (strong "fetch and cache it before rendering") ". This is just "
+         (code "~suspense") " combined with a style component — no new infrastructure:")
+      (highlight
+        "(defcomp ~styled (&key css-url css-hash fallback &rest children)\n  (if (css-cached? css-hash)\n    ;; Already have it — render immediately\n    children\n    ;; Don't have it — suspense while we fetch\n    (~suspense :id (str \"css-\" css-hash)\n      :fallback (or fallback (span \"\"))\n      (do\n        (fetch-css css-url css-hash)\n        children))))"
+        "lisp")
+      (p "The consumer never knows:")
+      (highlight
+        "(~styled :css-url \"/css/charts.css\" :css-hash \"abc123\"\n  (~bar-chart :data metrics))"
+        "lisp"))
+
+    (~doc-section :title "Use Cases" :id "use-cases"
+      (~doc-subsection :title "Federated Components"
+        (p "A " (code "~btn") " from another site arrives via IPFS with a CID pointing "
+           "to its CSS. The component fetches and caches it before rendering. "
+           "No coordination needed between sites.")
+        (highlight
+          "(defcomp ~federated-widget (&key cid &rest children)\n  (let ((css-cid (str cid \"/style.css\"))\n        (cached  (css-cached? css-cid)))\n    (if cached\n      children\n      (~suspense :id (str \"fed-\" cid)\n        :fallback (div :class \"animate-pulse bg-stone-100 rounded h-20\")\n        (do (fetch-css (str \"https://ipfs.io/ipfs/\" css-cid) css-cid)\n            children)))))"
+          "lisp"))
+
+      (~doc-subsection :title "Heavy UI Libraries"
+        (p "Code editors, chart libraries, rich text editors — their CSS only loads "
+           "when the component actually appears on screen:")
+        (highlight
+          "(defcomp ~code-editor (&key language value on-change)\n  (~styled :css-url \"/css/codemirror.css\" :css-hash (asset-hash \"codemirror\")\n    :fallback (pre :class \"p-4 bg-stone-900 text-stone-300 rounded\" value)\n    (div :class \"cm-editor\"\n      :data-language language\n      :data-value value)))"
+          "lisp"))
+
+      (~doc-subsection :title "Lazy Themes"
+        (p "Theme CSS loads on first use, then is instant on subsequent visits:")
+        (highlight
+          "(defcomp ~lazy-theme (&key name &rest children)\n  (let ((css-url (str \"/css/themes/\" name \".css\"))\n        (hash    (str \"theme-\" name)))\n    (~styled :css-url css-url :css-hash hash\n      :fallback children  ;; render unstyled immediately\n      children)))"
+          "lisp")))
+
+    (~doc-section :title "How It Composes" :id "composition"
+      (p "Async CSS composes with everything already in SX:")
+      (ul :class "list-disc pl-5 space-y-1 text-stone-700"
+        (li (code "~suspense") " handles the async gap with fallback content")
+        (li "localStorage handles caching across sessions")
+        (li (code "<style id=\"sx-css\">") " is the injection target (same as CSS class delivery)")
+        (li "Component content-hashing tracks what the client has")
+        (li "No new types, no new delivery protocol, no new spec code")))))
+
+
+;; ---------------------------------------------------------------------------
+;; Live Styles
+;; ---------------------------------------------------------------------------
+
+(defcomp ~cssx-live-content ()
+  (~doc-page :title "Live Styles"
+
+    (~doc-section :title "Styles That Respond to Events" :id "concept"
+      (p "Combine " (code "~live") " (SSE) or " (code "~ws") " (WebSocket) with style "
+         "components, and you get styles that change in real-time in response to server "
+         "events. No new infrastructure — just components receiving data through a "
+         "persistent transport."))
+
+    (~doc-section :title "SSE: Live Theme Updates" :id "sse-theme"
+      (p "A " (code "~live") " component declares a persistent connection to an SSE "
+         "endpoint. When the server pushes a new event, " (code "resolveSuspense")
+         " replaces the content:")
+      (highlight
+        "(~live :src \"/api/stream/brand\"\n  (~suspense :id \"theme\"\n    (~theme :primary \"#7c3aed\" :surface \"#fafaf9\")))"
+        "lisp")
+      (p "Server pushes a new theme:")
+      (highlight
+        "event: sx-resolve\ndata: {\"id\": \"theme\", \"sx\": \"(~theme :primary \\\"#2563eb\\\" :surface \\\"#1e1e2e\\\")\"}"
+        "text")
+      (p "The " (code "~theme") " component emits CSS custom properties. Everything "
+         "using " (code "var(--color-primary)") " repaints instantly:")
+      (highlight
+        "(defcomp ~theme (&key primary surface)\n  (style (str \":root {\"\n    \"--color-primary:\" (or primary \"#7c3aed\") \";\"\n    \"--color-surface:\" (or surface \"#fafaf9\") \"}\")))"
+        "lisp"))
+
+    (~doc-section :title "SSE: Live Dashboard Metrics" :id "sse-metrics"
+      (p "Style changes driven by live data — the component decides the visual treatment:")
+      (highlight
+        "(~live :src \"/api/stream/dashboard\"\n  (~suspense :id \"cpu\"\n    (~metric :value 0 :label \"CPU\" :threshold 80))\n  (~suspense :id \"memory\"\n    (~metric :value 0 :label \"Memory\" :threshold 90))\n  (~suspense :id \"requests\"\n    (~metric :value 0 :label \"RPS\" :threshold 1000)))"
+        "lisp")
+      (p "Server pushes updated values. " (code "~metric") " turns red when "
+         (code "value > threshold") " — the styling logic lives in the component, "
+         "not in CSS selectors or JavaScript event handlers."))
+
+    (~doc-section :title "WebSocket: Collaborative Design" :id "ws-design"
+      (p "Bidirectional channel for real-time collaboration. A designer adjusts a color, "
+         "all connected clients see the change:")
+      (highlight
+        "(~ws :src \"/ws/design-studio\"\n  (~suspense :id \"canvas-theme\"\n    (~theme :primary \"#7c3aed\")))"
+        "lisp")
+      (p "Client sends a color change:")
+      (highlight
+        ";; Designer picks a new primary color\n(sx-send ws-conn '(theme-update :primary \"#dc2626\"))"
+        "lisp")
+      (p "Server broadcasts to all connected clients via " (code "sx-resolve") " — "
+         "every client's " (code "~theme") " component re-renders with the new color."))
+
+    (~doc-section :title "Why This Works" :id "why"
+      (p "Every one of these patterns is just a " (code "defcomp") " receiving data "
+         "through a persistent transport. The styling strategy — CSS custom properties, "
+         "class swaps, inline styles, " (code "<style>") " blocks — is the component's "
+         "private business. The transport doesn't know or care.")
+      (p "A parallel style system would have needed its own streaming, its own caching, "
+         "its own delta protocol for each of these use cases — duplicating what components "
+         "already do.")
+      (p :class "mt-4 text-stone-500 italic"
+         "Note: ~live and ~ws are planned (see Live Streaming). The patterns shown here "
+         "will work as described once the streaming transport is implemented. The component "
+         "and suspense infrastructure they depend on already exists."))))
+
+
+;; ---------------------------------------------------------------------------
+;; Comparison with CSS Technologies
+;; ---------------------------------------------------------------------------
+
+(defcomp ~cssx-comparison-content ()
+  (~doc-page :title "Comparisons"
+
+    (~doc-section :title "styled-components / Emotion" :id "styled-components"
+      (p (a :href "https://styled-components.com" :class "text-violet-600 hover:underline" "styled-components")
+         " pioneered the idea that styling belongs in components. But it generates CSS "
+         "at runtime, injects " (code "<style>") " tags, and produces opaque hashed class "
+         "names (" (code "class=\"sc-bdfBwQ fNMpVx\"") "). Open DevTools and you see gibberish. "
+         "It also carries significant runtime cost — parsing CSS template literals, hashing, "
+         "deduplicating — and needs a separate SSR extraction step (" (code "ServerStyleSheet") ").")
+      (p "CSSX components share the core insight (" (em "styling is a component concern")
+         ") but without the runtime machinery. When a component applies Tailwind classes, "
+         "there's zero CSS generation overhead. When it does emit " (code "<style>")
+         " blocks, it's explicit — not hidden behind a tagged template literal. "
+         "And the DOM is always readable."))
+
+    (~doc-section :title "CSS Modules" :id "css-modules"
+      (p (a :href "https://github.com/css-modules/css-modules" :class "text-violet-600 hover:underline" "CSS Modules")
+         " scope class names to avoid collisions by rewriting them at build time: "
+         (code ".button") " becomes " (code ".button_abc123")
+         ". This solves the global namespace problem but creates the same opacity issue — "
+         "hashed names in the DOM that you can't grep for or reason about.")
+      (p "CSSX components don't need scoping because component boundaries already provide "
+         "isolation. A " (code "~btn") " owns its markup. There's nothing to collide with."))
+
+    (~doc-section :title "Tailwind CSS" :id "tailwind"
+      (p "Tailwind is " (em "complementary") ", not competitive. CSSX components are the "
+         "semantic layer on top. Raw Tailwind in markup — "
+         (code ":class \"px-4 py-2 bg-blue-600 text-white font-medium rounded hover:bg-blue-700\"")
+         " — is powerful but verbose and duplicated across call sites.")
+      (p "A CSSX component wraps that string once: " (code "(~btn :variant \"primary\" \"Submit\")")
+         ". The Tailwind classes are still there, readable in DevTools, but consumers don't "
+         "repeat them. This is the same pattern Tailwind's own docs recommend ("
+         (em "\"extracting components\"") ") — CSSX components are just SX's native way of doing it."))
+
+    (~doc-section :title "Vanilla Extract" :id "vanilla-extract"
+      (p (a :href "https://vanilla-extract.style" :class "text-violet-600 hover:underline" "Vanilla Extract")
+         " is zero-runtime CSS-in-JS: styles are written in TypeScript, compiled to static "
+         "CSS at build time, and referenced by generated class names. It avoids the runtime "
+         "cost of styled-components but still requires a build step, a bundler plugin, and "
+         "TypeScript. The generated class names are again opaque.")
+      (p "CSSX components need no build step for styling — they're evaluated at render time "
+         "like any other component. And since the component chooses its own strategy, it can "
+         "reference pre-built classes (zero runtime) " (em "or") " generate CSS on the fly — "
+         "same API either way."))
+
+    (~doc-section :title "Design Tokens / Style Dictionary" :id "design-tokens"
+      (p "The " (a :href "https://amzn.github.io/style-dictionary/" :class "text-violet-600 hover:underline" "Style Dictionary")
+         " pattern — a JSON/YAML file mapping token names to values, compiled to "
+         "platform-specific output — is essentially what the old CSSX was. It's the "
+         "industry standard for design systems.")
+      (p "The problem is that it's a parallel system: separate file format, separate build "
+         "pipeline, separate caching, separate tooling. CSSX components eliminate all of "
+         "that by expressing tokens as component parameters: "
+         (code "(~theme :primary \"#7c3aed\")") " instead of "
+         (code "{\"color\": {\"primary\": {\"value\": \"#7c3aed\"}}}")
+         ". Same result, no parallel infrastructure."))))
+
+
+;; ---------------------------------------------------------------------------
+;; Philosophy
+;; ---------------------------------------------------------------------------
+
+(defcomp ~cssx-philosophy-content ()
+  (~doc-page :title "Philosophy"
+
+    (~doc-section :title "The Collapse" :id "collapse"
+      (p "The web has spent two decades building increasingly complex CSS tooling: "
+         "preprocessors, CSS-in-JS, atomic CSS, utility frameworks, design tokens, style "
+         "dictionaries. Each solves a real problem but adds a new system with its own "
+         "caching, bundling, and mental model.")
+      (p "CSSX components collapse all of this back to the simplest possible thing: "
+         (strong "a function that takes data and returns markup with classes.")
+         " That's what a component already is. There is no separate styling system because "
+         "there doesn't need to be."))
+
+    (~doc-section :title "Proof by Deletion" :id "proof"
+      (p "The strongest validation: we built the full parallel system — style dictionary, "
+         "StyleValue type, content-addressed hashing, runtime injection, localStorage "
+         "caching — and then deleted it because nobody used it. The codebase already had "
+         "the answer: " (code "defcomp") " with " (code ":class") " strings.")
+      (p "3,000 lines of infrastructure removed. Zero lines added. Every use case still works."))
+
+    (~doc-section :title "The Right Abstraction Level" :id "abstraction"
+      (p "CSS-in-JS puts styling " (em "below") " components — you style elements, then compose "
+         "them. Utility CSS puts styling " (em "beside") " components — classes in markup, logic "
+         "elsewhere. Both create a seam between what something does and how it looks.")
+      (p "CSSX components put styling " (em "inside") " components — at the same level as "
+         "structure and behavior. A " (code "~metric") " component knows its own thresholds, "
+         "its own color scheme, its own responsive behavior. Styling is just another "
+         "decision the component makes, not a separate concern."))
+
+    (~doc-section :title "Relationship to Other Plans" :id "relationships"
+      (ul :class "list-disc pl-5 space-y-2 text-stone-700"
+        (li (strong "Content-Addressed Components: ") "CSSX components get CIDs like any "
+            "other component. A " (code "~btn") " from one site can be shared to another via "
+            "IPFS. No " (code ":css-atoms") " manifest field needed — the component carries "
+            "its own styling logic.")
+        (li (strong "Isomorphic Rendering: ") "Components render the same on server and client. "
+            "No style injection timing issues, no FOUC from late CSS loading.")
+        (li (strong "Component Bundling: ") "deps.sx already handles transitive component deps. "
+            "Style components are just more components in the bundle — no separate style bundling.")
+        (li (strong "Live Streaming: ") "SSE and WebSocket transports push data to components. "
+            "Style components react to that data like any other component — no separate style "
+            "streaming protocol.")))))
diff --git a/sx/sx/layouts.sx b/sx/sx/layouts.sx
index 32f085b..6a65db1 100644
--- a/sx/sx/layouts.sx
+++ b/sx/sx/layouts.sx
@@ -8,6 +8,7 @@
   (let* ((sc "aria-selected:bg-violet-200 aria-selected:text-violet-900")
          (items (list
            (dict :label "Docs" :href "/docs/introduction")
+           (dict :label "CSSX" :href "/cssx/")
            (dict :label "Reference" :href "/reference/")
            (dict :label "Protocols" :href "/protocols/wire-format")
            (dict :label "Examples" :href "/examples/click-to-load")
diff --git a/sx/sx/nav-data.sx b/sx/sx/nav-data.sx
index 90d55b1..f8b003f 100644
--- a/sx/sx/nav-data.sx
+++ b/sx/sx/nav-data.sx
@@ -55,13 +55,21 @@
   (dict :label "Request Abort" :href "/examples/sync-replace")
   (dict :label "Retry" :href "/examples/retry")))
 
+(define cssx-nav-items (list
+  (dict :label "Overview" :href "/cssx/")
+  (dict :label "Patterns" :href "/cssx/patterns")
+  (dict :label "Async CSS" :href "/cssx/async")
+  (dict :label "Live Styles" :href "/cssx/live")
+  (dict :label "Comparisons" :href "/cssx/comparisons")
+  (dict :label "Philosophy" :href "/cssx/philosophy")))
+
 (define essays-nav-items (list
   (dict :label "Why S-Expressions" :href "/essays/why-sexps"
         :summary "Why SX uses s-expressions instead of HTML templates, JSX, or any other syntax.")
   (dict :label "The htmx/React Hybrid" :href "/essays/htmx-react-hybrid"
         :summary "How SX combines the server-driven simplicity of htmx with the component model of React.")
   (dict :label "On-Demand CSS" :href "/essays/on-demand-css"
-        :summary "The CSSX system: keyword atoms resolved to class names, CSS rules injected on first use.")
+        :summary "How SX delivers only the CSS each page needs — server scans rendered classes, sends the delta.")
   (dict :label "Client Reactivity" :href "/essays/client-reactivity"
         :summary "Reactive UI updates without a virtual DOM, diffing library, or build step.")
   (dict :label "SX Native" :href "/essays/sx-native"
@@ -103,7 +111,6 @@
   (dict :label "SxEngine" :href "/specs/engine")
   (dict :label "Orchestration" :href "/specs/orchestration")
   (dict :label "Boot" :href "/specs/boot")
-  (dict :label "CSSX" :href "/specs/cssx")
   (dict :label "Continuations" :href "/specs/continuations")
   (dict :label "call/cc" :href "/specs/callcc")
   (dict :label "Deps" :href "/specs/deps")
@@ -147,7 +154,7 @@
   (dict :label "SX CI Pipeline" :href "/plans/sx-ci"
         :summary "Build, test, and deploy in s-expressions — CI pipelines as SX components.")
   (dict :label "CSSX Components" :href "/plans/cssx-components"
-        :summary "Styling as components — replace the style dictionary with regular defcomps that apply classes, respond to data, and compose naturally.")
+        :summary "Done — see /cssx/. Styling as components: style dictionary removed, defcomps handle all styling.")
   (dict :label "Live Streaming" :href "/plans/live-streaming"
         :summary "SSE and WebSocket transports for re-resolving suspense slots after initial page load — live data, real-time collaboration.")))
 
@@ -176,7 +183,7 @@
         :prose "Special forms are the syntactic constructs whose arguments are NOT evaluated before dispatch. Each form has its own evaluation rules — unlike primitives, which receive pre-evaluated values. Together with primitives, special forms define the complete language surface. The registry covers control flow (if, when, cond, case, and, or), binding (let, letrec, define, set!), functions (lambda, defcomp, defmacro), sequencing (begin, do, thread-first), quoting (quote, quasiquote), continuations (reset, shift), guards (dynamic-wind), higher-order forms (map, filter, reduce), and domain-specific definitions (defstyle, defhandler, defpage, defquery, defaction).")
   (dict :slug "renderer"   :filename "render.sx"      :title "Renderer"
         :desc "Shared rendering registries and utilities used by all adapters."
-        :prose "The renderer defines what is renderable and how arguments are parsed, but not the output format. It maintains registries of known HTML tags, SVG tags, void elements, and boolean attributes. It specifies how keyword arguments on elements become HTML attributes, how children are collected, and how special attributes (class, style, data-*) are handled. All three adapters (DOM, HTML, SX wire) share these definitions so they agree on what constitutes valid markup. The renderer also defines the StyleValue type used by the CSSX on-demand CSS system.")))
+        :prose "The renderer defines what is renderable and how arguments are parsed, but not the output format. It maintains registries of known HTML tags, SVG tags, void elements, and boolean attributes. It specifies how keyword arguments on elements become HTML attributes, how children are collected, and how special attributes (class, style, data-*) are handled. All three adapters (DOM, HTML, SX wire) share these definitions so they agree on what constitutes valid markup.")))
 
 (define adapter-spec-items (list
   (dict :slug "adapter-dom"   :filename "adapter-dom.sx"   :title "DOM Adapter"
diff --git a/sx/sxc/pages/docs.sx b/sx/sxc/pages/docs.sx
index 957c766..320e844 100644
--- a/sx/sxc/pages/docs.sx
+++ b/sx/sxc/pages/docs.sx
@@ -286,6 +286,39 @@
     "no-alternative" (~essay-no-alternative)
     :else (~essays-index-content)))
 
+;; ---------------------------------------------------------------------------
+;; CSSX section
+;; ---------------------------------------------------------------------------
+
+(defpage cssx-index
+  :path "/cssx/"
+  :auth :public
+  :layout (:sx-section
+    :section "CSSX"
+    :sub-label "CSSX"
+    :sub-href "/cssx/"
+    :sub-nav (~section-nav :items cssx-nav-items :current "Overview")
+    :selected "Overview")
+  :content (~cssx-overview-content))
+
+(defpage cssx-page
+  :path "/cssx/<slug>"
+  :auth :public
+  :layout (:sx-section
+    :section "CSSX"
+    :sub-label "CSSX"
+    :sub-href "/cssx/"
+    :sub-nav (~section-nav :items cssx-nav-items
+               :current (find-current cssx-nav-items slug))
+    :selected (or (find-current cssx-nav-items slug) ""))
+  :content (case slug
+    "patterns" (~cssx-patterns-content)
+    "async" (~cssx-async-content)
+    "live" (~cssx-live-content)
+    "comparisons" (~cssx-comparison-content)
+    "philosophy" (~cssx-philosophy-content)
+    :else (~cssx-overview-content)))
+
 ;; ---------------------------------------------------------------------------
 ;; Specs section
 ;; ---------------------------------------------------------------------------