@nxds/eslint-plugin 0.7.0 → 0.8.0

package/README.md

@@ -14,12 +14,16 @@ Requires `jsonc-eslint-parser`. Wired in the root `eslint.config.js` to target s
 
 Enforces the `nx:` Tailwind-class conventions from `.claude/rules/shadcn-divergences.md` on class strings (string + single-quasi template literals): correct prefix order (`nx:` before every modifier, not `hover:nx:…`), no banned `accent` token, complete semantic token paths (`-background` / `-foreground` / `-subtle`), and no raw primitive colors (`nx:bg-blue-500`). Ported from the former `.claude/hooks/lint-nx-prefix.mjs` so the checks run in `pnpm lint` and the pre-commit hook. Wired for `packages/react/src/**` and `apps/**` `.tsx`.
 
+Icons keep one size at every density, so the rule reports an icon sized from spacing. That is a numeric spacing step (`size-4`, `h-3`, `w-3`) or a value that reads a spacing variable, such as `size-[var(--nx-spacing-8)]`. It checks a variant whose subject is the `svg`, such as `[&_svg]:size-4` or `[&>svg:not(…)]:h-3`, and the `className` of an `Icon*` or `*Icon` JSX element. `has-[>svg]:size-8` and `[&:has(svg)]:size-9` size the box around the icon, so they pass. Use `size-icon-glyph-xs`, `-sm`, `-default`, `-lg` or `-xl`. They follow the UI scale. Stories are checked, because the docs pages copy their code. The docs app is not checked, and neither are Vue template `class` attributes.
+
 One check reads a whole class-string scope rather than a single literal: `nx:transition-colors` beside a ring-painting `focus-visible:outline-*` class fades the focus ring in, because Tailwind expands `transition-colors` to a list carrying `outline-color`. Only a width or a colour paints a ring, so `outline-none`, `outline-hidden`, `outline-0`, `outline-offset-*` and the style keywords (`outline-solid` / `dashed` / `dotted` / `double`) are exempt. Use `nx:transition-control` / `nx:transition-field` instead — see `/foundations/focus`.
 
 **What counts as one scope.** One class string; one call to `cva`, `cn`, `clsx` or `cx` — base, array elements and `variants` values together; or one `[…].join(' ')`, which collapses an array literal into a single attribute. That **over-approximates**: two sibling `variants` values of the same key are mutually exclusive and never share an element, and the rule reports the pair anyway. Over-reporting is the safe direction here, and the shape every field surface is written in — a base string plus a ring in a later array element — needs the call-wide scope to be caught at all.
 
 Two things fall outside a scope and pass: an array that is never joined, whose elements are per-item class strings; and a string that only meets the rest at a call site — a shared `const`, an argument handed to another function, or a callback body the enclosing call takes with it. The four composer names must be written plainly, and `join` is the one member expression the walk reads, on an array literal receiver — so an aliased or chained composer (`twMerge`, `utils.cn`, a renamed import, `[…].filter(Boolean).join(' ')`) is invisible to it. Specimen surfaces are exempt from this check: the docs pages under `apps/docs/app/_pages`, where a pairing is the subject of the prose. Stories and the rest of the docs app are checked.
 
+A second scope check covers icon line width. A class list that sizes `svg` children, such as `[&_svg]:size-…` or `[&>svg]:h-…`, must also include `nx:icon-stroke`, so every stroked icon draws the line for its size, from `--nx-icon-stroke-base` and `--nx-icon-stroke-ratio`. It must size them with a `size-icon-glyph-*` class, because `size-*`, `h-*` and `w-*` leave `--nx-icon-size` unset. Stories and the docs app are not checked.
+
 ### `@nxds/no-render-prop-types`
 
 Enforces `.claude/rules/composition-over-render-props.md`: component props must not be typed as render callbacks (`(...) => ReactNode`) or component references (`ComponentType` / `FC` / `ElementType`). Event-handler-named props (`on*`) are exempt. Use `children` / named `ReactNode` slots or per-mode components instead. Third-party-mandated shapes (e.g. recharts) opt out with a scoped `eslint-disable` + reason.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nxds/eslint-plugin",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
   "description": "ESLint rules that enforce nxds conventions in copied components.",
   "keywords": [

package/src/canonical-step-set.json

@@ -1,10 +1,14 @@
 {
   "$comment": "Union of every px value shipped across packages/core/tokens/semantic/spacing-{vega,lyra,maia,mira,nova,luma,sera}.json. Regenerate via `pnpm --filter @nxds/eslint-plugin refresh:canonical-set`. The shipped union may exceed the originally-intended scale; reconciliation tracked separately.",
   "values": [
-    0, 2, 4, 6, 8, 9, 10, 11, 12, 14, 15, 16, 18, 20, 22, 24, 26, 28, 30, 32,
-    34, 36, 38, 40, 42, 44, 46, 48, 52, 56, 60, 64, 68, 76, 80, 84, 92, 96, 100,
-    108, 112, 116, 120, 124, 128, 132, 140, 144, 148, 156, 160, 164, 172, 176,
-    180, 188, 192, 196, 204, 208, 210, 212, 220, 224, 228, 236, 240, 244, 252,
-    256, 260, 284, 288, 292, 316, 320, 324, 380, 384, 388
+    0, 2, 4, 6, 8, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 22, 23, 24, 25,
+    26, 28, 30, 32, 34, 36, 38, 40, 42, 44, 46, 48, 50, 52, 54, 56, 58, 60, 62,
+    64, 66, 68, 70, 76, 78, 80, 82, 84, 86, 92, 94, 96, 98, 100, 102, 108, 110,
+    112, 114, 116, 118, 124, 126, 128, 130, 132, 134, 140, 142, 144, 146, 148,
+    150, 156, 158, 160, 162, 164, 166, 172, 174, 176, 178, 180, 182, 188, 190,
+    192, 194, 196, 198, 204, 206, 208, 210, 212, 214, 220, 222, 224, 226, 228,
+    230, 236, 238, 240, 242, 244, 246, 252, 254, 256, 258, 260, 262, 284, 286,
+    288, 290, 292, 294, 316, 318, 320, 322, 324, 326, 380, 382, 384, 386, 388,
+    390
   ]
 }

package/src/rules/nx-class-conventions.js

@@ -35,6 +35,88 @@ export const RAW_LETTER_SPACINGS = [
   'widest',
 ];
 
+// A size from spacing follows density: a numeric spacing step (`size-4`), or an
+// arbitrary value that reads a spacing variable
+// (`size-[var(--nx-spacing-8)]`, `size-(--nx-spacing-8)`). Glyph tokens
+// (`size-icon-glyph-sm`) and other arbitrary values (`size-[24px]`) do not.
+// A leading `!` is Tailwind's important modifier.
+const SPACING_SIZE = /^!?(?:size|h|w)-(?:\d|[[(].*--nx-spacing-)/;
+
+// Any size utility: a spacing step, a glyph token or an arbitrary value.
+const ANY_SIZE = /^!?(?:size|h|w)-/;
+
+// A fixed size that leaves `--nx-icon-size` unset, such as `size-[24px]`. A size
+// from spacing reports `densityIconSize` instead.
+const PLAIN_SIZE = /^!?(?:size|h|w)-(?!icon-glyph-|\d|[[(].*--nx-spacing-)/;
+
+// An `Icon*` or `*Icon` JSX element, such as `IconX` or `CheckIcon`.
+const ICON_ELEMENT_NAME = /^Icon(?![a-z])|Icon$/;
+
+/** The `nx:` classes in a class string. */
+function nxClasses(raw) {
+  return raw.split(/\s+/).filter((token) => token.startsWith('nx:'));
+}
+
+/** Splits a class at the `:` separators outside `[…]` and `(…)`. */
+function splitVariants(className) {
+  const parts = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < className.length; i++) {
+    const char = className[i];
+    if (char === '[' || char === '(') depth++;
+    else if (char === ']' || char === ')') depth--;
+    else if (char === ':' && depth === 0) {
+      parts.push(className.slice(start, i));
+      start = i + 1;
+    }
+  }
+  parts.push(className.slice(start));
+  return parts;
+}
+
+/** A selector without its `[…]` and `(…)` groups. */
+function withoutGroups(selector) {
+  let depth = 0;
+  let kept = '';
+  for (const char of selector) {
+    if (char === '[' || char === '(') depth++;
+    else if (char === ']' || char === ')') depth--;
+    else if (depth === 0) kept += char;
+  }
+  return kept;
+}
+
+// An arbitrary variant whose subject is the `svg`, such as `[&_svg]` or
+// `[&>svg:not(…)]`. In `has-[>svg]` and `[&:has(svg)]` the subject is the box
+// around the icon.
+function selectsSvg(variant) {
+  if (!variant.startsWith('[') || !variant.endsWith(']')) return false;
+  const compounds = withoutGroups(variant.slice(1, -1)).split(/[_>+~]/);
+  return /^svg(?![\w-])/.test(compounds.at(-1));
+}
+
+/** Whether an `nx:` class sizes an `svg` with a utility that `size` matches. */
+function sizesSvg(token, size) {
+  const variants = splitVariants(token.slice('nx:'.length));
+  const utility = variants.pop();
+  return size.test(utility) && variants.some(selectsSvg);
+}
+
+function sizesSvgFromSpacing(raw) {
+  return nxClasses(raw).some((token) => sizesSvg(token, SPACING_SIZE));
+}
+
+function sizesFromSpacing(raw) {
+  return nxClasses(raw).some((token) =>
+    SPACING_SIZE.test(splitVariants(token).at(-1))
+  );
+}
+
+function isIconElement(name) {
+  return name.type === 'JSXIdentifier' && ICON_ELEMENT_NAME.test(name.name);
+}
+
 const NAMED_VARIANT = String.raw`@?[\w-]+(?:\[[^\s]+?\])?(?:\/[\w-]+)?:`;
 const ARBITRARY_VARIANT = String.raw`\[[^\s]+?\]:`;
 const CHILD_VARIANT = String.raw`\*{1,2}:`;
@@ -72,21 +154,27 @@ const CHECKS = [
     re: new RegExp(
       `nx:${NX_MODIFIER_CHAIN}font-(?:${RAW_FONT_WEIGHTS.join('|')})\\b`
     ),
-    runtimeOnly: true,
+    skipFile: isExampleFile,
   },
   {
     messageId: 'rawLineHeight',
     re: new RegExp(
       `nx:${NX_MODIFIER_CHAIN}leading-(?:${RAW_LINE_HEIGHTS.join('|')}|\\d+|\\[)`
     ),
-    runtimeOnly: true,
+    skipFile: isExampleFile,
+  },
+  {
+    messageId: 'densityIconSize',
+    test: sizesSvgFromSpacing,
+    // Stories are checked: the docs pages copy their code into apps.
+    skipFile: isDocsFile,
   },
   {
     messageId: 'rawLetterSpacing',
     re: new RegExp(
       `nx:${NX_MODIFIER_CHAIN}tracking-(?:${RAW_LETTER_SPACINGS.join('|')}|\\[)`
     ),
-    runtimeOnly: true,
+    skipFile: isExampleFile,
   },
 ];
 
@@ -105,6 +193,27 @@ function fadesItsFocusRing(scope) {
   );
 }
 
+// A class list that sizes its `svg` children draws the icon, so it sets the
+// icon's line with `nx:icon-stroke` too.
+function leavesIconUnstroked(scope) {
+  const classes = nxClasses(scope);
+  if (classes.includes('nx:icon-stroke')) return false;
+  return classes.some((token) => sizesSvg(token, ANY_SIZE));
+}
+
+// `size-icon-glyph-*` sets `--nx-icon-size`, the size the line is drawn for. Any
+// other size must set the variable itself, under the same variants.
+function sizesIconWithoutLine(scope) {
+  const classes = nxClasses(scope);
+  return classes.some((token) => {
+    if (!sizesSvg(token, PLAIN_SIZE)) return false;
+    const variants = splitVariants(token).slice(0, -1).join(':');
+    return !classes.some((other) =>
+      other.startsWith(`${variants}:[--nx-icon-size:`)
+    );
+  });
+}
+
 function isStoryFile(filename) {
   return /\.stories\.[jt]sx?$/.test(filename);
 }
@@ -113,8 +222,9 @@ function isDocsFile(filename) {
   return /(?:^|[/\\])apps[/\\]docs[/\\]/.test(filename);
 }
 
-// What the runtime-only checks skip: stories and the docs app quote utilities
-// as specimens and prose, and the docs app styles its own chrome off-system.
+// What the raw typography and stroke checks skip: stories and the docs app
+// quote utilities as specimens and prose, and the docs app styles its own
+// chrome off-system.
 function isExampleFile(filename) {
   return isStoryFile(filename) || isDocsFile(filename);
 }
@@ -157,10 +267,7 @@ function isRawTypographyException(check, filename, raw) {
 }
 
 function shouldRunCheck(check, filename, raw) {
-  if (!check.runtimeOnly) {
-    return true;
-  }
-  if (isExampleFile(filename)) {
+  if (check.skipFile?.(filename)) {
     return false;
   }
   return !isRawTypographyException(check, filename, raw);
@@ -169,12 +276,12 @@ function shouldRunCheck(check, filename, raw) {
 function matchedMessageIds(raw, filename) {
   const matched = new Set();
   for (const check of CHECKS) {
-    const { messageId, re } = check;
     if (!shouldRunCheck(check, filename, raw)) {
       continue;
     }
-    if (re.test(raw)) {
-      matched.add(messageId);
+    const matches = check.test ? check.test(raw) : check.re.test(raw);
+    if (matches) {
+      matched.add(check.messageId);
     }
   }
   return matched;
@@ -255,7 +362,7 @@ export default {
     type: 'problem',
     docs: {
       description:
-        'Enforce nx: Tailwind class conventions — correct prefix order, no banned `accent` token, complete semantic token paths, no raw primitive colors, no raw named font-size utilities, and no ring-fading `transition-colors` on a focus-ring surface.',
+        'Enforce nx: Tailwind class conventions — correct prefix order, no banned `accent` token, complete semantic token paths, no raw primitive colors, no raw named font-size utilities, no icon sized from spacing, no ring-fading `transition-colors` on a focus-ring surface, and no sized `svg` children without `nx:icon-stroke`.',
     },
     schema: [],
     messages: {
@@ -275,8 +382,14 @@ export default {
         'Raw Tailwind line-height utility — let a typography composite own line-height instead of `nx:leading-*`.',
       rawLetterSpacing:
         'Raw Tailwind letter-spacing utility — use a typography composite such as `nx:typography-label-caps` instead of `nx:tracking-*`.',
+      densityIconSize:
+        'Icon size from spacing — a numeric `size-*`, `h-*` or `w-*`, or one that reads a `--nx-spacing-*` variable, on an `svg` selector (`[&_svg]:size-4`) or on an `Icon*` / `*Icon` element follows density. Use `size-icon-glyph-xs`, `-sm`, `-default`, `-lg` or `-xl` (12, 14, 16, 24 or 32px at the Default UI scale).',
       ringFadingTransition:
         'Ring-fading transition — `nx:transition-colors` includes `outline-color`, so this focus ring fades in instead of landing with the keypress. Use `nx:transition-control` (or `nx:transition-field` on a field surface).',
+      unstrokedIcon:
+        'Unstroked icon — this class list sizes its `svg` children (`[&_svg]:size-icon-glyph-default`), so add `nx:icon-stroke` to draw stroked icons at the icon line width.',
+      plainIconSize:
+        'Plain icon size — size `svg` children with a `size-icon-glyph-*` class, so the line matches the icon. `size-*`, `h-*` and `w-*` leave `--nx-icon-size` unset, so set it on the same selector for a size off the scale.',
     },
   },
   create(context) {
@@ -290,14 +403,22 @@ export default {
     }
 
     function reportScope(node) {
-      if (isDocsSpecimenPage(filename) || isInsideClassCall(node)) {
+      if (isInsideClassCall(node)) {
         return;
       }
       const collected = [];
       collectClassStrings(node, visitorKeys, collected);
-      if (fadesItsFocusRing(collected.join(' '))) {
+      const scope = collected.join(' ');
+      if (!isDocsSpecimenPage(filename) && fadesItsFocusRing(scope)) {
         context.report({ node, messageId: 'ringFadingTransition' });
       }
+      if (isExampleFile(filename)) return;
+      if (leavesIconUnstroked(scope)) {
+        context.report({ node, messageId: 'unstrokedIcon' });
+      }
+      if (sizesIconWithoutLine(scope)) {
+        context.report({ node, messageId: 'plainIconSize' });
+      }
     }
 
     return {
@@ -327,6 +448,24 @@ export default {
         }
         reportScope(node);
       },
+      JSXOpeningElement(node) {
+        if (isDocsFile(filename) || !isIconElement(node.name)) {
+          return;
+        }
+        const className = node.attributes.find(
+          (attribute) =>
+            attribute.type === 'JSXAttribute' &&
+            attribute.name.name === 'className'
+        );
+        if (!className?.value) {
+          return;
+        }
+        const collected = [];
+        collectClassStrings(className.value, visitorKeys, collected);
+        if (collected.some(sizesFromSpacing)) {
+          context.report({ node: className, messageId: 'densityIconSize' });
+        }
+      },
     };
   },
 };