@tenphi/eslint-plugin-tasty 1.18.0 → 1.19.0

package/docs/rules/no-protected-restyle.md

@@ -0,0 +1,192 @@
+# tasty/no-protected-restyle
+
+Warn when a design system's protected components are restyled rather than
+customized through their props. It does nothing until a `tasty.config.*` lists
+`protectedComponents`.
+
+**Presets:** warning in recommended and strict. **Fix:** none.
+
+A design system built on Tasty exposes `styles` and `*Styles` props on its
+components, but for most of them the look is a contract: a consumer picks a
+`type`, `theme` or `size` rather than restyling a `Button`. This rule lets the
+design system say which components those are, and asks an override to explain
+itself.
+
+## Configuration
+
+The design system ships the list in its own `tasty.config.*`, and consumers
+inherit it through `extends`:
+
+```ts
+// @my-org/ui tasty.config.ts
+import type { TastyValidationConfig } from '@tenphi/eslint-plugin-tasty';
+
+export default {
+  importSources: ['@my-org/ui'],
+  protectedComponents: [
+    {
+      source: '@my-org/ui',
+      exclude: ['Block', 'Flex', 'Grid', 'Space', 'Text', 'Title', '*Icon'],
+      allowedStyleProps: ['position', 'dimension'],
+    },
+  ],
+} satisfies TastyValidationConfig;
+```
+
+```ts
+// the consumer's tasty.config.ts
+export default {
+  extends: '@my-org/ui',
+};
+```
+
+| Key | Meaning |
+| --- | --- |
+| `source` | The package the components are imported from. `*` matches any run of characters. |
+| `include` | Exported names or member paths to protect. Defaults to every export. |
+| `exclude` | Exported names or member paths to leave open, usually layout and typography primitives. `*` matches any run of characters, so `*Icon` covers every icon. |
+| `allowedStyleProps` | Style props that place or size the root and stay allowed. `'position'` and `'dimension'` stand for Tasty's `POSITION_STYLES` (`gridArea`, `margin`, `inset`, `zIndex`, …) and `DIMENSION_STYLES` (`width`, `height`, `flex`, …); anything else is a property name. Defaults to none. |
+
+A component matches the first entry whose `source`, `include` and `exclude` fit
+it, so a second entry for the same source can give a few components their own
+`allowedStyleProps`. Entries from an extended config come first; a config can
+add its own, or set `protectedComponents: false` to drop the inherited ones.
+
+### Sub-components
+
+A sub-component such as `<Button.Primary>` follows the entry of the export it
+hangs off, which suits one that shares its parent's contract. Some are separate
+components attached for convenience, though: `Button.Group` may be a layout
+primitive. A name with a dot in `include` or `exclude` is a member path
+(`'Button.Group'`, `'Menu.*'`), and an entry that names a component's member
+path decides for it before any entry that matches only its export:
+
+```ts
+protectedComponents: [
+  {
+    source: '@my-org/ui',
+    exclude: ['Space', 'ButtonGroup', 'Button.Group'],
+    allowedStyleProps: ['position', 'dimension'],
+  },
+  // `Button.Split` gets its own allowance; `Button` and `Button.Primary` don't.
+  { source: '@my-org/ui', include: ['Button.Split'], allowedStyleProps: ['direction'] },
+],
+```
+
+```tsx
+<Button.Group gap="1x" flow="row" />; // passes: Button.Group is excluded
+<Button.Split direction="column" />; // passes
+<Button gap="1x" />; // reported: Button keeps its contract
+```
+
+The longest named path wins, so `'Button.Group'` also covers
+`<Button.Group.Item>`, and the first entry that names a path decides it:
+excluding the path leaves it open, including it protects it with that entry's
+`allowedStyleProps`. Patterns without a dot, `*` included, only ever match the
+export name.
+
+For `extends: '@my-org/ui'` to find the list, the package has to publish its
+`tasty.config.*` at the package root.
+
+The design system's own source imports its components by relative path, which
+does not match `source`, so the design system itself is not held to the rule.
+
+## Options
+
+```js
+'tasty/no-protected-restyle': ['error', { usages: 'wrappers' }],
+```
+
+| `usages` | Reports |
+| --- | --- |
+| `'all'` (default) | Instance `styles`, `*Styles` and style props, and `tasty()` wrappers |
+| `'wrappers'` | `tasty()` wrappers that restyle a protected component, and wrappers of those wrappers |
+
+A wrapper defines a restyled component once, and every use of it inherits the
+restyle. `'wrappers'` lets a project enforce the rule on those definitions while
+its instance overrides are still being worked through.
+
+## What it reports
+
+On a protected component:
+
+```tsx
+import { tasty } from '@tenphi/tasty';
+import { Button, ComboBox } from '@my-org/ui';
+
+// Instance styles: `styles` and every `*Styles` prop.
+<Button styles={{ fill: '#danger' }} />;
+<ComboBox inputStyles={{ padding: '2x' }} />;
+
+// Appearance style props.
+<Button fill="#danger" radius="round" />;
+
+// Wrappers that restyle it: `styles`, `variants`, or `*Styles` and appearance
+// style props among their default props.
+const DangerButton = tasty(Button, { styles: { fill: '#danger' } });
+
+// Wrappers of wrappers still restyle `Button`.
+const CopyButton = tasty(Button, { type: 'clear' });
+<CopyButton styles={{ fill: '#danger' }} />;
+tasty(CopyButton, { fill: '#danger' });
+```
+
+And not:
+
+```tsx
+// Its own props, tokens and mods.
+<Button type="primary" theme="danger" size="small" tokens={{ $gap: '1x' }} />;
+
+// Allowed style props, and root `styles` whose keys are all allowed.
+<Button width="100%" gridArea="actions" />;
+<Button styles={{ width: '100%', gridArea: 'actions' }} />;
+
+// A wrapper that only sets semantic defaults.
+const CopyButton = tasty(Button, { type: 'clear', size: 'small' });
+```
+
+Root `styles` passes only as an inline object whose every key is an allowed
+style prop. A sub-element key, a spread, or a variable holding the styles is
+reported. `*Styles` props style the component's inner elements, so they are
+always reported.
+
+A style prop is a Tasty style property or an entry in `config.styles`. Plain
+CSS property names are left out, because some of them (`size`, `orientation`)
+are common semantic props. With
+[`typeAwareJSX`](../../README.md#experimental-type-aware-jsx-props) on, a prop
+the component declares with its own type (such as a `position: 'before' |
+'after'` prop) is not a style prop either. Callbacks and JSX values are never
+style values.
+
+## Recognition
+
+A component resolves to the name its source exports it under, so:
+
+- an aliased import (`import { Button as UIButton }`) still counts;
+- a namespace member (`<UI.Button>`) is `Button`;
+- a sub-component (`<Text.Strong>`) follows `Text`, so excluding `Text` leaves
+  `Text.Strong` open too, unless an entry names the member path (see
+  [Sub-components](#sub-components));
+- `const` aliases and `tasty()` wrappers are followed, within the file and
+  across relative imports, along with relative re-exports and `export *` from a
+  protected source. Following relative modules needs the `typescript` package.
+
+Shadowed bindings, `let` aliases, type-only imports and native elements are not
+protected components.
+
+## Intentional overrides
+
+A justified override takes a reasoned disable on its line:
+
+```tsx
+// eslint-disable-next-line tasty/no-protected-restyle -- campaign banner needs the brand fill
+<Button fill="#brand" />;
+```
+
+## Relation to `no-styles-prop`
+
+`tasty/no-styles-prop` reports instance `styles` on every recognized Tasty
+component. Once a design system lists its protected components, this rule
+covers those with a message that names the component. A project that relies on
+it can turn `no-styles-prop` off, so layout primitives keep `styles` as their
+expected API.

package/docs/rules/no-raw-color-values.md

@@ -0,0 +1,49 @@
+# tasty/no-raw-color-values
+
+Reports raw colors in style values: hex colors, color functions such as `rgb()` or `okhsl()`, and named colors such as `red`. Use a color token instead.
+
+**Presets:** warning in recommended and strict. **Fix:** none.
+
+## Why
+
+A design system owns its colors in one place. A raw color skips the palette, so it does not follow themes, dark mode or high contrast, and it drifts from the tokens over time.
+
+## Examples
+
+```js
+// ❌ Use a color token instead of raw hex color '#ff0000'.
+fill: '#ff0000'
+
+// ❌ Use a color token instead of raw rgb() color.
+color: 'rgb(0 0 0)'
+
+// ❌ Use a color token instead of raw named color 'red'.
+border: '1bw solid red'
+
+// ✅ A token
+fill: '#danger'
+
+// ✅ A token definition may hold a raw color
+'#accent': '#ff0000'
+```
+
+## Checks
+
+1. **Hex colors:** `#` followed by 3, 4, 6 or 8 hex digits. A token name made only of those characters (`#add`, `#beef`) reads as a hex color too.
+2. **Color functions:** `rgb()`, `rgba()`, `hsl()`, `hsla()`, `hwb()`, `lab()`, `lch()`, `oklab()`, `oklch()`, `okhsl()`, `okhsv()`, `okhst()`, `color()`, `device-cmyk()` and `light-dark()`.
+3. **Named colors** (`red`, `rebeccapurple`, …) in properties that take colors. `transparent` and `currentColor` are left to [`tasty/prefer-custom-property-syntax`](prefer-custom-property-syntax.md), which suggests `#clear` and `#current`.
+
+Not reported: values of `#name` and `$name` keys, which define tokens, values inside `tastyStatic(':root', { … })`, quoted strings and URLs.
+
+## Exceptions
+
+For an intentional one-off color, disable the rule for that line, with a reason:
+
+```js
+// eslint-disable-next-line tasty/no-raw-color-values -- brand color from the partner's guidelines
+fill: '#1db954',
+```
+
+## Options
+
+None.

package/docs/rules/no-raw-motion-duration.md

@@ -0,0 +1,50 @@
+# tasty/no-raw-motion-duration
+
+Reports a hardcoded duration in `animation`, `animationDuration` and `transitionDuration`, such as `'spin 2s linear infinite'`. Use a duration token instead.
+
+**Presets:** none. Turn it on in your config. **Fix:** editor suggestions.
+
+## Why
+
+When a design system keeps its animation timing in tokens, a raw `2s` drifts from it. This rule extends [`tasty/no-raw-transition-duration`](no-raw-transition-duration.md) to the CSS animation and duration properties. It is opt-in because not every design system has motion tokens.
+
+## Examples
+
+```js
+// ❌ animation duration '2s' is hardcoded. Use a duration token.
+animation: 'spin 2s linear infinite'
+
+// ❌ transitionDuration duration '150ms' is hardcoded. Use a duration token.
+transitionDuration: '150ms'
+
+// ✅ A token
+animationDuration: '$fast-duration'
+
+// ✅ A delay: the second time in an animation shorthand
+animation: 'spin $spin-duration linear 2s'
+```
+
+## Checks
+
+- The duration in `animation`, and the values of `animationDuration` and `transitionDuration`, in Tasty style objects and JSX style props.
+- A second time in an animation shorthand is a delay and is left alone.
+- Zero and token-based timing are fine.
+
+The editor suggests each configured duration token whose name fits the property, such as a `$…duration` token. It never suggests removing the duration: unlike Tasty's `transition`, these CSS properties have no Tasty timing to fall back to.
+
+Lengths and other numbers are outside this rule. [`tasty/consistent-token-usage`](consistent-token-usage.md) covers pixel lengths.
+
+## Turning it on
+
+```js
+import tasty from '@tenphi/eslint-plugin-tasty';
+
+export default [
+  tasty.configs.recommended,
+  { rules: { 'tasty/no-raw-motion-duration': 'warn' } },
+];
+```
+
+## Options
+
+None.

package/docs/rules/no-raw-transition-duration.md

@@ -0,0 +1,56 @@
+# tasty/no-raw-transition-duration
+
+Reports a hardcoded duration in a `transition` value, such as `'fill 0.2s'`. Use a duration token, or leave the duration out to get the design system's timing.
+
+**Presets:** warning in recommended and strict. **Fix:** editor suggestions.
+
+## Why
+
+A design system that owns its motion timing owns it in one place. A `0.2s` sprinkled through components drifts the same way a raw hex color does. Without a duration, Tasty uses `var(--<name>-transition, var(--transition))`, so the timing follows the design system.
+
+## Examples
+
+```js
+// ❌ Transition duration '0.2s' is hardcoded. Use a duration token ($transition),
+//    or omit it to inherit $fill-transition (falling back to $transition).
+transition: 'fill 0.2s'
+
+// ❌ Transition duration '(0.2s * 2)' contains a hardcoded time.
+transition: 'fill (0.2s * 2)'
+
+// ✅ A token
+transition: 'fill $transition'
+
+// ✅ No duration: Tasty uses the per-name timing
+transition: 'fill'
+transition: 'fill ease-in'
+
+// ✅ A delay, not a duration
+transition: 'fill ease-in 0.1s'
+
+// ✅ Zero turns the motion off
+transition: 'fill 0s'
+```
+
+## Checks
+
+The rule checks only the **duration**: the second word of each comma group, when it is not an easing. A Tasty transition is `[name] [duration] [easing] [delay]` or `[name] [easing] [delay]`, so a later time is a delay and is left alone. Leaving out a delay means "no delay", a real change, while leaving out a duration falls back to the design system's timing.
+
+Hardcoded means a nonzero CSS time (`0.2s`, `200ms`, `.15s`), or an expression with a raw time and no token, such as `(0.2s * 2)`. Tokens and expressions built on them are fine: `$transition`, `var(--transition)`, `calc(var(--transition) * 2)`.
+
+The rule also checks the `transition` JSX prop of a local `const` component created by an imported `tasty()` call. Other components' props are not assumed to use Tasty's transition syntax.
+
+## Suggestions
+
+For a literal duration, the editor offers:
+
+1. each duration token in the project config: a `tokens` entry named `$transition`, ending in `-transition`, or containing `duration`;
+2. removing the duration, to inherit `var(--<name>-transition, var(--transition))`.
+
+Neither is an autofix: both change what the browser renders. An expression with a raw time gets no suggestion, since replacing or removing it may change what it computes.
+
+`@tenphi/tasty` ships a `tasty.config.ts` that lists `$transition`, and the plugin reads it as the base of the config chain, so there is always at least one token to suggest.
+
+## Options
+
+None.

package/docs/rules/no-runtime-styles-mutation.md

@@ -0,0 +1,58 @@
+# tasty/no-runtime-styles-mutation
+
+Reports style values and keys computed at render time: props, state, hook results, parameters, local bindings, calls, conditionals, computed keys and template interpolation.
+
+**Presets:** warning in recommended and strict. **Fix:** none.
+
+## Why
+
+Tasty generates CSS once per distinct styles object. Values that change on every render generate new CSS each time they change, and they hide what the component can look like. Express dynamic behavior with modifiers (`mods`), tokens (`tokens`) or CSS custom properties, and keep style values static.
+
+## Examples
+
+```js
+// ❌ Prefer a static style value for 'fill'. Use states with mods, tokens, or styleProps.
+function Tab({ isActive }) {
+  return <Box styles={{ fill: isActive ? '#blue' : '#gray' }} />;
+}
+
+// ✅ A state map and a modifier
+const TabBox = tasty({
+  styles: {
+    fill: {
+      '': '#gray',
+      active: '#blue',
+    },
+  },
+});
+
+function Tab({ isActive }) {
+  return <TabBox mods={{ active: isActive }} />;
+}
+```
+
+## What is reported
+
+The rule reports the specific value inside a state map or sub-element.
+
+- A style object that no function encloses is built once, while the module loads, so none of its values is reported, calls and unresolved names included. An instance field does not count as module level: it runs for every instance.
+- Inside a function, values fixed once the module has loaded are allowed, since Tasty generates their CSS once, as for a literal: `undefined`, module-scope `const` bindings, enums and imports (and their members, including computed members with such keys), and templates, operators, conditionals and `mergeStyles(...)` calls built only from those. The same test applies to computed keys.
+- Anything that reaches render-time scope is reported: props, state, hook results, parameters, a local or `let` binding, any other call.
+- A `mergeStyles` object-literal argument is a style object of its own and is checked where it stands.
+- Literal strings, `null`, `false` and `true` are fine.
+
+Style objects are found where they reach Tasty, not only where they are written: an object behind a conditional or logical operator (`mergeStyles(cond ? { … } : null, styles)`), and an object held in a render-scope variable that is read as styles (`const local = { … }` or `styles = { ...styles, … }`, then `styles={local}`, `mergeStyles(styles, local)` or `Icon: local`). A render-scope `const` bound to an object literal is not reported where it is passed on: its values are checked where it is written.
+
+Not covered here:
+
+- Spreads, which [`tasty/no-style-spread`](no-style-spread.md) reports, so each can be disabled on its own.
+- `tastyStatic()`, which [`tasty/static-no-dynamic-values`](static-no-dynamic-values.md) checks.
+- At-rule definition objects (`@keyframes`, `@font-face`, …), which may be shared JavaScript data.
+
+## Exceptions
+
+For JavaScript computation that is really needed, disable the rule for that line, with a reason.
+
+## Options
+
+None.

package/docs/rules/no-state-in-selector.md

@@ -0,0 +1,142 @@
+# tasty/no-state-in-selector
+
+Keep sub-element `$` selectors structural. Express state conditions in property
+state maps so Tasty can resolve their priority and make competing states
+exclusive.
+
+**Presets:** warning in recommended and strict. **Fix:** none.
+
+## Reported
+
+```js
+const Content = tasty({
+  styles: {
+    ResponsiveWidth: {
+      $: 'img:not([width]), :where(picture), video:not([width])',
+      inlineSize: 'max 100%',
+    },
+    Link: {
+      $: 'a:hover',
+      color: '#active',
+    },
+  },
+});
+```
+
+The rule reports one warning per `$` value, pointing out its first condition.
+Attribute selectors (such as `[width]`, `[disabled]`, `[data-active]`, and
+`[aria-expanded="true"]`) and pseudo-classes (including `:hover`, `:not()`,
+`:has()`, and `:last-child`) are conditions. Conditions are also reported inside
+structural grouping functions such as `:is()` and `:where()`.
+
+## Preferred
+
+```js
+const Content = tasty({
+  styles: {
+    Link: {
+      $: 'a',
+      color: {
+        '': '#text',
+        '@own(:hover)': '#active',
+      },
+    },
+    Picture: {
+      $: ':where(picture)',
+      inlineSize: 'max 100%',
+    },
+    Before: {
+      $: '&::before',
+      content: '""',
+    },
+  },
+});
+```
+
+Use `@own(...)` when the state belongs to the selected sub-element, for example
+`@own(![width])`. Ordinary state keys such as `:hover` refer to the root component.
+Conditions on ancestors need the appropriate root/parent state expression.
+When a selector list mixes conditions with unconditional targets, keep their
+different behavior explicit. For example, `picture` in the reported media list
+has no width condition and can own a separate unconditional style definition.
+
+Choose a default or fallback for each property state map deliberately. Removing
+a condition from `$` broadens the selector: every property in that sub-element
+must retain its intended condition, and default values can affect elements that
+previously received no rule. The rule provides no automatic fixes or editor
+suggestions because a safe migration depends on that intent.
+
+## Allowed structural selectors
+
+- Tags, universal selectors, Tasty element names and `@` placeholders.
+- Combinators, classes and IDs that identify the component's anatomy.
+- Exact, non-namespaced `[data-element="Name"]` selectors with a nonempty name.
+- Pseudo-elements, including the legacy spellings `:before`, `:after`,
+  `:first-line`, and `:first-letter`.
+- `:is()` and `:where()` containing only structural selectors.
+
+## Selectors that end in a pseudo-element
+
+When a `$` item ends in a pseudo-element, Tasty treats the pseudo-element as
+the sub-element: `@own(...)` states go after it, and states a pseudo-element
+cannot have (attributes, classes, `:first-child`, `:nth-*()`, `:empty`,
+`:has()`, and modifiers) are dropped with a warning. A condition on the element
+the pseudo-element belongs to must therefore stay in `$`, before the
+pseudo-element, and the rule accepts it:
+
+```js
+const Pagination = tasty({
+  styles: {
+    NextArrow: {
+      $: 'a[rel="next"]::before',
+      content: '"→"',
+    },
+    Marker: {
+      $: 'li:last-child::marker',
+      color: '#text',
+    },
+    Label: {
+      // Not '@::part(label):hover': @own(:hover) is the part's own state.
+      $: '@::part(label)',
+      color: { '': '#text', '@own(:hover)': '#active' },
+    },
+  },
+});
+```
+
+Moving such a condition into `@own(...)` would not work: Tasty ignores it, and
+[`tasty/no-ignored-pseudo-element-state`](no-ignored-pseudo-element-state.md)
+reports it. Pseudo-classes written after the pseudo-element are its own states,
+which `@own(...)` expresses exactly, so they are still reported. Conditions after it
+that `@own(...)` would drop, such as `::part(label):first-child`, are not.
+Conditions inside the pseudo-element, such as `::slotted(img:hover)`, are part
+of what it selects and stay in `$`. A condition in an earlier compound, such as
+`:last-child` in `li:last-child > a::before`, describes an ancestor and is
+still reported.
+
+"Ends in a pseudo-element" means the first `::name` or legacy single-colon
+spelling in the item's last compound. Each item of a selector list is checked
+on its own, so `summary::marker, li:last-child` still reports `:last-child`.
+
+Class and ID names are treated as identities; the rule cannot infer whether a
+particular class name represents application state. Keep such state in maps too.
+
+## Scope and limits
+
+This rule checks literal strings and templates without interpolation in
+sub-element `$` values. It uses the plugin's existing Tasty style detection,
+including `tasty()`, `tastyStatic()`, `useStyles()`, `useGlobalStyles()`, typed/shared
+style objects, JSX/Storybook styles, and configured `styleFunctions` helpers.
+TypeScript wrappers and statically computed `$` keys are supported.
+
+Root selector arguments to `tastyStatic()` and `useGlobalStyles()` are outside
+this rule's scope, as are unrelated JavaScript objects and dynamic selectors.
+Malformed selectors that cannot be parsed are left to syntax validation; this
+rule does not validate CSS syntax. Other rules may flag dynamic style values.
+
+For an intentional exception, disable only this rule on the selector's line and
+explain why its condition must remain part of the structural selection.
+
+## Options
+
+None.

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

@@ -0,0 +1,127 @@
+# tasty/no-style-prop
+
+Warn about React's `style` prop on recognized Tasty components. The [`elements`](#options) option extends the check to
+every component or element, so this rule can replace React's `style`
+restriction.
+
+**Presets:** warning in recommended and strict. **Fix:** none.
+
+Define token references in the component's styles and use `tokens` for dynamic
+per-instance values:
+
+```tsx
+import { tasty } from '@tenphi/tasty';
+
+const Progress = tasty({ styles: { width: '$progress' } });
+
+// ❌ Move the dynamic value to a token consumed by the definition.
+<Progress style={{ width: `${percent}%` }} />;
+
+// ✅ Preferred.
+<Progress tokens={{ $progress: `${percent}%` }} />;
+```
+
+The warning covers literals, variables, calls, conditional expressions, null,
+and visible `style` keys in inline JSX object spreads. It does not rewrite the
+prop: choosing a token and declaring its reference requires the component's
+styling contract.
+
+A third-party positioning or animation library may require applying its inline
+styles through `style`. Keep that integration and acknowledge the exception with
+an explicit local ignore and a reason:
+
+```tsx
+const floating = (
+  // eslint-disable-next-line tasty/no-style-prop -- positioning library supplies these inline styles
+  <Progress style={positioningStyles} />
+);
+```
+
+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.
+
+## Options
+
+```js
+'tasty/no-style-prop': ['warn', { elements: 'all' }],
+```
+
+| `elements`          | Reports `style` on                                                                                          |
+| ------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `'tasty'` (default) | Recognized Tasty components                                                                                 |
+| `'components'`      | Every component: Tasty ones, other capitalized tags, and member tags such as `<UI.Panel>` or `<motion.div>` |
+| `'all'`             | Every component and native element, such as `<div>`, `<my-element>` or `<svg:rect>`                         |
+
+On a Tasty component the message suggests token references and `tokens`. On any
+other element it suggests moving the styles into Tasty: render a `tasty()`
+element, or wrap the component with `tasty(Component, { styles })`.
+
+```js
+'tasty/no-style-prop': ['warn', { values: 'static' }],
+```
+
+| `values`          | Reports                                                                                                 |
+| ----------------- | ------------------------------------------------------------------------------------------------------- |
+| `'all'` (default) | Every `style`                                                                                           |
+| `'static'`        | A `style` whose every value is a literal, written inline or as a local `const` object, and Tasty syntax |
+
+A static `style` always has a Tasty form: style props or the component's styles,
+where Tasty units, tokens and states apply. A runtime value (a measured
+position, a size from a prop, a user's theme) is the same inline custom property
+whether it is written in `style` or in `tokens`, so `'static'` leaves it to the
+author. A `style` built from a spread, a call, a conditional, a template with
+substitutions or a computed key is not static.
+
+### Tasty syntax in `style`
+
+`style` hands its values to the browser unparsed, so a Tasty unit (`'4x'`,
+`'1bw'`), a color token (`'#dark'`) or a `$` token in a literal value is an
+invalid declaration that the browser drops. The rule reports it under either
+`values` setting, even when the other values are dynamic, and names the value.
+A raw hex color, `var()` and CSS units, `lh` included, are left alone.
+
+## Replacing React's `style` restriction
+
+`react/forbid-component-props` and `react/forbid-dom-props` are each one rule
+for every prop they forbid, and a disable directive cannot target a single
+forbidden prop. When they forbid `style`, a `style` exception on a Tasty
+component has to name the React rule as well as this one, and the React part
+also hides any other forbidden prop, such as `className`, on that line.
+
+Let this rule handle `style` instead, and keep the React rules for the other
+props:
+
+```js
+rules: {
+  // Without options, forbid-component-props forbids both className and style.
+  'react/forbid-component-props': ['error', { forbid: ['className'] }],
+  // Remove 'style' from forbid-dom-props, or turn the rule off if 'style' was
+  // its only entry.
+  'react/forbid-dom-props': 'off',
+  'tasty/no-style-prop': ['warn', { elements: 'all' }],
+},
+```
+
+The rule names are the same in an Oxlint config. Use `elements: 'components'`
+instead to leave native elements to `react/forbid-dom-props`. A `style`
+exception then names this rule only, and leaves every other check on the line in
+place:
+
+```tsx
+// eslint-disable-next-line tasty/no-style-prop -- positioning library supplies these inline styles
+<Popover style={positioningStyles} />
+```
+
+After the switch, existing `style` exceptions that name a React rule no longer
+suppress anything. ESLint reports them as unused disable directives (a warning
+by default, see `linterOptions.reportUnusedDisableDirectives`); Oxlint does with
+`--report-unused-disable-directives`. Rename each to `tasty/no-style-prop`.
+
+Recognition uses local `const` components created by imported `tasty()` or
+configured options factories, their `const` aliases/sub-elements, and components
+from configured `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. List the design-system module
+in `importSources` for components imported from a package. Native elements, unrelated components, shadowed bindings,
+mutable aliases, and opaque spread bindings are excluded.