okchroma 0.1.0

package/dist-lib/types/engine/alphaPapers.d.ts

@@ -0,0 +1,14 @@
+import type { GeneratedScale } from './colorEngine';
+export type AlphaMode = 'light' | 'dark';
+export interface AlphaPaper {
+    stop: number;
+    name: string;
+    overlayHex: string;
+    alpha: number;
+    capped?: 'gamut' | 'ink-bars';
+}
+export declare const ALPHA_TOL_APP = 1;
+export declare const ALPHA_LIFT_FRACTION = 0.5;
+export declare const compositeHex: (fg: string, bg: string, a: number) => string;
+export declare function alphaSep(familyScales: GeneratedScale[]): number;
+export declare function alphaPapersFor(scale: GeneratedScale, neutral: GeneratedScale, mode: AlphaMode, sep: number): AlphaPaper[];

package/dist-lib/types/engine/archetypes.d.ts

@@ -0,0 +1,13 @@
+export type Archetype = 'near-black' | 'dark' | 'rich' | 'vivid' | 'bright' | 'light';
+export declare const ARCHETYPES: Array<{
+    name: Archetype;
+    min: number;
+    max: number;
+    medianL: number;
+}>;
+export declare function classifyArchetype(L: number): Archetype;
+export declare function medianLForArchetype(archetype: Archetype): number;
+export declare function hoverL(L: number): number;
+export declare function pressedL(L: number): number;
+export declare function stateStepL(restL: number, _mode: 'light' | 'dark', k: 1 | 2): number;
+export declare function stateFillL(restL: number, mode: 'light' | 'dark', k: 1 | 2): number;

package/dist-lib/types/engine/collision.d.ts

@@ -0,0 +1,43 @@
+import type { GeneratedScale, ColorStop } from './colorEngine';
+import type { SignalDef } from './signals';
+export declare const HUE_GATE_DEG = 30;
+export declare const DELTA_E_THRESHOLD = 0.16;
+export declare const DARK_DELTA_E_THRESHOLD = 0.1;
+export { RED_GATE, redGateDist } from './colorMath';
+export type Mode = 'light' | 'dark';
+export interface CollisionCheck {
+    signal: SignalDef['name'];
+    mode: Mode;
+    dHue: number;
+    hueGate: boolean;
+    deltaE: number;
+    collides: boolean;
+}
+export declare function stopDeltaE(s1: ColorStop, s2: ColorStop): number;
+export declare function checkCollision(brand: GeneratedScale, signalScale: GeneratedScale, signalDef: SignalDef, mode: Mode): CollisionCheck;
+export declare const HUE_COLLISION_WASH_DEG = 15;
+export declare const HUE_COLLISION_MIN_V = 0.5;
+export declare const SECONDARY_NOTE_MIN_V: number;
+export interface HueCollisionCheck {
+    signal: SignalDef['name'];
+    dHueWash: {
+        light: number;
+        dark: number;
+    };
+    washDeltaE: {
+        light: number;
+        dark: number;
+    };
+    vividness: number;
+    collides: boolean;
+}
+export declare function checkHueCollision(brand: GeneratedScale, signalScale: GeneratedScale, signalDef: SignalDef, opts?: {
+    minV?: number;
+}): HueCollisionCheck;
+export declare const YELLOW_SPLIT_H = 96;
+export declare function warningVariant(brand: GeneratedScale, warningScale: GeneratedScale, warningDef: SignalDef): 'lemon' | 'macaroni' | null;
+export interface BrandCollisionReport {
+    checks: CollisionCheck[];
+    collidesWith: SignalDef['name'][];
+}
+export declare function checkAllCollisions(brand: GeneratedScale, signalScales: Map<SignalDef['name'], GeneratedScale>): BrandCollisionReport;

package/dist-lib/types/engine/colorEngine.d.ts

@@ -0,0 +1,109 @@
+import { type Archetype } from './archetypes';
+import { type DarkCtaKind } from './stopTable';
+import { type NeutralLevel } from './neutralCurve';
+export type { NeutralLevel } from './neutralCurve';
+export { SUBTLE_SECONDARY_MULT, SUBTLE_SECONDARY_MULT_CANDIDATES } from './neutralCurve';
+import { type ColorStop } from './colorMath';
+export { goldSpineHue, torsionedHue, hexToOklch, RED_COOL_DEG, redCoolWeight, inRedBand, RED_PIVOT_H, redRepelShiftDeg, inRedRepelBand, } from './colorMath';
+export type { ColorStop } from './colorMath';
+import { type ContrastProfile } from './requirements/profiles';
+export type { ContrastProfile } from './requirements/profiles';
+export interface GeneratedScale {
+    name: string;
+    archetype: Archetype;
+    brandL: number;
+    brandC: number;
+    brandH: number;
+    onFillTextIsWhite: boolean;
+    onFillTextIsWhiteDark: boolean;
+    light: ColorStop[];
+    dark: ColorStop[];
+    cta: ColorStop;
+    ctaHover: ColorStop;
+    ctaPressed: ColorStop;
+    ctaDark: ColorStop;
+    ctaHoverDark: ColorStop;
+    ctaPressedDark: ColorStop;
+    ctaRepelled?: {
+        light: boolean;
+        dark: boolean;
+    };
+    identityHex?: string;
+    paper0?: ColorStop;
+    paper0Dark?: ColorStop;
+    ink0?: ColorStop;
+    ink0Dark?: ColorStop;
+}
+export interface GenerateOptions {
+    hueShiftDeg?: number;
+    chromaScale?: number;
+    subtleChromaScale?: number;
+    darkFillMinL?: number;
+    enforceOnFillContrast?: boolean;
+    coolRedDark?: boolean;
+    suppressRedCool?: boolean;
+    goldBoost?: boolean;
+    signalWarmDrift?: boolean;
+    style?: 'default' | 'deeper' | 'full-chroma';
+    chromaCurve?: (L: number, mode: 'light' | 'dark') => number;
+    darkChromaCurve?: (L: number, H: number, brandC: number, ctaC?: number) => number;
+    darkCtaC?: DarkCtaKind;
+    ctaSolve?: {
+        seed: {
+            L: number;
+            C: number;
+            H: number;
+        };
+        red: {
+            L: number;
+            C: number;
+            H: number;
+        };
+        redDark: {
+            L: number;
+            C: number;
+            H: number;
+        };
+    };
+    heat?: number;
+    darkCtaFlatApp?: number;
+    contrastProfile?: ContrastProfile;
+    apcaClearance?: boolean;
+    apcaClearanceLc?: number;
+    deltaLightStops?: {
+        stop: number;
+        L: number;
+        C: number;
+        H: number;
+    }[];
+    deltaCarry?: boolean;
+    inkGround?: {
+        light: {
+            L: number;
+            C: number;
+            H: number;
+        };
+        dark: {
+            L: number;
+            C: number;
+            H: number;
+        };
+    };
+    deltaHKPlace?: boolean;
+    deltaChromaEq?: boolean;
+    deltaLiftFloor?: boolean;
+}
+export declare function generateScale(hex: string, scaleName: string, forcedArchetype?: Archetype, opts?: GenerateOptions): GeneratedScale;
+export type NeutralSource = 'secondary' | 'custom';
+export declare function neutralTintHue(primaryH: number, source?: NeutralSource, secondaryH?: number, customHex?: string | null): number;
+export declare function generateNeutralScale(brandH: number, level?: NeutralLevel, contrastProfile?: ContrastProfile): GeneratedScale;
+export declare function generateSubtleSecondary(hex: string, opts?: {
+    contrastProfile?: ContrastProfile;
+    mult?: number;
+    pastelK?: number;
+    curve?: (L: number, mode: 'light' | 'dark') => number;
+    ctaL?: {
+        light: number;
+        dark: number;
+    };
+}): GeneratedScale;

package/dist-lib/types/engine/colorMath.d.ts

@@ -0,0 +1,181 @@
+import { type Gamut } from './constraints';
+export declare function goldSpineHue(L: number): number;
+export declare function torsionedHue(brandH: number, stopL: number, anchorL: number, offPathG: number): number;
+export declare const SPINE_OFFPATH_SIGMA = 20;
+export declare const sigmoid: (x: number) => number;
+export declare const gauss: (x: number, sigma: number) => number;
+export declare function hueDelta(h: number, center: number): number;
+export declare function oklabDist(a: {
+    L: number;
+    C: number;
+    H: number;
+}, b: {
+    L: number;
+    C: number;
+    H: number;
+}): number;
+export declare const RED_GATE: {
+    readonly wDark: 0.65;
+    readonly wLight: 1.6;
+    readonly wDust: 1.4;
+    readonly wGoldArc: 1.6;
+    readonly G: 0.09;
+    readonly releaseMargin: 0.005;
+};
+export declare function redGateDist(c: {
+    L: number;
+    C: number;
+    H: number;
+}, red: {
+    L: number;
+    C: number;
+    H: number;
+}): number;
+export declare const RED_KEEP_BOX: {
+    readonly hLo: 20;
+    readonly hHi: 44;
+    readonly cMin: 0.18;
+    readonly lLo: 0.5;
+    readonly lHi: 0.62;
+};
+export declare function inRedKeepBox(L: number, C: number, H: number): boolean;
+export declare const RED_VIVID_ARC: {
+    readonly hLo: 5;
+    readonly hHi: 50;
+    readonly vividMin: 0.85;
+    readonly lLo: 0.55;
+    readonly lHi: 0.75;
+};
+export declare function inRedVividArc(L: number, C: number, H: number): boolean;
+export declare const RED_SOLVE: {
+    readonly wDark: 0.6;
+    readonly ring: 0.02;
+    readonly magentaDh: -14;
+    readonly magentaMinL: 0.53;
+    readonly magentaUpRatio: 2.5;
+    readonly vividMin: 0.85;
+    readonly goldDh: 1.5;
+    readonly vividMinL: 0.53;
+    readonly trueRedBrightCut: 0.67;
+    readonly brickHLo: 20;
+    readonly brickHHi: 50;
+    readonly brickLLo: 0.36;
+    readonly brickLHi: 0.52;
+    readonly brickVividMin: 0.55;
+    readonly brickCool: -4;
+    readonly brickCoolGold: -3;
+    readonly brickDesat: 0.85;
+    readonly brickExtraDeep: 0.02;
+    readonly coreL: readonly [0.49, 0.47, 0.45];
+    readonly edgeL: readonly [0.65, 0.68, 0.71, 0.75];
+    readonly redHuesWarmBrand: readonly [28, 24, 33.3, 38];
+    readonly redHuesMagentaBrand: readonly [33.3, 38, 28];
+    readonly redHueMagentaDh: -15;
+};
+export declare function redSolveDist(c: {
+    L: number;
+    C: number;
+    H: number;
+}, red: {
+    L: number;
+    C: number;
+    H: number;
+}): number;
+export declare function inBrickBand(L: number, C: number, H: number): boolean;
+export declare const RED_SPLIT: {
+    readonly redDLBase: -0.1;
+    readonly redDLBump: -0.04;
+    readonly redDLSigma: 7;
+    readonly brandDLMax: 0.08;
+    readonly brandSigmaMagenta: 21.5;
+    readonly brandSigmaGold: 6;
+    readonly coolDeg: -5;
+    readonly coolKneeDh: 9;
+    readonly coolSoftness: 2.5;
+};
+export declare function vividSplit(dh: number): {
+    redDL: number;
+    brandDL: number;
+    redDH: number;
+};
+export declare const RED_DEEP_PIVOT = 0.5;
+export declare const RED_VARIANT_L_MIN = 0.45;
+export declare const RED_TORSION_CENTER_H = 35.5;
+export declare const RED_TORSION_SOFTNESS = 3.5;
+export declare const RED_BAND_LO_H = 12;
+export declare const RED_BAND_LO_SOFTNESS = 2;
+export declare const VIVID_C = 0.13;
+export declare const LIGHT_DRIFT_COOL_HI = 88;
+export declare const LIGHT_DRIFT_COOL_RANGE = 16;
+export declare const BRAND_BELL_H = 95;
+export declare const BRAND_BELL_SIGMA = 55;
+export declare const BRAND_BELL_AMOUNT = 0.6;
+export declare const BRAND_BELL_L_HI = 0.95;
+export declare const BRAND_BELL_L_LO = 0.76;
+export declare const BRAND_BELL_RED_H = 33.3;
+export declare const BRAND_BELL_RED_SIGMA = 30;
+export declare const HUE_NOISE_C = 0.008;
+export declare const MUTED_BLEND_DENOM = 0.55;
+export declare const CREAM_UPPER_H = 105;
+export declare const CREAM_UPPER_SOFTNESS = 5;
+export declare const DEEPER_BAND_H_LO = 55;
+export declare const DEEPER_BAND_H_HI = 100;
+export declare const DEEPER_BAND_H_SOFT = 4;
+export declare const DEEPER_BAND_U_LO = 0.1;
+export declare const DEEPER_BAND_U_HI = 0.7;
+export declare const DEEPER_BAND_U_SOFT = 0.015;
+export declare const DEEPER_STRENGTH = 0.85;
+export declare const RED_COOL_DEG = 10.8;
+export declare function redCoolWeight(brandH: number): number;
+export declare function inRedBand(h: number): boolean;
+export declare const RED_PIVOT_H = 33.3;
+export declare const RED_WARM_EXIT_H = 44;
+export declare const RED_WARM_EXIT_SOFTNESS = 3.5;
+export declare const RED_REPEL_HI_H = 41.5;
+export declare function inRedRepelBand(h: number): boolean;
+export declare const RED_EXIT_FLOOR_H = 30.8;
+export declare const RED_EXIT_FLOOR_SOFTNESS = 0.9;
+export declare const RED_WARM_EXIT_FLOOR_H = 35.3;
+export declare const RED_WARM_EXIT_FLOOR_SOFTNESS = 0.8;
+export declare const RED_PIVOT_EXIT_DEG = 14;
+export declare function redRepelShiftDeg(brandH: number): number;
+export declare function maxChromaAt(L: number, H: number, gamut?: Gamut): number;
+export declare function medianGamutCAt(L: number, gamut?: Gamut): number;
+export declare function hexToOklch(hex: string): {
+    L: number;
+    C: number;
+    H: number;
+};
+export declare function oklchToSrgbUnclamped(L: number, C: number, H: number): {
+    r: number;
+    g: number;
+    b: number;
+};
+export declare function srgbEmitChannels(s: {
+    L: number;
+    C: number;
+    H: number;
+}): {
+    r: number;
+    g: number;
+    b: number;
+};
+export declare const masterEmitChannels: (s: {
+    L: number;
+    C: number;
+    H: number;
+}) => [number, number, number];
+export interface ColorStop {
+    stop: number;
+    L: number;
+    C: number;
+    H: number;
+    r: number;
+    g: number;
+    b: number;
+}
+export declare function applyChromaFloor(C: number, multiplier: number, floorBase: number, floorStrength: number): number;
+export declare const DARK_FLOOR_FULL_C = 0.022;
+export declare const DARK_FLOOR_MUTED_MAX_C = 0.04;
+export declare function makeStop(stop: number, L: number, C: number, H: number, gamut?: Gamut): ColorStop;
+export declare function onTextIsWhite(Y: number, L: number, C: number, H: number, enforce: boolean, ratioFloor?: number): boolean;

package/dist-lib/types/engine/constraints.d.ts

@@ -0,0 +1,18 @@
+export type Gamut = 'srgb' | 'p3';
+export declare const MASTER_GAMUT: Gamut;
+export declare function oklchToLinearRgb(L: number, C: number, H: number): [number, number, number];
+export declare function oklchToXyz(L: number, C: number, H: number): [number, number, number];
+export declare function oklchToLinearP3(L: number, C: number, H: number): [number, number, number];
+export declare const linearChannels: (L: number, C: number, H: number, gamut: Gamut) => [number, number, number];
+export declare function encodedChannels(L: number, C: number, H: number, gamut?: Gamut): [number, number, number];
+export declare function wcagY(L: number, C: number, H: number, gamut?: Gamut): number;
+export declare function contrastRatio(Y1: number, Y2: number): number;
+export declare function legalRatio(L: number, C: number, H: number, otherY: number): number;
+export declare function shippedY(L: number, C: number, H: number): number;
+export declare function findLForY(targetY: number, C: number, H: number, gamut?: Gamut): number;
+export declare function findLForContrast(startL: number, C: number, H: number, bgY: number, targetContrast: number): number;
+export declare function findLForContrastUp(startL: number, C: number, H: number, bgY: number, targetContrast: number): number;
+export declare function apcaY(r: number, g: number, b: number, gamut?: Gamut): number;
+export declare function apcaLc(txtY: number, bgY: number): number;
+export declare function findMaxLForContrast(C: number, H: number, bgY: number, targetContrast: number): number;
+export declare function clampChromaToGamut(L: number, C: number, H: number, gamut?: Gamut): number;

package/dist-lib/types/engine/cssRender.d.ts

@@ -0,0 +1,32 @@
+import { type GeneratedScale, type ColorStop, type NeutralLevel, type ContrastProfile } from './colorEngine';
+import { type ResolvedBrand, type SecondaryStyle } from './resolve';
+export declare function toHex(r: number, g: number, b: number): string;
+export declare const stopHex: (s: ColorStop) => string;
+export declare const P3_SUPPORTS = "@supports (color: color(display-p3 1 1 1))";
+export declare const P3_MEDIA = "@media (color-gamut: p3)";
+export declare function stopsToVars(stops: ColorStop[], prefix: string): string;
+export declare const CTA_BORDER_LC_FLOOR = 15;
+export declare function pageStopFor(neutral: GeneratedScale, mode: 'light' | 'dark'): ColorStop | undefined;
+export declare const OFFSET_ALPHAS: {
+    readonly 6: 0.06;
+    readonly 8: 0.08;
+    readonly 16: 0.16;
+};
+export type OffsetRung = keyof typeof OFFSET_ALPHAS;
+export declare const ctaBorderRung: (prefix: string) => OffsetRung;
+export declare const offsetLeafName: (rung: OffsetRung) => string;
+export declare const offsetVarName: (rung: OffsetRung) => string;
+export declare const offsetTokenPath: (rung: OffsetRung) => string;
+export declare const TRANSPARENT_VAR = "--alpha-transparent";
+export declare const offsetRgba: (rung: OffsetRung, mode: "light" | "dark") => string;
+export declare const alphaRootVars: (mode: "light" | "dark") => string[];
+export declare function ctaPageLc(s: GeneratedScale, mode: 'light' | 'dark', page: ColorStop): number;
+export declare function ctaNeedsBorder(s: GeneratedScale, mode: 'light' | 'dark', page: ColorStop | undefined): boolean;
+export declare function brandKindBody(prefix: string, s: GeneratedScale, mode: 'light' | 'dark', page: ColorStop | undefined): string[];
+export declare function brandKindP3Body(prefix: string, s: GeneratedScale, mode: 'light' | 'dark'): string[];
+export declare function neutralCss(selector: string, brandH: number, level?: NeutralLevel, contrastProfile?: ContrastProfile, ctaBorder?: boolean): string;
+export declare function signalsCss(contrastProfile?: ContrastProfile): string;
+export declare function annotationNote(r: ResolvedBrand, opts?: {
+    archetypeOverride?: string;
+}): string;
+export declare function brandCss(slug: string, displayName: string, r: ResolvedBrand, secondary?: GeneratedScale | null, noteSuffix?: string, neutralLevel?: NeutralLevel, contrastProfile?: ContrastProfile, secondaryStyle?: SecondaryStyle, ctaEscape?: boolean, linkHex?: string | null, ctaBorder?: boolean, neutralH?: number): string;

package/dist-lib/types/engine/darkChromaCurve.d.ts

@@ -0,0 +1,2 @@
+export declare const darkChromaCurve: (L: number, H: number, brandC: number, _ctaC?: number) => number;
+export declare const darkCtaTrim: (H: number) => number;

package/dist-lib/types/engine/figmaRender.d.ts

@@ -0,0 +1,34 @@
+import { type GeneratedScale, type NeutralLevel, type ContrastProfile } from './colorEngine';
+import { type ResolvedBrand, type SecondaryStyle } from './resolve';
+export interface FigmaColorToken {
+    $type: 'color';
+    $value: {
+        colorSpace: 'srgb';
+        components: [number, number, number];
+        alpha: number;
+        hex: string;
+    };
+}
+export type FigmaGroup = {
+    [key: string]: FigmaColorToken | FigmaGroup;
+};
+export declare function groupEntries(g: FigmaGroup): Array<[string, FigmaColorToken | FigmaGroup]>;
+export declare function putLeaf(g: FigmaGroup, flat: string, tok: FigmaColorToken): void;
+export interface ThemeInput {
+    secondary?: GeneratedScale | null;
+    secondaryStyle?: SecondaryStyle;
+    neutralLevel?: NeutralLevel;
+    neutralH?: number;
+    signals: Array<{
+        name: string;
+        scale: GeneratedScale;
+    }>;
+    contrastProfile?: ContrastProfile;
+    ctaEscape?: boolean;
+    linkHex?: string | null;
+    ctaBorder?: boolean;
+}
+export declare function themeToFigma(r: ResolvedBrand, input: ThemeInput): {
+    light: FigmaGroup;
+    dark: FigmaGroup;
+};

package/dist-lib/types/engine/neutralCurve.d.ts

@@ -0,0 +1,5 @@
+export type NeutralLevel = 'pure' | 'default' | 'medium' | 'branded';
+export declare function neutralChromaCurve(brandH: number, level?: NeutralLevel): (L: number, mode: 'light' | 'dark') => number;
+export declare const SUBTLE_SECONDARY_MULT = 4.5;
+export declare const SUBTLE_SECONDARY_MULT_CANDIDATES: number[];
+export declare function subtleSecondaryChromaCurve(brandH: number, mult?: number): (L: number, mode: 'light' | 'dark') => number;

package/dist-lib/types/engine/p2.d.ts

@@ -0,0 +1,12 @@
+export declare const P2_D = 0.12;
+export declare const P2_D_UP = 0.11;
+export declare const P2_D_FALLBACK = 0.115;
+export declare function p2Diff(a: {
+    L: number;
+    C: number;
+    H: number;
+}, b: {
+    L: number;
+    C: number;
+    H: number;
+}): number;

package/dist-lib/types/engine/perceptualL.d.ts

@@ -0,0 +1,11 @@
+import { type Gamut } from './constraints';
+export declare const lstarFromY: (Y: number) => number;
+export declare function apparentL(L: number, C: number, H: number, gamut?: Gamut): number;
+export declare const grayApparentL: (L: number, gamut?: Gamut) => number;
+export declare function solveLForApparent(target: number, C: number, H: number, gamut?: Gamut): number;
+export declare function solveCForApparent(L: number, H: number, target: number, gamut?: Gamut): number;
+export declare const KEEP_LIGHT = 1;
+export declare const KEEP_DARK = 1;
+export declare function meanBoost(rootL: number, C: number, gamut?: Gamut): number;
+export declare function perceptualRungL(rootL: number, C: number, H: number, keep?: number, gamut?: Gamut, targetC?: number): number;
+export declare function perceptualDarkC(L: number, H: number, nativeC: number, keep?: number, gamut?: Gamut): number;

package/dist-lib/types/engine/requirements/dtcg.d.ts

@@ -0,0 +1,44 @@
+import type { StopReq, RoleReq, ModeSpec } from './spec';
+import { type ResolvedRamp } from './resolve';
+export declare const EXT_KEY = "org.okchroma.requirement";
+export declare const RESOLVER_ID = "okchroma-reqtoken@2";
+export type DtcgColorValue = {
+    colorSpace: 'srgb';
+    components: [number, number, number];
+    alpha: 1;
+    hex: string;
+};
+type ExtCommon = {
+    resolver: string;
+    seed: string;
+    mode: 'light' | 'dark';
+};
+export type DtcgRequirementToken = {
+    $type: 'color';
+    $value: DtcgColorValue;
+    $extensions: {
+        [EXT_KEY]: ExtCommon & (StopReq | RoleReq);
+    };
+};
+export type DtcgSeedToken = {
+    $type: 'color';
+    $value: DtcgColorValue;
+};
+export type DtcgRampGroup = {
+    seed: DtcgSeedToken;
+    $extensions?: {
+        [EXT_KEY]: {
+            resolver: string;
+            ons: ModeSpec['ons'];
+        };
+    };
+    [key: string]: unknown;
+};
+export declare function emitDtcgRamp(hex: string, mode: 'light' | 'dark', groupName: string, spec?: ModeSpec): DtcgRampGroup;
+export declare function parseToken(token: DtcgRequirementToken): {
+    req: StopReq | RoleReq;
+    seedRef: string;
+    mode: 'light' | 'dark';
+};
+export declare function resolveDtcgRamp(group: DtcgRampGroup): ResolvedRamp;
+export {};