@lindaui/tokens 0.0.3 → 0.1.0

package/README.md

@@ -21,6 +21,51 @@ Toggle a `.dark` class on an ancestor (e.g. `<html class="dark">`). The dark
 palette redefines the canonical tokens; HeroUI's variables reference them, so
 components re-skin for free.
 
+## Custom theme (per project)
+
+Every consumer can ship its own brand without rebuilding this package or touching
+any component. The whole design system is driven by CSS custom properties read at
+runtime, so theming = overriding a small set of **canonical** variables.
+
+Copy the template, fill it with your brand, and import it **after** the base:
+
+```tsx
+import "@lindaui/tokens/css";   // HeroUI + utilities + default (teal) theme
+import "./theme.css";            // your brand — overrides the canonical vars
+```
+
+The template lists every overridable variable (for `:root` and `.dark`) with the
+defaults as a starting point:
+
+```bash
+# the template ships in the package:
+node -e "console.log(require.resolve('@lindaui/tokens/theme-template.css'))"
+```
+
+Only override the **canonical** vars (`--primary`, `--card`, `--secondary`,
+`--destructive`, `--ring`, `--radius`, `--chart-1..5`, ...). Do NOT touch the
+HeroUI vars (`--accent`/`--surface`/`--default`/`--danger`/...) or the utility
+vars (`--color-*`) — they reference the canonical ones and update automatically.
+Soft variants (`--accent-soft`, `--danger-soft`, ...) are derived from `--primary`
+/`--destructive` via `color-mix`, so they follow your brand for free.
+
+### Runtime-switchable themes
+
+For multiple themes in one app, switchable without reload (on top of dark/light),
+scope each theme under a selector instead of `:root` — the matrix is theme × mode:
+
+```css
+[data-theme="ocean"]      { --primary: oklch(0.55 0.13 240); --ring: oklch(0.55 0.13 240); /* ... */ }
+[data-theme="ocean"].dark { --primary: oklch(0.78 0.12 240); /* ... */ }
+```
+
+```js
+document.documentElement.dataset.theme = "ocean";       // switch theme
+document.documentElement.classList.toggle("dark");      // switch mode
+```
+
+The template's bottom section documents this pattern in full.
+
 ## Local build
 
 ```bash

package/dist/index.css

@@ -367,6 +367,9 @@
   .hidden {
     display: none;
   }
+  .inline {
+    display: inline;
+  }
   .inline-flex {
     display: inline-flex;
   }

package/llms.txt

@@ -33,8 +33,52 @@ That single import brings:
 Toggle a `.dark` class on any ancestor element. Only the canonical tokens are
 redefined in `.dark`; the HeroUI vars are references, so everything follows.
 
-## Notes for agents
+## Custom theme (per consuming project)
 
-- It is the only export: `@lindaui/tokens/css`. There is no JS entry point.
-- `@lindaui/ui` and `@lindaui/blocks` declare this as a peer — install it alongside.
-- If a layout looks unstyled ("just text"), the consumer usually forgot this import.
+Theming = overriding the **canonical** CSS vars; everything reads them at runtime, so
+no rebuild and no component changes. Override AFTER the base import:
+
+```tsx
+import "@lindaui/tokens/css";   // default (teal) theme
+import "./theme.css";            // your brand — wins by source order
+```
+
+```css
+/* theme.css — override ONLY canonical vars */
+:root { --primary: oklch(0.55 0.2 264); --primary-foreground: oklch(.98 0 0); --ring: oklch(0.55 0.2 264); --radius: 0.5rem; --chart-1: oklch(0.6 0.2 264); }
+.dark { --primary: oklch(0.72 0.16 264); --primary-foreground: oklch(.2 0 0); --ring: oklch(0.72 0.16 264); }
+```
+
+There are THREE var systems — override only (A):
+- **(A) canonical** (source of truth, override these): `--background`, `--foreground`,
+  `--card(-foreground)`, `--popover(-foreground)`, `--secondary(-foreground)`,
+  `--muted-foreground`, `--primary(-foreground)`, `--destructive`, `--success(-foreground)`,
+  `--warning(-foreground)`, `--border`, `--input`, `--ring`, `--radius`,
+  `--chart-1..5`, `--viewer-*`.
+- **(B) HeroUI** (`--accent`/`--surface`/`--default`/`--danger`/`--focus`/...) — refs to (A),
+  DO NOT override.
+- **(C) utilities** (`--color-*` from `@theme inline`) — refs to (A), DO NOT override.
+  Soft variants (`--accent-soft`/`--danger-soft`/...) are `color-mix` of (A), follow for free.
+
+A ready, commented starting point ships as `@lindaui/tokens/theme-template.css` — copy it
+into your project and fill in your brand. Resolve its path with
+`require.resolve('@lindaui/tokens/theme-template.css')`.
+
+### Runtime-switchable themes
+
+For multiple themes in one app (beyond dark/light), scope each theme under a selector
+instead of `:root` (matrix = theme × mode):
+
+```css
+[data-theme="ocean"]      { --primary: oklch(0.55 0.13 240); --ring: oklch(0.55 0.13 240); }
+[data-theme="ocean"].dark { --primary: oklch(0.78 0.12 240); }
+```
+
+Toggle with `document.documentElement.dataset.theme = "ocean"` + the `.dark` class.
+
+## Exports & notes for agents
+
+- `@lindaui/tokens/css` → the compiled stylesheet (the only thing you import for runtime).
+- `@lindaui/tokens/theme-template.css` → commented theme template to copy (not imported).
+- No JS entry point. `@lindaui/ui` and `@lindaui/blocks` declare this as a peer.
+- If a layout looks unstyled ("just text"), the consumer usually forgot the `/css` import.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lindaui/tokens",
-  "version": "0.0.3",
+  "version": "0.1.0",
   "description": "Brand design tokens (OKLCH light/dark) + HeroUI v3 + Tailwind v4 compiled into a single CSS bundle.",
   "author": "Franco Carballar <francocarballar@gmail.com>",
   "license": "MIT",
@@ -14,13 +14,15 @@
   },
   "type": "module",
   "exports": {
-    "./css": "./dist/index.css"
+    "./css": "./dist/index.css",
+    "./theme-template.css": "./theme-template.css"
   },
   "files": [
     "dist",
     "LICENSE",
     "README.md",
-    "llms.txt"
+    "llms.txt",
+    "theme-template.css"
   ],
   "devDependencies": {
     "tailwindcss": "^4.0.0",

package/theme-template.css

@@ -0,0 +1,126 @@
+/* ============================================================
+   @lindaui — THEME TEMPLATE (copiá este archivo a tu proyecto)
+
+   Cada proyecto consumidor define su marca pisando las variables
+   CANÓNICAS de abajo. NO necesitás rebuildear @lindaui/tokens ni tocar
+   componentes: HeroUI v3, los bespoke, las utilities (bg-primary, ...) y
+   los charts leen estas vars en runtime, así que re-skinean solos.
+
+   USO (orden importa — el tema va DESPUÉS de la base):
+     import "@lindaui/tokens/css";   // HeroUI + utilities + tema default
+     import "./theme.css";            // este archivo, con TUS valores
+
+   REGLA DE ORO: pisá SOLO las variables de este archivo (las "canónicas").
+   NO toques las de HeroUI (--accent/--surface/--default/--danger/--focus/...)
+   ni las utilities (--color-*): son referencias a estas y se actualizan solas.
+   Las variantes soft (--accent-soft, --danger-soft, ...) salen por color-mix
+   desde --primary/--destructive → cambian con tu marca automáticamente.
+
+   Los valores de acá son los DEFAULT (teal). Cambialos por los tuyos.
+   Color en OKLCH: oklch(L C H) — L 0..1 (luz), C croma, H 0..360 (matiz).
+   ============================================================ */
+
+:root {
+  /* ── Superficies + texto base ── */
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.145 0 0);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.145 0 0);
+  --secondary: oklch(0.97 0 0); /* superficie neutra (bg-secondary) */
+  --secondary-foreground: oklch(0.205 0 0);
+  --muted-foreground: oklch(0.556 0 0); /* texto atenuado (text-muted-foreground) */
+
+  /* ── Marca (lo más importante) ── */
+  --primary: oklch(0.47 0.097 183); /* <- TU color de marca */
+  --primary-foreground: oklch(0.985 0 0); /* texto sobre la marca */
+
+  /* ── Estado ── */
+  --destructive: oklch(0.577 0.245 27.325);
+  --success: oklch(0.59 0.163 148);
+  --success-foreground: oklch(1 0 0);
+  --warning: oklch(0.56 0.14 58);
+  --warning-foreground: oklch(1 0 0);
+
+  /* ── Bordes / input / foco / radio ── */
+  --border: oklch(0.922 0 0);
+  --input: oklch(0.922 0 0);
+  --ring: oklch(0.47 0.097 183); /* normalmente == --primary */
+  --radius: 0.625rem; /* escala sm/md/lg/xl... deriva de esto */
+
+  /* ── Paleta categórica de charts ── */
+  --chart-1: oklch(0.55 0.12 183);
+  --chart-2: oklch(0.6 0.12 220);
+  --chart-3: oklch(0.65 0.14 150);
+  --chart-4: oklch(0.72 0.15 80);
+  --chart-5: oklch(0.62 0.19 25);
+
+  /* ── Visor media (oscuro SIEMPRE; opcional, borralo si no usás image-viewer) ── */
+  --viewer-bg: oklch(0.22 0.027 214);
+  --viewer-foreground: oklch(0.88 0.012 220);
+  --viewer-border: oklch(0.3 0.025 214);
+
+  /* Tipografía: inyectá tus fuentes vía --font-sans / --font-mono / --font-heading
+     (ej. next/font expone --font-xxx). Si no, quedan los fallbacks del default. */
+}
+
+/* ── Dark mode: redefiní SOLO lo que cambia en oscuro (toggleás la clase .dark) ── */
+.dark {
+  --background: oklch(0.145 0 0);
+  --foreground: oklch(0.985 0 0);
+  --card: oklch(0.205 0 0);
+  --card-foreground: oklch(0.985 0 0);
+  --popover: oklch(0.205 0 0);
+  --popover-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.269 0 0);
+  --secondary-foreground: oklch(0.985 0 0);
+  --muted-foreground: oklch(0.708 0 0);
+  --primary: oklch(0.79 0.12 181); /* marca más brillante en dark */
+  --primary-foreground: oklch(0.205 0 0);
+  --destructive: oklch(0.704 0.191 22.216);
+  --success: oklch(0.7 0.16 150);
+  --success-foreground: oklch(0.205 0 0);
+  --warning: oklch(0.75 0.14 70);
+  --warning-foreground: oklch(0.205 0 0);
+  --border: oklch(1 0 0 / 10%);
+  --input: oklch(1 0 0 / 15%);
+  --ring: oklch(0.79 0.12 181);
+  --chart-1: oklch(0.7 0.13 183);
+  --chart-2: oklch(0.7 0.13 220);
+  --chart-3: oklch(0.72 0.15 150);
+  --chart-4: oklch(0.78 0.15 80);
+  --chart-5: oklch(0.7 0.18 25);
+}
+
+/* ============================================================
+   TEMAS CONMUTABLES EN RUNTIME (opcional)
+
+   Si querés varios temas en el MISMO proyecto, conmutables sin reload
+   (además de dark/light), scopeá cada tema bajo un selector en vez de
+   :root. La matriz es tema × modo. Toggleás el atributo data-theme en
+   <html> (o cualquier ancestro) y la clase .dark como siempre.
+
+   <html data-theme="ocean" class="dark">
+
+   Default (sin data-theme) = el bloque :root/.dark de arriba.
+   Cada tema extra define su light bajo [data-theme="x"] y su dark bajo
+   [data-theme="x"].dark. Solo necesitás repetir las vars que cambian.
+
+   [data-theme="ocean"] {
+     --primary: oklch(0.55 0.13 240);
+     --primary-foreground: oklch(0.985 0 0);
+     --ring: oklch(0.55 0.13 240);
+     --chart-1: oklch(0.6 0.14 240);
+     ...
+   }
+   [data-theme="ocean"].dark {
+     --primary: oklch(0.78 0.12 240);
+     --primary-foreground: oklch(0.205 0 0);
+     --ring: oklch(0.78 0.12 240);
+     ...
+   }
+
+   En JS: document.documentElement.dataset.theme = "ocean";  // cambiar
+          document.documentElement.classList.toggle("dark"); // modo
+   ============================================================ */