@assure-one/design-system 1.36.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.36.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": {

package/dist/design-system-provider-cPUklDJv.d.ts

@@ -1,220 +0,0 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ComponentType, AnchorHTMLAttributes, Ref, ReactNode, ImgHTMLAttributes } from 'react';
-
-/**
- * L0 foundation (W5-20, ADR-010). The typed messages catalogue every
- * design-system component reads its generic strings from (target architecture
- * §38): accessibility and micro-copy with a universal meaning — Clear, No
- * results, Loading, optional — never product copy, which is always the
- * consumer's (`children`, `label`, `placeholder`).
- *
- * The catalogue is keyed by component namespace; each namespace is the
- * `*Messages` interface that component already accepted through its
- * `messages` prop before the provider existed, so the resolution order is one
- * rule everywhere: **prop > provider > English default**. A value is a string
- * or, where a parameter is involved, a function of that parameter (no string
- * concatenation or pluralisation inside components).
- *
- * The English defaults live in `./en.ts`; `./en.json` is generated from it
- * (`pnpm messages:generate`) so translators start from the full list.
- */
-/** The copy a `Select` renders. @experimental */
-interface SelectMessages {
-    /** The accessible name of the `clearable` button. Default `"Clear selection"`. */
-    clear: string;
-}
-/** The copy a `SearchInput` renders. @experimental */
-interface SearchInputMessages {
-    /** The accessible name of the clear button. Default `"Clear search"`. */
-    clear: string;
-}
-/** The copy a `Combobox` (and `MultiSelect`) renders. @experimental */
-interface ComboboxMessages {
-    /** The empty state when the query matches nothing. */
-    empty: string;
-    /** The loading state while `loading`. */
-    loading: string;
-    /** The label of the create row for a query. */
-    create: (query: string) => string;
-    /** The accessible name of the clear button. */
-    clear: string;
-    /** The accessible name of the toggle button. */
-    toggle: string;
-    /** The accessible name of a chip's remove button (`multiple`). */
-    remove: (label: string) => string;
-}
-/**
- * The copy a `Field` renders (target architecture §24.5).
- *
- * @experimental
- */
-interface FieldMessages {
-    /** The indicator after the label of an optional field. Default `"optional"`, rendered in parentheses. */
-    optional: string;
-}
-/** The default dropzone copy a `FileUpload` renders when it has no `children`. @experimental */
-interface FileUploadMessages {
-    /** The emphasised call to action. Default `"Click to upload"`. */
-    prompt: string;
-    /** The rest of the sentence after the prompt. Default `" or drag and drop"`. */
-    dragHint: string;
-    /** The accepted-types line; receives the `accept` list. */
-    accepted: (accept: string) => string;
-    /** The size-limit line; receives the formatted limit (e.g. `"10 MB"`). */
-    maxSize: (size: string) => string;
-}
-/**
- * The whole catalogue, one namespace per component. This is the type a
- * consumer's i18n lint can check for completeness.
- *
- * @experimental
- */
-interface DsMessages {
-    select: SelectMessages;
-    searchInput: SearchInputMessages;
-    combobox: ComboboxMessages;
-    field: FieldMessages;
-    fileUpload: FileUploadMessages;
-}
-/** A component namespace of the catalogue. @experimental */
-type DsMessageNamespace = keyof DsMessages;
-/**
- * What `DesignSystemProvider messages` accepts: any subset of namespaces, each
- * any subset of its keys. Every omitted key keeps its English default.
- *
- * @experimental
- */
-type DsMessagesOverride = {
-    [N in DsMessageNamespace]?: Partial<DsMessages[N]>;
-};
-
-/**
- * L0 foundation (W5-21, ADR-010). The adapters through which the design
- * system renders an application's router link and image component without
- * importing them itself.
- *
- * `LinkButton` and `Logo` read these from `DesignSystemProvider`. Without a
- * provider they keep their static `next/link` / `next/image` imports (C-NEXT-PEER)
- * until 2.0, so nothing changes for a Next.js app that renders no provider;
- * `@assure-one/design-system/next` exports a provider that passes exactly
- * those two, and a non-Next app passes its own.
- */
-/** The props a link adapter receives: a plain anchor with an `href`. @experimental */
-interface LinkComponentProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
-    href: string;
-    ref?: Ref<HTMLAnchorElement>;
-    children?: ReactNode;
-}
-/**
- * A component that renders a link — `next/link`, React Router's `Link`, or a
- * plain `<a>`. It must forward every anchor attribute and the ref.
- *
- * @experimental
- */
-type LinkComponent = ComponentType<LinkComponentProps>;
-/** The props an image adapter receives: `src`, `alt` and the intrinsic size. @experimental */
-interface ImageComponentProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "width" | "height"> {
-    src: string;
-    alt: string;
-    width: number;
-    height: number;
-    /** Load eagerly, above the fold (`next/image` `priority`). */
-    priority?: boolean;
-}
-/**
- * A component that renders an image — `next/image` or a plain `<img>`.
- *
- * @experimental
- */
-type ImageComponent = ComponentType<ImageComponentProps>;
-
-/** Text direction the provider announces. Context only until components adopt logical properties (W5-22). @experimental */
-type DsDirection = "ltr" | "rtl";
-/**
- * The resolved messages of one component namespace: the component's own
- * `messages` prop wins over the provider's catalogue, which wins over the
- * English default. Works without a provider (English). Stable while the three
- * inputs are.
- *
- * @experimental
- */
-declare function useDsMessages<N extends DsMessageNamespace>(namespace: N, override?: Partial<DsMessages[N]> | undefined): DsMessages[N];
-
-/**
- * Props of `DesignSystemProvider` (W5-20, ADR-010, target architecture §43).
- *
- * @experimental
- */
-interface DesignSystemProviderProps {
-    /**
-     * Overrides for the generic strings components render (Clear, No results,
-     * optional…), by component namespace. Any subset; omitted keys keep their
-     * English default. A component's own `messages` prop still wins. The full
-     * list is `DsMessages` (and `messages/en.json` in the package source).
-     */
-    messages?: DsMessagesOverride;
-    /**
-     * The BCP 47 tag locale-aware components format with (dates, numbers).
-     * Default `"en-US"` on the server and on the client (amendment A3): pass the
-     * locale your app already knows server-side; never `navigator.language`
-     * during render.
-     */
-    locale?: string;
-    /** Text direction. Context only for now — components adopt logical properties in W5-22. */
-    dir?: DsDirection;
-    /**
-     * Where portalled content (dialogs, menus, tooltips) mounts. `undefined`
-     * (default) keeps Radix's `document.body`. Read by the shared Portal of the
-     * overlay primitives as they adopt it.
-     */
-    portalContainer?: HTMLElement | null;
-    /**
-     * The application's router link, rendered by `LinkButton` and `Logo`
-     * instead of their static `next/link` import (W5-21). A Next.js app uses
-     * `NextDesignSystemProvider` from `@assure-one/design-system/next`.
-     */
-    linkComponent?: LinkComponent;
-    /** The application's image component, rendered by `Logo` instead of its static `next/image` import. */
-    imageComponent?: ImageComponent;
-    /**
-     * Shared tooltip defaults (`delayDuration`, `skipDelayDuration`,
-     * `disableHoverableContent`) for tooltips built directly on the Radix
-     * root. `false` mounts no `TooltipProvider`. The design system's own
-     * `Tooltip` still wraps its own provider today, so it is unaffected.
-     */
-    tooltip?: TooltipDefaults | false;
-    /**
-     * Mount the toast region (`ToastProvider`) so `useToast()` works anywhere
-     * below. Off by default: an app that already renders `ToastProvider` keeps
-     * its single region (the `aria-label="Notifications"` region consumers
-     * select on, C-TOAST-ARIALABEL, must exist exactly once).
-     */
-    toasts?: boolean;
-    children?: ReactNode;
-}
-/** The Radix `TooltipProvider` props the provider forwards. @experimental */
-interface TooltipDefaults {
-    delayDuration?: number;
-    skipDelayDuration?: number;
-    disableHoverableContent?: boolean;
-}
-/**
- * The optional application-level provider of the design system (W5-20,
- * ADR-010). Thin by design: it owns only what CSS cannot — the messages
- * catalogue, the locale, the text direction, the portal container, the link
- * and image adapters, shared tooltip defaults and (opt-in) the toast region.
- * Colour scheme, brand and density stay attributes + CSS on `<html>`.
- *
- * Everything works identically without it: every component falls back to
- * the English catalogue, `"en-US"`, `document.body` and its static `next/*`
- * import. The provider renders **no DOM wrapper** (only the toast region when
- * `toasts` is set), so it cannot cause a hydration mismatch.
- *
- * Reserved: the `useConfirm` / `usePrompt` host (W5-18) mounts here once it
- * exists — see the comment in the render tree.
- *
- * @experimental
- */
-declare function DesignSystemProvider({ messages, locale, dir, portalContainer, linkComponent, imageComponent, tooltip, toasts, children, }: DesignSystemProviderProps): react_jsx_runtime.JSX.Element;
-
-export { type ComboboxMessages as C, type DesignSystemProviderProps as D, type FileUploadMessages as F, type ImageComponent as I, type LinkComponent as L, type SearchInputMessages as S, type TooltipDefaults as T, type SelectMessages as a, type FieldMessages as b, DesignSystemProvider as c, type DsDirection as d, type DsMessageNamespace as e, type DsMessages as f, type DsMessagesOverride as g, type ImageComponentProps as h, type LinkComponentProps as i, useDsMessages as u };