From 621c0bbf429178b0ec9afd40031972638fc51511 Mon Sep 17 00:00:00 2001
From: giles <giles.bradshaw@rose-ash.com>
Date: Sat, 7 Mar 2026 22:15:24 +0000
Subject: [PATCH] CSSX plan: add CSS technology comparisons, fix
 strategy-agnostic claim
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add comparisons with styled-components, CSS Modules, Tailwind, Vanilla
Extract, and Design Tokens. Add example of components emitting <style>
blocks directly. Fix "CSS-agnostic" to "strategy-agnostic" — components
can generate CSS, not just reference existing classes.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 sx/sx/plans.sx | 34 ++++++++++++++++++++++++++++++++--
 1 file changed, 32 insertions(+), 2 deletions(-)

diff --git a/sx/sx/plans.sx b/sx/sx/plans.sx
index 8a646a0..735778f 100644
--- a/sx/sx/plans.sx
+++ b/sx/sx/plans.sx
@@ -2114,7 +2114,7 @@
         (li (strong "One system: ") "No separate " (code "StyleValue") " type, no style dictionary JSON, no " (code "<script type=\"text/sx-styles\">") ", no " (code "sx-css") " injection. 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 "CSS-agnostic: ") "Works with Tailwind classes, BEM, CSS modules, inline styles, or any combination. Swap implementations without touching call sites.")))
+        (li (strong "Strategy-agnostic: ") "A component can apply Tailwind classes, emit " (code "<style>") " blocks, use inline styles, generate CSS custom properties, or any combination. The consumer never knows or cares. Swap strategies without touching call sites.")))
 
     (~doc-section :title "Examples" :id "examples"
       (~doc-subsection :title "Simple class mapping"
@@ -2139,7 +2139,14 @@
         (p "Components can encode responsive breakpoints and interactive states as class strings — the same way you'd write Tailwind, but wrapped in a semantic component:")
         (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")))
+          "lisp"))
+
+      (~doc-subsection :title "Emitting CSS directly"
+        (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)))\n\n(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.")))
 
     (~doc-section :title "What Changes" :id "changes"
 
@@ -2182,6 +2189,29 @@
         (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.")))
 
+    (~doc-section :title "Comparison with CSS Technologies" :id "comparison"
+      (p "CSSX components share DNA with several existing approaches but avoid the problems that make each one painful at scale.")
+
+      (~doc-subsection :title "styled-components / Emotion"
+        (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-subsection :title "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-subsection :title "Tailwind CSS"
+        (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-subsection :title "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-subsection :title "Design Tokens / Style Dictionary"
+        (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.")))
+
     (~doc-section :title "Philosophy" :id "philosophy"
       (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."))))