@spotkit/mwala 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,17 @@
+MIT License
+
+Copyright (c) 2026 MeloSpot
+
+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.

package/README.md

@@ -1,3 +1,94 @@
-# Temporary Holding Version
+# Mwala
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Color intelligence, accessibility and design foundations for the web.
+
+## Install
+
+```bash
+npm install @spotkit/mwala
+```
+
+## Quick start
+
+```ts
+import {
+  generateScale,
+  checkContrast,
+  createTheme,
+  themeToCss,
+} from '@spotkit/mwala';
+
+const palette = generateScale('#D74D0F');
+console.log(palette[500]);
+
+const contrast = checkContrast('#171717', '#FFFFFF');
+console.log(contrast.ratio, contrast.passesAA);
+
+const theme = createTheme({ primary: '#D74D0F', mode: 'light' });
+console.log(themeToCss(theme));
+```
+
+## API
+
+### Color conversion
+- `normalizeHex(hex)` — normalize `#RGB` or `#RRGGBB` to lowercase six-digit hex.
+- `hexToRgb(hex)`, `hexToRgba(hex)`, `rgbToHex(rgb)`
+- `hexToHsl(hex)`, `hslToHex(hsl)`, `rgbToHsl(rgb)`, `hslToRgb(hsl)`
+- `adjustLightness(hex, amount)` — adjust HSL lightness by a percentage-point amount.
+- `mix(a, b, amount)` — mix two colors in sRGB.
+- `composite(foreground, background)` — composite a translucent color over an opaque one.
+
+### Palettes
+- `generateScale(seed)` — generate a hue-preserving 50–950 palette scale.
+- `generateHarmony(seed, harmony)` — generate `complementary`, `analogous`, `triadic`, or `split-complementary` colors.
+
+### Contrast
+- `relativeLuminance(hex)`
+- `contrastRatio(foreground, background)`
+- `checkContrast(foreground, background)` — returns the ratio and WCAG AA/AAA pass flags. `passesAA` uses 4.5:1; `passesAALarge` uses 3:1; `passesAAA` uses 7:1.
+- `worstContrast(foreground, backgrounds)` — the lowest ratio against any background, useful for gradients and layered surfaces.
+- `meetsContrast(foreground, backgrounds, standard?)` — `standard` is `AA` (4.5:1), `AA-large` (3:1) or `AAA` (7:1).
+
+### Contrast suggestions
+- `ensureContrast(foreground, backgrounds, options?)` — return the closest color that passes. By default it keeps hue and saturation and only moves lightness, so the suggestion still looks like the user's color. Pass `preserveHue: false` to allow a black/white fallback.
+- `suggestReadable(backgrounds, candidates?, options?)` — suggest a passing color from the user's existing palette, preferring the hue-preserving version of `preferred`.
+- Both return `{ color, ratio, passes, changed }`.
+
+```ts
+import { ensureContrast, suggestReadable } from '@spotkit/mwala';
+
+// A gold title on white becomes a readable dark gold, not black.
+const title = ensureContrast('#FFD700', ['#FFFFFF']);
+console.log(title.color, title.ratio); // e.g. #8a7400 4.59
+
+// Pass the user's palette too. With preserveHue: false, a palette colour
+// can win when it is closer than black or white.
+const text = suggestReadable(['#FFFFFF'], ['#6B4E00', '#EEEEEE'], {
+  preferred: '#EEEEEE',
+  preserveHue: false,
+});
+console.log(text.color); // #6b4e00
+```
+
+### Themes
+- `createTheme({ primary, mode })` — create a semantic light or dark theme.
+- `readableForeground(background)` — choose black or white by contrast ratio.
+- `readableOn(...backgrounds)` — choose black or white for several backgrounds at once.
+- `themeToCssVariables(theme, prefix?)` and `themeToCss(theme, selector?, prefix?)`.
+
+## Development
+
+```bash
+npm install
+npm test
+npm run typecheck
+npm run build
+```
+
+## Status
+
+Early development (`0.0.1`). The palette scale is intentionally simple and deterministic; perceptual color spaces (OKLCH), gamut mapping, color-blindness simulation, and advanced theme generation are potential future additions.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,380 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CONTRAST_MINIMUM: () => CONTRAST_MINIMUM,
+  adjustLightness: () => adjustLightness,
+  checkContrast: () => checkContrast,
+  composite: () => composite,
+  contrastRatio: () => contrastRatio,
+  createTheme: () => createTheme,
+  ensureContrast: () => ensureContrast,
+  generateHarmony: () => generateHarmony,
+  generateScale: () => generateScale,
+  hexToHsl: () => hexToHsl,
+  hexToRgb: () => hexToRgb,
+  hexToRgba: () => hexToRgba,
+  hslToHex: () => hslToHex,
+  hslToRgb: () => hslToRgb,
+  meetsContrast: () => meetsContrast,
+  mix: () => mix,
+  normalizeHex: () => normalizeHex,
+  readableForeground: () => readableForeground,
+  readableOn: () => readableOn,
+  relativeLuminance: () => relativeLuminance,
+  rgbToHex: () => rgbToHex,
+  rgbToHsl: () => rgbToHsl,
+  suggestReadable: () => suggestReadable,
+  themeToCss: () => themeToCss,
+  themeToCssVariables: () => themeToCssVariables,
+  worstContrast: () => worstContrast
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/color/parse.ts
+function normalizeHex(input) {
+  const value = input.trim().replace(/^#/, "");
+  if (/^[\da-fA-F]{3}$/.test(value)) {
+    return `#${[...value].map((char) => char + char).join("").toLowerCase()}`;
+  }
+  if (/^[\da-fA-F]{6}$/.test(value)) return `#${value.toLowerCase()}`;
+  throw new Error(`Invalid hex color: "${input}". Expected #RGB or #RRGGBB.`);
+}
+function hexToRgba(hex) {
+  const value = hex.trim().replace(/^#/, "");
+  const expanded = /^[\da-f]{3,4}$/i.test(value) ? [...value].map((char) => char + char).join("") : value;
+  if (!/^[\da-f]{6}([\da-f]{2})?$/i.test(expanded)) {
+    throw new Error(`Invalid hex color: "${hex}". Expected #RGB, #RGBA, #RRGGBB or #RRGGBBAA.`);
+  }
+  const int = Number.parseInt(expanded.slice(0, 6), 16);
+  return {
+    r: int >> 16 & 255,
+    g: int >> 8 & 255,
+    b: int & 255,
+    a: expanded.length === 8 ? Number.parseInt(expanded.slice(6, 8), 16) / 255 : 1
+  };
+}
+function hexToRgb(hex) {
+  const { r, g, b } = hexToRgba(normalizeHex(hex));
+  return { r, g, b };
+}
+function rgbToHex({ r, g, b }) {
+  const channels = [r, g, b];
+  if (channels.some((channel) => !Number.isFinite(channel) || channel < 0 || channel > 255)) {
+    throw new Error("RGB channels must be finite numbers between 0 and 255.");
+  }
+  return `#${channels.map((channel) => Math.round(channel).toString(16).padStart(2, "0")).join("")}`;
+}
+
+// src/color/convert.ts
+function rgbToHsl({ r, g, b }) {
+  const red = r / 255;
+  const green = g / 255;
+  const blue = b / 255;
+  const max = Math.max(red, green, blue);
+  const min = Math.min(red, green, blue);
+  const delta = max - min;
+  let h = 0;
+  const l = (max + min) / 2;
+  let s = 0;
+  if (delta !== 0) {
+    s = delta / (1 - Math.abs(2 * l - 1));
+    switch (max) {
+      case red:
+        h = (green - blue) / delta % 6;
+        break;
+      case green:
+        h = (blue - red) / delta + 2;
+        break;
+      default:
+        h = (red - green) / delta + 4;
+    }
+    h *= 60;
+    if (h < 0) h += 360;
+  }
+  return { h, s: s * 100, l: l * 100 };
+}
+function hslToRgb({ h, s, l }) {
+  if (![h, s, l].every(Number.isFinite) || s < 0 || s > 100 || l < 0 || l > 100) {
+    throw new Error("HSL requires finite hue and saturation/lightness between 0 and 100.");
+  }
+  const hue = (h % 360 + 360) % 360;
+  const saturation = s / 100;
+  const lightness = l / 100;
+  const chroma = (1 - Math.abs(2 * lightness - 1)) * saturation;
+  const x = chroma * (1 - Math.abs(hue / 60 % 2 - 1));
+  const m = lightness - chroma / 2;
+  let channels;
+  if (hue < 60) channels = [chroma, x, 0];
+  else if (hue < 120) channels = [x, chroma, 0];
+  else if (hue < 180) channels = [0, chroma, x];
+  else if (hue < 240) channels = [0, x, chroma];
+  else if (hue < 300) channels = [x, 0, chroma];
+  else channels = [chroma, 0, x];
+  return {
+    r: Math.round((channels[0] + m) * 255),
+    g: Math.round((channels[1] + m) * 255),
+    b: Math.round((channels[2] + m) * 255)
+  };
+}
+function hexToHsl(hex) {
+  return rgbToHsl(hexToRgb(hex));
+}
+function hslToHex(hsl) {
+  return rgbToHex(hslToRgb(hsl));
+}
+function adjustLightness(hex, amount2) {
+  if (!Number.isFinite(amount2) || amount2 < -100 || amount2 > 100) {
+    throw new Error("Lightness adjustment must be between -100 and 100.");
+  }
+  const hsl = hexToHsl(normalizeHex(hex));
+  return hslToHex({ ...hsl, l: Math.min(100, Math.max(0, hsl.l + amount2)) });
+}
+
+// src/color/mix.ts
+function amount(value) {
+  if (!Number.isFinite(value)) throw new Error("Mix amount must be a finite number.");
+  return Math.min(1, Math.max(0, value));
+}
+function mix(a, b, weight) {
+  const t = amount(weight);
+  const first = hexToRgba(a);
+  const second = hexToRgba(b);
+  return rgbToHex({
+    r: first.r + (second.r - first.r) * t,
+    g: first.g + (second.g - first.g) * t,
+    b: first.b + (second.b - first.b) * t
+  });
+}
+function composite(foreground, background) {
+  const fg = hexToRgba(foreground);
+  const bg = hexToRgba(background);
+  return rgbToHex({
+    r: fg.r * fg.a + bg.r * (1 - fg.a),
+    g: fg.g * fg.a + bg.g * (1 - fg.a),
+    b: fg.b * fg.a + bg.b * (1 - fg.a)
+  });
+}
+
+// src/contrast/wcag.ts
+function linearize(channel) {
+  const value = channel / 255;
+  return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+}
+function relativeLuminance(hex) {
+  const { r, g, b } = hexToRgb(normalizeHex(hex));
+  return 0.2126 * linearize(r) + 0.7152 * linearize(g) + 0.0722 * linearize(b);
+}
+function contrastRatio(foreground, background) {
+  const first = relativeLuminance(foreground);
+  const second = relativeLuminance(background);
+  const lighter = Math.max(first, second);
+  const darker = Math.min(first, second);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+function checkContrast(foreground, background) {
+  const ratio = contrastRatio(foreground, background);
+  return {
+    ratio: Math.round(ratio * 100) / 100,
+    level: ratio >= 7 ? "AAA" : ratio >= 4.5 ? "AA" : ratio >= 3 ? "AA-large" : "fail",
+    passesAA: ratio >= 4.5,
+    passesAALarge: ratio >= 3,
+    passesAAA: ratio >= 7
+  };
+}
+
+// src/contrast/advise.ts
+var CONTRAST_MINIMUM = {
+  "AA-large": 3,
+  AA: 4.5,
+  AAA: 7
+};
+function firstBackground(backgrounds) {
+  const first = backgrounds[0];
+  if (first === void 0) throw new Error("At least one background is required.");
+  return first;
+}
+function worstContrast(foreground, backgrounds) {
+  const fg = normalizeHex(foreground);
+  let worst = { ratio: Number.POSITIVE_INFINITY, background: normalizeHex(firstBackground(backgrounds)) };
+  for (const background of backgrounds) {
+    const normalized = normalizeHex(background);
+    const ratio = contrastRatio(fg, normalized);
+    if (ratio < worst.ratio) worst = { ratio, background: normalized };
+  }
+  return worst;
+}
+function meetsContrast(foreground, backgrounds, standard = "AA") {
+  return worstContrast(foreground, backgrounds).ratio >= CONTRAST_MINIMUM[standard];
+}
+function distance(a, b) {
+  const first = hexToRgb(a);
+  const second = hexToRgb(b);
+  return (first.r - second.r) ** 2 + (first.g - second.g) ** 2 + (first.b - second.b) ** 2;
+}
+function ensureContrast(foreground, backgrounds, options = {}) {
+  const standard = options.standard ?? "AA";
+  const minimum = CONTRAST_MINIMUM[standard];
+  const base = normalizeHex(foreground);
+  const current = worstContrast(base, backgrounds);
+  if (current.ratio >= minimum) {
+    return { color: base, ratio: current.ratio, passes: true, changed: false };
+  }
+  if (options.preserveHue !== false) {
+    const { h, s, l } = hexToHsl(base);
+    for (let step = 1; step <= 100; step += 1) {
+      const shades = [
+        hslToHex({ h, s, l: Math.max(0, l - step) }),
+        hslToHex({ h, s, l: Math.min(100, l + step) })
+      ];
+      let best2;
+      for (const shade of shades) {
+        const ratio = worstContrast(shade, backgrounds).ratio;
+        if (ratio >= minimum && (best2 === void 0 || ratio > best2.ratio)) {
+          best2 = { color: shade, ratio };
+        }
+      }
+      if (best2 !== void 0) return { ...best2, passes: true, changed: best2.color !== base };
+    }
+  }
+  const black = { color: "#000000", ratio: worstContrast("#000000", backgrounds).ratio };
+  const white = { color: "#ffffff", ratio: worstContrast("#ffffff", backgrounds).ratio };
+  const best = black.ratio >= white.ratio ? black : white;
+  return { ...best, passes: best.ratio >= minimum, changed: true };
+}
+function suggestReadable(backgrounds, candidates = [], options = {}) {
+  const standard = options.standard ?? "AA";
+  const minimum = CONTRAST_MINIMUM[standard];
+  const preferredInput = options.preferred ?? candidates[0];
+  const preferred = preferredInput === void 0 ? void 0 : normalizeHex(preferredInput);
+  if (preferred !== void 0 && meetsContrast(preferred, backgrounds, standard)) {
+    return { color: preferred, ratio: worstContrast(preferred, backgrounds).ratio, passes: true, changed: false };
+  }
+  const adjusted = preferred === void 0 ? void 0 : ensureContrast(preferred, backgrounds, options);
+  const passing = /* @__PURE__ */ new Map();
+  if (adjusted !== void 0 && adjusted.passes) {
+    passing.set(adjusted.color, { color: adjusted.color, ratio: adjusted.ratio });
+  }
+  for (const candidate of candidates) {
+    const color = normalizeHex(candidate);
+    const ratio = worstContrast(color, backgrounds).ratio;
+    if (ratio >= minimum) passing.set(color, { color, ratio });
+  }
+  if (passing.size > 0) {
+    const best = [...passing.values()].sort((a, b) => {
+      if (preferred === void 0) return b.ratio - a.ratio;
+      return distance(a.color, preferred) - distance(b.color, preferred);
+    })[0];
+    return { ...best, passes: true, changed: best.color !== preferred };
+  }
+  return ensureContrast(preferred ?? "#111111", backgrounds, options);
+}
+
+// src/palette/generate.ts
+var STEPS = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950];
+var LIGHTNESS = [97, 94, 88, 80, 69, 55, 45, 36, 27, 18, 12];
+function generateScale(seed) {
+  const { h, s } = hexToHsl(normalizeHex(seed));
+  return Object.fromEntries(
+    STEPS.map((step, index) => [step, hslToHex({ h, s: Math.min(100, s * (0.72 + LIGHTNESS[index] / 350)), l: LIGHTNESS[index] })])
+  );
+}
+function generateHarmony(seed, harmony) {
+  const base = hexToHsl(normalizeHex(seed));
+  const offsets = {
+    complementary: [0, 180],
+    analogous: [-30, 0, 30],
+    triadic: [0, 120, 240],
+    "split-complementary": [0, 150, 210]
+  };
+  return offsets[harmony].map((offset) => hslToHex({ ...base, h: (base.h + offset + 360) % 360 }));
+}
+
+// src/theme/theme.ts
+function createTheme({ primary, mode = "light" }) {
+  const brand = normalizeHex(primary);
+  if (mode === "light") {
+    return {
+      primary: brand,
+      background: "#ffffff",
+      foreground: "#171717",
+      muted: "#737373",
+      border: "#e5e5e5",
+      accent: adjustLightness(brand, 38)
+    };
+  }
+  return {
+    primary: brand,
+    background: "#171717",
+    foreground: "#fafafa",
+    muted: "#a3a3a3",
+    border: "#404040",
+    accent: adjustLightness(brand, 18)
+  };
+}
+function readableForeground(background) {
+  return readableOn(background);
+}
+function readableOn(...backgrounds) {
+  const worst = (text) => Math.min(...backgrounds.map((background) => checkContrast(text, background).ratio));
+  return worst("#000000") >= worst("#ffffff") ? "#000000" : "#ffffff";
+}
+function themeToCssVariables(theme, prefix = "color") {
+  return Object.fromEntries(
+    Object.entries(theme).map(([key, value]) => [`--${prefix}-${key}`, value])
+  );
+}
+function themeToCss(theme, selector = ":root", prefix = "color") {
+  const variables = themeToCssVariables(theme, prefix);
+  const declarations = Object.entries(variables).map(([key, value]) => `  ${key}: ${value};`).join("\n");
+  return `${selector} {
+${declarations}
+}`;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CONTRAST_MINIMUM,
+  adjustLightness,
+  checkContrast,
+  composite,
+  contrastRatio,
+  createTheme,
+  ensureContrast,
+  generateHarmony,
+  generateScale,
+  hexToHsl,
+  hexToRgb,
+  hexToRgba,
+  hslToHex,
+  hslToRgb,
+  meetsContrast,
+  mix,
+  normalizeHex,
+  readableForeground,
+  readableOn,
+  relativeLuminance,
+  rgbToHex,
+  rgbToHsl,
+  suggestReadable,
+  themeToCss,
+  themeToCssVariables,
+  worstContrast
+});

package/dist/index.d.cts

@@ -0,0 +1,112 @@
+/** Normalize a 3- or 6-digit hex color to #rrggbb. */
+declare function normalizeHex(input: string): string;
+interface RGB {
+    r: number;
+    g: number;
+    b: number;
+}
+interface RGBA extends RGB {
+    /** 0 (transparent) to 1 (opaque). */
+    a: number;
+}
+/** Parse #RGB, #RGBA, #RRGGBB or #RRGGBBAA into channels and alpha. */
+declare function hexToRgba(hex: string): RGBA;
+declare function hexToRgb(hex: string): RGB;
+declare function rgbToHex({ r, g, b }: RGB): string;
+
+interface HSL {
+    h: number;
+    s: number;
+    l: number;
+}
+declare function rgbToHsl({ r, g, b }: RGB): HSL;
+declare function hslToRgb({ h, s, l }: HSL): RGB;
+declare function hexToHsl(hex: string): HSL;
+declare function hslToHex(hsl: HSL): string;
+declare function adjustLightness(hex: string, amount: number): string;
+
+/** Mix two colors in sRGB. 0 returns `a`, 1 returns `b`. Alpha is ignored. */
+declare function mix(a: string, b: string, weight: number): string;
+/** Composite a translucent foreground over an opaque background. */
+declare function composite(foreground: string, background: string): string;
+
+/** WCAG 2.x relative luminance, from 0 (black) to 1 (white). */
+declare function relativeLuminance(hex: string): number;
+/** WCAG contrast ratio, from 1:1 to 21:1. */
+declare function contrastRatio(foreground: string, background: string): number;
+type ContrastLevel = 'fail' | 'AA-large' | 'AA' | 'AAA';
+interface ContrastResult {
+    ratio: number;
+    level: ContrastLevel;
+    passesAA: boolean;
+    passesAALarge: boolean;
+    passesAAA: boolean;
+}
+declare function checkContrast(foreground: string, background: string): ContrastResult;
+
+type ContrastStandard = 'AA' | 'AA-large' | 'AAA';
+/** WCAG 2.x minimum ratios: 4.5:1 for body text, 3:1 for large text, 7:1 for AAA. */
+declare const CONTRAST_MINIMUM: Record<ContrastStandard, number>;
+interface ContrastOptions {
+    standard?: ContrastStandard;
+    /** Keep hue and saturation and move lightness only. Defaults to true. */
+    preserveHue?: boolean;
+}
+interface SuggestOptions extends ContrastOptions {
+    /** The colour the user already picked. Defaults to the first candidate. */
+    preferred?: string;
+}
+interface ContrastSuggestion {
+    color: string;
+    ratio: number;
+    passes: boolean;
+    changed: boolean;
+}
+/** The lowest contrast ratio between `foreground` and any of the backgrounds. */
+declare function worstContrast(foreground: string, backgrounds: string[]): {
+    ratio: number;
+    background: string;
+};
+declare function meetsContrast(foreground: string, backgrounds: string[], standard?: ContrastStandard): boolean;
+/**
+ * Return the closest colour to `foreground` that meets the standard on every
+ * background. By default it keeps the hue and saturation and only moves
+ * lightness, so the result still looks like the user's colour.
+ */
+declare function ensureContrast(foreground: string, backgrounds: string[], options?: ContrastOptions): ContrastSuggestion;
+/**
+ * Suggest a readable colour from the colours the user already has. The
+ * hue-preserving version of `preferred` wins unless a palette candidate is
+ * closer to it.
+ */
+declare function suggestReadable(backgrounds: string[], candidates?: string[], options?: SuggestOptions): ContrastSuggestion;
+
+type PaletteScale = Record<50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950, string>;
+/** Generate a Tailwind-style 50–950 scale while preserving the source hue and saturation. */
+declare function generateScale(seed: string): PaletteScale;
+type Harmony = 'complementary' | 'analogous' | 'triadic' | 'split-complementary';
+/** Generate companion colors using classic hue relationships. */
+declare function generateHarmony(seed: string, harmony: Harmony): string[];
+
+interface ColorTheme {
+    primary: string;
+    background: string;
+    foreground: string;
+    muted: string;
+    border: string;
+    accent: string;
+}
+interface ThemeOptions {
+    primary: string;
+    mode?: 'light' | 'dark';
+}
+/** Create a small semantic theme from a primary brand color. */
+declare function createTheme({ primary, mode }: ThemeOptions): ColorTheme;
+/** Choose black or white text based on the stronger WCAG contrast ratio. */
+declare function readableForeground(background: string): '#000000' | '#ffffff';
+/** Choose black or white, whichever reads better on every given background. */
+declare function readableOn(...backgrounds: string[]): '#000000' | '#ffffff';
+declare function themeToCssVariables(theme: ColorTheme, prefix?: string): Record<string, string>;
+declare function themeToCss(theme: ColorTheme, selector?: string, prefix?: string): string;
+
+export { CONTRAST_MINIMUM, type ColorTheme, type ContrastLevel, type ContrastOptions, type ContrastResult, type ContrastStandard, type ContrastSuggestion, type HSL, type Harmony, type PaletteScale, type RGB, type RGBA, type SuggestOptions, type ThemeOptions, adjustLightness, checkContrast, composite, contrastRatio, createTheme, ensureContrast, generateHarmony, generateScale, hexToHsl, hexToRgb, hexToRgba, hslToHex, hslToRgb, meetsContrast, mix, normalizeHex, readableForeground, readableOn, relativeLuminance, rgbToHex, rgbToHsl, suggestReadable, themeToCss, themeToCssVariables, worstContrast };

package/dist/index.d.ts

@@ -0,0 +1,112 @@
+/** Normalize a 3- or 6-digit hex color to #rrggbb. */
+declare function normalizeHex(input: string): string;
+interface RGB {
+    r: number;
+    g: number;
+    b: number;
+}
+interface RGBA extends RGB {
+    /** 0 (transparent) to 1 (opaque). */
+    a: number;
+}
+/** Parse #RGB, #RGBA, #RRGGBB or #RRGGBBAA into channels and alpha. */
+declare function hexToRgba(hex: string): RGBA;
+declare function hexToRgb(hex: string): RGB;
+declare function rgbToHex({ r, g, b }: RGB): string;
+
+interface HSL {
+    h: number;
+    s: number;
+    l: number;
+}
+declare function rgbToHsl({ r, g, b }: RGB): HSL;
+declare function hslToRgb({ h, s, l }: HSL): RGB;
+declare function hexToHsl(hex: string): HSL;
+declare function hslToHex(hsl: HSL): string;
+declare function adjustLightness(hex: string, amount: number): string;
+
+/** Mix two colors in sRGB. 0 returns `a`, 1 returns `b`. Alpha is ignored. */
+declare function mix(a: string, b: string, weight: number): string;
+/** Composite a translucent foreground over an opaque background. */
+declare function composite(foreground: string, background: string): string;
+
+/** WCAG 2.x relative luminance, from 0 (black) to 1 (white). */
+declare function relativeLuminance(hex: string): number;
+/** WCAG contrast ratio, from 1:1 to 21:1. */
+declare function contrastRatio(foreground: string, background: string): number;
+type ContrastLevel = 'fail' | 'AA-large' | 'AA' | 'AAA';
+interface ContrastResult {
+    ratio: number;
+    level: ContrastLevel;
+    passesAA: boolean;
+    passesAALarge: boolean;
+    passesAAA: boolean;
+}
+declare function checkContrast(foreground: string, background: string): ContrastResult;
+
+type ContrastStandard = 'AA' | 'AA-large' | 'AAA';
+/** WCAG 2.x minimum ratios: 4.5:1 for body text, 3:1 for large text, 7:1 for AAA. */
+declare const CONTRAST_MINIMUM: Record<ContrastStandard, number>;
+interface ContrastOptions {
+    standard?: ContrastStandard;
+    /** Keep hue and saturation and move lightness only. Defaults to true. */
+    preserveHue?: boolean;
+}
+interface SuggestOptions extends ContrastOptions {
+    /** The colour the user already picked. Defaults to the first candidate. */
+    preferred?: string;
+}
+interface ContrastSuggestion {
+    color: string;
+    ratio: number;
+    passes: boolean;
+    changed: boolean;
+}
+/** The lowest contrast ratio between `foreground` and any of the backgrounds. */
+declare function worstContrast(foreground: string, backgrounds: string[]): {
+    ratio: number;
+    background: string;
+};
+declare function meetsContrast(foreground: string, backgrounds: string[], standard?: ContrastStandard): boolean;
+/**
+ * Return the closest colour to `foreground` that meets the standard on every
+ * background. By default it keeps the hue and saturation and only moves
+ * lightness, so the result still looks like the user's colour.
+ */
+declare function ensureContrast(foreground: string, backgrounds: string[], options?: ContrastOptions): ContrastSuggestion;
+/**
+ * Suggest a readable colour from the colours the user already has. The
+ * hue-preserving version of `preferred` wins unless a palette candidate is
+ * closer to it.
+ */
+declare function suggestReadable(backgrounds: string[], candidates?: string[], options?: SuggestOptions): ContrastSuggestion;
+
+type PaletteScale = Record<50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950, string>;
+/** Generate a Tailwind-style 50–950 scale while preserving the source hue and saturation. */
+declare function generateScale(seed: string): PaletteScale;
+type Harmony = 'complementary' | 'analogous' | 'triadic' | 'split-complementary';
+/** Generate companion colors using classic hue relationships. */
+declare function generateHarmony(seed: string, harmony: Harmony): string[];
+
+interface ColorTheme {
+    primary: string;
+    background: string;
+    foreground: string;
+    muted: string;
+    border: string;
+    accent: string;
+}
+interface ThemeOptions {
+    primary: string;
+    mode?: 'light' | 'dark';
+}
+/** Create a small semantic theme from a primary brand color. */
+declare function createTheme({ primary, mode }: ThemeOptions): ColorTheme;
+/** Choose black or white text based on the stronger WCAG contrast ratio. */
+declare function readableForeground(background: string): '#000000' | '#ffffff';
+/** Choose black or white, whichever reads better on every given background. */
+declare function readableOn(...backgrounds: string[]): '#000000' | '#ffffff';
+declare function themeToCssVariables(theme: ColorTheme, prefix?: string): Record<string, string>;
+declare function themeToCss(theme: ColorTheme, selector?: string, prefix?: string): string;
+
+export { CONTRAST_MINIMUM, type ColorTheme, type ContrastLevel, type ContrastOptions, type ContrastResult, type ContrastStandard, type ContrastSuggestion, type HSL, type Harmony, type PaletteScale, type RGB, type RGBA, type SuggestOptions, type ThemeOptions, adjustLightness, checkContrast, composite, contrastRatio, createTheme, ensureContrast, generateHarmony, generateScale, hexToHsl, hexToRgb, hexToRgba, hslToHex, hslToRgb, meetsContrast, mix, normalizeHex, readableForeground, readableOn, relativeLuminance, rgbToHex, rgbToHsl, suggestReadable, themeToCss, themeToCssVariables, worstContrast };

package/dist/index.js

@@ -0,0 +1,328 @@
+// src/color/parse.ts
+function normalizeHex(input) {
+  const value = input.trim().replace(/^#/, "");
+  if (/^[\da-fA-F]{3}$/.test(value)) {
+    return `#${[...value].map((char) => char + char).join("").toLowerCase()}`;
+  }
+  if (/^[\da-fA-F]{6}$/.test(value)) return `#${value.toLowerCase()}`;
+  throw new Error(`Invalid hex color: "${input}". Expected #RGB or #RRGGBB.`);
+}
+function hexToRgba(hex) {
+  const value = hex.trim().replace(/^#/, "");
+  const expanded = /^[\da-f]{3,4}$/i.test(value) ? [...value].map((char) => char + char).join("") : value;
+  if (!/^[\da-f]{6}([\da-f]{2})?$/i.test(expanded)) {
+    throw new Error(`Invalid hex color: "${hex}". Expected #RGB, #RGBA, #RRGGBB or #RRGGBBAA.`);
+  }
+  const int = Number.parseInt(expanded.slice(0, 6), 16);
+  return {
+    r: int >> 16 & 255,
+    g: int >> 8 & 255,
+    b: int & 255,
+    a: expanded.length === 8 ? Number.parseInt(expanded.slice(6, 8), 16) / 255 : 1
+  };
+}
+function hexToRgb(hex) {
+  const { r, g, b } = hexToRgba(normalizeHex(hex));
+  return { r, g, b };
+}
+function rgbToHex({ r, g, b }) {
+  const channels = [r, g, b];
+  if (channels.some((channel) => !Number.isFinite(channel) || channel < 0 || channel > 255)) {
+    throw new Error("RGB channels must be finite numbers between 0 and 255.");
+  }
+  return `#${channels.map((channel) => Math.round(channel).toString(16).padStart(2, "0")).join("")}`;
+}
+
+// src/color/convert.ts
+function rgbToHsl({ r, g, b }) {
+  const red = r / 255;
+  const green = g / 255;
+  const blue = b / 255;
+  const max = Math.max(red, green, blue);
+  const min = Math.min(red, green, blue);
+  const delta = max - min;
+  let h = 0;
+  const l = (max + min) / 2;
+  let s = 0;
+  if (delta !== 0) {
+    s = delta / (1 - Math.abs(2 * l - 1));
+    switch (max) {
+      case red:
+        h = (green - blue) / delta % 6;
+        break;
+      case green:
+        h = (blue - red) / delta + 2;
+        break;
+      default:
+        h = (red - green) / delta + 4;
+    }
+    h *= 60;
+    if (h < 0) h += 360;
+  }
+  return { h, s: s * 100, l: l * 100 };
+}
+function hslToRgb({ h, s, l }) {
+  if (![h, s, l].every(Number.isFinite) || s < 0 || s > 100 || l < 0 || l > 100) {
+    throw new Error("HSL requires finite hue and saturation/lightness between 0 and 100.");
+  }
+  const hue = (h % 360 + 360) % 360;
+  const saturation = s / 100;
+  const lightness = l / 100;
+  const chroma = (1 - Math.abs(2 * lightness - 1)) * saturation;
+  const x = chroma * (1 - Math.abs(hue / 60 % 2 - 1));
+  const m = lightness - chroma / 2;
+  let channels;
+  if (hue < 60) channels = [chroma, x, 0];
+  else if (hue < 120) channels = [x, chroma, 0];
+  else if (hue < 180) channels = [0, chroma, x];
+  else if (hue < 240) channels = [0, x, chroma];
+  else if (hue < 300) channels = [x, 0, chroma];
+  else channels = [chroma, 0, x];
+  return {
+    r: Math.round((channels[0] + m) * 255),
+    g: Math.round((channels[1] + m) * 255),
+    b: Math.round((channels[2] + m) * 255)
+  };
+}
+function hexToHsl(hex) {
+  return rgbToHsl(hexToRgb(hex));
+}
+function hslToHex(hsl) {
+  return rgbToHex(hslToRgb(hsl));
+}
+function adjustLightness(hex, amount2) {
+  if (!Number.isFinite(amount2) || amount2 < -100 || amount2 > 100) {
+    throw new Error("Lightness adjustment must be between -100 and 100.");
+  }
+  const hsl = hexToHsl(normalizeHex(hex));
+  return hslToHex({ ...hsl, l: Math.min(100, Math.max(0, hsl.l + amount2)) });
+}
+
+// src/color/mix.ts
+function amount(value) {
+  if (!Number.isFinite(value)) throw new Error("Mix amount must be a finite number.");
+  return Math.min(1, Math.max(0, value));
+}
+function mix(a, b, weight) {
+  const t = amount(weight);
+  const first = hexToRgba(a);
+  const second = hexToRgba(b);
+  return rgbToHex({
+    r: first.r + (second.r - first.r) * t,
+    g: first.g + (second.g - first.g) * t,
+    b: first.b + (second.b - first.b) * t
+  });
+}
+function composite(foreground, background) {
+  const fg = hexToRgba(foreground);
+  const bg = hexToRgba(background);
+  return rgbToHex({
+    r: fg.r * fg.a + bg.r * (1 - fg.a),
+    g: fg.g * fg.a + bg.g * (1 - fg.a),
+    b: fg.b * fg.a + bg.b * (1 - fg.a)
+  });
+}
+
+// src/contrast/wcag.ts
+function linearize(channel) {
+  const value = channel / 255;
+  return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+}
+function relativeLuminance(hex) {
+  const { r, g, b } = hexToRgb(normalizeHex(hex));
+  return 0.2126 * linearize(r) + 0.7152 * linearize(g) + 0.0722 * linearize(b);
+}
+function contrastRatio(foreground, background) {
+  const first = relativeLuminance(foreground);
+  const second = relativeLuminance(background);
+  const lighter = Math.max(first, second);
+  const darker = Math.min(first, second);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+function checkContrast(foreground, background) {
+  const ratio = contrastRatio(foreground, background);
+  return {
+    ratio: Math.round(ratio * 100) / 100,
+    level: ratio >= 7 ? "AAA" : ratio >= 4.5 ? "AA" : ratio >= 3 ? "AA-large" : "fail",
+    passesAA: ratio >= 4.5,
+    passesAALarge: ratio >= 3,
+    passesAAA: ratio >= 7
+  };
+}
+
+// src/contrast/advise.ts
+var CONTRAST_MINIMUM = {
+  "AA-large": 3,
+  AA: 4.5,
+  AAA: 7
+};
+function firstBackground(backgrounds) {
+  const first = backgrounds[0];
+  if (first === void 0) throw new Error("At least one background is required.");
+  return first;
+}
+function worstContrast(foreground, backgrounds) {
+  const fg = normalizeHex(foreground);
+  let worst = { ratio: Number.POSITIVE_INFINITY, background: normalizeHex(firstBackground(backgrounds)) };
+  for (const background of backgrounds) {
+    const normalized = normalizeHex(background);
+    const ratio = contrastRatio(fg, normalized);
+    if (ratio < worst.ratio) worst = { ratio, background: normalized };
+  }
+  return worst;
+}
+function meetsContrast(foreground, backgrounds, standard = "AA") {
+  return worstContrast(foreground, backgrounds).ratio >= CONTRAST_MINIMUM[standard];
+}
+function distance(a, b) {
+  const first = hexToRgb(a);
+  const second = hexToRgb(b);
+  return (first.r - second.r) ** 2 + (first.g - second.g) ** 2 + (first.b - second.b) ** 2;
+}
+function ensureContrast(foreground, backgrounds, options = {}) {
+  const standard = options.standard ?? "AA";
+  const minimum = CONTRAST_MINIMUM[standard];
+  const base = normalizeHex(foreground);
+  const current = worstContrast(base, backgrounds);
+  if (current.ratio >= minimum) {
+    return { color: base, ratio: current.ratio, passes: true, changed: false };
+  }
+  if (options.preserveHue !== false) {
+    const { h, s, l } = hexToHsl(base);
+    for (let step = 1; step <= 100; step += 1) {
+      const shades = [
+        hslToHex({ h, s, l: Math.max(0, l - step) }),
+        hslToHex({ h, s, l: Math.min(100, l + step) })
+      ];
+      let best2;
+      for (const shade of shades) {
+        const ratio = worstContrast(shade, backgrounds).ratio;
+        if (ratio >= minimum && (best2 === void 0 || ratio > best2.ratio)) {
+          best2 = { color: shade, ratio };
+        }
+      }
+      if (best2 !== void 0) return { ...best2, passes: true, changed: best2.color !== base };
+    }
+  }
+  const black = { color: "#000000", ratio: worstContrast("#000000", backgrounds).ratio };
+  const white = { color: "#ffffff", ratio: worstContrast("#ffffff", backgrounds).ratio };
+  const best = black.ratio >= white.ratio ? black : white;
+  return { ...best, passes: best.ratio >= minimum, changed: true };
+}
+function suggestReadable(backgrounds, candidates = [], options = {}) {
+  const standard = options.standard ?? "AA";
+  const minimum = CONTRAST_MINIMUM[standard];
+  const preferredInput = options.preferred ?? candidates[0];
+  const preferred = preferredInput === void 0 ? void 0 : normalizeHex(preferredInput);
+  if (preferred !== void 0 && meetsContrast(preferred, backgrounds, standard)) {
+    return { color: preferred, ratio: worstContrast(preferred, backgrounds).ratio, passes: true, changed: false };
+  }
+  const adjusted = preferred === void 0 ? void 0 : ensureContrast(preferred, backgrounds, options);
+  const passing = /* @__PURE__ */ new Map();
+  if (adjusted !== void 0 && adjusted.passes) {
+    passing.set(adjusted.color, { color: adjusted.color, ratio: adjusted.ratio });
+  }
+  for (const candidate of candidates) {
+    const color = normalizeHex(candidate);
+    const ratio = worstContrast(color, backgrounds).ratio;
+    if (ratio >= minimum) passing.set(color, { color, ratio });
+  }
+  if (passing.size > 0) {
+    const best = [...passing.values()].sort((a, b) => {
+      if (preferred === void 0) return b.ratio - a.ratio;
+      return distance(a.color, preferred) - distance(b.color, preferred);
+    })[0];
+    return { ...best, passes: true, changed: best.color !== preferred };
+  }
+  return ensureContrast(preferred ?? "#111111", backgrounds, options);
+}
+
+// src/palette/generate.ts
+var STEPS = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950];
+var LIGHTNESS = [97, 94, 88, 80, 69, 55, 45, 36, 27, 18, 12];
+function generateScale(seed) {
+  const { h, s } = hexToHsl(normalizeHex(seed));
+  return Object.fromEntries(
+    STEPS.map((step, index) => [step, hslToHex({ h, s: Math.min(100, s * (0.72 + LIGHTNESS[index] / 350)), l: LIGHTNESS[index] })])
+  );
+}
+function generateHarmony(seed, harmony) {
+  const base = hexToHsl(normalizeHex(seed));
+  const offsets = {
+    complementary: [0, 180],
+    analogous: [-30, 0, 30],
+    triadic: [0, 120, 240],
+    "split-complementary": [0, 150, 210]
+  };
+  return offsets[harmony].map((offset) => hslToHex({ ...base, h: (base.h + offset + 360) % 360 }));
+}
+
+// src/theme/theme.ts
+function createTheme({ primary, mode = "light" }) {
+  const brand = normalizeHex(primary);
+  if (mode === "light") {
+    return {
+      primary: brand,
+      background: "#ffffff",
+      foreground: "#171717",
+      muted: "#737373",
+      border: "#e5e5e5",
+      accent: adjustLightness(brand, 38)
+    };
+  }
+  return {
+    primary: brand,
+    background: "#171717",
+    foreground: "#fafafa",
+    muted: "#a3a3a3",
+    border: "#404040",
+    accent: adjustLightness(brand, 18)
+  };
+}
+function readableForeground(background) {
+  return readableOn(background);
+}
+function readableOn(...backgrounds) {
+  const worst = (text) => Math.min(...backgrounds.map((background) => checkContrast(text, background).ratio));
+  return worst("#000000") >= worst("#ffffff") ? "#000000" : "#ffffff";
+}
+function themeToCssVariables(theme, prefix = "color") {
+  return Object.fromEntries(
+    Object.entries(theme).map(([key, value]) => [`--${prefix}-${key}`, value])
+  );
+}
+function themeToCss(theme, selector = ":root", prefix = "color") {
+  const variables = themeToCssVariables(theme, prefix);
+  const declarations = Object.entries(variables).map(([key, value]) => `  ${key}: ${value};`).join("\n");
+  return `${selector} {
+${declarations}
+}`;
+}
+export {
+  CONTRAST_MINIMUM,
+  adjustLightness,
+  checkContrast,
+  composite,
+  contrastRatio,
+  createTheme,
+  ensureContrast,
+  generateHarmony,
+  generateScale,
+  hexToHsl,
+  hexToRgb,
+  hexToRgba,
+  hslToHex,
+  hslToRgb,
+  meetsContrast,
+  mix,
+  normalizeHex,
+  readableForeground,
+  readableOn,
+  relativeLuminance,
+  rgbToHex,
+  rgbToHsl,
+  suggestReadable,
+  themeToCss,
+  themeToCssVariables,
+  worstContrast
+};

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@spotkit/mwala",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "Color intelligence, accessibility and design foundations for the web.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch"
+  },
+  "keywords": ["color", "palette", "contrast", "accessibility", "theme", "design-system", "typescript", "mwala", "spotkit"],
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}