@botiverse/raft-ui 0.0.0-stage → 0.7.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Botiverse
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# raft-ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Raft Design System foundations for plain HTML, plus React components built with Base UI and Tailwind CSS v4.
+
+## React
+
+```tsx
+import { Button } from "@botiverse/raft-ui";
+```
+
+```css
+@import "tailwindcss";
+@import "@botiverse/raft-ui/styles.css";
+```
+
+## Plain HTML
+
+Link `dist/foundation.css` directly, or copy it beside your HTML. It exposes the same theme variables used by the components, without React, Tailwind, or a CSS reset.
+
+```html
+<link rel="stylesheet" href="./foundation.css" />
+<style>
+  body {
+    background: var(--layer-canvas);
+    color: var(--foreground);
+  }
+  article {
+    background: var(--layer-canvas);
+  }
+</style>
+```
+
+Put `class="light"` or `class="dark"` on the root to pick a mode; omit it to follow the system mode. Optional `fonts.css` loads web fonts and defines `--heading-font`, `--sans-font`, and `--mono-font`.
+
+`styles.css` remains the Tailwind integration entry and imports this foundation automatically.
+
+## Tokens
+
+`@botiverse/raft-ui/tokens.json` holds every token in the [Design Tokens Community Group format](https://www.designtokens.org/), with light and dark values, for design tools and code generators. `foundation.css` is generated from it.
+
+## Agent Skills
+
+raft-ui ships two version-matched Agent Skills in the npm package:
+
+- `raft-ui-guide` for adopting raft-ui, looking up its API, and where the design system's guidance is.
+- `raft-ui-critique` for visual, interaction, accessibility, and light/dark review.
+
+### TanStack Intent
+
+Allow raft-ui skills in the consuming project's `package.json`:
+
+```json
+{
+  "intent": {
+    "skills": ["@botiverse/raft-ui"]
+  }
+}
+```
+
+Install the project guidance, then inspect or load either skill:
+
+```bash
+pnpm dlx @tanstack/intent@latest install --map
+pnpm dlx @tanstack/intent@latest load @botiverse/raft-ui#raft-ui-guide
+pnpm dlx @tanstack/intent@latest load @botiverse/raft-ui#raft-ui-critique
+```
+
+### Other installers
+
+The package uses the standard `skills/*/SKILL.md` layout, so consumers can also use tools such as `skills-npm` or Vercel `skills`. Installer-specific destination names may add their own package namespace.
+
+## Development
+
+- Install dependencies:
+
+```bash
+vp install
+```
+
+- Build the library:
+
+```bash
+vp pack
+```
+
+## Upgrading from `raft-ui`
+
+The package was published as `raft-ui` up to 0.6.0. To move a project:
+
+```bash
+pnpm add @botiverse/raft-ui
+node node_modules/@botiverse/raft-ui/codemods/package-name.mjs src
+node node_modules/@botiverse/raft-ui/codemods/token-names.mjs src
+pnpm remove raft-ui
+```
+
+The first command rewrites imports, CSS `@import` and `@source` paths and the dependency, and lists any bare `"raft-ui"` strings (bundler aliases, path mappings) to change by hand. The second moves to the current token names; the former names keep working until 1.0.
+
+Review two kinds of code by hand after `token-names.mjs`:
+
+- **Guards that forbid a name.** A lint rule, a test or an allowlist that bans a former name (for example a `doesNotMatch(/text-foreground-strong/)`) has that name rewritten too, so it now bans the current one. Put the former name back there.
+- **Patterns built from parts.** A regex such as `/bg-brutal-[a-z]+/` is not a literal token, so it keeps the former name and stops matching the rewritten source. Widen it to the current name (`palette-`, `brand-`, `attention-`).
+
+If a package you depend on declares `raft-ui` as a peer dependency, also install `"raft-ui": "npm:@botiverse/raft-ui@<version>"` so it resolves to the same copy instead of bundling a second one.

package/codemods/package-name.mjs

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+// Moves a project from the unscoped `raft-ui` package to `@botiverse/raft-ui`.
+//
+//   pnpm add @botiverse/raft-ui      # or npm install, yarn add
+//   node node_modules/@botiverse/raft-ui/codemods/package-name.mjs <dir>... [--version 0.7.0] [--dry]
+//
+// Rewrites import and require specifiers, CSS `@import` / `@source` /
+// `@reference` paths, `node_modules/raft-ui` paths, and the `raft-ui`
+// dependency in package.json files (to `--version`, default the version of the
+// package this script ships in). It lists, without changing, any other place
+// that names the bare string "raft-ui" (a bundler alias, a tsconfig path), so
+// you can check those by hand. Run `token-names.mjs` afterwards to move to the
+// current token names.
+import { readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const NEW = "@botiverse/raft-ui";
+const SOURCE = new Set([
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".mts",
+  ".cts",
+  ".css",
+  ".html",
+  ".vue",
+  ".svelte",
+]);
+const SKIP = new Set(["node_modules", "dist", "build", ".git", ".next", ".turbo", "coverage"]);
+
+const RULES = [
+  // `(?<!@)import`: a CSS `@import` is the next rule's, not a JS import.
+  [/(from\s+|import\(\s*|require\(\s*|(?<!@)import\s+)(["'])raft-ui(?=["'/])/g, `$1$2${NEW}`],
+  [
+    /(@import|@source|@reference|@plugin)(\s+(?:url\()?["'])([^"']*?)(?<![\w@/-])raft-ui(?=["'/])/g,
+    `$1$2$3${NEW}`,
+  ],
+  [/node_modules\/raft-ui(?=["'/\s)])/g, `node_modules/${NEW}`],
+];
+
+/** Whether `index` in `line` sits inside a JavaScript regex literal (`/…from "raft-ui"…/`). */
+function insideRegexLiteral(line, index) {
+  const before = line.slice(0, index);
+  const opener = /(?:^|[(,=:[!&|?{};])\s*\/(?![/*])/g;
+  let start = -1;
+  for (const match of before.matchAll(opener)) start = match.index + match[0].length;
+  if (start < 0) return false;
+  // Closed again before the match: an unescaped `/` after the opener.
+  return !/(?<!\\)\//.test(before.slice(start));
+}
+
+export function renameSpecifiers(source) {
+  return source
+    .split("\n")
+    .map((line) => {
+      let out = line;
+      for (const [pattern, replacement] of RULES) {
+        out = out.replace(pattern, (...args) => {
+          const offset = args.at(-2);
+          const groups = args.slice(1, -2);
+          const replaced = replacement.replace(/\$(\d)/g, (_, n) => groups[Number(n) - 1] ?? "");
+          // A slash in a regex literal ends it: write `@botiverse\/raft-ui` there.
+          return insideRegexLiteral(out, offset)
+            ? replaced.replace(NEW, NEW.replace("/", "\\/"))
+            : replaced;
+        });
+      }
+      return out;
+    })
+    .join("\n");
+}
+
+export function renameDependency(json, version) {
+  let changed = false;
+  for (const field of [
+    "dependencies",
+    "devDependencies",
+    "peerDependencies",
+    "optionalDependencies",
+  ]) {
+    const deps = json[field];
+    // `"raft-ui": "npm:@botiverse/raft-ui@…"` is an alias kept on purpose, for a dependency
+    // that peers on the unscoped name: leave it.
+    if (!deps || !("raft-ui" in deps) || deps["raft-ui"].startsWith(`npm:${NEW}@`)) continue;
+    const next = {};
+    for (const [name, range] of Object.entries(deps)) {
+      if (name === "raft-ui")
+        next[NEW] = range.startsWith("workspace:") || range.startsWith("link:") ? range : version;
+      else next[name] = range;
+    }
+    json[field] = next;
+    changed = true;
+  }
+  return changed;
+}
+
+function* walk(target) {
+  const stat = statSync(target);
+  if (stat.isFile()) {
+    yield target;
+    return;
+  }
+  for (const name of readdirSync(target)) {
+    if (SKIP.has(name)) continue;
+    yield* walk(path.join(target, name));
+  }
+}
+
+function main(argv) {
+  const dry = argv.includes("--dry");
+  const versionIndex = argv.indexOf("--version");
+  const ownPackage = JSON.parse(
+    readFileSync(
+      path.join(path.dirname(fileURLToPath(import.meta.url)), "../package.json"),
+      "utf8",
+    ),
+  );
+  const version = versionIndex >= 0 ? argv[versionIndex + 1] : ownPackage.version;
+  const targets = argv.filter(
+    (arg, index) => !arg.startsWith("--") && argv[index - 1] !== "--version",
+  );
+  if (targets.length === 0) {
+    console.error("usage: package-name.mjs <dir>... [--version x.y.z] [--dry]");
+    process.exit(1);
+  }
+  let changed = 0;
+  const review = [];
+  for (const target of targets) {
+    for (const file of walk(target)) {
+      const base = path.basename(file);
+      const before = readFileSync(file, "utf8");
+      let after = before;
+      if (base === "package.json") {
+        const json = JSON.parse(before);
+        if (renameDependency(json, version)) after = `${JSON.stringify(json, null, 2)}\n`;
+      } else if (SOURCE.has(path.extname(file))) {
+        after = renameSpecifiers(before);
+      } else continue;
+      if (after !== before) {
+        changed += 1;
+        console.log(`${dry ? "would update" : "updated"} ${file}`);
+        if (!dry) writeFileSync(file, after);
+      }
+      after.split("\n").forEach((line, index) => {
+        // A bare "raft-ui" or "raft-ui/<subpath>" string left over: an alias key, a dedupe list,
+        // require.resolve, a path mapping.
+        if (/(?<![\w@/-])["']raft-ui(?:\/[^"']*)?["']/.test(line) && base !== "package.json") {
+          review.push(`${file}:${index + 1}: ${line.trim()}`);
+        }
+      });
+    }
+  }
+  console.log(`${changed} file${changed === 1 ? "" : "s"} ${dry ? "to update" : "updated"}`);
+  if (review.length) {
+    console.log(
+      `\nCheck these by hand (a bare "raft-ui" string, such as an alias or a path mapping):`,
+    );
+    for (const line of review) console.log(`  ${line}`);
+  }
+  if (!dry && changed)
+    console.log("\nNext: install dependencies, then run token-names.mjs on the same directories.");
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) main(process.argv.slice(2));

package/codemods/token-names.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+// Renames raft-ui tokens to the names the Raft Design System docs use.
+//
+//   node node_modules/@botiverse/raft-ui/codemods/token-names.mjs <dir-or-file>... [--dry]
+//
+// Rewrites Tailwind utilities (`bg-layer-panel`, `hover:border-line-muted/50`)
+// and CSS custom properties (`var(--primary-soft)`) in .ts, .tsx, .js, .jsx,
+// .mjs, .css and .html files. The old names keep working as deprecated aliases
+// until raft-ui 1.0, so the rewrite can land at any time after upgrading.
+//
+// Review by hand afterwards: a guard that forbids a former name (a lint rule,
+// a test's doesNotMatch, an allowlist) now forbids the current one, and a
+// pattern built from parts (/bg-brutal-[a-z]+/) keeps the former name.
+import { readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+/** Old token name -> new token name. Used for both utilities and `--` properties. */
+export const TOKEN_RENAMES = {
+  "layer-panel": "layer-canvas",
+  "layer-inset": "fill-muted",
+  "layer-canvas-muted": "layer-sidebar",
+  "foreground-strong": "foreground",
+  "foreground-icon": "foreground-muted",
+  "foreground-placeholder": "foreground-hint",
+  "layer-hud-foreground": "foreground-on-hud",
+  "line-muted": "line-hairline",
+  line: "line-seam",
+  "theme-shadow-float": "elevation-float",
+  "theme-shadow-lg": "elevation-float",
+  "theme-shadow-xl": "elevation-float",
+  "theme-shadow-sticker": "elevation-sticker",
+  "theme-focus-ring": "focus-ring",
+  "soft-signal": "palette-yellow",
+};
+
+/** Families renamed with every step: `primary-soft` -> `brand-soft`. */
+export const FAMILY_RENAMES = {
+  primary: "brand",
+  accent: "attention",
+};
+
+/** The brand palette loses the name of a theme family that no longer exists. */
+export const PALETTE_COLORS = {
+  yellow: "yellow",
+  pink: "pink",
+  cyan: "cyan",
+  lime: "lime",
+  orange: "orange",
+  red: "red",
+  purple: "lavender",
+  lavender: "lavender",
+  stone: "stone",
+  cream: "cream",
+};
+
+/** Shadow utilities, which are named apart from their properties. */
+export const UTILITY_RENAMES = {
+  "shadow-raft-float": "shadow-float",
+  "shadow-raft-lg": "shadow-float",
+  "shadow-raft-xl": "shadow-float",
+  "shadow-raft-sticker": "shadow-sticker",
+  "shadow-raft-focus": "shadow-focus",
+};
+
+const COLOR_UTILITY =
+  "(?:bg|text|border(?:-[trblxyse])?|ring|ring-offset|inset-ring|outline|fill|stroke|divide|from|via|to|shadow|inset-shadow|decoration|caret|accent|placeholder)";
+const END = "(?![\\w-])";
+// A custom property, not a BEM modifier: `var(--primary-soft)` but not `.r-button--primary`.
+const VAR = "(?<![\\w-])--";
+// A reference, not a declaration: `var(--line)` is renamed, `--line: …` is left alone,
+// so the deprecated aliases (`--line: var(--line-seam)`) survive a rerun.
+const REF_END = "(?![\\w-])(?!\\s*:)";
+const escape = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+function rules() {
+  const list = [];
+  for (const [from, to] of Object.entries(UTILITY_RENAMES)) {
+    list.push([new RegExp(`(?<![\\w-])${escape(from)}${END}`, "g"), to]);
+  }
+  // Longer names first, so `line-muted` is handled before `line`.
+  const tokens = Object.entries(TOKEN_RENAMES).sort(([a], [b]) => b.length - a.length);
+  for (const [from, to] of tokens) {
+    list.push([new RegExp(`(?<![\\w-])(${COLOR_UTILITY})-${escape(from)}${END}`, "g"), `$1-${to}`]);
+    list.push([new RegExp(`${VAR}${escape(from)}${REF_END}`, "g"), `--${to}`]);
+  }
+  for (const [from, to] of Object.entries(FAMILY_RENAMES)) {
+    list.push([
+      new RegExp(`(?<![\\w-])(${COLOR_UTILITY})-${from}((?:-[a-z0-9]+)*)${END}`, "g"),
+      `$1-${to}$2`,
+    ]);
+    list.push([new RegExp(`${VAR}${from}((?:-[a-z0-9]+)*)${REF_END}`, "g"), `--${to}$1`]);
+  }
+  for (const [from, to] of Object.entries(PALETTE_COLORS)) {
+    list.push([
+      new RegExp(`${VAR}color-brutal-${from}-(\\d+)${REF_END}`, "g"),
+      `--palette-${to}-$1`,
+    ]);
+    list.push([new RegExp(`${VAR}color-brutal-${from}${REF_END}`, "g"), `--color-palette-${to}`]);
+    list.push([
+      new RegExp(`(?<![\\w-])(${COLOR_UTILITY})-brutal-${from}${END}`, "g"),
+      `$1-palette-${to}`,
+    ]);
+  }
+  list.push([new RegExp(`${VAR}color-soft-signal${REF_END}`, "g"), "--color-palette-yellow"]);
+  return list;
+}
+
+export function renameTokens(source) {
+  let out = source;
+  for (const [pattern, replacement] of rules()) out = out.replace(pattern, replacement);
+  return out;
+}
+
+const EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".css", ".html"]);
+const SKIP = new Set(["node_modules", "dist", "build", ".git"]);
+
+function* walk(target) {
+  const stat = statSync(target);
+  if (stat.isFile()) {
+    if (EXTENSIONS.has(path.extname(target))) yield target;
+    return;
+  }
+  for (const name of readdirSync(target)) {
+    if (SKIP.has(name) || name.startsWith(".")) continue;
+    yield* walk(path.join(target, name));
+  }
+}
+
+function main(argv) {
+  const dry = argv.includes("--dry");
+  const targets = argv.filter((arg) => !arg.startsWith("--"));
+  if (targets.length === 0) {
+    console.error("usage: token-names.mjs <dir-or-file>... [--dry]");
+    process.exit(1);
+  }
+  let changed = 0;
+  for (const target of targets) {
+    for (const file of walk(target)) {
+      const before = readFileSync(file, "utf8");
+      const after = renameTokens(before);
+      if (after === before) continue;
+      changed += 1;
+      console.log(`${dry ? "would update" : "updated"} ${file}`);
+      if (!dry) writeFileSync(file, after);
+    }
+  }
+  console.log(`${changed} file${changed === 1 ? "" : "s"} ${dry ? "to update" : "updated"}`);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) main(process.argv.slice(2));

package/dist/cn.d.mts

@@ -0,0 +1,5 @@
+import { ClassValue } from "cnfast";
+//#region src/lib/cn.d.ts
+export declare function cn(...inputs: ClassValue[]): string;
+//#endregion
+export type { ClassValue };

package/dist/cn.mjs

@@ -0,0 +1,48 @@
+import { clsx } from "cnfast";
+import { extendTailwindMerge } from "tailwind-merge";
+//#region src/lib/cn.ts
+const twMerge = extendTailwindMerge({ extend: { classGroups: {
+	shadow: [{ shadow: [
+		"float",
+		"sticker",
+		"focus"
+	] }, { shadow: [{ raft: [
+		"xs",
+		"sm",
+		"md",
+		"lg",
+		"xl",
+		"float",
+		"sticker",
+		"focus"
+	] }] }],
+	rounded: [{ rounded: [
+		"sticker",
+		"chip",
+		"control",
+		"container",
+		"dialog"
+	] }],
+	"font-size": [{ text: [
+		"field",
+		"card-title",
+		"hero",
+		"display",
+		"title",
+		"headline",
+		"body",
+		"subhead",
+		"callout",
+		"footnote",
+		"caption",
+		"label",
+		"mono-meta",
+		"mono-code"
+	] }],
+	"font-weight": [{ font: ["field", "card-title"] }]
+} } });
+function cn(...inputs) {
+	return twMerge(clsx(inputs));
+}
+//#endregion
+export { cn };