@tenphi/eslint-plugin-tasty 1.17.1 → 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. 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/dist/rules/no-protected-restyle.js

@@ -38,10 +38,17 @@ var no_protected_restyle_default = createRule({
 			restyleProp: "'{{prop}}' restyles {{component}}, a protected {{source}} component. Customize it through its own props, 'tokens' or 'mods'. If this override is intended, explicitly disable tasty/no-protected-restyle for this usage with an ESLint comment and a reason.",
 			restyleWrapper: "This tasty() wrapper restyles {{component}}, a protected {{source}} component, through '{{prop}}'. Set its own props, 'tokens' or 'mods' instead. If this override is intended, explicitly disable tasty/no-protected-restyle for this usage with an ESLint comment and a reason."
 		},
-		schema: []
+		schema: [{
+			type: "object",
+			properties: { usages: {
+				type: "string",
+				enum: ["all", "wrappers"]
+			} },
+			additionalProperties: false
+		}]
 	},
-	defaultOptions: [],
-	create(context) {
+	defaultOptions: [{ usages: "all" }],
+	create(context, [{ usages = "all" }]) {
 		const ctx = new TastyContext(context);
 		const components = new ProtectedComponents(context, ctx);
 		if (!components.enabled) return {};
@@ -87,18 +94,21 @@ var no_protected_restyle_default = createRule({
 				if (name === "variants" || restyles(name, prop.value, target)) report(prop, "restyleWrapper", name, target);
 			}
 		}
+		const jsx = jsxElementPropListeners(ctx, (node) => {
+			const target = components.resolveTag(node.name);
+			return target && {
+				...target,
+				reference: context.sourceCode.getText(node.name)
+			};
+		}, (name, node, target) => {
+			if (restyles(name, node.type === "Property" ? node.value : node.value?.type === "JSXExpressionContainer" ? node.value.expression : node.value, target, node.type === "JSXAttribute" ? node : void 0)) report(node, "restyleProp", name, target);
+		});
 		return {
-			...jsxElementPropListeners(ctx, (node) => {
-				const target = components.resolveTag(node.name);
-				return target && {
-					...target,
-					reference: context.sourceCode.getText(node.name)
-				};
-			}, (name, node, target) => {
-				if (restyles(name, node.type === "Property" ? node.value : node.value?.type === "JSXExpressionContainer" ? node.value.expression : node.value, target, node.type === "JSXAttribute" ? node : void 0)) report(node, "restyleProp", name, target);
-			}),
-			"Program:exit"() {
-				ctx.finishJSXAnalysis();
+			...usages === "wrappers" ? { ImportDeclaration: jsx.ImportDeclaration } : {
+				...jsx,
+				"Program:exit"() {
+					ctx.finishJSXAnalysis();
+				}
 			},
 			CallExpression(node) {
 				const [base, options] = node.arguments;

package/dist/rules/no-protected-restyle.js.map

@@ -1 +1 @@
-{"version":3,"file":"no-protected-restyle.js","names":[],"sources":["../../src/rules/no-protected-restyle.ts"],"sourcesContent":["import type { TSESTree } from '@typescript-eslint/utils';\nimport { createRule } from '../create-rule.js';\nimport { TastyContext } from '../context.js';\nimport { KNOWN_TASTY_PROPERTIES } from '../constants.js';\nimport {\n  type ProtectedComponent,\n  ProtectedComponents,\n} from '../protected-components.js';\nimport { getKeyName, unwrapExpression } from '../utils.js';\nimport { jsxElementPropListeners } from './tasty-component-props.js';\n\ntype MessageIds = 'restyleProp' | 'restyleWrapper';\n\n/** `tasty(Base, options)` keys that configure the wrapper instead of setting a default prop. */\nconst WRAPPER_OPTIONS = new Set([\n  'as',\n  'element',\n  'elements',\n  'mods',\n  'modProps',\n  'qa',\n  'qaVal',\n  'styleProps',\n  'tokenProps',\n  'tokens',\n  'variant',\n]);\n\ninterface Target extends ProtectedComponent {\n  /** The tag or base as written: `UI.Button`, `CopyButton`. */\n  reference: string;\n}\n\n/** `inputStyles`, `triggerStyles`, ...: styles for one of the component's inner elements. */\nfunction isInnerStylesProp(name: string): boolean {\n  return /^[a-z][A-Za-z0-9]*Styles$/.test(name);\n}\n\n/** A value that cannot be a style value: a callback or an element. */\nfunction isNeverStyleValue(node: TSESTree.Node): boolean {\n  const value = unwrapExpression(node);\n  return (\n    value.type === 'ArrowFunctionExpression' ||\n    value.type === 'FunctionExpression' ||\n    value.type === 'JSXElement' ||\n    value.type === 'JSXFragment'\n  );\n}\n\nexport default createRule<[], MessageIds>({\n  name: 'no-protected-restyle',\n  meta: {\n    type: 'suggestion',\n    docs: {\n      description:\n        \"Warn when a design system's protected components are restyled instead of customized through their props\",\n    },\n    messages: {\n      restyleProp:\n        \"'{{prop}}' restyles {{component}}, a protected {{source}} component. Customize it through its own props, 'tokens' or 'mods'. If this override is intended, explicitly disable tasty/no-protected-restyle for this usage with an ESLint comment and a reason.\",\n      restyleWrapper:\n        \"This tasty() wrapper restyles {{component}}, a protected {{source}} component, through '{{prop}}'. Set its own props, 'tokens' or 'mods' instead. If this override is intended, explicitly disable tasty/no-protected-restyle for this usage with an ESLint comment and a reason.\",\n    },\n    schema: [],\n  },\n  defaultOptions: [],\n  create(context) {\n    const ctx = new TastyContext(context);\n    const components = new ProtectedComponents(context, ctx);\n    if (!components.enabled) return {};\n\n    const styleProps = new Set([\n      ...KNOWN_TASTY_PROPERTIES,\n      ...ctx.config.styles,\n    ]);\n\n    /** Root `styles` that only places or sizes the component, through allowed keys. */\n    function placesOnly(value: TSESTree.Node | null, target: Target): boolean {\n      const object = value && unwrapExpression(value);\n      return (\n        object?.type === 'ObjectExpression' &&\n        object.properties.every((prop) => {\n          if (prop.type !== 'Property' || prop.computed) return false;\n          const key = getKeyName(prop.key);\n          return key !== null && target.allowedStyleProps.has(key);\n        })\n      );\n    }\n\n    function restyles(\n      name: string,\n      value: TSESTree.Node | null,\n      target: Target,\n      attribute?: TSESTree.JSXAttribute,\n    ): boolean {\n      if (name === 'styles') return !placesOnly(value, target);\n      if (isInnerStylesProp(name)) return true;\n      if (!styleProps.has(name) || target.allowedStyleProps.has(name)) {\n        return false;\n      }\n      if (value && isNeverStyleValue(value)) return false;\n      // With typeAwareJSX, a prop the component declares itself is not a style prop.\n      return !(attribute && ctx.isComponentJSXProp(attribute));\n    }\n\n    function report(\n      node: TSESTree.Node,\n      messageId: MessageIds,\n      prop: string,\n      target: Target,\n    ): void {\n      context.report({\n        node,\n        messageId,\n        data: {\n          prop,\n          component:\n            target.reference === target.name\n              ? `'${target.name}'`\n              : `'${target.reference}' (based on '${target.name}')`,\n          source: `'${target.source}'`,\n        },\n      });\n    }\n\n    function checkWrapperOptions(\n      options: TSESTree.ObjectExpression,\n      target: Target,\n    ): void {\n      for (const prop of options.properties) {\n        if (prop.type === 'SpreadElement') {\n          const spread = unwrapExpression(prop.argument);\n          if (spread.type === 'ObjectExpression') {\n            checkWrapperOptions(spread, target);\n          }\n          continue;\n        }\n        const key = prop.computed ? unwrapExpression(prop.key) : prop.key;\n        if (prop.computed && key.type !== 'Literal') continue;\n        const name = getKeyName(key);\n        if (name === null || WRAPPER_OPTIONS.has(name)) continue;\n        if (name === 'variants' || restyles(name, prop.value, target)) {\n          report(prop, 'restyleWrapper', name, target);\n        }\n      }\n    }\n\n    const jsx = jsxElementPropListeners(\n      ctx,\n      (node): Target | null => {\n        const target = components.resolveTag(node.name);\n        return (\n          target && {\n            ...target,\n            reference: context.sourceCode.getText(node.name),\n          }\n        );\n      },\n      (name, node, target) => {\n        const value =\n          node.type === 'Property'\n            ? node.value\n            : node.value?.type === 'JSXExpressionContainer'\n              ? node.value.expression\n              : node.value;\n        const attribute = node.type === 'JSXAttribute' ? node : undefined;\n        if (restyles(name, value, target, attribute)) {\n          report(node, 'restyleProp', name, target);\n        }\n      },\n    );\n\n    return {\n      ...jsx,\n      'Program:exit'() {\n        ctx.finishJSXAnalysis();\n      },\n      CallExpression(node) {\n        const [base, options] = node.arguments;\n        if (!options || !components.isWrapperCall(node)) return;\n        const component = components.resolveExpression(base);\n        const object = unwrapExpression(options);\n        if (!component || object.type !== 'ObjectExpression') return;\n        checkWrapperOptions(object, {\n          ...component,\n          reference: context.sourceCode.getText(unwrapExpression(base)),\n        });\n      },\n    };\n  },\n});\n"],"mappings":"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"}
+{"version":3,"file":"no-protected-restyle.js","names":[],"sources":["../../src/rules/no-protected-restyle.ts"],"sourcesContent":["import type { TSESTree } from '@typescript-eslint/utils';\nimport { createRule } from '../create-rule.js';\nimport { TastyContext } from '../context.js';\nimport { KNOWN_TASTY_PROPERTIES } from '../constants.js';\nimport {\n  type ProtectedComponent,\n  ProtectedComponents,\n} from '../protected-components.js';\nimport { getKeyName, unwrapExpression } from '../utils.js';\nimport { jsxElementPropListeners } from './tasty-component-props.js';\n\ntype MessageIds = 'restyleProp' | 'restyleWrapper';\n\n/** Which usages the rule checks: instance props and `tasty()` wrappers, or the wrappers alone. */\ntype Usages = 'all' | 'wrappers';\n\n/** `tasty(Base, options)` keys that configure the wrapper instead of setting a default prop. */\nconst WRAPPER_OPTIONS = new Set([\n  'as',\n  'element',\n  'elements',\n  'mods',\n  'modProps',\n  'qa',\n  'qaVal',\n  'styleProps',\n  'tokenProps',\n  'tokens',\n  'variant',\n]);\n\ninterface Target extends ProtectedComponent {\n  /** The tag or base as written: `UI.Button`, `CopyButton`. */\n  reference: string;\n}\n\n/** `inputStyles`, `triggerStyles`, ...: styles for one of the component's inner elements. */\nfunction isInnerStylesProp(name: string): boolean {\n  return /^[a-z][A-Za-z0-9]*Styles$/.test(name);\n}\n\n/** A value that cannot be a style value: a callback or an element. */\nfunction isNeverStyleValue(node: TSESTree.Node): boolean {\n  const value = unwrapExpression(node);\n  return (\n    value.type === 'ArrowFunctionExpression' ||\n    value.type === 'FunctionExpression' ||\n    value.type === 'JSXElement' ||\n    value.type === 'JSXFragment'\n  );\n}\n\nexport default createRule<[{ usages?: Usages }], MessageIds>({\n  name: 'no-protected-restyle',\n  meta: {\n    type: 'suggestion',\n    docs: {\n      description:\n        \"Warn when a design system's protected components are restyled instead of customized through their props\",\n    },\n    messages: {\n      restyleProp:\n        \"'{{prop}}' restyles {{component}}, a protected {{source}} component. Customize it through its own props, 'tokens' or 'mods'. If this override is intended, explicitly disable tasty/no-protected-restyle for this usage with an ESLint comment and a reason.\",\n      restyleWrapper:\n        \"This tasty() wrapper restyles {{component}}, a protected {{source}} component, through '{{prop}}'. Set its own props, 'tokens' or 'mods' instead. If this override is intended, explicitly disable tasty/no-protected-restyle for this usage with an ESLint comment and a reason.\",\n    },\n    schema: [\n      {\n        type: 'object',\n        properties: {\n          usages: { type: 'string', enum: ['all', 'wrappers'] },\n        },\n        additionalProperties: false,\n      },\n    ],\n  },\n  defaultOptions: [{ usages: 'all' }],\n  create(context, [{ usages = 'all' }]) {\n    const ctx = new TastyContext(context);\n    const components = new ProtectedComponents(context, ctx);\n    if (!components.enabled) return {};\n\n    const styleProps = new Set([\n      ...KNOWN_TASTY_PROPERTIES,\n      ...ctx.config.styles,\n    ]);\n\n    /** Root `styles` that only places or sizes the component, through allowed keys. */\n    function placesOnly(value: TSESTree.Node | null, target: Target): boolean {\n      const object = value && unwrapExpression(value);\n      return (\n        object?.type === 'ObjectExpression' &&\n        object.properties.every((prop) => {\n          if (prop.type !== 'Property' || prop.computed) return false;\n          const key = getKeyName(prop.key);\n          return key !== null && target.allowedStyleProps.has(key);\n        })\n      );\n    }\n\n    function restyles(\n      name: string,\n      value: TSESTree.Node | null,\n      target: Target,\n      attribute?: TSESTree.JSXAttribute,\n    ): boolean {\n      if (name === 'styles') return !placesOnly(value, target);\n      if (isInnerStylesProp(name)) return true;\n      if (!styleProps.has(name) || target.allowedStyleProps.has(name)) {\n        return false;\n      }\n      if (value && isNeverStyleValue(value)) return false;\n      // With typeAwareJSX, a prop the component declares itself is not a style prop.\n      return !(attribute && ctx.isComponentJSXProp(attribute));\n    }\n\n    function report(\n      node: TSESTree.Node,\n      messageId: MessageIds,\n      prop: string,\n      target: Target,\n    ): void {\n      context.report({\n        node,\n        messageId,\n        data: {\n          prop,\n          component:\n            target.reference === target.name\n              ? `'${target.name}'`\n              : `'${target.reference}' (based on '${target.name}')`,\n          source: `'${target.source}'`,\n        },\n      });\n    }\n\n    function checkWrapperOptions(\n      options: TSESTree.ObjectExpression,\n      target: Target,\n    ): void {\n      for (const prop of options.properties) {\n        if (prop.type === 'SpreadElement') {\n          const spread = unwrapExpression(prop.argument);\n          if (spread.type === 'ObjectExpression') {\n            checkWrapperOptions(spread, target);\n          }\n          continue;\n        }\n        const key = prop.computed ? unwrapExpression(prop.key) : prop.key;\n        if (prop.computed && key.type !== 'Literal') continue;\n        const name = getKeyName(key);\n        if (name === null || WRAPPER_OPTIONS.has(name)) continue;\n        if (name === 'variants' || restyles(name, prop.value, target)) {\n          report(prop, 'restyleWrapper', name, target);\n        }\n      }\n    }\n\n    const jsx = jsxElementPropListeners(\n      ctx,\n      (node): Target | null => {\n        const target = components.resolveTag(node.name);\n        return (\n          target && {\n            ...target,\n            reference: context.sourceCode.getText(node.name),\n          }\n        );\n      },\n      (name, node, target) => {\n        const value =\n          node.type === 'Property'\n            ? node.value\n            : node.value?.type === 'JSXExpressionContainer'\n              ? node.value.expression\n              : node.value;\n        const attribute = node.type === 'JSXAttribute' ? node : undefined;\n        if (restyles(name, value, target, attribute)) {\n          report(node, 'restyleProp', name, target);\n        }\n      },\n    );\n\n    // `usages: 'wrappers'` drops the JSX checks, so instance props pass. The\n    // wrapper check still needs the imports tracked.\n    const instances =\n      usages === 'wrappers'\n        ? { ImportDeclaration: jsx.ImportDeclaration }\n        : {\n            ...jsx,\n            'Program:exit'() {\n              ctx.finishJSXAnalysis();\n            },\n          };\n\n    return {\n      ...instances,\n      CallExpression(node) {\n        const [base, options] = node.arguments;\n        if (!options || !components.isWrapperCall(node)) return;\n        const component = components.resolveExpression(base);\n        const object = unwrapExpression(options);\n        if (!component || object.type !== 'ObjectExpression') return;\n        checkWrapperOptions(object, {\n          ...component,\n          reference: context.sourceCode.getText(unwrapExpression(base)),\n        });\n      },\n    };\n  },\n});\n"],"mappings":"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"}

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.