@tenphi/eslint-plugin-tasty 1.18.0 → 1.19.0

package/README.md

@@ -226,59 +226,61 @@ not matched.
 
 ## Rules
 
+Every rule has a page in [`docs/rules/`](docs/rules/) with examples and options. The pages ship in the package.
+
 ### Recommended
 
 | Rule | Severity | Description |
 |------|----------|-------------|
-| `tasty/known-property` | warn | Unknown style property names (checked against the full MDN/W3C CSS property set) |
-| `tasty/valid-value` | error | Malformed style values (unbalanced parens, !important) |
-| `tasty/valid-color-token` | error | Invalid color token syntax or unknown tokens |
-| `tasty/valid-custom-unit` | error | Unknown custom units |
-| `tasty/valid-boolean-property` | error | `true` on properties that don't support it, in a state map as well as on a direct value. Includes `fill`, which tasty documents as taking `true` but currently renders as `background-color: true` |
-| `tasty/valid-state-key` | error | Invalid state key syntax in style mappings (including misuse of the `_` fallback floor) |
-| `tasty/valid-styles-structure` | error | Invalid styles object structure, and the v2 at-rule key spellings (auto-fixable) |
-| `tasty/no-nested-state-map` | error | Nested state maps (not supported) |
-| `tasty/no-important` | error | `!important` usage (breaks tasty specificity) |
-| `tasty/valid-sub-element` | error | Sub-element values must be style objects; `$` selectors must not target the root element ([details](docs/rules/valid-sub-element.md)) |
-| `tasty/valid-directional-modifier` | error | Directional modifiers on wrong properties, and more than one value in a group that names directions. Physical properties take `top`/`right`/`bottom`/`left`, logical ones `start`/`end`, and mixing the two is reported in either direction |
-| `tasty/valid-radius-shape` | error | Unknown radius shape keywords |
-| `tasty/valid-preset` | error | Unknown preset names |
-| `tasty/valid-recipe` | error | Unknown recipe names |
-| `tasty/valid-transition` | warn | Unknown transition names, and camelCase CSS names that Tasty would emit as no property (`gridTemplateColumns` → `grid-template-columns`) |
-| `tasty/no-nested-selector` | warn | `&`-prefixed nested selectors (use sub-elements) |
-| `tasty/no-state-in-selector` | warn | Pseudo-class and attribute conditions in sub-element `$` selectors; put conditions in property state maps ([details](docs/rules/no-state-in-selector.md)) |
-| `tasty/prefer-element-selector` | warn | Prefer element names such as `Primary > Search` over exact `data-element` attributes in sub-element `$` selectors (safely autofixable; [details](docs/rules/prefer-element-selector.md)) |
-| `tasty/static-no-dynamic-values` | error | Dynamic values in `tastyStatic()` |
-| `tasty/static-valid-selector` | error | Invalid selector in `tastyStatic(selector, ...)` |
-| `tasty/require-default-state` | error | Missing default (`''`) or fallback floor (`_`) key in state mappings (skipped for extending calls and maps that spread another) |
-| `tasty/no-own-at-root` | warn | `@own()` used at root level where it is redundant (not in shared style constants, which may be spread into a sub-element) |
-| `tasty/no-ignored-pseudo-element-state` | error | States Tasty ignores on a pseudo-element, such as `@own([open])` on `$: 'a::before'`: attributes, modifiers, classes, and tree-structural pseudo-classes ([details](docs/rules/no-ignored-pseudo-element-state.md)) |
-| `tasty/valid-default-state-order` | warn | Misplaced default (`''`) or redundant `''` when only `_` is present |
-| `tasty/prefer-shorthand-property` | warn | Use Tasty shorthand instead of native CSS properties (`backgroundColor` → `fill`, `paddingBlock` → `blockPadding`, etc.). Report-only warnings explain how to override one part through a token, with concrete min/max dimension examples. Extension warnings point at the base component and are skipped over bases you cannot edit (see `ownedSources`; [details](docs/rules/prefer-shorthand-property.md)) |
-| `tasty/no-raw-color-values` | warn | Raw hex/rgb/`okhsl`/`okhst`/`oklch`/named colors instead of `#color` tokens |
-| `tasty/no-raw-transition-duration` | warn | Hardcoded `transition` duration (`fill 0.2s`) in Tasty styles or a local `tasty()` component's `transition` prop. Suggests a configured duration token or the implicit per-name timing; zero and delays are left alone |
-| `tasty/no-runtime-styles-mutation` | warn | Render-time JavaScript in Tasty style values (props, state, hook results, parameters, local bindings, calls, computed keys); use states and tokens instead. A style object no function encloses is built once at load and not checked; inside a function, module-scope constants, imports, `undefined` and static `mergeStyles(...)` calls are fixed at load and allowed |
-| `tasty/no-style-spread` | warn | Object or array spreads inside runtime Tasty styles; recommends `mergeStyles` for multiple root spreads; intentional spreads need a per-line suppression and reason |
-| `tasty/no-style-prop` | warn | `style` on recognized Tasty components; use token references and the `tokens` prop. The `elements` option covers every component or element, so it can replace React's `style` restriction; `values: 'static'` reports only static styles. Tasty syntax in `style` is always reported ([details](docs/rules/no-style-prop.md)) |
-| `tasty/no-classname-prop` | warn | `className` on recognized Tasty components; keep styling in Tasty or use `data-element` for sub-elements ([details](docs/rules/no-classname-prop.md)) |
-| `tasty/no-styles-prop` | warn | Instance `styles` on recognized Tasty components; use `tokens`, `mods`, exposed props/variants, or `tasty(Component, { styles })` ([details](docs/rules/no-styles-prop.md)) |
-| `tasty/no-protected-restyle` | warn | Restyling a design system's `protectedComponents`: instance `styles` and `*Styles`, appearance style props, and `tasty()` wrappers that restyle them, followed through aliases, wrappers and relative re-exports. `usages: 'wrappers'` reports only the wrappers. Inactive without the config ([details](docs/rules/no-protected-restyle.md)) |
-| `tasty/consistent-token-usage` | warn | Nonzero raw pixel lengths, including compounds, expressions and numeric inputs to enhanced length handlers. The `pixels: 'replaceable'` option reports only lengths with an exact unit, such as `8px` → `1x` ([details](docs/rules/consistent-token-usage.md)) |
-| `tasty/prefer-auto-calc` | warn | `calc(...)` instead of Tasty auto-calc `(...)` |
-| `tasty/prefer-state-negation` | warn | Top-level `:not(...)` in state keys instead of the `!` prefix (autofixable; nested CSS selectors stay intact) |
-| `tasty/prefer-custom-property-syntax` | warn | `var(--prop)` / `$x-color` / `transparent` / `currentColor` instead of `$prop` / `#color` / `#clear` / `#current` |
-| `tasty/prefer-hide` | warn | `display: 'none'` instead of `hide: true` |
-| `tasty/prefer-fill-mix` | warn | Deprecated two-color `fill`, space-separated (`'#surface #dark.04'`) or comma-mixed (`'#dark 4%, #surface'`), instead of a compound color (`'#surface+#dark.04'`) or `color-mix()`, autofixed when the result is the same color; mix parts weighted by their opacity (`'#dark.04, #surface'`). Needs `@tenphi/tasty` 3.15, and 3.16 for compound colors ([details](docs/rules/prefer-fill-mix.md)) |
-| `tasty/prefer-directional-shorthand` | warn | 4-value `margin`/`padding`/`inset`/`radius`/`fade`/`border` with placeholder positions instead of directional form |
-| `tasty/prefer-longhand-property` | error | Lossy `flex` shorthand instead of `flexGrow` / `flexShrink` / `flexBasis` |
+| [`tasty/known-property`](docs/rules/known-property.md) | warn | Unknown style property names (checked against the full MDN/W3C CSS property set) |
+| [`tasty/valid-value`](docs/rules/valid-value.md) | error | Malformed style values (unbalanced parens, !important) |
+| [`tasty/valid-color-token`](docs/rules/valid-color-token.md) | error | Invalid color token syntax or unknown tokens |
+| [`tasty/valid-custom-unit`](docs/rules/valid-custom-unit.md) | error | Unknown custom units |
+| [`tasty/valid-boolean-property`](docs/rules/valid-boolean-property.md) | error | `true` on properties that don't support it, in a state map as well as on a direct value. Includes `fill`, which tasty documents as taking `true` but currently renders as `background-color: true` |
+| [`tasty/valid-state-key`](docs/rules/valid-state-key.md) | error | Invalid state key syntax in style mappings (including misuse of the `_` fallback floor) |
+| [`tasty/valid-styles-structure`](docs/rules/valid-styles-structure.md) | error | Invalid styles object structure, and the v2 at-rule key spellings (auto-fixable) |
+| [`tasty/no-nested-state-map`](docs/rules/no-nested-state-map.md) | error | Nested state maps (not supported) |
+| [`tasty/no-important`](docs/rules/no-important.md) | error | `!important` usage (breaks tasty specificity) |
+| [`tasty/valid-sub-element`](docs/rules/valid-sub-element.md) | error | Sub-element values must be style objects; `$` selectors must not target the root element |
+| [`tasty/valid-directional-modifier`](docs/rules/valid-directional-modifier.md) | error | Directional modifiers on wrong properties, and more than one value in a group that names directions. Physical properties take `top`/`right`/`bottom`/`left`, logical ones `start`/`end`, and mixing the two is reported in either direction |
+| [`tasty/valid-radius-shape`](docs/rules/valid-radius-shape.md) | error | Unknown radius shape keywords |
+| [`tasty/valid-preset`](docs/rules/valid-preset.md) | error | Unknown preset names |
+| [`tasty/valid-recipe`](docs/rules/valid-recipe.md) | error | Unknown recipe names |
+| [`tasty/valid-transition`](docs/rules/valid-transition.md) | warn | Unknown transition names, and camelCase CSS names that Tasty would emit as no property (`gridTemplateColumns` → `grid-template-columns`) |
+| [`tasty/no-nested-selector`](docs/rules/no-nested-selector.md) | warn | `&`-prefixed nested selectors (use sub-elements) |
+| [`tasty/no-state-in-selector`](docs/rules/no-state-in-selector.md) | warn | Pseudo-class and attribute conditions in sub-element `$` selectors; put conditions in property state maps |
+| [`tasty/prefer-element-selector`](docs/rules/prefer-element-selector.md) | warn | Prefer element names such as `Primary > Search` over exact `data-element` attributes in sub-element `$` selectors (safely autofixable) |
+| [`tasty/static-no-dynamic-values`](docs/rules/static-no-dynamic-values.md) | error | Dynamic values in `tastyStatic()` |
+| [`tasty/static-valid-selector`](docs/rules/static-valid-selector.md) | error | Invalid selector in `tastyStatic(selector, ...)` |
+| [`tasty/require-default-state`](docs/rules/require-default-state.md) | error | Missing default (`''`) or fallback floor (`_`) key in state mappings (skipped for extending calls and maps that spread another) |
+| [`tasty/no-own-at-root`](docs/rules/no-own-at-root.md) | warn | `@own()` used at root level where it is redundant (not in shared style constants, which may be spread into a sub-element) |
+| [`tasty/no-ignored-pseudo-element-state`](docs/rules/no-ignored-pseudo-element-state.md) | error | States Tasty ignores on a pseudo-element, such as `@own([open])` on `$: 'a::before'`: attributes, modifiers, classes, and tree-structural pseudo-classes |
+| [`tasty/valid-default-state-order`](docs/rules/valid-default-state-order.md) | warn | Misplaced default (`''`) or redundant `''` when only `_` is present |
+| [`tasty/prefer-shorthand-property`](docs/rules/prefer-shorthand-property.md) | warn | Use Tasty shorthand instead of native CSS properties (`backgroundColor` → `fill`, `paddingBlock` → `blockPadding`, etc.). Report-only warnings explain how to override one part through a token, with concrete min/max dimension examples. Extension warnings point at the base component and are skipped over bases you cannot edit (see `ownedSources`) |
+| [`tasty/no-raw-color-values`](docs/rules/no-raw-color-values.md) | warn | Raw hex/rgb/`okhsl`/`okhst`/`oklch`/named colors instead of `#color` tokens |
+| [`tasty/no-raw-transition-duration`](docs/rules/no-raw-transition-duration.md) | warn | Hardcoded `transition` duration (`fill 0.2s`) in Tasty styles or a local `tasty()` component's `transition` prop. Suggests a configured duration token or the implicit per-name timing; zero and delays are left alone |
+| [`tasty/no-runtime-styles-mutation`](docs/rules/no-runtime-styles-mutation.md) | warn | Render-time JavaScript in Tasty style values (props, state, hook results, parameters, local bindings, calls, computed keys); use states and tokens instead. A style object no function encloses is built once at load and not checked; inside a function, module-scope constants, imports, `undefined` and static `mergeStyles(...)` calls are fixed at load and allowed |
+| [`tasty/no-style-spread`](docs/rules/no-style-spread.md) | warn | Object or array spreads inside runtime Tasty styles; recommends `mergeStyles` for multiple root spreads; intentional spreads need a per-line suppression and reason |
+| [`tasty/no-style-prop`](docs/rules/no-style-prop.md) | warn | `style` on recognized Tasty components; use token references and the `tokens` prop. The `elements` option covers every component or element, so it can replace React's `style` restriction; `values: 'static'` reports only static styles. Tasty syntax in `style` is always reported |
+| [`tasty/no-classname-prop`](docs/rules/no-classname-prop.md) | warn | `className` on recognized Tasty components; keep styling in Tasty or use `data-element` for sub-elements |
+| [`tasty/no-styles-prop`](docs/rules/no-styles-prop.md) | warn | Instance `styles` on recognized Tasty components; use `tokens`, `mods`, exposed props/variants, or `tasty(Component, { styles })` |
+| [`tasty/no-protected-restyle`](docs/rules/no-protected-restyle.md) | warn | Restyling a design system's `protectedComponents`: instance `styles` and `*Styles`, appearance style props, and `tasty()` wrappers that restyle them, followed through aliases, wrappers and relative re-exports. `usages: 'wrappers'` reports only the wrappers. Inactive without the config |
+| [`tasty/consistent-token-usage`](docs/rules/consistent-token-usage.md) | warn | Nonzero raw pixel lengths, including compounds, expressions and numeric inputs to enhanced length handlers. The `pixels: 'replaceable'` option reports only lengths with an exact unit, such as `8px` → `1x` |
+| [`tasty/prefer-auto-calc`](docs/rules/prefer-auto-calc.md) | warn | `calc(...)` instead of Tasty auto-calc `(...)` |
+| [`tasty/prefer-state-negation`](docs/rules/prefer-state-negation.md) | warn | Top-level `:not(...)` in state keys instead of the `!` prefix (autofixable; nested CSS selectors stay intact) |
+| [`tasty/prefer-custom-property-syntax`](docs/rules/prefer-custom-property-syntax.md) | warn | `var(--prop)` / `$x-color` / `transparent` / `currentColor` instead of `$prop` / `#color` / `#clear` / `#current` |
+| [`tasty/prefer-hide`](docs/rules/prefer-hide.md) | warn | `display: 'none'` instead of `hide: true` |
+| [`tasty/prefer-fill-mix`](docs/rules/prefer-fill-mix.md) | warn | Deprecated two-color `fill`, space-separated (`'#surface #dark.04'`) or comma-mixed (`'#dark 4%, #surface'`), instead of a compound color (`'#surface+#dark.04'`) or `color-mix()`, autofixed when the result is the same color; mix parts weighted by their opacity (`'#dark.04, #surface'`). Needs `@tenphi/tasty` 3.15, and 3.16 for compound colors |
+| [`tasty/prefer-directional-shorthand`](docs/rules/prefer-directional-shorthand.md) | warn | 4-value `margin`/`padding`/`inset`/`radius`/`fade`/`border` with placeholder positions instead of directional form |
+| [`tasty/prefer-longhand-property`](docs/rules/prefer-longhand-property.md) | error | Lossy `flex` shorthand instead of `flexGrow` / `flexShrink` / `flexBasis` |
 
 ### Strict (includes all recommended rules)
 
 | Rule | Severity | Description |
 |------|----------|-------------|
-| `tasty/valid-custom-property` | warn | Unknown `$name` custom properties |
-| `tasty/valid-state-definition` | warn | Invalid state definition values in `configure()` or `tasty.config` |
-| `tasty/no-unknown-state-alias` | warn | Unknown `@name` state aliases |
+| [`tasty/valid-custom-property`](docs/rules/valid-custom-property.md) | warn | Unknown `$name` custom properties |
+| [`tasty/valid-state-definition`](docs/rules/valid-state-definition.md) | warn | Invalid state definition values in `configure()` or `tasty.config` |
+| [`tasty/no-unknown-state-alias`](docs/rules/no-unknown-state-alias.md) | warn | Unknown `@name` state aliases |
 
 ### Structural selectors and state maps
 
@@ -360,7 +362,7 @@ suppressed, run ESLint with `--max-warnings=0`.
 
 ### Optional motion duration rule
 
-Enable `tasty/no-raw-motion-duration` as a warning if your design system uses
+Enable [`tasty/no-raw-motion-duration`](docs/rules/no-raw-motion-duration.md) as a warning if your design system uses
 tokens for animation timing and explicit CSS durations:
 
 ```js
@@ -635,6 +637,23 @@ your installed version — and on 3.7 and below `blockPadding` is not a style ta
 (an unhandled camelCase key renders through to `block-padding`, which the browser drops).
 The peer range floor is 3.8.0 for that reason.
 
+## AI agents
+
+The package ships an agent harness for [harnesspm](https://www.npmjs.com/package/@tenphi/harnesspm), as plugin `tasty-lint`. In a project that uses harnesspm, agents get:
+
+- a short always-on rule: lint the files you change and fix every `tasty/*` problem;
+- the rule pages of the installed version, in the docs index;
+- `npx harnesspm run tasty-lint:check <files> [--strict] [--json]`, which runs only the `tasty/*` rules with the project's `tasty.config.*` and prints each problem with its rule's page;
+- a Claude Code hook that lints each file the agent edits, when it imports Tasty or a configured `importSources` module, and hands the new problems back to the agent.
+
+The tool and the hook run only in projects that trust the package, in `harnesspm.json`:
+
+```json
+{ "trust": { "@tenphi/eslint-plugin-tasty": true } }
+```
+
+They need `eslint`, and `typescript-eslint` or `@typescript-eslint/parser` for TypeScript files. They do not read the project's ESLint or Oxlint config, so other plugins, rule options and settings such as `typeAwareJSX` do not apply there.
+
 ## License
 
 MIT

package/docs/rules/consistent-token-usage.md

@@ -0,0 +1,72 @@
+# tasty/consistent-token-usage
+
+Warn about pixel lengths in Tasty styles.
+
+**Presets:** warning in recommended and strict. **Fix:** editor suggestions.
+
+## Why
+
+A design system sizes things with its units (`x`, `r`, `bw`) and tokens, so a layout follows its scale. A raw `8px` stays put when the scale changes.
+
+## Checks
+
+The rule reports every nonzero pixel length in recognized style objects and JSX
+style props: compound values, comma-separated groups, function arguments, and
+numeric inputs to enhanced handlers that convert them to pixels, such as
+`gap={17}`. Unitless properties such as `opacity` and `zIndex` are not checked.
+Zero, token definitions (`$name` and `#name` keys), quoted CSS text, and URLs
+are allowed.
+
+A pixel length with an exact unit gets a suggestion that replaces it:
+
+| Pixels                      | Replacement     |
+| --------------------------- | --------------- |
+| `8px` to `64px`, step `8px` | `1x` to `8x`    |
+| `6px` in `radius`           | `1r`            |
+| `1px` in a border width     | `1bw`           |
+
+These replacements assume Tasty's default scale. Review them against your
+design system. Any other pixel length, such as `17px` or `520px`, is reported
+without a suggestion: the rule does not invent a token. A `fontSize`,
+`lineHeight` or `letterSpacing` length never gets an `x` suggestion: it is on
+the type scale, which presets set, and `x` is the spacing scale.
+
+A suggestion keeps the rest of the value as written. It is withheld when
+JavaScript escapes or JSX entities make the source differ from the value.
+
+```tsx
+import { tasty } from '@tenphi/tasty';
+
+// ❌ '1x' and '1bw' replace these exactly.
+const Card = tasty({ styles: { padding: '8px', border: '1px solid #border' } });
+
+// ✅ Preferred.
+const Card = tasty({ styles: { padding: '1x', border: '1bw solid #border' } });
+```
+
+For an intentional pixel length, add an explicit local ignore with a reason:
+
+```tsx
+const Rule = tasty({
+  styles: {
+    // eslint-disable-next-line tasty/consistent-token-usage -- aligns with the 3px focus ring
+    inset: '-3px',
+  },
+});
+```
+
+## Options
+
+```js
+'tasty/consistent-token-usage': ['error', { pixels: 'replaceable' }],
+```
+
+| `pixels`          | Reports                                                                        |
+| ----------------- | ------------------------------------------------------------------------------ |
+| `'all'` (default) | Every nonzero pixel length                                                     |
+| `'replaceable'`   | Only a pixel length with an exact unit in the table above, with its suggestion |
+
+Use `'replaceable'` when your layout sizes are in pixels on purpose, such as
+`width: 'max 520px'`. The rule then reports only a length that a unit replaces
+exactly, so every finding has a fix and the rule can run as an error. In
+`padding: '8px 17px'` it reports `8px` and leaves `17px` alone.

package/docs/rules/known-property.md

@@ -0,0 +1,55 @@
+# tasty/known-property
+
+Reports a style property name that is neither a Tasty style nor a CSS property, such as a typo.
+
+**Presets:** warning in recommended and strict. **Fix:** none.
+
+## Why
+
+Tasty passes an unknown key through as a CSS declaration, which the browser drops. A typo such as `colour` or `boarder` fails silently at runtime.
+
+## Examples
+
+```js
+// ✅ Valid
+tasty({ styles: { fill: '#purple', padding: '2x' } });
+
+// ❌ Unknown style property 'colour'
+tasty({ styles: { colour: '#purple' } });
+
+// ❌ Unknown style property 'boarder'
+tasty({ styles: { boarder: true } });
+```
+
+## What counts as known
+
+- **Tasty styles:** `display`, `font`, `preset`, `hide`, `whiteSpace`, `opacity`, `transition`, `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `margin`, `inset`, `position`, `padding`, `overflow`, `scrollbar`, `textAlign`, `scrollMargin`, `scrollPadding`, `border`, `radius`, `shadow`, `outline`, `color`, `fill`, `svgFill`, `fade`, `image`, `textTransform`, `fontWeight`, `fontStyle`, `width`, `height`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`, `flow`, `placeItems`, `placeContent`, `alignItems`, `alignContent`, `justifyItems`, `justifyContent`, `align`, `justify`, `gap`, `columnGap`, `rowGap`, `gridColumns`, `gridRows`, `gridTemplate`, `gridAreas`, `recipe`, `textOverflow`.
+- **Enhanced logical styles** (Tasty 3.8 and later), one per axis and category:
+
+  | Category | Block axis | Inline axis |
+  | --- | --- | --- |
+  | Size | `blockSize` (+ `minBlockSize`, `maxBlockSize`) | `inlineSize` (+ `minInlineSize`, `maxInlineSize`) |
+  | Padding | `blockPadding` | `inlinePadding` |
+  | Margin | `blockMargin` | `inlineMargin` |
+  | Inset | `blockInset` | `inlineInset` |
+  | Scroll margin | `blockScrollMargin` | `inlineScrollMargin` |
+  | Scroll padding | `blockScrollPadding` | `inlineScrollPadding` |
+  | Border | `blockBorder` | `inlineBorder` |
+
+- **CSS properties.** The list is generated from `known-css-properties`, the MDN/W3C dataset that stylelint uses for `property-no-unknown`. It covers modern properties (`maskSize`, `anchorName`, `fieldSizing`, `viewTransitionName`, `textBox`) and SVG presentation and geometry properties. A small hand-kept supplement adds properties that ship before the dataset has them. At-rule descriptors that the specs (through `@webref/css`) do not also define as properties, such as `src`, `prefix`, `suffix`, `syntax`, `symbols` and `unicodeRange`, are left out: a style rule cannot declare them. Regenerate the list with `pnpm generate:css-properties`.
+- **Names from your config:** the `styles` list in `tasty.config.*`, for handlers added through `configure({ handlers })`.
+
+The native logical spellings (`paddingBlock`, `insetInlineStart`, `borderBlockColor`, …) stay valid as CSS properties. They are no longer Tasty styles: Tasty 3.8 stopped reading `paddingBlock`, `paddingInline`, `insetBlock` and `insetInline` in its physical handlers. [`tasty/prefer-shorthand-property`](prefer-shorthand-property.md) reports them with a migration.
+
+## Keys this rule skips
+
+- A key that starts with an uppercase letter is a sub-element ([`tasty/valid-sub-element`](valid-sub-element.md)).
+- A key that starts with `@` is an at-rule key (`@keyframes`, `@property`, …) or a local state alias.
+- A key that starts with `$` or `$$` defines a custom property (`$name` is `--name`).
+- A key that starts with `#` or `##` defines a color token (`#name` is `--name-color`).
+- `--name` custom properties and vendor-prefixed properties (`-webkit-…`).
+- A key that starts with `&` is a nested selector, which [`tasty/no-nested-selector`](no-nested-selector.md) reports.
+
+## Options
+
+None.

package/docs/rules/no-classname-prop.md

@@ -0,0 +1,60 @@
+# tasty/no-classname-prop
+
+Warn about `className` on recognized Tasty components.
+
+**Presets:** warning in recommended and strict. **Fix:** none.
+
+Keep styling in Tasty rather than attaching external styling classes. When a
+class identifies a sub-element for its parent to style, replace that identity
+with `data-element="Name"` and a matching capitalized sub-element key:
+
+```tsx
+import { tasty } from '@tenphi/tasty';
+
+const Card = tasty({ styles: { Body: { padding: '2x' } } });
+const Box = tasty({ as: 'div' });
+
+// ❌ Avoid external class-based styling.
+<Card>
+  <Box className="card-body" />
+</Card>;
+
+// ✅ Preferred: Card's Body styles target this element.
+<Card>
+  <Box data-element="Body" />
+</Card>;
+```
+
+For general root styling, define styles on the component or use a styled wrapper.
+`data-element` is an identity for parent sub-element styling, not a replacement
+for an arbitrary list of CSS classes.
+
+The rule checks every explicit attribute value and visible `className` keys in
+inline object spreads. It has no automatic fix because external classes can have
+multiple styling or behavior roles.
+
+A third-party library may require a class for its stylesheet or behavior. Keep
+that integration and acknowledge the exception with an explicit local ignore and
+a reason:
+
+```tsx
+const libraryElement = (
+  // eslint-disable-next-line tasty/no-classname-prop -- library stylesheet requires this class
+  <Box className={libraryClassName} />
+);
+```
+
+Place the directive immediately before the reported attribute line. It suppresses
+only this rule for that line. The warning message includes this exception path;
+the plugin does not silently exempt library-provided values or enforce reasons.
+
+Recognition uses local `const` Tasty/configured-options factory results, their
+`const` aliases/sub-elements, and imports from `importSources`. Exports of relative modules (`import { Panel } from './styled'`) count when they
+resolve to one of these, through re-exports too; following them needs the
+`typescript` package. Native elements,
+unrelated components, type-only imports, shadowed bindings, mutable aliases, and
+opaque spread bindings are excluded.
+
+## Options
+
+None.

package/docs/rules/no-ignored-pseudo-element-state.md

@@ -0,0 +1,97 @@
+# tasty/no-ignored-pseudo-element-state
+
+Report states that Tasty ignores because they test a pseudo-element for
+something it cannot have. The reported state never applies.
+
+**Presets:** error in recommended and strict. **Fix:** none.
+
+When a sub-element's `$` ends in a pseudo-element, Tasty applies `@own(...)` to
+the pseudo-element itself: `$: '@::part(label)'` with `@own(:focus)` becomes
+`::part(label):where(:focus)`. A pseudo-element has no attributes, classes, IDs,
+or place in the DOM tree, so a state that tests one of those can never match.
+Tasty drops such a state at runtime with a `PSEUDO_ELEMENT_STATE_IGNORED`
+warning. This rule reports the same state keys while you edit.
+
+## Reported
+
+```js
+const Pagination = tasty({
+  styles: {
+    NextArrow: {
+      $: 'a::before',
+      content: {
+        '': 'none',
+        '@own([rel="next"])': '"→"', // attributes
+      },
+    },
+    Marker: {
+      $: 'li::marker',
+      color: {
+        '': '#text',
+        '@own(:last-child)': '#accent', // position in the DOM tree
+        '@own(selected)': '#active', // modifiers
+      },
+    },
+  },
+});
+```
+
+Tasty ignores these states on a pseudo-element:
+
+- Modifiers: `@own(hovered)`, `@own(theme=dark)`.
+- Attributes: `@own([open])`, `@own(:not([open]))`.
+- Classes and IDs: `@own(.active)`.
+- Tree-structural pseudo-classes: `:root`, `:scope`, `:empty`, `:has()`,
+  `:first-child`, `:last-child`, `:only-child`, their `-of-type` forms, and
+  `:nth-*()`.
+- Any key that combines one of these with other states, such as
+  `@own(:hover | [open])` or `:focus & @own([open])`. Tasty drops the whole key.
+
+## Preferred
+
+Write a condition on the element the pseudo-element belongs to in `$`, before
+the pseudo-element. `tasty/no-state-in-selector` accepts these selectors.
+
+```js
+const Pagination = tasty({
+  styles: {
+    NextArrow: { $: 'a[rel="next"]::before', content: '"→"' },
+    Marker: { $: 'li:last-child::marker', color: '#accent' },
+    Label: {
+      $: '@::part(label)',
+      color: { '': '#text', '@own(:hover)': '#active' },
+    },
+  },
+});
+```
+
+A pseudo-element can be in a pseudo-class state such as `:hover` or `:focus`, so
+those still belong in `@own(...)`. Root states, `@parent(...)`, `@root(...)`, and
+at-rule conditions describe other elements and are not reported.
+
+## Where it applies
+
+- A sub-element `$` item that ends in a pseudo-element: the first `::name`, or a
+  legacy `:before`, `:after`, `:first-line`, or `:first-letter`, in its last
+  compound. Each item of a `$` list is judged on its own. With
+  `$: 'summary::marker, summary'`, Tasty ignores `@own([open])` only on
+  `summary::marker`, and the message names that item.
+- `&` keys and `&`-prefixed `$` values extend their owner's selector. `'&::before'`
+  at the root, and `'&:hover'` under `$: 'a::before'`, are pseudo-element targets.
+- A selector-mode call whose literal selector ends in a pseudo-element, such as
+  `useGlobalStyles('.card::before', styles)` or `tastyStatic('.card::before',
+  styles)`. There, root states describe the pseudo-element too, so
+  `[data-on]`, `selected`, and `.dark` are reported, while `:hover` is not.
+
+## Limits
+
+- `@name` state aliases are not resolved. Tasty may still ignore a state an
+  alias expands to.
+- Dynamic `$` values and selector arguments are skipped. Malformed state keys
+  are left to `tasty/valid-state-key`.
+- The rule has no autofix. Moving a condition into `$` changes which element
+  every property of that sub-element applies to, so the author must choose.
+
+## Options
+
+None.

package/docs/rules/no-important.md

@@ -0,0 +1,25 @@
+# tasty/no-important
+
+Reports `!important` in a style value.
+
+**Presets:** error in recommended and strict. **Fix:** autofix (removes `!important`).
+
+## Why
+
+Tasty manages specificity itself, through doubled class selectors and the order of states. `!important` overrides that system: states and extensions can no longer win where they should.
+
+## Examples
+
+```js
+// ❌ Do not use !important in tasty styles.
+fill: '#red !important'
+
+// ✅ After the autofix
+fill: '#red'
+```
+
+To make a state win, give it a later place in the state map, or combine conditions in its key.
+
+## Options
+
+None.

package/docs/rules/no-nested-selector.md

@@ -0,0 +1,39 @@
+# tasty/no-nested-selector
+
+Reports `&`-prefixed nested selectors, such as `'& img'` or `'&:hover'`, as keys of a style object.
+
+**Presets:** error in recommended and strict. **Fix:** none.
+
+## Why
+
+Nested selectors are legacy syntax. Sub-elements (capitalized keys that target `data-element`) and state maps are more explicit and compose: Tasty resolves their priority, and `mergeStyles` and extensions merge them per key.
+
+## Examples
+
+```js
+// ❌ Avoid nested selectors. Use sub-element styling instead.
+tasty({
+  styles: {
+    '& img': { width: '100%' },
+    '&:hover': { fill: '#blue' },
+  },
+});
+
+// ✅ A sub-element
+tasty({
+  styles: {
+    Image: { width: '100%' },
+  },
+});
+
+// ✅ A state map for a pseudo-class
+tasty({
+  styles: {
+    fill: { '': '#white', ':hover': '#blue' },
+  },
+});
+```
+
+## Options
+
+None.

package/docs/rules/no-nested-state-map.md

@@ -0,0 +1,33 @@
+# tasty/no-nested-state-map
+
+Reports a state map inside another state map.
+
+**Presets:** error in recommended and strict. **Fix:** none.
+
+## Why
+
+A state map's keys are states and its values are style values. Tasty does not read a map as a value, so the nested map renders nothing. Combine the states in one key instead.
+
+## Examples
+
+```js
+// ❌ Nested state maps are not allowed. Use combined state keys instead.
+fill: {
+  '': '#white',
+  hovered: {
+    '': '#blue',
+    pressed: '#red',
+  },
+}
+
+// ✅ Combined states
+fill: {
+  '': '#white',
+  hovered: '#blue',
+  'hovered & pressed': '#red',
+}
+```
+
+## Options
+
+None.

package/docs/rules/no-own-at-root.md

@@ -0,0 +1,57 @@
+# tasty/no-own-at-root
+
+Reports `@own(...)` in a state key of the root styles, where it is redundant.
+
+**Presets:** warning in recommended and strict. **Fix:** autofix.
+
+## Why
+
+`@own(...)` says "this state belongs to the sub-element itself, not to the root". At the root, the element is the root, so `@own(:hover)` means the same as `:hover`. Writing it there suggests a difference that does not exist.
+
+## Examples
+
+```js
+// ❌ @own() is redundant outside sub-element styles.
+tasty({
+  styles: {
+    fill: { '': '#white', '@own(:hover)': '#blue' },
+  },
+});
+
+// ✅ After the autofix
+tasty({
+  styles: {
+    fill: { '': '#white', ':hover': '#blue' },
+  },
+});
+
+// ✅ In a sub-element, @own() is the sub-element's own state
+tasty({
+  styles: {
+    Icon: {
+      fill: { '': '#white', '@own(:hover)': '#blue' },
+    },
+  },
+});
+```
+
+## Autofix
+
+The fix unwraps every `@own(...)` term of the key and keeps a term with operators inside grouped:
+
+| Before | After |
+| --- | --- |
+| `'@parent(:hover) & !@own(:hover)'` | `'@parent(:hover) & !:hover'` |
+| `'@own(pin=start \| pin=end)'` | `'pin=start \| pin=end'` |
+| `'@own(hovered \| focused) & active'` | `'(hovered \| focused) & active'` |
+
+A key with a comma inside `@own(...)` is reported without a fix.
+
+## Not reported
+
+- Sub-element styles, at any depth.
+- Shared style objects, such as a `const CELL_STYLES: Styles = { … }` that may be spread into a sub-element, where `@own(...)` matters.
+
+## Options
+
+None.