@marianmeres/design-tokens 1.0.0

package/AGENTS.md

@@ -0,0 +1,85 @@
+# @marianmeres/design-tokens — Agent Guide
+
+## Quick Reference
+- **Stack**: Deno / TypeScript
+- **Run**: `deno task test` | **Watch**: `deno task test:watch`
+- **Build (npm)**: `deno task npm:build`
+- **Publish**: `deno task publish` (JSR + npm)
+- **Format**: `deno fmt` (tabs, 90 chars, indent 4)
+
+## What This Package Does
+
+CSS custom property generator for design token systems. Takes a structured
+`ThemeSchema` (light + optional dark mode) and produces CSS `--custom-property`
+declarations with automatic hover/active state derivation via `color-mix()`.
+
+Three entry points:
+- `.` — core generation functions, types, color palette
+- `./reboot` — Bootstrap Reboot `--bs-*` variable bridge
+- `./themes` — 31 pre-built theme definitions
+
+## Project Structure
+
+```
+/src
+  mod.ts              — main entry: re-exports functions, types, colors
+  types.ts            — core type definitions (ThemeSchema, TokenSchema, etc.)
+  generate.ts         — token generation + CSS output (generateCssTokens, toCssString, generateThemeCss)
+  utils.ts            — hex color parsing (hexToRgb, hexToRgbTriplet)
+  colors.ts           — complete Tailwind v3 color palette (hex values)
+  reboot-bridge.ts    — Bootstrap Reboot --bs-* variable mapping
+  /themes
+    mod.ts            — re-exports all theme definitions
+    *.ts              — individual theme files (default export: ThemeSchema)
+/tests                — test files (deno test --allow-read)
+/scripts              — npm build script
+/theme-preview-builder — HTML preview tool
+```
+
+## Public API Surface
+
+### Functions (from `./src/mod.ts`)
+| Function | Purpose |
+|----------|---------|
+| `generateCssTokens(schema, prefix, mode?)` | Generate token key-value pairs from a TokenSchema |
+| `toCssString(tokens, selector?)` | Convert tokens to a CSS declaration block |
+| `generateThemeCss(schema, prefix)` | Generate complete CSS for light + optional dark mode |
+| `hexToRgb(hex)` | Parse hex to `[r, g, b]` tuple |
+| `hexToRgbTriplet(hex)` | Convert hex to `"r, g, b"` string |
+
+### Functions (from `./reboot`)
+| Function | Purpose |
+|----------|---------|
+| `generateRebootBridge(tokens, prefix)` | Map tokens to `--bs-*` variables |
+| `generateThemedCss(schema, prefix)` | Combined tokens + reboot bridge CSS |
+
+### Key Types
+| Type | Purpose |
+|------|---------|
+| `ThemeSchema` | `{ light: TokenSchema; dark?: TokenSchema }` |
+| `TokenSchema` | Intent colors, role paired/single colors |
+| `ColorPair` | `{ DEFAULT, foreground, hover?, active? }` |
+| `ColorValue` | `{ DEFAULT, hover?, active? }` |
+| `SingleColor` | `string \| ColorValue` |
+| `GeneratedTokens` | `Record<string, string>` |
+
+### Constants
+| Export | Purpose |
+|--------|---------|
+| `colors` | Complete Tailwind v3 hex palette (`colors.blue[600]`) |
+
+## Critical Conventions
+
+1. All public functions must have JSDoc and explicit return types (Deno/JSR requirement)
+2. Token naming: `--{prefix}color-{key}`, `--{prefix}color-{key}-hover`, etc.
+3. Hover/active auto-derived via `color-mix(in oklch, ...)` — light darkens with black, dark lightens with white
+4. Surface-intent tokens derived via `color-mix(in srgb, ...)` from intent + background
+5. Theme files use `export default` with `ThemeSchema` type annotation
+6. Formatting: tabs, 90-char line width, 4-space indent width (`deno fmt`)
+
+## Before Making Changes
+
+- [ ] Read existing patterns in similar files
+- [ ] Run `deno task test` — all 37 tests must pass
+- [ ] Follow `deno fmt` conventions
+- [ ] Ensure new exports have JSDoc + explicit return types

package/API.md

@@ -0,0 +1,271 @@
+# API
+
+## Functions
+
+### `generateCssTokens(schema, prefix, mode?)`
+
+Generate CSS token key-value pairs from a single-mode token schema.
+
+**Parameters:**
+- `schema` (`TokenSchema`) — Color definitions for intent, role paired, and role single colors
+- `prefix` (`string`) — CSS variable prefix (e.g. `"my-"` produces `--my-color-primary`)
+- `mode` (`"light" | "dark"`, optional) — Affects auto-derivation direction. Light darkens with black, dark lightens with white. Default: `"light"`
+
+**Returns:** `GeneratedTokens` — Key-value record of token names to CSS values (keys without the `--` prefix)
+
+**Example:**
+```typescript
+import { generateCssTokens } from "@marianmeres/design-tokens";
+
+const tokens = generateCssTokens(schema.light, "app-", "light");
+// { "app-color-primary": "#2563eb", "app-color-primary-hover": "color-mix(...)", ... }
+```
+
+---
+
+### `toCssString(tokens, selector?)`
+
+Convert a tokens record to a formatted CSS declaration block, grouped by base color name.
+
+**Parameters:**
+- `tokens` (`GeneratedTokens`) — Key-value token pairs (from `generateCssTokens`)
+- `selector` (`string`, optional) — CSS selector for the block. Default: `":root"`
+
+**Returns:** `string` — Formatted CSS string
+
+**Example:**
+```typescript
+import { generateCssTokens, toCssString } from "@marianmeres/design-tokens";
+
+const css = toCssString(tokens, ":root.dark");
+// :root.dark {
+//     --app-color-primary: #2563eb;
+//     ...
+// }
+```
+
+---
+
+### `generateThemeCss(schema, prefix)`
+
+Generate complete CSS for a theme with light mode and optional dark mode.
+
+**Parameters:**
+- `schema` (`ThemeSchema`) — Theme with required `light` and optional `dark` token schemas
+- `prefix` (`string`) — CSS variable prefix
+
+**Returns:** `string` — Complete CSS with `:root` for light and `:root.dark` for dark mode
+
+**Example:**
+```typescript
+import { generateThemeCss } from "@marianmeres/design-tokens";
+import { zinc } from "@marianmeres/design-tokens/themes";
+
+const css = generateThemeCss(zinc, "app-");
+```
+
+---
+
+### `hexToRgb(hex)`
+
+Parse a hex color string to RGB components. Supports 3-digit (`#abc`) and 6-digit (`#aabbcc`) formats, with or without `#` prefix.
+
+**Parameters:**
+- `hex` (`string`) — Hex color string
+
+**Returns:** `[number, number, number] | null` — RGB tuple, or `null` if invalid
+
+**Example:**
+```typescript
+import { hexToRgb } from "@marianmeres/design-tokens";
+
+hexToRgb("#2563eb"); // → [37, 99, 235]
+hexToRgb("fff");     // → [255, 255, 255]
+hexToRgb("nope");    // → null
+```
+
+---
+
+### `hexToRgbTriplet(hex)`
+
+Convert a hex color to an `"r, g, b"` triplet string suitable for CSS `rgb()` usage.
+
+**Parameters:**
+- `hex` (`string`) — Hex color string
+
+**Returns:** `string | null` — Comma-separated RGB triplet, or `null` if invalid
+
+**Example:**
+```typescript
+import { hexToRgbTriplet } from "@marianmeres/design-tokens";
+
+hexToRgbTriplet("#2563eb"); // → "37, 99, 235"
+```
+
+---
+
+### `generateRebootBridge(tokens, prefix)`
+
+*Import from `@marianmeres/design-tokens/reboot`*
+
+Map design tokens to Bootstrap Reboot `--bs-*` CSS variables. Automatically generates `-rgb` triplet companions for hex color values.
+
+**Parameters:**
+- `tokens` (`GeneratedTokens`) — Generated token pairs (from `generateCssTokens`)
+- `prefix` (`string`) — The same prefix used in `generateCssTokens`
+
+**Returns:** `GeneratedTokens` — Bootstrap bridge variables (`bs-body-bg`, `bs-link-color`, etc.)
+
+---
+
+### `generateThemedCss(schema, prefix)`
+
+*Import from `@marianmeres/design-tokens/reboot`*
+
+Generate complete themed CSS including both design tokens AND the Bootstrap Reboot bridge.
+
+**Parameters:**
+- `schema` (`ThemeSchema`) — Theme schema with light and optional dark modes
+- `prefix` (`string`) — CSS variable prefix
+
+**Returns:** `string` — Combined CSS with token variables and `--bs-*` bridge variables
+
+**Example:**
+```typescript
+import { generateThemedCss } from "@marianmeres/design-tokens/reboot";
+import { zinc } from "@marianmeres/design-tokens/themes";
+
+const css = generateThemedCss(zinc, "app-");
+// → :root { --app-color-primary: ...; --bs-body-bg: ...; --bs-link-color: ...; }
+```
+
+---
+
+## Types
+
+### `ThemeSchema`
+
+```typescript
+type ThemeSchema = {
+    light: TokenSchema;
+    dark?: TokenSchema;
+};
+```
+
+Complete theme definition with required light mode and optional dark mode.
+
+---
+
+### `TokenSchema`
+
+```typescript
+type TokenSchema = {
+    colors: {
+        intent: WithRequired<IntentColorKey, ColorPair>;
+        role: {
+            paired: WithRequired<RolePairedKey, ColorPair>;
+            single: WithRequired<RoleSingleKey, SingleColor>;
+        };
+    };
+};
+```
+
+Single-mode token schema. Intent colors define primary UI actions; role colors define structural UI elements.
+
+---
+
+### `ColorPair`
+
+```typescript
+type ColorPair = {
+    DEFAULT: string;
+    foreground: string;
+    hover?: string;
+    active?: string;
+};
+```
+
+Color with a foreground companion. Hover/active are auto-derived when omitted.
+
+---
+
+### `ColorValue`
+
+```typescript
+type ColorValue = {
+    DEFAULT: string;
+    hover?: string;
+    active?: string;
+};
+```
+
+Color with optional pseudo states.
+
+---
+
+### `SingleColor`
+
+```typescript
+type SingleColor = string | ColorValue;
+```
+
+Either a plain CSS color string or an object with optional hover/active states.
+
+---
+
+### `GeneratedTokens`
+
+```typescript
+type GeneratedTokens = Record<string, string>;
+```
+
+Generated CSS token key-value pairs (keys without the `--` prefix).
+
+---
+
+### `IntentColorKey`
+
+```typescript
+type IntentColorKey = "primary" | "accent" | "destructive" | "warning" | "success";
+```
+
+---
+
+### `RolePairedKey`
+
+```typescript
+type RolePairedKey = "background" | "muted" | "surface";
+```
+
+---
+
+### `RoleSingleKey`
+
+```typescript
+type RoleSingleKey = "foreground" | "border" | "input" | "ring";
+```
+
+---
+
+## Constants
+
+### `colors`
+
+Complete Tailwind CSS v3 color palette as hex values. Contains `black`, `white`, and 22 color scales (slate, gray, zinc, neutral, stone, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose) each with shades 50–950.
+
+```typescript
+import { colors } from "@marianmeres/design-tokens";
+
+colors.blue[600]   // → "#2563eb"
+colors.white        // → "#ffffff"
+```
+
+---
+
+## Bundled Themes
+
+*Import from `@marianmeres/design-tokens/themes`*
+
+31 pre-built `ThemeSchema` definitions, each with light + dark mode:
+
+`blueOrange`, `cyanRed`, `cyanSlate`, `emeraldAmberForest`, `emeraldPink`, `fuchsiaEmerald`, `gray`, `indigoAmber`, `limeFuchsiaNeon`, `monokaiCyan`, `monokaiGreen`, `monokaiPink`, `orangePinkSunset`, `pinkEmerald`, `pinkTeal`, `purpleYellow`, `rainbow`, `redBlue`, `redCyan`, `redSky`, `redSkySlate`, `roseTeal`, `skyAmber`, `slateCyan`, `slateTealOcean`, `stone`, `stoneOrangeEarth`, `tealRose`, `violetLime`, `violetRoseDusk`, `zinc`

package/CLAUDE.md

@@ -0,0 +1,3 @@
+# Project Instructions
+
+See [AGENTS.md](./AGENTS.md) for complete project documentation and AI agent instructions.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marian Meres
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,139 @@
+# @marianmeres/design-tokens
+
+[![JSR](https://jsr.io/badges/@marianmeres/design-tokens)](https://jsr.io/@marianmeres/design-tokens)
+[![License](https://img.shields.io/github/license/marianmeres/design-tokens)](LICENSE)
+
+A standalone CSS custom property generator for design token systems. Takes a structured
+color token schema and produces CSS variables for light and dark modes, with automatic
+hover/active state derivation using `color-mix()`. Ships an optional Bootstrap Reboot
+bridge that maps tokens to `--bs-*` variables. Same mental model as
+[@marianmeres/stuic](https://github.com/marianmeres/stuic)'s token system, but
+framework-agnostic — no Tailwind dependency.
+
+## Install
+
+```sh
+deno add jsr:@marianmeres/design-tokens
+```
+
+## Usage
+
+```ts
+import { generateThemeCss } from "@marianmeres/design-tokens";
+import type { ThemeSchema } from "@marianmeres/design-tokens";
+
+const theme: ThemeSchema = {
+	light: {
+		colors: {
+			intent: {
+				primary: { DEFAULT: "#2563eb", foreground: "#ffffff" },
+				accent: { DEFAULT: "#8b5cf6", foreground: "#ffffff" },
+				destructive: { DEFAULT: "#dc2626", foreground: "#ffffff" },
+				warning: { DEFAULT: "#f59e0b", foreground: "#000000" },
+				success: { DEFAULT: "#16a34a", foreground: "#ffffff" },
+			},
+			role: {
+				paired: {
+					background: { DEFAULT: "#ffffff", foreground: "#171717" },
+					muted: { DEFAULT: "#f5f5f5", foreground: "#737373" },
+					surface: { DEFAULT: "#e5e5e5", foreground: "#171717" },
+				},
+				single: {
+					foreground: "#171717",
+					border: { DEFAULT: "#d4d4d4" },
+					input: { DEFAULT: "#ffffff" },
+					ring: "color-mix(in srgb, #2563eb 25%, transparent)",
+				},
+			},
+		},
+	},
+};
+
+const css = generateThemeCss(theme, "my-");
+// → :root { --my-color-primary: #2563eb; ... }
+```
+
+## Creating a custom theme
+
+Use the bundled `colors` map (complete Tailwind v3 palette) to avoid looking up hex values:
+
+```ts
+import { colors, generateThemeCss } from "@marianmeres/design-tokens";
+import type { ThemeSchema } from "@marianmeres/design-tokens";
+
+const myTheme: ThemeSchema = {
+	light: {
+		colors: {
+			intent: {
+				primary: { DEFAULT: colors.blue[600], foreground: colors.white },
+				accent: { DEFAULT: colors.violet[500], foreground: colors.white },
+				destructive: { DEFAULT: colors.red[600], foreground: colors.white },
+				warning: { DEFAULT: colors.amber[500], foreground: colors.black },
+				success: { DEFAULT: colors.emerald[600], foreground: colors.white },
+			},
+			role: {
+				paired: {
+					background: {
+						DEFAULT: colors.slate[50],
+						foreground: colors.slate[900],
+					},
+					muted: {
+						DEFAULT: colors.slate[100],
+						foreground: colors.slate[500],
+					},
+					surface: {
+						DEFAULT: colors.slate[200],
+						foreground: colors.slate[900],
+					},
+				},
+				single: {
+					foreground: colors.slate[900],
+					border: { DEFAULT: colors.slate[300] },
+					input: { DEFAULT: colors.slate[50], hover: colors.slate[100] },
+					ring: `color-mix(in srgb, ${colors.blue[600]} 25%, transparent)`,
+				},
+			},
+		},
+	},
+	// dark: { ... }  // optional
+};
+
+const css = generateThemeCss(myTheme, "my-");
+```
+
+Hover/active states are auto-derived via `color-mix(in oklch, ...)` when omitted. You can
+provide explicit values to override the derivation.
+
+## Bundled themes
+
+```ts
+import { gray, stone, zinc } from "@marianmeres/design-tokens/themes";
+import { generateThemeCss } from "@marianmeres/design-tokens";
+
+const css = generateThemeCss(zinc, "app-");
+```
+
+## Reboot bridge
+
+Maps design tokens to Bootstrap Reboot's `--bs-*` CSS variables:
+
+```ts
+import { generateThemedCss } from "@marianmeres/design-tokens/reboot";
+import { zinc } from "@marianmeres/design-tokens/themes";
+
+const css = generateThemedCss(zinc, "app-");
+// → :root { --app-color-primary: ...; --bs-body-bg: ...; --bs-link-color: ...; }
+```
+
+## API
+
+See [API.md](API.md) for the complete API documentation.
+
+## Types
+
+See [src/types.ts](src/types.ts) for the full type definitions (`TokenSchema`,
+`ThemeSchema`, `ColorPair`, `ColorValue`, etc.).
+
+## License
+
+[MIT](LICENSE)