@sethyrung/tailshade 0.1.0

package/README.md

@@ -0,0 +1,115 @@
+# tailshade
+
+Generate a full Tailwind CSS color palette (50–950) from a single base color.
+Any CSS color in, Tailwind v4 `@theme` block out.
+
+```bash
+$ tailshade '#ff0000'
+@theme {
+  --color-red-50: oklch(0.977 0.011 29.234);
+  --color-red-100: oklch(0.945 0.027 29.234);
+  --color-red-200: oklch(0.892 0.056 29.234);
+  --color-red-300: oklch(0.815 0.104 29.234);
+  --color-red-400: oklch(0.712 0.181 29.234);
+  /* … */
+  --color-red-950: oklch(0.223 0.091 29.234);
+}
+```
+
+Your base color lands verbatim at `<name>-500`, and the ramp reads like one of
+Tailwind's own: lightness targets and chroma taper derived from v4's real
+palettes, every step gamut-mapped to sRGB.
+
+## Install
+
+No install needed — run it directly:
+
+```bash
+bunx @sethyrung/tailshade '#ff0000'
+npx @sethyrung/tailshade '#ff0000'
+```
+
+Or install globally:
+
+```bash
+bun add -g @sethyrung/tailshade   # then: tailshade '#ff0000'
+npm install -g @sethyrung/tailshade
+```
+
+Requires [Bun](https://bun.com) >= 1.4 (or Node >= 18). For local development,
+clone and `bun link` instead — edits stay live.
+
+## Usage
+
+```bash
+tailshade '<color>' [flags]
+```
+
+The base color accepts any CSS format — hex, `rgb()`, `hsl()`, named colors, or
+`oklch()` (which passes through untouched).
+
+| Flag                              | Effect                                                              |
+| --------------------------------- | ------------------------------------------------------------------- |
+| _(none)_                          | Tailwind v4 `@theme` block, oklch values (default)                  |
+| `--name <name>`                   | Override the auto-detected palette name                             |
+| `--v3`                            | Export a `tailwind.config.js` snippet instead of the `@theme` block |
+| `--format <oklch\|hex\|rgb\|hsl>` | Color notation of the emitted values (default: oklch)               |
+| `--preview`                       | Print an ANSI swatch strip above the output                         |
+| `--help`, `-h`                    | Usage                                                               |
+
+Examples:
+
+```bash
+tailshade 'oklch(0.6 0.1 29)' --name brand
+tailshade '#ff0000' --v3 --format hex
+tailshade 'teal' --preview
+```
+
+### Palette naming
+
+The name defaults to the nearest CSS named color (`#ff0000` → `red`). Watch
+out: auto-names can shadow Tailwind's built-in colors inside `@theme` — pass
+`--name brand` to choose your own.
+
+### Tailwind v3 export
+
+```bash
+$ tailshade '#ff0000' --v3 --format hex
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        red: {
+          50: "#fff5f3",
+          100: "#ffe7e2",
+          /* … */
+          950: "#3c0000",
+        },
+      },
+    },
+  },
+};
+```
+
+## How it works
+
+- Parse any CSS color (via [culori](https://culorijs.org/)) and normalize to OKLCH.
+- Anchor the base color verbatim at step 500; scale a v4-derived lightness
+  ladder around it — natural spacing near the archetypal base, stretched or
+  compressed for extreme bases, never two identical steps.
+- Apply a v4-derived chroma taper (peak at 500, whisper at 50, moderate at 950),
+  then gamut-map every step so nothing clips.
+
+Decisions are recorded in [docs/adr](docs/adr); the domain vocabulary lives in
+[CONTEXT.md](CONTEXT.md).
+
+## Development
+
+```bash
+bun install
+bun test               # test suite (single seam: the CLI entry, in-process)
+bun run typecheck      # tsc --noEmit
+bun run lint           # oxlint
+bun run fmt            # oxfmt
+bun run start '#ff0000'
+```

package/bin/cli.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const bunEntry = join(here, "../index.ts");
+const nodeEntry = join(here, "../dist/cli.js");
+
+if (typeof globalThis.Bun !== "undefined") {
+  await import(pathToFileURL(bunEntry).href);
+} else if (existsSync(nodeEntry)) {
+  await import(pathToFileURL(nodeEntry).href);
+} else {
+  process.stderr.write("tailshade: Node needs a built CLI. Run `bun run build`.\n");
+  process.exit(1);
+}

package/dist/cli.js

@@ -0,0 +1,311 @@
+#!/usr/bin/env bun
+// @bun
+
+// src/core.ts
+import { converter as converter2, displayable, parse as parse2 } from "culori";
+
+// src/name.ts
+import { colorsNamed, converter, differenceEuclidean, nearest, parse } from "culori";
+var toOklch = converter("oklch");
+var NAMED_COLORS = Object.entries(colorsNamed).flatMap(([name, int]) => {
+  const color = toOklch(parse("#" + Number(int).toString(16).padStart(6, "0")));
+  return color && Number.isFinite(color.l) ? [{ name, color: normalize(color) }] : [];
+});
+var findNearest = nearest(NAMED_COLORS, differenceEuclidean("oklch"), (entry) => ({
+  mode: "oklch",
+  ...entry.color
+}));
+function normalize(color) {
+  return {
+    l: color.l ?? 0,
+    c: Number.isFinite(color.c) ? color.c : 0,
+    h: Number.isFinite(color.h) ? color.h : 0
+  };
+}
+function kebabCase(input) {
+  return input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
+}
+function detectName(color) {
+  const [hit] = findNearest({ mode: "oklch", ...color });
+  if (!hit) {
+    throw new Error("no named colors available");
+  }
+  return kebabCase(hit.name);
+}
+
+// src/targets.ts
+var TARGETS = {
+  50: 0.9772,
+  100: 0.9504,
+  200: 0.9055,
+  300: 0.8405,
+  400: 0.7535,
+  500: 0.6827,
+  600: 0.5978,
+  700: 0.5149,
+  800: 0.4461,
+  900: 0.3946,
+  950: 0.2779
+};
+var L_MAX = 0.985;
+var L_MIN = 0.02;
+var L_TOO_LIGHT = 0.97;
+var L_TOO_DARK = 0.03;
+var CHROMA_RATIOS = {
+  50: 0.0867,
+  100: 0.2082,
+  200: 0.3993,
+  300: 0.6594,
+  400: 0.9036,
+  500: 1,
+  600: 0.9823,
+  700: 0.8606,
+  800: 0.7083,
+  900: 0.5679,
+  950: 0.4013
+};
+
+// src/core.ts
+var STEPS = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950];
+var toOklch2 = converter2("oklch");
+
+class PaletteError extends Error {
+}
+function target(step) {
+  const t = TARGETS[step];
+  if (t === undefined) {
+    throw new Error(`missing lightness target for step ${step}`);
+  }
+  return t;
+}
+function taperRatio(step) {
+  const ratio = CHROMA_RATIOS[step];
+  if (ratio === undefined) {
+    throw new Error(`missing chroma taper ratio for step ${step}`);
+  }
+  return ratio;
+}
+function parseBase(input) {
+  const color = parse2(input);
+  if (!color) {
+    throw new PaletteError(`could not parse color '${input}'`);
+  }
+  const oklch = toOklch2(color);
+  if (!oklch) {
+    throw new PaletteError(`could not convert color '${input}' to oklch`);
+  }
+  const h = Number.isFinite(oklch.h) ? oklch.h : 0;
+  const c = Number.isFinite(oklch.c) ? oklch.c : 0;
+  return { l: oklch.l ?? 0, c, h };
+}
+function lightnessLadder(baseL) {
+  if (baseL > L_TOO_LIGHT) {
+    throw new PaletteError("base color is too light to build a 50–950 ramp");
+  }
+  if (baseL < L_TOO_DARK) {
+    throw new PaletteError("base color is too dark to build a 50–950 ramp");
+  }
+  const t500 = target(500);
+  const upExtent = target(50) - t500;
+  const downExtent = target(950) - t500;
+  const end50 = Math.min(Math.max(baseL + upExtent, target(50)), L_MAX);
+  const end950 = Math.max(Math.min(baseL + downExtent, target(950)), L_MIN);
+  const scaleUp = (end50 - baseL) / upExtent;
+  const scaleDown = (end950 - baseL) / downExtent;
+  const ladder = new Map;
+  for (const step of STEPS) {
+    if (step === 500) {
+      ladder.set(step, baseL);
+      continue;
+    }
+    const scale = step < 500 ? scaleUp : scaleDown;
+    ladder.set(step, baseL + (target(step) - t500) * scale);
+  }
+  return ladder;
+}
+function ladderLightness(ladder, step) {
+  const l = ladder.get(step);
+  if (l === undefined) {
+    throw new Error(`missing ladder entry for step ${step}`);
+  }
+  return l;
+}
+function maxInGamutChroma(l, c, h) {
+  if (c <= 0)
+    return 0;
+  if (displayable({ mode: "oklch", l, c, h }))
+    return c;
+  let lo = 0;
+  let hi = c;
+  for (let i = 0;i < 24; i++) {
+    const mid = (lo + hi) / 2;
+    if (displayable({ mode: "oklch", l, c: mid, h })) {
+      lo = mid;
+    } else {
+      hi = mid;
+    }
+  }
+  return lo;
+}
+var round3 = (n) => Math.round(n * 1000) / 1000;
+var floor3 = (n) => Math.floor(n * 1000) / 1000;
+function generatePalette(input) {
+  const base = parseBase(input);
+  const ladder = lightnessLadder(base.l);
+  const steps = STEPS.map((step) => {
+    const l = round3(ladderLightness(ladder, step));
+    const h = round3(base.h);
+    const c = floor3(maxInGamutChroma(l, base.c * taperRatio(step), h));
+    return { step, l, c, h };
+  });
+  return { name: detectName(base), base, steps };
+}
+
+// src/format.ts
+import { converter as converter3, formatHex, formatHsl, formatRgb } from "culori";
+var toRgb = converter3("rgb");
+var fmt = (n) => n.toFixed(3);
+var asColor = (s) => ({ mode: "oklch", l: s.l, c: s.c, h: s.h });
+var NOTATIONS = {
+  oklch: (s) => `oklch(${fmt(s.l)} ${fmt(s.c)} ${fmt(s.h)})`,
+  hex: (s) => formatHex(asColor(s)),
+  rgb: (s) => formatRgb(asColor(s)),
+  hsl: (s) => formatHsl(asColor(s))
+};
+function valueStr(s, notation) {
+  return NOTATIONS[notation](s);
+}
+function toThemeCss(palette, notation = "oklch") {
+  const lines = palette.steps.map((s) => `  --color-${palette.name}-${s.step}: ${valueStr(s, notation)};`);
+  return ["@theme {", ...lines, "}"].join(`
+`);
+}
+function toPreviewStrip(palette) {
+  const ESC = String.fromCharCode(27);
+  const blocks = palette.steps.map((s) => {
+    const rgb = toRgb(asColor(s));
+    const [r, g, b] = [rgb.r, rgb.g, rgb.b].map((v) => Math.round((v ?? 0) * 255));
+    const label = s.step.toString().padStart(3);
+    return `${label} ${ESC}[48;2;${r};${g};${b}m      ${ESC}[0m`;
+  });
+  return blocks.join(" ");
+}
+function toTailwindV3(palette, notation = "oklch") {
+  const entries = palette.steps.map((s) => `          ${s.step}: "${valueStr(s, notation)}",`);
+  return [
+    "module.exports = {",
+    "  theme: {",
+    "    extend: {",
+    "      colors: {",
+    `        ${palette.name}: {`,
+    ...entries,
+    "        },",
+    "      },",
+    "    },",
+    "  },",
+    "};"
+  ].join(`
+`);
+}
+
+// src/cli.ts
+var NOTATIONS2 = ["oklch", "hex", "rgb", "hsl"];
+var USAGE = `Usage: tailshade '<color>' [--name <name>] [--v3] [--format <oklch|hex|rgb|hsl>] [--preview]
+
+Generate a Tailwind v4 palette from a base color (any CSS color format).
+
+The palette name defaults to the nearest CSS color name, which can shadow
+Tailwind's built-in colors (red, teal, ...) inside @theme — pass --name to
+choose your own. Pass --v3 to export a tailwind.config.js snippet instead of
+the v4 @theme block. Values default to oklch; pass --format to switch the
+notation (hex, rgb, hsl). Pass --preview to print an ANSI swatch strip above
+the output.
+
+Example: tailshade '#ff0000'
+         tailshade '#ff0000' --name brand
+         tailshade '#ff0000' --v3 --format hex --preview`;
+function main(argv) {
+  let color;
+  let name;
+  let v3 = false;
+  let preview = false;
+  let notation;
+  for (let i = 0;i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") {
+      return { output: USAGE, exitCode: 0 };
+    }
+    if (arg === "--name") {
+      const value = argv[++i];
+      if (value === undefined || value.startsWith("--")) {
+        return usage("--name requires a value");
+      }
+      name = value;
+      continue;
+    }
+    if (arg === "--preview") {
+      preview = true;
+      continue;
+    }
+    if (arg === "--format") {
+      const value = argv[++i];
+      if (value === undefined) {
+        return usage("--format requires a value");
+      }
+      if (!NOTATIONS2.includes(value)) {
+        return usage(`--format '${value}' expects one of: ${NOTATIONS2.join(", ")}`);
+      }
+      notation = value;
+      continue;
+    }
+    if (arg === "--v3") {
+      v3 = true;
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      return usage(`unknown flag '${arg}'`);
+    }
+    if (color !== undefined) {
+      return usage("expected exactly one color argument");
+    }
+    color = arg;
+  }
+  if (color === undefined) {
+    return usage("expected exactly one color argument");
+  }
+  try {
+    const palette = generatePalette(color);
+    if (name !== undefined) {
+      const kebab = kebabCase(name);
+      if (!kebab) {
+        return usage(`--name '${name}' must contain letters or digits`);
+      }
+      palette.name = kebab;
+    }
+    const fmt = notation ?? "oklch";
+    let output = v3 ? toTailwindV3(palette, fmt) : toThemeCss(palette, fmt);
+    if (preview) {
+      output = `${toPreviewStrip(palette)}
+
+${output}`;
+    }
+    return { output, exitCode: 0 };
+  } catch (error) {
+    if (error instanceof PaletteError) {
+      return usage(error.message);
+    }
+    throw error;
+  }
+}
+function usage(message) {
+  return { output: `tailshade: ${message}
+
+${USAGE}`, exitCode: 1 };
+}
+
+// index.ts
+var { output, exitCode } = main(process.argv.slice(2));
+if (output) {
+  console.log(output);
+}
+process.exitCode = exitCode;

package/index.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env bun
+import { main } from "@/cli";
+
+const { output, exitCode } = main(process.argv.slice(2));
+if (output) {
+  console.log(output);
+}
+process.exitCode = exitCode;

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@sethyrung/tailshade",
+  "version": "0.1.0",
+  "description": "Generate a full Tailwind CSS palette (50-950) from a single base color",
+  "keywords": [
+    "cli",
+    "colors",
+    "oklch",
+    "palette",
+    "tailwind",
+    "tailwindcss"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Sethy Rung",
+    "url": "https://sethyrung.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SethyRung/tailshade.git"
+  },
+  "bin": {
+    "tailshade": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "src",
+    "index.ts",
+    "tsconfig.json"
+  ],
+  "type": "module",
+  "module": "index.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "bun run index.ts",
+    "dev": "bun --hot index.ts",
+    "build": "bun build index.ts --target=node --outfile=dist/cli.js --packages=external",
+    "prepack": "bun run build",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check"
+  },
+  "dependencies": {
+    "culori": "^4.0.2"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/culori": "^4.0.1",
+    "oxfmt": "^0.70.0",
+    "oxlint": "^1.85.0"
+  },
+  "peerDependencies": {
+    "typescript": "^7"
+  },
+  "engines": {
+    "bun": ">=1.4.0",
+    "node": ">=18"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,104 @@
+import { generatePalette, PaletteError } from "@/core";
+import { toPreviewStrip, toTailwindV3, toThemeCss, type Notation } from "@/format";
+import { kebabCase } from "@/name";
+
+const NOTATIONS: Notation[] = ["oklch", "hex", "rgb", "hsl"];
+
+export type CliResult = { output: string; exitCode: number };
+
+const USAGE = `Usage: tailshade '<color>' [--name <name>] [--v3] [--format <oklch|hex|rgb|hsl>] [--preview]
+
+Generate a Tailwind v4 palette from a base color (any CSS color format).
+
+The palette name defaults to the nearest CSS color name, which can shadow
+Tailwind's built-in colors (red, teal, ...) inside @theme — pass --name to
+choose your own. Pass --v3 to export a tailwind.config.js snippet instead of
+the v4 @theme block. Values default to oklch; pass --format to switch the
+notation (hex, rgb, hsl). Pass --preview to print an ANSI swatch strip above
+the output.
+
+Example: tailshade '#ff0000'
+         tailshade '#ff0000' --name brand
+         tailshade '#ff0000' --v3 --format hex --preview`;
+
+/**
+ * CLI entry and the single test seam: pure — takes an argv array, returns
+ * the output and exit code instead of writing to stdout.
+ */
+export function main(argv: string[]): CliResult {
+  let color: string | undefined;
+  let name: string | undefined;
+  let v3 = false;
+  let preview = false;
+  let notation: Notation | undefined;
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]!;
+    if (arg === "--help" || arg === "-h") {
+      return { output: USAGE, exitCode: 0 };
+    }
+    if (arg === "--name") {
+      const value = argv[++i];
+      if (value === undefined || value.startsWith("--")) {
+        return usage("--name requires a value");
+      }
+      name = value;
+      continue;
+    }
+    if (arg === "--preview") {
+      preview = true;
+      continue;
+    }
+    if (arg === "--format") {
+      const value = argv[++i];
+      if (value === undefined) {
+        return usage("--format requires a value");
+      }
+      if (!NOTATIONS.includes(value as Notation)) {
+        return usage(`--format '${value}' expects one of: ${NOTATIONS.join(", ")}`);
+      }
+      notation = value as Notation;
+      continue;
+    }
+    if (arg === "--v3") {
+      v3 = true;
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      return usage(`unknown flag '${arg}'`);
+    }
+    if (color !== undefined) {
+      return usage("expected exactly one color argument");
+    }
+    color = arg;
+  }
+  if (color === undefined) {
+    return usage("expected exactly one color argument");
+  }
+
+  try {
+    const palette = generatePalette(color);
+    if (name !== undefined) {
+      const kebab = kebabCase(name);
+      if (!kebab) {
+        return usage(`--name '${name}' must contain letters or digits`);
+      }
+      palette.name = kebab;
+    }
+    const fmt = notation ?? "oklch";
+    let output = v3 ? toTailwindV3(palette, fmt) : toThemeCss(palette, fmt);
+    if (preview) {
+      output = `${toPreviewStrip(palette)}\n\n${output}`;
+    }
+    return { output, exitCode: 0 };
+  } catch (error) {
+    if (error instanceof PaletteError) {
+      return usage(error.message);
+    }
+    throw error;
+  }
+}
+
+function usage(message: string): CliResult {
+  return { output: `tailshade: ${message}\n\n${USAGE}`, exitCode: 1 };
+}

package/src/core.ts

@@ -0,0 +1,125 @@
+import { converter, displayable, parse } from "culori";
+import { detectName, type Oklch } from "@/name";
+import { CHROMA_RATIOS, L_MAX, L_MIN, L_TOO_DARK, L_TOO_LIGHT, TARGETS } from "@/targets";
+
+export const STEPS = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950] as const;
+export type Step = (typeof STEPS)[number];
+
+const toOklch = converter("oklch");
+
+export type PaletteEntry = { step: Step; l: number; c: number; h: number };
+export type Palette = { name: string; base: Oklch; steps: PaletteEntry[] };
+
+export class PaletteError extends Error {}
+
+function target(step: Step): number {
+  const t = TARGETS[step];
+  if (t === undefined) {
+    throw new Error(`missing lightness target for step ${step}`);
+  }
+  return t;
+}
+
+function taperRatio(step: Step): number {
+  const ratio = CHROMA_RATIOS[step];
+  if (ratio === undefined) {
+    throw new Error(`missing chroma taper ratio for step ${step}`);
+  }
+  return ratio;
+}
+
+/**
+ * Parse any CSS color and normalize to OKLCH. Achromatic colors have no
+ * meaningful hue, so missing/NaN channels normalize to 0.
+ */
+function parseBase(input: string): Oklch {
+  const color = parse(input);
+  if (!color) {
+    throw new PaletteError(`could not parse color '${input}'`);
+  }
+  const oklch = toOklch(color);
+  if (!oklch) {
+    throw new PaletteError(`could not convert color '${input}' to oklch`);
+  }
+  const h = Number.isFinite(oklch.h) ? (oklch.h as number) : 0;
+  const c = Number.isFinite(oklch.c) ? (oklch.c as number) : 0;
+  return { l: oklch.l ?? 0, c, h };
+}
+
+/**
+ * Lightness ladder for the 11 steps, scaled around the base's L. Clamping
+ * each endpoint keeps archetypal bases on the universal ladder and stretches
+ * or compresses extreme bases to span the range without duplicate steps.
+ */
+export function lightnessLadder(baseL: number): Map<Step, number> {
+  if (baseL > L_TOO_LIGHT) {
+    throw new PaletteError("base color is too light to build a 50–950 ramp");
+  }
+  if (baseL < L_TOO_DARK) {
+    throw new PaletteError("base color is too dark to build a 50–950 ramp");
+  }
+  const t500 = target(500);
+  const upExtent = target(50) - t500;
+  const downExtent = target(950) - t500;
+
+  const end50 = Math.min(Math.max(baseL + upExtent, target(50)), L_MAX);
+  const end950 = Math.max(Math.min(baseL + downExtent, target(950)), L_MIN);
+  const scaleUp = (end50 - baseL) / upExtent;
+  const scaleDown = (end950 - baseL) / downExtent;
+
+  const ladder = new Map<Step, number>();
+  for (const step of STEPS) {
+    if (step === 500) {
+      ladder.set(step, baseL);
+      continue;
+    }
+    const scale = step < 500 ? scaleUp : scaleDown;
+    ladder.set(step, baseL + (target(step) - t500) * scale);
+  }
+  return ladder;
+}
+
+function ladderLightness(ladder: Map<Step, number>, step: Step): number {
+  const l = ladder.get(step);
+  if (l === undefined) {
+    throw new Error(`missing ladder entry for step ${step}`);
+  }
+  return l;
+}
+
+/** Largest chroma at fixed L and H that stays inside the sRGB gamut. */
+function maxInGamutChroma(l: number, c: number, h: number): number {
+  if (c <= 0) return 0;
+  if (displayable({ mode: "oklch", l, c, h })) return c;
+  let lo = 0;
+  let hi = c;
+  for (let i = 0; i < 24; i++) {
+    const mid = (lo + hi) / 2;
+    if (displayable({ mode: "oklch", l, c: mid, h })) {
+      lo = mid;
+    } else {
+      hi = mid;
+    }
+  }
+  return lo;
+}
+
+const round3 = (n: number) => Math.round(n * 1000) / 1000;
+const floor3 = (n: number) => Math.floor(n * 1000) / 1000;
+
+/**
+ * Generate the full 50–950 palette from a base color. Chroma follows the
+ * v4 taper ratios, is gamut-mapped at the rounded L/H and floored so the
+ * printed triple can't round its way out of the sRGB gamut.
+ */
+export function generatePalette(input: string): Palette {
+  const base = parseBase(input);
+  const ladder = lightnessLadder(base.l);
+  const steps: PaletteEntry[] = STEPS.map((step) => {
+    const l = round3(ladderLightness(ladder, step));
+    const h = round3(base.h);
+    const c = floor3(maxInGamutChroma(l, base.c * taperRatio(step), h));
+    return { step, l, c, h };
+  });
+  return { name: detectName(base), base, steps };
+}

package/src/format.ts

@@ -0,0 +1,64 @@
+import { converter, formatHex, formatHsl, formatRgb, type Color } from "culori";
+import type { Palette, PaletteEntry } from "@/core";
+
+export type Notation = "oklch" | "hex" | "rgb" | "hsl";
+
+const toRgb = converter("rgb");
+
+const fmt = (n: number) => n.toFixed(3);
+
+const asColor = (s: { l: number; c: number; h: number }): Color =>
+  ({ mode: "oklch", l: s.l, c: s.c, h: s.h }) as Color;
+
+const NOTATIONS: Record<Notation, (s: PaletteEntry) => string> = {
+  oklch: (s) => `oklch(${fmt(s.l)} ${fmt(s.c)} ${fmt(s.h)})`,
+  hex: (s) => formatHex(asColor(s)),
+  rgb: (s) => formatRgb(asColor(s)),
+  hsl: (s) => formatHsl(asColor(s)),
+};
+
+/** Stringify one palette step in the given color notation. */
+export function valueStr(s: PaletteEntry, notation: Notation): string {
+  return NOTATIONS[notation](s);
+}
+
+/** A Tailwind v4 @theme block; values in the given notation (oklch default). */
+export function toThemeCss(palette: Palette, notation: Notation = "oklch"): string {
+  const lines = palette.steps.map(
+    (s) => `  --color-${palette.name}-${s.step}: ${valueStr(s, notation)};`,
+  );
+  return ["@theme {", ...lines, "}"].join("\n");
+}
+
+/**
+ * An ANSI truecolor swatch strip — one labeled block per step, 50→950 —
+ * rendered from the palette's own colors. Labels stay plain text.
+ */
+export function toPreviewStrip(palette: Palette): string {
+  const ESC = String.fromCharCode(27);
+  const blocks = palette.steps.map((s) => {
+    const rgb = toRgb(asColor(s))!;
+    const [r, g, b] = [rgb.r, rgb.g, rgb.b].map((v) => Math.round((v ?? 0) * 255));
+    const label = s.step.toString().padStart(3);
+    return `${label} ${ESC}[48;2;${r};${g};${b}m      ${ESC}[0m`;
+  });
+  return blocks.join(" ");
+}
+
+/** A paste-ready Tailwind v3 config snippet for the same palette. */
+export function toTailwindV3(palette: Palette, notation: Notation = "oklch"): string {
+  const entries = palette.steps.map((s) => `          ${s.step}: "${valueStr(s, notation)}",`);
+  return [
+    "module.exports = {",
+    "  theme: {",
+    "    extend: {",
+    "      colors: {",
+    `        ${palette.name}: {`,
+    ...entries,
+    "        },",
+    "      },",
+    "    },",
+    "  },",
+    "};",
+  ].join("\n");
+}

package/src/name.ts

@@ -0,0 +1,42 @@
+import { colorsNamed, converter, differenceEuclidean, nearest, parse } from "culori";
+
+const toOklch = converter("oklch");
+
+export type Oklch = { l: number; c: number; h: number };
+
+type NamedColor = { name: string; color: Oklch };
+
+const NAMED_COLORS: NamedColor[] = Object.entries(colorsNamed).flatMap(([name, int]) => {
+  const color = toOklch(parse("#" + Number(int).toString(16).padStart(6, "0")));
+  return color && Number.isFinite(color.l) ? [{ name, color: normalize(color) }] : [];
+});
+
+const findNearest = nearest(NAMED_COLORS, differenceEuclidean("oklch"), (entry) => ({
+  mode: "oklch",
+  ...entry.color,
+}));
+
+function normalize(color: { l?: number; c?: number; h?: number }): Oklch {
+  return {
+    l: color.l ?? 0,
+    c: Number.isFinite(color.c) ? (color.c as number) : 0,
+    h: Number.isFinite(color.h) ? (color.h as number) : 0,
+  };
+}
+
+/** Kebab-case: lowercase; anything not [a-z0-9] collapses to a single dash. */
+export function kebabCase(input: string): string {
+  return input
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/(^-|-$)/g, "");
+}
+
+/** Closest CSS named color to the given color in OKLCH space, kebab-cased. */
+export function detectName(color: Oklch): string {
+  const [hit] = findNearest({ mode: "oklch", ...color });
+  if (!hit) {
+    throw new Error("no named colors available");
+  }
+  return kebabCase(hit.name);
+}

package/src/targets.ts

@@ -0,0 +1,44 @@
+/**
+ * Per-step lightness targets: mean L across the 17 chromatic families of
+ * Tailwind v4's theme.css.
+ */
+export const TARGETS: Record<number, number> = {
+  50: 0.9772,
+  100: 0.9504,
+  200: 0.9055,
+  300: 0.8405,
+  400: 0.7535,
+  500: 0.6827,
+  600: 0.5978,
+  700: 0.5149,
+  800: 0.4461,
+  900: 0.3946,
+  950: 0.2779,
+};
+
+/** Ramp endpoint bounds: the 50 and 950 steps clamp into these. */
+export const L_MAX = 0.985;
+export const L_MIN = 0.02;
+
+/** Bases beyond this cannot fit 4 distinct steps above/below. */
+export const L_TOO_LIGHT = 0.97;
+export const L_TOO_DARK = 0.03;
+
+/**
+ * Chroma taper ratios per step (C_step / C_500): mean ratio across the 17
+ * chromatic families of Tailwind v4's theme.css. Chroma peaks at the base
+ * step and tapers hard toward 50, gently toward 950.
+ */
+export const CHROMA_RATIOS: Record<number, number> = {
+  50: 0.0867,
+  100: 0.2082,
+  200: 0.3993,
+  300: 0.6594,
+  400: 0.9036,
+  500: 1,
+  600: 0.9823,
+  700: 0.8606,
+  800: 0.7083,
+  900: 0.5679,
+  950: 0.4013,
+};

package/tsconfig.json

@@ -0,0 +1,34 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+    "types": ["bun"],
+
+    "paths": {
+      "@/*": ["./src/*"]
+    },
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}