@alex.radulescu/styled-static 0.2.0 → 0.7.2

package/README.md

@@ -1,12 +1,12 @@
 <!--
 ═══════════════════════════════════════════════════════════════════════════════
 This README serves as both user documentation and LLM context (LLMs.txt).
-It documents styled-static - a zero-runtime CSS-in-JS library for React 19+
-with Vite.
+It documents styled-static - a near-zero-runtime CSS-in-JS library for React 19+
+with Vite. CSS is extracted at build time; minimal runtime handles dynamic features.
 
 Key APIs: styled, css, createGlobalStyle, styledVariants, cssVariants, cx
 Theme helpers: initTheme, setTheme, getTheme, onSystemThemeChange
-Runtime: ~300 bytes | Dependencies: 0 | React 19+ required | Vite only
+Runtime: Minimal | Dependencies: 0 | React 19+ required | Vite only
 
 For implementation details, see CLAUDE.md or the source files in src/
 ═══════════════════════════════════════════════════════════════════════════════
@@ -14,22 +14,25 @@ For implementation details, see CLAUDE.md or the source files in src/
 
 # styled-static
 
-Zero-runtime CSS-in-JS for React 19+ with Vite. Write styled-components syntax, get static CSS extracted at build time.
+Near-zero-runtime CSS-in-JS for React 19+ with Vite. Write styled-components syntax, get static CSS extracted at build time.
+
+**What's "zero"?** CSS generation happens at build time (the expensive part). A minimal runtime (~45 bytes) handles className merging. Components are generated inline at build time.
 
 ## Features
 
-- ⚡ **Zero Runtime** - CSS extracted at build time, no CSS-in-JS overhead
+- ⚡ **Static CSS** - All CSS extracted at build time, no runtime stylesheet generation
 - 🎯 **Type-Safe** - Full TypeScript support with proper prop inference
 - 🎨 **Familiar API** - styled-components syntax you already know
-- 📦 **Tiny** - ~300 bytes runtime for `as` prop and transient props support
+- 📦 **Tiny** - Minimal ~45 byte runtime for className merging only
 - 🔧 **Zero Dependencies** - Uses native CSS features and Vite's built-in tools
+- 🌳 **Inline Components** - Components generated at build time, no runtime factories
 - 🌓 **Theme Helpers** - Simple utilities for dark mode and custom themes
 
 ---
 
 ## Quick Overview
 
-All the APIs you need at a glance. styled-static provides 6 core functions that cover most CSS-in-JS use cases:
+All the APIs you need at a glance. styled-static provides 10 core functions that cover most CSS-in-JS use cases:
 
 ### styled.element
 
@@ -101,55 +104,70 @@ const badgeCss = cssVariants({
 });
 
 <span className={badgeCss({ color: "blue" })}>Info</span>;
-```
-
----
-
-## Why styled-static?
 
-- 🌐 **CSS & browsers have evolved.** Native CSS nesting, CSS variables, container queries, and fewer vendor prefixes mean the gap between CSS and CSS-in-JS has never been smaller.
+// Combine classes conditionally
+<div className={cx("base", isActive && activeClass)} />;
 
-- 😵 **CSS-in-JS fatigue is real.** Most libraries are now obsolete, overly complex, or have large runtime overhead. The ecosystem needs simpler solutions.
+// Default attributes
+const PasswordInput = styled.input.attrs({ type: "password" })`
+  padding: 0.5rem 1rem;
+`;
 
-- ✨ **Syntactic sugar over CSS modules.** Most projects don't need runtime interpolation. They need a better DX for writing and organizing CSS.
+// Polymorphism - render Link with Button's styles
+import { Link } from "react-router-dom";
+const LinkButton = withComponent(Link, Button);
+<LinkButton to="/path">Router link styled as button</LinkButton>;
+```
 
-- 🔒 **Supply chain security matters.** Zero dependencies means a minimal attack surface. No transitive dependencies to audit or worry about.
+---
 
-- 🎯 **Intentionally simple.** 95% native browser foundation + 5% sprinkles on top. We leverage what browsers already do well.
+## Table of Contents
 
-- 🎉 **Built for fun.** Sometimes the best projects come from curiosity and the joy of building something useful.
+- [Quick Overview](#quick-overview) · [Why](#why-styled-static) · [What We Don't Do](#what-we-dont-do) · [Installation](#installation)
+- **API:** [styled](#styled) · [Extension](#component-extension) · [css](#css-helper) · [keyframes](#keyframes) · [attrs](#attrs) · [cx](#cx-utility) · [Global Styles](#global-styles) · [Variants](#variants-api)
+- **Features:** [Polymorphism](#polymorphism-with-withcomponent) · [.className](#manual-composition-with-classname) · [CSS Nesting](#css-nesting) · [Dynamic Styling](#dynamic-styling) · [Theming](#theming)
+- **Internals:** [Troubleshooting](#troubleshooting) · [How It Works](#how-it-works) · [Config](#configuration) · [TypeScript](#typescript) · [Zero Deps](#zero-dependencies) · [Comparison](#comparison)
 
 ---
 
-## What We Don't Do
+## Why styled-static?
 
-styled-static is intentionally limited. Here's what we don't support—and why:
+- 🌐 **CSS evolved.** Native nesting, CSS variables, container queries—the gap between CSS and CSS-in-JS is smaller than ever.
+- 😵 **CSS-in-JS fatigue.** Most libraries are obsolete, complex, or have large runtime overhead.
+- ✨ **Syntactic sugar over CSS modules.** Better DX for writing CSS, without runtime interpolation.
+- 🔒 **Zero dependencies.** Minimal attack surface. Nothing to audit.
+- 🎯 **Intentionally simple.** 95% native browser + 5% sprinkles.
+- 🎉 **Built for fun.** Curiosity-driven, useful code.
 
-- 🚫 **No runtime interpolation.** You can't write `${props => props.color}`. CSS is extracted at build time, so values must be static. Use CSS variables, data attributes, or the Variants API for dynamic styles.
+---
 
-- ⚛️ **React 19+ only.** We rely on automatic ref forwarding instead of `forwardRef`. This keeps the runtime tiny but requires React 19.
+## What We Don't Do
 
-- ⚡ **Vite only.** The plugin uses Vite's built-in AST parser and virtual module system. No Webpack, Rollup, or other bundler support.
+- 🚫 **No runtime interpolation** — Can't write `${props => props.color}`. Use variants, CSS variables, or data attributes.
+- ⚛️ **React 19+ only** — Uses automatic ref forwarding (no `forwardRef`).
+- ⚡ **Vite only** — Uses Vite's AST parser and virtual modules. No Webpack/Rollup.
+- 🚫 **No `css` prop** — Use named `css` variables with `className`.
+- 🚫 **No `shouldForwardProp`** — Not needed. Variants auto-strip props.
 
-- 💡 **Why these constraints?** Each limitation removes complexity. No runtime interpolation means no runtime CSS parsing. React 19 means no forwardRef wrapper. Vite-only means one excellent integration instead of many mediocre ones.
+Each constraint removes complexity—no CSS parsing, no forwardRef, one great integration.
 
 ---
 
 ## Installation
 
 ```bash
-npm install styled-static
+npm install @alex.radulescu/styled-static
 # or
-bun add styled-static
+bun add @alex.radulescu/styled-static
 ```
 
 Configure the Vite plugin:
 
 ```ts
 // vite.config.ts
-import { defineConfig } from "vite";
 import react from "@vitejs/plugin-react";
-import { styledStatic } from "styled-static/vite";
+import { styledStatic } from "@alex.radulescu/styled-static/vite";
+import { defineConfig } from "vite";
 
 export default defineConfig({
   plugins: [styledStatic(), react()],
@@ -164,10 +182,10 @@ export default defineConfig({
 
 ### styled
 
-Create styled React components with zero runtime overhead. CSS is extracted to static files at build time.
+Create styled React components:
 
 ```tsx
-import { styled } from "styled-static";
+import { styled } from "@alex.radulescu/styled-static";
 
 const Button = styled.button`
   padding: 0.5rem 1rem;
@@ -226,7 +244,7 @@ When components are extended, classes are ordered correctly:
 Get a scoped class name for mixing with other classes:
 
 ```tsx
-import { css } from 'styled-static';
+import { css } from '@alex.radulescu/styled-static';
 
 const activeClass = css`
   outline: 2px solid blue;
@@ -252,7 +270,7 @@ const highlightClass = css`
 Create scoped keyframe animations. The animation name is hashed to avoid conflicts between components:
 
 ```tsx
-import { styled, keyframes } from "styled-static";
+import { keyframes, styled } from "@alex.radulescu/styled-static";
 
 const spin = keyframes`
   from { transform: rotate(0deg); }
@@ -282,42 +300,13 @@ const PulsingDot = styled.div`
 `;
 ```
 
-**How it works:**
-
-- At build time, keyframes CSS is extracted to a static file
-- The animation name is hashed (e.g., `ss-abc123`)
-- References in styled components are replaced with the hashed name
-
-```css
-/* Generated CSS */
-@keyframes ss-abc123 {
-  from {
-    transform: rotate(0deg);
-  }
-  to {
-    transform: rotate(360deg);
-  }
-}
-.ss-xyz789 {
-  animation: ss-abc123 1s linear infinite;
-}
-```
+Animation names are hashed at build time to avoid conflicts.
 
 ### attrs
 
-Set default HTML attributes on styled components using the `.attrs()` method:
+Set default HTML attributes using `.attrs()`:
 
 ```tsx
-import { styled } from 'styled-static';
-
-// Set default type for input
-const PasswordInput = styled.input.attrs({ type: 'password' })`
-  padding: 0.5rem 1rem;
-  border: 1px solid #e5e7eb;
-  border-radius: 4px;
-`;
-
-// Set multiple default attributes
 const SubmitButton = styled.button.attrs({
   type: 'submit',
   'aria-label': 'Submit form',
@@ -327,45 +316,30 @@ const SubmitButton = styled.button.attrs({
   color: white;
 `;
 
-// Usage - default attrs are applied, can be overridden
-<PasswordInput placeholder="Enter password" />
-// Renders: <input type="password" placeholder="Enter password" class="ss-abc123" />
-
 <SubmitButton>Send</SubmitButton>
-// Renders: <button type="submit" aria-label="Submit form" class="ss-xyz789">Send</button>
+// Renders: <button type="submit" aria-label="Submit form" class="ss-xyz789">
 ```
 
-> **Note:** Unlike styled-components, attrs in styled-static must be static objects (no functions). For dynamic attributes, use regular props on your component.
+> **Note:** attrs must be static objects (no functions). For dynamic attributes, use regular props.
 
 ### cx Utility
 
-Combine class names conditionally with the minimal `cx` utility (~40 bytes):
+Combine class names conditionally. Intentionally flat (no nested arrays/objects) for minimal bundle size:
 
 ```tsx
-import { css, cx } from 'styled-static';
+import { css, cx } from '@alex.radulescu/styled-static';
 
-const activeClass = css`
-  color: blue;
-`;
-
-// Multiple class names
-<div className={cx('base', 'active')} />
-// → class="base active"
+const activeClass = css`color: blue;`;
 
-// Conditional classes
-<Button className={cx('btn', isActive && activeClass)} />
-// → class="btn ss-abc123" (when active)
-// → class="btn" (when not active)
-
-// Falsy values are filtered out
-<div className={cx('a', null, undefined, false, 'b')} />
-// → class="a b"
+cx('base', 'active')                    // → "base active"
+cx('btn', isActive && activeClass)      // → "btn ss-abc123" or "btn"
+cx('a', null, undefined, false, 'b')    // → "a b"
 ```
 
 ### Global Styles
 
 ```tsx
-import { createGlobalStyle } from "styled-static";
+import { createGlobalStyle } from "@alex.radulescu/styled-static";
 
 const GlobalStyle = createGlobalStyle`
   * {
@@ -392,7 +366,6 @@ createRoot(document.getElementById("root")!).render(
 );
 ```
 
-> **Note:** The component renders nothing at runtime. All CSS is extracted and injected via imports.
 
 ### Variants API
 
@@ -403,68 +376,37 @@ For type-safe variant handling, use `styledVariants` to create components with v
 #### styledVariants
 
 ```tsx
-import { styledVariants, css } from "styled-static";
+import { css, styledVariants } from "@alex.radulescu/styled-static";
 
-// With css`` for syntax highlighting (recommended)
 const Button = styledVariants({
   component: "button",
   css: css`
     padding: 0.5rem 1rem;
-    border: none;
-    border-radius: 4px;
-    cursor: pointer;
+    background: gray;
+    color: white;
+    font-size: 1rem;
   `,
   variants: {
     color: {
-      primary: css`
-        background: blue;
-        color: white;
-      `,
-      danger: css`
-        background: red;
-        color: white;
-      `,
-      success: css`
-        background: green;
-        color: white;
-      `,
+      primary: css`background: blue;`,
+      danger: css`background: red;`,
+      success: css`background: green;`,
     },
     size: {
-      sm: css`
-        font-size: 0.875rem;
-        padding: 0.25rem 0.5rem;
-      `,
-      md: css`
-        font-size: 1rem;
-      `,
-      lg: css`
-        font-size: 1.125rem;
-        padding: 0.75rem 1.5rem;
-      `,
+      sm: css`font-size: 0.875rem; padding: 0.25rem 0.5rem;`,
+      lg: css`font-size: 1.125rem; padding: 0.75rem 1.5rem;`,
     },
   },
 });
 
-// Plain strings also work (no highlighting)
-const SimpleButton = styledVariants({
-  component: "button",
-  css: `padding: 0.5rem;`,
-  variants: {
-    size: { sm: `font-size: 0.875rem;` },
-  },
-});
-
-// Usage - variant props are type-safe
-<Button color="primary" size="lg">
-  Click me
-</Button>;
+<Button color="primary" size="lg">Click me</Button>
 // Renders: <button class="ss-abc ss-abc--color-primary ss-abc--size-lg">
 ```
 
 #### cssVariants
 
 ```tsx
-import { cssVariants, css, cx } from 'styled-static';
+import { cssVariants, css, cx } from '@alex.radulescu/styled-static';
 
 // With css`` for syntax highlighting (recommended)
 const badgeCss = cssVariants({
@@ -496,44 +438,58 @@ const badgeCss = cssVariants({
 
 ## Features
 
-### Polymorphic `as` Prop
+### Polymorphism with withComponent
 
-Render a styled component as a different HTML element:
+Render one component with another's styles using `withComponent`:
 
 ```tsx
+import { Link } from "react-router-dom";
+import { styled, withComponent } from "@alex.radulescu/styled-static";
+
 const Button = styled.button`
   padding: 0.5rem 1rem;
   background: blue;
   color: white;
 `;
 
-// Render as an anchor tag
-<Button as="a" href="/link">
-  I'm a link styled as a button
-</Button>;
+// Create a Link that looks like Button
+const LinkButton = withComponent(Link, Button);
+
+// Also works with HTML tags
+const AnchorButton = withComponent('a', Button);
+
+// Usage
+<LinkButton to="/path">Router link styled as button</LinkButton>
+<AnchorButton href="/external">External link</AnchorButton>
 ```
 
-### Transient Props
+`withComponent` accepts:
+
+- **First argument**: The component to render (React component or HTML tag string)
+- **Second argument**: The styled component whose styles to use
+
+### Manual Composition with .className
 
-Props prefixed with `$` are filtered out and won't reach the DOM. This is useful for passing data through components without polluting the HTML:
+Every styled component exposes a static `.className` property for manual composition:
 
 ```tsx
-// $-prefixed props are filtered from the DOM
-<Button $trackingId="hero-cta" onClick={handleClick}>
-  Click
-</Button>;
-// Renders: <button class="ss-abc123">Click</button>
-// The $trackingId prop is available in event handlers but not in HTML
-
-// Useful for component composition
-const Card = styled.div`...`;
-<Card $featured={true} $size="large" className="my-card">
-  Content
-</Card>;
-// Renders: <div class="ss-abc123 my-card">Content</div>
+const Button = styled.button`
+  padding: 0.5rem 1rem;
+  background: blue;
+`;
+
+// Use className directly on any element
+<a className={Button.className} href="/link">
+  Link with button styles
+</a>
+
+// Combine with cx utility
+<div className={cx(Button.className, Card.className, "custom")}>
+  Combined styles
+</div>
 ```
 
-> **Note:** Since styled-static extracts CSS at build time, transient props cannot be used for dynamic styling. Use class toggling, data attributes, or CSS variables instead.
+This is useful when you need button styles on a non-component element or want to combine multiple styled component classes.
 
 ### CSS Nesting
 
@@ -574,281 +530,175 @@ const Card = styled.div`
 
 ## Dynamic Styling
 
-Since CSS is extracted at build time, you cannot use runtime interpolations like `${props => props.color}`. Instead, use these patterns:
-
-### 1. Variants API (Recommended)
-
-For type-safe variant handling, use `styledVariants` or `cssVariants`:
-
-```tsx
-import { styledVariants, css } from "styled-static";
-
-const Button = styledVariants({
-  component: "button",
-  css: css`
-    padding: 0.5rem 1rem;
-    border: none;
-    border-radius: 4px;
-  `,
-  variants: {
-    color: {
-      primary: css`background: blue; color: white;`,
-      danger: css`background: red; color: white;`,
-      success: css`background: green; color: white;`,
-    },
-  },
-});
+No runtime interpolation—use these patterns instead:
+- **[Variants API](#variants-api)** — Type-safe component variants (recommended)
+- **[cx utility](#cx-utility)** — Conditional class toggling
+- **CSS variables** — Pass via `style` prop for truly dynamic values
+- **Data attributes** — Style with `&[data-variant="x"]` selectors
 
-// Usage - variant props are type-safe
-<Button color="primary">Click</Button>
-<Button color="danger">Delete</Button>
-```
+---
 
-See the [Variants API](#variants-api) section for full documentation.
+## Theming
 
-### 2. Class Toggling with cx
+CSS-first theming with CSS variables and `data-theme` attributes:
 
 ```tsx
-import { styled, css, cx } from "styled-static";
-
-const primaryClass = css`
-  background: blue;
-`;
-const dangerClass = css`
-  background: red;
+const GlobalStyle = createGlobalStyle`
+  :root, [data-theme="light"] { --bg: #fff; --text: #1a1a1a; }
+  [data-theme="dark"] { --bg: #0a0a0a; --text: #f1f5f9; }
+  [data-theme="pokemon"] { --bg: #ffcb05; --text: #2a75bb; }
 `;
 
-const Button = styled.button`
-  padding: 0.5rem 1rem;
-  color: white;
+const Card = styled.div`
+  background: var(--bg);
+  color: var(--text);
 `;
-
-// Toggle between classes based on props/state
-<Button className={cx(isPrimary ? primaryClass : dangerClass)}>Click</Button>;
 ```
 
-### 3. Data Attributes
+### Theme Helpers
 
 ```tsx
-const Button = styled.button`
-  padding: 0.5rem 1rem;
-  color: white;
-
-  &[data-variant="primary"] {
-    background: blue;
-  }
-  &[data-variant="danger"] {
-    background: red;
-  }
-  &[data-variant="success"] {
-    background: green;
-  }
-`;
+import { initTheme, setTheme, getTheme, onSystemThemeChange } from "@alex.radulescu/styled-static";
 
-<Button data-variant={variant}>Click</Button>;
-```
+// Initialize (reads localStorage → system preference → default)
+initTheme({ defaultTheme: "light", useSystemPreference: true });
 
-### 4. CSS Variables
+// Switch themes
+setTheme("dark");              // persists to localStorage
+setTheme("pokemon", false);    // no persist (preview)
 
-```tsx
-const Button = styled.button`
-  padding: 0.5rem 1rem;
-  background: var(--btn-bg, gray);
-  color: var(--btn-color, white);
-`;
+// Read current
+const current = getTheme();    // 'light' | 'dark' | etc.
 
-<Button style={{ "--btn-bg": color, "--btn-color": textColor }}>Click</Button>;
+// React to OS changes
+const unsub = onSystemThemeChange((prefersDark) => {
+  if (!localStorage.getItem("theme")) setTheme(prefersDark ? "dark" : "light", false);
+});
 ```
 
----
-
-## Theming
-
-styled-static provides a simple, CSS-first approach to theming using CSS variables and `data-theme` attributes. No runtime overhead—just pure CSS.
-
-### Defining Themes
+| Function | Description |
+| -------- | ----------- |
+| `initTheme(options?)` | Init on load. Priority: localStorage → system → default |
+| `setTheme(theme, persist?)` | Set theme. Persists to localStorage by default |
+| `getTheme()` | Get current theme from `data-theme` |
+| `onSystemThemeChange(cb)` | Subscribe to OS theme changes |
 
-Use `createGlobalStyle` to define your theme tokens:
+---
 
-```tsx
-import { createGlobalStyle, styled } from "styled-static";
+## Troubleshooting
 
-const GlobalStyle = createGlobalStyle`
-  :root, [data-theme="light"] {
-    --color-bg: #ffffff;
-    --color-text: #1a1a1a;
-    --color-primary: #3b82f6;
-    --color-accent: #8b5cf6;
-  }
-  
-  [data-theme="dark"] {
-    --color-bg: #0f172a;
-    --color-text: #f1f5f9;
-    --color-primary: #60a5fa;
-    --color-accent: #a78bfa;
-  }
-  
-  /* Custom themes */
-  [data-theme="pokemon"] {
-    --color-bg: #ffcb05;
-    --color-text: #2a75bb;
-    --color-primary: #cc0000;
-    --color-accent: #3d7dca;
-  }
-  
-  [data-theme="star-trek"] {
-    --color-bg: #000000;
-    --color-text: #ff9900;
-    --color-primary: #3366cc;
-    --color-accent: #cc0000;
-  }
-`;
+### Storybook: "This package is ESM only"
 
-// Use CSS variables in your components
-const Button = styled.button`
-  background: var(--color-primary);
-  color: var(--color-bg);
-  padding: 0.75rem 1.5rem;
-  border: none;
-  border-radius: 4px;
+If you see this error when using styled-static with Storybook:
 
-  &:hover {
-    background: var(--color-accent);
-  }
-`;
+```
+Failed to resolve "@alex.radulescu/styled-static/vite".
+This package is ESM only but it was tried to load by `require`.
 ```
 
-### Theme Helper Functions
+Add the package to Vite's `optimizeDeps.include` in your Storybook config:
 
-styled-static provides helper functions for theme switching:
+```ts
+// .storybook/main.ts
+export default {
+  // ... other config
+  viteFinal: async (config) => {
+    config.optimizeDeps = config.optimizeDeps || {};
+    config.optimizeDeps.include = [
+      ...(config.optimizeDeps.include || []),
+      '@alex.radulescu/styled-static',
+    ];
+    return config;
+  },
+};
+```
 
-```tsx
-import {
-  initTheme,
-  setTheme,
-  getTheme,
-  onSystemThemeChange,
-} from "styled-static";
-
-// Initialize on app load (reads from localStorage, falls back to default)
-initTheme({
-  defaultTheme: "light",
-  useSystemPreference: true, // Optional: detect OS dark mode
-});
+This is a known limitation with ESM-only packages in Storybook's esbuild-based config loading.
 
-// Get current theme
-const current = getTheme(); // 'light' | 'dark' | 'pokemon' | etc.
+---
 
-// Change theme (persists to localStorage by default)
-setTheme("dark");
+## How It Works
 
-// Change without persisting (useful for previews)
-setTheme("pokemon", false);
+styled-static uses a Vite plugin to transform your styled components at build time. Here's what happens under the hood:
 
-// Listen for OS theme changes
-const unsubscribe = onSystemThemeChange((prefersDark) => {
-  if (!localStorage.getItem("theme")) {
-    setTheme(prefersDark ? "dark" : "light", false);
-  }
-});
-```
+### Build-Time Transformation
 
-### Theme Toggle Example
+When you write a styled component, the Vite plugin intercepts your code and performs AST-based transformation:
 
 ```tsx
-import { getTheme, setTheme } from "styled-static";
+// 1. What you write:
+import { styled } from "@alex.radulescu/styled-static";
 
-function ThemeToggle() {
-  const toggleTheme = () => {
-    const current = getTheme();
-    setTheme(current === "dark" ? "light" : "dark");
-  };
+const Button = styled.button`
+  padding: 1rem;
+  background: blue;
+  color: white;
+`;
 
-  return <button onClick={toggleTheme}>Toggle Theme</button>;
-}
+// 2. What gets generated:
+import { createElement } from "react";
+import { m } from "@alex.radulescu/styled-static/runtime";
+import "@alex.radulescu/styled-static:abc123-0.css";
 
-function ThemeSelector() {
-  return (
-    <select onChange={(e) => setTheme(e.target.value)}>
-      <option value="light">Light</option>
-      <option value="dark">Dark</option>
-      <option value="pokemon">Pokemon</option>
-      <option value="star-trek">Star Trek</option>
-    </select>
-  );
-}
+const Button = Object.assign(
+  (p) => createElement("button", {...p, className: m("ss-abc123", p.className)}),
+  { className: "ss-abc123" }
+);
 ```
 
-### System Preference Detection
+The CSS is completely removed from your JavaScript bundle and extracted to a virtual CSS module. The component becomes an inline function with a static `.className` property for composition.
 
-Combine `useSystemPreference` with CSS for automatic system theme detection:
+### Virtual CSS Modules
 
-```tsx
-const GlobalStyle = createGlobalStyle`
-  :root {
-    --color-bg: #ffffff;
-    --color-text: #1a1a1a;
-  }
-  
-  /* Automatic system preference (when no explicit theme set) */
-  @media (prefers-color-scheme: dark) {
-    :root:not([data-theme]) {
-      --color-bg: #0f172a;
-      --color-text: #f1f5f9;
-    }
-  }
-  
-  /* Explicit theme overrides */
-  [data-theme="light"] { --color-bg: #ffffff; --color-text: #1a1a1a; }
-  [data-theme="dark"] { --color-bg: #0f172a; --color-text: #f1f5f9; }
-`;
+Each styled component gets its own virtual CSS module with a unique ID like `styled-static:abc123-0.css`. This approach enables:
 
-// Initialize with system preference detection
-initTheme({ useSystemPreference: true });
+- ✅ **Deduplication** - CSS is optimized by Vite's pipeline
+- ✅ **Code splitting** - CSS loads only with the components that use it
+- ✅ **Hot Module Replacement** - Changes to styles trigger instant HMR
+- ✅ **Production optimization** - CSS can be extracted to a single file
+
+```css
+/* Virtual module: styled-static:abc123-0.css */
+.ss-abc123 {
+  padding: 1rem;
+  background: blue;
+  color: white;
+}
 ```
 
-### API Reference
+### Minimal Runtime
 
-| Function                              | Description                                                                          |
-| ------------------------------------- | ------------------------------------------------------------------------------------ |
-| `getTheme(attribute?)`                | Get current theme from `data-theme` attribute. Returns `'light'` as default.         |
-| `setTheme(theme, persist?, options?)` | Set theme on document. Persists to localStorage by default.                          |
-| `initTheme(options?)`                 | Initialize theme on page load. Priority: localStorage → system preference → default. |
-| `onSystemThemeChange(callback)`       | Subscribe to OS theme changes. Returns unsubscribe function.                         |
+The runtime is extremely small because components are generated inline at build time. The only runtime code is a className merge helper:
 
-#### initTheme Options
+| Module           | Minified | Brotli |
+| ---------------- | -------- | ------ |
+| runtime/index.js | **45 B** | 50 B   |
 
-```ts
-initTheme({
-  defaultTheme: "light", // Default theme if no stored preference
-  storageKey: "theme", // localStorage key (default: 'theme')
-  useSystemPreference: false, // Detect OS dark/light preference
-  attribute: "data-theme", // Attribute to set on documentElement
-});
+This is a **98% reduction** from traditional CSS-in-JS libraries.
+
+```tsx
+// The ENTIRE runtime - just className merging
+export const m = (base, user) => user ? `${base} ${user}` : base;
 ```
 
----
+Everything else is generated at build time as inline components.
 
-## How It Works
+### Zero-Runtime Features
 
-styled-static transforms your code at build time:
+Some features have literally zero runtime cost because they're completely replaced at build time:
 
 ```tsx
-// You write:
-const Button = styled.button`
-  padding: 1rem;
-  background: blue;
-`;
+// css helper - zero runtime (just a string)
+const activeClass = css`outline: 2px solid blue;`;
+// Generated: const activeClass = "ss-xyz789";
 
-// Becomes:
-import "styled-static:abc123-0.css";
-const Button = __styled("button", "ss-def456", "Button");
+// Global styles - zero runtime (just CSS import)
+const GlobalStyles = createGlobalStyle`* { box-sizing: border-box; }`;
+// Generated: const GlobalStyles = () => null;
 
-// CSS extracted to static file:
-.ss-def456 {
-  padding: 1rem;
-  background: blue;
-}
+// withComponent - zero runtime (build-time transformation)
+const LinkButton = withComponent(Link, Button);
+// Generated: Object.assign((p) => createElement(Link, {...p, className: m(Button.className, p.className)}), { className: Button.className })
 ```
 
 ---
@@ -874,67 +724,53 @@ const Button = styled.button`...`;
 // ✅ Type-safe: button props are available
 <Button type="submit" disabled>Submit</Button>
 
-// ✅ Type-safe: as prop changes available props
-<Button as="a" href="/link">Link</Button>
+// ✅ Type-safe: withComponent infers props from target component
+const LinkButton = withComponent(Link, Button);
+<LinkButton to="/path">Link</LinkButton>
 
-// ✅ Transient props are typed
-<Button $primary={true}>Primary</Button>
+// ✅ Type-safe: .className is always string
+const classes = Button.className; // string
 ```
 
 ---
 
-## Limitations
-
-- **No runtime interpolation** - CSS values must be static (use CSS variables for dynamic values)
-- **React 19+ only** - Uses automatic ref forwarding
-- **Vite only** - Built specifically for Vite's plugin system
-
----
-
 ## Zero Dependencies
 
-The plugin has **ZERO** direct dependencies! 🎉
-
-It relies on:
+Zero runtime dependencies. Uses native CSS nesting (Chrome 112+, Safari 16.5+, Firefox 117+) and Vite's CSS pipeline. See [Installation](#installation) for optional Lightning CSS integration.
 
-- **Native CSS nesting** - Supported in all browsers that support React 19 (Chrome 112+, Safari 16.5+, Firefox 117+, Edge 112+)
-- **Vite's CSS pipeline** - Handles the virtual CSS modules
-
-### Optional: Lightning CSS
+---
 
-For faster CSS processing and automatic vendor prefixes, install Lightning CSS:
+## Comparison
 
-```bash
-npm install lightningcss
-```
+**Legend:** ✓ Yes | ◐ Partial | ✗ No
 
-Then enable in your vite.config.ts:
+| | styled-static | Emotion | Linaria | [Restyle](https://restyle.dev) | Panda CSS |
+|-|---------------|---------|---------|--------|-----------|
+| Runtime | **~50 B** | ~11 KB | ~1.5 KB | ~2.2 KB | 0 B |
+| Dependencies | 0 | 5+ | 10+ | 0 | 5+ |
+| React | 19+ | 16+ | 16+ | 19+ | 16+ |
+| Bundler | Vite | Any | Many | Any | Any |
+| `styled.el` | ✓ | ✓ | ✓ | ✓ | ◐ |
+| `styled(Comp)` | ✓ | ✓ | ✓ | ✓ | ◐ |
+| Variants | ✓ | ◐ | ◐ | ◐ | ✓ |
+| `css` helper | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `css` inline prop | ✗ | ✓ | ✗ | ✓ | ✓ |
+| Runtime interpolation | ✗ | ✓ | ✗ | ✓ | ✗ |
+| `.className` access | ✓ | ✗ | ✗ | ✗ | ✗ |
 
-```ts
-export default defineConfig({
-  css: { transformer: "lightningcss" },
-  plugins: [styledStatic(), react()],
-});
-```
+**When to choose:** styled-static for familiar DX + zero deps + React 19/Vite. Emotion for runtime interpolation + ThemeProvider. Linaria for multi-bundler zero-runtime. [Restyle](https://restyle.dev) for `css` prop + Server Components. Panda for atomic CSS + design tokens.
 
 ---
 
-## Comparison
+## VS Code Support
 
-| Feature               | styled-static | styled-components | Emotion | Linaria |
-| --------------------- | ------------- | ----------------- | ------- | ------- |
-| Zero Runtime          | ✅            | ❌                | ❌      | ✅      |
-| Runtime Interpolation | ❌            | ✅                | ✅      | ❌      |
-| `as` prop             | ✅            | ✅                | ✅      | ❌      |
-| Component Extension   | ✅            | ✅                | ✅      | ✅      |
-| Bundle Size           | ~300B         | ~12KB             | ~11KB   | ~0B     |
-| Direct Dependencies   | 0             | 7                 | 5       | 10+     |
+For syntax highlighting in template literals, install the [vscode-styled-components](https://marketplace.visualstudio.com/items?itemName=styled-components.vscode-styled-components) extension.
 
 ---
 
-## VS Code Support
+## Inspiration
 
-For syntax highlighting in template literals, install the [vscode-styled-components](https://marketplace.visualstudio.com/items?itemName=styled-components.vscode-styled-components) extension.
+We take inspiration from the greats before us: [Emotion](https://emotion.sh), [styled-components](https://styled-components.com), [Linaria](https://linaria.dev), [Panda CSS](https://panda-css.com), [Pigment CSS](https://github.com/mui/pigment-css), [Stitches](https://stitches.dev), [Ecsstatic](https://github.com/danielroe/ecsstatic), [Restyle](https://restyle.dev), [goober](https://goober.rocks). Thanks to each and every one for ideas and inspiration.
 
 ---