@nebutra/theme 0.1.0

package/README.md

@@ -0,0 +1,46 @@
+# @nebutra/theme
+
+CSS-only theme engine for Nebutra — Tailwind v4 `@theme` tokens, `data-theme` selectors, and a `next-themes` re-export.
+
+## Design Intent
+
+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.
+
+Apps import a single CSS file and a single provider — no per-component theme wiring required.
+
+## Registry Contract
+
+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.
+
+The registry is consumed by:
+
+- `@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
+
+Each built-in theme must declare token path, install command, compatibility flags, WCAG target, required token coverage, and visual regression suites.
+
+## Usage
+
+```tsx
+// In your root layout
+import { ThemeProvider } from "@nebutra/theme";
+import "@nebutra/theme/themes.css";
+
+<ThemeProvider attribute="data-theme" defaultTheme="neon">
+  {children}
+</ThemeProvider>
+```
+
+## Available Themes
+
+`neon` | `gradient` | `dark-dense` | `minimal` | `vibrant` | `ocean`
+
+The `THEME_IDS` constant and `ThemeId` type are exported for use in theme switcher components.
+
+```bash
+nebutra theme list --format json
+nebutra theme inspect neon --format json
+```

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@nebutra/theme",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "CSS-only theme engine — Tailwind v4 @theme tokens + data-theme selectors + next-themes re-export",
+  "private": false,
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./registry": "./src/registry.ts",
+    "./registry.json": "./src/registry.json",
+    "./themes.css": "./themes.css"
+  },
+  "dependencies": {
+    "next-themes": "^0.4.6"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.4"
+  },
+  "peerDependencies": {
+    "react": "^19"
+  },
+  "homepage": "https://github.com/Nebutra/Nebutra-Sailor/tree/main/packages/design/theme#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Nebutra/Nebutra-Sailor.git",
+    "directory": "packages/design/theme"
+  },
+  "bugs": {
+    "url": "https://github.com/Nebutra/Nebutra-Sailor/issues"
+  },
+  "publishConfig": {
+    "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')\"",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/__tests__/theme-registry.test.ts

@@ -0,0 +1,49 @@
+import { readFile } from "node:fs/promises";
+import { describe, expect, it } from "vitest";
+import { getThemeById, THEME_IDS, THEME_REGISTRY } from "../index";
+
+function getTokenAtPath(tokens: Record<string, unknown>, tokenPath: string): unknown {
+  return tokenPath.split(".").reduce<unknown>((node, key) => {
+    if (!node || typeof node !== "object") return undefined;
+    return (node as Record<string, unknown>)[key];
+  }, tokens);
+}
+
+describe("@nebutra/theme registry contract", () => {
+  it("exports deterministic theme ids from the registry", () => {
+    expect(THEME_IDS).toEqual(["neon", "gradient", "dark-dense", "minimal", "vibrant", "ocean"]);
+  });
+
+  it("exposes install and governance metadata for each built-in theme", () => {
+    for (const theme of THEME_REGISTRY.themes) {
+      expect(theme.id).toMatch(/^[a-z0-9-]+$/u);
+      expect(theme.tokenPath).toBe(`tokens/themes/${theme.id}.json`);
+      expect(theme.install.command).toContain(`nebutra theme add ${theme.id}`);
+      expect(theme.governance.requiredTokens.length).toBeGreaterThan(0);
+      expect(theme.governance.wcag).toBe("AA");
+      expect(theme.compatibility.tailwind).toBe("4");
+      expect(theme.compatibility.figmaVariables).toBe(true);
+    }
+  });
+
+  it("keeps registry token paths and required tokens backed by DTCG files", async () => {
+    for (const theme of THEME_REGISTRY.themes) {
+      const tokenFile = new URL(`../../../design-tokens/${theme.tokenPath}`, import.meta.url);
+      const tokens = JSON.parse(await readFile(tokenFile, "utf8")) as Record<string, unknown>;
+
+      expect(tokens.theme).toBe(theme.id);
+
+      for (const requiredToken of theme.governance.requiredTokens) {
+        expect(getTokenAtPath(tokens, requiredToken)).toMatchObject({
+          $type: expect.any(String),
+          $value: expect.any(String),
+        });
+      }
+    }
+  });
+
+  it("supports lookup by id without callers hardcoding theme details", () => {
+    expect(getThemeById("neon")?.mood).toContain("AI");
+    expect(getThemeById("missing")).toBeUndefined();
+  });
+});

package/src/index.ts

@@ -0,0 +1,20 @@
+// packages/design/theme/src/index.ts
+// Re-export next-themes for convenience — all apps import from @nebutra/theme.
+// Theme catalog metadata lives in ./registry so CLI/preset/docs/Figma sync all
+// discover the same built-in theme contract.
+
+export type { ThemeProviderProps } from "next-themes";
+export { ThemeProvider, useTheme } from "next-themes";
+
+export {
+  BUILT_IN_THEME_IDS,
+  DEFAULT_THEME,
+  getThemeById,
+  isBuiltInThemeId,
+  isThemeId,
+  THEME_IDS,
+  THEME_REGISTRY,
+  type ThemeId,
+  type ThemeRegistry,
+  type ThemeRegistryEntry,
+} from "./registry";

package/src/registry.json

@@ -0,0 +1,199 @@
+{
+  "$schema": "https://nebutra.com/schemas/theme-registry.json",
+  "version": "2026.05",
+  "defaultTheme": "neon",
+  "themes": [
+    {
+      "id": "neon",
+      "name": "Neon",
+      "category": "ai-native",
+      "mood": "AI SaaS default - dark, electric, high contrast",
+      "tokenPath": "tokens/themes/neon.json",
+      "install": {
+        "command": "nebutra theme add neon",
+        "registryUrl": "https://ui.nebutra.com/themes/neon.json"
+      },
+      "compatibility": {
+        "tailwind": "4",
+        "cssVariables": true,
+        "figmaVariables": true,
+        "shadcnRegistry": true
+      },
+      "governance": {
+        "wcag": "AA",
+        "requiredTokens": [
+          "color.primary",
+          "color.primary-foreground",
+          "color.background",
+          "color.foreground",
+          "color.card",
+          "color.border",
+          "color.ring",
+          "radius.md",
+          "fontFamily.sans"
+        ],
+        "visualSuites": ["forms", "pricing", "dashboard", "ai-chat", "charts"]
+      }
+    },
+    {
+      "id": "gradient",
+      "name": "Gradient",
+      "category": "marketing",
+      "mood": "Growth and marketing - bright, polished, conversion-oriented",
+      "tokenPath": "tokens/themes/gradient.json",
+      "install": {
+        "command": "nebutra theme add gradient",
+        "registryUrl": "https://ui.nebutra.com/themes/gradient.json"
+      },
+      "compatibility": {
+        "tailwind": "4",
+        "cssVariables": true,
+        "figmaVariables": true,
+        "shadcnRegistry": true
+      },
+      "governance": {
+        "wcag": "AA",
+        "requiredTokens": [
+          "color.primary",
+          "color.primary-foreground",
+          "color.background",
+          "color.foreground",
+          "color.card",
+          "color.border",
+          "color.ring",
+          "radius.md",
+          "fontFamily.sans"
+        ],
+        "visualSuites": ["forms", "pricing", "dashboard", "ai-chat", "charts"]
+      }
+    },
+    {
+      "id": "dark-dense",
+      "name": "Dark Dense",
+      "category": "pro-tools",
+      "mood": "Dense operator surfaces - dark, compact, low distraction",
+      "tokenPath": "tokens/themes/dark-dense.json",
+      "install": {
+        "command": "nebutra theme add dark-dense",
+        "registryUrl": "https://ui.nebutra.com/themes/dark-dense.json"
+      },
+      "compatibility": {
+        "tailwind": "4",
+        "cssVariables": true,
+        "figmaVariables": true,
+        "shadcnRegistry": true
+      },
+      "governance": {
+        "wcag": "AA",
+        "requiredTokens": [
+          "color.primary",
+          "color.primary-foreground",
+          "color.background",
+          "color.foreground",
+          "color.card",
+          "color.border",
+          "color.ring",
+          "radius.md",
+          "fontFamily.sans"
+        ],
+        "visualSuites": ["forms", "pricing", "dashboard", "ai-chat", "charts"]
+      }
+    },
+    {
+      "id": "minimal",
+      "name": "Minimal",
+      "category": "productivity",
+      "mood": "Document and workspace apps - neutral, calm, readable",
+      "tokenPath": "tokens/themes/minimal.json",
+      "install": {
+        "command": "nebutra theme add minimal",
+        "registryUrl": "https://ui.nebutra.com/themes/minimal.json"
+      },
+      "compatibility": {
+        "tailwind": "4",
+        "cssVariables": true,
+        "figmaVariables": true,
+        "shadcnRegistry": true
+      },
+      "governance": {
+        "wcag": "AA",
+        "requiredTokens": [
+          "color.primary",
+          "color.primary-foreground",
+          "color.background",
+          "color.foreground",
+          "color.card",
+          "color.border",
+          "color.ring",
+          "radius.md",
+          "fontFamily.sans"
+        ],
+        "visualSuites": ["forms", "pricing", "dashboard", "ai-chat", "charts"]
+      }
+    },
+    {
+      "id": "vibrant",
+      "name": "Vibrant",
+      "category": "creative",
+      "mood": "Creator and consumer surfaces - saturated, expressive, energetic",
+      "tokenPath": "tokens/themes/vibrant.json",
+      "install": {
+        "command": "nebutra theme add vibrant",
+        "registryUrl": "https://ui.nebutra.com/themes/vibrant.json"
+      },
+      "compatibility": {
+        "tailwind": "4",
+        "cssVariables": true,
+        "figmaVariables": true,
+        "shadcnRegistry": true
+      },
+      "governance": {
+        "wcag": "AA",
+        "requiredTokens": [
+          "color.primary",
+          "color.primary-foreground",
+          "color.background",
+          "color.foreground",
+          "color.card",
+          "color.border",
+          "color.ring",
+          "radius.md",
+          "fontFamily.sans"
+        ],
+        "visualSuites": ["forms", "pricing", "dashboard", "ai-chat", "charts"]
+      }
+    },
+    {
+      "id": "ocean",
+      "name": "Ocean",
+      "category": "enterprise",
+      "mood": "B2B infrastructure and finance - cool, stable, trustworthy",
+      "tokenPath": "tokens/themes/ocean.json",
+      "install": {
+        "command": "nebutra theme add ocean",
+        "registryUrl": "https://ui.nebutra.com/themes/ocean.json"
+      },
+      "compatibility": {
+        "tailwind": "4",
+        "cssVariables": true,
+        "figmaVariables": true,
+        "shadcnRegistry": true
+      },
+      "governance": {
+        "wcag": "AA",
+        "requiredTokens": [
+          "color.primary",
+          "color.primary-foreground",
+          "color.background",
+          "color.foreground",
+          "color.card",
+          "color.border",
+          "color.ring",
+          "radius.md",
+          "fontFamily.sans"
+        ],
+        "visualSuites": ["forms", "pricing", "dashboard", "ai-chat", "charts"]
+      }
+    }
+  ]
+}

package/src/registry.ts

@@ -0,0 +1,56 @@
+import registryJson from "./registry.json" with { type: "json" };
+
+export interface ThemeRegistryInstall {
+  command: string;
+  registryUrl: string;
+}
+
+export interface ThemeRegistryCompatibility {
+  tailwind: "4";
+  cssVariables: boolean;
+  figmaVariables: boolean;
+  shadcnRegistry: boolean;
+}
+
+export interface ThemeRegistryGovernance {
+  wcag: "AA" | "AAA";
+  requiredTokens: string[];
+  visualSuites: string[];
+}
+
+export interface ThemeRegistryEntry {
+  id: string;
+  name: string;
+  category: string;
+  mood: string;
+  tokenPath: string;
+  install: ThemeRegistryInstall;
+  compatibility: ThemeRegistryCompatibility;
+  governance: ThemeRegistryGovernance;
+}
+
+export interface ThemeRegistry {
+  $schema: string;
+  version: string;
+  defaultTheme: string;
+  themes: ThemeRegistryEntry[];
+}
+
+export const THEME_REGISTRY = registryJson as ThemeRegistry;
+export const THEME_IDS = THEME_REGISTRY.themes.map((theme) => theme.id);
+export const BUILT_IN_THEME_IDS = THEME_IDS;
+export const DEFAULT_THEME = THEME_REGISTRY.defaultTheme;
+
+export type ThemeId = string;
+
+export function isBuiltInThemeId(id: string): boolean {
+  return THEME_IDS.includes(id);
+}
+
+export function isThemeId(id: string): boolean {
+  return id === "custom" || isBuiltInThemeId(id);
+}
+
+export function getThemeById(id: string): ThemeRegistryEntry | undefined {
+  return THEME_REGISTRY.themes.find((theme) => theme.id === id);
+}