@tenphi/tasty 0.0.0-snapshot.002b1b3

package/dist/zero/next.d.ts

@@ -0,0 +1,86 @@
+import { TastyZeroConfig } from "./babel.js";
+
+//#region src/zero/next.d.ts
+interface WebpackConfigContext {
+  isServer: boolean;
+  dev: boolean;
+  buildId: string;
+  dir: string;
+}
+interface TurbopackLoaderItem {
+  loader: string;
+  options?: Record<string, unknown>;
+}
+interface TurbopackRuleConfig {
+  loaders: (string | TurbopackLoaderItem)[];
+  as?: string;
+  condition?: unknown;
+}
+interface TurbopackConfig {
+  rules?: Record<string, TurbopackRuleConfig | TurbopackRuleConfig[]>;
+  [key: string]: unknown;
+}
+interface NextConfig {
+  webpack?: (config: any, context: WebpackConfigContext) => any;
+  turbopack?: TurbopackConfig;
+  [key: string]: unknown;
+}
+interface TastyZeroNextOptions {
+  /**
+   * Output path for CSS relative to project root.
+   * @default 'public/tasty.css'
+   */
+  output?: string;
+  /**
+   * Whether to enable the plugin.
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * Tasty configuration for build-time processing.
+   * For static configs that don't change during dev.
+   *
+   * For configs that depend on theme files, use `configFile` instead.
+   */
+  config?: TastyZeroConfig;
+  /**
+   * Path to a TypeScript/JavaScript module that exports the tasty zero config
+   * as its default export. The module is re-evaluated on each
+   * compilation, enabling hot reload when the file (or its imports) change.
+   *
+   * @example './app/tasty-zero.config.ts'
+   */
+  configFile?: string;
+  /**
+   * Extra file paths (relative to project root) that the config depends on.
+   * When any of these files change, the Babel cache is invalidated and
+   * the config is re-evaluated.
+   *
+   * The `configFile` itself is always tracked automatically.
+   * Use this for transitive dependencies that aren't directly imported
+   * by the config file, or when using `config` instead of `configFile`.
+   *
+   * @example ['./app/theme.ts']
+   */
+  configDeps?: string[];
+  /**
+   * Output mode for extracted CSS.
+   *
+   * - `'file'` (default): CSS is written to a single output file.
+   * - `'inject'`: CSS is embedded inline in JS and injected at runtime.
+   *   No CSS file is written. Best for reusable components and extensions.
+   *
+   * When `mode` is `'inject'`, `output` is ignored.
+   *
+   * @default 'file'
+   */
+  mode?: 'file' | 'inject';
+}
+/**
+ * Next.js configuration wrapper for tasty-zero.
+ * Configures both webpack and Turbopack bundlers automatically.
+ */
+declare function withTastyZero(options?: TastyZeroNextOptions): (nextConfig?: NextConfig) => NextConfig;
+//#endregion
+export { TastyZeroNextOptions, withTastyZero };
+//# sourceMappingURL=next.d.ts.map

package/dist/zero/next.js

@@ -0,0 +1,143 @@
+import * as path from "path";
+import { createJiti } from "jiti";
+import { createRequire } from "module";
+import { fileURLToPath } from "url";
+//#region src/zero/next.ts
+/**
+* Next.js configuration wrapper for tasty-zero.
+*
+* Supports both webpack and Turbopack bundlers:
+* - **webpack**: Injects a babel-loader rule with the tasty-zero Babel plugin
+*   via `webpack()` config hook. Config is passed as a jiti factory function.
+* - **Turbopack**: Adds a `turbopack.rules` entry with babel-loader and
+*   JSON-serializable options (`configFile` path instead of a function).
+*   The Babel plugin loads the config internally via jiti.
+*
+* The generated CSS is injected automatically — `@tenphi/tasty/static`
+* imports are replaced with an import of the output CSS file at build time.
+* No manual CSS import in layout files is needed.
+*
+* @example
+* ```javascript
+* // next.config.js
+* const { withTastyZero } = require('@tenphi/tasty/next');
+*
+* module.exports = withTastyZero({
+*   output: 'public/tasty.css',
+*   configFile: './app/tasty-zero.config.ts',
+* })({
+*   // your Next.js config
+* });
+* ```
+*/
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+/**
+* Next.js configuration wrapper for tasty-zero.
+* Configures both webpack and Turbopack bundlers automatically.
+*/
+function withTastyZero(options = {}) {
+	const { output = "public/tasty.css", enabled = true, config: tastyConfig, configFile, configDeps = [], mode } = options;
+	return (nextConfig = {}) => {
+		if (!enabled) return nextConfig;
+		const projectDir = process.cwd();
+		const absoluteOutput = path.resolve(projectDir, output);
+		const babelPluginPath = path.resolve(__dirname, "babel.js");
+		const absoluteConfigFile = configFile ? path.resolve(projectDir, configFile) : void 0;
+		const allDeps = [...absoluteConfigFile ? [absoluteConfigFile] : [], ...configDeps.map((dep) => path.resolve(projectDir, dep))];
+		const turbopackBabelOptions = {
+			babelrc: false,
+			configFile: false,
+			parserOpts: { plugins: [
+				"typescript",
+				"jsx",
+				"decorators-legacy"
+			] },
+			plugins: [[babelPluginPath, {
+				output: absoluteOutput,
+				injectImport: true,
+				...mode ? { mode } : {},
+				...absoluteConfigFile ? { configFile: absoluteConfigFile } : tastyConfig ? { config: tastyConfig } : {},
+				...allDeps.length > 0 ? { configDeps: allDeps } : {}
+			}]]
+		};
+		const existingTurbopack = nextConfig.turbopack || {};
+		const existingRules = existingTurbopack.rules || {};
+		const existingExperimental = nextConfig.experimental || {};
+		return {
+			...nextConfig,
+			experimental: {
+				...existingExperimental,
+				turbopackUseBuiltinBabel: true
+			},
+			turbopack: {
+				...existingTurbopack,
+				rules: {
+					...existingRules,
+					"*.{ts,tsx,js,jsx}": {
+						condition: { not: "foreign" },
+						loaders: [{
+							loader: "babel-loader",
+							options: turbopackBabelOptions
+						}]
+					}
+				}
+			},
+			webpack(config, context) {
+				const { dir } = context;
+				const wpProjectDir = dir || projectDir;
+				const wpAbsoluteOutput = path.resolve(wpProjectDir, output);
+				const projectRequire = createRequire(path.resolve(wpProjectDir, "package.json"));
+				const wpAbsoluteConfigFile = configFile ? path.resolve(wpProjectDir, configFile) : void 0;
+				const wpAllDeps = [...wpAbsoluteConfigFile ? [wpAbsoluteConfigFile] : [], ...configDeps.map((dep) => path.resolve(wpProjectDir, dep))];
+				const babelPluginOptions = {
+					output: wpAbsoluteOutput,
+					injectImport: true,
+					...mode ? { mode } : {}
+				};
+				if (wpAbsoluteConfigFile) {
+					const jiti = createJiti(wpProjectDir, { moduleCache: false });
+					babelPluginOptions.config = () => {
+						return jiti(wpAbsoluteConfigFile);
+					};
+				} else if (tastyConfig) babelPluginOptions.config = tastyConfig;
+				if (wpAllDeps.length > 0) babelPluginOptions.configDeps = wpAllDeps;
+				const babelPluginConfig = [babelPluginPath, babelPluginOptions];
+				const existingRule = config.module?.rules?.find((rule) => rule.use?.loader === "babel-loader" || rule.use?.some?.((u) => u.loader === "babel-loader"));
+				if (existingRule) {
+					const babelUse = Array.isArray(existingRule.use) ? existingRule.use.find((u) => u.loader === "babel-loader") : existingRule.use;
+					if (babelUse?.options) {
+						babelUse.options.plugins = babelUse.options.plugins || [];
+						babelUse.options.plugins.push(babelPluginConfig);
+					}
+				} else {
+					config.module = config.module || {};
+					config.module.rules = config.module.rules || [];
+					config.module.rules.push({
+						test: /\.(tsx?|jsx?)$/,
+						exclude: /node_modules/,
+						use: [{
+							loader: projectRequire.resolve("babel-loader"),
+							options: {
+								babelrc: false,
+								configFile: false,
+								parserOpts: { plugins: [
+									"typescript",
+									"jsx",
+									"decorators-legacy"
+								] },
+								plugins: [babelPluginConfig]
+							}
+						}]
+					});
+				}
+				if (typeof nextConfig.webpack === "function") return nextConfig.webpack(config, context);
+				return config;
+			}
+		};
+	};
+}
+//#endregion
+export { withTastyZero };
+
+//# sourceMappingURL=next.js.map

package/dist/zero/next.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"next.js","names":[],"sources":["../../src/zero/next.ts"],"sourcesContent":["/**\n * Next.js configuration wrapper for tasty-zero.\n *\n * Supports both webpack and Turbopack bundlers:\n * - **webpack**: Injects a babel-loader rule with the tasty-zero Babel plugin\n *   via `webpack()` config hook. Config is passed as a jiti factory function.\n * - **Turbopack**: Adds a `turbopack.rules` entry with babel-loader and\n *   JSON-serializable options (`configFile` path instead of a function).\n *   The Babel plugin loads the config internally via jiti.\n *\n * The generated CSS is injected automatically — `@tenphi/tasty/static`\n * imports are replaced with an import of the output CSS file at build time.\n * No manual CSS import in layout files is needed.\n *\n * @example\n * ```javascript\n * // next.config.js\n * const { withTastyZero } = require('@tenphi/tasty/next');\n *\n * module.exports = withTastyZero({\n *   output: 'public/tasty.css',\n *   configFile: './app/tasty-zero.config.ts',\n * })({\n *   // your Next.js config\n * });\n * ```\n */\n\nimport { createRequire } from 'module';\nimport * as path from 'path';\nimport { fileURLToPath } from 'url';\n\nimport { createJiti } from 'jiti';\n\nimport type { TastyZeroBabelOptions, TastyZeroConfig } from './babel';\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = path.dirname(__filename);\n\n// Next.js types (inline to avoid requiring next as a dependency)\ninterface WebpackConfigContext {\n  isServer: boolean;\n  dev: boolean;\n  buildId: string;\n  dir: string;\n}\n\n/* eslint-disable @typescript-eslint/no-explicit-any -- webpack/Next.js config types are complex */\ninterface TurbopackLoaderItem {\n  loader: string;\n  options?: Record<string, unknown>;\n}\n\ninterface TurbopackRuleConfig {\n  loaders: (string | TurbopackLoaderItem)[];\n  as?: string;\n  condition?: unknown;\n}\n\ninterface TurbopackConfig {\n  rules?: Record<string, TurbopackRuleConfig | TurbopackRuleConfig[]>;\n  [key: string]: unknown;\n}\n\ninterface NextConfig {\n  webpack?: (config: any, context: WebpackConfigContext) => any;\n  turbopack?: TurbopackConfig;\n  [key: string]: unknown;\n}\n\nexport interface TastyZeroNextOptions {\n  /**\n   * Output path for CSS relative to project root.\n   * @default 'public/tasty.css'\n   */\n  output?: string;\n\n  /**\n   * Whether to enable the plugin.\n   * @default true\n   */\n  enabled?: boolean;\n\n  /**\n   * Tasty configuration for build-time processing.\n   * For static configs that don't change during dev.\n   *\n   * For configs that depend on theme files, use `configFile` instead.\n   */\n  config?: TastyZeroConfig;\n\n  /**\n   * Path to a TypeScript/JavaScript module that exports the tasty zero config\n   * as its default export. The module is re-evaluated on each\n   * compilation, enabling hot reload when the file (or its imports) change.\n   *\n   * @example './app/tasty-zero.config.ts'\n   */\n  configFile?: string;\n\n  /**\n   * Extra file paths (relative to project root) that the config depends on.\n   * When any of these files change, the Babel cache is invalidated and\n   * the config is re-evaluated.\n   *\n   * The `configFile` itself is always tracked automatically.\n   * Use this for transitive dependencies that aren't directly imported\n   * by the config file, or when using `config` instead of `configFile`.\n   *\n   * @example ['./app/theme.ts']\n   */\n  configDeps?: string[];\n\n  /**\n   * Output mode for extracted CSS.\n   *\n   * - `'file'` (default): CSS is written to a single output file.\n   * - `'inject'`: CSS is embedded inline in JS and injected at runtime.\n   *   No CSS file is written. Best for reusable components and extensions.\n   *\n   * When `mode` is `'inject'`, `output` is ignored.\n   *\n   * @default 'file'\n   */\n  mode?: 'file' | 'inject';\n}\n\n/**\n * Next.js configuration wrapper for tasty-zero.\n * Configures both webpack and Turbopack bundlers automatically.\n */\nexport function withTastyZero(options: TastyZeroNextOptions = {}) {\n  const {\n    output = 'public/tasty.css',\n    enabled = true,\n    config: tastyConfig,\n    configFile,\n    configDeps = [],\n    mode,\n  } = options;\n\n  return (nextConfig: NextConfig = {}): NextConfig => {\n    if (!enabled) {\n      return nextConfig;\n    }\n\n    const projectDir = process.cwd();\n    const absoluteOutput = path.resolve(projectDir, output);\n    const babelPluginPath = path.resolve(__dirname, 'babel.js');\n\n    const absoluteConfigFile = configFile\n      ? path.resolve(projectDir, configFile)\n      : undefined;\n\n    const allDeps = [\n      ...(absoluteConfigFile ? [absoluteConfigFile] : []),\n      ...configDeps.map((dep) => path.resolve(projectDir, dep)),\n    ];\n\n    // --- Turbopack configuration ---\n    // Turbopack loader options must be JSON-serializable (no functions).\n    // The Babel plugin loads config internally via `configFile` path + jiti.\n    const turbopackBabelOptions: Record<string, unknown> = {\n      babelrc: false,\n      configFile: false,\n      parserOpts: {\n        plugins: ['typescript', 'jsx', 'decorators-legacy'],\n      },\n      plugins: [\n        [\n          babelPluginPath,\n          {\n            output: absoluteOutput,\n            injectImport: true,\n            ...(mode ? { mode } : {}),\n            ...(absoluteConfigFile\n              ? { configFile: absoluteConfigFile }\n              : tastyConfig\n                ? { config: tastyConfig }\n                : {}),\n            ...(allDeps.length > 0 ? { configDeps: allDeps } : {}),\n          },\n        ],\n      ],\n    };\n\n    const existingTurbopack = nextConfig.turbopack || {};\n    const existingRules = existingTurbopack.rules || {};\n\n    const existingExperimental =\n      (nextConfig.experimental as Record<string, unknown>) || {};\n\n    return {\n      ...nextConfig,\n\n      experimental: {\n        ...existingExperimental,\n        turbopackUseBuiltinBabel: true,\n      },\n\n      turbopack: {\n        ...existingTurbopack,\n        rules: {\n          ...existingRules,\n          '*.{ts,tsx,js,jsx}': {\n            condition: { not: 'foreign' },\n            loaders: [\n              {\n                loader: 'babel-loader',\n                options: turbopackBabelOptions,\n              },\n            ],\n          },\n        },\n      },\n\n      webpack(config: any, context: WebpackConfigContext) {\n        const { dir } = context;\n\n        const wpProjectDir = dir || projectDir;\n        const wpAbsoluteOutput = path.resolve(wpProjectDir, output);\n        const projectRequire = createRequire(\n          path.resolve(wpProjectDir, 'package.json'),\n        );\n\n        const wpAbsoluteConfigFile = configFile\n          ? path.resolve(wpProjectDir, configFile)\n          : undefined;\n\n        const wpAllDeps = [\n          ...(wpAbsoluteConfigFile ? [wpAbsoluteConfigFile] : []),\n          ...configDeps.map((dep) => path.resolve(wpProjectDir, dep)),\n        ];\n\n        const babelPluginOptions: TastyZeroBabelOptions = {\n          output: wpAbsoluteOutput,\n          injectImport: true,\n          ...(mode ? { mode } : {}),\n        };\n\n        if (wpAbsoluteConfigFile) {\n          const jiti = createJiti(wpProjectDir, {\n            moduleCache: false,\n          });\n\n          babelPluginOptions.config = () => {\n            return jiti(wpAbsoluteConfigFile) as TastyZeroConfig;\n          };\n        } else if (tastyConfig) {\n          babelPluginOptions.config = tastyConfig;\n        }\n\n        if (wpAllDeps.length > 0) {\n          babelPluginOptions.configDeps = wpAllDeps;\n        }\n\n        const babelPluginConfig = [babelPluginPath, babelPluginOptions];\n\n        const existingRule = config.module?.rules?.find(\n          (rule: any) =>\n            rule.use?.loader === 'babel-loader' ||\n            rule.use?.some?.((u: any) => u.loader === 'babel-loader'),\n        );\n\n        if (existingRule) {\n          const babelUse = Array.isArray(existingRule.use)\n            ? existingRule.use.find((u: any) => u.loader === 'babel-loader')\n            : existingRule.use;\n\n          if (babelUse?.options) {\n            babelUse.options.plugins = babelUse.options.plugins || [];\n            babelUse.options.plugins.push(babelPluginConfig);\n          }\n        } else {\n          config.module = config.module || {};\n          config.module.rules = config.module.rules || [];\n          config.module.rules.push({\n            test: /\\.(tsx?|jsx?)$/,\n            exclude: /node_modules/,\n            use: [\n              {\n                loader: projectRequire.resolve('babel-loader'),\n                options: {\n                  babelrc: false,\n                  configFile: false,\n                  parserOpts: {\n                    plugins: ['typescript', 'jsx', 'decorators-legacy'],\n                  },\n                  plugins: [babelPluginConfig],\n                },\n              },\n            ],\n          });\n        }\n\n        if (typeof nextConfig.webpack === 'function') {\n          return nextConfig.webpack(config, context);\n        }\n\n        return config;\n      },\n    };\n  };\n}\n"],"mappings":"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"}

package/docs/README.md

@@ -0,0 +1,31 @@
+# Tasty Docs
+
+Tasty is a styling engine for design systems that turns component state into deterministic CSS by compiling state maps into mutually exclusive selectors. Use this hub to choose the right guide once you know whether you are evaluating the model, adopting it in a design system, or implementing reusable, stateful components day to day.
+
+## Start Here
+
+- **New to Tasty**: [Getting Started](getting-started.md) for installation, the first component, optional shared `configure()`, ESLint, editor tooling, and rendering mode selection.
+- **Learning the component model**: [Methodology](methodology.md) for root + sub-elements, `styleProps`, tokens, extension, and recommended boundaries between `styles`, `style`, and wrappers.
+- **Evaluating the selector model**: [Style rendering pipeline](pipeline.md) for how mutually exclusive selectors make stateful styling deterministic.
+- **Evaluating fit**: [Comparison](comparison.md) for tool-selection context, then [Adoption Guide](adoption.md) for audience fit and rollout strategy inside a design system.
+
+## By Role
+
+- **Application developer using an existing design system**: [Getting Started](getting-started.md), then [React API](react-api.md).
+- **Design-system author**: [Methodology](methodology.md), [Building a Design System](design-system.md), [Configuration](configuration.md), and [Adoption Guide](adoption.md).
+- **Platform or tooling engineer**: [Configuration](configuration.md), [Zero Runtime (tastyStatic)](tasty-static.md), [Server-Side Rendering](ssr.md), and [Debug Utilities](debug.md).
+
+## By Styling Approach
+
+- **React components**: [React API](react-api.md)
+- **Zero-runtime / build-time extraction**: [Zero Runtime (tastyStatic)](tasty-static.md)
+- **Runtime `tasty()` with server collection and hydration**: [Server-Side Rendering](ssr.md)
+
+## By Task
+
+- **Learn the style language**: [Style DSL](dsl.md)
+- **Look up a property handler**: [Style Properties](styles.md)
+- **Define tokens, units, recipes, keyframes, or properties globally**: [Configuration](configuration.md)
+- **Debug generated CSS or cache behavior**: [Debug Utilities](debug.md)
+- **Understand how selector generation works internally**: [Style rendering pipeline](pipeline.md)
+- **Understand runtime injection internals**: [Style Injector](injector.md)

package/docs/adoption.md

@@ -0,0 +1,298 @@
+# Adoption Guide
+
+Tasty is not a drop-in replacement for another styling library. It is a **substrate for building a design-system-defined styling language**: what the comparison guide calls a house styling language. That means adoption usually starts where styling for reusable, stateful components has already become a composition problem, not with an all-at-once rewrite.
+
+This guide is for design-system maintainers and platform engineers evaluating Tasty or introducing it into an existing codebase. Use this document for rollout strategy and adoption sequencing; use the [Comparison guide](comparison.md) when the open question is whether Tasty is the right tool in the first place.
+
+---
+
+## Where Tasty sits in the stack
+
+Tasty is not the surface your product engineers interact with directly. It sits one layer below:
+
+```
+Product code
+  └─ DS components (Button, Card, Layout, ...)
+       └─ Tasty engine (tasty(), configure(), style functions)
+            └─ CSS (mutually exclusive selectors, tokens, custom properties)
+```
+
+**What Tasty owns:**
+- The DSL and value parser (tokens, custom units, auto-calc, color opacity)
+- State compilation (mutually exclusive selectors from state maps)
+- Style injection and deduplication (runtime or build-time)
+- The `tasty()` component factory and hooks API
+
+**What the DS team owns:**
+- Token names and values (colors, spacing, typography)
+- Custom units and their semantics
+- State aliases (`@mobile`, `@dark`, `@compact`)
+- Recipes (reusable style bundles)
+- Which style props each component exposes
+- Sub-element structure for compound components
+- The override and extension rules product teams follow
+
+Two teams using Tasty can end up with very different authoring models. That is by design.
+
+---
+
+## Who should adopt Tasty
+
+**Strong fit:**
+- A design-system or platform team that wants to define a governed styling language
+- Components with complex, intersecting states (hover + disabled + theme + breakpoint)
+- Teams that need deterministic style resolution without cascade/specificity bugs
+- Organizations where styling decisions should be centralized, not distributed
+
+**Not the right fit:**
+- Solo developers building a one-off app with minimal UI structure
+- Teams that want a shared utility vocabulary and direct markup authoring (Tailwind is better here)
+- Projects where low ceremony matters more than central governance
+- Codebases where intersecting state complexity is low
+
+For a detailed comparison with Tailwind, Panda CSS, vanilla-extract, StyleX, Stitches, and Emotion, see the [Comparison guide](comparison.md).
+
+---
+
+## What you are expected to define
+
+Tasty provides the engine. The DS team defines the language that runs on it. Here is what that typically involves:
+
+| Layer | What you define | Where |
+|-------|----------------|-------|
+| **Tokens** | Color names, spacing scale, border widths, radii | `configure({ tokens })` |
+| **Units** | Custom multiplier units (`x`, `r`, `bw`, or your own) | `configure({ units })` |
+| **State aliases** | Responsive breakpoints, theme modes, feature flags | `configure({ states })` |
+| **Recipes** | Reusable style bundles (card, elevated, input-reset) | `configure({ recipes })` |
+| **Typography** | Preset definitions (h1-h6, t1-t4, etc.) | `configure({ presets: { ... } })` |
+| **Style props** | Which CSS properties each component exposes as React props | `styleProps` in each component |
+| **Sub-elements** | Inner parts of compound components (Title, Icon, Content) | `elements` + capitalized keys in `styles` |
+| **Override rules** | How product engineers extend or constrain components | Styled wrappers via `tasty(Base, { ... })` |
+
+The same engine can power a minimal design system with a handful of tokens:
+
+```tsx
+configure({
+  tokens: { '#bg': '#white', '#text': '#111' },
+  states: { '@dark': '@root(schema=dark)' },
+});
+```
+
+...or an enterprise-scale system with dozens of tokens, multiple state aliases, typography presets, recipes, and custom units. The scope is yours to decide.
+
+Here is how the layers connect end-to-end. The DS team configures the engine, defines components, and product engineers consume them:
+
+```tsx
+// ds/config.ts — DS team defines the language
+configure({
+  tokens: { '#primary': 'oklch(55% 0.25 265)', '#surface': '#fff', '#text': '#111' },
+  states: { '@mobile': '@media(w < 768px)', '@dark': '@root(schema=dark)' },
+  recipes: { card: { padding: '4x', fill: '#surface', radius: '1r', border: true } },
+});
+
+// ds/components/Card.tsx — DS team builds components on top
+const Card = tasty({
+  styles: {
+    recipe: 'card',
+    Title: { preset: 'h3', color: '#primary' },
+    Body: { preset: 't2', color: '#text' },
+  },
+  elements: { Title: 'h2', Body: 'div' },
+  styleProps: ['padding', 'fill'],
+});
+
+// app/Dashboard.tsx — product engineer uses the component
+<Card padding={{ '': '4x', '@mobile': '2x' }}>
+  <Card.Title>Monthly Revenue</Card.Title>
+  <Card.Body>$1.2M — up 12% from last month</Card.Body>
+</Card>
+```
+
+See [Configuration](configuration.md) for the full `configure()` API.
+
+---
+
+## Incremental adoption
+
+You do not need to adopt everything at once. Tasty is designed to be introduced layer by layer.
+
+A practical way to start is with the components that already suffer from intersecting state and variant logic: buttons, inputs, menus, disclosures, dialogs, list items, interactive cards, and compound components. Those are the places where deterministic resolution pays off fastest.
+
+### Phase 1 -- Tokens and units
+
+Start by defining your design tokens and custom units. This is the lowest-risk step: it only configures the parser and does not require rewriting any components.
+
+```tsx
+import { configure } from '@tenphi/tasty';
+
+configure({
+  tokens: {
+    '#primary': 'oklch(55% 0.25 265)',
+    '#surface': '#white',
+    '#text': '#111',
+    '$card-padding': '4x',
+  },
+  // Common units (x, r, bw, ow, cr) are built-in.
+  // A DS typically redefines them to use CSS custom properties
+  // so that the actual scale is controlled via CSS, not JS:
+  units: {
+    x: 'var(--gap)',   // 2x → calc(var(--gap) * 2)
+    r: 'var(--radius)',
+    bw: 'var(--border-width)',
+  },
+});
+```
+
+### Phase 2 -- State aliases and recipes
+
+Define the state vocabulary your components will share. This is where you start encoding your team's conventions.
+
+```tsx
+configure({
+  states: {
+    '@mobile': '@media(w < 768px)',
+    '@tablet': '@media(w < 1024px)',
+    '@dark': '@root(schema=dark) | (!@root(schema) & @media(prefers-color-scheme: dark))',
+  },
+  recipes: {
+    card: { padding: '4x', fill: '#surface', radius: '1r', border: true },
+    elevated: { shadow: '0 2x 4x #shadow' },
+  },
+});
+```
+
+### Phase 3 -- Migrate a few primitives
+
+Pick 2-3 widely used primitives (Box, Text, Button) and rewrite them with `tasty()`. Keep the public API identical so product code does not need to change.
+
+```tsx
+const Box = tasty({
+  as: 'div',
+  styles: {
+    display: 'flex',
+    flow: 'column',
+    gap: '1x',
+  },
+  styleProps: ['gap', 'flow', 'padding', 'fill'],
+});
+```
+
+At this point you can validate the DSL, token workflow, and component authoring experience before expanding the rollout.
+
+### Phase 4 -- Encode complex states
+
+Move the components with the most painful intersecting states (buttons with hover + disabled + theme variants, inputs with focus + error + readonly) to Tasty's state map syntax. This is where mutually exclusive selectors start paying off.
+
+```tsx
+const Button = tasty({
+  as: 'button',
+  styles: {
+    fill: {
+      '': '#primary',
+      ':hover': '#primary-hover',
+      ':active': '#primary-pressed',
+      // `disabled` is a data-attribute modifier → [data-disabled].
+      // Tasty auto-applies it from the native `disabled` attribute.
+      // `[disabled]` (attribute selector) also works here.
+      disabled: '#surface',
+    },
+    color: {
+      '': '#on-primary',
+      disabled: '#text.40',
+    },
+    cursor: {
+      '': 'pointer',
+      disabled: 'not-allowed',
+    },
+    transition: 'theme',
+  },
+});
+```
+
+### Phase 5 -- Standardize style props and sub-elements
+
+Define which style props each component category exposes. Layout components get flow/gap/padding. Interactive components get positioning. Compound components declare sub-elements.
+
+```tsx
+const Card = tasty({
+  styles: {
+    recipe: 'card elevated',
+    Title: { preset: 'h3', color: '#primary' },
+    Content: { color: '#text', preset: 't2' },
+  },
+  elements: { Title: 'h2', Content: 'div' },
+  styleProps: ['padding', 'fill', 'radius'],
+});
+```
+
+### Phase 6 -- Expand to full DS coverage
+
+Migrate the remaining components, add the [ESLint plugin](https://github.com/tenphi/eslint-plugin-tasty) to enforce style conventions at lint time, and consider [zero-runtime mode](tasty-static.md) for static or performance-critical pages.
+
+---
+
+## What changes for product engineers
+
+When a DS is powered by Tasty, product engineers typically interact with **components, not Tasty itself**. Here is what changes from their perspective:
+
+**They do not write CSS directly.** Styling decisions are embedded in the components the DS provides. Product code consumes components, tokens, and style props.
+
+**Overrides use styled wrappers.** Instead of passing one-off `className` or `style` props, product engineers extend components:
+
+```tsx
+import { tasty } from '@tenphi/tasty';
+import { Button } from 'my-ds';
+
+// Replace mode: providing '' (default) key replaces the parent's fill entirely
+const DangerButton = tasty(Button, {
+  styles: {
+    fill: { '': '#danger', ':hover': '#danger-hover' },
+  },
+});
+
+// Extend mode: omitting '' key preserves parent states and adds/overrides
+const LoadingButton = tasty(Button, {
+  styles: {
+    fill: {
+      loading: '#yellow',       // new state appended
+      disabled: '#gray.20',     // existing state overridden in place
+    },
+  },
+});
+```
+
+**Style props replace raw CSS.** Layout, spacing, and positioning are controlled through typed props on the components that expose them:
+
+```tsx
+<Space flow="row" gap="2x" placeItems="center">
+  <Title>Dashboard</Title>
+  <Button placeSelf="end">Add Item</Button>
+</Space>
+```
+
+**Components are server components by default.** All `tasty()` components and style functions are hook-free, so they work as React Server Components without `'use client'`. In server-only contexts (Next.js RSC, Astro without `client:*` directives), they produce zero client JavaScript. Product engineers only add `'use client'` when their component needs actual React interactivity (state, effects, event handlers), never because of styling.
+
+**No cascade/specificity concerns.** Tasty's mutually exclusive selectors mean extending a component cannot accidentally break another. Import order, class name collisions, and specificity arithmetic are non-issues.
+
+---
+
+## Migration and Interop Notes
+
+- **From Tailwind**: keep utility-authored product surfaces as-is at first, and use Tasty to build or replace the design-system primitives underneath them instead of forcing an all-at-once markup rewrite.
+- **From CSS-in-JS libraries**: start with shared primitives such as `Box`, `Text`, and `Button`, preserve the external component API, and move state logic into Tasty state maps so behavior changes without product-code churn.
+- **From CSS Modules or plain CSS**: migrate token definitions and repeated patterns first, then wrap existing DOM structure with `tasty()` components gradually rather than converting every stylesheet at once.
+
+---
+
+## Learn more
+
+- [README](../README.md) -- overview, quick start, and feature highlights
+- [Getting Started](getting-started.md) -- installation, first component, tooling setup
+- [Methodology](methodology.md) -- the recommended patterns for structuring Tasty components
+- [Building a Design System](design-system.md) -- practical guide to building a DS layer with Tasty
+- [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
+- [Configuration](configuration.md) -- tokens, recipes, custom units, style handlers, and TypeScript extensions
+- [Style Properties](styles.md) -- complete reference for all enhanced style properties
+- [Comparison](comparison.md) -- positioning and trade-offs vs. other styling systems
+- [Zero Runtime (tastyStatic)](tasty-static.md) -- build-time static styling with Babel plugin