@tenphi/eslint-plugin-tasty 1.18.0 → 1.19.1

package/docs/rules/prefer-shorthand-property.md

@@ -0,0 +1,194 @@
+# tasty/prefer-shorthand-property
+
+Prefer Tasty's shorthand properties when defining a complete style, such as
+`fill` instead of `backgroundColor` or `height` instead of separate size constraints.
+
+**Presets:** warning in recommended and strict. **Fix:** autofix for pure key renames.
+
+## Why
+
+Tasty's shorthands carry its units, tokens, modifiers and defaults: `fill` takes
+color tokens and mixes, `padding: '2x top'` names its side, `blockPadding`
+emits native logical CSS. A native longhand bypasses that handler.
+
+## Examples
+
+```js
+// ❌ When defining the complete style, prefer tasty shorthand 'fill' instead of 'backgroundColor'.
+tasty({ styles: { backgroundColor: '#purple' } });
+
+// ✅ After the autofix
+tasty({ styles: { fill: '#purple' } });
+
+// ❌ Prefer 'padding: '... top'' instead of 'paddingTop'. Reported without a fix.
+tasty({ styles: { paddingTop: '2x' } });
+```
+
+## Mapping
+
+| Native CSS | Tasty |
+| --- | --- |
+| `backgroundColor` | `fill` |
+| `backgroundImage` | `image` |
+| `borderColor`, `borderWidth`, `borderStyle` | `border` |
+| `borderTop`, `borderRight`, `borderBottom`, `borderLeft` | `border: '... top'` and the other sides |
+| `borderRadius` | `radius` |
+| `minWidth`, `maxWidth` | `width: 'min ...'`, `width: 'max ...'` |
+| `minHeight`, `maxHeight` | `height: 'min ...'`, `height: 'max ...'` |
+| `flexDirection`, `flexWrap`, `flexFlow`, `gridAutoFlow` | `flow` |
+| `flexGap` | `gap` |
+| `gridTemplateColumns`, `gridTemplateRows`, `gridTemplateAreas` | `gridColumns`, `gridRows`, `gridAreas` |
+| `top`, `right`, `bottom`, `left` | `inset: '... top'` and the other sides |
+| `outlineColor`, `outlineWidth`, `outlineStyle` | `outline` |
+| `outlineOffset` | `outline: '... / offset'` |
+| `paddingTop`, `paddingRight`, `paddingBottom`, `paddingLeft` | `padding: '... top'` and the other sides |
+| `marginTop`, `marginRight`, `marginBottom`, `marginLeft` | `margin: '... top'` and the other sides |
+| `fontSize`, `letterSpacing`, `textTransform` | `preset` |
+| `fontWeight`, `lineHeight`, `fontStyle` | `preset: 'name / strong'`, `'name / tight'`, `'name / italic'` |
+| `fontFamily` | `font` (`preset` for a CSS-wide keyword such as `inherit`) |
+| `boxShadow` | `shadow` |
+| `scrollbarWidth`, `scrollbarColor`, `scrollbarGutter` | `scrollbar` |
+| `lineClamp` | `textOverflow: 'ellipsis / {lines}'` |
+
+**Logical properties** (Tasty 3.8 and later). Tasty moved the enhanced behavior
+onto the `<axis><Category>` names and left the native spellings as plain CSS:
+
+| Native CSS | Tasty |
+| --- | --- |
+| `paddingBlock`, `paddingInline` | `blockPadding`, `inlinePadding` |
+| `paddingBlockStart`, `paddingInlineEnd`, … | `blockPadding: '... start'`, `inlinePadding: '... end'`, … |
+| `marginBlock`, `marginInline` and their edges | `blockMargin`, `inlineMargin` |
+| `insetBlock`, `insetInline` and their edges | `blockInset`, `inlineInset` |
+| `scrollMarginBlock`, `scrollPaddingInline` and the like | `blockScrollMargin`, `inlineScrollPadding` and the like |
+| `borderBlock`, `borderBlockColor`, `borderBlockWidth`, `borderBlockStyle` | `blockBorder` |
+| `borderInlineStart`, … | `inlineBorder: '... start'`, … |
+| `minBlockSize`, `maxBlockSize` | `blockSize: 'min ...'`, `blockSize: 'max ...'` |
+| `minInlineSize`, `maxInlineSize` | `inlineSize: 'min ...'`, `inlineSize: 'max ...'` |
+
+Logical corners (`borderStartStartRadius` and the like) are left out on purpose:
+`radius` sets physical corners, so pointing a logical corner at it would be wrong.
+
+## Autofix
+
+Only renames that change nothing but the key are fixed, outside extension
+layers: `backgroundColor` to `fill`, `borderRadius` to `radius`, and the logical
+axis renames such as `paddingBlock: '1x 2x'` to `blockPadding: '1x 2x'`, which
+emit the same `padding-block: 1x 2x`.
+
+The others stay report-only. An edge longhand needs a `start`, `end` or side
+modifier in the value, and the axis handler resets the edge you do not name. A
+`border-*` rename adds the style and color defaults that `border-block` never
+had (`border-block: 1bw` renders nothing).
+
+## Extension layers
+
+In an extension layer (`tasty(Base, {...})`, `tastyStatic(Base, {...})` or a
+`styles` prop), the report says the shorthand would replace the base's whole
+property, and has no fix. Styles merge per key there, so renaming the key
+replaces the base component's whole property instead of patching the part the
+layer writes: `paddingTop: '2x'` to `padding: '2x top'` sets the base's other
+three edges to `0`, and `backgroundColor` to `fill` replaces a `fill` state map
+the layer never mentioned.
+
+The recommended shape is a token in the base component, set from the layer:
+
+```js
+// base component: the seam
+const Card = tasty({ styles: { padding: '$v-padding $h-padding' } });
+
+// extension layer: no raw CSS longhand needed
+const TallCard = tasty(Card, { styles: { '$v-padding': '4x' } });
+```
+
+**Ownership.** That advice helps only if the base component is yours to edit,
+so the report is skipped when the base is imported from a package. Over a UI kit
+component, the only options left are the longhand already written or a rewrite
+that would clobber the base. Components declared in the same file count as
+owned, as do relative, absolute, `~`, `#` and `@/` imports. List a design system
+published from the same monorepo in `ownedSources` in `tasty.config.ts`. A base
+the plugin cannot resolve to an import is treated as owned.
+
+```js
+import { Button } from '@uikit/button';
+import { Card } from './card';
+
+// ✅ Not reported: '@uikit/button' is not this project's to change
+tasty(Button, { styles: { paddingTop: '2x' } });
+
+// ❌ Reported without a fix: the seam belongs in ./card
+tasty(Card, { styles: { paddingTop: '2x' } });
+```
+
+## Changing one part with a token
+
+A shorthand can also reset values you did not intend to change. For example,
+replacing `minHeight: '20x'` with `height: 'min 20x'` resets `height` to `auto` and
+`max-height` to `initial`. In a component extension, it replaces the base's whole
+`height` definition, including its state map. The rule reports these changes
+without an autofix.
+
+For an independent override, expose the relevant part as a token in the original
+component definition. Keep the other values and any states already defined there:
+
+```tsx
+const Card = tasty({
+  styles: {
+    '$min-height': '100vh',
+    height: '$min-height auto 100vw',
+  },
+});
+
+// Changes only min-height; height and max-height keep their original values.
+<Card tokens={{ '$min-height': '20x' }} />;
+```
+
+The default token preserves the original minimum height until it is overridden.
+Use your existing height and maximum height in place of `auto` and `100vw`.
+The diagnostic's `initial` placeholders describe an otherwise unconstrained
+dimension; keep any constraints from the original definition when adding a token.
+
+Two dimension values mean **minimum and maximum**, with the main size set to
+`auto`: `height: '$min-height 100vw'` sets `min-height` and `max-height`. Three
+values mean **minimum, size, maximum**: `height: '$min-height 100vh 100vw'` also
+sets an explicit height. The same pattern works for `width`, `blockSize`, and
+`inlineSize`, and for independent maximum-size overrides.
+
+The diagnostics also recommend tokens for other partial shorthand overrides,
+such as one padding edge or one border part. Add the token in the original
+definition while preserving its other values, then override it through `tokens`.
+Extension diagnostics point to the base component, where the token must be
+exposed. Reports over imported components you cannot edit remain suppressed;
+`ownedSources` can opt a design system from your own project back in.
+
+For sub-elements, declare the token default on the component root and reference
+it from the sub-element's shorthand. A default declared on the sub-element itself
+would take precedence over a token inherited from the root.
+
+`useStyles`, `useGlobalStyles`, and `tastyStatic` produce classes or CSS rather than
+a component accepting `tokens`. Their diagnostics instead recommend setting the
+corresponding CSS custom property on the target element, for example
+`element.style.setProperty('--min-height', '160px')`. These values must use CSS
+units; the component `tokens` prop processes Tasty units such as `20x` for you.
+
+Preset names and modifiers are static. For independent typography overrides,
+use the CSS value tokens referenced by the original named preset, such as
+`$body-font-size` for `preset: 'body'`. A token cannot replace the preset name
+or its modifiers. Scrollbar width and gutter modifiers are also static;
+independent token overrides belong in the `scrollbarWidth` or `scrollbarGutter`
+longhand instead of the `scrollbar` DSL.
+
+## Motion longhands
+
+Motion longhands are left alone on purpose. Tasty has an enhanced `transition`
+shorthand and accepts the native CSS `animation` shorthand. Replacing
+`transitionDuration`, `animationDuration` or another motion longhand with a
+shorthand could reset other values in a state or extension, and `animation` can
+also reset `animationTimeline` and `animationRange`. Use a shorthand to define a
+complete effect and longhands to change one part.
+[`tasty/no-raw-transition-duration`](no-raw-transition-duration.md) and
+[`tasty/no-raw-motion-duration`](no-raw-motion-duration.md) check raw timing in
+either form.
+
+## Options
+
+None.

package/docs/rules/prefer-state-negation.md

@@ -0,0 +1,44 @@
+# tasty/prefer-state-negation
+
+Reports a top-level `:not(...)` in a state key. Tasty's `!` prefix says the same thing.
+
+**Presets:** warning in recommended and strict. **Fix:** autofix.
+
+## Why
+
+`!` is Tasty's negation operator. It works on every kind of state: modifiers, attributes, pseudo-classes and aliases. One spelling for negation keeps state maps easy to read.
+
+## Examples
+
+```js
+// ❌ Use the '!' prefix instead of top-level :not() in state keys.
+fill: { '': '#white', ':not(:hover)': '#blue' }
+
+// ✅ After the autofix
+fill: { '': '#white', '!:hover': '#blue' }
+```
+
+## Autofix
+
+| Before | After |
+| --- | --- |
+| `':not(:hover)'` | `'!:hover'` |
+| `':not(:nth-child(2n + 1))'` | `'!:nth-child(2n + 1)'` |
+| `':not(.active)'`, `':not([data-kind="x"])'` | `'!:is(.active)'`, `'!:is([data-kind="x"])'` |
+| `':not(:hover, :focus)'` | `'!:is(:hover, :focus)'` |
+| `'hovered & (:not(:hover) \| :not(:focus))'` | `'hovered & (!:hover \| !:focus)'` |
+
+Anything but a single known pseudo-class is wrapped in `:is(...)`, so it keeps its meaning.
+
+The rule reports without a fix when the key has JavaScript escapes, when the new key already exists in the map, or when the map has a spread or a computed key that could hold it.
+
+## Not reported
+
+- `:not()` nested inside another selector: `':has(~ :not([data-drop-indicator]))'`, `':is(:not(:hover), :focus)'`.
+- `:not()` inside `@parent(...)`, `@root(...)` or `@own(...)`.
+- Malformed keys, which [`tasty/valid-state-key`](valid-state-key.md) reports.
+- Selector arguments, such as `tastyStatic(':not(:hover)', …)`.
+
+## Options
+
+None.

package/docs/rules/require-default-state.md

@@ -0,0 +1,50 @@
+# tasty/require-default-state
+
+Reports a state map without a `''` default and without a `_` fallback floor.
+
+**Presets:** error in recommended and strict. **Fix:** none.
+
+## Why
+
+Without `''` or `_`, the property has no value in the normal state: it applies only while one of the listed states holds. That is rarely intended in a component's own styles.
+
+## Examples
+
+```js
+// ❌ State mapping for 'fill' has no default ('') or fallback floor ('_') value.
+tasty({
+  styles: {
+    fill: { hovered: '#blue' },
+  },
+});
+
+// ✅ A '' default
+tasty({
+  styles: {
+    fill: { '': '#white', hovered: '#blue' },
+  },
+});
+
+// ✅ A '_' fallback floor gives a value in the normal state too
+tasty({
+  styles: {
+    inset: { _: 'auto', '@(scroll-state(stuck: top))': '0 auto auto auto' },
+  },
+});
+
+// ✅ Extending a component: no default keeps the base's
+tasty(Button, {
+  styles: {
+    fill: { loading: '#yellow' },
+  },
+});
+```
+
+## Not reported
+
+- Extension layers: `tasty(Base, { styles })`, a `styles` prop, a later `mergeStyles` argument and other partial overrides. There, a map without `''` extends the base's map.
+- A state map that spreads another (`{ ...BASE_STYLES.fill, hovered: '#blue' }`): the spread may bring the default.
+
+## Options
+
+None.

package/docs/rules/static-no-dynamic-values.md

@@ -0,0 +1,32 @@
+# tasty/static-no-dynamic-values
+
+Reports a value in a `tastyStatic()` call that is not a literal: variables, templates with expressions, calls, spreads and other expressions.
+
+**Presets:** error in recommended and strict. **Fix:** none.
+
+## Why
+
+The Babel plugin turns `tastyStatic()` into CSS at build time. It cannot evaluate JavaScript, so a dynamic value fails the build. This is a stricter, build-time version of [`tasty/no-runtime-styles-mutation`](no-runtime-styles-mutation.md).
+
+## Examples
+
+```js
+// ❌ tastyStatic() values must be static.
+const size = '2x';
+tastyStatic({ padding: size });
+
+// ❌ tastyStatic() values must be static.
+tastyStatic({ padding: `${base}x` });
+
+// ✅ Valid
+tastyStatic({ padding: '2x' });
+tastyStatic({ padding: { '': '2x', '@mobile': '1x' } });
+```
+
+## Checks
+
+Every value must be a string, number, boolean or `null`, or an object or array of those (state maps, sub-elements). Variables, templates with expressions, calls, spreads and other expressions are reported.
+
+## Options
+
+None.

package/docs/rules/static-valid-selector.md

@@ -0,0 +1,36 @@
+# tasty/static-valid-selector
+
+Reports an invalid selector in `tastyStatic(selector, styles)`: an empty string, unbalanced brackets, or a selector that is not a string literal.
+
+**Presets:** error in recommended and strict. **Fix:** none.
+
+## Why
+
+The Babel plugin reads the selector at build time. It cannot evaluate a variable, and a broken selector produces CSS the browser drops.
+
+## Examples
+
+```js
+// ✅ Valid
+tastyStatic('body', { fill: '#dark' });
+tastyStatic('.heading', { preset: 'h1' });
+tastyStatic(':root', { $gap: '8px' });
+
+// ❌ Invalid CSS selector: Selector cannot be empty
+tastyStatic('', { fill: '#dark' });
+
+// ❌ Invalid CSS selector: Unbalanced brackets in selector
+tastyStatic('.card[', { fill: '#dark' });
+
+// ❌ tastyStatic() selector must be a string literal.
+tastyStatic(getSelector(), { fill: '#dark' });
+```
+
+## Checks
+
+1. The selector is a string literal.
+2. Basic syntax: not empty, balanced brackets, valid characters. Tag names, `.class`, `#id`, `:pseudo`, `[attr]` and combinators are always valid.
+
+## Options
+
+None.

package/docs/rules/valid-boolean-property.md

@@ -0,0 +1,39 @@
+# tasty/valid-boolean-property
+
+Reports `true` on a property that has no default to apply, such as `textAlign: true` or `fill: true`. `false` is valid everywhere.
+
+**Presets:** error in recommended and strict. **Fix:** none.
+
+## Why
+
+On a property with a design-system default, `true` means "use the default": `padding: true` is `1x`, `border: true` is `1bw`. On any other property, Tasty passes `true` through, and the browser drops the declaration.
+
+## Examples
+
+```js
+// ✅ Valid
+border: true
+radius: true
+padding: true
+padding: false // false removes the property, on any property
+
+// ❌ Property 'textAlign' does not accept boolean true.
+textAlign: true
+
+// ❌ The same check applies inside a state map
+fill: { '': '#surface', hovered: true }
+```
+
+## Properties that take `true`
+
+`border`, `radius`, `padding`, `margin`, `inset`, `gap`, `color`, `fade`, `outline`, `shadow`, `width`, `height`, `hide`, `preset`, `font`, `scrollbar`, `scrollMargin`, `scrollPadding`, and the enhanced logical styles (`blockSize`, `inlinePadding`, `blockBorder`, …). Each one carries its category's default: `1x` for spacing and scroll edges, `0` for inset, `1bw` for border, a reset for the sizes.
+
+Left out on purpose:
+
+- `fill`, though the Tasty docs list it. As of Tasty 3.8 the handler passes the boolean through, so `fill: true` emits `background-color: true`: the browser drops it and the element has no background. A canary in `constants.round-trip.test.ts` fails when Tasty changes this.
+- `minWidth`, `maxWidth`, `minHeight`, `maxHeight` and the logical `minBlockSize` and the like. Tasty accepts `true` there but resets the whole axis rather than the one constraint named. Write `width: true` or `blockSize: true` to ask for that.
+- Native logical CSS such as `paddingInlineStart`, which has no category default.
+
+## Options
+
+None.

package/docs/rules/valid-color-token.md

@@ -0,0 +1,64 @@
+# tasty/valid-color-token
+
+Reports a color token with invalid syntax, such as `#purple.-5`, and a color token that your config does not list.
+
+**Presets:** error in recommended and strict. **Fix:** none.
+
+## Why
+
+Tasty turns `#name` into `var(--name-color)`. A token that no one defines resolves to nothing, and the browser drops the declaration without an error.
+
+## Examples
+
+```js
+// ❌ Invalid color token '#purple.-5': Opacity cannot be negative.
+fill: '#purple.-5'
+
+// ❌ Unknown color token '#pruple' (with tokens listed in tasty.config)
+fill: '#pruple'
+
+// ✅ Valid
+fill: '#purple'
+fill: '#purple.5'
+```
+
+## Syntax
+
+Always checked.
+
+| Valid | Meaning |
+| --- | --- |
+| `#purple` | Full opacity |
+| `#purple.5` | 50% opacity |
+| `#purple.05` | 5% opacity |
+| `#purple.100` | 10% opacity, the same as `#purple.1` |
+| `#purple.999` | 99.9% opacity |
+| `#current`, `#current.5` | `currentcolor`, at full or 50% opacity |
+| `##purple` | The raw `--purple-color` reference, for transitions and `@property` |
+| `(#primary, #secondary)` | A fallback |
+| `#name.$prop` | Opacity from a custom property |
+
+The digits after the dot are a decimal fraction, so any digit string is in range.
+
+| Invalid | Why |
+| --- | --- |
+| `#` | Empty token name |
+| `#purple.` | Trailing dot with no opacity value |
+| `#purple.5.5` | The opacity is not a digit string |
+| `#purple.-5` | Negative opacity |
+
+Raw hex colors such as `#ff0000` are not tokens. [`tasty/no-raw-color-values`](no-raw-color-values.md) reports them.
+
+## Existence
+
+Checked only when `tokens` in `tasty.config.*` lists names. A token is known when it is:
+
+- one of Tasty's built-in color tokens: `#current`, `#clear`, `#white`, `#black`, `#border`, `#outline`, with or without an opacity;
+- listed in `tokens`;
+- defined as a `#name` key in any style object of the same file, such as a sibling `'#accent': '#purple'` or a key in `tastyStatic(':root', { … })`.
+
+`##name` is checked the same way as `#name`. `tokens: false` turns the existence check off, also when an extended config lists tokens.
+
+## Options
+
+None.

package/docs/rules/valid-custom-property.md

@@ -0,0 +1,36 @@
+# tasty/valid-custom-property
+
+Reports a `$name` custom property reference with invalid syntax, and one that nothing defines.
+
+**Presets:** warning in strict. **Fix:** none.
+
+## Why
+
+Tasty turns `$name` into `var(--name)`. A misspelled name resolves to nothing, and the declaration is dropped without an error.
+
+## Examples
+
+```js
+// ✅ Valid
+padding: '$spacing'
+transition: '$$gradient-angle 0.3s'
+
+// ❌ Unknown custom property '$spacign'
+padding: '$spacign'
+```
+
+## Checks
+
+1. **Syntax.** A name is `$` followed by letters, digits or hyphens, such as `$accent-color`. The fallback form `($name, fallback)` is checked too.
+2. **Existence.** Checked only when `tokens` in `tasty.config.*` lists names. A property is known when it is:
+   - one of Tasty's built-in custom properties: `$gap`, `$radius`, `$border-width`, `$outline-width`, `$transition`, `$sharp-radius`, `$bold-font-weight`, `$font-sans-fallback`, `$font-mono-fallback`;
+   - listed in `tokens`;
+   - a `$name` key in any style object of the same file, including `tastyStatic(':root', { … })`;
+   - a `$name` key of a literal `tokens={{ … }}` JSX prop, or of the `tokens` option of `tasty()` or a configured options factory, in the same file;
+   - a `'--name'` key of a literal inline `style={{ … }}` object in the same file, which declares `$name`.
+
+`$$name` (the raw `--name`, for transitions) is checked the same way as `$name`. `tokens: false` turns the existence check off.
+
+## Options
+
+None.

package/docs/rules/valid-custom-unit.md

@@ -0,0 +1,34 @@
+# tasty/valid-custom-unit
+
+Reports a number with a unit that is neither a Tasty unit, a CSS unit, nor a unit from your config, such as `2q`.
+
+**Presets:** error in recommended and strict. **Fix:** none.
+
+## Why
+
+Tasty expands its own units (`2x` becomes `calc(2 * var(--gap))`) and passes CSS units through. A unit it does not know reaches the browser as is, and the browser drops the declaration.
+
+## Examples
+
+```js
+// ✅ Valid
+padding: '2x'
+radius: '1r'
+border: '1bw'
+
+// ❌ Unknown unit 'q' in '2q'
+padding: '2q'
+
+// ✅ Valid when tasty.config lists 'cols' in units
+width: '3cols'
+```
+
+## Known units
+
+- **Tasty's units:** `x`, `r`, `cr`, `bw`, `ow`, `lh`, `sf`.
+- **CSS units:** `px`, `em`, `rem`, `%`, `vw`, `vh`, `vmin`, `vmax`, `ch`, `ex`, `cm`, `mm`, `in`, `pt`, `pc`, `fr`, `deg`, `rad`, `turn`, `grad`, `s`, `ms`, `dpi`, `dpcm`, `dppx`, the small, large and dynamic viewport units (`svw`, `lvh`, `dvh`, …), the container units (`cqw`, `cqh`, `cqi`, `cqb`, `cqmin`, `cqmax`), `cap`, `ic`, `rlh`, `vi` and `vb`.
+- **Your units:** the `units` list in `tasty.config.*`. `units: false` turns the check off.
+
+## Options
+
+None.

package/docs/rules/valid-default-state-order.md

@@ -0,0 +1,44 @@
+# tasty/valid-default-state-order
+
+Reports a `''` default that is not the first key of a state map, a `_` fallback floor that is not the first key, and a `''` that is redundant next to `_`.
+
+**Presets:** warning in recommended and strict. **Fix:** autofix.
+
+## Why
+
+A state map resolves in the order it is written: the last key whose condition holds wins. The `''` default always holds, so after other states it overrides them. The `_` floor is the lowest layer of the cascade, so it goes first, above `''`.
+
+## Examples
+
+```js
+// ❌ Default state ('') in 'fill' must be the first key in the state map.
+fill: { hovered: '#blue', '': '#white' }
+
+// ✅ After the autofix
+fill: { '': '#white', hovered: '#blue' }
+
+// ❌ Fallback floor ('_') in 'fill' must be the first key in the state map, above the '' default.
+fill: { '': '#white', _: '#gray', hovered: '#blue' }
+
+// ✅ After the autofix
+fill: { _: '#gray', '': '#white', hovered: '#blue' }
+
+// ❌ Default state ('') in 'fill' is redundant when '_' is the only other state.
+fill: { _: '#gray', '': '#white' }
+
+// ✅ After the autofix
+fill: { _: '#gray' }
+```
+
+## Checks
+
+1. With `''` and `_` as the only keys, `''` is removed: `_` already gives the always-on value.
+2. A `_` that is not first moves to the top.
+3. With `_` first, a `''` moves right after it.
+4. Without `_`, a `''` that is not first moves to the top.
+
+The fix applies one step at a time, so a map with both keys misplaced takes two `--fix` passes, which ESLint runs on its own.
+
+## Options
+
+None.

package/docs/rules/valid-directional-modifier.md

@@ -0,0 +1,46 @@
+# tasty/valid-directional-modifier
+
+Reports a direction a property does not take, such as `start` on `padding` or `top` on `blockPadding`, and more than one value in a group that names directions.
+
+**Presets:** error in recommended and strict. **Fix:** none.
+
+## Why
+
+Physical properties speak `top`, `right`, `bottom` and `left`. Logical properties speak `start` and `end`. Each handler drops a direction from the other vocabulary without a word. In a group that names directions, Tasty keeps values and modifiers apart, so `'2x 4x top right'` does not pair `2x` with `top`.
+
+## Examples
+
+```js
+// ✅ Valid
+border: '1bw #red top'
+padding: '2x left right'
+inlinePadding: '1x start, 2x end'
+blockBorder: '1bw solid #accent start'
+
+// ❌ Modifier 'top' is not valid for 'blockPadding'. Accepted: start, end.
+blockPadding: '1x top'
+
+// ❌ Modifier 'start' is not valid for 'padding'. Accepted: top, right, bottom, left.
+padding: '1x start'
+
+// ❌ A group that names directions takes a single value, but '2x 4x top right' has 2.
+padding: '2x 4x top right'
+
+// ✅ One group per side
+padding: '2x top, 4x right'
+```
+
+## Directions per property
+
+| Property | Directions |
+| --- | --- |
+| `border`, `padding`, `margin`, `fade`, `scrollMargin`, `scrollPadding` | `top`, `right`, `bottom`, `left` |
+| `radius` | `top`, `right`, `bottom`, `left`, `top-left`, `top-right`, `bottom-left`, `bottom-right` |
+| `inset` | `top`, `right`, `bottom`, `left`, `dock` |
+| Every enhanced logical style (`blockPadding`, `inlineBorder`, …) | `start`, `end` |
+
+A group that names directions takes one value, applied to every direction it names. With `dock`, it takes up to two: the second insets the sides the dock spans. Colors do not count, since a `fade` group carries a width and up to two mask colors.
+
+## Options
+
+None.

package/docs/rules/valid-preset.md

@@ -0,0 +1,35 @@
+# tasty/valid-preset
+
+Reports a `preset` name your config does not list, and a preset modifier Tasty does not know.
+
+**Presets:** error in recommended and strict. **Fix:** none.
+
+## Why
+
+An unknown preset name renders no typography at all. The component falls back to inherited font styles, and nothing reports it at runtime.
+
+## Examples
+
+```js
+// ✅ Valid, when tasty.config lists 'h1' and 't2' in presets
+preset: 'h1'
+preset: 'h1 strong'
+preset: 't2 italic'
+
+// ❌ Unknown preset 'heading1'
+preset: 'heading1'
+
+// ❌ Unknown preset modifier 'heavy'
+preset: 'h1 / heavy'
+```
+
+## Checks
+
+1. **Name.** When `presets` in `tasty.config.*` lists names, the first word of the value must be one of them.
+2. **Modifiers.** Words after a `/` must be `strong`, `bold`, `italic`, `icon`, `tight` or `normal` (`line-height: normal`).
+
+A value made only of modifiers, such as `preset: 'normal'` or `preset: 'bold italic'`, is the modifier-only shorthand: its words are not checked against `presets`. CSS-wide keywords (`inherit`, `initial`, …) and `preset: true` are always valid. Without `presets` in the config, only modifiers are checked.
+
+## Options
+
+None.