@nebutra/theme 0.1.1 → 0.2.0

package/.turbo/turbo-build.log

@@ -1,177 +1,10 @@
 
-> @nebutra/theme@0.1.1 prebuild /home/runner/work/Nebutra-Sailor/Nebutra-Sailor/packages/design/theme
-> corepack pnpm --filter @nebutra/design-tokens build
-
-
-> @nebutra/design-tokens@0.1.1 build /home/runner/work/Nebutra-Sailor/Nebutra-Sailor/packages/design/design-tokens
-> node style-dictionary.config.mjs
-
-
-css
-- build/css/light.css
-
-ts
-- build/ts/light.ts
-- build/ts/light.d.ts
-
-tailwind
-- build/tailwind/light.preset.cjs
-
-css
-✔︎ build/css/light.css
-
-ts
-✔︎ build/ts/light.ts
-✔︎ build/ts/light.d.ts
-
-tailwind
-✔︎ build/tailwind/light.preset.cjs
-
-css
-- build/css/dark.css
-
-ts
-- build/ts/dark.ts
-- build/ts/dark.d.ts
-
-tailwind
-- build/tailwind/dark.preset.cjs
-
-css
-✔︎ build/css/dark.css
-
-ts
-✔︎ build/ts/dark.ts
-✔︎ build/ts/dark.d.ts
-
-tailwind
-✔︎ build/tailwind/dark.preset.cjs
-
-css
-- build/css/neon.css
-
-ts
-- build/ts/neon.ts
-- build/ts/neon.d.ts
-
-tailwind
-- build/tailwind/neon.preset.cjs
-
-css
-✔︎ build/css/neon.css
-
-ts
-✔︎ build/ts/neon.ts
-✔︎ build/ts/neon.d.ts
-
-tailwind
-✔︎ build/tailwind/neon.preset.cjs
-
-css
-- build/css/gradient.css
-
-ts
-- build/ts/gradient.ts
-- build/ts/gradient.d.ts
-
-tailwind
-- build/tailwind/gradient.preset.cjs
-
-css
-✔︎ build/css/gradient.css
-
-ts
-✔︎ build/ts/gradient.ts
-✔︎ build/ts/gradient.d.ts
-
-tailwind
-✔︎ build/tailwind/gradient.preset.cjs
-
-css
-- build/css/dark-dense.css
-
-ts
-- build/ts/dark-dense.ts
-- build/ts/dark-dense.d.ts
-
-tailwind
-- build/tailwind/dark-dense.preset.cjs
-
-css
-✔︎ build/css/dark-dense.css
-
-ts
-✔︎ build/ts/dark-dense.ts
-✔︎ build/ts/dark-dense.d.ts
-
-tailwind
-✔︎ build/tailwind/dark-dense.preset.cjs
-
-css
-- build/css/minimal.css
-
-ts
-- build/ts/minimal.ts
-- build/ts/minimal.d.ts
-
-tailwind
-- build/tailwind/minimal.preset.cjs
-
-css
-✔︎ build/css/minimal.css
-
-ts
-✔︎ build/ts/minimal.ts
-✔︎ build/ts/minimal.d.ts
-
-tailwind
-✔︎ build/tailwind/minimal.preset.cjs
-
-css
-- build/css/vibrant.css
-
-ts
-- build/ts/vibrant.ts
-- build/ts/vibrant.d.ts
-
-tailwind
-- build/tailwind/vibrant.preset.cjs
-
-css
-✔︎ build/css/vibrant.css
-
-ts
-✔︎ build/ts/vibrant.ts
-✔︎ build/ts/vibrant.d.ts
-
-tailwind
-✔︎ build/tailwind/vibrant.preset.cjs
-
-css
-- build/css/ocean.css
-
-ts
-- build/ts/ocean.ts
-- build/ts/ocean.d.ts
-
-tailwind
-- build/tailwind/ocean.preset.cjs
-
-css
-✔︎ build/css/ocean.css
-
-ts
-✔︎ build/ts/ocean.ts
-✔︎ build/ts/ocean.d.ts
-
-tailwind
-✔︎ build/tailwind/ocean.preset.cjs
-
-[design-tokens] build complete
-  → build/css/styles.generated.css   (replaces packages/design/tokens/styles.css)
-  → build/css/themes.generated.css   (replaces packages/design/theme/themes.css)
-
-> @nebutra/theme@0.1.1 build /home/runner/work/Nebutra-Sailor/Nebutra-Sailor/packages/design/theme
-> node -e "require('node:fs').copyFileSync('../design-tokens/build/css/themes.generated.css', './themes.css'); console.log('themes.css regenerated from @nebutra/design-tokens')"
-
-themes.css regenerated from @nebutra/design-tokens
+> @nebutra/theme@0.2.0 build /Users/tseka_luk/Documents/Nebutra-SaaS-Lab/Nebutra-Sailor/packages/design/theme
+> node scripts/sync-languages.mjs && node ../tokens/scripts/emit-skins.mjs && node scripts/sync-skins.mjs
+
+sync-languages:
+  languages.json: 8 languages (7 skins + factory)
+  built-in-packages.generated.ts: 7 packages
+emit-skins: 7 skins from brand.json → skins/*.css
+  gsap, linear, notion, raycast, stripe, vanta, vercel
+skins.css refreshed: 7 languages -> /Users/tseka_luk/Documents/Nebutra-SaaS-Lab/Nebutra-Sailor/packages/design/theme/skins.css

package/.turbo/turbo-typecheck.log

@@ -1,4 +1,4 @@
 
-> @nebutra/theme@0.1.1 typecheck /home/runner/work/Nebutra-Sailor/Nebutra-Sailor/packages/design/theme
+> @nebutra/theme@0.2.0 typecheck /Users/tseka_luk/Documents/Nebutra-SaaS-Lab/Nebutra-Sailor/packages/design/theme
 > tsc --noEmit
 

package/AGENTS.md

@@ -1,41 +1,28 @@
-# AGENTS.md — packages/theme
-
-Execution contract for Nebutra's multi-theme preset package.
+# AGENTS.md — packages/design/theme
 
 ## Scope
 
-Applies to everything under `packages/design/theme/`.
-
-This package owns the named product-theme layer that sits above base runtime
-tokens. It is CSS-first and intentionally small.
-
-## Source Of Truth
-
-- Public package surface and exports: `package.json`, `src/index.ts`
-- Canonical named theme selectors and CSS theme payloads: `themes.css`
+`@nebutra/theme` is the **design-language switch surface**.
 
-## Contract Boundaries
+## Do not reintroduce
 
-- Treat `themes.css` as the canonical source for theme-specific CSS behavior.
-  Do not duplicate theme selector logic in apps.
-- Keep `THEME_IDS` in `src/index.ts` aligned with the `[data-theme]` selectors
-  defined in `themes.css`. Adding, renaming, or removing a theme requires
-  updating both in the same change.
-- This package re-exports `next-themes` as a convenience boundary. Do not add
-  unrelated runtime policy, product gating, or token definitions here.
-- Keep this package distinct from `@nebutra/tokens`. `@nebutra/theme` owns
-  named presets such as `ocean` or `minimal`; `@nebutra/tokens` owns the base
-  semantic token system.
+- Multi-mood oklch `[data-theme]` catalogs (deleted 2026.07)
+- Root `@theme { --color-primary: … }` dual-truth against `@nebutra/tokens`
+- “Theme = recolor primary only” product thinking
 
-## Generated And Derived Files
+## Source Of Truth
 
-- `tsconfig.tsbuildinfo` and similar compiler artifacts are derived files.
-- Treat consumer app theme state and compiled CSS output as derived from
-  `themes.css` and `src/index.ts`.
+| Concern | Source |
+|---------|--------|
+| Product chrome (factory) | `@nebutra/tokens` |
+| Design language catalog | `src/languages.json` |
+| Brand Package fixtures | `packages/design/tokens/brands/*` |
+| Multi-language CSS | `skins.css` (`html[data-brand]`) |
+| Keyframes only | `keyframes.css` (`themes.css` = deprecated alias) |
 
 ## Validation
 
-- Theme surface or type changes:
-  `pnpm --filter @nebutra/theme typecheck`
-- When selector changes matter, verify a consumer imports `@nebutra/theme/themes.css`
-  instead of patching compiled output.
+```bash
+pnpm --filter @nebutra/theme test
+pnpm --filter @nebutra/theme sync:skins
+```

package/DESIGN.md

@@ -1,203 +1,124 @@
 # `@nebutra/theme` — Design Spec
 
-> Multi-theme engine of the Nebutra-Sailor design system.
-> Part of the [root DESIGN.md](../../DESIGN.md). Spec format: `design-md@2026.05`.
+> Design-language catalog for **global product chrome swap**.  
+> Part of the [root DESIGN.md](../../DESIGN.md). Spec format: `design-md@2026.07`.
 
 | Field | Value |
 |------|------|
 | Package | `@nebutra/theme` |
-| Status | Stable — 6 themes shipped, more allowed via governance |
-| Source files | `packages/design/theme/src/registry.json` and generated `packages/design/theme/themes.css` |
-| Activation | `[data-theme="…"]` attribute on `<html>` |
-| Default theme | `neon` (no `data-theme` attribute) |
+| Status | Design languages only — oklch multi-mood catalog **deleted** |
+| Primary catalog | `src/languages.json` + generated `skins.css` |
+| Brand Package fixtures | `packages/design/tokens/brands/*` |
+| keyframes.css | Keyframes only (no color moods); themes.css is a deprecated alias |
+| Product SSOT | Always `@nebutra/tokens` |
 
 ---
 
 ## 1. Identity
 
-A **product feature**: the SaaS preset system (`@nebutra/preset`) lets end customers and self-hosters choose a theme that matches their product mood. Switching is CSS-only (no JS rebuild) — token values are overridden per `[data-theme]` selector.
+**What users mean by “换主题” in Create Center** is swapping a full **design language**:  
+action vs brand-mark, button recipe, free elevation stacks, radii slots, type zones — not recoloring `--primary` alone.
 
-**Boundary**: this package is for the multi-theme product feature. For light/dark of the *base* `neon` look, use `class="dark"` from `next-themes`. The two systems compose.
+That product surface lives here. The stress-test loop (Linear → GSAP → Raycast → Vercel → Vanta) is how we grow **carrier capacity**, not an infinite preset zoo.
 
-The theme catalogue is governed through `src/registry.json`. Consumers must import from
-`@nebutra/theme/registry` instead of copying theme names. The Style Dictionary pipeline,
-`@nebutra/preset`, CLI commands, docs, and future Figma/playground publishing all use this registry.
+**Not this package:** factory semantic HSL (tokens), VI logo lock (brand), component class strings (ui).
+
+### 1.1 Single catalog
+
+| Catalog | Attribute | Payload |
+|---------|-----------|---------|
+| **Design language** | `html[data-brand]` | Brand Package CSS |
+
+Oklch multi-mood `[data-theme]` catalog was removed — dual-truth and weak design quality.
 
 ---
 
-## 2. Tokens (per theme)
+## 2. Design language contract
 
-Each preset overrides the same set of tokens; only values differ. The base set:
+Each entry in `languages.json` maps to a Brand Package:
 
 ```
-Brand:        --color-primary, --color-secondary, --color-accent (+ -foreground each)
-Surfaces:     --color-background, --color-foreground, --color-card, --color-popover, --color-muted, --color-border, --color-input, --color-ring
-Status:       --color-destructive, --color-success, --color-warning, --color-info (+ -foreground each)
-Derived:      --color-primary-hover, --color-primary-active (via color-mix in oklch)
-Radius:       --radius-{sm,md,lg,xl,full}
-Typography:   --font-sans, --font-mono, --font-heading
-Shadows:      --shadow-{sm,md,lg,xl}
-Transitions:  --transition-{fast,normal,slow}
+roles.action     → --primary          (CTA)
+roles.brand      → --brand-mark       (logo / AI badge)
+recipe           → --btn-default-*, --badge-default-*, radii
+elevationTokens  → --elevation-card|control|raised  (free CSS)
+zones            → product vs marketing type scales
+typography.faces → @font-face
 ```
 
-All color values are **oklch** for perceptual uniformity. Hover/active states are derived via `color-mix(in oklch, …)` — no JS.
-
-### 2.1 Theme catalogue
+### 2.1 Fixture matrix (acceptance bar)
 
-| `data-theme` | Mood | Background | Primary | Use case |
-|------|------|-----------|---------|----------|
-| `neon` *(default)* | Vibrant dark, electric blue | `oklch(0.141 0.005 285.9)` ≈ #09090b | `oklch(0.452 0.313 264.1)` ≈ vivid blue | AI SaaS dashboards |
-| `gradient` | Soft light, blue spectrum | `oklch(1 0 0)` (white) | `oklch(0.546 0.245 262.9)` | Marketing / growth |
-| `dark-dense` | High-density dark | near-black | desaturated blue | Pro tools, terminals |
-| `minimal` | Neutral, low chroma | white / off-white | low-chroma blue | Document apps |
-| `vibrant` | Saturated multicolor | white | vivid magenta-blue | Creator / consumer |
-| `ocean` | Cool teal/blue | white | teal | B2B finance, infra |
+| id | Proves |
+|----|--------|
+| factory | No override — tokens SSOT |
+| linear | Chromatic solid CTA + **dual-mode** dark/light |
+| gsap | Non-solid CTA recipe + zones |
+| raycast | action ≠ brand-mark + elev=key |
+| vercel | Light mono + elev=hairline + **dual-mode** light/dark palettes |
+| vanta | Chromatic action≠brand + elev=none + pills + dual fonts |
 
-> Exact oklch tuples for every theme are in `packages/design/theme/themes.css`. Designer-readable per-theme tables are deferred to Storybook (Foundation/Themes) — adding them here would duplicate the source of truth.
+### 2.2 CSS modes
 
-### 2.2 Default (neon) — illustrative
-
-```css
-@theme {
-  --color-primary:        oklch(0.452 0.313 264.1);
-  --color-secondary:      oklch(0.715 0.143 215.2);
-  --color-accent:         oklch(0.714 0.203 264.1);
-  --color-background:     oklch(0.141 0.005 285.9);
-  --color-foreground:     oklch(0.985 0 0);
-  --color-card:           oklch(0.212 0.006 285.9);
-  --color-border:         oklch(0.274 0.006 286);
-  --color-destructive:    oklch(0.577 0.245 27.3);
-  --color-success:        oklch(0.723 0.219 149.6);
-  --color-warning:        oklch(0.769 0.189 70.1);
-  --color-info:           oklch(0.623 0.214 259.1);
-
-  --color-primary-hover:  color-mix(in oklch, oklch(0.452 0.313 264.1), white 15%);
-  --color-primary-active: color-mix(in oklch, oklch(0.452 0.313 264.1), black 10%);
-
-  --radius-md: 0.375rem;
-  --font-sans: "Inter", ui-sans-serif, system-ui, sans-serif;
-  --transition-fast: 150ms cubic-bezier(0.4, 0, 0.2, 1);
-}
-```
+| Emit mode | Selector | Use |
+|-----------|----------|-----|
+| `global` (darkDefault) | `:root, .dark, html[data-brand]` | Dark-first single-skin demos |
+| `global` (light) | `:root, html[data-brand]` | Light packs — never bind `.dark` |
+| `scoped` | `html[data-brand]` only | `skins.css` multi-language catalog |
 
 ---
 
 ## 3. Patterns
 
-### 3.1 Wiring up a Next.js app
-
-```tsx
-// apps/{app}/src/app/globals.css
-@import "tailwindcss";
-@import "@nebutra/tokens/styles.css";   /* base tokens */
-@import "@nebutra/theme/themes.css";    /* multi-theme overrides */
+### 3.1 App wiring
 
-// apps/{app}/src/app/layout.tsx
-import { ThemeProvider } from "@nebutra/tokens";
-
-<ThemeProvider attribute="data-theme" defaultTheme="neon" themes={["neon","gradient","dark-dense","minimal","vibrant","ocean"]}>
-  {children}
-</ThemeProvider>
-```
-
-### 3.2 Switching themes at runtime
-
-```tsx
-"use client";
-import { useTheme } from "@nebutra/tokens";
-
-function ThemeSwitch() {
-  const { theme, setTheme } = useTheme();
-  return (
-    <select value={theme} onChange={(e) => setTheme(e.target.value)}>
-      <option value="neon">Neon</option>
-      <option value="gradient">Gradient</option>
-      <option value="dark-dense">Dark Dense</option>
-      <option value="minimal">Minimal</option>
-      <option value="vibrant">Vibrant</option>
-      <option value="ocean">Ocean</option>
-    </select>
-  );
-}
+```css
+@import "@nebutra/tokens/styles.css";
+@import "@nebutra/tokens/recipe.css";
+@import "@nebutra/theme/skins.css"; /* optional catalog */
 ```
 
-### 3.3 Adding a new theme
+```ts
+import { applyLanguage, clearLanguage } from "@nebutra/theme";
 
-1. Add the DTCG file under `packages/design/design-tokens/tokens/themes/my-theme.json`.
-2. Add the registry entry to `packages/design/theme/src/registry.json`.
-3. Provide every token defined in §2.
-4. Run `pnpm --filter @nebutra/design-tokens build` to regenerate theme CSS.
-5. Validate with theme tests, preset tests, and the CLI smoke checks.
-6. Add the playground/Storybook visual entry before publishing the theme.
-7. Open a PR; design-system maintainer reviews perceptual coherence, contrast, and component coverage.
-
----
+applyLanguage("vanta", { persist: true }); // built-in Brand Package
+clearLanguage(); // factory
+```
 
-## 4. Imports & Conventions
+### 3.2 Compile pipeline
 
-```css
-@import "@nebutra/theme/themes.css";
+```bash
+pnpm --filter @nebutra/tokens compile-brand -- ~/Desktop/Design-System/Foo --id foo
+# edit languages.json
+pnpm --filter @nebutra/theme sync:skins
 ```
 
-Themes are CSS at runtime, but their catalogue metadata is exported from `@nebutra/theme/registry`.
-Theme names are registry-derived; do not introduce new handwritten enums.
+### 3.3 Light/dark
 
-### Forbidden
+Independent of design-language **id**. Use `@nebutra/tokens` ThemeProvider (`class="dark"`).
 
-```tsx
-// ❌ Hardcoding theme-specific colors in components
-<div className="bg-[#7C3AED]" />
+| Pack shape | Emit behavior |
+|------------|----------------|
+| Single-mode (most fixtures) | One palette; `darkDefault` may bind `.dark` so dark shells keep the skin |
+| Dual-mode (`modes.light` + `modes.dark`) | Light under `:root` / `html[data-brand]`; dark under `.dark` / `html.dark[data-brand]` (e.g. **vercel**) |
 
-// ❌ Skipping a token override when defining a new theme
-[data-theme="my-theme"] { --color-primary: oklch(…); /* missing background, etc. */ }
-```
+Recipe, typography, and zones are shared across modes; only color roles/semantic flip.
 
 ---
 
-## 5. Theming (composition with light/dark)
-
-Light/dark and multi-theme are **orthogonal**:
+## 4. Anti-goals
 
-| `class` (next-themes) | `data-theme` (preset) | Result |
-|-----------------------|----------------------|--------|
-| (none) | (none) | base tokens from `@nebutra/tokens`, light |
-| `dark` | (none) | base tokens, dark variant |
-| (none) | `gradient` | gradient theme overrides |
-| `dark` | `dark-dense` | dark-dense theme overrides (dark by design) |
-
-Themes that define their own background/foreground supersede the `.dark` overrides for those tokens — designers should pick one mode per theme intent.
+- Do not treat 78 oklch moods as the product roadmap.
+- Do not dual-write root `@theme --color-primary` against tokens.
+- Do not map brand-mark into `--primary` for “branded buttons”.
+- Do not add a language that only changes hue without a new **capacity** proof.
 
 ---
 
-## 6. Versioning & Governance
-
-| Surface | Status |
-|--------|--------|
-| Default theme name (`neon`) | **Locked** |
-| Token *names* listed in §2 | **Locked** — every theme must define all of them |
-| Adding a new theme preset | Extensible — design-system maintainer review |
-| Renaming an existing theme | **Forbidden** without a migration alias |
-| Per-theme oklch values | Extensible — adjust freely with PR + visual diff |
-
-### Governance scripts
+## 5. Validation
 
 ```bash
 pnpm --filter @nebutra/theme test
-pnpm --filter @nebutra/theme typecheck
-pnpm --filter @nebutra/design-tokens build
-pnpm --filter @nebutra/preset test
-pnpm --filter nebutra build
-node packages/ops/cli/dist/index.js theme list --format json
-pnpm tsx scripts/validate-ui-governance-policy.ts
+pnpm --filter @nebutra/tokens test
+nebutra theme list
+nebutra theme inspect vanta
 ```
-
----
-
-## 7. Open questions / review notes
-
-- Per-theme oklch tables are not enumerated here to avoid duplicating `themes.css`. Storybook's Foundation/Themes panel is the canonical visual reference — add it if missing.
-
----
-
-← back to [root DESIGN.md](../../DESIGN.md) ·
-peer specs: [brand](../brand/DESIGN.md) · [tokens](../tokens/DESIGN.md) · [ui](../ui/DESIGN.md)