@nebutra/theme 0.1.1 → 0.2.0

package/README.md

@@ -1,46 +1,92 @@
 # @nebutra/theme
 
-CSS-only theme engine for Nebutra — Tailwind v4 `@theme` tokens, `data-theme` selectors, and a `next-themes` re-export.
+**Design-language catalog** for global product chrome swap (Create Center / multi-tenant SaaS).
 
-## Design Intent
+## What this is
 
-All visual theming in Nebutra is expressed as CSS custom properties scoped to `[data-theme="<id>"]` selectors defined in `themes.css`. There is no JavaScript theme object or runtime style computation. The `data-theme` attribute is toggled by `next-themes` (re-exported here as `ThemeProvider` and `useTheme`), making the theme system framework-agnostic at the CSS layer while remaining ergonomic in React apps.
+| Layer | Package | Role |
+|-------|---------|------|
+| Product SSOT | `@nebutra/tokens` | `styles.css` + `recipe.css` |
+| **Language swap** | **`@nebutra/theme`** | Brand Packages + `applyLanguage` + `skins.css` |
+| Components | `@nebutra/ui` | `--primary`, `--brand-mark`, `--elevation-*` |
 
-Apps import a single CSS file and a single provider — no per-component theme wiring required.
+A **design language** is a full Brand Package (roles + recipe + free elevation + zones + fonts).
 
-## Registry Contract
+> **Removed (2026.07):** 78 oklch “mood” presets under `[data-theme]`. They dual-wrote product chrome, looked generic, and fought the carrier model. Do not reintroduce them.
 
-Theme metadata is governed by `src/registry.json` and exported from `@nebutra/theme/registry`.
-Do not add new hard-coded theme arrays in apps, presets, docs, or CLI commands.
+## Quick start
 
-The registry is consumed by:
+```css
+@import "@nebutra/tokens/styles.css";
+@import "@nebutra/tokens/recipe.css";
+@import "@nebutra/theme/skins.css"; /* multi-language, scoped to html[data-brand] */
+```
 
-- `@nebutra/design-tokens` build output (`themes.css`)
-- `@nebutra/preset` config validation
-- `nebutra theme list` and `nebutra theme inspect <id>`
-- future Figma/theme-playground publishing surfaces
+```ts
+// Client-safe root (or `@nebutra/theme/client`)
+import { applyLanguage, clearLanguage, LANGUAGE_REGISTRY } from "@nebutra/theme";
 
-Each built-in theme must declare token path, install command, compatibility flags, WCAG target, required token coverage, and visual regression suites.
+applyLanguage("vanta", { persist: true }); // built-in Brand Package
+clearLanguage(); // factory
 
-## Usage
+// Compile / Create Center tooling — not on package root:
+// import { compileReferoTokens } from "@nebutra/tokens/brand-package";
+// import { compileReferoTokens } from "@nebutra/theme/brand-package";
+```
 
-```tsx
-// In your root layout
-import { ThemeProvider } from "@nebutra/theme";
-import "@nebutra/theme/themes.css";
+```bash
+nebutra theme list
+nebutra theme inspect vanta
+```
 
-<ThemeProvider attribute="data-theme" defaultTheme="neon">
-  {children}
-</ThemeProvider>
+## Catalog generation
+
+| File | Role |
+|------|------|
+| `tokens/brands/<id>/brand.json` | Package SSOT (roles, recipe, zones) |
+| `src/languages.meta.json` | Catalog copy: description + proves |
+| `src/languages.json` | **Generated** by `pnpm sync:languages` |
+| `src/built-in-packages.generated.ts` | **Generated** runtime map for `applyLanguage(id)` |
+| `skins.css` | **Generated** by `pnpm sync:skins` |
+| `keyframes.css` | Shared animations (prefer over deprecated `themes.css`) |
+
+```bash
+pnpm --filter @nebutra/theme sync:languages
+pnpm --filter @nebutra/tokens emit-skins
+pnpm --filter @nebutra/theme sync:skins
 ```
 
-## Available Themes
+## Catalog
 
-`neon` | `gradient` | `dark-dense` | `minimal` | `vibrant` | `ocean`
+| id | Proves |
+|----|--------|
+| factory | Default tokens SSOT |
+| linear | Chromatic solid CTA + dual-mode dark/light |
+| gsap | gradient-stroke / outline + zones |
+| raycast | action ≠ brand-mark + elev=key |
+| vercel | Light mono + elev=hairline + dual-mode palettes |
+| vanta | Chromatic action≠brand + elev=none + pills |
+| stripe | Indigo action ≠ midnight brand + elev=none + 4px |
+| notion | Blue action ≠ ink brand + paper canvas + 8/12 radii |
 
-The `THEME_IDS` constant and `ThemeId` type are exported for use in theme switcher components.
+## Dual-mode stress fixtures
 
-```bash
-nebutra theme list --format json
-nebutra theme inspect neon --format json
+Brand packages with `modes.light` + `modes.dark` (today: **linear**, **vercel**)
+emit separate selector blocks so light paint never lands under bare `.dark`:
+
+- light → `:root, html[data-brand="…"]`
+- dark → `.dark, html.dark[data-brand="…"]`
+
+Coverage: `src/__tests__/apply-language.test.ts` (runtime apply) and
+`@nebutra/tokens` `emit-css.test.ts` (compiler). When adding a dual-mode
+language, extend both fixtures.
+
+## `keyframes.css`
+
+Shared keyframe animations only. Prefer:
+
+```css
+@import "@nebutra/theme/keyframes.css";
 ```
+
+`themes.css` remains a **deprecated alias** that re-exports keyframes (no color moods).

package/keyframes.css

@@ -0,0 +1,147 @@
+/**
+ * @nebutra/theme — keyframes.css (via themes.generated.css)
+ * AUTO-GENERATED — multi-mood oklch catalog removed.
+ * Product chrome SSOT: @nebutra/tokens. Design languages: @nebutra/theme/skins.css.
+ * This file: shared keyframes only.
+ */
+
+/* ─── Shared Keyframe Animations ─── */
+/*
+ * These keyframes are shared across all apps that import this file.
+ * App-specific keyframes (marquee, shimmer-slide, accordion, etc.) stay in each app's globals.css.
+ */
+
+@theme inline {
+  /* Loader / status animations */
+  @keyframes typing {
+    0%,
+    100% {
+      transform: translateY(0);
+      opacity: 0.5;
+    }
+    50% {
+      transform: translateY(-2px);
+      opacity: 1;
+    }
+  }
+  @keyframes loading-dots {
+    0%,
+    100% {
+      opacity: 0;
+    }
+    50% {
+      opacity: 1;
+    }
+  }
+  @keyframes wave {
+    0%,
+    100% {
+      transform: scaleY(1);
+    }
+    50% {
+      transform: scaleY(0.6);
+    }
+  }
+  @keyframes blink {
+    0%,
+    100% {
+      opacity: 1;
+    }
+    50% {
+      opacity: 0;
+    }
+  }
+  @keyframes text-blink {
+    0%,
+    100% {
+      color: var(--color-primary);
+    }
+    50% {
+      color: var(--color-muted-foreground);
+    }
+  }
+  @keyframes bounce-dots {
+    0%,
+    100% {
+      transform: scale(0.8);
+      opacity: 0.5;
+    }
+    50% {
+      transform: scale(1.2);
+      opacity: 1;
+    }
+  }
+  @keyframes thin-pulse {
+    0%,
+    100% {
+      transform: scale(0.95);
+      opacity: 0.8;
+    }
+    50% {
+      transform: scale(1.05);
+      opacity: 0.4;
+    }
+  }
+  @keyframes pulse-dot {
+    0%,
+    100% {
+      transform: scale(1);
+      opacity: 0.8;
+    }
+    50% {
+      transform: scale(1.5);
+      opacity: 1;
+    }
+  }
+  @keyframes wave-bars {
+    0%,
+    100% {
+      transform: scaleY(1);
+      opacity: 0.5;
+    }
+    50% {
+      transform: scaleY(0.6);
+      opacity: 1;
+    }
+  }
+  @keyframes shimmer {
+    0% {
+      background-position: 200% 50%;
+    }
+    100% {
+      background-position: -200% 50%;
+    }
+  }
+  @keyframes spinner-fade {
+    0% {
+      opacity: 0;
+    }
+    100% {
+      opacity: 1;
+    }
+  }
+
+  /* SnippetStatus copy animations */
+  @keyframes snippet-fade-in {
+    from {
+      opacity: 0;
+      transform: scale(0.5);
+    }
+    to {
+      opacity: 1;
+      transform: scale(1);
+    }
+  }
+  @keyframes snippet-fade-out {
+    from {
+      opacity: 1;
+      transform: scale(1);
+    }
+    to {
+      opacity: 0;
+      transform: scale(0.5);
+    }
+  }
+  --animate-snippet-fade-in: snippet-fade-in 0.2s ease-out forwards;
+  --animate-snippet-fade-out: snippet-fade-out 0.2s ease-out forwards;
+}

package/package.json

@@ -1,23 +1,33 @@
 {
   "name": "@nebutra/theme",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
-  "description": "CSS-only theme engine — Tailwind v4 @theme tokens + data-theme selectors + next-themes re-export",
+  "description": "Design-language catalog for global product chrome swap (Brand Packages). Multi-mood oklch catalog removed.",
   "private": false,
   "license": "MIT",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
+  "sideEffects": [
+    "./keyframes.css",
+    "./themes.css",
+    "./skins.css"
+  ],
   "exports": {
     ".": "./src/index.ts",
-    "./registry": "./src/registry.ts",
-    "./registry.json": "./src/registry.json",
-    "./themes.css": "./themes.css"
+    "./client": "./src/client.ts",
+    "./languages": "./src/languages.ts",
+    "./languages.json": "./src/languages.json",
+    "./brand-package": "./src/brand-package-surface.ts",
+    "./keyframes.css": "./keyframes.css",
+    "./themes.css": "./themes.css",
+    "./skins.css": "./skins.css"
   },
   "dependencies": {
-    "next-themes": "^0.4.6"
+    "@nebutra/tokens": "0.1.1"
   },
   "devDependencies": {
     "@types/react": "^19.2.14",
+    "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.1.4"
   },
@@ -37,9 +47,10 @@
     "access": "public"
   },
   "scripts": {
-    "prebuild": "corepack pnpm --filter @nebutra/design-tokens build",
-    "build": "node -e \"require('node:fs').copyFileSync('../design-tokens/build/css/themes.generated.css', './themes.css'); console.log('themes.css regenerated from @nebutra/design-tokens')\"",
-    "sync": "corepack pnpm --filter @nebutra/design-tokens build && node -e \"require('node:fs').copyFileSync('../design-tokens/build/css/themes.generated.css', './themes.css')\"",
+    "build": "node scripts/sync-languages.mjs && node ../tokens/scripts/emit-skins.mjs && node scripts/sync-skins.mjs",
+    "sync": "node scripts/sync-languages.mjs && node scripts/sync-skins.mjs",
+    "sync:languages": "node scripts/sync-languages.mjs",
+    "sync:skins": "node scripts/sync-skins.mjs",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   }

package/scripts/sync-languages.mjs

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+/**
+ * Generate design-language catalog artifacts from brands + meta.
+ *
+ * SSOT package data: packages/design/tokens/brands/<id>/brand.json
+ * SSOT catalog copy: packages/design/theme/src/languages.meta.json
+ *
+ * Generated (DO NOT hand-edit):
+ *   - src/languages.json
+ *   - src/built-in-packages.generated.ts
+ *
+ * Usage: node scripts/sync-languages.mjs
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const repoRoot = resolve(packageRoot, "../../..");
+const tokensRoot = resolve(packageRoot, "..", "tokens");
+const brandsDir = join(tokensRoot, "brands");
+const metaPath = join(packageRoot, "src", "languages.meta.json");
+const languagesOut = join(packageRoot, "src", "languages.json");
+const builtInOut = join(packageRoot, "src", "built-in-packages.generated.ts");
+const biomeBin = join(repoRoot, "node_modules/.bin/biome");
+
+if (!existsSync(metaPath)) {
+  throw new Error(`Missing ${metaPath}`);
+}
+if (!existsSync(brandsDir)) {
+  throw new Error(`Missing brands dir ${brandsDir}`);
+}
+
+const meta = JSON.parse(readFileSync(metaPath, "utf8"));
+const compatibility = {
+  tailwind: "4",
+  cssVariables: true,
+  brandPackage: true,
+  dataBrand: true,
+};
+
+const factoryMeta = meta.factory ?? {};
+const languages = [
+  {
+    id: "factory",
+    name: factoryMeta.name ?? "Nebutra Factory",
+    kind: "design-language",
+    description: factoryMeta.description ?? "Default product chrome (no skin).",
+    proves: factoryMeta.proves ?? [],
+    darkDefault: factoryMeta.darkDefault ?? true,
+    brandPath: null,
+    skinPath: null,
+    install: {
+      command: "nebutra theme use factory",
+      cssImport: null,
+    },
+    compatibility,
+  },
+];
+
+const brandIds = readdirSync(brandsDir, { withFileTypes: true })
+  .filter((d) => d.isDirectory())
+  .map((d) => d.name)
+  .sort();
+
+const langMeta = meta.languages ?? {};
+const missingMeta = [];
+
+for (const id of brandIds) {
+  const brandPath = join(brandsDir, id, "brand.json");
+  if (!existsSync(brandPath)) {
+    process.stderr.write(`warn: brands/${id} has no brand.json — skip\n`);
+    continue;
+  }
+  const brand = JSON.parse(readFileSync(brandPath, "utf8"));
+  const entryMeta = langMeta[id];
+  if (!entryMeta) {
+    missingMeta.push(id);
+  }
+  languages.push({
+    id: brand.id || id,
+    name: brand.name || id,
+    kind: "design-language",
+    description: entryMeta?.description ?? `${brand.name || id} design language.`,
+    proves: entryMeta?.proves ?? [],
+    darkDefault: Boolean(brand.darkDefault),
+    brandPath: `brands/${id}/brand.json`,
+    skinPath: `skins/${id}.css`,
+    install: {
+      command: `nebutra theme use ${id}`,
+      cssImport: `@nebutra/tokens/skins/${id}.css`,
+    },
+    compatibility,
+  });
+}
+
+if (missingMeta.length > 0) {
+  process.stderr.write(
+    `warn: languages.meta.json missing entries for: ${missingMeta.join(", ")}\n` +
+      `  (generated with fallback description; add proves/description to meta)\n`,
+  );
+}
+
+const orphanMeta = Object.keys(langMeta).filter((id) => !brandIds.includes(id));
+if (orphanMeta.length > 0) {
+  process.stderr.write(
+    `warn: languages.meta.json has unused keys (no brands/<id>): ${orphanMeta.join(", ")}\n`,
+  );
+}
+
+const registry = {
+  $schema: "https://nebutra.com/schemas/design-language-registry.json",
+  version: meta.version ?? "2026.07",
+  defaultLanguage: meta.defaultLanguage ?? "factory",
+  description:
+    meta.description ?? "Design-language catalog for global product chrome swap (Brand Packages).",
+  languages,
+};
+
+writeFileSync(languagesOut, `${JSON.stringify(registry, null, 2)}\n`);
+
+// ── built-in-packages.generated.ts ───────────────────────────────────────────
+const importLines = brandIds.map(
+  (id) =>
+    `import ${safeIdent(id)} from "@nebutra/tokens/brands/${id}/brand.json" with { type: "json" };`,
+);
+const mapEntries = brandIds.map(
+  (id) => `  ${JSON.stringify(id)}: ${safeIdent(id)} as BrandPackage,`,
+);
+
+const builtInTs = `/**
+ * AUTO-GENERATED by scripts/sync-languages.mjs — DO NOT EDIT.
+ * Built-in Brand Packages for applyLanguage(id) without manual JSON import.
+ * Source: packages/design/tokens/brands/<id>/brand.json
+ */
+
+import {
+  type BrandPackage,
+  normalizeBrandPackage,
+} from "@nebutra/tokens/brand-package";
+${importLines.join("\n")}
+
+const RAW_BUILT_IN: Record<string, BrandPackage> = {
+${mapEntries.join("\n")}
+};
+
+/** Normalized package for a shipped design-language id, or undefined. */
+export function getBuiltInBrandPackage(id: string): BrandPackage | undefined {
+  const raw = RAW_BUILT_IN[id];
+  if (!raw) return undefined;
+  return normalizeBrandPackage({ ...raw, id });
+}
+
+export function listBuiltInBrandIds(): string[] {
+  return Object.keys(RAW_BUILT_IN);
+}
+
+export function hasBuiltInBrandPackage(id: string): boolean {
+  return id in RAW_BUILT_IN;
+}
+`;
+
+writeFileSync(builtInOut, builtInTs);
+
+// Biome format so CI governance (full-tree biome check after typecheck/build)
+// does not fail on JSON.stringify / multi-line import formatting drift.
+if (existsSync(biomeBin)) {
+  const fmt = spawnSync(biomeBin, ["format", "--write", languagesOut, builtInOut], {
+    cwd: repoRoot,
+    encoding: "utf8",
+  });
+  if (fmt.status !== 0) {
+    process.stderr.write(fmt.stderr || fmt.stdout || "biome format failed on language artifacts\n");
+    process.exit(fmt.status ?? 1);
+  }
+}
+
+process.stdout.write(
+  `sync-languages:\n` +
+    `  languages.json: ${languages.length} languages (${brandIds.length} skins + factory)\n` +
+    `  built-in-packages.generated.ts: ${brandIds.length} packages\n`,
+);
+
+/** Valid JS identifier from brand id (kebab → camel if needed; most ids are single words). */
+function safeIdent(id) {
+  if (/^[a-zA-Z_$][\w$]*$/.test(id)) return id;
+  return id.replace(/[^a-zA-Z0-9_$]/g, "_").replace(/^(\d)/, "_$1");
+}

package/scripts/sync-skins.mjs

@@ -0,0 +1,83 @@
+/**
+ * Build skins.css — multi-language catalog for html[data-brand] switching.
+ *
+ * Reads tokens/skins/*.css (global emit), rewrites selectors to scoped-only,
+ * concatenates into packages/design/theme/skins.css.
+ *
+ * Product chrome SSOT remains tokens/styles.css; this file never paints :root alone.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const repoRoot = resolve(packageRoot, "../../..");
+const tokensRoot = resolve(packageRoot, "..", "tokens");
+const skinsDir = join(tokensRoot, "skins");
+const outPath = join(packageRoot, "skins.css");
+const biomeBin = join(repoRoot, "node_modules/.bin/biome");
+
+if (!existsSync(skinsDir)) {
+  throw new Error(`Missing skins dir at ${skinsDir}`);
+}
+
+/** Keep only html[data-brand] activation — strip global :root / optional .dark binding. */
+function toScopedCatalogCss(css, id) {
+  const scoped = `html[data-brand="${id}"] {`;
+  const out = css
+    // darkDefault=true global: ":root,\n.dark,\nhtml[data-brand=\"id\"] {"
+    .replace(/:root\s*,\s*\n\.dark\s*,\s*\nhtml\[data-brand="[^"]+"\]\s*\{/g, scoped)
+    .replace(/:root\s*,\s*\.dark\s*,\s*html\[data-brand="[^"]+"\]\s*\{/g, scoped)
+    // darkDefault=false global: ":root,\nhtml[data-brand=\"id\"] {" (no .dark)
+    .replace(/:root\s*,\s*\nhtml\[data-brand="[^"]+"\]\s*\{/g, scoped)
+    .replace(/:root\s*,\s*html\[data-brand="[^"]+"\]\s*\{/g, scoped);
+
+  // Safety: never leave a bare :root { color block from a skin
+  if (/^:root\s*\{/m.test(out) || /\n:root\s*,/.test(out)) {
+    throw new Error(`Skin ${id} still binds :root after scoping — fix emit or regex`);
+  }
+  return out.trimEnd();
+}
+
+const files = readdirSync(skinsDir)
+  .filter((f) => f.endsWith(".css") && f !== "README.md")
+  .sort();
+
+const ids = [];
+const chunks = [
+  "/**",
+  " * @nebutra/theme — skins.css (design-language catalog)",
+  " * AUTO-GENERATED by scripts/sync-skins.mjs — DO NOT EDIT.",
+  " *",
+  " * Product chrome SSOT: @nebutra/tokens/styles.css + recipe.css",
+  " * This file: scoped Brand Package skins under html[data-brand] only.",
+  ' * Switch: document.documentElement.dataset.brand = "vanta" | "linear" | ...',
+  ' * Factory: delete dataset.brand (or clearLanguage() / applyLanguage("factory")).',
+  " *",
+  ` * Languages: ${files.map((f) => f.replace(/\.css$/, "")).join(", ")}`,
+  " */",
+  "",
+];
+
+for (const file of files) {
+  const id = file.replace(/\.css$/, "");
+  const raw = readFileSync(join(skinsDir, file), "utf8");
+  ids.push(id);
+  chunks.push(toScopedCatalogCss(raw, id));
+  chunks.push("");
+}
+
+writeFileSync(outPath, `${chunks.join("\n").trimEnd()}\n`);
+// Match Biome CSS formatter so governance lint after theme build stays green.
+if (existsSync(biomeBin)) {
+  const fmt = spawnSync(biomeBin, ["format", "--write", outPath], {
+    cwd: repoRoot,
+    encoding: "utf8",
+  });
+  if (fmt.status !== 0) {
+    process.stderr.write(fmt.stderr || fmt.stdout || "biome format failed on skins.css\n");
+    process.exit(fmt.status ?? 1);
+  }
+}
+process.stdout.write(`skins.css refreshed: ${ids.length} languages -> ${outPath}\n`);

package/scripts/sync-themes.mjs

@@ -0,0 +1,40 @@
+import { execFileSync } from "node:child_process";
+import { copyFileSync, existsSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const repoRoot = resolve(packageRoot, "..", "..", "..");
+const designTokensRoot = resolve(packageRoot, "..", "design-tokens");
+const generatedThemesPath = resolve(designTokensRoot, "build", "css", "themes.generated.css");
+const keyframesPath = resolve(packageRoot, "keyframes.css");
+const themesAliasPath = resolve(packageRoot, "themes.css");
+const biomeBin = resolve(
+  repoRoot,
+  "node_modules",
+  ".bin",
+  process.platform === "win32" ? "biome.cmd" : "biome",
+);
+
+if (!existsSync(generatedThemesPath)) {
+  throw new Error(
+    `Missing generated theme CSS at ${generatedThemesPath}. Run \`pnpm --filter @nebutra/design-tokens build\` before syncing @nebutra/theme.`,
+  );
+}
+
+copyFileSync(generatedThemesPath, keyframesPath);
+// Compatibility alias — prefer @nebutra/theme/keyframes.css
+writeFileSync(
+  themesAliasPath,
+  `/**
+ * @deprecated Import \`@nebutra/theme/keyframes.css\` instead.
+ * themes.css is a compatibility alias (keyframes only — no color moods).
+ */
+@import "./keyframes.css";
+`,
+);
+execFileSync(biomeBin, ["format", "--write", keyframesPath], {
+  cwd: repoRoot,
+  stdio: "inherit",
+});
+process.stdout.write("keyframes.css refreshed from @nebutra/design-tokens (+ themes.css alias)\n");