@tenphi/tasty 0.0.0-snapshot.fafcbfe → 0.0.0-snapshot.fdb16ea

package/docs/comparison.md

@@ -0,0 +1,448 @@
+# Comparison
+
+Use this guide when you are deciding whether Tasty is the right tool. If you have already decided to adopt it and need rollout guidance, use the [Adoption Guide](adoption.md) instead.
+
+Tasty is CSS-in-JS for React design systems. It is built for the point where reusable components have enough intersecting states, variants, themes, and extension rules that ordinary selector competition becomes hard to reason about.
+
+Its distinctive guarantee is narrow and concrete: each property’s state map compiles into selectors that cannot compete, so one declared branch wins regardless of CSS source order.
+
+That does not require a big upfront configuration step. Tasty's built-in units and normal CSS color values work out of the box, and `okhsl(...)` is available immediately as the recommended path for color authoring. The extra setup comes later if a team wants shared tokens, aliases, recipes, or stricter conventions.
+
+Most styling tools focus on one of these layers:
+
+- direct app styling
+- component-level styling
+- typed CSS authoring
+- utility composition
+- atomic CSS generation
+
+For design-system teams, that state model can sit alongside tokens, typed style props, recipes, custom units, and sub-element rules. Tasty can therefore define the styling language exposed by shared components, not just another syntax for writing CSS.
+
+That is why syntax-level comparisons are often shallow. The more meaningful comparison is about:
+
+- **which layer** a tool is designed for
+- **who owns the authoring language**
+- **how state conflicts are resolved**
+- **what kind of predictability** the tool actually guarantees
+
+---
+
+## High-level positioning
+
+| System                                  | Best described as                        | Main authoring model                                                             | Conflict model                                                   | RSC / zero-JS SSG                             | Best fit                                                      |
+| --------------------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------- |
+| **Tasty**                               | CSS-in-JS for React design systems       | CSS-like objects with state maps, tokens, recipes, style props, and sub-elements | **Mutually exclusive selector resolution** for stateful styles   | Yes — hook-free, server components by default | Teams building long-lived shared component APIs               |
+| **Tailwind CSS**                        | Utility-first styling framework          | Utility classes in markup                                                        | Utility composition, variants, and framework-controlled ordering | Yes — no JS runtime                           | Product teams optimizing for speed and direct authoring       |
+| **Panda CSS**                           | Typed styling engine with atomic output  | Typed style objects, recipes, generated primitives, style props                  | Atomic CSS with static analysis                                  | Yes — build-time extraction                   | Teams wanting a DS-friendly engine with typed primitives      |
+| **vanilla-extract**                     | Zero-runtime TS-native stylesheet system | `.css.ts` files, theme contracts, style composition                              | Standard CSS semantics                                           | Yes — build-time extraction                   | Teams wanting static CSS and low-level control                |
+| **StyleX**                              | Compiler-based atomic styling system     | JS authoring with compiler-generated atomic CSS                                  | Compiler-controlled atomic composition                           | Yes — compiler-extracted                      | Large app teams wanting optimized, predictable atomic styling |
+| **Stitches** (deprecated) **/ Emotion** | Component-first CSS-in-JS                | Styled components, `css()` APIs, object/string styles                            | Composition within CSS-in-JS rules                               | No — requires `'use client'`                  | Teams optimizing for component DX and flexible styling        |
+
+---
+
+## What makes Tasty different
+
+Tasty is built around a stronger goal than generic "predictable styling."
+
+In many systems, predictability means:
+
+- the compiler controls ordering
+- class names do not accidentally collide
+- specificity is reduced or normalized
+- atomic rules compose in a stable way
+
+Those are useful guarantees, but they are not the same as Tasty's main idea.
+
+Tasty focuses on **stateful style resolution**. Instead of relying on ordinary cascade competition between matching rules, it compiles style logic into **mutually exclusive selectors**. For a given property and state combination, the system ensures that exactly one branch is eligible to win.
+
+This is especially relevant for components with intersecting states such as:
+
+- hover
+- focus
+- pressed
+- disabled
+- selected
+- theme variants
+- responsive conditions
+- parent or root-driven conditions
+
+Here is a minimal example. Two CSS rules for a button's background — one for `:hover`, one for `[disabled]`:
+
+```css
+.btn:hover {
+  background: dodgerblue;
+}
+.btn[disabled] {
+  background: gray;
+}
+```
+
+When the button is both hovered **and** disabled, both selectors match with equal specificity. The last rule in source order wins. Swap the two lines and the visual behavior silently reverses — a hovered disabled button turns blue instead of gray.
+
+In Tasty, the same intent is declared as a state map:
+
+```tsx
+fill: {
+  '': '#primary',
+  ':hover': '#primary-hover',
+  '[disabled]': '#surface',
+}
+```
+
+Because `[disabled]` is declared later, it has higher priority. Tasty excludes disabled buttons from the hover selector, so exactly one background rule matches. The outcome is defined by the state map, not by which CSS rule comes last.
+
+That makes Tasty less of a "better way to write CSS objects" and more of a **state-aware style compiler for design systems**.
+
+Beyond state resolution, Tasty also provides several structural capabilities that reinforce the design-system layer:
+
+- **CSS properties as typed React props** — `styleProps` lets a component expose selected style properties as normal props (`<Button placeSelf="end">`), including state maps for responsive values. This keeps layout and composition controls inside a governed component API instead of pushing teams back to ad hoc styling escapes.
+- **Sub-element styling** — Compound components declare inner parts via capitalized keys in `styles` and `data-element` attributes. States, tokens, and recipes apply across the entire element tree from a single definition. See [React API — Sub-element Styling](react-api.md#sub-element-styling).
+- **Auto-inferred `@property`** — When a custom property is assigned a concrete value, Tasty infers the CSS `@property` syntax and registers it automatically, enabling smooth transitions on custom properties without manual declarations.
+- **AI-friendly style definitions** — Style definitions are declarative, self-contained, and structurally consistent. AI tools can read, refactor, and generate Tasty styles as confidently as a human — no hidden cascade logic or implicit ordering to second-guess.
+- **Companion ecosystem** — An [ESLint plugin](https://github.com/tenphi/eslint-plugin-tasty) with 27 lint rules, a [VS Code extension](https://github.com/tenphi/tasty-vscode-extension) for syntax highlighting, and [Glaze](https://github.com/tenphi/glaze) for OKHSL color theme generation with automatic WCAG contrast solving.
+
+---
+
+## Comparison by system
+
+### Tasty vs Tailwind CSS
+
+Tailwind is centered on **direct authoring in markup**.
+
+Its strength is speed: developers compose utilities directly where they use them, with responsive and state modifiers layered on top. This works extremely well for app teams that want a shared utility vocabulary with minimal ceremony.
+
+Tasty solves a different problem.
+
+Tasty is more appropriate when styling should be exposed through a **design-system-owned API** rather than through raw utility composition. You can start using Tasty immediately with its built-in DSL, but it becomes especially compelling when a team wants to define:
+
+- approved style props
+- semantic tokens
+- custom units
+- recipes
+- state semantics
+- sub-element rules
+- constrained component-facing styling APIs
+
+So this is not mainly a comparison of syntax. It is a comparison of **governance models**:
+
+- Tailwind: developers author directly with framework vocabulary
+- Tasty: design-system authors define the vocabulary product teams consume
+
+Tailwind is a stronger fit for fast product styling with framework-owned vocabulary. Tasty is a stronger fit when styling should be exposed through a design-system-owned API and state resolution needs to stay deterministic as the component model grows.
+
+To make this concrete, consider a button with `hover`, `disabled`, and `theme=danger` states.
+
+**Plain CSS** — you need a selector for every intersection, and equal-specificity rules depend on source order:
+
+```css
+.btn {
+  background: var(--primary);
+  color: white;
+  cursor: pointer;
+}
+.btn:hover {
+  background: var(--primary-hover);
+}
+.btn:active {
+  background: var(--primary-pressed);
+}
+.btn[disabled] {
+  background: var(--surface);
+  color: var(--text-40);
+  cursor: not-allowed;
+}
+
+/* theme=danger overrides — must repeat disabled/hover/active */
+.btn[data-theme='danger'] {
+  background: var(--danger);
+}
+.btn[data-theme='danger']:hover {
+  background: var(--danger-hover);
+}
+.btn[data-theme='danger']:active {
+  background: var(--danger-pressed);
+}
+.btn[data-theme='danger'][disabled] {
+  background: var(--surface);
+}
+
+/* Bug: .btn:hover and .btn[disabled] have the same specificity.
+   A hovered disabled button gets :hover styles — unless source order saves you. */
+```
+
+Every new state doubles the selector count. Miss one intersection and you ship a visual bug.
+
+**Tailwind** — state intersections move into conditional className logic:
+
+```tsx
+<button className={cn(
+  'bg-primary text-white cursor-pointer',
+  'hover:bg-primary-hover active:bg-primary-pressed',
+  'disabled:bg-surface disabled:text-text-40 disabled:cursor-not-allowed',
+  theme === 'danger' && 'bg-danger hover:bg-danger-hover active:bg-danger-pressed',
+  theme === 'danger' && disabled && '!bg-surface',
+)}>
+```
+
+The `theme` branch is runtime JS, not CSS. Intersections like `disabled + hover` need manual `!important` or extra utilities to override correctly.
+
+**Tasty** — each property declares all its states in one map. The engine generates mutually exclusive selectors:
+
+```tsx
+const Button = tasty({
+  as: 'button',
+  styles: {
+    fill: {
+      '': '#primary',
+      ':hover': '#primary-hover',
+      ':active': '#primary-pressed',
+      disabled: '#surface',
+      'theme=danger': '#danger',
+      'theme=danger & :hover': '#danger-hover',
+      'theme=danger & :active': '#danger-pressed',
+    },
+    color: {
+      '': '#on-primary',
+      disabled: '#text.40',
+    },
+    cursor: {
+      '': 'pointer',
+      disabled: 'not-allowed',
+    },
+  },
+});
+```
+
+`disabled` always wins over `:hover` because Tasty emits negation selectors — no source-order dependence, no manual intersection management, no `!important`.
+
+---
+
+### Tasty vs Panda CSS
+
+Panda is one of the closest comparisons.
+
+Like Tasty, Panda sits closer to the design-system layer than many other tools. It supports typed style authoring, recipes, generated primitives, and a DS-friendly workflow. It is much more than a basic styling helper.
+
+The difference is where each system puts its core idea.
+
+Panda is centered on **typed atomic generation** and static analysis. It gives teams a structured, modern, design-system-friendly engine with a strong build-time story.
+
+Tasty is more centered on:
+
+- a custom DSL
+- state mapping
+- mutually exclusive resolution
+- defining a team-specific styling language
+
+So while both can support serious design-system work, they do not optimize for exactly the same thing:
+
+- **Panda** is closer to a typed styling engine with strong DS ergonomics
+- **Tasty** is closer to a design-system style compiler with explicit state semantics
+
+If a team mostly wants typed primitives, recipes, and extracted CSS, Panda may feel more straightforward.
+
+If a team wants to define a more opinionated styling language with stronger control over state logic and rule exclusivity, Tasty has a more specialized angle.
+
+---
+
+### Tasty vs vanilla-extract
+
+vanilla-extract is a lower-level foundation.
+
+It gives teams a zero-runtime TypeScript-native way to generate CSS, plus strong theming primitives and the ability to build architecture on top. It is excellent when a team wants maximum control over structure while staying close to normal CSS semantics.
+
+That last point matters.
+
+With vanilla-extract, styles are still fundamentally governed by **standard CSS behavior**. Ordering, layering, and media-query structure still matter in the usual CSS sense. That is not a flaw; it is simply a different abstraction level.
+
+Tasty is more opinionated.
+
+It behaves less like "TypeScript that outputs CSS" and more like a **state-aware style compiler**. It is designed to encode higher-level styling semantics rather than only expose CSS primitives in typed form.
+
+This also makes Tasty's delivery model notable:
+
+- `tasty()` components are hook-free and work as React Server Components. In server-only contexts, they produce HTML + CSS with zero Tasty styling runtime in the browser while retaining the full React feature set. Astro without islands is the concrete integration; server-only Next.js RSC uses the same architecture.
+- `tastyStatic()` with the Babel plugin produces static class-name objects via build-time extraction, with no React dependency — the output works with any JavaScript framework.
+
+React component features like `styleProps`, sub-element components, and dynamic variants are available in the `tasty()` path whether it renders on the server or in the browser. The `tastyStatic()` path is framework-agnostic but limited to the DSL, tokens, and state logic.
+
+So the tradeoff is roughly:
+
+- **vanilla-extract**: lower-level, static, explicit, architecture left to the team
+- **Tasty**: more opinionated, more state-aware, more language-defining
+
+---
+
+### Tasty vs StyleX
+
+This comparison needs extra precision, because both systems care about predictability, but not in the same way.
+
+StyleX is a compiler-based atomic system with strong guarantees around consistency and composition. Its model is designed to avoid many classic CSS pitfalls such as accidental rule collisions and specificity-driven unpredictability.
+
+That is real value.
+
+But it is still a different kind of guarantee from Tasty's.
+
+StyleX predictability comes from:
+
+- atomic decomposition
+- compiler control
+- constrained composition
+- normalized style behavior
+
+Tasty's differentiator is stronger in a specific area:
+
+- **stateful per-property resolution**
+- **mutually exclusive selectors**
+- **conflict avoidance by construction**, not only by atomic normalization
+
+So "collision-free atomic CSS" should not be treated as equivalent to Tasty's approach.
+
+A better framing is:
+
+- **StyleX** provides compiler-controlled atomic predictability
+- **Tasty** provides mutually exclusive selector resolution for stateful component styling
+
+That makes Tasty especially interesting when the hardest problem is not just style composition, but **complex intersecting component states**.
+
+---
+
+### Tasty vs Stitches (deprecated) / Emotion
+
+Stitches and Emotion are component-first styling systems. (Note: Stitches has been archived and is no longer maintained. It is included here because it remains widely referenced in comparisons.)
+
+They optimize for developer experience, flexible composition, reusable styled primitives, and ergonomic component authoring. For many teams, that is exactly the right abstraction level.
+
+Tasty targets a different question.
+
+It is less focused on "how do I style this component ergonomically right now?" and more focused on:
+
+- what styling language should this design system expose?
+- how should states be modeled?
+- what should be allowed or constrained?
+- how do we keep style behavior deterministic as the system grows?
+
+So while Stitches and Emotion are strong tools for building components, Tasty is more naturally positioned as the **styling engine underneath a design system’s component API**.
+
+That makes it narrower in audience, but deeper in architectural ambition.
+
+There is also a fundamental architectural difference: Emotion and styled-components rely on React context and hooks internally, which means they require `'use client'` in modern React and cannot run as React Server Components. Tasty's style functions and `tasty()` components are hook-free, so they work as server components by default and ship no Tasty styling runtime in server-only contexts. This is not a minor compatibility detail — it means Tasty-based components stay as server components until _your_ code needs interactivity, while Emotion and styled-components force the client boundary at the styling layer.
+
+For teams evaluating runtime styling at scale, Tasty also documents its runtime benchmarks and caching model in the main [README](../README.md#performance). That matters, but it is still secondary to the core question of whether you want Tasty's deterministic selector model.
+
+---
+
+## Where styles are computed
+
+Tasty is not limited to one execution model.
+
+Zero-runtime delivery is an outcome, not a synonym for `tastyStatic()`. `tasty()` computes styles during React rendering, but that rendering can happen only on the server. In that case it produces HTML + CSS and ships **zero Tasty styling runtime** to the browser. The full feature set — `styleProps`, sub-elements, variants, state maps — remains available. Astro's `tastyIntegration({ islands: false })` is the explicit setup for this path. Server-only Next.js RSC follows the same architecture; verify the generated output for the target deployment.
+
+Client JavaScript only enters the picture when a component needs React interactivity (state, effects, event handlers) — and that is the consuming component's decision, never Tasty's. Tasty never forces the `'use client'` boundary.
+
+`tastyStatic()` with the Babel plugin reaches zero-runtime delivery differently: CSS is extracted **during the build**, without React. The output is framework-agnostic — any JavaScript framework can consume the resulting class names and CSS. This makes Tasty usable as the compiler layer underneath a design-system implementation, even outside the React ecosystem.
+
+The tradeoff is that some capabilities — `styleProps`, sub-element components (`<Card.Title>`), dynamic variants — are tied to the `tasty()` path. The `tastyStatic()` path is best understood as extraction and compilation of the DSL, tokens, and state logic without a React dependency.
+
+This gives Tasty two zero-runtime paths:
+
+- server-only `tasty()` for the full React component API, with CSS generated during server or static rendering
+- `tastyStatic()` as a build-time compiler whose output works with any framework, including non-React ones
+
+---
+
+## Comparison by abstraction level
+
+Another useful way to think about the ecosystem is by abstraction level.
+
+### Direct styling tools
+
+These are optimized for styling product code directly.
+
+Examples:
+
+- Tailwind CSS
+- Emotion (requires `'use client'` — not RSC-compatible)
+- Stitches (deprecated, requires `'use client'`)
+
+### Typed styling engines
+
+These are optimized for generating CSS with stronger structure and tooling.
+
+Examples:
+
+- Panda CSS
+- vanilla-extract
+- StyleX
+
+### Design-system language engines
+
+These are optimized for helping a team define its own styling grammar and semantics.
+
+Tasty belongs most naturally here.
+
+That is why generic "feature matrix" comparisons often miss the point. Tasty is not only trying to style elements. It is trying to help define **how a design system talks about styling**.
+
+---
+
+## When Tasty is a strong fit
+
+Tasty makes the most sense when:
+
+- a real design system exists or is being built
+- a shared component API is emerging even if the design system is still lightweight
+- styling should be governed through a central platform team
+- component state logic is complex
+- the team wants a design-system-owned styling language instead of raw CSS-shaped authoring
+- tokens, recipes, and sub-elements should be first-class
+- deterministic state resolution matters more than minimum abstraction overhead
+- the styling engine may need to work as either a runtime tool or a build-time compiler
+
+---
+
+## When another tool may be a better fit
+
+A different tool may be more appropriate when:
+
+- the main goal is styling app code directly with minimal setup and without defining shared styling conventions
+- the team prefers a shared framework vocabulary over a custom design-system language
+- the complexity of intersecting states is low
+- low ceremony matters more than central governance
+- the team wants static CSS primitives without a more opinionated state model
+- component-level DX is the primary optimization target
+
+---
+
+## Summary
+
+Tasty is not best compared as "another CSS framework."
+
+Its more meaningful comparison point is this:
+
+> Tasty is a styling engine for building a design-system-defined authoring language, with a particular focus on explicit state semantics and mutually exclusive selector resolution.
+
+That puts it in a different category from:
+
+- utility-first tools that optimize for direct authoring
+- component-first CSS-in-JS libraries that optimize for DX
+- typed static CSS systems that expose lower-level primitives
+- atomic compilers that focus on normalized composition
+
+Those systems are all useful, but they optimize for different layers.
+
+Tasty is most compelling when the problem is not just "how do we write styles," but:
+
+> "How do we define a scalable, deterministic styling model for the design system itself?"
+
+---
+
+## Learn more
+
+- [README](../README.md) — overview, quick start, and feature highlights
+- [Style DSL](dsl.md) — state maps, tokens, units, extending semantics, keyframes, @property
+- [React API](react-api.md) — `tasty()` factory, component props, variants, sub-elements, style functions
+- [Style Properties](styles.md) — complete reference for all enhanced style properties
+- [Configuration](configuration.md) — tokens, recipes, custom units, style handlers, and TypeScript extensions
+- [Build-Time Extraction (`tastyStatic`)](tasty-static.md) — static styling with the Babel plugin
+- [Adoption Guide](adoption.md) — where Tasty sits in the stack, incremental adoption, and what changes for product engineers
+- [Server-Side Rendering](ssr.md) — SSR setup for Next.js, Astro, and generic frameworks