@ideare/kit 0.0.0-stage → 0.1.0-next.1

package/dist/color/contrast.js

@@ -0,0 +1,84 @@
+import { clampChroma, formatHex, modeOklch, modeRgb, useMode } from "culori/fn";
+import { contrast, luminance, normalizeHex } from "./wcag.js";
+// culori's tree-shakable entry: register only the two spaces the kit converts between.
+const toOklchColor = useMode(modeOklch);
+useMode(modeRgb);
+/** A hex color's OKLCH coordinates. A gray has no hue; it reads as 0. */
+export function toOklch(hex) {
+    const color = toOklchColor(normalizeHex(hex));
+    return { l: color?.l ?? 0, c: color?.c ?? 0, h: color?.h ?? 0 };
+}
+/** Distance in OKLab between two hex colors: under 0.02 looks the same, 0.1 is clearly different. */
+export function oklabDistance(a, b) {
+    const lab = (hex) => {
+        const { l, c, h } = toOklch(hex);
+        const radians = (h * Math.PI) / 180;
+        return [l, c * Math.cos(radians), c * Math.sin(radians)];
+    };
+    const [l1, a1, b1] = lab(a);
+    const [l2, a2, b2] = lab(b);
+    return Math.hypot(l1 - l2, a1 - a2, b1 - b2);
+}
+/**
+ * The hex for an OKLCH color, brought into sRGB by lowering chroma at the same lightness and hue
+ * (culori's clampChroma). Lightness is clamped to 0..1.
+ */
+export function fromOklch({ l, c, h }) {
+    const color = clampChroma({ mode: "oklch", l: Math.min(1, Math.max(0, l)), c: Math.max(0, c), h }, "oklch", "rgb");
+    return formatHex(color);
+}
+/**
+ * The closest color to `fg`, at the same OKLCH hue and chroma where sRGB allows, that reaches
+ * `min` contrast against `bg`. It searches lightness both ways (darker and lighter), keeps the
+ * smaller change that passes, and measures WCAG 2 on the final hex, so rounding to 8 bits can
+ * never push it under the line.
+ */
+export function ensureContrast(fg, bg, min) {
+    const start = normalizeHex(fg);
+    const startRatio = contrast(start, bg);
+    if (startRatio >= min)
+        return { hex: start, ratio: startRatio, ok: true, changed: false };
+    const base = toOklch(start);
+    const candidates = [0, 1]
+        .map((extreme) => searchLightness(base, extreme, bg, min))
+        .filter((found) => !!found)
+        .sort((a, b) => a.distance - b.distance);
+    const best = candidates[0];
+    if (best)
+        return { hex: best.hex, ratio: best.ratio, ok: true, changed: best.hex !== start };
+    // Nothing reaches the minimum: give back whichever of black and white comes closest.
+    const fallback = contrast("#000000", bg) >= contrast("#ffffff", bg) ? "#000000" : "#ffffff";
+    return { hex: fallback, ratio: contrast(fallback, bg), ok: false, changed: true };
+}
+function searchLightness(base, extreme, bg, min) {
+    const at = (l) => fromOklch({ ...base, l });
+    const far = at(extreme);
+    if (contrast(far, bg) < min)
+        return undefined;
+    // `pass` always holds a lightness whose measured hex passes; `fail` one that does not.
+    let fail = base.l;
+    let pass = extreme;
+    for (let step = 0; step < 24; step++) {
+        const mid = (fail + pass) / 2;
+        if (contrast(at(mid), bg) >= min)
+            pass = mid;
+        else
+            fail = mid;
+    }
+    const hex = at(pass);
+    return { hex, ratio: contrast(hex, bg), distance: Math.abs(pass - base.l) };
+}
+/**
+ * The better of the candidates (by default the given ink and white) to put on `bg`, measured.
+ * smartgenius's onColor, generalized: a brand fill keeps its own color, and the text on it picks
+ * the side that reads.
+ */
+export function onColor(bg, ink = "#141414", light = "#ffffff") {
+    const dark = { hex: normalizeHex(ink), ratio: contrast(ink, bg) };
+    const bright = { hex: normalizeHex(light), ratio: contrast(light, bg) };
+    return dark.ratio >= bright.ratio ? dark : bright;
+}
+/** True when `bg` is light enough that dark text is the natural pick. */
+export function isLight(hex) {
+    return luminance(hex) > 0.179;
+}

package/dist/color/palette.d.ts

@@ -0,0 +1,27 @@
+import type { ColorRole, Palette } from "../brand/schema.ts";
+/**
+ * Every pair of roles a brand promises to keep readable, with its WCAG 2 floor: 4.5 for text,
+ * 3 for lines, fills and focus (non-text). check() measures these on every brand, and
+ * generatePalette() is built to pass them.
+ */
+export declare const CONTRAST_PAIRS: readonly {
+    fg: ColorRole;
+    bg: ColorRole;
+    min: number;
+    what: string;
+}[];
+export declare const MOODS: readonly ["calm", "bold", "warm", "fresh", "classic", "playful"];
+export type Mood = (typeof MOODS)[number];
+export type PaletteSeed = {
+    hue: number;
+    mood: Mood;
+};
+/**
+ * A light and a dark role set from one hue and a mood. Lightness and chroma come from the mood;
+ * every role is then pushed (in OKLCH lightness only) until each of CONTRAST_PAIRS passes, so the
+ * result is readable by construction and keeps the hue the owner picked.
+ */
+export declare function generatePalette({ hue, mood }: PaletteSeed): {
+    light: Palette;
+    dark: Palette;
+};

package/dist/color/palette.js

@@ -0,0 +1,114 @@
+import { ensureContrast, fromOklch, onColor } from "./contrast.js";
+/**
+ * Every pair of roles a brand promises to keep readable, with its WCAG 2 floor: 4.5 for text,
+ * 3 for lines, fills and focus (non-text). check() measures these on every brand, and
+ * generatePalette() is built to pass them.
+ */
+export const CONTRAST_PAIRS = [
+    { fg: "ink", bg: "ground", min: 4.5, what: "text" },
+    { fg: "ink", bg: "surface", min: 4.5, what: "text on cards" },
+    { fg: "muted", bg: "ground", min: 4.5, what: "quiet text" },
+    { fg: "muted", bg: "surface", min: 4.5, what: "quiet text on cards" },
+    { fg: "line", bg: "ground", min: 3, what: "field borders" },
+    { fg: "line", bg: "surface", min: 3, what: "field borders on cards" },
+    { fg: "primary", bg: "ground", min: 3, what: "the brand color as a button" },
+    { fg: "onPrimary", bg: "primary", min: 4.5, what: "text on the brand color" },
+    { fg: "accent", bg: "ground", min: 3, what: "the accent as a fill" },
+    { fg: "onAccent", bg: "accent", min: 4.5, what: "text on the accent" },
+    { fg: "focus", bg: "ground", min: 3, what: "the focus ring" },
+    { fg: "danger", bg: "ground", min: 4.5, what: "error text" },
+    { fg: "success", bg: "ground", min: 4.5, what: "success text" },
+    { fg: "warning", bg: "ground", min: 4.5, what: "warning text" },
+];
+export const MOODS = ["calm", "bold", "warm", "fresh", "classic", "playful"];
+const MOOD = {
+    calm: { chroma: 0.09, accentShift: 150, accentChroma: 0.07, tint: 0.006 },
+    bold: { chroma: 0.2, accentShift: 180, accentChroma: 0.17, tint: 0.004 },
+    warm: { chroma: 0.14, accentShift: 40, accentChroma: 0.12, tint: 0.012 },
+    fresh: { chroma: 0.15, accentShift: 120, accentChroma: 0.13, tint: 0.008 },
+    classic: { chroma: 0.07, accentShift: 30, accentChroma: 0.05, tint: 0.004 },
+    playful: { chroma: 0.19, accentShift: 210, accentChroma: 0.16, tint: 0.01 },
+};
+const STATUS_HUE = { danger: 27, success: 150, warning: 70, focus: 255 };
+/**
+ * A light and a dark role set from one hue and a mood. Lightness and chroma come from the mood;
+ * every role is then pushed (in OKLCH lightness only) until each of CONTRAST_PAIRS passes, so the
+ * result is readable by construction and keeps the hue the owner picked.
+ */
+export function generatePalette({ hue, mood }) {
+    const spec = MOOD[mood];
+    const h = ((hue % 360) + 360) % 360;
+    const light = buildTheme("light", h, spec);
+    const dark = buildTheme("dark", h, spec);
+    // The fleet's retune rule: the brand color is never the same in both themes.
+    if (dark.primary === light.primary)
+        dark.primary = fromOklch({ l: 0.8, c: spec.chroma, h });
+    return { light, dark };
+}
+function buildTheme(theme, h, spec) {
+    const isLight = theme === "light";
+    const ground = isLight
+        ? fromOklch({ l: 0.993, c: spec.tint * 0.5, h })
+        : fromOklch({ l: 0.17, c: spec.tint * 1.5, h });
+    const surface = isLight
+        ? fromOklch({ l: 0.965, c: spec.tint * 1.5, h })
+        : fromOklch({ l: 0.22, c: spec.tint * 2, h });
+    const grounds = [ground, surface];
+    const ink = readable(fromOklch({ l: isLight ? 0.22 : 0.95, c: 0.02, h }), grounds, 4.5);
+    const muted = readable(fromOklch({ l: isLight ? 0.48 : 0.74, c: 0.025, h }), grounds, 4.5);
+    const line = readable(fromOklch({ l: isLight ? 0.64 : 0.52, c: 0.02, h }), grounds, 3);
+    // Text on a fill: ink or white in light themes; the dark ground or the ink in dark ones.
+    const darkText = isLight ? ink : ground;
+    const lightText = isLight ? "#ffffff" : ink;
+    const primaryPair = fill(fromOklch({ l: isLight ? 0.52 : 0.74, c: spec.chroma, h }), ground, {
+        dark: darkText,
+        light: lightText,
+        prefer: isLight ? lightText : darkText,
+    });
+    const accentPair = fill(fromOklch({
+        l: isLight ? 0.58 : 0.76,
+        c: spec.accentChroma,
+        h: (h + spec.accentShift) % 360,
+    }), ground, { dark: darkText, light: lightText, prefer: isLight ? lightText : darkText });
+    const status = (hueOf, l, c, min) => readable(fromOklch({ l, c, h: hueOf }), grounds, min);
+    return {
+        ground,
+        surface,
+        ink,
+        muted,
+        line,
+        primary: primaryPair.fill,
+        onPrimary: primaryPair.on,
+        accent: accentPair.fill,
+        onAccent: accentPair.on,
+        focus: status(STATUS_HUE.focus, isLight ? 0.55 : 0.72, 0.17, 3),
+        danger: status(STATUS_HUE.danger, isLight ? 0.52 : 0.72, 0.19, 4.5),
+        success: status(STATUS_HUE.success, isLight ? 0.5 : 0.75, 0.13, 4.5),
+        warning: status(STATUS_HUE.warning, isLight ? 0.52 : 0.8, 0.12, 4.5),
+    };
+}
+/** Push `color` until it reaches `min` against every background in `grounds`. */
+function readable(color, grounds, min) {
+    let hex = color;
+    // Two passes: fixing it against one ground can, rarely, bring it back under on another.
+    for (let pass = 0; pass < 2; pass++) {
+        for (const ground of grounds)
+            hex = ensureContrast(hex, ground, min).hex;
+    }
+    return hex;
+}
+/**
+ * A fill that reads as a control on the ground (3:1) and carries 4.5:1 text. The text is the
+ * dark or the light candidate, whichever reads; when neither does, the fill moves away from the
+ * preferred one (darker under white in light themes, lighter over the dark ground in dark ones).
+ */
+function fill(color, ground, text) {
+    let hex = ensureContrast(color, ground, 3).hex;
+    let on = onColor(hex, text.dark, text.light);
+    if (on.ratio < 4.5) {
+        hex = ensureContrast(hex, text.prefer, 4.5).hex;
+        hex = ensureContrast(hex, ground, 3).hex;
+        on = onColor(hex, text.dark, text.light);
+    }
+    return { fill: hex, on: on.hex };
+}

package/dist/color/wcag.d.ts

@@ -0,0 +1,22 @@
+/**
+ * WCAG 2 contrast on hex colors. The fleet's contrast gates measure the same way, so a brand
+ * that passes here passes there.
+ */
+export type Rgb = {
+    r: number;
+    g: number;
+    b: number;
+};
+/** `#rrggbb` (or `#rgb`) to 0..255 channels. Throws on anything else. */
+export declare function parseHex(hex: string): Rgb;
+export declare function toHex({ r, g, b }: Rgb): string;
+/** Lowercase `#rrggbb`. */
+export declare function normalizeHex(hex: string): string;
+/** WCAG 2 relative luminance, 0 (black) to 1 (white). */
+export declare function luminance(hex: string): number;
+/** WCAG 2 contrast ratio, 1 to 21. Order does not matter. */
+export declare function contrast(a: string, b: string): number;
+/** The ratio rounded down to 2 decimals, the way people should see it: 4.499 is not 4.5. */
+export declare function formatRatio(ratio: number): string;
+/** Composite a color with alpha over an opaque ground, for contrast on translucent paint. */
+export declare function over(hex: string, alpha: number, ground: string): string;

package/dist/color/wcag.js

@@ -0,0 +1,50 @@
+/**
+ * WCAG 2 contrast on hex colors. The fleet's contrast gates measure the same way, so a brand
+ * that passes here passes there.
+ */
+/** `#rrggbb` (or `#rgb`) to 0..255 channels. Throws on anything else. */
+export function parseHex(hex) {
+    const match = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(hex.trim());
+    if (!match?.[1])
+        throw new TypeError(`Not a hex color: ${hex}`);
+    const digits = match[1].length === 3 ? [...match[1]].map((digit) => digit + digit).join("") : match[1];
+    const value = Number.parseInt(digits, 16);
+    return { r: (value >> 16) & 255, g: (value >> 8) & 255, b: value & 255 };
+}
+export function toHex({ r, g, b }) {
+    const channel = (value) => Math.max(0, Math.min(255, Math.round(value)))
+        .toString(16)
+        .padStart(2, "0");
+    return `#${channel(r)}${channel(g)}${channel(b)}`;
+}
+/** Lowercase `#rrggbb`. */
+export function normalizeHex(hex) {
+    return toHex(parseHex(hex));
+}
+function linear(channel) {
+    const value = channel / 255;
+    return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+}
+/** WCAG 2 relative luminance, 0 (black) to 1 (white). */
+export function luminance(hex) {
+    const { r, g, b } = parseHex(hex);
+    return 0.2126 * linear(r) + 0.7152 * linear(g) + 0.0722 * linear(b);
+}
+/** WCAG 2 contrast ratio, 1 to 21. Order does not matter. */
+export function contrast(a, b) {
+    const first = luminance(a);
+    const second = luminance(b);
+    const [light, dark] = first > second ? [first, second] : [second, first];
+    return (light + 0.05) / (dark + 0.05);
+}
+/** The ratio rounded down to 2 decimals, the way people should see it: 4.499 is not 4.5. */
+export function formatRatio(ratio) {
+    return `${(Math.floor(ratio * 100) / 100).toFixed(2)}:1`;
+}
+/** Composite a color with alpha over an opaque ground, for contrast on translucent paint. */
+export function over(hex, alpha, ground) {
+    const top = parseHex(hex);
+    const bottom = parseHex(ground);
+    const mix = (a, b) => a * alpha + b * (1 - alpha);
+    return toHex({ r: mix(top.r, bottom.r), g: mix(top.g, bottom.g), b: mix(top.b, bottom.b) });
+}

package/dist/draft/draft.d.ts

@@ -0,0 +1,61 @@
+import type { Brand, Locale } from "../brand/schema.ts";
+import { type Mood } from "../color/palette.ts";
+import type { FontResolver } from "../text/fonts.ts";
+/**
+ * A draft brand from a business's name and one line about it, drawn by code alone. The same
+ * input always draws the same brand, so a link that carries the input (`draftParams`) redraws it
+ * anywhere: the site's try-it makes one in the browser and the studio picks it up from the link.
+ *
+ * `seed` keeps the look steady while the name is typed: colors, fonts and the kind of logo come
+ * from the seed, and change only when a word says something about the business ("padaria",
+ * "salon"), so mostly the letters change as you type.
+ * `picks` count each "Try another" press, per part.
+ */
+export type DraftPicks = {
+    colors: number;
+    fonts: number;
+    logo: number;
+};
+export type DraftInput = {
+    name: string;
+    /** What the business does, in the owner's words. It becomes the tagline. */
+    idea: string;
+    locale: Locale;
+    seed: number;
+    picks: DraftPicks;
+};
+/** The longest name (the wordmark's limit) and line (the copy check's tagline limit) a draft
+ *  takes: every file the kit makes has room for them. */
+export declare const DRAFT_LIMITS: {
+    readonly name: 40;
+    readonly idea: 60;
+};
+/**
+ * The font pairs a draft picks from. Few on purpose: a browser carries every file
+ * (`draftFontFiles`), so the try-it draws with no font server. Each display face has one weight,
+ * and the text faces are sans or serif opposites of their display.
+ */
+export declare const DRAFT_FONT_PAIRS: readonly {
+    display: string;
+    weight: number;
+    text: string;
+    moods: readonly Mood[];
+}[];
+/** Every font file a draft can ask for, so a page can serve them from its own origin. */
+export declare function draftFontFiles(): {
+    id: string;
+    weight: number;
+}[];
+/** A fresh seed for a new draft. */
+export declare function newDraftSeed(): number;
+/**
+ * Draw the draft. The name and the line are trimmed and cut to DRAFT_LIMITS; an empty line makes
+ * the name the tagline. Loads the display font (for a monogram) through `fonts`.
+ */
+export declare function draftBrand(input: DraftInput, ctx: {
+    fonts: FontResolver;
+}): Promise<Brand>;
+/** The draft as link parameters: name, idea, locale, seed, colors, fonts and logo. */
+export declare function draftParams(input: DraftInput): URLSearchParams;
+/** A draft read back from link parameters, or null when any part is missing or out of range. */
+export declare function readDraftParams(params: URLSearchParams): DraftInput | null;