@instruments/materia-ui 0.1.0

package/dist/utils/keyboard.js

@@ -0,0 +1,97 @@
+/**
+ * Keyboard shortcut parsing utilities.
+ *
+ * Converts shortcut strings like "cmd+k" or "ctrl+shift+p" into display-ready
+ * arrays with proper symbols. Inlined into @instruments/materia-ui (was @materia/utils) so
+ * the package is self-contained - only `parseShortcut` is consumed here.
+ */
+/** Map of modifier aliases to their display symbols. */
+const MODIFIER_MAP = new Map(Object.entries({
+    // Command/Meta
+    cmd: "⌘",
+    command: "⌘",
+    meta: "⌘",
+    "⌘": "⌘",
+    // Control
+    ctrl: "Ctrl",
+    control: "Ctrl",
+    "⌃": "Ctrl",
+    // Shift
+    shift: "⇧",
+    "⇧": "⇧",
+    // Alt/Option
+    alt: "⌥",
+    opt: "⌥",
+    option: "⌥",
+    "⌥": "⌥",
+}));
+/** Map of special key names to their display form. */
+const KEY_MAP = new Map(Object.entries({
+    // Arrow keys
+    up: "↑",
+    down: "↓",
+    left: "←",
+    right: "→",
+    arrowup: "↑",
+    arrowdown: "↓",
+    arrowleft: "←",
+    arrowright: "→",
+    // Action keys
+    enter: "↵",
+    return: "↵",
+    tab: "⇥",
+    esc: "Esc",
+    escape: "Esc",
+    space: "Space",
+    backspace: "⌫",
+    delete: "⌦",
+    del: "⌦",
+    // Navigation
+    home: "Home",
+    end: "End",
+    pageup: "PgUp",
+    pagedown: "PgDn",
+}));
+const SHORTCUT_SPLIT_REGEX = /\+(?![+]$)/u;
+const FUNCTION_KEY_REGEX = /^f\d{1,2}$/iu;
+/** Display symbol for a single shortcut token. */
+const renderShortcutKey = (part) => {
+    const lower = part.toLowerCase();
+    const modifier = MODIFIER_MAP.get(lower);
+    if (modifier !== undefined) {
+        return modifier;
+    }
+    const special = KEY_MAP.get(lower);
+    if (special !== undefined) {
+        return special;
+    }
+    if (part.length === 1) {
+        return part.toUpperCase();
+    }
+    if (FUNCTION_KEY_REGEX.test(part)) {
+        return part.toUpperCase();
+    }
+    return part;
+};
+/**
+ * Parses a keyboard shortcut string into an array of display-ready key symbols.
+ *
+ * @example
+ * ```ts
+ * parseShortcut("cmd+k") // ["⌘", "K"]
+ * parseShortcut("ctrl+shift+p") // ["Ctrl", "⇧", "P"]
+ * ```
+ */
+export const parseShortcut = (shortcut) => {
+    if (!shortcut) {
+        return [];
+    }
+    const keys = [];
+    for (const raw of shortcut.split(SHORTCUT_SPLIT_REGEX)) {
+        const part = raw.trim();
+        if (part) {
+            keys.push(renderShortcutKey(part));
+        }
+    }
+    return keys;
+};

package/dist/utils/motion-style.d.ts

@@ -0,0 +1,15 @@
+import type { MotionStyle } from "motion/react";
+/** `MotionStyle` with `undefined` allowed on optional keys, as spreads produce. */
+type LooseMotionStyle = {
+    [Key in keyof MotionStyle]?: MotionStyle[Key] | undefined;
+};
+/**
+ * Bridge a plain (or MotionValue-bearing) style object to motion's
+ * `MotionStyle`. `motion.*` components accept `MotionValue`s alongside regular
+ * CSS, but under `exactOptionalPropertyTypes` a spread `CSSProperties` widens
+ * optional keys with `undefined`, which `MotionStyle` structurally rejects.
+ * This is the one place that gap is crossed: the entries are copied
+ * across, so motion receives the same CSS surface at runtime.
+ */
+export declare const asMotionStyle: (style: LooseMotionStyle | undefined) => MotionStyle;
+export {};

package/dist/utils/motion-style.js

@@ -0,0 +1,13 @@
+/**
+ * Bridge a plain (or MotionValue-bearing) style object to motion's
+ * `MotionStyle`. `motion.*` components accept `MotionValue`s alongside regular
+ * CSS, but under `exactOptionalPropertyTypes` a spread `CSSProperties` widens
+ * optional keys with `undefined`, which `MotionStyle` structurally rejects.
+ * This is the one place that gap is crossed: the entries are copied
+ * across, so motion receives the same CSS surface at runtime.
+ */
+export const asMotionStyle = (style) => {
+    const motionStyle = {};
+    Object.assign(motionStyle, style);
+    return motionStyle;
+};

package/dist/utils/random-color.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Returns a random colour from the deterministic palette.
+ *
+ * Uses `Math.random`, which is runtime-nondeterministic - kept out of
+ * `tokens/color.ts` so the tokens module stays pure and dependency-free.
+ */
+export declare const getRandomColor: () => string;

package/dist/utils/random-color.js

@@ -0,0 +1,13 @@
+import { DETERMINISTIC_COLORS } from "@instruments/materia-ui/tokens/color";
+// Neutral grey fallback, mirrors tokens/color.ts DEFAULT_COLOR.
+const DEFAULT_COLOR = "#6B7280";
+/**
+ * Returns a random colour from the deterministic palette.
+ *
+ * Uses `Math.random`, which is runtime-nondeterministic - kept out of
+ * `tokens/color.ts` so the tokens module stays pure and dependency-free.
+ */
+export const getRandomColor = () => {
+    const randomIndex = Math.floor(Math.random() * DETERMINISTIC_COLORS.length);
+    return DETERMINISTIC_COLORS[randomIndex] ?? DEFAULT_COLOR;
+};

package/dist/utils/resolve-state-update.d.ts

@@ -0,0 +1,7 @@
+/** A state update: the next value, or a function of the previous one. */
+export type StateUpdate<T> = T | ((previous: T) => T);
+/**
+ * Resolve a `setState`-style update against the previous value. `T` must not
+ * itself be a function type.
+ */
+export declare const resolveStateUpdate: <T>(update: StateUpdate<T>, previous: T) => T;

package/dist/utils/resolve-state-update.js

@@ -0,0 +1,6 @@
+const isUpdater = (update) => typeof update === "function";
+/**
+ * Resolve a `setState`-style update against the previous value. `T` must not
+ * itself be a function type.
+ */
+export const resolveStateUpdate = (update, previous) => (isUpdater(update) ? update(previous) : update);

package/dist/utils/type-guards.d.ts

@@ -0,0 +1,8 @@
+/** Narrow a union to its `number` member. */
+export declare const isNumber: (value: unknown) => value is number;
+/** Narrow a union to its `string` member. */
+export declare const isString: (value: unknown) => value is string;
+/** A non-empty string: rules out `undefined`, `null` and `""`. */
+export declare const hasText: (value: string | null | undefined) => value is string;
+/** A present value: rules out `undefined` and `null`, but keeps `""`, `0` and `false`. */
+export declare const isPresent: <T>(value: T | null | undefined) => value is T;

package/dist/utils/type-guards.js

@@ -0,0 +1,8 @@
+/** Narrow a union to its `number` member. */
+export const isNumber = (value) => typeof value === "number";
+/** Narrow a union to its `string` member. */
+export const isString = (value) => typeof value === "string";
+/** A non-empty string: rules out `undefined`, `null` and `""`. */
+export const hasText = (value) => value !== undefined && value !== null && value !== "";
+/** A present value: rules out `undefined` and `null`, but keeps `""`, `0` and `false`. */
+export const isPresent = (value) => value !== undefined && value !== null;

package/dist/utils/typed-entries.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `Object.entries` that preserves the key type. The standard lib signature
+ * widens keys to `string`; for a `Record<K, V>` the keys are `K` by
+ * construction, so the narrowing guard below holds for every own key.
+ */
+export declare const typedEntries: <K extends PropertyKey, V>(obj: Partial<Record<K, V>>) => [K, V][];
+/**
+ * `Object.keys` that preserves the key type, for the same reason as
+ * {@link typedEntries}.
+ */
+export declare const typedKeys: <K extends PropertyKey, V = NonNullable<unknown>>(obj: Partial<Record<K, V>>) => K[];

package/dist/utils/typed-entries.js

@@ -0,0 +1,11 @@
+/**
+ * `Object.entries` that preserves the key type. The standard lib signature
+ * widens keys to `string`; for a `Record<K, V>` the keys are `K` by
+ * construction, so the narrowing guard below holds for every own key.
+ */
+export const typedEntries = (obj) => Object.entries(obj).filter((entry) => entry[0] in obj);
+/**
+ * `Object.keys` that preserves the key type, for the same reason as
+ * {@link typedEntries}.
+ */
+export const typedKeys = (obj) => Object.keys(obj).filter((key) => key in obj);

package/dist/utils/warn-missing-aria-label.d.ts

@@ -0,0 +1,16 @@
+import type { LucideIcon } from "lucide-react";
+import type { ComponentType, ReactNode, SVGProps } from "react";
+/**
+ * Dev-only guard: warn when an icon-only control has no accessible name.
+ *
+ * An item that renders an icon with no visible text and no `aria-label` /
+ * `aria-labelledby` is announced as an unlabelled control by screen readers.
+ * This fires a console warning in local-dev browser sessions only (never in
+ * production), naming the icon so the offending item is easy to find.
+ *
+ * @param icon - The item's leading icon, or `undefined` when text-only.
+ * @param children - The item's children; an icon-only item has none.
+ * @param ariaLabel - The item's `aria-label`, if any.
+ * @param ariaLabelledby - The item's `aria-labelledby`, if any.
+ */
+export declare const warnMissingAriaLabel: (icon: LucideIcon | ComponentType<SVGProps<SVGSVGElement>> | undefined, children: ReactNode, ariaLabel: string | undefined, ariaLabelledby: string | undefined) => void;

package/dist/utils/warn-missing-aria-label.js

@@ -0,0 +1,26 @@
+import { isDevelopmentBrowser } from "./is-development-browser.js";
+import { hasText } from "./type-guards.js";
+/**
+ * Dev-only guard: warn when an icon-only control has no accessible name.
+ *
+ * An item that renders an icon with no visible text and no `aria-label` /
+ * `aria-labelledby` is announced as an unlabelled control by screen readers.
+ * This fires a console warning in local-dev browser sessions only (never in
+ * production), naming the icon so the offending item is easy to find.
+ *
+ * @param icon - The item's leading icon, or `undefined` when text-only.
+ * @param children - The item's children; an icon-only item has none.
+ * @param ariaLabel - The item's `aria-label`, if any.
+ * @param ariaLabelledby - The item's `aria-labelledby`, if any.
+ */
+export const warnMissingAriaLabel = (icon, children, ariaLabel, ariaLabelledby) => {
+    if (isDevelopmentBrowser() &&
+        icon !== undefined &&
+        (children === undefined || children === null) &&
+        !hasText(ariaLabel) &&
+        !hasText(ariaLabelledby)) {
+        console.warn("Icon-only item is missing `aria-label` or `aria-labelledby`. " +
+            "Screen readers will announce this as an unlabelled control. " +
+            `Icon: ${icon.displayName ?? icon.name ?? "unknown"}`);
+    }
+};

package/dist/utils/with-test-id.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Utility type that adds a `testId` prop to component props for Playwright
+ * testing. Components extract `testId` and render it as `data-testid={testId}`.
+ *
+ * Inlined into @instruments/materia-ui (was @materia/utils) so the package is self-contained.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent({ testId, ...props }: WithTestId<React.ComponentProps<"div">>) {
+ *   return <div data-testid={testId} {...props} />;
+ * }
+ * ```
+ */
+export type WithTestId<T> = T & {
+    testId?: string;
+};

package/dist/utils/with-test-id.js

@@ -0,0 +1 @@
+export {};

package/lint/README.md

@@ -0,0 +1,116 @@
+# `@instruments/materia-ui/lint` - consumer lint preset
+
+Guardrails that keep app code inside the design system. The four rules below are split across the two enforcement mechanisms the repo's lint stack supports; the type case and the colour tokens, further down, configure `@howells/lint` rules for an app:
+
+| Rule | Mechanism | Forbids |
+| --- | --- | --- |
+| **base-ui** | Oxlint `no-restricted-imports`, via `lint/no-raw-base-ui.mjs` | `import … from "@base-ui/react"` / `"@base-ui/react/*"`, and any `"@radix-ui/*"` / `"radix-ui"` |
+| **lucide** | Oxlint `no-restricted-imports`, via `lint/no-raw-lucide.mjs` | `import … from "lucide-react"` (use the `Icon` component) |
+| **hex** | `scan-classes.mjs` class scanner | raw `#rgb`/`#rrggbb`/`oklch()`/`oklab()` inside class strings |
+| **arbitrary** | `scan-classes.mjs` class scanner | arbitrary Tailwind values (`mt-[13px]`, `bg-[#fff]`, `w-[…]`) |
+
+The import restrictions are Oxlint config fragments because every unit in this repo lints with `@howells/lint` (oxlint). The hex and arbitrary-value rules scan class strings, which no import-level linter can see, so they run as a small Node script.
+
+The two fragments live at the repo root rather than in this package: they are repo-local policy, extended by each unit's own `oxlint.config.ts`, and each carries the `@doctrine` sentence and the published ban message that `lint/doctrine-rules.mjs` and `scripts/generate-docs-manifest.mjs` hydrate the doctrine page from.
+
+## Rollout - enable per rule, not all-or-nothing
+
+The **base-ui** and **hex** rules are enforced now. The **lucide** and **arbitrary** rules are opt-in - they gate on large migrations (lucide → `Icon`, and tokenising ~400 arbitrary values), so each door locks behind its own migration instead of blocking on all of them at once. `apps/web` is the one unit past the lucide migration and the one that extends that fragment.
+
+## Enabling the import rules (Oxlint)
+
+`lint/materia-policy.mjs` carries the **base-ui** ban alongside the flat-shim boundary, and every unit extends it:
+
+```ts
+import next from "@howells/lint/oxlint/next";
+
+import materiaPolicy from "../../lint/materia-policy.mjs";
+
+export default {
+  extends: [next, materiaPolicy],
+};
+```
+
+Add `lint/no-raw-lucide.mjs` once the unit's lucide → `Icon` migration is complete:
+
+```ts
+import noRawLucide from "../../lint/no-raw-lucide.mjs";
+
+export default {
+  extends: [next, materiaPolicy, noRawLucide],
+};
+```
+
+Oxlint replaces a rule's options rather than merging them, so the lucide fragment restates the base-ui pattern and has to come last.
+
+`packages/ui` extends neither fragment: it is where Base UI primitives and Lucide glyphs are legitimately wrapped.
+
+## Enabling the type case (Oxlint)
+
+Text takes its shape from a role on the type ramp (`text-caption` to `text-title`), never from raw Tailwind typography such as `text-sm`, `leading-*`, `tracking-*` or `uppercase`. The roles are defined in `styles/index.css`, so an app gets them by importing that stylesheet. The rule that keeps an app on them is published as `@instruments/materia-ui/lint/type-case`:
+
+```ts
+import next from "@howells/lint/oxlint/next";
+import { typeCaseRule } from "@instruments/materia-ui/lint/type-case";
+
+export default {
+  extends: [next],
+  rules: { ...typeCaseRule },
+};
+```
+
+It runs `@howells/lint`'s `no-raw-type-utilities`, so the app needs the `howells` plugin in scope, which every `@howells/lint` preset carries.
+
+## Enabling the colour tokens (Oxlint)
+
+`shadcn/no-raw-colors` keeps colour on theme tokens, but it reads declared tokens only from the app's own stylesheet and skips anything under `node_modules`, so in an app that installs this package every Materia token looks undeclared. `@instruments/materia-ui/lint/tokens` publishes the names instead, generated from `styles/index.css`, with a ready-made rule that allows them:
+
+```ts
+import next from "@howells/lint/oxlint/next";
+import { rawColorsRule } from "@instruments/materia-ui/lint/tokens";
+import { typeCaseRule } from "@instruments/materia-ui/lint/type-case";
+
+export default {
+  extends: [next],
+  rules: { ...rawColorsRule, ...typeCaseRule },
+};
+```
+
+`rawColorsRule` allows every utility on a declared colour (`*-primary`, `*-muted-foreground`) and every `text-<role>`, which the rule would otherwise read as an undeclared colour. The bare lists are exported as `colorTokens` and `textRoles` for an app that adds tokens of its own:
+
+```ts
+import { colorTokens, textRoles } from "@instruments/materia-ui/lint/tokens";
+
+const allow = [
+  ...colorTokens.map((name) => `*-${name}`),
+  ...textRoles.map((name) => `text-${name}`),
+  "*-brand-ink",
+];
+```
+
+Every `lint/*` entry ships its own type declarations, so a TypeScript config imports them without a shim.
+
+## Enabling the class-string rules (scanner)
+
+Run the scanner as part of your lint script. It is exposed as the `materia-ui-lint` bin:
+
+```jsonc
+{
+  "scripts": {
+    // hex on, arbitrary off (current default for apps/web)
+    "lint": "materia-ui-lint app components features lib && howells-check app components features lib",
+  },
+}
+```
+
+### Scanner flags
+
+| Flag | Effect |
+| --- | --- |
+| _(default)_ | **hex** rule on, **arbitrary** rule off |
+| `--arbitrary` | also enable the arbitrary-values rule |
+| `--all` | enable both rules |
+| `--no-hex` | disable the hex rule |
+| `--exclude <substr>` | skip any file whose path contains `<substr>` (repeatable) |
+
+The scanner scopes detection to class strings only: `class`/`className` attribute values and the argument lists of `cn` / `clsx` / `cva` / `tv` / `twMerge` / `twJoin` / `classNames`. Inline `style={{ … }}` colours and ordinary colour constants are not flagged. It exits non-zero and prints `file:line:col  rule  value  message` for each violation.

package/lint/doctrine-rules.mjs

@@ -0,0 +1,111 @@
+/**
+ * Hand-authored doctrine taxonomy for @instruments/materia-ui.
+ *
+ * The design system's "wrong UI must not typecheck" doctrine is enforced by
+ * independent mechanisms (three oxlint import bans, four node gate scripts, one
+ * layer matrix, one api-drift gate) with NO single source file. This module is
+ * the one place that names them as a coherent set. It carries only the stable
+ * editorial framing (id / name / one-line statement / which gates enforce it);
+ * `scripts/generate-docs-manifest.mjs` HYDRATES each rule at build time with the
+ * live data it must never restate by hand:
+ *
+ *   - `restrictedImports` - the import bans read straight out of the repo's
+ *     oxlint policy fragments, each of which exports an `importBans` array of
+ *     `{ group, message }` (see `IMPORT_BAN_SOURCES`). A rule opts in via
+ *     `banMatch`, a substring matched against those live messages.
+ *   - `matrix` / `layers` - the layer dependency matrix imported from
+ *     scripts/layer-matrix.mjs's exported `LAYERS` / `ALLOWED`.
+ *   - per-gate `doctrine` prose - the single `@doctrine` sentinel line in each
+ *     gate script's header, extracted by a strict tag-line parse.
+ *
+ * Treat each fragment's `message` field as published copy: it is rendered
+ * verbatim on the MateriaUI doctrine page, so it is edited with that page in
+ * mind rather than as a lint string.
+ *
+ * @module
+ */
+
+/**
+ * Repo-root-relative paths of the oxlint policy fragments carrying import bans.
+ * Each exports `importBans`, an array of `{ group, message }`. Deduped by
+ * message downstream, because the lucide fragment restates the Base UI pattern
+ * (oxlint replaces a rule's options rather than merging them).
+ */
+export const IMPORT_BAN_SOURCES = [
+  "lint/no-raw-base-ui.mjs",
+  "lint/no-raw-lucide.mjs",
+  "lint/materia-policy.mjs",
+];
+
+/**
+ * The five hard rules plus the layer matrix and the api-drift gate. `gates` are
+ * repo-root-relative paths, and a `.mjs` gate contributes its `@doctrine`
+ * sentinel. `banMatch` selects the rule's published import-ban messages out of
+ * `IMPORT_BAN_SOURCES` by substring. `kind: "layer-matrix"` asks the generator to
+ * attach the live LAYERS/ALLOWED matrix.
+ */
+export const DOCTRINE_RULES = [
+  {
+    id: "no-raw-base-ui",
+    name: "No raw Base UI primitives",
+    statement:
+      "Base UI primitives are consumed only through @instruments/materia-ui components - never imported directly - so every consumer inherits the design system's accessibility and styling contract.",
+    gates: ["lint/no-raw-base-ui.mjs"],
+    banMatch: "Base UI",
+  },
+  {
+    id: "no-raw-lucide",
+    name: "No raw Lucide icons",
+    statement:
+      "Lucide glyphs are imported from @instruments/materia-ui/icons and rendered through the Icon component, keeping the icon dependency behind the design-system boundary.",
+    gates: ["lint/no-raw-lucide.mjs"],
+    banMatch: "lucide-react",
+  },
+  {
+    id: "tokens-only",
+    name: "Tokens-only values",
+    statement:
+      "Class strings use design tokens and theme utilities only - no raw hex/oklch colours, no arbitrary Tailwind values that shadow a real token step.",
+    gates: [
+      "packages/ui/lint/scan-classes.mjs",
+      "packages/ui/oxlint.config.ts",
+    ],
+  },
+  {
+    id: "flat-shim-imports",
+    name: "Flat-shim imports only",
+    statement:
+      "Every component is imported from its flat shim @instruments/materia-ui/components/<name>, never a deep internal part path - the shim is the stable public seam.",
+    gates: ["lint/materia-policy.mjs"],
+    banMatch: "flat shim",
+  },
+  {
+    id: "lazy-motion",
+    name: "m.* LazyMotion only",
+    statement:
+      "Components animate with the m.* LazyMotion primitives, never the full motion.* namespace, so the animation engine is never forced into a consumer's bundle.",
+    gates: ["packages/ui/oxlint.config.ts"],
+  },
+  {
+    id: "layer-matrix",
+    name: "Six-layer dependency matrix",
+    kind: "layer-matrix",
+    statement:
+      "The six src layers form a strict one-directional dependency matrix (data ← tokens ← utils ← hooks ← components ← compositions); tokens additionally take no external packages.",
+    gates: ["packages/ui/scripts/layer-matrix.mjs"],
+  },
+  {
+    id: "no-naked-element",
+    name: "No naked HTML elements",
+    statement:
+      "Application markup renders only @instruments/materia-ui components - every raw lowercase HTML host is lint-banned; the closed polymorphic `as` vocabulary picks semantics from an authored menu and className on a primitive (tokens-policed) is the single escape hatch.",
+    gates: ["packages/ui/lint/oxlint/no-naked-element.mjs"],
+  },
+  {
+    id: "api-drift",
+    name: "API surface drift gate",
+    statement:
+      "The full public export surface is captured as resolved-type hashes in api-report.md; any change to a public signature flips a hash and fails the gate until the report is regenerated and reviewed.",
+    gates: ["packages/ui/scripts/generate-api-report.mjs"],
+  },
+];

package/lint/oxlint/fixtures/allowed.tsx

@@ -0,0 +1,12 @@
+// Fixture: linted under an override granting allow:["html","body"]. The html and
+// body hosts must be suppressed; the div must still report. Exactly ONE
+// diagnostic proves context.options reaches the rule and is honored selectively.
+export function Allowed() {
+  return (
+    <html lang="en">
+      <body>
+        <div>still banned</div>
+      </body>
+    </html>
+  );
+}

package/lint/oxlint/fixtures/fixture.config.mjs

@@ -0,0 +1,29 @@
+// Fixture oxlint config. Plain object (oxlint's defineConfig is identity), so we
+// avoid importing "oxlint" here. The plugin is referenced by a file:// URL
+// resolved relative to this config so the test is location-independent.
+const specifier = new URL("../index.mjs", import.meta.url).href;
+
+export default {
+  // Single-purpose doctrine gate: silence oxlint's built-in rules so the JSON
+  // report contains only our diagnostics.
+  categories: { correctness: "off" },
+  jsPlugins: [{ name: "materia-ui", specifier }],
+  rules: {
+    "materia-ui/no-naked-element": "error",
+    "materia-ui/no-render-layout-as": "error",
+  },
+  overrides: [
+    {
+      files: ["**/allowed.tsx"],
+      rules: {
+        "materia-ui/no-naked-element": ["error", { allow: ["html", "body"] }],
+      },
+    },
+    {
+      files: ["**/layout-only.tsx"],
+      rules: {
+        "materia-ui/no-naked-element": ["error", { layoutOnly: true }],
+      },
+    },
+  ],
+};

package/lint/oxlint/fixtures/invalid.tsx

@@ -0,0 +1,24 @@
+// Fixture: every raw host on its own line so the rule reports each one.
+// Not a real module - never imported, never type-checked, never shipped as code.
+export function Invalid() {
+  return (
+    <div>
+      <span>text</span>
+      <a href="#">link</a>
+      <main>main</main>
+      <ul>
+        <li>item</li>
+      </ul>
+      <code>code</code>
+      <pre>pre</pre>
+      <img src="x.png" alt="" />
+      <svg />
+      <button type="button">btn</button>
+      <input />
+      <label>label</label>
+      <p>paragraph</p>
+      <section>section</section>
+      <h1>heading</h1>
+    </div>
+  );
+}

package/lint/oxlint/fixtures/layout-only.tsx

@@ -0,0 +1,26 @@
+// Fixture: linted under an override granting layoutOnly:true. Only a layout host
+// whose unconditional classes make it a flex or grid container reports: the
+// flex div (line 10), the inline-flex span (line 11), the grid template literal
+// (line 12) and the cn() argument (line 13). Everything after line 13 is clean.
+const cn = (...classes: unknown[]) => classes.filter(Boolean).join(" ");
+
+export function LayoutOnly({ open, size }: { open: boolean; size: number }) {
+  return (
+    <>
+      <div className="border-border flex items-center gap-2">flex</div>
+      <span className="inline-flex">inline</span>
+      <ul className={`grid gap-${size}`}>grid</ul>
+      <div className={cn("flex flex-1", open && "p-2")}>call</div>
+      <div className="p-4">plain</div>
+      <svg viewBox="0 0 1 1">
+        <path className="flex" d="M0 0" />
+      </svg>
+      <div className={cn("p-2", open && "flex")}>conditional</div>
+      <div className={`gap-${size}flex`}>glued</div>
+      <button className="flex" type="button">
+        not a layout host
+      </button>
+      <div className="flex-1 flex-col">no display utility</div>
+    </>
+  );
+}

package/lint/oxlint/fixtures/render-as-invalid.tsx

@@ -0,0 +1,11 @@
+// Fixture: each render={<Primitive as=... />} sits on its own line.
+// Not a real module - never imported, never type-checked, never shipped as code.
+export function RenderAsInvalid() {
+  return (
+    <>
+      <Stack render={<Box as="li" />} />
+      <Flex render={<Stack as="ul" />} />
+      <Grid render={<Center as="section" />} />
+    </>
+  );
+}

package/lint/oxlint/fixtures/render-as-valid.tsx

@@ -0,0 +1,14 @@
+// Fixture: legitimate render and as usage the rule must leave alone.
+// Not a real module - never imported, never type-checked, never shipped as code.
+export function RenderAsValid() {
+  return (
+    <>
+      <Stack as="ul" />
+      <Stack render={<Link href="/" />} />
+      <Stack render={<Box />} />
+      <Stack render={<Link as="a" href="/" />} />
+      <Stack render={<Foo.Bar as="li" />} />
+      <TooltipTrigger render={<Box as="span" />} />
+    </>
+  );
+}

package/lint/oxlint/fixtures/valid.tsx

@@ -0,0 +1,18 @@
+// Fixture: only design-system components, a member expression, a fragment, and a
+// self-closing component - none of these should trip the rule.
+import { Anchor, Box, Card, Stack, Text } from "@instruments/materia-ui";
+
+export function Valid() {
+  return (
+    <>
+      <Box>
+        <Stack>
+          <Text>hello</Text>
+          <Anchor href="#">link</Anchor>
+        </Stack>
+        <Card.Header>header</Card.Header>
+        <Box />
+      </Box>
+    </>
+  );
+}