;; ---------------------------------------------------------------------------
;; Comparison with CSS Technologies
;; ---------------------------------------------------------------------------
(defcomp ()
  (~docs/page :title "Comparisons"

    (~docs/section :title "styled-components / Emotion" :id "styled-components"
      (p (a :href "https://styled-components.com" (~tw :tokens "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."))

    (~docs/section :title "CSS Modules" :id "css-modules"
      (p (a :href "https://github.com/css-modules/css-modules" (~tw :tokens "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 "~cssx/btn") " owns its markup. There's nothing to collide with."))

    (~docs/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 "(~cssx/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."))

    (~docs/section :title "Vanilla Extract" :id "vanilla-extract"
      (p (a :href "https://vanilla-extract.style" (~tw :tokens "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."))

    (~docs/section :title "Design Tokens / Style Dictionary" :id "design-tokens"
      (p "The " (a :href "https://amzn.github.io/style-dictionary/" (~tw :tokens "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 "(~cssx/theme :primary \"#7c3aed\")") " instead of "
         (code "{\"color\": {\"primary\": {\"value\": \"#7c3aed\"}}}")
         ". Same result, no parallel infrastructure."))))
