@nebutra/tokens 0.1.0

package/README.md

@@ -0,0 +1,79 @@
+# @nebutra/tokens
+
+> Runtime design tokens and theme provider for Nebutra apps. Single source of truth for CSS variables, color scales, and light/dark mode switching.
+
+## Installation
+
+```bash
+# Internal monorepo dependency
+pnpm add @nebutra/tokens@workspace:*
+```
+
+## Usage
+
+### CSS Tokens (in your app's `globals.css`)
+
+```css
+@import "@nebutra/tokens/styles.css";
+```
+
+This provides:
+- Brand color scales (`--nebutra-blue-*`, `--nebutra-cyan-*`)
+- 12-step functional scales (`--neutral-1..12`, `--blue-1..12`, `--cyan-1..12`)
+- Semantic variables (`--primary`, `--background`, `--border`, etc.)
+- Light/dark mode via `:root` / `.dark`
+- Display-P3 wide gamut with sRGB fallback
+- Tailwind v4 `@theme` integration
+
+### Theme Provider (in your root layout)
+
+```tsx
+import { ThemeProvider } from "@nebutra/tokens";
+
+export default function RootLayout({ children }) {
+  return (
+    <ThemeProvider attribute="class" defaultTheme="dark">
+      {children}
+    </ThemeProvider>
+  );
+}
+```
+
+### Theme Hook
+
+```tsx
+import { useTheme } from "@nebutra/tokens";
+
+function ThemeToggle() {
+  const { theme, setTheme } = useTheme();
+  return (
+    <button onClick={() => setTheme(theme === "dark" ? "light" : "dark")}>
+      Toggle theme
+    </button>
+  );
+}
+```
+
+## API
+
+| Export | Description |
+|--------|-------------|
+| `ThemeProvider` | React provider for light/dark mode (from next-themes) |
+| `useTheme()` | Hook to read/set current theme |
+| `ThemeProviderProps` | Props type for ThemeProvider |
+| `THEME_IDS` | `["light", "dark"]` |
+| `ThemeId` | `"light" \| "dark"` |
+| `DEFAULT_THEME` | `"dark"` |
+
+## Token Architecture
+
+```
+@nebutra/brand   --> Brand primitives (source data, not runtime)
+@nebutra/tokens  --> Runtime CSS variables (THIS PACKAGE)
+@nebutra/theme   --> Multi-theme presets (oklch, 6 variants)
+@nebutra/ui      --> Components (consume tokens via CSS vars)
+```
+
+## Peer Dependencies
+
+- `react` ^19

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@nebutra/tokens",
+  "version": "0.1.0",
+  "description": "Unified theme tokens and theme-provider entry for Nebutra apps",
+  "private": false,
+  "license": "AGPL-3.0",
+  "type": "module",
+  "sideEffects": [
+    "./styles.css"
+  ],
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./styles.css": "./styles.css"
+  },
+  "dependencies": {
+    "next-themes": "^0.4.6",
+    "@nebutra/design-tokens": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": "^19"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "typescript": "^5.9.3"
+  },
+  "homepage": "https://github.com/Nebutra/Nebutra-Sailor/tree/main/packages/design/tokens#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Nebutra/Nebutra-Sailor.git",
+    "directory": "packages/design/tokens"
+  },
+  "bugs": {
+    "url": "https://github.com/Nebutra/Nebutra-Sailor/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node -e \"const fs=require('node:fs'),src='../design-tokens/build/css/styles.generated.css';if(fs.existsSync(src)){fs.copyFileSync(src,'./styles.css');console.log('styles.css refreshed from @nebutra/design-tokens')}else{console.log('styles.css kept (committed copy used; design-tokens build/ absent — likely Turbo cache restore without files)')}\"",
+    "sync": "pnpm --filter @nebutra/design-tokens build && node -e \"require('node:fs').copyFileSync('../design-tokens/build/css/styles.generated.css', './styles.css')\"",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+/**
+ * @nebutra/tokens — Runtime theme tokens & theme switching
+ *
+ * This package is the SINGLE SOURCE OF TRUTH for runtime design tokens.
+ *
+ * CSS tokens:  @import "@nebutra/tokens/styles.css"
+ *   → Brand color scales (--nebutra-blue-*, --nebutra-cyan-*)
+ *   → 12-step functional scales (--neutral-1..12, --blue-1..12, --cyan-1..12)
+ *   → Semantic variables (--primary, --background, --border, etc.)
+ *   → Light/dark mode via :root / .dark
+ *   → Display-P3 wide gamut with sRGB fallback
+ *   → Tailwind v4 @theme integration
+ *
+ * JS exports:  ThemeProvider, useTheme, THEME_STORAGE_KEY (custom — no next-themes)
+ *   → App-level light/dark mode switching
+ *   → ThemeProvider writes BOTH localStorage AND a cookie of the same name.
+ *     Server Components read the cookie via `next/headers` cookies() and
+ *     inject the resolved class directly into <html> — zero inline script,
+ *     zero React 19 "script in component" warning, zero FOUC risk.
+ *
+ * Related packages:
+ *   @nebutra/brand  → brand primitives (color definitions, motion language)
+ *   @nebutra/theme  → multi-theme presets (6 oklch variants for SaaS product)
+ *   @nebutra/ui     → component library (consumes tokens via CSS variables)
+ */
+
+export {
+  THEME_STORAGE_KEY,
+  ThemeProvider,
+  type ThemeProviderProps,
+  useTheme,
+} from "./theme-provider";
+
+export const THEME_IDS = ["light", "dark"] as const;
+export type ThemeId = (typeof THEME_IDS)[number];
+
+export const DEFAULT_THEME: ThemeId = "dark";

package/src/theme-provider.tsx

@@ -0,0 +1,231 @@
+"use client";
+
+/**
+ * Custom ThemeProvider — replaces the upstream `next-themes` re-export.
+ *
+ * Why we own this: `next-themes@0.4.x` renders an inline `<script>` element
+ * inside its Client-Component provider for FOUC prevention. React 19 +
+ * Next.js 16 (Turbopack) now emit a console error when scripts appear
+ * inside Client Components ("Scripts inside React components are never
+ * executed when rendering on the client"). The script DID do its job at
+ * SSR time, but the warning pollutes the dev console on every page load.
+ *
+ * Our architecture splits the two concerns cleanly:
+ *   - {@link ThemeProvider}  (Client) — runtime state, OS sync, transitions
+ *   - {@link ThemeScript}    (Server) — synchronous FOUC-prevention inline
+ *                                       script rendered into the SSR HTML
+ *
+ * The API surface mirrors next-themes so the migration is a drop-in for
+ * callers (same prop names: `attribute`, `defaultTheme`, `enableSystem`,
+ * `disableTransitionOnChange`, `storageKey`, `nonce`).
+ */
+
+import {
+  createContext,
+  type ReactNode,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+} from "react";
+
+type Theme = "light" | "dark" | "system";
+type ResolvedTheme = "light" | "dark";
+
+const THEMES = ["light", "dark", "system"] as const satisfies readonly Theme[];
+
+/**
+ * Shared default storage key. Matches what `next-themes` uses, so any user
+ * who already has a saved preference keeps it across the migration.
+ */
+export const THEME_STORAGE_KEY = "theme";
+
+interface ThemeContextValue {
+  /** The raw user preference. May be "system". */
+  theme: Theme;
+  /** The concretely-applied theme — always "light" or "dark". */
+  resolvedTheme: ResolvedTheme;
+  /** The OS-level preference (always concrete). */
+  systemTheme: ResolvedTheme;
+  setTheme: (theme: Theme) => void;
+  themes: readonly Theme[];
+}
+
+const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+/**
+ * Read the active theme state. Safe to call outside a provider — returns
+ * a sane default in that case so consumers don't need to null-check.
+ */
+export function useTheme(): ThemeContextValue {
+  const ctx = useContext(ThemeContext);
+  if (ctx) return ctx;
+  return {
+    theme: "system",
+    resolvedTheme: "light",
+    systemTheme: "light",
+    setTheme: () => {
+      // no-op outside provider
+    },
+    themes: THEMES,
+  };
+}
+
+function resolveSystemTheme(): ResolvedTheme {
+  if (typeof window === "undefined") return "light";
+  return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+}
+
+function readStoredTheme(storageKey: string, fallback: Theme): Theme {
+  if (typeof window === "undefined") return fallback;
+  try {
+    const v = window.localStorage.getItem(storageKey);
+    if (v === "light" || v === "dark" || v === "system") return v;
+  } catch {
+    // localStorage may be disabled (Safari private mode, etc.)
+  }
+  return fallback;
+}
+
+/** 1 year — long-lived because theme is a deliberate user choice. */
+const THEME_COOKIE_MAX_AGE = 365 * 24 * 60 * 60;
+
+/**
+ * Mirror the resolved theme into a cookie so the next request can be
+ * server-rendered with the correct `<html>` class — eliminating the
+ * need for an inline FOUC-prevention `<script>` (which React 19 warns
+ * about). The cookie value is always concrete ("light" | "dark"), never
+ * "system" — Server Components shouldn't try to guess the OS preference.
+ */
+function writeThemeCookie(resolved: ResolvedTheme, cookieName: string) {
+  if (typeof document === "undefined") return;
+  document.cookie = `${cookieName}=${resolved}; Max-Age=${THEME_COOKIE_MAX_AGE}; Path=/; SameSite=Lax`;
+}
+
+function applyThemeToDom(
+  resolved: ResolvedTheme,
+  attribute: "class" | "data-theme",
+  disableTransitionOnChange: boolean,
+) {
+  if (typeof document === "undefined") return;
+  const root = document.documentElement;
+
+  // Suppress CSS transitions during the swap so the change appears instant.
+  if (disableTransitionOnChange) {
+    const suppressor = document.createElement("style");
+    suppressor.appendChild(
+      document.createTextNode(
+        "*,*::before,*::after{transition:none!important;animation-duration:0s!important}",
+      ),
+    );
+    document.head.appendChild(suppressor);
+    // Force a reflow so the rule applies before we swap classes
+    void window.getComputedStyle(suppressor).opacity;
+    // Remove the rule on the next tick; transitions resume afterwards
+    setTimeout(() => {
+      if (suppressor.parentNode) suppressor.parentNode.removeChild(suppressor);
+    }, 1);
+  }
+
+  if (attribute === "class") {
+    root.classList.remove("light", "dark");
+    root.classList.add(resolved);
+  } else {
+    root.setAttribute("data-theme", resolved);
+  }
+  root.style.colorScheme = resolved;
+}
+
+export interface ThemeProviderProps {
+  children: ReactNode;
+  /** Which DOM attribute to set on `<html>`. Default: `"class"`. */
+  attribute?: "class" | "data-theme";
+  /** Default theme when no preference is stored. Default: `"system"`. */
+  defaultTheme?: Theme;
+  /** Whether `"system"` is a valid theme that tracks `prefers-color-scheme`. */
+  enableSystem?: boolean;
+  /** Suppress CSS transitions during the swap. Default: `true`. */
+  disableTransitionOnChange?: boolean;
+  /** Storage key under which the preference is persisted. */
+  storageKey?: string;
+  /** CSP nonce — accepted for API compatibility, currently unused by client logic. */
+  nonce?: string;
+}
+
+export function ThemeProvider({
+  children,
+  attribute = "class",
+  defaultTheme = "system",
+  enableSystem = true,
+  disableTransitionOnChange = true,
+  storageKey = THEME_STORAGE_KEY,
+}: ThemeProviderProps) {
+  const [theme, setThemeState] = useState<Theme>(() => readStoredTheme(storageKey, defaultTheme));
+  const [systemTheme, setSystemTheme] = useState<ResolvedTheme>(() => resolveSystemTheme());
+
+  const resolvedTheme: ResolvedTheme =
+    theme === "system" ? (enableSystem ? systemTheme : "light") : theme;
+
+  const setTheme = useCallback(
+    (next: Theme) => {
+      setThemeState(next);
+      try {
+        if (next === "system") {
+          window.localStorage.removeItem(storageKey);
+        } else {
+          window.localStorage.setItem(storageKey, next);
+        }
+      } catch {
+        // localStorage may be disabled — accept the loss
+      }
+    },
+    [storageKey],
+  );
+
+  // Apply the resolved theme to the DOM AND sync the cookie so the next
+  // SSR can render the correct <html> class directly (no inline script,
+  // no React 19 "script in component" warning).
+  useEffect(() => {
+    applyThemeToDom(resolvedTheme, attribute, disableTransitionOnChange);
+    writeThemeCookie(resolvedTheme, storageKey);
+  }, [resolvedTheme, attribute, disableTransitionOnChange, storageKey]);
+
+  // Follow OS preference changes when in `system` mode
+  useEffect(() => {
+    if (!enableSystem) return;
+    const mq = window.matchMedia("(prefers-color-scheme: dark)");
+    const handler = (event: MediaQueryListEvent) =>
+      setSystemTheme(event.matches ? "dark" : "light");
+    mq.addEventListener("change", handler);
+    return () => mq.removeEventListener("change", handler);
+  }, [enableSystem]);
+
+  // Sync across tabs / windows
+  useEffect(() => {
+    const handler = (event: StorageEvent) => {
+      if (event.key !== storageKey) return;
+      const next = event.newValue;
+      if (next === "light" || next === "dark" || next === "system") {
+        setThemeState(next);
+      } else if (next === null) {
+        setThemeState(defaultTheme);
+      }
+    };
+    window.addEventListener("storage", handler);
+    return () => window.removeEventListener("storage", handler);
+  }, [storageKey, defaultTheme]);
+
+  const value = useMemo<ThemeContextValue>(
+    () => ({
+      theme,
+      resolvedTheme,
+      systemTheme,
+      setTheme,
+      themes: THEMES,
+    }),
+    [theme, resolvedTheme, systemTheme, setTheme],
+  );
+
+  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
+}