@sethyrung/tailshade 0.1.0 → 0.3.0

package/README.md

@@ -16,9 +16,9 @@ $ tailshade '#ff0000'
 }
 ```
 
-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.
+Your base color lands verbatim at `<name>-500` (or your chosen `--step`),
+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
 
@@ -51,6 +51,7 @@ The base color accepts any CSS format — hex, `rgb()`, `hsl()`, named colors, o
 | Flag                              | Effect                                                              |
 | --------------------------------- | ------------------------------------------------------------------- |
 | _(none)_                          | Tailwind v4 `@theme` block, oklch values (default)                  |
+| `--step <50..950>`                | Anchor base color to a specific shade (default: 500)                |
 | `--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)               |
@@ -60,6 +61,7 @@ The base color accepts any CSS format — hex, `rgb()`, `hsl()`, named colors, o
 Examples:
 
 ```bash
+tailshade '#111410' --step 700
 tailshade 'oklch(0.6 0.1 29)' --name brand
 tailshade '#ff0000' --v3 --format hex
 tailshade 'teal' --preview
@@ -94,11 +96,12 @@ module.exports = {
 ## 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.
+- Anchor the base color verbatim at step 500 (or the step given by `--step`);
+  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.
+  scaled relative to the anchor step, 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).

package/dist/cli.js

@@ -49,8 +49,19 @@ var TARGETS = {
 };
 var L_MAX = 0.985;
 var L_MIN = 0.02;
-var L_TOO_LIGHT = 0.97;
-var L_TOO_DARK = 0.03;
+var LIGHTNESS_BOUNDS = {
+  50: { min: 0.04, max: 0.985 },
+  100: { min: 0.035, max: 0.98 },
+  200: { min: 0.03, max: 0.98 },
+  300: { min: 0.03, max: 0.975 },
+  400: { min: 0.03, max: 0.97 },
+  500: { min: 0.03, max: 0.97 },
+  600: { min: 0.03, max: 0.97 },
+  700: { min: 0.025, max: 0.97 },
+  800: { min: 0.025, max: 0.97 },
+  900: { min: 0.025, max: 0.965 },
+  950: { min: 0.02, max: 0.96 }
+};
 var CHROMA_RATIOS = {
   50: 0.0867,
   100: 0.2082,
@@ -78,12 +89,13 @@ function target(step) {
   }
   return t;
 }
-function taperRatio(step) {
+function taperRatio(step, anchorStep = 500) {
   const ratio = CHROMA_RATIOS[step];
-  if (ratio === undefined) {
-    throw new Error(`missing chroma taper ratio for step ${step}`);
+  const anchorRatio = CHROMA_RATIOS[anchorStep];
+  if (ratio === undefined || anchorRatio === undefined) {
+    throw new Error(`missing chroma taper ratio for step ${step} or anchor ${anchorStep}`);
   }
-  return ratio;
+  return ratio / anchorRatio;
 }
 function parseBase(input) {
   const color = parse2(input);
@@ -98,28 +110,39 @@ function parseBase(input) {
   const c = Number.isFinite(oklch.c) ? oklch.c : 0;
   return { l: oklch.l ?? 0, c, h };
 }
-function lightnessLadder(baseL) {
-  if (baseL > L_TOO_LIGHT) {
+function lightnessLadder(baseL, anchorStep = 500) {
+  const bounds = LIGHTNESS_BOUNDS[anchorStep] ?? { min: 0.03, max: 0.97 };
+  if (baseL > bounds.max) {
     throw new PaletteError("base color is too light to build a 50–950 ramp");
   }
-  if (baseL < L_TOO_DARK) {
+  if (baseL < bounds.min) {
     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 tAnchor = target(anchorStep);
+  const upExtent = target(50) - tAnchor;
+  const downExtent = target(950) - tAnchor;
   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 scaleUp = upExtent === 0 ? 1 : (end50 - baseL) / upExtent;
+  const scaleDown = downExtent === 0 ? 1 : (end950 - baseL) / downExtent;
   const ladder = new Map;
   for (const step of STEPS) {
-    if (step === 500) {
+    if (step === anchorStep) {
       ladder.set(step, baseL);
       continue;
     }
-    const scale = step < 500 ? scaleUp : scaleDown;
-    ladder.set(step, baseL + (target(step) - t500) * scale);
+    const scale = step < anchorStep ? scaleUp : scaleDown;
+    ladder.set(step, baseL + (target(step) - tAnchor) * scale);
+  }
+  const values = STEPS.map((s) => round3(ladder.get(s)));
+  for (let i = 1;i < values.length; i++) {
+    if (values[i] >= values[i - 1]) {
+      if (baseL > target(anchorStep)) {
+        throw new PaletteError("base color is too light to build a 50–950 ramp");
+      } else {
+        throw new PaletteError("base color is too dark to build a 50–950 ramp");
+      }
+    }
   }
   return ladder;
 }
@@ -149,16 +172,16 @@ function maxInGamutChroma(l, c, h) {
 }
 var round3 = (n) => Math.round(n * 1000) / 1000;
 var floor3 = (n) => Math.floor(n * 1000) / 1000;
-function generatePalette(input) {
+function generatePalette(input, anchorStep = 500) {
   const base = parseBase(input);
-  const ladder = lightnessLadder(base.l);
+  const ladder = lightnessLadder(base.l, anchorStep);
   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));
+    const c = floor3(maxInGamutChroma(l, base.c * taperRatio(step, anchorStep), h));
     return { step, l, c, h };
   });
-  return { name: detectName(base), base, steps };
+  return { name: detectName(base), base, anchorStep, steps };
 }
 
 // src/format.ts
@@ -210,23 +233,26 @@ function toTailwindV3(palette, notation = "oklch") {
 
 // src/cli.ts
 var NOTATIONS2 = ["oklch", "hex", "rgb", "hsl"];
-var USAGE = `Usage: tailshade '<color>' [--name <name>] [--v3] [--format <oklch|hex|rgb|hsl>] [--preview]
+var USAGE = `Usage: tailshade '<color>' [--step <50..950>] [--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.
+The base color anchors at step 500 by default — pass --step to anchor at any
+shade (50, 100, 200, ..., 950). 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 '#111410' --step 700
          tailshade '#ff0000' --name brand
          tailshade '#ff0000' --v3 --format hex --preview`;
 function main(argv) {
   let color;
   let name;
+  let step = 500;
   let v3 = false;
   let preview = false;
   let notation;
@@ -235,6 +261,18 @@ function main(argv) {
     if (arg === "--help" || arg === "-h") {
       return { output: USAGE, exitCode: 0 };
     }
+    if (arg === "--step") {
+      const value = argv[++i];
+      if (value === undefined || value.startsWith("--")) {
+        return usage("--step requires a value");
+      }
+      const num = Number(value);
+      if (!Number.isInteger(num) || !STEPS.includes(num)) {
+        return usage(`--step '${value}' expects one of: ${STEPS.join(", ")}`);
+      }
+      step = num;
+      continue;
+    }
     if (arg === "--name") {
       const value = argv[++i];
       if (value === undefined || value.startsWith("--")) {
@@ -274,7 +312,7 @@ function main(argv) {
     return usage("expected exactly one color argument");
   }
   try {
-    const palette = generatePalette(color);
+    const palette = generatePalette(color, step);
     if (name !== undefined) {
       const kebab = kebabCase(name);
       if (!kebab) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sethyrung/tailshade",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Generate a full Tailwind CSS palette (50-950) from a single base color",
   "keywords": [
     "cli",

package/src/cli.ts

@@ -1,4 +1,4 @@
-import { generatePalette, PaletteError } from "@/core";
+import { generatePalette, PaletteError, STEPS, type Step } from "@/core";
 import { toPreviewStrip, toTailwindV3, toThemeCss, type Notation } from "@/format";
 import { kebabCase } from "@/name";
 
@@ -6,18 +6,20 @@ 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]
+const USAGE = `Usage: tailshade '<color>' [--step <50..950>] [--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.
+The base color anchors at step 500 by default — pass --step to anchor at any
+shade (50, 100, 200, ..., 950). 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 '#111410' --step 700
          tailshade '#ff0000' --name brand
          tailshade '#ff0000' --v3 --format hex --preview`;
 
@@ -28,6 +30,7 @@ Example: tailshade '#ff0000'
 export function main(argv: string[]): CliResult {
   let color: string | undefined;
   let name: string | undefined;
+  let step: Step = 500;
   let v3 = false;
   let preview = false;
   let notation: Notation | undefined;
@@ -37,6 +40,18 @@ export function main(argv: string[]): CliResult {
     if (arg === "--help" || arg === "-h") {
       return { output: USAGE, exitCode: 0 };
     }
+    if (arg === "--step") {
+      const value = argv[++i];
+      if (value === undefined || value.startsWith("--")) {
+        return usage("--step requires a value");
+      }
+      const num = Number(value);
+      if (!Number.isInteger(num) || !STEPS.includes(num as Step)) {
+        return usage(`--step '${value}' expects one of: ${STEPS.join(", ")}`);
+      }
+      step = num as Step;
+      continue;
+    }
     if (arg === "--name") {
       const value = argv[++i];
       if (value === undefined || value.startsWith("--")) {
@@ -77,7 +92,7 @@ export function main(argv: string[]): CliResult {
   }
 
   try {
-    const palette = generatePalette(color);
+    const palette = generatePalette(color, step);
     if (name !== undefined) {
       const kebab = kebabCase(name);
       if (!kebab) {

package/src/core.ts

@@ -1,6 +1,6 @@
 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";
+import { CHROMA_RATIOS, L_MAX, L_MIN, LIGHTNESS_BOUNDS, 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];
@@ -8,7 +8,7 @@ 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 type Palette = { name: string; base: Oklch; anchorStep: Step; steps: PaletteEntry[] };
 
 export class PaletteError extends Error {}
 
@@ -20,12 +20,13 @@ function target(step: Step): number {
   return t;
 }
 
-function taperRatio(step: Step): number {
+function taperRatio(step: Step, anchorStep: Step = 500): number {
   const ratio = CHROMA_RATIOS[step];
-  if (ratio === undefined) {
-    throw new Error(`missing chroma taper ratio for step ${step}`);
+  const anchorRatio = CHROMA_RATIOS[anchorStep];
+  if (ratio === undefined || anchorRatio === undefined) {
+    throw new Error(`missing chroma taper ratio for step ${step} or anchor ${anchorStep}`);
   }
-  return ratio;
+  return ratio / anchorRatio;
 }
 
 /**
@@ -51,31 +52,44 @@ function parseBase(input: string): Oklch {
  * 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) {
+export function lightnessLadder(baseL: number, anchorStep: Step = 500): Map<Step, number> {
+  const bounds = LIGHTNESS_BOUNDS[anchorStep] ?? { min: 0.03, max: 0.97 };
+  if (baseL > bounds.max) {
     throw new PaletteError("base color is too light to build a 50–950 ramp");
   }
-  if (baseL < L_TOO_DARK) {
+  if (baseL < bounds.min) {
     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 tAnchor = target(anchorStep);
+  const upExtent = target(50) - tAnchor;
+  const downExtent = target(950) - tAnchor;
 
   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 scaleUp = upExtent === 0 ? 1 : (end50 - baseL) / upExtent;
+  const scaleDown = downExtent === 0 ? 1 : (end950 - baseL) / downExtent;
 
   const ladder = new Map<Step, number>();
   for (const step of STEPS) {
-    if (step === 500) {
+    if (step === anchorStep) {
       ladder.set(step, baseL);
       continue;
     }
-    const scale = step < 500 ? scaleUp : scaleDown;
-    ladder.set(step, baseL + (target(step) - t500) * scale);
+    const scale = step < anchorStep ? scaleUp : scaleDown;
+    ladder.set(step, baseL + (target(step) - tAnchor) * scale);
   }
+
+  const values = STEPS.map((s) => round3(ladder.get(s)!));
+  for (let i = 1; i < values.length; i++) {
+    if (values[i]! >= values[i - 1]!) {
+      if (baseL > target(anchorStep)) {
+        throw new PaletteError("base color is too light to build a 50–950 ramp");
+      } else {
+        throw new PaletteError("base color is too dark to build a 50–950 ramp");
+      }
+    }
+  }
+
   return ladder;
 }
 
@@ -112,14 +126,14 @@ const floor3 = (n: number) => Math.floor(n * 1000) / 1000;
  * 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 {
+export function generatePalette(input: string, anchorStep: Step = 500): Palette {
   const base = parseBase(input);
-  const ladder = lightnessLadder(base.l);
+  const ladder = lightnessLadder(base.l, anchorStep);
   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));
+    const c = floor3(maxInGamutChroma(l, base.c * taperRatio(step, anchorStep), h));
     return { step, l, c, h };
   });
-  return { name: detectName(base), base, steps };
+  return { name: detectName(base), base, anchorStep, steps };
 }

package/src/targets.ts

@@ -20,10 +20,24 @@ export const TARGETS: Record<number, number> = {
 export const L_MAX = 0.985;
 export const L_MIN = 0.02;
 
-/** Bases beyond this cannot fit 4 distinct steps above/below. */
+/** Bases beyond this cannot fit distinct steps above/below. */
 export const L_TOO_LIGHT = 0.97;
 export const L_TOO_DARK = 0.03;
 
+export const LIGHTNESS_BOUNDS: Record<number, { min: number; max: number }> = {
+  50: { min: 0.04, max: 0.985 },
+  100: { min: 0.035, max: 0.98 },
+  200: { min: 0.03, max: 0.98 },
+  300: { min: 0.03, max: 0.975 },
+  400: { min: 0.03, max: 0.97 },
+  500: { min: 0.03, max: 0.97 },
+  600: { min: 0.03, max: 0.97 },
+  700: { min: 0.025, max: 0.97 },
+  800: { min: 0.025, max: 0.97 },
+  900: { min: 0.025, max: 0.965 },
+  950: { min: 0.02, max: 0.96 },
+};
+
 /**
  * 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