@tenphi/tasty 2.10.0 → 2.11.1

package/dist/ssr/next.js

@@ -1,9 +1,9 @@
 "use client";
-import { n as getConfig } from "../config-DA5FBnzm.js";
-import { i as registerSSRCollectorGetter } from "../format-rules-COR773Tn.js";
+import { n as getConfig } from "../config-YDAcLaVf.js";
+import { i as registerSSRCollectorGetter } from "../format-rules-CYriCDwq.js";
 import { t as getTastySSRContext } from "../context-CA8YKeMn.js";
-import { t as ServerStyleCollector } from "../collector-DCWdN88E.js";
-import { n as hydrateTastyClasses } from "../hydrate-F9olJTHt.js";
+import { t as ServerStyleCollector } from "../collector-AHZaBSv8.js";
+import { n as hydrateTastyClasses } from "../hydrate-GVTorHpU.js";
 import { Fragment, createElement, useState } from "react";
 import { useServerInsertedHTML } from "next/navigation";
 //#region src/ssr/next.ts

package/dist/static/index.d.ts

@@ -1,5 +1,5 @@
-import { b as Styles } from "../index-C5owZ15q.js";
-import { t as mergeStyles } from "../merge-styles-CvUi7SOD.js";
+import { b as Styles } from "../index-B9ih23uv.js";
+import { t as mergeStyles } from "../merge-styles-BZV-XAwX.js";
 
 //#region src/static/types.d.ts
 /**

package/dist/static/index.js

@@ -1,4 +1,4 @@
-import { t as mergeStyles } from "../merge-styles-DRUFVZH4.js";
+import { t as mergeStyles } from "../merge-styles-D4ITH4bc.js";
 //#region src/static/types.ts
 /**
 * Create a StaticStyle object.
@@ -34,14 +34,14 @@ function isStaticStyle(value) {
 */
 function tastyStatic(stylesOrBaseOrSelector, styles) {
 	if (typeof stylesOrBaseOrSelector === "string") {
-		console.warn(`[tasty] tastyStatic('${stylesOrBaseOrSelector}', styles) was called at runtime. This indicates the Babel plugin is not configured. Add @tenphi/tasty/babel-plugin to your Babel config.`);
+		console.warn(`[Tasty] tastyStatic('${stylesOrBaseOrSelector}', styles) was called at runtime. This indicates the Babel plugin is not configured. Add @tenphi/tasty/babel-plugin to your Babel config.`);
 		return;
 	}
 	if (isStaticStyle(stylesOrBaseOrSelector)) {
-		console.warn("[tasty] tastyStatic(base, styles) was called at runtime. This indicates the Babel plugin is not configured. Add @tenphi/tasty/babel-plugin to your Babel config.");
+		console.warn("[Tasty] tastyStatic(base, styles) was called at runtime. This indicates the Babel plugin is not configured. Add @tenphi/tasty/babel-plugin to your Babel config.");
 		return createStaticStyle("__TASTY_STATIC_NOT_TRANSFORMED__", mergeStyles(stylesOrBaseOrSelector.styles, styles || {}));
 	}
-	console.warn("[tasty] tastyStatic(styles) was called at runtime. This indicates the Babel plugin is not configured. Add @tenphi/tasty/babel-plugin to your Babel config.");
+	console.warn("[Tasty] tastyStatic(styles) was called at runtime. This indicates the Babel plugin is not configured. Add @tenphi/tasty/babel-plugin to your Babel config.");
 	return createStaticStyle("__TASTY_STATIC_NOT_TRANSFORMED__", stylesOrBaseOrSelector);
 }
 //#endregion

package/dist/static/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/static/types.ts","../../src/static/tastyStatic.ts"],"sourcesContent":["import type { Styles } from '../styles/types';\n\n/**\n * Static style definition returned by tastyStatic().\n *\n * Supports both explicit className access and implicit string coercion via toString().\n *\n * @example\n * ```typescript\n * const button = tastyStatic({ fill: '#blue' });\n *\n * // Both work in JSX:\n * <div className={button} />           // Uses toString()\n * <div className={button.className} /> // Explicit\n *\n * // Extension:\n * const primary = tastyStatic(button, { fill: '#purple' });\n * ```\n */\nexport interface StaticStyle {\n  /**\n   * Generated className(s) for use in JSX.\n   * May contain multiple space-separated class names due to chunking.\n   */\n  className: string;\n\n  /**\n   * The original (or merged) styles object.\n   * Available for extension via tastyStatic(base, overrides).\n   */\n  styles: Styles;\n\n  /**\n   * Returns className for implicit string coercion.\n   * Enables `<div className={button} />` syntax.\n   */\n  toString(): string;\n}\n\n/**\n * Create a StaticStyle object.\n * Used internally by the Babel plugin to generate output.\n */\nexport function createStaticStyle(\n  className: string,\n  styles: Styles,\n): StaticStyle {\n  return {\n    className,\n    styles,\n    toString() {\n      return this.className;\n    },\n  };\n}\n\n/**\n * Type guard to check if a value is a StaticStyle object.\n */\nexport function isStaticStyle(value: unknown): value is StaticStyle {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    'className' in value &&\n    'styles' in value &&\n    'toString' in value &&\n    typeof (value as StaticStyle).className === 'string' &&\n    typeof (value as StaticStyle).styles === 'object'\n  );\n}\n","import type { Styles } from '../styles/types';\nimport { mergeStyles } from '../utils/merge-styles';\n\nimport type { StaticStyle } from './types';\nimport { createStaticStyle, isStaticStyle } from './types';\n\n/**\n * Generate styles and return a StaticStyle object.\n * The object has `className`, `styles`, and `toString()`.\n *\n * @example\n * ```typescript\n * const button = tastyStatic({\n *   fill: '#blue',\n *   padding: '2x',\n * });\n * // After build: { className: 'ts3f2a1b', styles: {...}, toString() }\n *\n * <div className={button} />  // Works via toString()\n * ```\n */\nexport function tastyStatic(styles: Styles): StaticStyle;\n\n/**\n * Extend an existing StaticStyle with additional styles.\n * Uses mergeStyles() internally for proper nested selector handling.\n *\n * @example\n * ```typescript\n * const button = tastyStatic({ fill: '#blue' });\n * const primary = tastyStatic(button, { fill: '#purple' });\n * // After build: { className: 'ts8c4d2e', styles: {...merged...}, toString() }\n * ```\n */\nexport function tastyStatic(base: StaticStyle, styles: Styles): StaticStyle;\n\n/**\n * Generate styles for a specific CSS selector.\n * The call is completely removed after build transformation.\n *\n * @example\n * ```typescript\n * tastyStatic('.heading', { preset: 'h1', color: '#primary' });\n * // After build: (removed)\n * ```\n */\nexport function tastyStatic(selector: string, styles: Styles): void;\n\n/**\n * Build-time only function for zero-runtime static site generation.\n *\n * This function is transformed by the Babel plugin:\n * - `tastyStatic(styles)` → StaticStyle object with className\n * - `tastyStatic(base, styles)` → StaticStyle object with merged styles\n * - `tastyStatic(selector, styles)` → removed entirely\n *\n * At runtime (during development/build), this function returns a placeholder.\n * In production, all calls are replaced/removed by the build plugin.\n */\nexport function tastyStatic(\n  stylesOrBaseOrSelector: Styles | StaticStyle | string,\n  styles?: Styles,\n): StaticStyle | void {\n  // This code only executes if the Babel plugin hasn't processed the file yet.\n  // In a properly configured build, this function is never called at runtime.\n\n  if (typeof stylesOrBaseOrSelector === 'string') {\n    // Selector mode: tastyStatic(selector, styles)\n    // The plugin will remove this call entirely\n    if (process.env.NODE_ENV !== 'production') {\n      console.warn(\n        `[tasty] tastyStatic('${stylesOrBaseOrSelector}', styles) was called at runtime. ` +\n          'This indicates the Babel plugin is not configured. ' +\n          'Add @tenphi/tasty/babel-plugin to your Babel config.',\n      );\n    }\n    return; // void\n  }\n\n  if (isStaticStyle(stylesOrBaseOrSelector)) {\n    // Extension mode: tastyStatic(base, styles)\n    if (process.env.NODE_ENV !== 'production') {\n      console.warn(\n        '[tasty] tastyStatic(base, styles) was called at runtime. ' +\n          'This indicates the Babel plugin is not configured. ' +\n          'Add @tenphi/tasty/babel-plugin to your Babel config.',\n      );\n    }\n    // Merge styles for dev mode preview (won't have real classNames)\n    const mergedStyles = mergeStyles(\n      stylesOrBaseOrSelector.styles,\n      styles || {},\n    );\n    return createStaticStyle('__TASTY_STATIC_NOT_TRANSFORMED__', mergedStyles);\n  }\n\n  // Styles mode: tastyStatic(styles)\n  if (process.env.NODE_ENV !== 'production') {\n    console.warn(\n      '[tasty] tastyStatic(styles) was called at runtime. ' +\n        'This indicates the Babel plugin is not configured. ' +\n        'Add @tenphi/tasty/babel-plugin to your Babel config.',\n    );\n  }\n\n  // Return placeholder - styles won't be applied without the plugin\n  return createStaticStyle(\n    '__TASTY_STATIC_NOT_TRANSFORMED__',\n    stylesOrBaseOrSelector,\n  );\n}\n"],"mappings":";;;;;;AA2CA,SAAgB,kBACd,WACA,QACa;CACb,OAAO;EACL;EACA;EACA,WAAW;GACT,OAAO,KAAK;EACd;CACF;AACF;;;;AAKA,SAAgB,cAAc,OAAsC;CAClE,OACE,OAAO,UAAU,YACjB,UAAU,QACV,eAAe,SACf,YAAY,SACZ,cAAc,SACd,OAAQ,MAAsB,cAAc,YAC5C,OAAQ,MAAsB,WAAW;AAE7C;;;;;;;;;;;;;;ACVA,SAAgB,YACd,wBACA,QACoB;CAIpB,IAAI,OAAO,2BAA2B,UAAU;EAI5C,QAAQ,KACN,wBAAwB,uBAAuB,0IAGjD;EAEF;CACF;CAEA,IAAI,cAAc,sBAAsB,GAAG;EAGvC,QAAQ,KACN,kKAGF;EAOF,OAAO,kBAAkB,oCAJJ,YACnB,uBAAuB,QACvB,UAAU,CAAC,CAE2D,CAAC;CAC3E;CAIE,QAAQ,KACN,4JAGF;CAIF,OAAO,kBACL,oCACA,sBACF;AACF"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/static/types.ts","../../src/static/tastyStatic.ts"],"sourcesContent":["import type { Styles } from '../styles/types';\n\n/**\n * Static style definition returned by tastyStatic().\n *\n * Supports both explicit className access and implicit string coercion via toString().\n *\n * @example\n * ```typescript\n * const button = tastyStatic({ fill: '#blue' });\n *\n * // Both work in JSX:\n * <div className={button} />           // Uses toString()\n * <div className={button.className} /> // Explicit\n *\n * // Extension:\n * const primary = tastyStatic(button, { fill: '#purple' });\n * ```\n */\nexport interface StaticStyle {\n  /**\n   * Generated className(s) for use in JSX.\n   * May contain multiple space-separated class names due to chunking.\n   */\n  className: string;\n\n  /**\n   * The original (or merged) styles object.\n   * Available for extension via tastyStatic(base, overrides).\n   */\n  styles: Styles;\n\n  /**\n   * Returns className for implicit string coercion.\n   * Enables `<div className={button} />` syntax.\n   */\n  toString(): string;\n}\n\n/**\n * Create a StaticStyle object.\n * Used internally by the Babel plugin to generate output.\n */\nexport function createStaticStyle(\n  className: string,\n  styles: Styles,\n): StaticStyle {\n  return {\n    className,\n    styles,\n    toString() {\n      return this.className;\n    },\n  };\n}\n\n/**\n * Type guard to check if a value is a StaticStyle object.\n */\nexport function isStaticStyle(value: unknown): value is StaticStyle {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    'className' in value &&\n    'styles' in value &&\n    'toString' in value &&\n    typeof (value as StaticStyle).className === 'string' &&\n    typeof (value as StaticStyle).styles === 'object'\n  );\n}\n","import type { Styles } from '../styles/types';\nimport { mergeStyles } from '../utils/merge-styles';\n\nimport type { StaticStyle } from './types';\nimport { createStaticStyle, isStaticStyle } from './types';\n\n/**\n * Generate styles and return a StaticStyle object.\n * The object has `className`, `styles`, and `toString()`.\n *\n * @example\n * ```typescript\n * const button = tastyStatic({\n *   fill: '#blue',\n *   padding: '2x',\n * });\n * // After build: { className: 'ts3f2a1b', styles: {...}, toString() }\n *\n * <div className={button} />  // Works via toString()\n * ```\n */\nexport function tastyStatic(styles: Styles): StaticStyle;\n\n/**\n * Extend an existing StaticStyle with additional styles.\n * Uses mergeStyles() internally for proper nested selector handling.\n *\n * @example\n * ```typescript\n * const button = tastyStatic({ fill: '#blue' });\n * const primary = tastyStatic(button, { fill: '#purple' });\n * // After build: { className: 'ts8c4d2e', styles: {...merged...}, toString() }\n * ```\n */\nexport function tastyStatic(base: StaticStyle, styles: Styles): StaticStyle;\n\n/**\n * Generate styles for a specific CSS selector.\n * The call is completely removed after build transformation.\n *\n * @example\n * ```typescript\n * tastyStatic('.heading', { preset: 'h1', color: '#primary' });\n * // After build: (removed)\n * ```\n */\nexport function tastyStatic(selector: string, styles: Styles): void;\n\n/**\n * Build-time only function for zero-runtime static site generation.\n *\n * This function is transformed by the Babel plugin:\n * - `tastyStatic(styles)` → StaticStyle object with className\n * - `tastyStatic(base, styles)` → StaticStyle object with merged styles\n * - `tastyStatic(selector, styles)` → removed entirely\n *\n * At runtime (during development/build), this function returns a placeholder.\n * In production, all calls are replaced/removed by the build plugin.\n */\nexport function tastyStatic(\n  stylesOrBaseOrSelector: Styles | StaticStyle | string,\n  styles?: Styles,\n): StaticStyle | void {\n  // This code only executes if the Babel plugin hasn't processed the file yet.\n  // In a properly configured build, this function is never called at runtime.\n\n  if (typeof stylesOrBaseOrSelector === 'string') {\n    // Selector mode: tastyStatic(selector, styles)\n    // The plugin will remove this call entirely\n    if (process.env.NODE_ENV !== 'production') {\n      console.warn(\n        `[Tasty] tastyStatic('${stylesOrBaseOrSelector}', styles) was called at runtime. ` +\n          'This indicates the Babel plugin is not configured. ' +\n          'Add @tenphi/tasty/babel-plugin to your Babel config.',\n      );\n    }\n    return; // void\n  }\n\n  if (isStaticStyle(stylesOrBaseOrSelector)) {\n    // Extension mode: tastyStatic(base, styles)\n    if (process.env.NODE_ENV !== 'production') {\n      console.warn(\n        '[Tasty] tastyStatic(base, styles) was called at runtime. ' +\n          'This indicates the Babel plugin is not configured. ' +\n          'Add @tenphi/tasty/babel-plugin to your Babel config.',\n      );\n    }\n    // Merge styles for dev mode preview (won't have real classNames)\n    const mergedStyles = mergeStyles(\n      stylesOrBaseOrSelector.styles,\n      styles || {},\n    );\n    return createStaticStyle('__TASTY_STATIC_NOT_TRANSFORMED__', mergedStyles);\n  }\n\n  // Styles mode: tastyStatic(styles)\n  if (process.env.NODE_ENV !== 'production') {\n    console.warn(\n      '[Tasty] tastyStatic(styles) was called at runtime. ' +\n        'This indicates the Babel plugin is not configured. ' +\n        'Add @tenphi/tasty/babel-plugin to your Babel config.',\n    );\n  }\n\n  // Return placeholder - styles won't be applied without the plugin\n  return createStaticStyle(\n    '__TASTY_STATIC_NOT_TRANSFORMED__',\n    stylesOrBaseOrSelector,\n  );\n}\n"],"mappings":";;;;;;AA2CA,SAAgB,kBACd,WACA,QACa;CACb,OAAO;EACL;EACA;EACA,WAAW;GACT,OAAO,KAAK;EACd;CACF;AACF;;;;AAKA,SAAgB,cAAc,OAAsC;CAClE,OACE,OAAO,UAAU,YACjB,UAAU,QACV,eAAe,SACf,YAAY,SACZ,cAAc,SACd,OAAQ,MAAsB,cAAc,YAC5C,OAAQ,MAAsB,WAAW;AAE7C;;;;;;;;;;;;;;ACVA,SAAgB,YACd,wBACA,QACoB;CAIpB,IAAI,OAAO,2BAA2B,UAAU;EAI5C,QAAQ,KACN,wBAAwB,uBAAuB,0IAGjD;EAEF;CACF;CAEA,IAAI,cAAc,sBAAsB,GAAG;EAGvC,QAAQ,KACN,kKAGF;EAOF,OAAO,kBAAkB,oCAJJ,YACnB,uBAAuB,QACvB,UAAU,CAAC,CAE2D,CAAC;CAC3E;CAIE,QAAQ,KACN,4JAGF;CAIF,OAAO,kBACL,oCACA,sBACF;AACF"}

package/dist/zero/babel.d.ts

@@ -1,4 +1,4 @@
-import { t as TastyConfig } from "../config-C3SKYuxY.js";
+import { t as TastyConfig } from "../config-BtK9fUaz.js";
 import { PluginPass } from "@babel/core";
 
 //#region src/zero/babel.d.ts

package/dist/zero/babel.js

@@ -1,7 +1,7 @@
-import { i as getGlobalConfigTokens, t as configure, u as getGlobalStyles, v as resetConfig } from "../config-DA5FBnzm.js";
-import { t as mergeStyles } from "../merge-styles-DRUFVZH4.js";
-import { t as resolveRecipes } from "../resolve-recipes-DUfJKJef.js";
-import { a as extractPropertiesFromStyles, c as setExtractorNamePrefix, i as extractKeyframesFromStyles, n as extractCounterStyleFromStyles, o as extractStylesForSelector, r as extractFontFaceFromStyles, s as extractStylesWithChunks, t as CSSWriter } from "../css-writer-Cnj-KrI4.js";
+import { i as getGlobalConfigTokens, t as configure, u as getGlobalStyles, v as resetConfig } from "../config-YDAcLaVf.js";
+import { t as mergeStyles } from "../merge-styles-D4ITH4bc.js";
+import { t as resolveRecipes } from "../resolve-recipes-llr0COs8.js";
+import { a as extractPropertiesFromStyles, c as setExtractorNamePrefix, i as extractKeyframesFromStyles, n as extractCounterStyleFromStyles, o as extractStylesForSelector, r as extractFontFaceFromStyles, s as extractStylesWithChunks, t as CSSWriter } from "../css-writer-BXSANVrq.js";
 import * as fs from "fs";
 import * as path from "path";
 import { declare } from "@babel/helper-plugin-utils";

package/dist/zero/index.d.ts

@@ -1,4 +1,4 @@
-import { b as Styles } from "../index-C5owZ15q.js";
+import { b as Styles } from "../index-B9ih23uv.js";
 
 //#region src/zero/extractor.d.ts
 interface ExtractedChunk {

package/dist/zero/index.js

@@ -1,2 +1,2 @@
-import { o as extractStylesForSelector, s as extractStylesWithChunks, t as CSSWriter } from "../css-writer-Cnj-KrI4.js";
+import { o as extractStylesForSelector, s as extractStylesWithChunks, t as CSSWriter } from "../css-writer-BXSANVrq.js";
 export { CSSWriter, extractStylesForSelector, extractStylesWithChunks };

package/docs/README.md

@@ -24,6 +24,7 @@ Tasty is a styling engine for design systems that turns component state into det
 ## By Task
 
 - **Learn the style language**: [Style DSL](dsl.md)
+- **Brief an AI agent (or yourself) on writing correct styles**: [Style Rules for AI Agents](ai-agents.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)

package/docs/ai-agents.md

@@ -0,0 +1,206 @@
+# Tasty Style Rules for AI Agents
+
+A compact ruleset for **writing correct `@tenphi/tasty` styles**. It is not an API tour — every rule here is machine-checked by [`@tenphi/eslint-plugin-tasty`](https://www.npmjs.com/package/@tenphi/eslint-plugin-tasty), so following it means clean lint output. For explanations and the complete API, see [Style DSL](dsl.md), [Style Properties](styles.md), [React API](react-api.md).
+
+Notation: ❌ wrong → ✅ correct.
+
+---
+
+## 0. Read the project config first
+
+Color tokens (`#name`), custom properties (`$name`), `preset` names, `recipe` names, state aliases (`@mobile`) and extra units are **project-defined** in `tasty.config.ts` or a `configure({ … })` call. Look them up before writing styles. Never invent a name — reuse an existing one, or add it to the config.
+
+## 1. Where styles go
+
+```jsx
+const Card = tasty({ as: 'div', styles: { … }, styleProps: ['padding'] }); // new component
+const Hero = tasty(Card, { styles: { … } });                              // extend a component
+const cls = useStyles({ … });                                             // ad-hoc class name
+tastyStatic('.card', { … });                                              // build-time, zero runtime
+```
+
+- Wrap, don't pass styles per instance: ❌ `<Box styles={{ padding: '2x' }} />` → ✅ `const Box = tasty({ styles: { padding: '2x' } })`.
+- Style values are **static**. Route anything conditional through a state map plus `mods` (or `tokens` / `styleProps`):
+  ❌ `fill: isOpen ? '#primary' : '#surface'` → ✅ `fill: { '': '#surface', open: '#primary' }` with `mods={{ open: isOpen }}`.
+
+## 2. Property names
+
+Keys are camelCase — a Tasty property or a real CSS property. No kebab-case, no invented names.
+
+Prefer the Tasty shorthand over its CSS equivalents:
+
+| Use | Instead of |
+|-----|------------|
+| `fill` | `backgroundColor`, `background` |
+| `image` | `backgroundImage` |
+| `border` | `borderColor`, `borderWidth`, `borderStyle`, `borderTop`/`Right`/`Bottom`/`Left` |
+| `radius` | `borderRadius` |
+| `outline` | `outlineColor`, `outlineWidth`, `outlineStyle`, `outlineOffset` |
+| `shadow` | `boxShadow` |
+| `padding` | `paddingTop`/`Right`/`Bottom`/`Left` |
+| `margin` | `marginTop`/`Right`/`Bottom`/`Left` |
+| `inset` | `top`, `right`, `bottom`, `left` |
+| `width` / `height` | `minWidth`/`maxWidth`, `minHeight`/`maxHeight` |
+| `flow` | `flexDirection`, `flexWrap`, `flexFlow`, `gridAutoFlow` |
+| `preset` | `fontSize`, `lineHeight`, `letterSpacing`, `fontWeight`, `fontStyle`, `textTransform` |
+| `font` | `fontFamily` |
+| `scrollbar` | `scrollbarWidth`, `scrollbarColor`, `scrollbarGutter` |
+| `gridColumns` / `gridRows` / `gridAreas` | `gridTemplateColumns` / `Rows` / `Areas` |
+| `textOverflow: 'ellipsis / 3'` | `lineClamp` |
+| `hide: true` | `display: 'none'` |
+| `flexGrow` / `flexShrink` / `flexBasis` | `flex` |
+
+The last row goes the other way — longhands over the shorthand — because `flex` is lossy: it resets the components you omit to non-initial values (`flex: '0'` silently sets `flex-basis: 0%`) and cannot express `flexShrink: 0` at all. The longhands also carry separate state maps.
+
+## 3. Values
+
+### Tokens
+
+| Syntax | Meaning |
+|--------|---------|
+| `#name` | color token → `var(--name-color)` |
+| `#name.50` | token at 50% opacity (`0`–`100`) |
+| `#name.$opacity` | opacity from a custom property |
+| `#clear` / `#current` | `transparent` / `currentcolor` |
+| `$name` | custom property → `var(--name)` |
+| `(#a, #b)` | fallback chain |
+| `$$name` / `##name` | the property *name* — only inside `transition` |
+
+- ❌ `#f5f5f5`, `rgb(0 0 0)`, `oklch(…)`, `okhsl(…)`, `red` → ✅ `#surface` (add the token to the config if it doesn't exist).
+- ❌ `var(--gap)` → ✅ `$gap` · ❌ `$accent-color` → ✅ `#accent` · ❌ `transparent` → ✅ `#clear` · ❌ `currentColor` → ✅ `#current`.
+- A `$name` must be declared as a `'$name': value` key in the same styles object, or in the config.
+
+### Units
+
+Tasty units: `x` (gap multiple), `r` (radius), `cr` (card radius), `bw` (border width), `ow` (outline width), `sf` (`minmax(0, Nfr)`). All CSS units work too, plus anything in `units` in the config. Any other unit is an error.
+
+Prefer units over raw pixels: `8px` → `1x` … `64px` → `8x`; `radius: '6px'` → `'1r'`; `border: '1px …'` → `'1bw …'`.
+
+### Math
+
+❌ `calc(100% - 2x)` → ✅ `(100% - 2x)`. Parentheses are wrapped in `calc()` automatically — and must be balanced.
+
+### `true`
+
+`true` means "the design-system default" and is accepted **only** by: `border`, `radius`, `outline`, `shadow`, `padding`, `margin`, `gap`, `inset`, `width`, `height`, `fill`, `color`, `preset`, `font`, `scrollbar`, `hide`. Anywhere else it is an error.
+
+### `!important`
+
+Never use it. Tasty owns specificity through doubled selectors and state ordering; `!important` breaks that. Express the exception as a state instead.
+
+### Modifiers
+
+A value is `[values…] [modifiers…]`, and several groups can be comma-separated (later groups override earlier ones). Only the modifiers a property knows are valid:
+
+| Property | Modifiers |
+|----------|-----------|
+| `padding`, `margin`, `inset`, `fade` | `top` `right` `bottom` `left` |
+| `border` | the four directions + `solid` `dashed` `dotted` `double` `groove` `ridge` `inset` `outset` `none` `hidden` |
+| `outline` | the style keywords above |
+| `radius` | `top` `right` `bottom` `left` + shapes `round` `ellipse` `leaf` `backleaf` |
+| `width`, `height` | `min` `max` `fixed` |
+| `flow` | `row` `column` `row-reverse` `column-reverse` `wrap` `nowrap` `dense` |
+| `overflow` | `visible` `hidden` `scroll` `clip` `auto` `overlay` |
+| `position` | `static` `relative` `absolute` `fixed` `sticky` |
+| `shadow` | `inset` |
+| `preset` | `name / strong` (or `bold`) `italic` `icon` `tight` |
+| box properties | `longhand` — emit CSS longhands instead of the shorthand |
+
+Directional modifiers beat placeholder zeros:
+
+- ❌ `padding: '0 0 2x 0'` → ✅ `padding: '2x bottom'`
+- ❌ `padding: '1x 1x 2x 1x'` → ✅ `padding: '1x, 2x bottom'`
+- ❌ `border: '0 0 1bw 0'` — four tokens parse as *one* border value, so this renders no border at all → ✅ `border: '1bw bottom'`
+
+Value-only properties reject both colors and modifiers: `gap`, `columnGap`, `rowGap`, `opacity`, `zIndex`, `order`, `flexGrow`, `flexShrink`, `flexBasis`, `aspectRatio`, `lineClamp`, `tabSize`, `paddingInline`, `paddingBlock`. `fill` and `color` take a color (plus `none` / `transparent`); `caretColor` and `accentColor` take a color only.
+
+### `transition`
+
+Use semantic names, not CSS property names: `fade` `fill` `color` `theme` `border` `radius` `shadow` `outline` `preset` `text` `gap` `opacity` `translate` `rotate` `scale` `filter` `image` `background` `width` `height` `zIndex` `inset` `flow` `dimension`.
+
+❌ `transition: 'background-color 0.2s'` → ✅ `transition: 'fill 0.2s'`
+
+## 4. State maps
+
+A property value can be an object of `state: value`. Key order is priority — later keys win.
+
+| Key | Generated selector |
+|-----|--------------------|
+| `hovered` | `[data-hovered]` (boolean modifier from `mods`) |
+| `theme=danger` | `[data-theme="danger"]` (value modifier) |
+| `:hover` | pseudo-class |
+| `.active` | class selector |
+| `[aria-expanded="true"]` | attribute selector |
+| `hovered & .active` | AND |
+| `hovered \| focused` | OR (`,` also means OR) |
+| `!disabled` | NOT |
+| `hovered ^ focused` | XOR — exactly one (keep chains ≤ 4 operands) |
+
+Precedence `!` > `^` > `|` > `&`; use parentheses to override.
+
+Rules:
+
+1. **`''` comes first.** The bare default is the lowest-priority state; placing it later would override everything above it.
+2. **Every state map needs `''` or `_`** — except when extending (`tasty(Parent, …)`), where omitting `''` merges into the parent's states and including `''` replaces them wholesale.
+3. **`_` is standalone-only** and always first (with `''` right after it, if present). `_` is a never-negated fallback floor for cases where a higher-priority branch may be *unknown* (`@supports`, container queries). If a map contains only `_` and `''`, drop the `''`.
+4. **No nested maps:** ❌ `{ hovered: { pressed: 'x' } }` → ✅ `{ 'hovered & pressed': 'x' }`
+5. **State keys never sit at the top level** of a styles object — `:hover`, `.active`, `[open]` belong inside a property value.
+
+```jsx
+color: { '': '#text', hovered: '#accent', disabled: '#text.40' }
+```
+
+Advanced states:
+
+| Prefix | Use | Example |
+|--------|-----|---------|
+| `@media(…)` | media query; dimensions `w` `h`; types `@media:print` `:screen` `:all` `:speech` | `@media(w < 768px)`, `@media(600px <= w < 1200px)` |
+| `@(…)` | container query; dimensions `w` `h` `is` `bs` | `@(layout, w >= 600px)`, `@($variant=primary)` |
+| `@supports(…)` | feature query; `$` first argument tests a selector | `@supports(display: grid)`, `@supports($, :has(*))` |
+| `@root(…)` | condition on `:root` | `@root(schema=dark)` |
+| `@parent(…)` | condition on an ancestor; `, >` for the direct parent | `@parent(hovered, >)` |
+| `@own(…)` | a sub-element's own state — **only inside sub-element styles** | `@own(:hover)` |
+| `@starting` | `@starting-style` entry animation | `@starting` |
+| `@name` | project state alias | `@mobile` |
+
+- At root level write the selector directly: ❌ `'@own(:hover)'` → ✅ `':hover'`.
+- `@name` aliases must exist in `states` in the config or be declared locally as an `'@name': '<state expression>'` key; alias keys start with `@` and their value must be a valid state expression.
+- `:is()` / `:has()` / `:not()` / `:where()` work in state keys but support at most 2 levels of nested parentheses, and `:has()` is expensive — prefer `@parent()`, `@own()` and modifiers.
+
+When extending a parent's state map: `'@inherit'` reuses the parent's value for that state, `null` removes a state (or resets a property, letting recipes fill in), `false` is a tombstone that blocks it entirely.
+
+## 5. Sub-elements
+
+A **capitalized** key targets `[data-element="Name"]`, and its value must be a style object.
+
+```jsx
+styles: { Title: { preset: 'h3' }, Icon: { $: '>@:last-child', color: '#accent' } }
+```
+
+❌ nested-selector keys (`'& .title'`, `'&:hover'`) → ✅ sub-elements and state maps. Use the `$` affix property inside a sub-element to control how its selector attaches (`>` direct child, `@` placeholder for the element itself, `&::before` for a root pseudo-element).
+
+## 6. Special top-level keys
+
+| Key | Shape |
+|-----|-------|
+| `@keyframes` | `{ name: { '0%': styles, … } }` |
+| `@properties` | `{ '$name': { syntax, inherits, initialValue } }` |
+| `@fontFace` | `{ 'Family Name': descriptors \| descriptors[] }` |
+| `@counterStyle` | `{ name: descriptors }` |
+| `recipe` | a **string** of configured recipe names: `'card elevated'`, `'reset input / autofill'`, `'none / disabled'` |
+
+## 7. `tastyStatic()`
+
+The selector must be a string literal and valid CSS. Values must be static — strings, numbers, booleans, `null`, or objects/arrays of those. No variables, template literals, function calls, or spreads.
+
+## 8. Checklist
+
+- Token, preset, recipe, unit and `@alias` names exist in the project config.
+- Tasty shorthand chosen over CSS longhands; `flexGrow`/`flexShrink`/`flexBasis` over `flex`; `hide: true` over `display: 'none'`.
+- Colors are `#tokens`, not hex/rgb/oklch/named; `$prop` not `var(--prop)`.
+- Spacing uses `x`/`r`/`bw`/`ow` units; math uses `(…)`, not `calc(…)`.
+- `true` only on the properties that accept it; no `!important`.
+- Modifiers valid for the property; directional shorthand instead of placeholder zeros.
+- Every state map starts with `''` (or `_`), is flat, and lives inside a property value.
+- `@own()` only inside sub-elements; sub-element keys are capitalized and hold objects.
+- Values are static; dynamic behavior comes from `mods` / `tokens` / `styleProps`.

package/docs/styles.md

@@ -199,6 +199,10 @@ Positioning offsets with directional modifiers and multi-group support. Same dir
 to the two perpendicular sides. `inset: 'bottom dock'` gives `inset: auto 0 0 0` — anchored to
 the bottom, full width. Without a direction, `dock` fills every side.
 
+A second value applies to the spanned sides: `inset: '2x 4x bottom dock'` pins the bottom at
+`2x` and insets the sides by `4x`. Intended for a single edge — combining `dock` with several
+directions has no well-defined meaning.
+
 **Output modifier:** `longhand` — forces output as individual CSS properties (`top`, `right`, `bottom`, `left`) instead of the `inset` shorthand.
 
 | Value | Effect |
@@ -212,6 +216,7 @@ the bottom, full width. Without a direction, `dock` fills every side.
 | `"bottom dock"` | Bottom/left/right `0`, top `auto` — bottom-anchored, full width |
 | `"right dock"` | Right/top/bottom `0`, left `auto` — right-anchored, full height |
 | `"2x bottom dock"` | Bottom/left/right `2x`, top `auto` |
+| `"2x 4x bottom dock"` | Bottom `2x`, left/right `4x`, top `auto` |
 | `"dock"` | All sides `0` |
 
 Later comma-separated groups override earlier groups for conflicting directions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenphi/tasty",
-  "version": "2.10.0",
+  "version": "2.11.1",
   "description": "A design-system-integrated styling system and DSL for concise, state-aware UI styling",
   "type": "module",
   "main": "./dist/index.js",
@@ -139,6 +139,7 @@
     "@eslint/js": "^10.0.1",
     "@size-limit/esbuild": "^12.0.0",
     "@size-limit/file": "^12.0.0",
+    "@tenphi/eslint-plugin-tasty": "^0.11.3",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
     "@types/babel__core": "^7.20.5",