@clhaas/palette-kit 0.1.4 → 0.1.6

package/README.md

@@ -22,7 +22,9 @@ pnpm add @clhaas/palette-kit
 
 - 12-step scale (light/dark) from a seed.
 - Semantic tokens for UI (`radix-like-ui` preset).
-- Alpha scale for overlays.
+- Alpha scales per palette slot (chromatic alpha).
+- Overlay scales (black/white alpha).
+- Deterministic text scales for light/dark backgrounds.
 - Exporters for TS, JSON, CSS vars, Tailwind, and React Native.
 - Auto anchor selection per mode (light/dark), overridable via `anchorStep`.
 - Basic contrast and gamut diagnostics.
@@ -41,6 +43,10 @@ const theme = createTheme({
     danger: { source: "seed", value: "#ef4444" },
   },
   tokens: { preset: "radix-like-ui" },
+  text: {
+    darkBase: "#1C1C1E",
+    lightBase: "#F5F5F7",
+  },
   p3: true,
 });
 ```
@@ -95,6 +101,10 @@ export default {
   },
   tokens: { preset: "radix-like-ui" },
   alpha: { enabled: true },
+  text: {
+    darkBase: "#1C1C1E",
+    lightBase: "#F5F5F7",
+  },
   p3: true,
 };
 ```
@@ -124,6 +134,31 @@ const tokens: ThemeTokenMap = theme.tokens.light;
 const tokenName: ThemeTokenName = "bg.app";
 ```
 
+## Alpha, overlay, and text examples
+
+```ts
+const accentAlpha = theme.alpha?.accent.light[5];
+const overlay = theme.overlay.black[9];
+const textOnLight = theme.tokens.light["text.dark.primary"];
+const textOnDark = theme.tokens.dark["text.light.primary"];
+```
+
+## Migration note (alpha)
+
+Alpha scales are now generated per palette slot. If you previously used:
+
+```ts
+theme.alpha?.light[5];
+```
+
+Update to:
+
+```ts
+theme.alpha?.accent.light[5];
+```
+
+CSS variables were also updated from `--pk-alpha-<step>` to `--pk-alpha-<slot>-<step>`.
+
 ## React Native + Expo
 
 Use the React Native exporter and `useColorScheme()`:
@@ -164,6 +199,8 @@ Note: React Native does not support `color(display-p3 ...)` strings as drop-in c
 - `docs/tokens.md`
 - `docs/contrast.md`
 - `docs/alpha.md`
+- `docs/text.md`
+- `docs/overlays.md`
 - `docs/Why.md`
 - `docs/spec-implementation.md`
 - `docs/plan-tests.md`

package/dist/createTheme.d.ts

@@ -24,6 +24,10 @@ export type CreateThemeOptions = {
             dark?: ColorHex;
         };
     };
+    text?: {
+        darkBase?: ColorHex;
+        lightBase?: ColorHex;
+    };
     contrast?: {
         textPrimary?: number;
         textSecondary?: number;

package/dist/createTheme.js

@@ -3,6 +3,8 @@ import { onSolidTextTokens } from "./contrast/onSolid.js";
 import { adjustTextColor } from "./contrast/solveText.js";
 import { analyzeTheme } from "./diagnostics/analyzeTheme.js";
 import { generateScale } from "./generateScale.js";
+import { generateOverlayScale } from "./overlays/generateOverlayScale.js";
+import { generateTextScale } from "./text/generateTextScale.js";
 import { buildPresetTokens } from "./tokens/presetRadixLikeUi.js";
 export function createTheme(options) {
     const includeP3 = options.p3 ?? false;
@@ -64,6 +66,48 @@ export function createTheme(options) {
     tokens.dark["onSolid.primary"] = darkOnSolid.primary;
     tokens.dark["onSolid.secondary"] = darkOnSolid.secondary;
     tokens.dark["onSolid.disabled"] = darkOnSolid.disabled;
+    const textScale = generateTextScale({
+        darkBase: options.text?.darkBase,
+        lightBase: options.text?.lightBase,
+    });
+    const darkTextSteps = {
+        primary: 12,
+        secondary: 10,
+        tertiary: 9,
+        disabled: 8,
+    };
+    const lightTextSteps = {
+        primary: 1,
+        secondary: 3,
+        tertiary: 4,
+        disabled: 5,
+    };
+    for (const [step, value] of Object.entries(textScale.dark)) {
+        tokens.light[`text.dark.${step}`] = value;
+        tokens.dark[`text.dark.${step}`] = value;
+    }
+    for (const [step, value] of Object.entries(textScale.light)) {
+        tokens.light[`text.light.${step}`] = value;
+        tokens.dark[`text.light.${step}`] = value;
+    }
+    for (const [key, step] of Object.entries(darkTextSteps)) {
+        const token = `text.dark.${key}`;
+        tokens.light[token] = textScale.dark[step];
+        tokens.dark[token] = textScale.dark[step];
+    }
+    for (const [key, step] of Object.entries(lightTextSteps)) {
+        const token = `text.light.${key}`;
+        tokens.light[token] = textScale.light[step];
+        tokens.dark[token] = textScale.light[step];
+    }
+    tokens.light["text.primary"] = textScale.dark[darkTextSteps.primary];
+    tokens.light["text.secondary"] = textScale.dark[darkTextSteps.secondary];
+    tokens.light["text.tertiary"] = textScale.dark[darkTextSteps.tertiary];
+    tokens.light["text.disabled"] = textScale.dark[darkTextSteps.disabled];
+    tokens.dark["text.primary"] = textScale.light[lightTextSteps.primary];
+    tokens.dark["text.secondary"] = textScale.light[lightTextSteps.secondary];
+    tokens.dark["text.tertiary"] = textScale.light[lightTextSteps.tertiary];
+    tokens.dark["text.disabled"] = textScale.light[lightTextSteps.disabled];
     if (options.tokens?.overrides?.light) {
         Object.assign(tokens.light, options.tokens.overrides.light);
     }
@@ -76,13 +120,18 @@ export function createTheme(options) {
             light: options.alpha?.background?.light ?? "#ffffff",
             dark: options.alpha?.background?.dark ?? "#111111",
         };
-        alpha = generateAlphaScale(accentScale.light[9], background);
+        alpha = Object.fromEntries(Object.entries(scales).map(([slot, scale]) => [
+            slot,
+            generateAlphaScale(scale.light[9], background),
+        ]));
     }
-    const diagnostics = analyzeTheme({ scales, tokens, alpha });
+    const overlay = generateOverlayScale();
+    const diagnostics = analyzeTheme({ scales, tokens, alpha, overlay });
     return {
         scales,
         tokens,
         alpha,
+        overlay,
         diagnostics,
     };
 }

package/dist/exporters/toCssVars.d.ts

@@ -4,6 +4,7 @@ type CssVarsOptions = {
     includeTokens?: boolean;
     includeScales?: boolean;
     includeAlpha?: boolean;
+    includeOverlays?: boolean;
     includeP3?: boolean;
     lightSelector?: string;
     darkSelector?: string;

package/dist/exporters/toCssVars.js

@@ -7,8 +7,11 @@ function tokenToCssVar(token, prefix) {
 function scaleToCssVar(slot, step, prefix) {
     return `--${prefix}-scale-${slot}-${step}`;
 }
-function alphaToCssVar(step, prefix) {
-    return `--${prefix}-alpha-${step}`;
+function alphaToCssVar(slot, step, prefix) {
+    return `--${prefix}-alpha-${slot}-${step}`;
+}
+function overlayToCssVar(color, step, prefix) {
+    return `--${prefix}-overlay-${color}-${step}`;
 }
 function hexToP3(value) {
     return new Color(value).to("p3").toString({ format: "color" });
@@ -18,6 +21,7 @@ export function toCssVars(theme, options) {
     const includeTokens = options?.includeTokens ?? true;
     const includeScales = options?.includeScales ?? true;
     const includeAlpha = options?.includeAlpha ?? true;
+    const includeOverlays = options?.includeOverlays ?? true;
     const includeP3 = options?.includeP3 ?? false;
     const lightSelector = options?.lightSelector ?? ":root";
     const darkSelector = options?.darkSelector ?? ".dark";
@@ -38,8 +42,18 @@ export function toCssVars(theme, options) {
             }
         }
         if (includeAlpha && theme.alpha) {
-            for (const [step, value] of Object.entries(theme.alpha[mode])) {
-                lines.push(`  ${alphaToCssVar(Number(step), prefix)}: ${value};`);
+            for (const [slot, scale] of Object.entries(theme.alpha)) {
+                for (const [step, value] of Object.entries(scale[mode])) {
+                    lines.push(`  ${alphaToCssVar(slot, Number(step), prefix)}: ${value};`);
+                }
+            }
+        }
+        if (includeOverlays) {
+            for (const [step, value] of Object.entries(theme.overlay.black)) {
+                lines.push(`  ${overlayToCssVar("black", Number(step), prefix)}: ${value};`);
+            }
+            for (const [step, value] of Object.entries(theme.overlay.white)) {
+                lines.push(`  ${overlayToCssVar("white", Number(step), prefix)}: ${value};`);
             }
         }
         lines.push("}");
@@ -69,8 +83,18 @@ export function toCssVars(theme, options) {
                 }
             }
             if (includeAlpha && theme.alpha) {
-                for (const [step, value] of Object.entries(theme.alpha[mode])) {
-                    lines.push(`    ${alphaToCssVar(Number(step), prefix)}: ${hexToP3(value)};`);
+                for (const [slot, scale] of Object.entries(theme.alpha)) {
+                    for (const [step, value] of Object.entries(scale[mode])) {
+                        lines.push(`    ${alphaToCssVar(slot, Number(step), prefix)}: ${hexToP3(value)};`);
+                    }
+                }
+            }
+            if (includeOverlays) {
+                for (const [step, value] of Object.entries(theme.overlay.black)) {
+                    lines.push(`    ${overlayToCssVar("black", Number(step), prefix)}: ${hexToP3(value)};`);
+                }
+                for (const [step, value] of Object.entries(theme.overlay.white)) {
+                    lines.push(`    ${overlayToCssVar("white", Number(step), prefix)}: ${hexToP3(value)};`);
                 }
             }
             lines.push("  }");

package/dist/exporters/toReactNative.d.ts

@@ -3,28 +3,52 @@ type ReactNativeOptions = {
     includeTokens?: boolean;
     includeScales?: boolean;
     includeAlpha?: boolean;
+    includeOverlays?: boolean;
     includeP3?: boolean;
 };
-export declare function toReactNative(theme: Theme, options?: ReactNativeOptions): {
-    light: {
-        tokens: Record<string, `#${string}`>;
-        scales: {
-            [k: string]: Record<import("../types.js").Step, `#${string}`>;
+type Mode = "light" | "dark";
+type ModeTokens<T extends Theme, O extends ReactNativeOptions, M extends Mode> = O extends {
+    includeTokens: false;
+} ? Record<string, never> : T["tokens"][M];
+type ModeScales<T extends Theme, O extends ReactNativeOptions, M extends Mode> = O extends {
+    includeScales: false;
+} ? Record<string, never> : {
+    [K in keyof T["scales"]]: T["scales"][K][M];
+};
+type ThemeAlpha<T extends Theme> = T["alpha"] extends undefined ? undefined : T["alpha"];
+type ModeAlpha<T extends Theme, O extends ReactNativeOptions, M extends Mode> = O extends {
+    includeAlpha: false;
+} ? undefined : ThemeAlpha<T> extends undefined ? undefined : ThemeAlpha<T> extends Record<string, {
+    light: infer L;
+    dark: infer D;
+}> ? M extends "light" ? Record<string, L> : Record<string, D> : undefined;
+type ModeOverlays<T extends Theme, O extends ReactNativeOptions> = O extends {
+    includeOverlays: false;
+} ? undefined : T["overlay"];
+type ModeP3<T extends Theme, O extends ReactNativeOptions, M extends Mode> = O extends {
+    includeP3: true;
+} ? Partial<{
+    [K in keyof T["scales"]]: T["scales"][K] extends {
+        p3?: {
+            light: infer L;
+            dark: infer D;
         };
-        alpha: Record<import("../types.js").Step, `#${string}`> | undefined;
-        p3: {
-            [k: string]: Record<import("../types.js").Step, string> | undefined;
-        } | undefined;
+    } ? M extends "light" ? L : D : never;
+}> : undefined;
+type ReactNativeTheme<T extends Theme, O extends ReactNativeOptions> = {
+    overlay: ModeOverlays<T, O>;
+    light: {
+        tokens: ModeTokens<T, O, "light">;
+        scales: ModeScales<T, O, "light">;
+        alpha: ModeAlpha<T, O, "light">;
+        p3: ModeP3<T, O, "light">;
     };
     dark: {
-        tokens: Record<string, `#${string}`>;
-        scales: {
-            [k: string]: Record<import("../types.js").Step, `#${string}`>;
-        };
-        alpha: Record<import("../types.js").Step, `#${string}`> | undefined;
-        p3: {
-            [k: string]: Record<import("../types.js").Step, string> | undefined;
-        } | undefined;
+        tokens: ModeTokens<T, O, "dark">;
+        scales: ModeScales<T, O, "dark">;
+        alpha: ModeAlpha<T, O, "dark">;
+        p3: ModeP3<T, O, "dark">;
     };
 };
+export declare function toReactNative<T extends Theme, O extends ReactNativeOptions = ReactNativeOptions>(theme: T, options?: O): ReactNativeTheme<T, O>;
 export {};

package/dist/exporters/toReactNative.js

@@ -2,6 +2,7 @@ export function toReactNative(theme, options) {
     const includeTokens = options?.includeTokens ?? true;
     const includeScales = options?.includeScales ?? true;
     const includeAlpha = options?.includeAlpha ?? true;
+    const includeOverlays = options?.includeOverlays ?? true;
     const includeP3 = options?.includeP3 ?? false;
     function buildMode(mode) {
         const scales = includeScales
@@ -12,14 +13,20 @@ export function toReactNative(theme, options) {
                 .filter(([, scale]) => scale.p3?.[mode])
                 .map(([slot, scale]) => [slot, scale.p3?.[mode]]))
             : undefined;
+        const alpha = includeAlpha
+            ? (theme.alpha
+                ? Object.fromEntries(Object.entries(theme.alpha).map(([slot, scale]) => [slot, scale[mode]]))
+                : undefined)
+            : undefined;
         return {
-            tokens: includeTokens ? theme.tokens[mode] : {},
+            tokens: (includeTokens ? theme.tokens[mode] : {}),
             scales,
-            alpha: includeAlpha ? theme.alpha?.[mode] : undefined,
+            alpha,
             p3,
         };
     }
     return {
+        overlay: (includeOverlays ? theme.overlay : undefined),
         light: buildMode("light"),
         dark: buildMode("dark"),
     };

package/dist/exporters/toTailwind.d.ts

@@ -4,6 +4,7 @@ type TailwindOptions = {
     includeTokens?: boolean;
     includeScales?: boolean;
     includeAlpha?: boolean;
+    includeOverlays?: boolean;
     includeP3?: boolean;
 };
 export declare function toTailwind(theme: Theme, options?: TailwindOptions): {

package/dist/exporters/toTailwind.js

@@ -36,8 +36,25 @@ function alphaToNested(alpha, mode) {
         return undefined;
     }
     const output = {};
-    for (const [step, value] of Object.entries(alpha[mode])) {
-        output[String(step)] = value;
+    for (const [slot, scale] of Object.entries(alpha)) {
+        const stepMap = {};
+        for (const [step, value] of Object.entries(scale[mode])) {
+            stepMap[String(step)] = value;
+        }
+        output[slot] = stepMap;
+    }
+    return output;
+}
+function overlaysToNested(overlays) {
+    const output = {
+        black: {},
+        white: {},
+    };
+    for (const [step, value] of Object.entries(overlays.black)) {
+        output.black[String(step)] = value;
+    }
+    for (const [step, value] of Object.entries(overlays.white)) {
+        output.white[String(step)] = value;
     }
     return output;
 }
@@ -46,6 +63,7 @@ export function toTailwind(theme, options) {
     const includeTokens = options?.includeTokens ?? true;
     const includeScales = options?.includeScales ?? false;
     const includeAlpha = options?.includeAlpha ?? false;
+    const includeOverlays = options?.includeOverlays ?? false;
     const includeP3 = options?.includeP3 ?? false;
     function buildModeTokens(modeKey, useP3) {
         const colors = {};
@@ -58,6 +76,9 @@ export function toTailwind(theme, options) {
         if (includeAlpha && theme.alpha) {
             colors.alpha = alphaToNested(theme.alpha, modeKey);
         }
+        if (includeOverlays) {
+            colors.overlay = overlaysToNested(theme.overlay);
+        }
         return colors;
     }
     const colors = {};

package/dist/exporters/toTs.js

@@ -32,6 +32,7 @@ function typeExports() {
         'export type ThemeScaleName = keyof Theme["scales"];',
         'export type ThemeTokenName = keyof Theme["tokens"]["light"];',
         'export type ThemeTokenMap = Theme["tokens"]["light"];',
+        'export type ThemeOverlay = Theme["overlay"];',
         "",
     ].join("\n");
 }

package/dist/index.d.ts

@@ -15,4 +15,6 @@ export { toTailwind } from "./exporters/toTailwind.js";
 export { toTs, toTsWithMode } from "./exporters/toTs.js";
 export type { AnchorStepOption, AutoAnchorModeOptions, AutoAnchorOptions, GenerateScaleOptions, SeedNormalizeOptions, SeedNormalizeRange, } from "./generateScale.js";
 export { generateScale } from "./generateScale.js";
-export type { AlphaScale, ColorHex, ColorSource, OklchColor, RadixSeedName, Scale, ScaleColorMode, ScaleDiagnostics, Step, TemplateId, Theme, ThemeColorMode, ThemeDiagnostics, } from "./types.js";
+export { generateOverlayScale } from "./overlays/generateOverlayScale.js";
+export { generateTextScale } from "./text/generateTextScale.js";
+export type { AlphaScale, AlphaScales, ColorHex, ColorSource, OklchColor, OverlayScale, RadixSeedName, Scale, ScaleColorMode, ScaleDiagnostics, Step, TemplateId, TextScale, Theme, ThemeColorMode, ThemeDiagnostics, } from "./types.js";

package/dist/index.js

@@ -13,3 +13,5 @@ export { toReactNative } from "./exporters/toReactNative.js";
 export { toTailwind } from "./exporters/toTailwind.js";
 export { toTs, toTsWithMode } from "./exporters/toTs.js";
 export { generateScale } from "./generateScale.js";
+export { generateOverlayScale } from "./overlays/generateOverlayScale.js";
+export { generateTextScale } from "./text/generateTextScale.js";

package/dist/overlays/generateOverlayScale.d.ts

@@ -0,0 +1,2 @@
+import type { OverlayScale } from "../types.js";
+export declare function generateOverlayScale(): OverlayScale;

package/dist/overlays/generateOverlayScale.js

@@ -0,0 +1,34 @@
+import Color from "colorjs.io";
+const steps = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12];
+const alphaCurve = {
+    1: 0.05,
+    2: 0.1,
+    3: 0.15,
+    4: 0.2,
+    5: 0.3,
+    6: 0.4,
+    7: 0.5,
+    8: 0.6,
+    9: 0.7,
+    10: 0.8,
+    11: 0.9,
+    12: 0.95,
+};
+function mixWithAlpha(foreground, alpha) {
+    const color = new Color(foreground).to("srgb");
+    const [r, g, b] = color.coords;
+    const hex = new Color({ space: "srgb", coords: [r, g, b], alpha }).toString({
+        format: "hex",
+    });
+    return hex;
+}
+export function generateOverlayScale() {
+    const black = {};
+    const white = {};
+    for (const step of steps) {
+        const alpha = alphaCurve[step];
+        black[step] = mixWithAlpha("#000000", alpha);
+        white[step] = mixWithAlpha("#ffffff", alpha);
+    }
+    return { black, white };
+}

package/dist/text/generateTextScale.d.ts

@@ -0,0 +1,8 @@
+import type { ColorHex, TextScale } from "../types.js";
+type TextScaleOptions = {
+    darkBase?: ColorHex;
+    lightBase?: ColorHex;
+    deltaL?: number;
+};
+export declare function generateTextScale(options?: TextScaleOptions): TextScale;
+export {};

package/dist/text/generateTextScale.js

@@ -0,0 +1,18 @@
+import { compressToSrgb, hexToOklch, oklchToHex } from "../engine/oklch.js";
+const steps = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12];
+export function generateTextScale(options) {
+    const darkBase = options?.darkBase ?? "#1C1C1E";
+    const lightBase = options?.lightBase ?? "#F5F5F7";
+    const deltaL = options?.deltaL ?? 0.055;
+    const darkBaseOklch = hexToOklch(darkBase);
+    const lightBaseOklch = hexToOklch(lightBase);
+    const dark = {};
+    const light = {};
+    for (const step of steps) {
+        const darkL = Math.min(darkBaseOklch.l + (12 - step) * deltaL, 0.92);
+        const lightL = Math.max(lightBaseOklch.l - (step - 1) * deltaL, 0.12);
+        dark[step] = oklchToHex(compressToSrgb({ ...darkBaseOklch, l: darkL }));
+        light[step] = oklchToHex(compressToSrgb({ ...lightBaseOklch, l: lightL }));
+    }
+    return { dark, light };
+}

package/dist/types.d.ts

@@ -35,6 +35,15 @@ export type AlphaScale = {
     light: Record<Step, ColorHex>;
     dark: Record<Step, ColorHex>;
 };
+export type AlphaScales = Record<string, AlphaScale>;
+export type OverlayScale = {
+    black: Record<Step, ColorHex>;
+    white: Record<Step, ColorHex>;
+};
+export type TextScale = {
+    dark: Record<Step, ColorHex>;
+    light: Record<Step, ColorHex>;
+};
 export type ThemeDiagnostics = {
     contrast: Record<string, number>;
     outOfGamutCount: number;
@@ -46,7 +55,8 @@ export type Theme = {
         light: Record<string, ColorHex>;
         dark: Record<string, ColorHex>;
     };
-    alpha?: AlphaScale;
+    alpha?: AlphaScales;
+    overlay: OverlayScale;
     diagnostics?: ThemeDiagnostics;
 };
 export type ThemeColorMode = Omit<Theme, "scales"> & {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clhaas/palette-kit",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Easy way to create the color palette of your app",
   "license": "MIT",
   "author": "Claus Haas",