@nxds/eslint-plugin 0.0.0-stage → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nexus Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,55 @@
-# Temporary Holding Version
+# @nxds/eslint-plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Custom ESLint rules for the nxds design system. They split into two groups: **token-layer** rules that backfill what the deleted `--nx-size-*` primitive layer used to enforce, and **component-authoring** rules that machine-enforce conventions documented in `.claude/rules/` (so they fail `pnpm lint` and the pre-commit hook for every contributor, not just code review).
+
+## Rules
+
+### `@nxds/canonical-spacing-steps`
+
+Flags any px value in `packages/core/tokens/semantic/spacing-*.json` that is not in the canonical step set. The canonical set is the union of every px value currently shipped across the 7 mode files; see `src/canonical-step-set.json`. Refresh that file when a mode file legitimately introduces a new value.
+
+Requires `jsonc-eslint-parser`. Wired in the root `eslint.config.js` to target spacing mode files only.
+
+### `@nxds/nx-class-conventions`
+
+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`.
+
+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.
+
+### `@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.
+
+### `@nxds/no-multi-statement-jsx-handler`
+
+Enforces `.claude/rules/extract-inline-handlers.md`: inline JSX handler props (`onClick`, `onChange`, …) with 3+ statements, or containing a nested callback-object argument, must be extracted to a named function above `return`. One- and two-statement handlers stay inline.
+
+### `@nxds/no-jsdoc-data-tags`
+
+Enforces `.claude/rules/code-comments.md`: JSDoc blocks must not carry `@default` or `@example` tags. The docs read prop defaults from code and usage from `docs` stories, so a tag is a second copy that can drift. Line comments and plain block comments are not checked. Wired in the root `eslint.config.js` for `packages/react/src` and `packages/vue/src`.
+
+## Source of truth
+
+The token-layer rules are self-contained: the canonical step set is `src/canonical-step-set.json`. The component rules map 1:1 to the `.claude/rules/*.md` cited above — the rule code plus those docs are the spec. Every rule has RuleTester coverage in `__tests__/`.
+
+## Shareable config
+
+`@nxds/eslint-plugin/config` exports small flat-config helpers for consumers
+that want the nxds rules without copying this monorepo's full lint setup:
+
+- `nxdsComponentConfig({ files })` wires the component-authoring rules.
+- `nxdsSpacingTokenConfig({ files, parser })` wires the spacing-token rule; pass
+  `jsonc-eslint-parser` when linting JSON token files.
+
+`@nxds/eslint-plugin/tailwind` exports `nxdsTailwindClassesConfig({ files,
+entryPoint })`, which wires `eslint-plugin-better-tailwindcss`'s
+`no-unknown-classes` against the stylesheet that builds `files`. Under
+`prefix(nx)` it reports a bare utility, a typo, and any class the theme no
+longer emits. `eslint-plugin-better-tailwindcss` is an optional peer dependency:
+install it only if you import this subpath. `entryPoint` must be an absolute
+path — tools such as `next build` lint from their own directory — and a
+relative one throws.

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@nxds/eslint-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.5.0",
+  "type": "module",
+  "description": "ESLint rules that enforce nxds conventions in copied components.",
+  "keywords": [
+    "nxds",
+    "design-system",
+    "eslint",
+    "eslintplugin",
+    "eslint-plugin",
+    "tailwindcss"
+  ],
+  "homepage": "https://nxds.dev/getting-started/install#optional-add-lint-rules",
+  "bugs": {
+    "url": "https://github.com/nexuslabs-ai/nxds/issues"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nexuslabs-ai/nxds.git",
+    "directory": "packages/eslint-plugin"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./config": "./src/config.js",
+    "./tailwind": "./src/tailwind.js"
+  },
+  "files": [
+    "src"
+  ],
+  "dependencies": {
+    "jsonc-eslint-parser": "^3.1.0"
+  },
+  "devDependencies": {
+    "eslint-plugin-better-tailwindcss": "^4.7.0"
+  },
+  "peerDependencies": {
+    "eslint-plugin-better-tailwindcss": "^4.7.0"
+  },
+  "peerDependenciesMeta": {
+    "eslint-plugin-better-tailwindcss": {
+      "optional": true
+    }
+  },
+  "license": "MIT",
+  "scripts": {
+    "refresh:canonical-set": "node scripts/refresh-canonical-set.js"
+  }
 }

package/src/canonical-step-set.json

@@ -0,0 +1,10 @@
+{
+  "$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
+  ]
+}

package/src/config.js

@@ -0,0 +1,50 @@
+import plugin from './index.js';
+
+export const componentRuleSet = {
+  '@nxds/nx-class-conventions': 'error',
+  '@nxds/no-render-prop-types': 'error',
+  '@nxds/no-multi-statement-jsx-handler': 'error',
+};
+
+export const spacingTokenRuleSet = {
+  '@nxds/canonical-spacing-steps': 'error',
+};
+
+export function nxdsComponentConfig(options = {}) {
+  const { files } = options;
+
+  return {
+    ...(files ? { files } : {}),
+    plugins: {
+      '@nxds': plugin,
+    },
+    rules: componentRuleSet,
+  };
+}
+
+export function nxdsSpacingTokenConfig(options = {}) {
+  const { files, parser } = options;
+
+  return {
+    ...(files ? { files } : {}),
+    ...(parser
+      ? {
+          languageOptions: {
+            parser,
+          },
+        }
+      : {}),
+    plugins: {
+      '@nxds': plugin,
+    },
+    rules: spacingTokenRuleSet,
+  };
+}
+
+export default {
+  plugin,
+  componentRuleSet,
+  spacingTokenRuleSet,
+  nxdsComponentConfig,
+  nxdsSpacingTokenConfig,
+};

package/src/index.js

@@ -0,0 +1,25 @@
+import { createRequire } from 'node:module';
+
+import canonicalSpacingSteps from './rules/canonical-spacing-steps.js';
+import noJsdocDataTags from './rules/no-jsdoc-data-tags.js';
+import noMultiStatementJsxHandler from './rules/no-multi-statement-jsx-handler.js';
+import noRenderPropTypes from './rules/no-render-prop-types.js';
+import nxClassConventions from './rules/nx-class-conventions.js';
+
+// Derive from package.json so ESLint's --cache / --print-config, which key off
+// meta.version, don't desync when changesets bumps the published version.
+const { name, version } = createRequire(import.meta.url)('../package.json');
+
+const plugin = {
+  meta: { name, version },
+  rules: {
+    'canonical-spacing-steps': canonicalSpacingSteps,
+    'nx-class-conventions': nxClassConventions,
+    'no-render-prop-types': noRenderPropTypes,
+    'no-multi-statement-jsx-handler': noMultiStatementJsxHandler,
+    'no-jsdoc-data-tags': noJsdocDataTags,
+  },
+};
+
+export default plugin;
+export const { rules } = plugin;

package/src/rules/canonical-spacing-steps.js

@@ -0,0 +1,74 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const canonical = JSON.parse(
+  readFileSync(join(__dirname, '..', 'canonical-step-set.json'), 'utf8')
+);
+const allowed = new Set(canonical.values);
+
+function summarizeAllowed(set) {
+  const arr = [...set].sort((a, b) => a - b);
+  if (arr.length <= 10) return arr.join(', ');
+  return `${arr.slice(0, 6).join(', ')}, … ${arr[arr.length - 1]} (${arr.length} total)`;
+}
+
+function readNumericLiteral(node) {
+  if (!node) return null;
+  if (node.type === 'JSONLiteral' && typeof node.value === 'number') {
+    return node.value;
+  }
+  if (
+    node.type === 'JSONUnaryExpression' &&
+    node.operator === '-' &&
+    node.argument?.type === 'JSONLiteral' &&
+    typeof node.argument.value === 'number'
+  ) {
+    return -node.argument.value;
+  }
+  return null;
+}
+
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow px values in spacing mode files outside the canonical step set',
+    },
+    schema: [],
+    messages: {
+      offGrid:
+        '{{value}}px is not in the canonical spacing step set. Allowed: {{allowed}}. Refresh src/canonical-step-set.json via `pnpm --filter @nxds/eslint-plugin refresh:canonical-set` if a mode file legitimately introduces a new value.',
+    },
+  },
+  create(context) {
+    return {
+      'JSONProperty[key.value="$value"] > JSONObjectExpression'(node) {
+        let valueProp, unitProp;
+        for (const prop of node.properties) {
+          if (prop.type !== 'JSONProperty') continue;
+          const key = prop.key?.value;
+          if (key === 'value') valueProp = prop.value;
+          else if (key === 'unit') unitProp = prop.value;
+        }
+        if (!unitProp || unitProp.type !== 'JSONLiteral') return;
+        if (unitProp.value !== 'px') return;
+
+        const n = readNumericLiteral(valueProp);
+        if (n === null) return;
+        if (allowed.has(n)) return;
+
+        context.report({
+          node: valueProp,
+          messageId: 'offGrid',
+          data: {
+            value: String(n),
+            allowed: summarizeAllowed(allowed),
+          },
+        });
+      },
+    };
+  },
+};

package/src/rules/no-jsdoc-data-tags.js

@@ -0,0 +1,54 @@
+// Enforces `.claude/rules/code-comments.md`: comments are prose, never data.
+// The docs read prop defaults from code and usage examples from `docs`
+// stories, so a `@default` or `@example` tag is a second copy that can drift.
+
+// TypeScript reads a tag at the start of a line, after its `*`, or after
+// whitespace mid-line.
+const TAG = /(^\s*\*?\s*|\s)@(default|example)\b/;
+
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow `@default` and `@example` JSDoc tags; defaults come from code and examples from docs stories.',
+    },
+    schema: [],
+    messages: {
+      default:
+        '`@default` duplicates a default the code sets. Delete it, and say so in the description if a dependency sets the default.',
+      example:
+        '`@example` is an untested copy of usage. Delete it and show the usage in a `docs` story.',
+    },
+  },
+  create(context) {
+    return {
+      Program() {
+        for (const comment of context.sourceCode.getAllComments()) {
+          if (comment.type !== 'Block' || !comment.value.startsWith('*')) {
+            continue;
+          }
+
+          comment.value.split('\n').forEach((text, index) => {
+            const match = TAG.exec(text);
+            if (!match) return;
+
+            const line = comment.loc.start.line + index;
+            // The first line starts after the comment's own `/*`.
+            const column =
+              (index === 0 ? comment.loc.start.column + 2 : 0) +
+              match.index +
+              match[1].length;
+            context.report({
+              loc: {
+                start: { line, column },
+                end: { line, column: column + match[2].length + 1 },
+              },
+              messageId: match[2],
+            });
+          });
+        }
+      },
+    };
+  },
+};

package/src/rules/no-multi-statement-jsx-handler.js

@@ -0,0 +1,121 @@
+// Enforces `.claude/rules/extract-inline-handlers.md`: inline JSX handler
+// props with 3+ statements, or containing a callback-object argument (e.g.,
+// `mutation.mutate(input, { onSuccess, onError })`), must be extracted to a
+// named function above `return`. One- and two-statement handlers stay inline.
+
+const HANDLER_NAME = /^on[A-Z]/;
+
+function countStatements(body) {
+  if (body.type !== 'BlockStatement') {
+    return 1;
+  }
+  return body.body.length;
+}
+
+function callExpressionHasCallbackObject(expr) {
+  if (!expr || expr.type !== 'CallExpression') {
+    return false;
+  }
+  for (const arg of expr.arguments) {
+    if (arg.type !== 'ObjectExpression') {
+      continue;
+    }
+    for (const prop of arg.properties) {
+      if (
+        prop.type === 'Property' &&
+        prop.key.type === 'Identifier' &&
+        HANDLER_NAME.test(prop.key.name)
+      ) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+function hasCallbackObjectArgument(body) {
+  // Expression-body arrow: `() => mutate(x, { onSuccess, onError })`.
+  if (body.type !== 'BlockStatement') {
+    return callExpressionHasCallbackObject(body);
+  }
+  for (const stmt of body.body) {
+    const expr =
+      stmt.type === 'ExpressionStatement'
+        ? stmt.expression
+        : stmt.type === 'ReturnStatement'
+          ? stmt.argument
+          : null;
+    if (callExpressionHasCallbackObject(expr)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow multi-statement or callback-nesting inline arrow functions in JSX handler props; extract to a named function above `return`.',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          maxStatements: { type: 'integer', minimum: 1 },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      tooManyStatements:
+        'Inline JSX handler "{{name}}" has {{count}} statements — extract a named function above `return`.',
+      nestedCallback:
+        'Inline JSX handler "{{name}}" contains nested callback object(s) — extract a named function above `return`.',
+    },
+  },
+  create(context) {
+    const options = context.options[0] ?? {};
+    const maxStatements = options.maxStatements ?? 2;
+
+    return {
+      JSXAttribute(node) {
+        if (!node.name || node.name.type !== 'JSXIdentifier') {
+          return;
+        }
+        const name = node.name.name;
+        if (!HANDLER_NAME.test(name)) {
+          return;
+        }
+        const value = node.value;
+        if (!value || value.type !== 'JSXExpressionContainer') {
+          return;
+        }
+        const expr = value.expression;
+        if (
+          expr.type !== 'ArrowFunctionExpression' &&
+          expr.type !== 'FunctionExpression'
+        ) {
+          return;
+        }
+        const count = countStatements(expr.body);
+        if (count > maxStatements) {
+          context.report({
+            node,
+            messageId: 'tooManyStatements',
+            data: { name, count },
+          });
+          return;
+        }
+        if (hasCallbackObjectArgument(expr.body)) {
+          context.report({
+            node,
+            messageId: 'nestedCallback',
+            data: { name },
+          });
+        }
+      },
+    };
+  },
+};

package/src/rules/no-render-prop-types.js

@@ -0,0 +1,136 @@
+// Enforces `.claude/rules/composition-over-render-props.md`: component props
+// should not be typed as render callbacks (`(...) => ReactNode`), component
+// references (`ComponentType<...>`, `FC<...>`), or unions thereof. Event
+// handler props (`onClick`, `onSubmit`, ...) return data, not JSX, and are
+// exempt.
+//
+// Known scope gaps — these patterns sneak through the AST visitors below and
+// must be caught by code review:
+// - Render-shaped props inherited via `Pick<Props, 'renderItem'>`.
+// - Prop shapes derived from `z.infer<typeof schema>` (no TSPropertySignature
+//   in the source AST — the shape comes from a type expression).
+// - Destructured arrow-fn parameters typed inline (no enclosing
+//   `TSInterfaceBody` / `TSTypeLiteral` — checker walks property signatures
+//   only).
+
+const EVENT_HANDLER = /^on[A-Z]/;
+
+const REACT_NODE_NAMES = new Set([
+  'ReactNode',
+  'ReactElement',
+  'ReactChild',
+  'ReactFragment',
+  'JSX.Element',
+  'React.ReactNode',
+  'React.ReactElement',
+]);
+
+const COMPONENT_TYPE_NAMES = new Set([
+  'ComponentType',
+  'FC',
+  'FunctionComponent',
+  'ElementType',
+  'React.ComponentType',
+  'React.FC',
+  'React.FunctionComponent',
+  'React.ElementType',
+]);
+
+function typeReferenceName(node) {
+  if (node.type !== 'TSTypeReference') {
+    return null;
+  }
+  const t = node.typeName;
+  if (t.type === 'Identifier') {
+    return t.name;
+  }
+  if (
+    t.type === 'TSQualifiedName' &&
+    t.left.type === 'Identifier' &&
+    t.right.type === 'Identifier'
+  ) {
+    return `${t.left.name}.${t.right.name}`;
+  }
+  return null;
+}
+
+function returnsReactNode(fnType) {
+  if (fnType.type !== 'TSFunctionType') {
+    return false;
+  }
+  const ret = fnType.returnType?.typeAnnotation;
+  if (!ret || ret.type !== 'TSTypeReference') {
+    return false;
+  }
+  const name = typeReferenceName(ret);
+  return name !== null && REACT_NODE_NAMES.has(name);
+}
+
+function isComponentTypeRef(node) {
+  const name = typeReferenceName(node);
+  return name !== null && COMPONENT_TYPE_NAMES.has(name);
+}
+
+function findViolation(typeNode) {
+  if (typeNode.type === 'TSFunctionType' && returnsReactNode(typeNode)) {
+    return { kind: 'renderCallback' };
+  }
+  if (typeNode.type === 'TSTypeReference' && isComponentTypeRef(typeNode)) {
+    return { kind: 'componentAsProp', typeName: typeReferenceName(typeNode) };
+  }
+  if (typeNode.type === 'TSUnionType') {
+    for (const member of typeNode.types) {
+      const v = findViolation(member);
+      if (v) {
+        return v;
+      }
+    }
+  }
+  return null;
+}
+
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow render-callback props and component-as-prop patterns; use `children` composition or per-mode component split.',
+    },
+    schema: [],
+    messages: {
+      renderCallback:
+        'Prop "{{name}}" returns ReactNode/JSX.Element — use `children` (or named ReactNode slots) instead of a render callback.',
+      componentAsProp:
+        'Prop "{{name}}" is typed as a component ({{typeName}}) — use `children` composition or split into per-mode components instead.',
+    },
+  },
+  create(context) {
+    function checkPropertySignature(node) {
+      if (!node.key || node.key.type !== 'Identifier') {
+        return;
+      }
+      const name = node.key.name;
+      if (EVENT_HANDLER.test(name)) {
+        return;
+      }
+      const ann = node.typeAnnotation?.typeAnnotation;
+      if (!ann) {
+        return;
+      }
+      const v = findViolation(ann);
+      if (!v) {
+        return;
+      }
+      context.report({
+        node,
+        messageId: v.kind,
+        data: { name, typeName: v.typeName ?? '' },
+      });
+    }
+
+    return {
+      'TSInterfaceBody > TSPropertySignature': checkPropertySignature,
+      'TSTypeLiteral > TSPropertySignature': checkPropertySignature,
+    };
+  },
+};

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

@@ -0,0 +1,332 @@
+// Enforces the nx: Tailwind class conventions from
+// `.claude/rules/shadcn-divergences.md` on
+// class strings (string literals and template literals). Ported from the
+// former `.claude/hooks/lint-nx-prefix.mjs` Claude hook so the checks run in
+// `pnpm lint` and the pre-commit hook for every contributor — not only on
+// in-session Claude edits.
+
+export const RAW_FONT_WEIGHTS = [
+  'thin',
+  'extralight',
+  'light',
+  'normal',
+  'medium',
+  'semibold',
+  'bold',
+  'extrabold',
+  'black',
+];
+
+export const RAW_LINE_HEIGHTS = [
+  'none',
+  'tight',
+  'snug',
+  'normal',
+  'relaxed',
+  'loose',
+];
+
+export const RAW_LETTER_SPACINGS = [
+  'tighter',
+  'tight',
+  'normal',
+  'wide',
+  'wider',
+  'widest',
+];
+
+const NAMED_VARIANT = String.raw`@?[\w-]+(?:\[[^\s]+?\])?(?:\/[\w-]+)?:`;
+const ARBITRARY_VARIANT = String.raw`\[[^\s]+?\]:`;
+const CHILD_VARIANT = String.raw`\*{1,2}:`;
+const NX_MODIFIER_CHAIN = String.raw`(?:${NAMED_VARIANT}|${ARBITRARY_VARIANT}|${CHILD_VARIANT})*`;
+
+const CHECKS = [
+  {
+    messageId: 'prefixOrder',
+    re: /[a-z][a-z0-9_-]*:nx:|\]:nx:/,
+  },
+  {
+    messageId: 'bannedAccent',
+    re: new RegExp(`nx:${NX_MODIFIER_CHAIN}(?:bg|text)-accent\\b`),
+  },
+  {
+    messageId: 'incompletePath',
+    re: new RegExp(
+      `nx:${NX_MODIFIER_CHAIN}(?:bg|text|border)-(?:primary|secondary|error|success|warning|information|destructive)(?![\\w-])`
+    ),
+  },
+  {
+    messageId: 'rawPrimitive',
+    re: new RegExp(
+      `nx:${NX_MODIFIER_CHAIN}(?:bg|text|border)-(?:slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-\\d{2,3}`
+    ),
+  },
+  {
+    messageId: 'rawFontSize',
+    re: new RegExp(
+      `nx:${NX_MODIFIER_CHAIN}text-(?:xs|sm|base|lg|xl|[2-9]xl)\\b`
+    ),
+  },
+  {
+    messageId: 'rawFontWeight',
+    re: new RegExp(
+      `nx:${NX_MODIFIER_CHAIN}font-(?:${RAW_FONT_WEIGHTS.join('|')})\\b`
+    ),
+    runtimeOnly: true,
+  },
+  {
+    messageId: 'rawLineHeight',
+    re: new RegExp(
+      `nx:${NX_MODIFIER_CHAIN}leading-(?:${RAW_LINE_HEIGHTS.join('|')}|\\d+|\\[)`
+    ),
+    runtimeOnly: true,
+  },
+  {
+    messageId: 'rawLetterSpacing',
+    re: new RegExp(
+      `nx:${NX_MODIFIER_CHAIN}tracking-(?:${RAW_LETTER_SPACINGS.join('|')}|\\[)`
+    ),
+    runtimeOnly: true,
+  },
+];
+
+// Only a width or a colour paints a ring. `outline-none` / `outline-hidden`
+// suppress one, `outline-0` is a zero width, `outline-offset-*` shifts a ring
+// it does not paint, and the style keywords set `outline-style` alone.
+const RING_PAINTING_OUTLINE =
+  /focus-visible:outline-(?!none\b|hidden\b|0\b|offset-|solid\b|dashed\b|dotted\b|double\b)/;
+
+// `nx:transition-colors` expands to a property list that includes
+// `outline-color`, so a surface that also paints a focus ring fades the ring in
+// over the duration instead of landing it with the keypress.
+function fadesItsFocusRing(scope) {
+  return (
+    /\bnx:transition-colors\b/.test(scope) && RING_PAINTING_OUTLINE.test(scope)
+  );
+}
+
+function isStoryFile(filename) {
+  return /\.stories\.[jt]sx?$/.test(filename);
+}
+
+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.
+function isExampleFile(filename) {
+  return isStoryFile(filename) || isDocsFile(filename);
+}
+
+// The ring check skips less: only the docs pages, which render a pairing as
+// the subject of the prose around it. The rest of the docs app is its own
+// shipped chrome, and a story's class strings are the component's real ones.
+function isDocsSpecimenPage(filename) {
+  return /(?:^|[/\\])apps[/\\]docs[/\\]app[/\\]_pages[/\\]/.test(filename);
+}
+
+const RAW_TYPOGRAPHY_EXCEPTIONS = [
+  {
+    filename:
+      /(?:^|[/\\])packages[/\\]react[/\\]src[/\\]components[/\\]avatar[/\\]avatar\.tsx$/,
+    className:
+      'nx:flex nx:size-full nx:items-center nx:justify-center nx:rounded-[inherit] nx:bg-muted nx:text-foreground nx:font-medium nx:leading-none',
+    messageIds: new Set(['rawFontWeight', 'rawLineHeight']),
+  },
+  {
+    filename:
+      /(?:^|[/\\])packages[/\\]react[/\\]src[/\\]components[/\\]chart[/\\]chart\.tsx$/,
+    className: 'nx:text-foreground nx:font-mono nx:font-medium nx:tabular-nums',
+    messageIds: new Set(['rawFontWeight']),
+  },
+];
+
+function normalizeClassName(raw) {
+  return raw.trim().replace(/\s+/g, ' ');
+}
+
+function isRawTypographyException(check, filename, raw) {
+  const normalized = normalizeClassName(raw);
+  return RAW_TYPOGRAPHY_EXCEPTIONS.some(
+    (exception) =>
+      exception.filename.test(filename) &&
+      exception.className === normalized &&
+      exception.messageIds.has(check.messageId)
+  );
+}
+
+function shouldRunCheck(check, filename, raw) {
+  if (!check.runtimeOnly) {
+    return true;
+  }
+  if (isExampleFile(filename)) {
+    return false;
+  }
+  return !isRawTypographyException(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);
+    }
+  }
+  return matched;
+}
+
+// A class composer joins every string it is handed — base, array element,
+// `variants` value — so the whole call is one scope. The name has to be
+// written plainly; an aliased or member-expression composer is invisible.
+const CLASS_COMPOSING_CALLEES = new Set(['cva', 'cn', 'clsx', 'cx']);
+
+// `[…].join(' ')` collapses the array literal into one class attribute.
+function isJoinedArrayLiteral(node) {
+  const { callee } = node;
+  return (
+    callee.type === 'MemberExpression' &&
+    !callee.computed &&
+    callee.object.type === 'ArrayExpression' &&
+    callee.property.type === 'Identifier' &&
+    callee.property.name === 'join'
+  );
+}
+
+function isClassComposingCall(node) {
+  if (node.type !== 'CallExpression') {
+    return false;
+  }
+  if (node.callee.type === 'Identifier') {
+    return CLASS_COMPOSING_CALLEES.has(node.callee.name);
+  }
+  return isJoinedArrayLiteral(node);
+}
+
+// A string handed to some other function reaches the class attribute only
+// through that call's return value, so it leaves the scope.
+function breaksClassScope(node) {
+  return node.type === 'CallExpression' && !isClassComposingCall(node);
+}
+
+function isInsideClassCall(node) {
+  for (let current = node.parent; current; current = current.parent) {
+    if (isClassComposingCall(current)) {
+      return true;
+    }
+    if (breaksClassScope(current)) {
+      return false;
+    }
+  }
+  return false;
+}
+
+// Every class string a node can contribute: its own value, a template
+// literal's quasis, and the same for anything nested inside it that still
+// reaches the same class attribute.
+function collectClassStrings(node, visitorKeys, collected) {
+  if (node.type === 'Literal') {
+    if (typeof node.value === 'string') {
+      collected.push(node.value);
+    }
+    return;
+  }
+  if (node.type === 'TemplateLiteral') {
+    for (const quasi of node.quasis) {
+      collected.push(quasi.value.cooked ?? quasi.value.raw);
+    }
+  }
+  for (const key of visitorKeys[node.type] ?? []) {
+    const child = node[key];
+    for (const value of Array.isArray(child) ? child : [child]) {
+      if (value?.type && !breaksClassScope(value)) {
+        collectClassStrings(value, visitorKeys, collected);
+      }
+    }
+  }
+}
+
+export default {
+  meta: {
+    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.',
+    },
+    schema: [],
+    messages: {
+      prefixOrder:
+        'Wrong nx: prefix order — `nx:` must come BEFORE all modifiers (e.g. `nx:hover:bg-*`, not `hover:nx:bg-*`).',
+      bannedAccent:
+        'Banned `accent` token — nxds has no `accent`; use `background-hover` / `container-hover` / `popover-hover` (see shadcn-divergences.md).',
+      incompletePath:
+        'Incomplete semantic token path — add a `-background`, `-foreground`, or `-subtle` suffix (e.g. `nx:bg-primary-background`).',
+      rawPrimitive:
+        'Raw Tailwind primitive color — use a semantic token instead (e.g. `nx:bg-primary-background`, not `nx:bg-blue-500`).',
+      rawFontSize:
+        'Raw Tailwind font-size utility — use a typography composite instead (e.g. `nx:typography-body-default`, not `nx:text-sm`).',
+      rawFontWeight:
+        'Raw Tailwind font-weight utility — use a typography composite instead (e.g. `nx:typography-label-default`, not `nx:font-medium`).',
+      rawLineHeight:
+        '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-*`.',
+      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).',
+    },
+  },
+  create(context) {
+    const filename = context.filename ?? '';
+    const { visitorKeys } = context.sourceCode;
+
+    function report(node, raw) {
+      for (const messageId of matchedMessageIds(raw, filename)) {
+        context.report({ node, messageId });
+      }
+    }
+
+    function reportScope(node) {
+      if (isDocsSpecimenPage(filename) || isInsideClassCall(node)) {
+        return;
+      }
+      const collected = [];
+      collectClassStrings(node, visitorKeys, collected);
+      if (fadesItsFocusRing(collected.join(' '))) {
+        context.report({ node, messageId: 'ringFadingTransition' });
+      }
+    }
+
+    return {
+      Literal(node) {
+        if (typeof node.value !== 'string') {
+          return;
+        }
+        report(node, node.value);
+        reportScope(node);
+      },
+      TemplateLiteral(node) {
+        const matched = new Set();
+        for (const quasi of node.quasis) {
+          const raw = quasi.value.cooked ?? quasi.value.raw;
+          for (const id of matchedMessageIds(raw, filename)) {
+            matched.add(id);
+          }
+        }
+        for (const messageId of matched) {
+          context.report({ node, messageId });
+        }
+        reportScope(node);
+      },
+      CallExpression(node) {
+        if (!isClassComposingCall(node)) {
+          return;
+        }
+        reportScope(node);
+      },
+    };
+  },
+};

package/src/tailwind.js

@@ -0,0 +1,52 @@
+import betterTailwindcss from 'eslint-plugin-better-tailwindcss';
+import { getDefaultSelectors } from 'eslint-plugin-better-tailwindcss/defaults';
+import path from 'node:path';
+
+// `matchesName` requires a full match, hence the leading `.*`.
+const tailwindClassSelectors = [
+  ...getDefaultSelectors(),
+  {
+    kind: 'attribute',
+    name: '.*ClassName',
+    match: [{ type: 'strings' }],
+  },
+  {
+    kind: 'variable',
+    name: '.*(?:ClassName|Class|Classes)',
+    match: [{ type: 'strings' }],
+  },
+  {
+    kind: 'variable',
+    name: '.*CLASSES',
+    match: [{ type: 'objectValues' }],
+  },
+  {
+    kind: 'variable',
+    name: '.*',
+    match: [{ type: 'objectValues', path: '(?:^|\\.)className$' }],
+  },
+];
+
+export function nxdsTailwindClassesConfig(options) {
+  const { files, entryPoint } = options;
+  if (typeof entryPoint !== 'string' || !path.isAbsolute(entryPoint)) {
+    throw new Error(
+      `nxdsTailwindClassesConfig: \`entryPoint\` must be an absolute path, got '${entryPoint}'.`
+    );
+  }
+
+  return {
+    ...(files ? { files } : {}),
+    plugins: { 'better-tailwindcss': betterTailwindcss },
+    settings: {
+      'better-tailwindcss': { entryPoint, selectors: tailwindClassSelectors },
+    },
+    rules: {
+      // `dark` is the hook for the `@custom-variant dark` in nxds.css.
+      'better-tailwindcss/no-unknown-classes': [
+        'error',
+        { ignore: ['^dark$'] },
+      ],
+    },
+  };
+}