@ux-builder/ui 0.0.0-stage → 0.6.1

package/licenses/vendored.json

@@ -0,0 +1,214 @@
+{
+  "$description": "Third-party source shipped inside @ux-builder/ui (ADR-023 rule 6), read by tools/check-licences.mjs. Each entry's files must keep its notice; changed files must say so; its licence text must ship in licenses/. The icon glyphs are generated by scripts/gen-icons.mjs, which writes these notice lines and copies the licences. Entries with shipped: false (AI Elements, assistant-ui and shadcn/ui, copied by tools/vendor-ai-elements.mjs) are used only by Storybook and the theme builder, so they need their notices but not a place in package.json \"files\".",
+  "vendored": [
+    {
+      "name": "@material-symbols/svg-400 glyphs",
+      "source": "https://github.com/marella/material-symbols",
+      "version": "0.47.6",
+      "licence": "Apache-2.0",
+      "licenceFile": "licenses/material.LICENSE",
+      "files": [
+        "src/icons/glyphs.generated.js",
+        "src/icons/library.generated.js"
+      ],
+      "notice": "@material-symbols/svg-400@0.47.6, Apache-2.0 (licenses/material.LICENSE)",
+      "changed": [
+        "src/icons/glyphs.generated.js",
+        "src/icons/library.generated.js"
+      ],
+      "changeNotice": "Generated by scripts/gen-icons.mjs"
+    },
+    {
+      "name": "@fluentui/svg-icons glyphs",
+      "source": "https://github.com/microsoft/fluentui-system-icons",
+      "version": "1.1.343",
+      "licence": "MIT",
+      "licenceFile": "licenses/fluent.LICENSE",
+      "files": [
+        "src/icons/glyphs.generated.js",
+        "src/icons/library.generated.js"
+      ],
+      "notice": "@fluentui/svg-icons@1.1.343, MIT (licenses/fluent.LICENSE)",
+      "changed": [
+        "src/icons/glyphs.generated.js",
+        "src/icons/library.generated.js"
+      ],
+      "changeNotice": "Generated by scripts/gen-icons.mjs"
+    },
+    {
+      "name": "@carbon/icons glyphs",
+      "source": "https://github.com/carbon-design-system/carbon",
+      "version": "11.89.0",
+      "licence": "Apache-2.0",
+      "licenceFile": "licenses/carbon.LICENSE",
+      "files": [
+        "src/icons/glyphs.generated.js",
+        "src/icons/library.generated.js"
+      ],
+      "notice": "@carbon/icons@11.89.0, Apache-2.0 (licenses/carbon.LICENSE)",
+      "changed": [
+        "src/icons/glyphs.generated.js",
+        "src/icons/library.generated.js"
+      ],
+      "changeNotice": "Generated by scripts/gen-icons.mjs"
+    },
+    {
+      "name": "lucide-static glyphs",
+      "source": "https://github.com/lucide-icons/lucide",
+      "version": "1.52.0",
+      "licence": "ISC",
+      "licenceFile": "licenses/lucide.LICENSE",
+      "files": [
+        "src/icons/glyphs.generated.js",
+        "src/icons/library.generated.js"
+      ],
+      "notice": "lucide-static@1.52.0, ISC (licenses/lucide.LICENSE)",
+      "changed": [
+        "src/icons/glyphs.generated.js",
+        "src/icons/library.generated.js"
+      ],
+      "changeNotice": "Generated by scripts/gen-icons.mjs"
+    },
+    {
+      "name": "AI Elements components",
+      "source": "https://github.com/vercel/ai-elements (registry.ai-sdk.dev)",
+      "version": "registry, fetched 2026-10-19",
+      "licence": "Apache-2.0",
+      "licenceFile": "ai/licenses/ai-elements.LICENSE",
+      "shipped": false,
+      "files": [
+        "ai/vendor/ai-elements/artifact.tsx",
+        "ai/vendor/ai-elements/chain-of-thought.tsx",
+        "ai/vendor/ai-elements/code-block.tsx",
+        "ai/vendor/ai-elements/confirmation.tsx",
+        "ai/vendor/ai-elements/conversation.tsx",
+        "ai/vendor/ai-elements/inline-citation.tsx",
+        "ai/vendor/ai-elements/message.tsx",
+        "ai/vendor/ai-elements/prompt-input.tsx",
+        "ai/vendor/ai-elements/reasoning.tsx",
+        "ai/vendor/ai-elements/shimmer.tsx",
+        "ai/vendor/ai-elements/sources.tsx",
+        "ai/vendor/ai-elements/suggestion.tsx",
+        "ai/vendor/ai-elements/task.tsx",
+        "ai/vendor/ai-elements/tool.tsx"
+      ],
+      "notice": "Copyright 2023 Vercel, Inc.",
+      "changed": [
+        "ai/vendor/ai-elements/artifact.tsx",
+        "ai/vendor/ai-elements/chain-of-thought.tsx",
+        "ai/vendor/ai-elements/code-block.tsx",
+        "ai/vendor/ai-elements/confirmation.tsx",
+        "ai/vendor/ai-elements/conversation.tsx",
+        "ai/vendor/ai-elements/inline-citation.tsx",
+        "ai/vendor/ai-elements/message.tsx",
+        "ai/vendor/ai-elements/prompt-input.tsx",
+        "ai/vendor/ai-elements/reasoning.tsx",
+        "ai/vendor/ai-elements/shimmer.tsx",
+        "ai/vendor/ai-elements/sources.tsx",
+        "ai/vendor/ai-elements/suggestion.tsx",
+        "ai/vendor/ai-elements/task.tsx",
+        "ai/vendor/ai-elements/tool.tsx"
+      ]
+    },
+    {
+      "name": "assistant-ui components",
+      "source": "https://github.com/assistant-ui/assistant-ui (r.assistant-ui.com)",
+      "version": "registry, fetched 2026-10-19",
+      "licence": "MIT",
+      "licenceFile": "ai/licenses/assistant-ui.LICENSE",
+      "shipped": false,
+      "files": [
+        "ai/vendor/assistant-ui/attachment.aui.tsx",
+        "ai/vendor/assistant-ui/collapsible-root.tsx",
+        "ai/vendor/assistant-ui/file.tsx",
+        "ai/vendor/assistant-ui/follow-up-suggestions.aui.tsx",
+        "ai/vendor/assistant-ui/href.ts",
+        "ai/vendor/assistant-ui/image.tsx",
+        "ai/vendor/assistant-ui/markdown-text.tsx",
+        "ai/vendor/assistant-ui/media-player.tsx",
+        "ai/vendor/assistant-ui/reasoning.aui.tsx",
+        "ai/vendor/assistant-ui/reasoning.tsx",
+        "ai/vendor/assistant-ui/surfaces.tsx",
+        "ai/vendor/assistant-ui/thread.aui.tsx",
+        "ai/vendor/assistant-ui/tool-fallback.aui.tsx",
+        "ai/vendor/assistant-ui/tool-group.aui.tsx",
+        "ai/vendor/assistant-ui/tooltip-icon-button.tsx",
+        "ai/vendor/assistant-ui/use-attachment-src.ts",
+        "ai/vendor/assistant-ui/use-copy-to-clipboard.ts",
+        "ai/vendor/assistant-ui/useIsomorphicLayoutEffect.ts"
+      ],
+      "notice": "Copyright (c) 2026 AgentbaseAI Inc.",
+      "changed": [
+        "ai/vendor/assistant-ui/attachment.aui.tsx",
+        "ai/vendor/assistant-ui/collapsible-root.tsx",
+        "ai/vendor/assistant-ui/file.tsx",
+        "ai/vendor/assistant-ui/follow-up-suggestions.aui.tsx",
+        "ai/vendor/assistant-ui/href.ts",
+        "ai/vendor/assistant-ui/image.tsx",
+        "ai/vendor/assistant-ui/markdown-text.tsx",
+        "ai/vendor/assistant-ui/media-player.tsx",
+        "ai/vendor/assistant-ui/reasoning.aui.tsx",
+        "ai/vendor/assistant-ui/reasoning.tsx",
+        "ai/vendor/assistant-ui/surfaces.tsx",
+        "ai/vendor/assistant-ui/thread.aui.tsx",
+        "ai/vendor/assistant-ui/tool-fallback.aui.tsx",
+        "ai/vendor/assistant-ui/tool-group.aui.tsx",
+        "ai/vendor/assistant-ui/tooltip-icon-button.tsx",
+        "ai/vendor/assistant-ui/use-attachment-src.ts",
+        "ai/vendor/assistant-ui/use-copy-to-clipboard.ts",
+        "ai/vendor/assistant-ui/useIsomorphicLayoutEffect.ts"
+      ]
+    },
+    {
+      "name": "shadcn/ui components",
+      "source": "https://github.com/shadcn-ui/ui (ui.shadcn.com, new-york-v4)",
+      "version": "registry, fetched 2026-10-19",
+      "licence": "MIT",
+      "licenceFile": "ai/licenses/shadcn-ui.LICENSE",
+      "shipped": false,
+      "files": [
+        "ai/vendor/ui/alert.tsx",
+        "ai/vendor/ui/avatar.tsx",
+        "ai/vendor/ui/badge.tsx",
+        "ai/vendor/ui/button-group.tsx",
+        "ai/vendor/ui/button.tsx",
+        "ai/vendor/ui/carousel.tsx",
+        "ai/vendor/ui/collapsible.tsx",
+        "ai/vendor/ui/command.tsx",
+        "ai/vendor/ui/dialog.tsx",
+        "ai/vendor/ui/dropdown-menu.tsx",
+        "ai/vendor/ui/hover-card.tsx",
+        "ai/vendor/ui/input-group.tsx",
+        "ai/vendor/ui/input.tsx",
+        "ai/vendor/ui/scroll-area.tsx",
+        "ai/vendor/ui/select.tsx",
+        "ai/vendor/ui/separator.tsx",
+        "ai/vendor/ui/skeleton.tsx",
+        "ai/vendor/ui/textarea.tsx",
+        "ai/vendor/ui/tooltip.tsx"
+      ],
+      "notice": "Copyright (c) 2023 shadcn",
+      "changed": [
+        "ai/vendor/ui/alert.tsx",
+        "ai/vendor/ui/avatar.tsx",
+        "ai/vendor/ui/badge.tsx",
+        "ai/vendor/ui/button-group.tsx",
+        "ai/vendor/ui/button.tsx",
+        "ai/vendor/ui/carousel.tsx",
+        "ai/vendor/ui/collapsible.tsx",
+        "ai/vendor/ui/command.tsx",
+        "ai/vendor/ui/dialog.tsx",
+        "ai/vendor/ui/dropdown-menu.tsx",
+        "ai/vendor/ui/hover-card.tsx",
+        "ai/vendor/ui/input-group.tsx",
+        "ai/vendor/ui/input.tsx",
+        "ai/vendor/ui/scroll-area.tsx",
+        "ai/vendor/ui/select.tsx",
+        "ai/vendor/ui/separator.tsx",
+        "ai/vendor/ui/skeleton.tsx",
+        "ai/vendor/ui/textarea.tsx",
+        "ai/vendor/ui/tooltip.tsx"
+      ]
+    }
+  ]
+}

package/lint/core.mjs

@@ -0,0 +1,158 @@
+/* ux-builder/no-hard-coded-values (FEAT-004 SDK-10, SDK-11; US-013): the checks
+   shared by the stylelint plugin and the ESLint rule.
+
+   A literal colour, font family or border radius in app code looks right
+   under one theme and wrong under every other. This finds them in a CSS
+   declaration (property + value), names the role token to use where the
+   app's theme has one with that exact value, and honours a reviewed
+   allow-list: each entry needs a reason.
+
+   Not reported: var(--…) (including literals in a var() fallback, which
+   only apply when a token is missing), transparent, currentColor, the
+   CSS-wide keywords, none, 0, generic font families on their own, and
+   fully round radii (50%, 100%, 999px or more), which are geometry rather
+   than a theme's choice. */
+
+import { createRequire } from "node:module";
+import { join } from "node:path";
+
+export const RULE = "ux-builder/no-hard-coded-values";
+
+const NAMED = new Set(("aliceblue antiquewhite aqua aquamarine azure beige bisque black blanchedalmond blue blueviolet brown burlywood cadetblue chartreuse chocolate coral cornflowerblue cornsilk crimson cyan darkblue darkcyan darkgoldenrod darkgray darkgreen darkgrey darkkhaki darkmagenta darkolivegreen darkorange darkorchid darkred darksalmon darkseagreen darkslateblue darkslategray darkslategrey darkturquoise darkviolet deeppink deepskyblue dimgray dimgrey dodgerblue firebrick floralwhite forestgreen fuchsia gainsboro ghostwhite gold goldenrod gray green greenyellow grey honeydew hotpink indianred indigo ivory khaki lavender lavenderblush lawngreen lemonchiffon lightblue lightcoral lightcyan lightgoldenrodyellow lightgray lightgreen lightgrey lightpink lightsalmon lightseagreen lightskyblue lightslategray lightslategrey lightsteelblue lightyellow lime limegreen linen magenta maroon mediumaquamarine mediumblue mediumorchid mediumpurple mediumseagreen mediumslateblue mediumspringgreen mediumturquoise mediumvioletred midnightblue mintcream mistyrose moccasin navajowhite navy oldlace olive olivedrab orange orangered orchid palegoldenrod palegreen paleturquoise palevioletred papayawhip peachpuff peru pink plum powderblue purple rebeccapurple red rosybrown royalblue saddlebrown salmon sandybrown seagreen seashell sienna silver skyblue slateblue slategray slategrey snow springgreen steelblue tan teal thistle tomato turquoise violet wheat white whitesmoke yellow yellowgreen").split(" "));
+const GENERIC = new Set(["serif", "sans-serif", "monospace", "cursive", "fantasy", "system-ui", "ui-serif", "ui-sans-serif", "ui-monospace", "ui-rounded", "emoji", "math", "fangsong", "inherit", "initial", "unset", "revert", "revert-layer"]);
+const COLOUR_FN = /\b(?:rgba?|hsla?|hwb|lab|lch|oklab|oklch|color)\(/gi;
+const RADIUS = /^border(?:-(?:top|bottom|start|end)-(?:left|right|start|end))?-radius$/;
+const COLOUR_PROPS = /^(?:--.*|color|background(?:-color|-image)?|border(?:-(?:top|right|bottom|left|block|inline)(?:-(?:start|end))?)?(?:-color)?|outline(?:-color)?|fill|stroke|(?:box|text)-shadow|caret-color|accent-color|text-decoration(?:-color)?|text-emphasis(?:-color)?|column-rule(?:-color)?|scrollbar-color|stop-color|flood-color|lighting-color)$/i;
+
+/* Remove var(…) (with its fallback) and url(…), keeping positions roughly
+   stable by blanking them, so what is left is the literal part. */
+export function stripVars(value) {
+  let out = "", i = 0;
+  const s = String(value);
+  while (i < s.length) {
+    const m = /^(var|url|env)\(/i.exec(s.slice(i));
+    if (m) {
+      let depth = 0, j = i + m[1].length;
+      for (; j < s.length; j++) { if (s[j] === "(") depth++; else if (s[j] === ")" && --depth === 0) break; }
+      out += " ".repeat(j + 1 - i); i = j + 1; continue;
+    }
+    out += s[i++];
+  }
+  return out;
+}
+
+function balanced(s, start) {
+  let depth = 0;
+  for (let j = start; j < s.length; j++) { if (s[j] === "(") depth++; else if (s[j] === ")" && --depth === 0) return s.slice(start, j + 1); }
+  return s.slice(start);
+}
+
+/* The literal colours, fonts and radii in one declaration: [{ kind, literal, index }]. */
+export function literals(property, value) {
+  const prop = String(property).toLowerCase();
+  const raw = String(value);
+  const bare = stripVars(raw);
+  const out = [];
+  if (COLOUR_PROPS.test(prop)) {
+    const noStrings = bare.replace(/(["'])(?:\\.|(?!\1).)*\1/g, (m) => " ".repeat(m.length));
+    for (const m of noStrings.matchAll(/#[0-9a-f]{3,8}\b/gi)) if ([4, 5, 7, 9].includes(m[0].length)) out.push({ kind: "colour", literal: m[0], index: m.index });
+    for (const m of noStrings.matchAll(COLOUR_FN)) out.push({ kind: "colour", literal: balanced(noStrings, m.index + m[0].length - 1).replace(/^\(/, m[0].slice(0, -1) + "("), index: m.index });
+    for (const m of noStrings.matchAll(/[a-z]+/gi)) if (NAMED.has(m[0].toLowerCase()) && !/[-\w]$/.test(noStrings.slice(0, m.index)) && !/^[-\w(]/.test(noStrings.slice(m.index + m[0].length))) out.push({ kind: "colour", literal: m[0], index: m.index });
+  }
+  if (prop === "font-family" || prop === "font") {
+    // In the font shorthand the families follow the size (and optional /line-height).
+    const families = prop === "font" ? (/(?:^|\s)(?:[\d.]+(?:px|rem|em|%|pt|vw|vh|ch)|xx?-small|small|medium|large|xx?-large|larger|smaller)(?:\/\S+)?\s+(.+)$/i.exec(bare.trim())?.[1] ?? "") : bare;
+    for (const f of families.split(",").map((x) => x.trim()).filter(Boolean)) {
+      const name = f.replace(/^["']|["']$/g, "");
+      if (!GENERIC.has(name.toLowerCase())) { out.push({ kind: "font", literal: f, index: Math.max(0, raw.indexOf(f)) }); break; }
+    }
+  }
+  if (RADIUS.test(prop)) {
+    for (const m of bare.matchAll(/-?\d*\.?\d+(px|rem|em|%|vw|vh|ch)?/g)) {
+      const n = parseFloat(m[0]), unit = m[1] ?? "";
+      if (n === 0) continue;
+      if ((unit === "%" && n >= 50) || (unit === "px" && n >= 999) || ((unit === "rem" || unit === "em") && n >= 99)) continue;
+      out.push({ kind: "radius", literal: m[0], index: m.index });
+    }
+  }
+  return out.sort((a, b) => a.index - b.index);
+}
+
+/* ---------------------------------------------------------- suggestions */
+
+function hexOf(literal) {
+  const s = literal.trim().toLowerCase();
+  if (/^#[0-9a-f]{3,4}$/.test(s)) return "#" + [...s.slice(1, 4)].map((c) => c + c).join("").toUpperCase();
+  if (/^#[0-9a-f]{6}([0-9a-f]{2})?$/.test(s)) return s.slice(0, 7).toUpperCase();
+  const m = /^rgba?\(\s*(\d+)[\s,]+(\d+)[\s,]+(\d+)/.exec(s);
+  if (m) return "#" + m.slice(1, 4).map((v) => Math.min(255, +v).toString(16).padStart(2, "0")).join("").toUpperCase();
+  return null;
+}
+const firstFamily = (stack) => String(stack).split(",")[0].trim().replace(/^["']|["']$/g, "").toLowerCase();
+const PREFER = [/^piq-color-text$/, /^piq-color-/, /^piq-state-/, /^piq-font-body$/, /^piq-font-/, /^piq-radius-/, /-radius$/];
+const rank = (k) => { const i = PREFER.findIndex((r) => r.test(k)); return i < 0 ? PREFER.length : i; };
+
+/* Role tokens whose value in the app's theme equals this literal, best first. */
+export function suggest(finding, tokens) {
+  if (!tokens) return [];
+  const entries = Object.entries(tokens).filter(([k]) => k.startsWith("piq-"));
+  let hits = [];
+  if (finding.kind === "colour") {
+    const hex = hexOf(finding.literal);
+    if (hex) hits = entries.filter(([k, v]) => /^piq-(color|state)-/.test(k) && String(v).toUpperCase() === hex);
+  } else if (finding.kind === "font") {
+    const f = firstFamily(finding.literal);
+    hits = entries.filter(([k, v]) => /^piq-font-(body|heading|display|mono)$/.test(k) && firstFamily(v) === f);
+  } else if (finding.kind === "radius") {
+    hits = entries.filter(([k, v]) => /radius/.test(k) && String(v).trim() === finding.literal.trim());
+  }
+  return hits.map(([k]) => k).sort((a, b) => rank(a) - rank(b) || a.localeCompare(b));
+}
+
+const KIND = { colour: "colour", font: "font family", radius: "radius" };
+export function message(finding, suggestions) {
+  const head = `Hard-coded ${KIND[finding.kind]} ${finding.literal}`;
+  if (!suggestions.length) return `${head}: use a --piq-* role token (${RULE})`;
+  const [best, ...rest] = suggestions;
+  return `${head}: use var(--${best})${rest.length ? ` (same value: ${rest.slice(0, 2).map((r) => `--${r}`).join(", ")})` : ""} (${RULE})`;
+}
+
+/* ------------------------------------------------------------ options */
+
+/* The resolved tokens of the app's theme, from the @ux-builder/tokens the app has
+   installed (else this package's own), for suggestions. */
+export function loadTokens(theme, appearance = "light", from = process.cwd()) {
+  if (!theme) return null;
+  for (const base of [join(from, "noop.js"), import.meta.url]) {
+    try { return createRequire(base)(`@ux-builder/tokens/resolved/${theme}.${appearance}.json`).tokens; } catch { /* try the next */ }
+  }
+  return null;
+}
+
+/* Allow-list entries: { value?, property?, file?, reason }. Returns errors for
+   entries without a reason or without anything to match. */
+export function checkAllow(allow = []) {
+  const errors = [];
+  if (!Array.isArray(allow)) return ["allow must be a list of { value?, property?, file?, reason }"];
+  allow.forEach((e, i) => {
+    if (!e || typeof e !== "object") errors.push(`allow[${i}] is not an object`);
+    else if (!String(e.reason ?? "").trim()) errors.push(`allow[${i}] has no reason: every exception is reviewed, so say why`);
+    else if (!e.value && !e.property && !e.file) errors.push(`allow[${i}] matches nothing: give value, property or file`);
+  });
+  return errors;
+}
+
+const globRe = (g) => new RegExp("(^|/)" + g.split("**").map((p) => p.split("*").map((x) => x.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join("[^/]*")).join(".*") + "$");
+export function allowed(finding, property, file, allow = []) {
+  return allow.some((e) => e?.reason
+    && (!e.value || String(e.value).toLowerCase().replace(/\s+/g, "") === finding.literal.toLowerCase().replace(/\s+/g, ""))
+    && (!e.property || String(e.property).toLowerCase() === String(property).toLowerCase())
+    && (!e.file || globRe(e.file).test(String(file ?? "").split("\\").join("/"))));
+}
+
+/* Everything to report for one declaration. */
+export function check(property, value, { tokens, allow = [], file } = {}) {
+  return literals(property, value)
+    .filter((f) => !allowed(f, property, file, allow))
+    .map((f) => ({ ...f, message: message(f, suggest(f, tokens)) }));
+}

package/lint/eslint.mjs

@@ -0,0 +1,128 @@
+// ux-builder/no-hard-coded-values for ESLint: the same check on JSX style props
+// (FEAT-004 SDK-10, SDK-11); and ux-builder/no-foreign-ui and
+// ux-builder/no-inline-svg, below (US-022).
+//
+//   // eslint.config.js
+//   import uxBuilder from "@ux-builder/ui/eslint";
+//   export default [{
+//     files: ["src/**/*.{js,jsx,ts,tsx}"],
+//     plugins: { "ux-builder": uxBuilder },
+//     rules: {
+//       "ux-builder/no-hard-coded-values": ["error", { theme: "databricks", allow: [] }],
+//       "ux-builder/no-foreign-ui": "error",
+//       "ux-builder/no-inline-svg": "error",
+//     },
+//   }];
+//
+// Only literal values are checked (strings, numbers for radii, template
+// strings without expressions); a value computed at run time is the app's own
+// data, not a hard-coded style.
+
+import { RULE, check, checkAllow, loadTokens } from "./core.mjs";
+
+const kebab = (k) => (k.startsWith("--") ? k : k.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`).replace(/^(webkit|moz|ms)-/, "-$1-"));
+const keyOf = (p) => (p.key.type === "Identifier" ? p.key.name : p.key.type === "Literal" ? String(p.key.value) : null);
+
+function literalOf(node, property) {
+  if (node.type === "Literal" && typeof node.value === "string") return node.value;
+  if (node.type === "Literal" && typeof node.value === "number") return /radius$/.test(property) && node.value !== 0 ? `${node.value}px` : null;
+  if (node.type === "TemplateLiteral" && node.expressions.length === 0) return node.quasis[0].value.cooked;
+  return null;
+}
+
+const rule = {
+  meta: {
+    type: "suggestion",
+    docs: { description: "Report hard-coded colours, font families and radii in JSX style props; use --piq-* role tokens" },
+    schema: [{ type: "object", properties: { theme: { type: "string" }, allow: { type: "array" } }, additionalProperties: false }],
+  },
+  create(context) {
+    const opts = context.options[0] ?? {};
+    const allow = opts.allow ?? [];
+    const tokens = loadTokens(opts.theme, "light", context.cwd ?? process.cwd());
+    const file = context.filename ?? context.getFilename?.();
+    return {
+      Program(node) {
+        for (const e of checkAllow(allow)) context.report({ node, message: `${e} (${RULE})` });
+      },
+      JSXAttribute(attr) {
+        if (attr.name?.name !== "style" || attr.value?.type !== "JSXExpressionContainer") return;
+        const obj = attr.value.expression;
+        if (obj.type !== "ObjectExpression") return;
+        for (const p of obj.properties) {
+          if (p.type !== "Property" || p.computed) continue;
+          const key = keyOf(p);
+          if (!key) continue;
+          const property = kebab(key), value = literalOf(p.value, property);
+          if (value == null) continue;
+          for (const f of check(property, value, { tokens, allow, file })) context.report({ node: p.value, message: f.message });
+        }
+      },
+    };
+  },
+};
+
+/* ux-builder/no-foreign-ui: another UI kit's components or icon set do not
+   follow the theme, so an import of one is reported with the SDK's
+   counterpart (US-022). allow: package names the app has reviewed. */
+const FOREIGN = [
+  [/^@mui\/(?!utils|base)/, "Material UI", "the SDK's widgets"],
+  [/^antd(\/|$)/, "Ant Design", "the SDK's widgets"],
+  [/^@chakra-ui\//, "Chakra UI", "the SDK's widgets"],
+  [/^@carbon\/(react|icons-react)/, "Carbon React", "the SDK's widgets on a Carbon theme"],
+  [/^@fluentui\//, "Fluent UI", "the SDK's widgets on a Fluent theme"],
+  [/^@mantine\//, "Mantine", "the SDK's widgets"],
+  [/^react-bootstrap(\/|$)|^bootstrap(\/|$)/, "Bootstrap", "the SDK's widgets"],
+  [/^@blueprintjs\//, "Blueprint", "the SDK's widgets"],
+  [/^primereact(\/|$)/, "PrimeReact", "the SDK's widgets"],
+  [/^@radix-ui\/themes/, "Radix Themes", "the SDK's widgets"],
+  [/^lucide-react|^react-icons(\/|$)|^@heroicons\/|^@phosphor-icons\/|^@tabler\/icons|^@fortawesome\//, "an icon set", "<Icon> with @ux-builder/ui/icons, which follows the theme's icon set"],
+  [/^react-spinners|^react-loader-spinner|^react-loading-skeleton/, "a loader library", "the SDK's loading widgets"],
+];
+const foreign = {
+  meta: {
+    type: "suggestion",
+    docs: { description: "Report imports of other UI kits and icon sets; use @ux-builder/ui" },
+    schema: [{ type: "object", properties: { allow: { type: "array", items: { type: "string" } } }, additionalProperties: false }],
+  },
+  create(context) {
+    const allow = new Set(context.options[0]?.allow ?? []);
+    const check = (node, source) => {
+      if (typeof source !== "string" || allow.has(source)) return;
+      const hit = FOREIGN.find(([re]) => re.test(source));
+      if (hit) context.report({ node, message: `"${source}" is ${hit[1] === "an icon set" || hit[1] === "a loader library" ? hit[1] : `from ${hit[1]}`}, which does not follow the theme: use ${hit[2]} (ux-builder/no-foreign-ui)` });
+    };
+    return {
+      ImportDeclaration: (n) => check(n, n.source.value),
+      ImportExpression: (n) => check(n, n.source.value),
+      CallExpression: (n) => { if (n.callee.name === "require" && n.arguments[0]?.type === "Literal") check(n, n.arguments[0].value); },
+    };
+  },
+};
+
+/* ux-builder/no-inline-svg: an <svg> written in app JSX is an icon or a loader
+   drawn by hand, which keeps its shape whatever the theme's design system.
+   Use <Icon> (any of @ux-builder/ui/icons, or registerIcons for the app's own
+   drawing) or the loading widgets. Charts and illustrations can opt out with
+   allow: ["chart"] matching a className or id on the <svg>. */
+const inlineSvg = {
+  meta: {
+    type: "suggestion",
+    docs: { description: "Report hand-drawn <svg> in JSX; use <Icon> or registerIcons" },
+    schema: [{ type: "object", properties: { allow: { type: "array", items: { type: "string" } } }, additionalProperties: false }],
+  },
+  create(context) {
+    const allow = context.options[0]?.allow ?? [];
+    const attr = (el, name) => el.attributes.find((a) => a.name?.name === name)?.value?.value;
+    return {
+      JSXOpeningElement(el) {
+        if (el.name.type !== "JSXIdentifier" || el.name.name !== "svg") return;
+        const ids = `${attr(el, "className") ?? ""} ${attr(el, "id") ?? ""}`;
+        if (allow.some((a) => ids.split(/\s+/).includes(a))) return;
+        context.report({ node: el, message: "a hand-drawn <svg> does not follow the theme's icon set: use <Icon> (import it from @ux-builder/ui/icons, or registerIcons({ name, glyphs }) for your own drawing) (ux-builder/no-inline-svg)" });
+      },
+    };
+  },
+};
+
+export default { meta: { name: "@ux-builder/ui/eslint" }, rules: { "no-hard-coded-values": rule, "no-foreign-ui": foreign, "no-inline-svg": inlineSvg } };

package/lint/stylelint.mjs

@@ -0,0 +1,35 @@
+/* ux-builder/no-hard-coded-values for stylelint (FEAT-004 SDK-10, SDK-11).
+
+     // .stylelintrc.json
+     { "plugins": ["@ux-builder/ui/stylelint"],
+       "rules": { "ux-builder/no-hard-coded-values": [true, {
+         "theme": "databricks",                      // suggest that theme's role tokens
+         "allow": [{ "value": "#4E79A7", "file": "src/charts/**", "reason": "chart series" }]
+       }] } }
+
+   `true` alone reports without suggestions. Every allow entry needs a reason. */
+
+import stylelint from "stylelint";
+import { RULE, check, checkAllow, loadTokens } from "./core.mjs";
+
+const { createPlugin, utils } = stylelint;
+const isObject = (v) => v && typeof v === "object" && !Array.isArray(v);
+
+const rule = (primary, secondary = {}) => (root, result) => {
+  const valid = utils.validateOptions(result, RULE, { actual: primary, possible: [true, false] }, { actual: secondary, possible: (v) => isObject(v), optional: true });
+  if (!valid || !primary) return;
+  for (const e of checkAllow(secondary.allow ?? [])) utils.report({ ruleName: RULE, result, node: root, message: `${e} (${RULE})` });
+  const tokens = loadTokens(secondary.theme, "light", result.opts?.cwd ?? process.cwd());
+  const file = root.source?.input?.file;
+  root.walkDecls((decl) => {
+    const before = decl.prop.length + (decl.raws.between ?? ":").length;
+    for (const f of check(decl.prop, decl.value, { tokens, allow: secondary.allow ?? [], file })) {
+      utils.report({ ruleName: RULE, result, node: decl, message: f.message, index: before + f.index, endIndex: before + f.index + f.literal.length });
+    }
+  });
+};
+rule.ruleName = RULE;
+rule.messages = utils.ruleMessages(RULE, {});
+rule.meta = { url: "https://github.com/DocumentDrivenDX/ux-builder#lint" };
+
+export default createPlugin(RULE, rule);

package/package.json

@@ -1,6 +1,106 @@
 {
   "name": "@ux-builder/ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.6.1",
+  "license": "MIT OR Apache-2.0",
+  "description": "Widgets for the harness and embedded products: prefixed CSS and React 19 components on @ux-builder/tokens, shaped by whichever theme is on.",
+  "type": "module",
+  "files": [
+    "dist",
+    "licenses",
+    "lint",
+    "catalogue.json",
+    "AGENTS.md",
+    "skill",
+    "THIRD-PARTY-NOTICES.md"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./icons": "./dist/icons.js",
+    "./patterns": "./dist/patterns.js",
+    "./ui.css": "./dist/ui.css",
+    "./patterns.css": "./dist/patterns.css",
+    "./stylelint": "./lint/stylelint.mjs",
+    "./eslint": "./lint/eslint.mjs",
+    "./catalogue.json": "./catalogue.json",
+    "./AGENTS.md": "./AGENTS.md",
+    "./skill/*": "./skill/*",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "node scripts/gen-icons.mjs --library && vite build && cp src/ui.css dist/ui.css && cp src/patterns.css dist/patterns.css",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build -o storybook-static",
+    "test:storybook": "node --test 'test/storybook/*.test.mjs'",
+    "prepublishOnly": "npm run build",
+    "test": "node --test 'test/*.test.mjs'",
+    "icons": "node scripts/gen-icons.mjs"
+  },
+  "dependencies": {
+    "@ux-builder/tokens": "^1.5.0"
+  },
+  "peerDependencies": {
+    "eslint": ">=9",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "stylelint": ">=16"
+  },
+  "devDependencies": {
+    "@assistant-ui/react": "^0.15.29",
+    "@assistant-ui/react-markdown": "^0.14.23",
+    "@carbon/icons": "^11.89.0",
+    "@fluentui/svg-icons": "^1.1.343",
+    "@material-symbols/svg-400": "^0.47.6",
+    "@playwright/test": "~1.63.0",
+    "@radix-ui/react-use-controllable-state": "^1.3.0",
+    "@storybook/addon-a11y": "^10.6.1",
+    "@storybook/addon-docs": "^10.6.1",
+    "@storybook/react-vite": "^10.6.1",
+    "@tailwindcss/vite": "^4.3.3",
+    "@vitejs/plugin-react": "^6.1.1",
+    "ai": "^7.0.145",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cmdk": "^1.1.1",
+    "embla-carousel-react": "^8.6.0",
+    "eslint": "^10.12.0",
+    "happy-dom": "^20.14.5",
+    "lucide-react": "^1.59.0",
+    "lucide-static": "^1.52.0",
+    "motion": "^14.4.0",
+    "nanoid": "^3.3.19",
+    "radix-ui": "^1.8.1",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "remark-gfm": "^4.0.1",
+    "shiki": "^4.5.0",
+    "storybook": "^10.6.1",
+    "streamdown": "^2.7.1",
+    "stylelint": "^17.16.0",
+    "tailwind-merge": "^3.7.0",
+    "tailwindcss": "^4.3.3",
+    "tw-animate-css": "^1.4.0",
+    "tw-shimmer": "^0.4.14",
+    "use-stick-to-bottom": "^1.1.6",
+    "vite": "^8.3.2",
+    "zustand": "^5.0.15"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DocumentDrivenDX/ux-builder.git",
+    "directory": "packages/ui"
+  },
+  "peerDependenciesMeta": {
+    "stylelint": {
+      "optional": true
+    },
+    "eslint": {
+      "optional": true
+    }
+  },
+  "sideEffects": [
+    "*.css"
+  ]
+}