@tenphi/tasty 0.0.0-snapshot.1c5dff6 → 0.0.0-snapshot.1f1c00a

package/docs/README.md

@@ -0,0 +1,39 @@
+# Tasty Docs
+
+Tasty is CSS-in-JS for React design systems. You describe hover, disabled, variants, themes, responsive behavior, and other conditions as state maps; Tasty compiles them so one branch wins without specificity fights or source-order surprises.
+
+Use this hub to move from the core idea to a working component, then into design-system patterns or API reference as needed.
+
+## Start Here
+
+- **Understand why**: [Introduction](../README.md) for the problem, the state-map model, and the product overview.
+- **Try it**: [Getting Started](getting-started.md) to build a stateful component, add shared configuration, and choose a rendering mode.
+- **Build a component system**: [Methodology](methodology.md) for root + sub-elements, typed public APIs, tokens, and extension patterns; then [Building a Design System](design-system.md).
+- **Evaluate or adopt it**: [Comparison](comparison.md) for tool-selection context and [Adoption Guide](adoption.md) for an incremental rollout.
+- **Understand the compiler**: [Style rendering pipeline](pipeline.md) for how state maps become mutually exclusive selectors.
+
+## 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), [Build-Time Extraction (`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-client-runtime React with `tasty()`**: [Server-Side Rendering](ssr.md), especially the static Astro integration
+- **Build-time extraction with `tastyStatic()`**: [Build-Time Extraction](tasty-static.md)
+- **Hydrated `tasty()` with server collection**: [Server-Side Rendering](ssr.md)
+- **Upgrading from v2**: [Migration Guide (v2 → v3)](migration-v3.md)
+
+## 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, properties, functions, or polyfills globally**: [Configuration](configuration.md)
+- **Extend Tasty with a plugin, custom handler, or custom prop**: [Plugins & Extension Points](plugins.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)
+- **Reproduce and interpret performance measurements**: [Runtime Benchmarks](runtime-benchmarks.md)

package/docs/adoption.md

@@ -0,0 +1,323 @@
+# Adoption Guide
+
+Tasty is most useful where reusable component styling has become a state-resolution problem: hover intersects with disabled, variants intersect with themes, and every extension makes selector behavior harder to predict.
+
+It normally sits underneath a design system’s existing components. You can preserve their public React APIs while moving their style logic into state maps that produce one declared winner. Adoption should start with a small, state-heavy component—not 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 it for rollout strategy and adoption sequencing; use the [Comparison guide](comparison.md) when the open question is whether Tasty is the right tool.
+
+---
+
+## 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 owns shared component APIs
+- Components with complex, intersecting states (hover + disabled + theme + breakpoint)
+- Teams that need deterministic style resolution without cascade/specificity bugs
+- Organizations that want tokens, states, and extension rules to stay consistent across products
+
+**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 first slice is one component that already suffers from intersecting state and variant logic: a button, input, menu item, disclosure, or interactive card. Keep its public API unchanged, move one or two properties into Tasty state maps, and verify that the declared priority matches the behavior your team expects.
+
+This proves the differentiator before you invest in a complete token vocabulary or migrate an entire component library.
+
+### Phase 1 -- Pilot one state-heavy component
+
+Choose a component with a known hover/disabled, focus/error, or variant/theme interaction. Preserve its external props and visual behavior. The pilot should answer three questions:
+
+1. Is the state map easier to review than the existing selectors or conditional class logic?
+2. Does extending the component keep the intended state priority?
+3. Can your current tokens and component API move over without product-code churn?
+
+If the answer is yes, establish the shared design-system vocabulary around the successful slice.
+
+### Phase 2 -- 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 3 -- 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 4 -- 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 5 -- Expand state resolution
+
+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 6 -- 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 7 -- 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 choose between [server-only `tasty()`](ssr.md) and [`tastyStatic()` build-time extraction](tasty-static.md) when a page should ship no Tasty styling runtime.
+
+---
+
+## 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 they ship no Tasty styling runtime. Astro without `client:*` directives ships no client JavaScript; server-only Next.js RSC follows the same Tasty architecture, while final output depends on the application deployment. 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
+- [Build-Time Extraction (`tastyStatic`)](tasty-static.md) -- static styling with the Babel plugin

package/docs/ai-agents.md

@@ -0,0 +1,250 @@
+# Tasty Style Rules for AI Agents
+
+A compact ruleset for **writing correct `@tenphi/tasty` styles**. It is not an API tour — most rules here are machine-checked by [`@tenphi/eslint-plugin-tasty`](https://www.npmjs.com/package/@tenphi/eslint-plugin-tasty), so following it generally means clean lint output. The plugin ships separately and can lag a new DSL rule, so treat this page as the source of truth and the plugin as the enforcement that catches most of it. 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 extraction
+```
+
+- 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 }}`.
+- Keep JavaScript identifiers, calls, computed keys, and interpolated templates
+  out of style values. Use token references inside strings for values supplied
+  at runtime. Spell out style properties rather than spreading objects; if a
+  runtime spread is unavoidable, add a
+  `// eslint-disable-next-line tasty/no-style-spread -- reason` comment directly
+  above it. `tastyStatic()` cannot use spreads.
+
+## 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`                                                                                |
+
+Use logical category styles when layout must follow writing mode or direction: `blockSize`/`inlineSize`, `blockPadding`/`inlinePadding`, `blockMargin`/`inlineMargin`, `blockInset`/`inlineInset`, `blockScrollMargin`/`inlineScrollMargin`, `blockScrollPadding`/`inlineScrollPadding`, and `blockBorder`/`inlineBorder`. Use `start`/`end` value modifiers; do not replace them with physical sides. Native logical CSS properties remain valid as ordinary keys when an individual declaration is needed.
+
+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 custom property _name_ (not its value) — inside `transition`          |
+| `$$name(…)`           | call a CSS `@function` declared via `@function`, `useFunction`, or config |
+
+- ❌ `#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.
+- Names are case-sensitive and start lowercase — `$myVar` → `--myVar`; a leading capital folds (`$Foo` → `--foo`). Prefer kebab-case.
+- A `$name` reference is untyped: it fills the first free slot in a shorthand (`border: '1bw $my-style'` → the line style). Write colors as `#name`; `$name-color` is a fallback for pointing at a raw CSS custom property that holds a color.
+- `preset` and `transition` take token _names_, not values, so a `$name` cannot stand in for one (it warns in dev and is ignored).
+
+### 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`, `fade`, `preset`, `font`, `scrollbar`, `scrollMargin`, `scrollPadding`, and the enhanced logical category styles listed above, plus `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). A group that names **direction** modifiers takes a **single** value, applied to every direction it names — per-side values come from comma groups. A group naming no direction keeps plain CSS shorthand order (1–4 values). (`inset` + `dock` is the one exception: a second value insets the spanned sides.) 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` |
+| logical axis spacing/inset styles    | `start` `end`                                                                                              |
+| `blockBorder`, `inlineBorder`         | `start` `end` + the border style keywords above                                                            |
+| `outline`                            | the style keywords above                                                                                   |
+| `radius`                             | `top` `right` `bottom` `left` + shapes `round` `ellipse` `leaf` `backleaf`                                 |
+| `width`, `height`, `blockSize`, `inlineSize` | `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'`
+- ❌ `padding: '2x 4x top right'` — a directional group takes one value, so `4x` is dropped → ✅ `padding: '2x top, 4x right'`
+- ❌ `fade: '3x 1x top bottom'` → ✅ `fade: '3x top, 1x bottom'`
+
+Value-only properties reject both colors and modifiers: `gap`, `columnGap`, `rowGap`, `opacity`, `zIndex`, `order`, `flexGrow`, `flexShrink`, `flexBasis`, `aspectRatio`, `lineClamp`, and `tabSize`. Logical axis category styles accept one or two values in start/end order and the `start`, `end`, and `longhand` modifiers. `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'`
+
+Omit the duration to use `$fill-transition` with `$transition` as fallback, or
+use a duration token explicitly (`transition: 'fill $transition'`). Avoid raw
+time values in duration slots. An explicit zero can be useful to disable motion.
+
+Use `transition` when defining a complete transition, and the native CSS
+`animation` shorthand when defining a complete animation. Tasty accepts
+`animation` directly and tracks local keyframes referenced by it; no special
+animation handler is needed. Use duration tokens in either form. Keep
+`transitionDuration`, `animationDuration`, and other motion longhands when a
+state or extension changes only one part of an existing effect. A shorthand
+resets omitted parts, including an animation's timeline and range.
+
+## 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.
+6. **Write keys Tasty can fully read.** Names start with a letter (a single letter is fine: `x` → `[data-x]`); join states with an operator (`hovered & focused`, not `hovered focused`); no space between `@media` and `(`. Tasty warns (`INVALID_STATE_KEY`) and skips what it cannot read.
+7. **Prefer automatic native states:** use `disabled` and `checked` in Tasty component styles instead of `[disabled]` and `[checked]`. The concise states track the corresponding native prop or attribute automatically.
+
+```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, … } }`                                                                             |
+| `@property`      | `{ '$name': { syntax, inherits, initialValue } }`                                                           |
+| `@font-face`     | `{ 'Family Name': descriptors \| descriptors[] }`                                                           |
+| `@counter-style` | `{ name: descriptors }`                                                                                     |
+| `@function`      | `{ '$$name': { args, returns?, result, '$local'? } }`                                                       |
+| `recipe`         | a **string** of configured recipe names: `'card elevated'`, `'reset input / autofill'`, `'none / disabled'` |
+
+`recipe` resolves on the component root and independently in each sub-element's styles: `styles: { Panel: { recipe: 'card elevated' } }` is supported. Configured recipe definitions must be flat and cannot contain their own `recipe` key; references inside recipe values are not recursively expanded. Compose names where the recipe is applied, not inside `configure({ recipes })`. See [Recipes](dsl.md#recipes).
+
+At-rule keys match the real CSS at-rule names, so they are kebab-case, not camelCase. Inside `@function`, the callable is `$$name` but its parameters and local variables are `$name`:
+
+```jsx
+styles: {
+  '@function': { $$negative: { args: ['$value'], result: '(-1 * $value)' } },
+  margin: '$$negative(2x) top',
+}
+```
+
+## 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'`.
+- Logical category styles keep native `block`/`inline` declarations and accept `start`/`end`, never physical direction modifiers.
+- 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.
+- At-rule keys are kebab-case (`@property`, `@font-face`, `@counter-style`, `@function`); `@function` names use `$$`, their args and locals use `$`.
+- Values are static; dynamic behavior comes from `mods` / `tokens` / `styleProps`.