hextimator 0.1.0

package/dist/react.js

@@ -0,0 +1,245 @@
+import {
+  hextimate
+} from "./chunk-MBVLFPTG.js";
+
+// src/react.tsx
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  useSyncExternalStore
+} from "react";
+import { jsx } from "react/jsx-runtime";
+function buildStyleContent(palette, darkMode, cssPrefix) {
+  const lightEntries = Object.entries(palette.light);
+  const darkEntries = Object.entries(palette.dark);
+  const toVars = (entries) => entries.map(([key, value]) => `${cssPrefix}${key}: ${value};`).join("\n  ");
+  const lightVars = toVars(lightEntries);
+  const darkVars = toVars(darkEntries);
+  if (darkMode === false) {
+    return `:root {
+  ${lightVars}
+}`;
+  }
+  if (darkMode.type === "media") {
+    return [
+      `:root {
+  ${lightVars}
+}`,
+      `@media (prefers-color-scheme: dark) {
+  :root {
+    ${darkVars}
+  }
+}`
+    ].join("\n");
+  }
+  if (darkMode.type === "media-or-class") {
+    const cls = darkMode.className ?? "dark";
+    const lightCls = cls === "dark" ? "light" : `not-${cls}`;
+    return [
+      `:root {
+  ${lightVars}
+}`,
+      `@media (prefers-color-scheme: dark) {
+  :root:not(.${lightCls}) {
+    ${darkVars}
+  }
+}`,
+      `:root.${cls} {
+  ${darkVars}
+}`
+    ].join("\n");
+  }
+  if (darkMode.type === "class") {
+    const cls = darkMode.className ?? "dark";
+    return [`:root {
+  ${lightVars}
+}`, `.${cls} {
+  ${darkVars}
+}`].join(
+      "\n"
+    );
+  }
+  const attr = darkMode.attribute ?? "data-theme";
+  return [
+    `:root {
+  ${lightVars}
+}`,
+    `[${attr}="dark"] {
+  ${darkVars}
+}`
+  ].join("\n");
+}
+function buildTargetedVars(palette, darkMode, cssPrefix) {
+  const prefixEntries = (entries) => entries.map(
+    ([key, value]) => [`${cssPrefix}${key}`, value]
+  );
+  return {
+    light: prefixEntries(
+      Object.entries(palette.light)
+    ),
+    dark: darkMode !== false ? prefixEntries(Object.entries(palette.dark)) : []
+  };
+}
+function useStableOptions(options) {
+  const ref = useRef(options);
+  const serialized = JSON.stringify({
+    generation: options?.generation,
+    format: options?.format,
+    darkMode: options?.darkMode,
+    cssPrefix: options?.cssPrefix
+  });
+  if (serialized !== JSON.stringify({
+    generation: ref.current?.generation,
+    format: ref.current?.format,
+    darkMode: ref.current?.darkMode,
+    cssPrefix: ref.current?.cssPrefix
+  })) {
+    ref.current = options;
+  }
+  return ref.current;
+}
+function useHextimator(color, options) {
+  const stable = useStableOptions(options);
+  const configure = options?.configure;
+  const target = options?.target;
+  const palette = useMemo(() => {
+    const builder = hextimate(color, stable?.generation);
+    configure?.(builder);
+    return builder.format({
+      ...stable?.format,
+      as: "css"
+    });
+  }, [color, stable?.generation, stable?.format, configure]);
+  const darkMode = stable?.darkMode ?? { type: "media" };
+  const cssPrefix = stable?.cssPrefix ?? "";
+  useEffect(() => {
+    const el = target?.current;
+    if (el) {
+      const vars = buildTargetedVars(palette, darkMode, cssPrefix);
+      for (const [key, value] of vars.light) {
+        el.style.setProperty(key, value);
+      }
+      return () => {
+        for (const [key] of vars.light) {
+          el.style.removeProperty(key);
+        }
+      };
+    }
+    const style = document.createElement("style");
+    style.setAttribute("data-hextimator", "");
+    style.textContent = buildStyleContent(palette, darkMode, cssPrefix);
+    document.head.appendChild(style);
+    return () => {
+      document.head.removeChild(style);
+    };
+  }, [palette, darkMode, cssPrefix, target]);
+  return palette;
+}
+var darkQuery = typeof window !== "undefined" ? window.matchMedia("(prefers-color-scheme: dark)") : null;
+function useOsPrefersDark() {
+  return useSyncExternalStore(
+    (cb) => {
+      if (!darkQuery) return () => {
+      };
+      darkQuery.addEventListener("change", cb);
+      return () => darkQuery.removeEventListener("change", cb);
+    },
+    () => darkQuery?.matches ?? false,
+    () => false
+  );
+}
+function applyModeToDOM(mode, darkMode) {
+  if (typeof document === "undefined") return;
+  if (darkMode === false || darkMode.type === "media") return;
+  const root = document.documentElement;
+  if (darkMode.type === "data") {
+    const attr = darkMode.attribute ?? "data-theme";
+    if (mode) {
+      root.setAttribute(attr, mode);
+    } else {
+      root.removeAttribute(attr);
+    }
+    return;
+  }
+  const cls = darkMode.className ?? "dark";
+  const lightCls = cls === "dark" ? "light" : `not-${cls}`;
+  root.classList.remove(cls, lightCls);
+  if (mode) {
+    root.classList.add(mode === "dark" ? cls : lightCls);
+  }
+}
+var HextimatorContext = createContext(null);
+function HextimatorProvider({
+  children,
+  defaultColor,
+  defaultMode: initialMode = "system",
+  generation: initialGeneration,
+  format: formatOpts,
+  configure: initialConfigure,
+  darkMode,
+  cssPrefix,
+  target
+}) {
+  const [color, setColor] = useState(defaultColor);
+  const [modePreference, setMode] = useState(initialMode);
+  const [generation, setGeneration] = useState(initialGeneration);
+  const [configure, setConfigureState] = useState(() => initialConfigure);
+  const osDark = useOsPrefersDark();
+  const mode = modePreference === "system" ? osDark ? "dark" : "light" : modePreference;
+  const resolvedDarkMode = darkMode ?? { type: "media" };
+  useEffect(() => {
+    applyModeToDOM(
+      modePreference === "system" ? null : modePreference,
+      resolvedDarkMode
+    );
+  }, [modePreference, resolvedDarkMode]);
+  const setConfigure = useCallback(
+    (fn) => {
+      setConfigureState(() => fn);
+    },
+    []
+  );
+  const palette = useHextimator(color, {
+    generation,
+    format: formatOpts,
+    configure,
+    darkMode,
+    cssPrefix,
+    target
+  });
+  const value = useMemo(
+    () => ({
+      color,
+      setColor,
+      mode,
+      modePreference,
+      setMode,
+      generation,
+      setGeneration,
+      configure,
+      setConfigure,
+      palette
+    }),
+    [color, mode, modePreference, generation, configure, setConfigure, palette]
+  );
+  return /* @__PURE__ */ jsx(HextimatorContext.Provider, { value, children });
+}
+function useHextimatorTheme() {
+  const ctx = useContext(HextimatorContext);
+  if (!ctx) {
+    throw new Error(
+      "useHextimatorTheme must be used within a <HextimatorProvider>"
+    );
+  }
+  return ctx;
+}
+export {
+  HextimatorProvider,
+  useHextimator,
+  useHextimatorTheme
+};

package/llms.txt

@@ -0,0 +1,289 @@
+# hextimator
+
+> Generate perceptually uniform color palettes with light/dark themes and WCAG contrast guarantees from a single brand color. Outputs CSS variables, Tailwind tokens, SCSS variables, JSON, or plain objects. Designed for runtime use in multi-tenant apps.
+
+## Install
+
+```bash
+npm install hextimator
+```
+
+## Quick start
+
+```typescript
+import { hextimate } from "hextimator";
+
+// Minimal: one color in, full theme out
+const theme = hextimate("#6A5ACD").format();
+// → { light: { accent: "#6a5acd", "accent-strong": "...", ... }, dark: { ... } }
+
+// With format options
+const css = hextimate("#6A5ACD").format({ as: "css", colors: "oklch" });
+// → { light: { "--accent": "oklch(...)", ... }, dark: { ... } }
+```
+
+## API
+
+### `hextimate(color, options?)`
+
+Creates a palette builder from any color input.
+
+- `color`: `string` (hex, CSS function), `[r, g, b]` tuple, `number` (0xFF6666), or a `Color` object
+- `options`: `HextimateGenerationOptions` (see below)
+- Returns: `HextimatePaletteBuilder` (chainable)
+- Throws: `HextimateError` on invalid input
+
+### Builder methods (all return `this`, chainable)
+
+| Method | Description |
+|---|---|
+| `.addRole(name, color)` | Add a new color role with DEFAULT, strong, weak, foreground variants |
+| `.addVariant(name, placement)` | Add a lightness step to every role. `placement`: `{ from: "strong" }`, `{ from: "weak" }`, or `{ between: ["DEFAULT", "weak"] }` |
+| `.addToken(name, value)` | Add a standalone derived token. `value`: a color, `{ from: "role.variant", emphasis?, lightness?, chroma?, hue? }`, or `{ light: ..., dark: ... }` for per-theme values. `emphasis` is theme-aware (positive = more contrast, negative = softer) |
+| `.preset(preset)` | Apply a framework preset (e.g. `presets.shadcn`). Preset format defaults are overridden by `.format()` options |
+| `.simulate(cvdType, severity?)` | Simulate color vision deficiency. Types: `protanopia`, `deuteranopia`, `tritanopia`, `achromatopsia` |
+| `.adaptFor(cvdType, severity?)` | Optimize palette for a CVD type (use instead of simulate for actual accessibility) |
+| `.fork(color?, options?)` | Clone builder with optional new color/options. Original unchanged |
+| `.format(options?)` | Output the palette (see format options) |
+
+### `.format(options?)` → `{ light: FormatResult, dark: FormatResult }`
+
+| Option | Values | Default |
+|---|---|---|
+| `as` | `"object"`, `"css"`, `"tailwind"`, `"tailwind-css"`, `"scss"`, `"json"` | `"object"` |
+| `colors` | `"hex"`, `"rgb"`, `"rgb-raw"`, `"hsl"`, `"hsl-raw"`, `"oklch"`, `"oklch-raw"`, `"p3"`, `"p3-raw"` | `"hex"` |
+| `roleNames` | `Record<string, string>` — rename roles in output keys | built-in names |
+| `variantNames` | `Record<string, string>` — rename variant suffixes | built-in names |
+| `separator` | `string` — between role and variant in keys | `"-"` |
+
+Output shape depends on `as`:
+- `"object"` → `Record<string, string>` flat map: `{ accent: "#...", "accent-strong": "#..." }`
+- `"css"` → `Record<string, string>` flat map: `{ "--accent": "#...", "--accent-strong": "#..." }`
+- `"tailwind"` → nested map: `{ accent: { DEFAULT: "#...", strong: "#..." } }`
+- `"tailwind-css"` → string: `@theme { --color-accent: #...; }`
+- `"scss"` → `Record<string, string>` flat map: `{ "$accent": "#...", "$accent-strong": "#..." }`
+- `"json"` → JSON string
+
+### Generation options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `baseColor` | color input | auto-derived | Override base/neutral baseline color |
+| `baseHueShift` | degrees | `0` | Rotate base hue relative to accent. Ignored if `baseColor` set |
+| `invertDarkModeBaseAccent` | boolean | `false` | Swap base/accent hues in dark mode. Useful when the accent should become the background in dark mode. Requires `baseColor` |
+| `semanticColors` | `{ positive?, negative?, warning? }` | auto | Override semantic colors (green/red/amber) |
+| `semanticColorRanges` | `{ positive?: [start,end], ... }` | greens, reds, ambers | Hue ranges for semantic detection |
+| `baseMaxChroma` | number | `0.01` | Max chroma for base colors |
+| `foregroundMaxChroma` | number | `0.01` | Max chroma for foreground colors |
+| `light` | `{ lightness?, maxChroma? }` | `{ lightness: 0.7 }` | Light theme adjustments |
+| `dark` | `{ lightness?, maxChroma? }` | `{ lightness: 0.6 }` | Dark theme adjustments |
+| `minContrastRatio` | `"AAA"`, `"AA"`, or number | `"AAA"` | WCAG contrast target (AAA=7, AA=4.5) |
+| `hueShift` | degrees | `0` | Per-variant hue rotation |
+
+### Default palette structure
+
+Every palette includes 5 roles × 4 variants = 20 tokens:
+
+- Roles: `base`, `accent`, `positive`, `negative`, `warning`
+- Variants: `DEFAULT` (no suffix), `strong`, `weak`, `foreground`
+
+Token keys: `accent`, `accent-strong`, `accent-weak`, `accent-foreground`, `base`, `base-strong`, ...
+
+### Presets
+
+```typescript
+import { hextimate, presets } from "hextimator";
+
+const theme = hextimate("#6366F1")
+  .preset(presets.shadcn)
+  .format();
+
+// Override preset defaults:
+const theme = hextimate("#6366F1")
+  .preset(presets.shadcn)
+  .format({ colors: "hsl-raw" });
+```
+
+The shadcn preset adds tokens like foreground, card, popover, secondary, muted, border, input, ring, and renames roles (base→background, accent→primary, negative→destructive, positive→success).
+
+### Standalone tokens with per-theme values
+
+```typescript
+hextimate("#6366F1")
+  .addToken("border", {
+    light: { from: "base.weak", lightness: -0.08 },
+    dark: { from: "base.weak", lightness: +0.08 },
+  })
+  .addToken("ring", { from: "accent" })
+  .format({ as: "css" });
+```
+
+### Utility exports
+
+```typescript
+import { parseColor, convertColor } from "hextimator";
+
+const color = parseColor("rgb(255, 102, 102)");  // → Color object (sRGB)
+const oklch = convertColor(color, "oklch");       // → OKLCH object
+```
+
+Also exported: `daltonizeColor(color, cvdType, severity?)`, `simulateColor(color, cvdType, severity?)`.
+
+### Color input formats
+
+All of these are valid:
+
+```typescript
+hextimate("#FF6666");            // hex string
+hextimate("FF6666");             // hex without #
+hextimate("rgb(255, 102, 102)"); // CSS function
+hextimate("hsl(0, 100%, 70%)"); // CSS HSL
+hextimate([255, 102, 102]);      // RGB tuple
+hextimate(0xff6666);             // numeric hex
+```
+
+Alpha is always ignored (forced to 1) to preserve contrast guarantees.
+
+## CLI
+
+```bash
+npx hextimator <color> [options]
+```
+
+| Flag | Description | Default |
+|---|---|---|
+| `-f, --format` | `css`, `object`, `tailwind`, `tailwind-css`, `scss`, `json` | `css` |
+| `-c, --colors` | `hex`, `rgb`, `rgb-raw`, `hsl`, `hsl-raw`, `oklch`, `oklch-raw`, `p3`, `p3-raw` | `hex` |
+| `-t, --theme` | `light`, `dark`, `both` | `both` |
+| `-p, --preset` | Apply preset (e.g. `shadcn`) | — |
+| `--separator` | Token separator between role and variant | `-` |
+| `--base-color` | Override base color | — |
+| `--base-hue-shift` | Degrees | `0` |
+| `--hue-shift` | Per-variant hue shift | `0` |
+| `--base-max-chroma` | Max chroma for base | `0.01` |
+| `--fg-max-chroma` | Max chroma for foreground | `0.01` |
+| `--light-lightness` | Light theme lightness 0-1 | `0.7` |
+| `--light-max-chroma` | Light theme max chroma | — |
+| `--dark-lightness` | Dark theme lightness 0-1 | `0.6` |
+| `--dark-max-chroma` | Dark theme max chroma | — |
+| `--min-contrast` | `AAA`, `AA`, or number | `AAA` |
+| `--invert-dark` | Swap base/accent hues in dark mode (requires --base-color) | — |
+| `--positive` | Override positive/success color | auto |
+| `--negative` | Override negative/error color | auto |
+| `--warning` | Override warning color | auto |
+| `--simulate` | Simulate CVD: `protanopia`, `deuteranopia`, `tritanopia`, `achromatopsia` | — |
+| `--adapt` | Adapt palette for CVD type | — |
+| `--cvd-severity` | CVD severity 0-1 | `1` |
+| `--role <name>=<color>` | Add custom role (repeatable) | — |
+| `--variant <spec>` | Add variant: `name:from:edge` or `name:between:a,b` (repeatable) | — |
+| `-o, --output <path>` | Write to file instead of stdout | stdout |
+
+```bash
+# Generate CSS palette
+npx hextimator "#6A5ACD" --format css --colors oklch
+
+# shadcn/ui preset
+npx hextimator "#6366F1" --preset shadcn
+
+# Invert base/accent in dark mode
+npx hextimator "#6A5ACD" --base-color "#FEBA5D" --invert-dark
+
+# Custom roles and variants
+npx hextimator "#22aa44" --role cta=#ee2244 --variant hover:from:strong -o theme.css
+
+# Simulate color blindness
+npx hextimator "#ff6600" --simulate deuteranopia
+
+# Adapt for color blindness
+npx hextimator "#ff6600" --adapt deuteranopia --cvd-severity 0.8
+```
+
+## React
+
+```typescript
+import { useHextimator } from "hextimator/react";
+
+function App() {
+  useHextimator("#6A5ACD");
+  return <div className="bg-accent text-accent-foreground">Themed!</div>;
+}
+```
+
+Dark mode strategies: `{ type: "media" }` (default), `{ type: "class" }`, `{ type: "data" }`, or `false`.
+
+Options: `generation`, `format`, `configure` (access builder), `darkMode`, `cssPrefix`, `target` (ref for scoped theming).
+
+Provider for app-wide theming:
+
+```typescript
+import { HextimatorProvider, useHextimatorTheme } from "hextimator/react";
+
+// Wrap app
+<HextimatorProvider defaultColor="#6A5ACD">
+  <App />
+</HextimatorProvider>
+
+// In children — setColor triggers re-generation
+const { color, setColor, palette } = useHextimatorTheme();
+```
+
+## Tailwind CSS v4
+
+```css
+@import "tailwindcss";
+@import "hextimator/tailwind.css";
+```
+
+This registers all 20 built-in tokens as Tailwind utilities (`bg-accent`, `text-base-foreground`, etc.).
+
+## Common recipes
+
+### Inverted dark mode (accent as background)
+
+```typescript
+const theme = hextimate("#52FE8C", {
+  baseColor: "#FEBA5D",
+  invertDarkModeBaseAccent: true,
+}).format({ as: "css" });
+// Dark mode uses the accent hue as background, base hue as accent
+```
+
+### shadcn/ui theme
+
+```typescript
+import { hextimate, presets } from "hextimator";
+
+hextimate("#6366F1")
+  .preset(presets.shadcn)
+  .format();
+// Generates all shadcn/ui tokens with proper naming
+```
+
+### Multi-tenant with `.fork()`
+
+```typescript
+const base = hextimate("#52FE8C", { baseColor: "#FEBA5D" })
+  .addRole("banner", "#ff006e")
+  .addVariant("hover", { from: "strong" });
+
+const tenantA = base.fork("#ff6677").format({ as: "css" });
+const tenantB = base.fork("#3a86ff").format({ as: "css" });
+```
+
+### Color vision deficiency
+
+```typescript
+const normalTheme = hextimate("#ff6600");
+const adaptedTheme = normalTheme.fork().adaptFor("deuteranopia");
+const preview = normalTheme.fork().simulate("deuteranopia");
+```
+
+## Optional
+
+- [Extending the palette](https://github.com/fgrgic/hextimator/blob/main/packages/hextimator/docs/extending-the-palette.md): addRole, addVariant, addToken in depth
+- [Customization reference](https://github.com/fgrgic/hextimator/blob/main/packages/hextimator/docs/customization.md): all generation and format options
+- [Multiple themes](https://github.com/fgrgic/hextimator/blob/main/packages/hextimator/docs/multiple-themes.md): .fork() and dynamic theming
+- [Color vision deficiency](https://github.com/fgrgic/hextimator/blob/main/packages/hextimator/docs/color-vision-deficiency.md): simulate and adaptFor
+- [React docs](https://github.com/fgrgic/hextimator/blob/main/packages/hextimator/docs/react.md): hook, provider, dark mode strategies
+- [Tailwind CSS v4](https://github.com/fgrgic/hextimator/blob/main/packages/hextimator/docs/tailwind.md): setup and custom tokens
+- [Real-world examples](https://github.com/fgrgic/hextimator/blob/main/packages/hextimator/docs/examples.md): shadcn/ui, Stripe, Slack configs

package/package.json

@@ -0,0 +1,81 @@
+{
+	"name": "hextimator",
+	"version": "0.1.0",
+	"description": "Generate perceptually uniform color palettes with light/dark themes and WCAG contrast guarantees from a single brand color. Outputs CSS vars, Tailwind, SCSS, or JSON.",
+	"keywords": [
+		"color",
+		"palette",
+		"generator",
+		"creator",
+		"oklch",
+		"rgb",
+		"rgb2oklch",
+		"theme",
+		"design-tokens",
+		"dark-mode",
+		"wcag",
+		"accessibility",
+		"contrast",
+		"brand-color",
+		"css-variables",
+		"tailwind-theme",
+		"runtime-theming",
+		"multi-tenant"
+	],
+	"homepage": "https://hextimator.com",
+	"bugs": {
+		"url": "https://github.com/fgrgic/hextimator/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/fgrgic/hextimator.git"
+	},
+	"license": "MIT",
+	"engines": {
+		"node": ">=18.3.0"
+	},
+	"bin": {
+		"hextimator": "./dist/cli.js",
+		"hextimate": "./dist/cli.js"
+	},
+	"author": "fgrgic",
+	"type": "module",
+	"module": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./react": {
+			"types": "./dist/react.d.ts",
+			"import": "./dist/react.js"
+		},
+		"./tailwind.css": "./tailwind.css"
+	},
+	"files": [
+		"dist",
+		"tailwind.css",
+		"llms.txt",
+		"CHANGELOG.md"
+	],
+	"scripts": {
+		"build": "tsup",
+		"dev": "tsup --watch",
+		"test": "bun test"
+	},
+	"peerDependencies": {
+		"react": ">=18"
+	},
+	"peerDependenciesMeta": {
+		"react": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"@types/react": "^19.2.7",
+		"react": "^19.2.0",
+		"tsup": "^8.0.0",
+		"typescript": "^5.0.0"
+	}
+}

package/tailwind.css

@@ -0,0 +1,22 @@
+@theme inline {
+	--color-accent: var(--accent);
+	--color-accent-strong: var(--accent-strong);
+	--color-accent-weak: var(--accent-weak);
+	--color-accent-foreground: var(--accent-foreground);
+	--color-base: var(--base);
+	--color-base-strong: var(--base-strong);
+	--color-base-weak: var(--base-weak);
+	--color-base-foreground: var(--base-foreground);
+	--color-positive: var(--positive);
+	--color-positive-strong: var(--positive-strong);
+	--color-positive-weak: var(--positive-weak);
+	--color-positive-foreground: var(--positive-foreground);
+	--color-negative: var(--negative);
+	--color-negative-strong: var(--negative-strong);
+	--color-negative-weak: var(--negative-weak);
+	--color-negative-foreground: var(--negative-foreground);
+	--color-warning: var(--warning);
+	--color-warning-strong: var(--warning-strong);
+	--color-warning-weak: var(--warning-weak);
+	--color-warning-foreground: var(--warning-foreground);
+}