@assure-one/design-system 1.37.0 → 1.38.0

package/docs/for-ai-agents.md

@@ -55,6 +55,8 @@ If a UI element exists in the design system, use it. Do not write `<button>`, `<
 | `flex gap-*` wrappers                                 | `Stack`, `Inline`; `Surface` / `Card` for boxes                                                                                           |
 | `title="…"`, `window.confirm()`, `alert()`            | `Tooltip`, `ConfirmActionButton` / `AlertDialog`, `useToast`                                                                              |
 
+Two shareable lint configs report the first three rows for you: `@assure-one/design-system/eslint-config` and `@assure-one/design-system/stylelint-config` (warn-level, experimental — see the README section "Lint configs for consumers").
+
 Before writing any element, look it up in the ["Pick a component"](./components.md#pick-a-component) table. The only raw elements that are fine are structural ones the design system does not model (`<main>`, `<article>`, `<ul>` for plain lists, `<img>` for content images, `<form>` itself).
 
 ## 3. Forms: the `Field` recipe

package/eslint-config/index.mjs

@@ -0,0 +1,210 @@
+/**
+ * `@assure-one/design-system/eslint-config` (W7-18).
+ *
+ * The consumer-facing half of the in-repo ratchets: the four findings the
+ * design system ratchets on its own source (`scripts/ratchet/*` — raw platform
+ * controls, direct Radix imports, deep imports past the public entries,
+ * `--ds-*` redefinition outside a preset) reported in a product's own lint run.
+ *
+ * Every rule is **warn** by default, deliberately: a product adopts this on a
+ * codebase that already has hundreds of findings, records the count, and
+ * ratchets it down (W7-19). Raise the ones you have cleaned to "error" in your
+ * own config.
+ *
+ * Flat config only:
+ *
+ *   import ds from "@assure-one/design-system/eslint-config";
+ *   export default [...ds.configs.recommended];
+ *
+ * Or wire the plugin yourself: `plugins: { ds }` plus the rules you want.
+ */
+
+const ENTRY_SUBPATHS = new Set([
+  "tokens",
+  "icons",
+  "next",
+  "testing",
+  "styles.css",
+  "package.json",
+  "eslint-config",
+  "stylelint-config",
+]);
+
+/** The DS component(s) that own each raw element (scripts/ratchet/lib/raw-controls-owners.mjs). */
+const RAW_CONTROLS = {
+  button: "Button, IconButton, LinkButton, SubmitButton or Pressable",
+  input: "Input, NumberInput, SearchInput, Checkbox, RadioGroup, Switch, Slider, DatePicker…",
+  select: "Select, Combobox or MultiSelect",
+  textarea: "Textarea",
+};
+
+const DS_PROPERTY = /^--ds-/;
+const DEFAULT_PRESET_PATH = "(^|/)presets/";
+
+const isStringLiteral = (node) => node?.type === "Literal" && typeof node.value === "string";
+
+/** The `--ds-*` name a property key or JSX attribute declares, or undefined. */
+function dsPropertyName(key, computed) {
+  if (computed) return undefined;
+  const name = isStringLiteral(key) ? key.value : key?.type === "Identifier" ? key.name : undefined;
+  return name && DS_PROPERTY.test(name) ? name : undefined;
+}
+
+/** Import-like source string of a node, or undefined. */
+function importSource(node) {
+  if (node.type === "ImportDeclaration" || node.type === "ExportNamedDeclaration") {
+    return isStringLiteral(node.source) ? node.source.value : undefined;
+  }
+  if (node.type === "ExportAllDeclaration") {
+    return isStringLiteral(node.source) ? node.source.value : undefined;
+  }
+  return undefined;
+}
+
+const importVisitors = (check) => ({
+  ImportDeclaration: (node) => check(node, importSource(node)),
+  ExportNamedDeclaration: (node) => check(node, importSource(node)),
+  ExportAllDeclaration: (node) => check(node, importSource(node)),
+  ImportExpression: (node) =>
+    check(node, isStringLiteral(node.source) ? node.source.value : undefined),
+});
+
+/** @type {import("eslint").Rule.RuleModule} */
+const noRawControls = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Use the design system's control instead of a raw <button>, <input>, <select> or <textarea>.",
+    },
+    schema: [],
+    messages: {
+      raw: "<{{ element }}> is owned by the design system. Use {{ use }} (docs/components.md → “Never hand-roll”).",
+    },
+  },
+  create(context) {
+    return {
+      JSXOpeningElement(node) {
+        if (node.name?.type !== "JSXIdentifier") return;
+        const element = node.name.name;
+        const use = RAW_CONTROLS[element];
+        if (!use) return;
+        context.report({ node, messageId: "raw", data: { element, use } });
+      },
+    };
+  },
+};
+
+/** @type {import("eslint").Rule.RuleModule} */
+const noRadixImports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Import the design system's primitive instead of the Radix package it wraps.",
+    },
+    schema: [],
+    messages: {
+      radix:
+        '"{{ source }}" is wrapped by the design system. Import the primitive from "@assure-one/design-system" so behaviour, tokens and the Radix version stay in one place.',
+    },
+  },
+  create(context) {
+    return importVisitors((node, source) => {
+      if (!source?.startsWith("@radix-ui/")) return;
+      context.report({ node, messageId: "radix", data: { source } });
+    });
+  },
+};
+
+/** @type {import("eslint").Rule.RuleModule} */
+const noDeepImports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Import from a published design-system entry, never from dist/ or src/ (ADR-011).",
+    },
+    schema: [],
+    messages: {
+      deep: '"{{ source }}" is not a published entry. Import from "@assure-one/design-system" or one of {{ entries }} — anything else may change without a major release (ADR-011).',
+    },
+  },
+  create(context) {
+    const entries = [...ENTRY_SUBPATHS].map((s) => `/${s}`).join(", ");
+    return importVisitors((node, source) => {
+      if (!source?.startsWith("@assure-one/design-system/")) return;
+      const subpath = source.slice("@assure-one/design-system/".length);
+      if (ENTRY_SUBPATHS.has(subpath) || subpath.startsWith("css/")) return;
+      context.report({ node, messageId: "deep", data: { source, entries } });
+    });
+  },
+};
+
+/** @type {import("eslint").Rule.RuleModule} */
+const noDsTokenRedefinition = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Set a `--ds-*` custom property only in a theme preset, never inline in a component.",
+    },
+    schema: [
+      {
+        type: "object",
+        properties: { presetPath: { type: "string" } },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      redefined:
+        "{{ name }} is a design-system token. Override it in a theme preset (a file under presets/, or ThemeScope/BrandScope), not inline: an inline value escapes the theme and the token contract.",
+    },
+  },
+  create(context) {
+    const presetPath = new RegExp(context.options?.[0]?.presetPath ?? DEFAULT_PRESET_PATH);
+    const filename = (context.filename ?? context.getFilename?.() ?? "").replace(/\\/g, "/");
+    if (presetPath.test(filename)) return {};
+    const report = (node, name) => context.report({ node, messageId: "redefined", data: { name } });
+    return {
+      Property(node) {
+        const name = dsPropertyName(node.key, node.computed);
+        if (name) report(node, name);
+      },
+      JSXAttribute(node) {
+        if (node.name?.type !== "JSXNamespacedName") return;
+        const name = `${node.name.namespace?.name}:${node.name.name?.name}`;
+        if (DS_PROPERTY.test(name)) report(node, name);
+      },
+    };
+  },
+};
+
+/** The `ds` plugin: the rules alone, for a config that wires them itself. */
+export const plugin = {
+  meta: { name: "@assure-one/design-system/eslint-config" },
+  rules: {
+    "no-raw-controls": noRawControls,
+    "no-radix-imports": noRadixImports,
+    "no-deep-imports": noDeepImports,
+    "no-ds-token-redefinition": noDsTokenRedefinition,
+  },
+};
+
+/** Warn-level rule table (W7-18): every rule this config ships. */
+export const rules = Object.fromEntries(
+  Object.keys(plugin.rules).map((name) => [`ds/${name}`, "warn"]),
+);
+
+/** Flat config: `export default [...ds.configs.recommended]`. */
+export const configs = {
+  recommended: [
+    {
+      name: "@assure-one/design-system/recommended",
+      files: ["**/*.{js,jsx,mjs,cjs,ts,tsx,mts,cts}"],
+      plugins: { ds: plugin },
+      rules,
+    },
+  ],
+};
+
+export default { plugin, rules, configs };

package/eslint-config/stylelint-rules.mjs

@@ -0,0 +1,54 @@
+/**
+ * The two stylelint checks of W7-18, as plain PostCSS finders.
+ *
+ * Kept free of any `stylelint` import so they can be exercised directly (and
+ * reused by the repo's own CSS tooling): `stylelint.mjs` wraps them into the
+ * published plugin. They mirror the `css-hygiene` ratchet family's concerns
+ * (`scripts/ratchet/lib/css-hygiene-analyse.mjs`) from the consumer side.
+ */
+
+/** A declaration whose property is a design-system token. */
+const DS_PROPERTY = /^--ds-/;
+
+/**
+ * Selectors that reach design-system DOM: a `ds:`-prefixed utility class
+ * (written `.ds\:flex` in CSS), the `ds-` component classes, and the
+ * `data-slot` / `data-ds-*` attributes components expose (ADR-008).
+ */
+const DS_SELECTOR = /\.ds\\?:|\.ds-|\[data-slot|\[data-ds-/;
+
+/** The nearest enclosing rule's selector, or undefined at the top level. */
+function enclosingSelector(node) {
+  for (let parent = node.parent; parent; parent = parent.parent) {
+    if (parent.type === "rule") return parent.selector;
+  }
+  return undefined;
+}
+
+/** Every `--ds-*` declaration in a stylesheet: `[{ prop, decl }]`. */
+export function dsTokenDeclarations(root) {
+  const found = [];
+  root.walkDecls((decl) => {
+    if (DS_PROPERTY.test(decl.prop)) found.push({ prop: decl.prop, decl });
+  });
+  return found;
+}
+
+/** Every `!important` declaration under a design-system selector: `[{ prop, selector, decl }]`. */
+export function importantOnDsSelectors(root) {
+  const found = [];
+  root.walkDecls((decl) => {
+    if (!decl.important) return;
+    const selector = enclosingSelector(decl);
+    if (!selector || !DS_SELECTOR.test(selector)) return;
+    found.push({ prop: decl.prop, selector, decl });
+  });
+  return found;
+}
+
+export const messages = {
+  dsToken: (prop) =>
+    `${prop} is a design-system token. Set it in a theme preset (the block \`pnpm derive-consumer-preset\` writes, or ThemeScope/BrandScope), not in app CSS — an override here escapes the theme and the token contract.`,
+  important: (prop, selector) =>
+    `Avoid \`!important\` on a design-system selector (\`${selector}\` → ${prop}). Pass \`className\`/\`classNames\` instead: consumer classes already win by cascade (ADR-004).`,
+};

package/eslint-config/stylelint.mjs

@@ -0,0 +1,73 @@
+/**
+ * `@assure-one/design-system/stylelint-config` (W7-18).
+ *
+ * The CSS half of the consumer lint surface: the two things a product's own
+ * stylesheet does to the design system that the `css-hygiene` ratchet catches
+ * inside this repository — redefining a `--ds-*` token outside a theme preset,
+ * and `!important` on a design-system selector.
+ *
+ * Both are **warnings** (the `severity: "warning"` below), for the same reason
+ * the ESLint rules are: a product adopts this on CSS that already has
+ * findings, records the count, and ratchets it down (W7-19).
+ *
+ *   // stylelint.config.mjs
+ *   import ds from "@assure-one/design-system/stylelint-config";
+ *   export default { extends: [], ...ds };
+ *
+ * `stylelint` itself is the consumer's (an optional peer dependency here).
+ * Preset files are exempt: override `ignoreFiles`/`overrides` to move them.
+ */
+import stylelint from "stylelint";
+
+import { dsTokenDeclarations, importantOnDsSelectors, messages } from "./stylelint-rules.mjs";
+
+const NAMESPACE = "assure-ds";
+
+const plugin = (ruleName, find, message) =>
+  stylelint.createPlugin(`${NAMESPACE}/${ruleName}`, (primary, secondary, context) => {
+    const name = `${NAMESPACE}/${ruleName}`;
+    return (root, result) => {
+      if (!primary) return;
+      for (const found of find(root)) {
+        stylelint.utils.report({
+          result,
+          ruleName: name,
+          node: found.decl,
+          word: found.prop,
+          message: message(found),
+          severity: secondary?.severity ?? context?.severity ?? "warning",
+        });
+      }
+    };
+  });
+
+/** The two plugin rules, for a config that wires them itself. */
+export const plugins = [
+  plugin("no-ds-token-redefinition", dsTokenDeclarations, ({ prop }) => messages.dsToken(prop)),
+  plugin("no-important-on-ds-selectors", importantOnDsSelectors, ({ prop, selector }) =>
+    messages.important(prop, selector),
+  ),
+];
+
+/** Warn-level rule table (W7-18). */
+export const rules = {
+  [`${NAMESPACE}/no-ds-token-redefinition`]: [true, { severity: "warning" }],
+  [`${NAMESPACE}/no-important-on-ds-selectors`]: [true, { severity: "warning" }],
+};
+
+/**
+ * The shareable config. Theme presets are where `--ds-*` belongs, so any file
+ * under a `presets/` directory (or named `*.preset.css`) is exempt.
+ */
+export const config = {
+  plugins,
+  rules,
+  overrides: [
+    {
+      files: ["**/presets/**/*.css", "**/*.preset.css"],
+      rules: { [`${NAMESPACE}/no-ds-token-redefinition`]: null },
+    },
+  ],
+};
+
+export default config;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assure-one/design-system",
-  "version": "1.37.0",
+  "version": "1.38.0",
   "description": "Assure One design system — tokens, primitives, and patterns for the Assure Suite.",
   "license": "UNLICENSED",
   "private": false,
@@ -45,12 +45,15 @@
         "default": "./dist/testing/index.cjs"
       }
     },
+    "./eslint-config": "./eslint-config/index.mjs",
+    "./stylelint-config": "./eslint-config/stylelint.mjs",
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
     "codemods",
     "!codemods/__test__",
+    "eslint-config",
     "docs/components.md",
     "docs/components.registry.json",
     "docs/for-ai-agents.md",
@@ -65,12 +68,16 @@
   },
   "peerDependencies": {
     "next": ">=15",
+    "stylelint": ">=16",
     "react": ">=19",
     "react-dom": ">=19"
   },
   "peerDependenciesMeta": {
     "next": {
       "optional": true
+    },
+    "stylelint": {
+      "optional": true
     }
   },
   "dependencies": {