@sando-ui/eslint-plugin 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Song
+
+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,65 @@
-# Temporary Holding Version
+# @sando-ui/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.
+ESLint rules a service repository runs over its own screens and CSS beside installed Sando units.
+Sando UI is a component design system (React Aria for behavior, Vanilla CSS and design tokens for
+look) distributed as a copy-paste registry. These rules keep your own code on the system's tokens
+and public classes, and keep your screens renderable from props alone.
+
+## Install
+
+Install it with the CLI, both pinned to the same exact version (`<version>` is the Sando version you install, such as `0.1.0`):
+
+```sh
+npm install -D --save-exact @sando-ui/cli@<version> @sando-ui/eslint-plugin@<version>
+```
+
+Requires Node.js 22.13 or later and ESLint 9.24 or later. `sando check` runs these rules for you.
+
+## Usage
+
+```js
+// eslint.config.js
+import { defineConfig } from 'eslint/config'
+import sando from '@sando-ui/eslint-plugin'
+
+export default defineConfig([{ extends: [sando.configs.recommended] }])
+```
+
+The `recommended` config reads `design/product.json` from the directory ESLint runs in.
+
+## Rules
+
+Screens and units (TSX):
+
+| Rule | What it enforces |
+|---|---|
+| `sando/screen-imports` | A screen imports no other screen, only units `product.json` lists, and nothing `denyImports` names. |
+| `sando/story-args-only` | A screen story is data: the meta holds `component`, `title` and `args`; each story holds `args` and `name`. |
+| `sando/installed-units` | An import of `src/{components,blocks,layouts}/*` lands on a file `design/sando.lock.json` records as installed. |
+| `sando/shared-class-only` | An `sd-*` class in `className` is one the system makes public. |
+| `sando/policy-props` | A unit's prop takes only the values `policy.props` allows. |
+| `sando/policy-units` | A screen places only the units its screen type allows. |
+| `sando/no-inline-scale-literal` | No spacing, border width or color literal in an inline `style` object. |
+
+Stylesheets (CSS):
+
+| Rule | What it enforces |
+|---|---|
+| `sando/token-tier` | A `var(--sd-*)` names an existing system token, never a component or reference token. |
+| `sando/no-scale-literal` | No spacing, border width or color literal: a system token carries them. |
+| `sando/own-prefix` | Every class and custom property you define starts with your product prefix. |
+| `sando/no-reach` | No selector reaches into a Sando unit. |
+| `sando/type-whole` | No per-property type declarations: use `Text` or one `.sd-type-*` class. |
+| `sando/theme-in-token` | No hand-built theme cascade: themes come from tokens. |
+
+The recommended config also enables ESLint core rules that keep a screen free of network, storage,
+clock and effect calls. Every rule id is stable, so `eslint --suppress-all` works as usual.
+
+## Documentation
+
+The registry and its documentation are at <https://sando-ui.github.io>. The full guide is installed
+into `docs/sando/` by `sando install` from `@sando-ui/cli`.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/lib/configs.mjs

@@ -0,0 +1,176 @@
+// The shared config a service extends. It reads design/product.json at config-evaluation time,
+// because S7's core-rule options and U4/U5's policy are static options, not runtime lookups.
+//
+//   // eslint.config.js
+//   import { defineConfig } from 'eslint/config'
+//   import sando from '@sando-ui/eslint-plugin'
+//   export default defineConfig([{ extends: [sando.configs.recommended] }])
+//
+// Every rule id is stable (`sando/<name>` or an ESLint core rule), so `eslint --suppress-all`
+// bulk suppression works as for any rule.
+
+import './typescript-api.mjs' // first: it must run before the parser loads
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import css from '@eslint/css'
+import tsParser from '@typescript-eslint/parser'
+import { DEFAULT_DENY_IMPORTS } from './rules/screens.mjs'
+
+const INSTALLED = ['src/components/**', 'src/blocks/**', 'src/layouts/**', 'src/styles/**']
+const SCREENS = ['src/screens/**/*.{ts,tsx,js,jsx}']
+const STORIES = ['src/screens/**/*.stories.{ts,tsx,js,jsx}']
+
+// ── S7 screen purity: what breaks rendering every state without a backend (plan § 1.3) ───────
+const NETWORK = ['fetch', 'XMLHttpRequest', 'WebSocket', 'EventSource']
+const GLOBALS = {
+  network: NETWORK,
+  storage: ['localStorage', 'sessionStorage', 'indexedDB', 'caches'],
+  url: ['location', 'history', 'open', 'parent', 'top', 'opener', 'postMessage'],
+  time: ['setTimeout', 'setInterval', 'requestAnimationFrame'],
+  dom: ['document', 'addEventListener', 'removeEventListener', 'scrollTo', 'matchMedia'],
+}
+const PROPERTIES = [
+  ['navigator', 'sendBeacon'],
+  ['Date', 'now'],
+  ['performance', 'now'],
+  ['Math', 'random'],
+  ['crypto', 'randomUUID'],
+  ['crypto', 'getRandomValues'],
+  ['React', 'useEffect'],
+  ['React', 'useLayoutEffect'],
+  ['React', 'useInsertionEffect'],
+  ['React', 'useSyncExternalStore'],
+]
+const GLOBAL_OBJECTS = ['window', 'globalThis', 'self']
+const EFFECTS = ['useEffect', 'useLayoutEffect', 'useInsertionEffect', 'useSyncExternalStore']
+// The one exception (plan § 1.3): a viewport hook in src/screens/lib reads matchMedia through
+// useSyncExternalStore. It is presentation, not data.
+const LIB_EXCEPTION = ['matchMedia', 'useSyncExternalStore', 'React.useSyncExternalStore']
+
+/**
+ * The S7 core-rule set, with `allow` names removed: a global (`setTimeout`), a property
+ * (`Date.now`, `window.scrollTo`) or a React effect (`useEffect`).
+ */
+export function purityRules(allow = []) {
+  const allowed = new Set(allow)
+  const why = 'a screen renders from props alone; move this to the route layer (Sando screen purity)'
+  const windowAllowed = [...allowed].filter((n) => /^(window|globalThis|self)\./.test(n)).map((n) => n.split('.')[1])
+  return {
+    'no-restricted-globals': [
+      'error',
+      ...Object.values(GLOBALS).flat().filter((n) => !allowed.has(n)).map((name) => ({ name, message: why })),
+    ],
+    'no-restricted-properties': [
+      'error',
+      ...PROPERTIES.filter(([o, p]) => !allowed.has(`${o}.${p}`) && !allowed.has(p)).map(([object, property]) => ({ object, property, message: why })),
+      ...GLOBAL_OBJECTS.map((object) => ({
+        object,
+        message: why,
+        ...(windowAllowed.length ? { allowProperties: windowAllowed } : {}),
+      })),
+    ],
+    'no-restricted-syntax': [
+      'error',
+      ...(allowed.has('new Date()')
+        ? []
+        : [
+            { selector: "NewExpression[callee.name='Date'][arguments.length=0]", message: `\`new Date()\` reads the clock; take a \`now\` prop. ${why}` },
+            { selector: "CallExpression[callee.name='Date']", message: `\`Date()\` reads the clock; take a \`now\` prop. ${why}` },
+          ]),
+      { selector: "MemberExpression[object.type='MetaProperty'][property.name='env']", message: `\`import.meta.env\` is build configuration; ${why}` },
+      // Effects by named import from `react`. A namespace import (`import * as React`) is fine;
+      // its `React.useEffect` is caught by no-restricted-properties above.
+      ...EFFECTS.filter((e) => !allowed.has(e)).map((e) => ({
+        selector: `ImportDeclaration[source.value='react'] > ImportSpecifier[imported.name='${e}']`,
+        message: `\`${e}\` runs after render; ${why}`,
+      })),
+    ],
+  }
+}
+
+const readJson = (path) => {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Build the flat config for one service root.
+ * @param {{ root?: string, product?: object, tokenNames?: string, lock?: string }} [options]
+ *   `product` overrides reading `<root>/design/product.json`; `tokenNames` and `lock` override the
+ *   installed paths (a test fixture feeds both).
+ */
+export function createConfig(plugin, options = {}) {
+  const root = options.root ?? process.cwd()
+  const product = options.product ?? readJson(join(root, 'design/product.json')) ?? {}
+  const policy = product.policy ?? {}
+  const tokenNames = options.tokenNames ?? join(root, 'src/styles/token-names.json')
+  const lock = options.lock ?? join(root, 'design/sando.lock.json')
+  const allow = (policy.screen?.allowGlobals ?? []).map((g) => g.name)
+  const denyImports = [...DEFAULT_DENY_IMPORTS, ...(policy.screen?.denyImports ?? [])]
+  const tsx = {
+    files: ['src/**/*.{ts,tsx,js,jsx}'],
+    languageOptions: { parser: tsParser, parserOptions: { ecmaFeatures: { jsx: true } }, sourceType: 'module' },
+  }
+  return [
+    // Installed Sando files are not the service's code and may not be edited (U6 holds them), so
+    // ESLint never lints them: a directive they carry for a rule this config does not register
+    // (`@typescript-eslint/no-explicit-any` in icons.tsx) would otherwise be an unknown-rule error.
+    { name: 'sando/installed', ignores: INSTALLED },
+    // The parser still reaches every TSX file, for a service config that scopes the ignore away.
+    { name: 'sando/tsx-parser', ...tsx },
+    {
+      name: 'sando/tsx',
+      files: tsx.files,
+      ignores: INSTALLED,
+      plugins: { sando: plugin },
+      rules: {
+        'sando/installed-units': ['error', { root, lock }],
+        'sando/shared-class-only': ['error', { tokenNames }],
+        'sando/policy-props': ['error', { root, props: policy.props ?? [] }],
+        'sando/no-inline-scale-literal': 'error',
+      },
+    },
+    {
+      name: 'sando/screens',
+      files: SCREENS,
+      ignores: STORIES,
+      rules: {
+        ...purityRules(allow),
+        'sando/screen-imports': ['error', { root, units: product.units ?? null, denyImports }],
+        'sando/policy-units': ['error', { root, screens: policy.screens ?? {}, screenTypes: policy.screenTypes ?? {} }],
+      },
+    },
+    {
+      name: 'sando/screens-lib',
+      files: ['src/screens/lib/**/*.{ts,tsx,js,jsx}'],
+      ignores: STORIES,
+      rules: { ...purityRules([...allow, ...LIB_EXCEPTION]), 'sando/policy-units': 'off' },
+    },
+    {
+      name: 'sando/screen-stories',
+      files: STORIES,
+      rules: {
+        'sando/story-args-only': 'error',
+        'no-restricted-globals': ['error', ...NETWORK.map((name) => ({ name, message: 'a story is data; it never fetches' }))],
+      },
+    },
+    {
+      name: 'sando/css',
+      files: ['src/**/*.css'],
+      ignores: INSTALLED,
+      plugins: { css, sando: plugin },
+      language: 'css/css',
+      rules: {
+        'sando/token-tier': ['error', { tokenNames }],
+        'sando/no-scale-literal': 'error',
+        'sando/own-prefix': ['error', { prefix: product.prefix ?? null }],
+        'sando/no-reach': 'error',
+        'sando/type-whole': 'error',
+        'sando/theme-in-token': 'error',
+      },
+    },
+  ]
+}

package/lib/index.mjs

@@ -0,0 +1,41 @@
+// @sando-ui/eslint-plugin: the TSX and CSS rules a service repository runs over its own code
+// beside installed Sando units. Rule ids and option schemas are listed in surface.json.
+
+import { readFileSync } from 'node:fs'
+import { createConfig } from './configs.mjs'
+import { noReach, noScaleLiteral, ownPrefix, themeInToken, tokenTier, typeWhole } from './rules/css.mjs'
+import { screenImports, storyArgsOnly } from './rules/screens.mjs'
+import { installedUnits, noInlineScaleLiteral, policyProps, policyUnits, sharedClassOnly } from './rules/units.mjs'
+
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+
+const plugin = {
+  meta: { name: pkg.name, version: pkg.version },
+  rules: {
+    'screen-imports': screenImports,
+    'story-args-only': storyArgsOnly,
+    'installed-units': installedUnits,
+    'shared-class-only': sharedClassOnly,
+    'policy-props': policyProps,
+    'policy-units': policyUnits,
+    'no-inline-scale-literal': noInlineScaleLiteral,
+    'token-tier': tokenTier,
+    'no-scale-literal': noScaleLiteral,
+    'own-prefix': ownPrefix,
+    'no-reach': noReach,
+    'type-whole': typeWhole,
+    'theme-in-token': themeInToken,
+  },
+  configs: {},
+}
+
+let recommended
+Object.defineProperty(plugin.configs, 'recommended', {
+  enumerable: true,
+  // Read product.json from the directory ESLint runs in, once, when a config first asks.
+  get: () => (recommended ??= createConfig(plugin)),
+})
+
+/** The shared config for an explicit service root (the CLI and tests pass one). */
+export const configure = (options) => createConfig(plugin, options)
+export default plugin

package/lib/resolve.mjs

@@ -0,0 +1,65 @@
+// Where an import LANDS, as a repository path, and which Sando unit that path is.
+//
+// Policy is written in repo paths (`src/app/api/*`) and registry item names (`plan-card`), while
+// code is written in specifiers (`../app/api/client`, `./PlanCard`). Matching the specifier text
+// would let `../layouts/../screens/Auth` wear a legal prefix, so every rule here resolves first and
+// tests where the import actually lands (the same reasoning as Sando's own screen check).
+
+import { posix, relative, resolve, dirname, sep } from 'node:path'
+
+const toPosix = (p) => p.split(sep).join('/')
+
+/**
+ * The repo path an import specifier lands on, or `null` for a package import.
+ * Relative specifiers resolve against the importing file; `@/x` and `src/x` read as `src/x`.
+ * ponytail: only the `@/` alias is known; other tsconfig/vite aliases read as packages. Read the
+ * service's alias map when a consumer uses another one.
+ */
+export function repoPath(spec, filename, root) {
+  if (spec.startsWith('.')) {
+    return posix.normalize(toPosix(relative(root, resolve(dirname(filename), spec))))
+  }
+  if (spec.startsWith('@/')) return posix.normalize(`src/${spec.slice(2)}`)
+  if (spec.startsWith('src/')) return posix.normalize(spec)
+  return null
+}
+
+export const kebab = (name) =>
+  name
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/([A-Z])([A-Z][a-z])/g, '$1-$2')
+    .toLowerCase()
+
+const UNIT_PATH = /^src\/(components|blocks|layouts)\/([A-Z][A-Za-z0-9]*)(?:\.(?:tsx|ts|jsx|js))?$/
+
+/**
+ * The installed Sando unit a repo path names, or `null`.
+ * A unit is its MODULE FILE: `src/components/Card.tsx` is the registry item `card`, and every
+ * component that file exports (`Card`, `CardHeader`) belongs to `card`.
+ */
+export function unitOf(path) {
+  const m = path && UNIT_PATH.exec(path)
+  return m ? { file: `src/${m[1]}/${m[2]}.tsx`, unit: kebab(m[2]) } : null
+}
+
+/** Map every imported local binding in the file to the unit its module is, for JSX lookups. */
+export function unitBindings(program, filename, root) {
+  const out = new Map()
+  for (const node of program.body) {
+    if (node.type !== 'ImportDeclaration') continue
+    const unit = unitOf(repoPath(node.source.value, filename, root))
+    if (!unit) continue
+    for (const s of node.specifiers) out.set(s.local.name, unit.unit)
+  }
+  return out
+}
+
+/** The local binding a JSX element name starts with: `Card` for `<Card>` and `<Card.Header>`. */
+export function jsxRootName(name) {
+  let n = name
+  while (n.type === 'JSXMemberExpression') n = n.object
+  return n.type === 'JSXIdentifier' ? n.name : null
+}
+
+/** A repo-path glob test (`*` within a segment, `**` across), via node's own matcher. */
+export const matchesGlob = (path, glob) => posix.matchesGlob(path, glob)

package/lib/rules/css.mjs

@@ -0,0 +1,167 @@
+// C1 to C6: the stylesheet a service writes beside installed Sando units, read with @eslint/css.
+// Source of every rule: docs/guide/styling-contract.md (shipped to the service as
+// docs/sando/styling-contract.md). Installed Sando files are out of scope: the shared config
+// ignores src/{components,blocks,layouts,styles}.
+//
+// NOT seen here: CSS-in-JS and `<style>` blocks (only `*.css` files reach the CSS language), the
+// TIER of a `var()` inside an inline `style={{}}` (C2's inline half reads literals only), and
+// state styling through `[data-*]` on your own element (C7, deferred).
+
+import { classify, loadTokenNames } from '../token-names.mjs'
+
+const SOURCE = 'docs/sando/styling-contract.md'
+const rule = (id, section, description, create, schema = []) => ({
+  meta: {
+    type: 'problem',
+    docs: { description, url: `${SOURCE}#${section}`, sandoId: id },
+    schema,
+    messages: { violation: '{{message}} ({{source}})' },
+  },
+  create(context) {
+    const report = (node, message) =>
+      context.report({ node, messageId: 'violation', data: { message, source: `${SOURCE} § ${section}` } })
+    return create(context, report)
+  },
+})
+
+// ── shared property families (Sando's own css-literal check uses the same three) ─────────────
+const SIDES = '(-(top|right|bottom|left|block|inline)(-(start|end))?)?'
+export const isSpaceProp = (p) => new RegExp(`^(gap|row-gap|column-gap|padding${SIDES}|margin${SIDES})$`).test(p)
+export const isWidthProp = (p) =>
+  new RegExp(`^(border${SIDES}(-width)?|outline(-width)?|column-rule(-width)?)$`).test(p)
+export const isColorProp = (p) =>
+  new RegExp(
+    `^(color|background|background-color|border${SIDES}(-color)?|outline(-color)?|fill|stroke|caret-color|accent-color|text-decoration-color|column-rule(-color)?)$`,
+  ).test(p)
+export const TYPE_PROPS = new Set(['font', 'font-size', 'line-height', 'font-weight', 'letter-spacing'])
+const THEME_ATTRS = new Set(['data-theme', 'data-brand', 'data-contrast', 'data-context', 'data-ground'])
+const THEME_FEATURES = new Set(['prefers-color-scheme', 'prefers-contrast'])
+const COLOR_FN = /^(rgba?|hsla?|hwb|lab|lch|oklab|oklch|color)$/i
+
+/** Literal findings in one value tree: `space` / `width` lengths and colour literals. */
+function literalsIn(node, out = []) {
+  if (!node || typeof node !== 'object') return out
+  if (node.type === 'Function' && node.name === 'var') return out
+  if (node.type === 'Dimension' && Number(node.value) !== 0) out.push({ kind: 'length', text: `${node.value}${node.unit}` })
+  if (node.type === 'Hash') out.push({ kind: 'color', text: `#${node.value}` })
+  if (node.type === 'Function' && COLOR_FN.test(node.name)) out.push({ kind: 'color', text: `${node.name}()` })
+  for (const c of node.children ?? []) literalsIn(c, out)
+  return out
+}
+
+export const tokenTier = rule(
+  'C1',
+  'read-sys-tokens-never-cmp-or-ref',
+  'A `var(--sd-*)` must name an existing Sys token: never Cmp, never Ref.',
+  (context, report) => {
+    const [{ tokenNames }] = context.options
+    const names = loadTokenNames(tokenNames)
+    let missingReported = false
+    return {
+      "Function[name='var']"(node) {
+        const name = node.children?.[0]?.name
+        if (!name?.startsWith('--sd-')) return
+        if (!names) {
+          if (!missingReported) report(node, `cannot read ${tokenNames}; reinstall the \`styles\` item`)
+          missingReported = true
+          return
+        }
+        const tier = classify(name, names)
+        if (tier === 'sys') return
+        report(
+          node,
+          tier === 'unknown'
+            ? `\`${name}\` is not a Sando token; the declaration would silently drop`
+            : `\`${name}\` is a ${tier === 'cmp' ? 'Cmp' : 'Ref'} token; read the Sys role instead`,
+        )
+      },
+    }
+  },
+  [{ type: 'object', properties: { tokenNames: { type: 'string' } }, required: ['tokenNames'], additionalProperties: false }],
+)
+
+export const noScaleLiteral = rule(
+  'C2',
+  'never-write-a-literal-for-a-value-a-scale-carries',
+  'No non-zero length in gap/padding/margin or a border width, and no colour literal: a Sys family carries them.',
+  (context, report) => ({
+    Declaration(node) {
+      const p = node.property.toLowerCase()
+      if (p.startsWith('--')) return
+      const lengths = isSpaceProp(p) || isWidthProp(p)
+      for (const f of literalsIn(node.value)) {
+        if (f.kind === 'length' && lengths) report(node, `\`${p}: ${f.text}\`; use a \`--sd-${isSpaceProp(p) ? 'space' : 'border'}-*\` token`)
+        if (f.kind === 'color' && isColorProp(p)) report(node, `colour literal \`${f.text}\` in \`${p}\`; use a \`--sd-color-*\` role`)
+      }
+    },
+  }),
+)
+
+export const ownPrefix = rule(
+  'C3',
+  'your-own-class-prefix-never-sd-',
+  'Every class and custom property you define starts with the product prefix (`product.json` `prefix`).',
+  (context, report) => {
+    const raw = context.options[0]?.prefix
+    const prefix = raw ? raw.replace(/-$/, '') + '-' : null
+    const check = (node, name, what) => {
+      if (name.startsWith('sd-')) return what === 'class' ? undefined : report(node, `\`--${name}\` defines a property in Sando's \`sd-\` namespace`)
+      if (!prefix) return report(node, `${what} \`${name}\`: declare \`prefix\` in design/product.json`)
+      if (!name.startsWith(prefix)) report(node, `${what} \`${what === 'class' ? '.' : '--'}${name}\` does not start with \`${prefix}\``)
+    }
+    return {
+      ClassSelector(node) {
+        check(node, node.name, 'class')
+      },
+      Declaration(node) {
+        if (node.property.startsWith('--')) check(node, node.property.slice(2), 'custom property')
+      },
+    }
+  },
+  [{ type: 'object', properties: { prefix: { type: ['string', 'null'] } }, additionalProperties: false }],
+)
+
+export const noReach = rule(
+  'C4',
+  'one-class-per-element-no-reaching-into-a-unit',
+  'No selector into a Sando unit: no `.sd-*` class and no `[class*="sd-"]` attribute match.',
+  (context, report) => ({
+    ClassSelector(node) {
+      if (node.name.startsWith('sd-')) report(node, `\`.${node.name}\` targets Sando's implementation; use the unit's props`)
+    },
+    AttributeSelector(node) {
+      const value = node.value?.value ?? node.value?.name ?? ''
+      if (node.name.name === 'class' && value.includes('sd-')) report(node, '`[class…sd-]` targets Sando classes; use the unit\'s props')
+    },
+  }),
+)
+
+export const typeWhole = rule(
+  'C5',
+  'type-comes-whole-from-a-role',
+  'No per-property type (`font`, `font-size`, `line-height`, `font-weight`, `letter-spacing`): use `Text` or one `.sd-type-*` class.',
+  (context, report) => ({
+    Declaration(node) {
+      const p = node.property.toLowerCase()
+      if (TYPE_PROPS.has(p)) report(node, `\`${p}\` set by property; a type role sets all four together`)
+    },
+  }),
+)
+
+export const themeInToken = rule(
+  'C6',
+  'the-theme-is-already-in-the-token',
+  'No hand-built theme cascade: no `prefers-color-scheme`/`prefers-contrast` query and no theme attribute selector.',
+  (context, report) => {
+    const feature = (node) => {
+      if (THEME_FEATURES.has(node.name)) report(node, `\`${node.name}\` query; a Sys role already follows it`)
+    }
+    return {
+      Feature: feature,
+      MediaFeature: feature,
+      AttributeSelector(node) {
+        if (THEME_ATTRS.has(node.name.name)) report(node, `\`[${node.name.name}]\` selector; a Sys role already follows it`)
+      },
+    }
+  },
+)

package/lib/rules/screens.mjs

@@ -0,0 +1,122 @@
+// S7's import half and the screen-story rule.
+//
+// screen-imports resolves every relative or `@/` specifier to the repo path it LANDS on before
+// judging it, because `no-restricted-imports` matches specifier text: `src/app/api/*` would never
+// match `../app/api/client`, and `../layouts/../screens/Auth` would pass a prefix test.
+//
+//   * a screen (or src/screens/lib) importing another screen, `src/screens/<Name>`
+//   * an installed unit (`src/{components,blocks,layouts}/<Name>`) whose item is not in
+//     product.json `units` (when `units` is given); U1 separately asks whether it is installed
+//   * any `denyImports` glob. A glob is matched against the landed REPO path for a relative or `@/`
+//     import and against the specifier itself for a package import. Defaults: `react-dom/client`
+//     and `src/styles/*.css` (global sheets), plus product.json `policy.screen.denyImports`.
+//
+// Everything else is allowed: the list is a denylist, so a service's i18n, context, form and
+// logic modules pass without being named.
+// NOT seen: dynamic `import(variable)`, `require()`, and aliases other than `@/` (resolve.mjs).
+
+import { matchesGlob, repoPath, unitOf } from '../resolve.mjs'
+
+export const DEFAULT_DENY_IMPORTS = ['react-dom/client', 'src/styles/*.css']
+const SCREEN_FILE = /^src\/screens\/(?!lib\/)[^/]+$/
+const CODE_EXT = /\.(tsx?|jsx?)$/
+
+const meta = (id, description, source, schema) => ({
+  type: 'problem',
+  docs: { description, url: source, sandoId: id },
+  schema,
+  messages: { violation: '{{message}} ({{source}})' },
+})
+
+export const screenImports = {
+  meta: meta(
+    'S7',
+    'A screen imports no other screen, only units listed in product.json `units`, and nothing `denyImports` names (matched on the resolved repo path).',
+    'docs/sando/design-language.md § Building a screen',
+    [
+      {
+        type: 'object',
+        properties: {
+          root: { type: 'string' },
+          units: { type: ['array', 'null'], items: { type: 'string' } },
+          denyImports: { type: 'array', items: { type: 'string' } },
+        },
+        additionalProperties: false,
+      },
+    ],
+  ),
+  create(context) {
+    const { root = context.cwd, units = null, denyImports = DEFAULT_DENY_IMPORTS } = context.options[0] ?? {}
+    const source = meta('S7', '', 'docs/sando/design-language.md § Building a screen').docs.url
+    const report = (node, message) => context.report({ node, messageId: 'violation', data: { message, source } })
+    const judge = (node) => {
+      if (node?.type !== 'Literal' || typeof node.value !== 'string') return
+      const spec = node.value
+      const landed = repoPath(spec, context.filename, root)
+      const subject = landed ?? spec
+      if (landed && SCREEN_FILE.test(landed) && (!/\.[a-z]+$/.test(landed) || CODE_EXT.test(landed))) {
+        return report(node, `imports the screen \`${landed}\`; a screen renders alone, so pass what it needs as props (or a \`background\` slot)`)
+      }
+      const unit = landed && unitOf(landed)
+      if (unit && units && !units.includes(unit.unit)) {
+        return report(node, `\`${unit.unit}\` is not in product.json \`units\`; add it there and run \`sando install\``)
+      }
+      const hit = denyImports.find((g) => matchesGlob(subject, g))
+      if (hit) report(node, `\`${subject}\` matches denyImports \`${hit}\`; a screen gets this through props`)
+    }
+    return {
+      ImportDeclaration: (n) => judge(n.source),
+      ExportNamedDeclaration: (n) => judge(n.source),
+      ExportAllDeclaration: (n) => judge(n.source),
+      ImportExpression: (n) => judge(n.source),
+    }
+  },
+}
+
+// ── screen stories: CSF3 data, nothing that runs ────────────────────────────────────────────
+// A screen story is the state's props and nothing else, so the harness can render every state
+// without Storybook: the meta holds `component`, `title`, `args`; each story holds `args`, `name`.
+// `render`, `decorators`, `loaders`, `beforeEach`, `play` and `parameters` are reported.
+const META_KEYS = new Set(['component', 'title', 'args'])
+const STORY_KEYS = new Set(['args', 'name'])
+const STORY_SOURCE = 'CSF3 screen stories: `component` and `args` only'
+
+const unwrap = (n) => {
+  while (n && ['TSAsExpression', 'TSSatisfiesExpression', 'TSTypeAssertion', 'TSNonNullExpression'].includes(n.type)) n = n.expression
+  return n
+}
+
+export const storyArgsOnly = {
+  meta: meta('S3', 'A screen story is data: the meta holds `component`/`title`/`args`, each story `args`/`name`.', STORY_SOURCE, []),
+  create(context) {
+    const report = (node, message) => context.report({ node, messageId: 'violation', data: { message, source: STORY_SOURCE } })
+    const consts = new Map()
+    const objectOf = (n) => {
+      n = unwrap(n)
+      if (n?.type === 'Identifier') n = unwrap(consts.get(n.name))
+      return n
+    }
+    const keys = (obj, allowed, what) => {
+      if (obj?.type !== 'ObjectExpression') return report(obj ?? context.sourceCode.ast, `${what} is not an object literal`)
+      for (const p of obj.properties) {
+        const k = p.type === 'Property' && !p.computed ? (p.key.name ?? p.key.value) : null
+        if (!k || !allowed.has(k)) report(p, `${what} holds \`${k ?? '…'}\`; a screen story carries only ${[...allowed].map((a) => `\`${a}\``).join(', ')}`)
+      }
+    }
+    return {
+      Program(program) {
+        for (const s of program.body) {
+          const d = s.type === 'ExportNamedDeclaration' ? s.declaration : s
+          if (d?.type === 'VariableDeclaration') for (const v of d.declarations) if (v.id.type === 'Identifier') consts.set(v.id.name, v.init)
+        }
+        for (const s of program.body) {
+          if (s.type === 'ExportDefaultDeclaration') keys(objectOf(s.declaration), META_KEYS, 'the story meta')
+          if (s.type === 'ExportNamedDeclaration' && s.declaration?.type === 'VariableDeclaration') {
+            for (const v of s.declaration.declarations) keys(objectOf(v.init), STORY_KEYS, `story \`${v.id.name}\``)
+          }
+          if (s.type === 'ExportNamedDeclaration' && s.declaration?.type === 'FunctionDeclaration') report(s, `story \`${s.declaration.id.name}\` is a function; write \`{ args }\``)
+        }
+      },
+    }
+  },
+}

package/lib/rules/units.mjs

@@ -0,0 +1,254 @@
+// U1, U3, U4, U5 and C2's inline half: how service TSX uses the installed Sando units.
+//
+// `policy` semantics (product.json, read by U4 and U5), stated once here and in surface.json:
+//   * A UNIT is a registry item name (`plan-card`). A JSX element belongs to unit X when its import
+//     lands on X's module file `src/{components,blocks,layouts}/<Pascal>.tsx`; every component that
+//     file exports counts as X (`Card` and `CardHeader` are both `card`).
+//   * `policy` absent, or a key of it absent: that rule has nothing to enforce and reports nothing.
+//   * `policy.screens` is OPTIONAL and partial. A screen with no entry has no type, so U5 sets no
+//     limit on it; a listed screen whose type has no `screenTypes` entry is reported.
+//   * `screenTypes.<t>.allowUnits`: absent, or containing "*", means every installed unit.
+//     Otherwise only the listed units. `denyUnits` always wins: a unit both allowed and denied is denied.
+//   * U5 also reads every src/screens/lib module a screen imports (and the lib modules those import):
+//     a unit such a module places in JSX counts as placed by the screen, reported on the import.
+//   * `props[].inside`: the element has a JSX ANCESTOR in the same file that belongs to that unit.
+//     An ancestor reached through another component file is not seen.
+//   * `props[].allow`: compared with a LITERAL attribute value (string, number, boolean; a bare
+//     attribute is `true`). An expression (`size={size}`) or an omitted prop is not judged.
+//
+// NOT seen: unit use through re-export barrels or aliases other than `@/` (resolve.mjs), and
+// className values built at runtime (only string literals and template-literal text are read).
+
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { basename, join } from 'node:path'
+import { loadTokenNames } from '../token-names.mjs'
+import { jsxRootName, repoPath, unitBindings, unitOf } from '../resolve.mjs'
+import { isColorProp, isSpaceProp, isWidthProp } from './css.mjs'
+
+const rule = (id, source, description, schema, create) => ({
+  meta: {
+    type: 'problem',
+    docs: { description, url: source, sandoId: id },
+    schema,
+    messages: { violation: '{{message}} ({{source}})' },
+  },
+  create(context) {
+    const report = (node, message) => context.report({ node, messageId: 'violation', data: { message, source } })
+    return create(context, report, context.options[0] ?? {})
+  },
+})
+
+const rootOf = (context, options) => options.root ?? context.cwd
+
+const lockCache = new Map()
+function lockFiles(path) {
+  if (!lockCache.has(path)) {
+    let files = null
+    try {
+      files = new Set(Object.keys(JSON.parse(readFileSync(path, 'utf8')).files ?? {}))
+    } catch {
+      files = null
+    }
+    lockCache.set(path, files)
+  }
+  return lockCache.get(path)
+}
+
+const ROOT_OPT = { root: { type: 'string' } }
+
+export const installedUnits = rule(
+  'U1',
+  'docs/sando/design-language.md § Building a screen',
+  'An import of `src/{components,blocks,layouts}/*` must land on a file `design/sando.lock.json` records as installed.',
+  [{ type: 'object', properties: { ...ROOT_OPT, lock: { type: 'string' } }, required: ['lock'], additionalProperties: false }],
+  (context, report, options) => {
+    const files = lockFiles(options.lock)
+    const root = rootOf(context, options)
+    return {
+      ImportDeclaration(node) {
+        const unit = unitOf(repoPath(node.source.value, context.filename, root))
+        if (!unit) return
+        if (!files) return report(node.source, `cannot read ${options.lock}; run \`sando install\``)
+        if (!files.has(unit.file)) report(node.source, `\`${unit.file}\` is not an installed Sando file; add \`${unit.unit}\` to \`units\` and run \`sando install\`, or build it in src/local/`)
+      },
+    }
+  },
+)
+
+const classTexts = (value) => {
+  if (!value) return []
+  if (value.type === 'Literal' && typeof value.value === 'string') return [[value, value.value]]
+  if (value.type === 'TemplateLiteral') return value.quasis.map((q) => [q, q.value.cooked ?? ''])
+  if (value.type === 'JSXExpressionContainer') return collectStrings(value.expression)
+  return []
+}
+// Every string literal inside a className expression: `cx('a', on && 'sd-x')`.
+function collectStrings(node, out = []) {
+  if (!node || typeof node !== 'object') return out
+  if (node.type === 'Literal' && typeof node.value === 'string') out.push([node, node.value])
+  else if (node.type === 'TemplateLiteral') for (const q of node.quasis) out.push([q, q.value.cooked ?? ''])
+  else for (const [k, v] of Object.entries(node)) if (k !== 'parent' && v && typeof v === 'object') (Array.isArray(v) ? v : [v]).forEach((c) => collectStrings(c, out))
+  return out
+}
+
+export const sharedClassOnly = rule(
+  'U3',
+  'docs/sando/shared-classes.md',
+  'A `sd-*` class in `className` must be one `shared-classes.md` makes public (read from token-names.json `classes`).',
+  [{ type: 'object', properties: { tokenNames: { type: 'string' } }, required: ['tokenNames'], additionalProperties: false }],
+  (context, report, options) => {
+    const classes = loadTokenNames(options.tokenNames)?.classes ?? null
+    return {
+      JSXAttribute(node) {
+        if (node.name.name !== 'className') return
+        for (const [at, text] of classTexts(node.value)) {
+          for (const cls of text.match(/(?<![\w-])sd-[a-z0-9_-]+/g) ?? []) {
+            if (!classes) report(at, `cannot read ${options.tokenNames}; reinstall the \`styles\` item`)
+            else if (!classes.has(cls)) report(at, `\`${cls}\` is not a public Sando class; style the unit through its props`)
+          }
+        }
+      },
+    }
+  },
+)
+
+const literalValue = (attr) => {
+  if (attr.value === null) return { ok: true, value: true }
+  if (attr.value.type === 'Literal') return { ok: true, value: attr.value.value }
+  const e = attr.value.type === 'JSXExpressionContainer' ? attr.value.expression : null
+  if (e?.type === 'Literal') return { ok: true, value: e.value }
+  return { ok: false }
+}
+
+export const policyProps = rule(
+  'U4',
+  'design/product.json § policy.props',
+  'A unit\'s prop takes only the values `policy.props` allows, optionally only inside another unit.',
+  [{ type: 'object', properties: { ...ROOT_OPT, props: { type: 'array' } }, additionalProperties: false }],
+  (context, report, options) => {
+    const entries = options.props ?? []
+    let units = new Map()
+    const unitOfElement = (el) => units.get(jsxRootName(el.openingElement.name))
+    return {
+      Program(node) {
+        units = unitBindings(node, context.filename, rootOf(context, options))
+      },
+      JSXOpeningElement(node) {
+        const unit = units.get(jsxRootName(node.name))
+        if (!unit) return
+        for (const entry of entries) {
+          if (entry.unit !== unit) continue
+          if (entry.inside) {
+            let inside = false
+            for (let p = node.parent.parent; p; p = p.parent) if (p.type === 'JSXElement' && unitOfElement(p) === entry.inside) inside = true
+            if (!inside) continue
+          }
+          const attr = node.attributes.find((a) => a.type === 'JSXAttribute' && a.name.name === entry.prop)
+          if (!attr) continue
+          const v = literalValue(attr)
+          if (v.ok && !entry.allow.includes(v.value)) {
+            report(attr, `\`${unit}\` ${entry.inside ? `inside \`${entry.inside}\` ` : ''}takes \`${entry.prop}\` ${entry.allow.map((a) => JSON.stringify(a)).join(' | ')}, not ${JSON.stringify(v.value)}${entry.because ? `: ${entry.because}` : ''}`)
+          }
+        }
+      },
+    }
+  },
+)
+
+// The units a src/screens/lib module places in JSX, and those of the lib modules it imports, read
+// with the parser this file is linted with. A unit the module places only on some props counts
+// (static reading): a frame that differs by screen type is split per type, or passed in as props.
+const LIB = /^src\/screens\/lib\//
+const EXTS = ['', '.tsx', '.ts', '.jsx', '.js', '/index.tsx', '/index.ts', '/index.jsx', '/index.js']
+const libCache = new Map()
+function libUnits(path, root, parser, parserOptions, seen = new Set()) {
+  const file = EXTS.map((e) => join(root, path + e)).find((f) => existsSync(f) && statSync(f).isFile())
+  if (!file || seen.has(file)) return new Set()
+  seen.add(file)
+  const stamp = `${file}\u0000${statSync(file).mtimeMs}`
+  if (libCache.has(stamp)) return libCache.get(stamp)
+  const out = new Set()
+  try {
+    const code = readFileSync(file, 'utf8')
+    const options = { ...parserOptions, ecmaVersion: 'latest', sourceType: 'module', filePath: file, range: true, loc: true }
+    const program = parser.parseForESLint ? parser.parseForESLint(code, options).ast : parser.parse(code, options)
+    const units = unitBindings(program, file, root)
+    const walk = (n) => {
+      if (!n || typeof n !== 'object') return
+      if (n.type === 'JSXOpeningElement' && units.has(jsxRootName(n.name))) out.add(units.get(jsxRootName(n.name)))
+      for (const [k, v] of Object.entries(n)) if (k !== 'parent' && v && typeof v === 'object') (Array.isArray(v) ? v : [v]).forEach(walk)
+    }
+    walk(program)
+    for (const node of program.body) {
+      const to = node.type === 'ImportDeclaration' ? repoPath(node.source.value, file, root) : null
+      if (to && LIB.test(to)) for (const u of libUnits(to, root, parser, parserOptions, seen)) out.add(u)
+    }
+  } catch {
+    // An unreadable or unparsable lib module is linted as its own file; nothing is inferred here.
+  }
+  libCache.set(stamp, out)
+  return out
+}
+
+export const policyUnits = rule(
+  'U5',
+  'design/product.json § policy.screens, policy.screenTypes',
+  'A screen places only the units its screen type allows (`denyUnits` wins over `allowUnits`), in its own JSX or through a src/screens/lib module it imports.',
+  [{ type: 'object', properties: { ...ROOT_OPT, screens: { type: 'object' }, screenTypes: { type: 'object' } }, additionalProperties: false }],
+  (context, report, options) => {
+    const name = basename(context.filename).replace(/\.[tj]sx?$/, '')
+    const type = options.screens?.[name]?.type
+    if (!type) return {}
+    const limits = options.screenTypes?.[type]
+    const root = rootOf(context, options)
+    let units = new Map()
+    const judge = (node, unit, via = '') => {
+      const allow = limits.allowUnits
+      if (limits.denyUnits?.includes(unit)) report(node, `a \`${type}\` screen does not place \`${unit}\`${via} (denyUnits)`)
+      else if (allow && !allow.includes('*') && !allow.includes(unit)) report(node, `a \`${type}\` screen places only ${allow.map((u) => `\`${u}\``).join(', ')}; not \`${unit}\`${via}`)
+    }
+    return {
+      Program(node) {
+        units = unitBindings(node, context.filename, root)
+        if (!limits) report(node, `screen \`${name}\` has type \`${type}\`, which \`policy.screenTypes\` does not define`)
+      },
+      ImportDeclaration(node) {
+        const to = limits && repoPath(node.source.value, context.filename, root)
+        if (!to || !LIB.test(to)) return
+        const { parser, parserOptions } = context.languageOptions
+        for (const unit of libUnits(to, root, parser, parserOptions)) judge(node, unit, ` through ${node.source.value}`)
+      },
+      JSXOpeningElement(node) {
+        const unit = units.get(jsxRootName(node.name))
+        if (unit && limits) judge(node, unit)
+      },
+    }
+  },
+)
+
+const REACT_UNITLESS = new Set(['flex', 'flexGrow', 'flexShrink', 'fontWeight', 'lineHeight', 'opacity', 'order', 'zIndex', 'zoom', 'scale'])
+const LENGTH = /(?<![\w.#-])-?(\d*\.?\d+)(px|rem|em)\b/
+const COLOR = /#[0-9a-fA-F]{3,8}\b|\b(rgba?|hsla?|oklch|oklab|lab|lch|hwb)\(/
+const toKebab = (k) => k.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)
+
+export const noInlineScaleLiteral = rule(
+  'C2',
+  'docs/sando/styling-contract.md § Never write a literal for a value a scale carries',
+  'C2 for an inline `style={{…}}` object literal: no non-zero length in gap/padding/margin or a border width, no colour literal.',
+  [],
+  (context, report) => ({
+    "JSXAttribute[name.name='style'] > JSXExpressionContainer > ObjectExpression > Property"(node) {
+      const key = node.key.type === 'Identifier' ? node.key.name : node.key.value
+      if (typeof key !== 'string' || key.startsWith('--')) return
+      const p = toKebab(key)
+      const v = node.value
+      let text = null
+      if (v.type === 'Literal' && typeof v.value === 'string') text = v.value.replace(/var\([^)]*\)/g, ' ')
+      else if (v.type === 'Literal' && typeof v.value === 'number') text = v.value === 0 || REACT_UNITLESS.has(key) ? null : `${v.value}px`
+      if (!text) return
+      const m = text.match(LENGTH)
+      if (m && Number(m[1]) !== 0 && (isSpaceProp(p) || isWidthProp(p))) report(node, `\`${p}: ${m[0]}\`; use a Sys token`)
+      if (COLOR.test(text) && isColorProp(p)) report(node, `colour literal in \`${p}\`; use a \`--sd-color-*\` role`)
+    },
+  }),
+)

package/lib/token-names.mjs

@@ -0,0 +1,58 @@
+// The token-classification core: which tier a `--sd-*` name is, decided by WHERE it is declared,
+// never by how it reads. `--sd-color-swatch-size-small` reads like a Sys colour and is a Cmp token
+// (docs/guide/styling-contract.md § Read Sys tokens, never Cmp or Ref).
+//
+//   Sys  = declared in a brand sheet (src/styles/themes/<brand>.css) and not `--sd-ref-*`
+//   Ref  = `--sd-ref-*`; its names differ per brand, so the prefix alone decides it
+//   Cmp  = declared in src/styles/tokens.css
+//
+// Only DECLARATIONS count (`--sd-x:`). tokens.css also READS Sys names inside Cmp values
+// (`var(--sd-duration-fast)`), so "appears in tokens.css" would misfile Sys as Cmp.
+
+import { readFileSync } from 'node:fs'
+
+const DECL = /(--sd-[a-z0-9-]+)\s*:/g
+const CLASS = /\.(sd-[a-z0-9_-]+)/g
+const stripComments = (css) => css.replace(/\/\*[\s\S]*?\*\//g, '')
+
+export const declaredNames = (css) => new Set([...stripComments(css).matchAll(DECL)].map((m) => m[1]))
+export const classNames = (css) => new Set([...stripComments(css).matchAll(CLASS)].map((m) => m[1]))
+
+/**
+ * Build the token-names document from the stylesheets `styles` and the brand items install.
+ * @param {{ tokensCss: string, themeCss: string[], resetCss?: string }} input
+ * @returns {{ sys: string[], cmp: string[], classes: string[] }}
+ */
+export function buildTokenNames({ tokensCss, themeCss, resetCss = '' }) {
+  const sys = new Set(themeCss.flatMap((css) => [...declaredNames(css)]).filter((n) => !n.startsWith('--sd-ref-')))
+  const cmp = declaredNames(tokensCss)
+  const both = [...cmp].filter((n) => sys.has(n))
+  if (both.length) throw new Error(`declared as both Sys and Cmp: ${both.join(', ')}`)
+  const classes = new Set([...classNames(tokensCss), ...classNames(resetCss)])
+  const sorted = (s) => [...s].sort()
+  return { sys: sorted(sys), cmp: sorted(cmp), classes: sorted(classes) }
+}
+
+/** @returns {'ref' | 'sys' | 'cmp' | 'unknown'} */
+export function classify(name, names) {
+  if (name.startsWith('--sd-ref-')) return 'ref'
+  if (names.sys.has(name)) return 'sys'
+  if (names.cmp.has(name)) return 'cmp'
+  return 'unknown'
+}
+
+const cache = new Map()
+/** Load a token-names.json as Sets, or `null` when it cannot be read. Cached per path. */
+export function loadTokenNames(path) {
+  if (!cache.has(path)) {
+    let value = null
+    try {
+      const raw = JSON.parse(readFileSync(path, 'utf8'))
+      value = { sys: new Set(raw.sys), cmp: new Set(raw.cmp), classes: new Set(raw.classes) }
+    } catch {
+      value = null
+    }
+    cache.set(path, value)
+  }
+  return cache.get(path)
+}

package/lib/typescript-api.mjs

@@ -0,0 +1,32 @@
+// Keep the TSX parser on a TypeScript that has a JS API, whatever TypeScript the service runs.
+//
+// TypeScript 7 ships no JS API (`require('typescript')` is `{ version, versionMajorMinor }`).
+// `@typescript-eslint/parser` accepts only TypeScript < 6.1, so npm nests a TypeScript 6 for it,
+// but `ts-api-utils` (which typescript-estree loads) accepts any TypeScript >= 4.8.4, so npm hoists
+// it to the service root, where `typescript` is the service's 7, and loading the parser throws
+// (`Cannot read properties of undefined (reading 'Intrinsic')`). No dependency range in this
+// package can stop that hoist (measured: a direct `ts-api-utils` dependency still lands at the
+// root, and npm drops `bundleDependencies` when it packs a workspace).
+//
+// So before the parser loads, when the TypeScript ts-api-utils would load has no JS API, its
+// module cache entry is pointed at the TypeScript typescript-estree itself resolves. This module
+// is imported first in configs.mjs; static imports evaluate in order.
+// ponytail: aliases a CJS require.cache entry for this process; swap for the parser's own fix
+// once typescript-eslint and ts-api-utils resolve TypeScript 7 themselves.
+
+import { createRequire } from 'node:module'
+
+const from = (path) => createRequire(path)
+
+try {
+  const estree = from(from(import.meta.url).resolve('@typescript-eslint/parser')).resolve('@typescript-eslint/typescript-estree')
+  const own = from(estree).resolve('typescript')
+  const seen = from(from(estree).resolve('ts-api-utils')).resolve('typescript')
+  const require = from(estree)
+  if (seen !== own && typeof require(seen).createSourceFile !== 'function') {
+    require(own)
+    require.cache[seen] = require.cache[own]
+  }
+} catch {
+  // Nothing resolvable to repair: the parser import below reports the real error.
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@sando-ui/eslint-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "ESLint rules a service repository runs over its own screens and CSS beside installed Sando units.",
+  "license": "MIT",
+  "homepage": "https://sando-ui.github.io",
+  "keywords": [
+    "sando-ui",
+    "eslint",
+    "eslintplugin",
+    "eslint-plugin",
+    "design-system",
+    "design-tokens",
+    "css"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./lib/index.mjs",
+    "./token-names": "./lib/token-names.mjs"
+  },
+  "files": [
+    "lib",
+    "surface.json"
+  ],
+  "engines": {
+    "node": ">=22.13"
+  },
+  "scripts": {
+    "test": "node --test",
+    "token-names:build": "node scripts/build-token-names.mjs",
+    "surface:build": "node scripts/build-surface.mjs",
+    "surface:check": "node scripts/build-surface.mjs --check"
+  },
+  "peerDependencies": {
+    "eslint": ">=9.24.0"
+  },
+  "dependencies": {
+    "@eslint/css": "^2.0.1",
+    "@typescript-eslint/parser": "^8.72.1"
+  },
+  "devDependencies": {
+    "eslint": "^9.39.5"
+  }
+}

package/surface.json

@@ -0,0 +1,55 @@
+{
+  "package": "@sando-ui/eslint-plugin",
+  "removalBreaks": {
+    "rules": [
+      "sando/installed-units",
+      "sando/no-inline-scale-literal",
+      "sando/no-reach",
+      "sando/no-scale-literal",
+      "sando/own-prefix",
+      "sando/policy-props",
+      "sando/policy-units",
+      "sando/screen-imports",
+      "sando/shared-class-only",
+      "sando/story-args-only",
+      "sando/theme-in-token",
+      "sando/token-tier",
+      "sando/type-whole"
+    ],
+    "ruleOptions": [
+      "sando/installed-units.lock",
+      "sando/installed-units.root",
+      "sando/own-prefix.prefix",
+      "sando/policy-props.props",
+      "sando/policy-props.root",
+      "sando/policy-units.root",
+      "sando/policy-units.screenTypes",
+      "sando/policy-units.screens",
+      "sando/screen-imports.denyImports",
+      "sando/screen-imports.root",
+      "sando/screen-imports.units",
+      "sando/shared-class-only.tokenNames",
+      "sando/token-tier.tokenNames"
+    ]
+  },
+  "additionBreaks": {
+    "errorRules": [
+      "no-restricted-globals",
+      "no-restricted-properties",
+      "no-restricted-syntax",
+      "sando/installed-units",
+      "sando/no-inline-scale-literal",
+      "sando/no-reach",
+      "sando/no-scale-literal",
+      "sando/own-prefix",
+      "sando/policy-props",
+      "sando/policy-units",
+      "sando/screen-imports",
+      "sando/shared-class-only",
+      "sando/story-args-only",
+      "sando/theme-in-token",
+      "sando/token-tier",
+      "sando/type-whole"
+    ]
+  }
+}