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

package/dist/check/index.js

@@ -0,0 +1,492 @@
+import { ensureContrast, oklabDistance } from "../color/contrast.js";
+import { CONTRAST_PAIRS } from "../color/palette.js";
+import { contrast, formatRatio } from "../color/wcag.js";
+import { BANNERS, avatarScene, bannerScene, cardBackScene, catalogScene, ogScene, tileScene, } from "../files/templates.js";
+import { parseMark } from "../marks/svg.js";
+import { engineFor, renderScene } from "../scene/render.js";
+import { fontFor } from "../scene/brand-art.js";
+import { checkCopy } from "./copy.js";
+const GROUND_WORDS = {
+    ground: "the page",
+    surface: "cards",
+    ink: "text",
+    muted: "quiet text",
+    line: "borders",
+    primary: "the brand color",
+    onPrimary: "the brand color's text",
+    accent: "the accent",
+    onAccent: "the accent's text",
+    focus: "the focus ring",
+    danger: "errors",
+    success: "success",
+    warning: "warnings",
+};
+function capitalize(text) {
+    return text.charAt(0).toUpperCase() + text.slice(1);
+}
+function contrastChecks(brand) {
+    const results = [];
+    for (const theme of ["light", "dark"]) {
+        const palette = brand.colors[theme];
+        for (const pair of CONTRAST_PAIRS) {
+            const fg = palette[pair.fg];
+            const bg = palette[pair.bg];
+            const ratio = contrast(fg, bg);
+            const id = `contrast.${theme}.${pair.fg}.${pair.bg}`;
+            const details = {
+                color: fg,
+                background: bg,
+                ratio: formatRatio(ratio),
+                needed: `${pair.min}:1`,
+                theme,
+            };
+            if (ratio >= pair.min) {
+                results.push({
+                    id,
+                    area: "colors",
+                    level: "pass",
+                    title: `${capitalize(pair.what)}: easy to ${pair.min === 3 ? "see" : "read"}`,
+                    details,
+                });
+                continue;
+            }
+            const fix = ensureContrast(fg, bg, pair.min);
+            results.push({
+                id,
+                area: "colors",
+                level: "error",
+                // "Quiet text on cards" already names its ground; "Error text" gets "on the page".
+                title: `${capitalize(pair.what)}: hard to ${pair.min === 3 ? "see" : "read"}${pair.what.includes(" on ") ? "" : ` on ${GROUND_WORDS[pair.bg]}`}${theme === "dark" ? " in dark mode" : ""}. Fix it`,
+                message: `It needs ${pair.min}:1 and has ${formatRatio(ratio)}.`,
+                fix: fix.ok
+                    ? {
+                        kind: "set",
+                        label: `Use ${fix.hex}`,
+                        changes: [{ path: `colors.${theme}.${pair.fg}`, from: fg, to: fix.hex }],
+                    }
+                    : undefined,
+                details,
+            });
+        }
+        if (theme === "dark" && palette.primary === brand.colors.light.primary) {
+            results.push({
+                id: "contrast.retune",
+                area: "colors",
+                level: "warning",
+                title: "The brand color is the same in light and dark. Give dark mode its own",
+                message: "A color picked for white lands too close to the line on a dark page.",
+                details: { color: palette.primary },
+            });
+        }
+    }
+    return results;
+}
+function markChecks(brand) {
+    const results = [];
+    for (const [variant, svg] of [
+        ["svg", brand.mark.svg],
+        ["small", brand.mark.small],
+        ["dark", brand.mark.dark],
+        ["horizontal", brand.mark.lockups?.horizontal],
+        ["stacked", brand.mark.lockups?.stacked],
+        ["wordmark", brand.mark.lockups?.wordmark],
+    ]) {
+        if (!svg)
+            continue;
+        try {
+            const parsed = parseMark(svg);
+            if (parsed.unsupported.length) {
+                results.push({
+                    id: `logo.parse.${variant}`,
+                    area: "logo",
+                    level: "error",
+                    title: "Parts of the logo file can't be drawn. Simplify it",
+                    message: `ideare draws shapes with solid colors. Leave out ${parsed.unsupported.join(", ")}.`,
+                    details: { variant, unsupported: parsed.unsupported.join("; ") },
+                });
+            }
+        }
+        catch (error) {
+            results.push({
+                id: `logo.parse.${variant}`,
+                area: "logo",
+                level: "error",
+                title: "The logo file can't be read. Upload it again",
+                message: error instanceof Error ? error.message : String(error),
+                details: { variant },
+            });
+        }
+    }
+    if (results.some((result) => result.level === "error"))
+        return results;
+    // The mark on its tile (non-text, 3:1): the color that stands out most must reach it.
+    for (const theme of ["light", "dark"]) {
+        const tile = brand.colors[theme][brand.mark.tile.fill];
+        const mark = parseMark(theme === "dark" ? (brand.mark.dark ?? brand.mark.svg) : brand.mark.svg);
+        const colors = mark.colors.length ? mark.colors : [brand.colors[theme].ink];
+        const best = Math.max(...colors.map((color) => contrast(color, tile)));
+        const id = `logo.tile.${theme}`;
+        if (best >= 3) {
+            results.push({
+                id,
+                area: "logo",
+                level: "pass",
+                title: `The logo stands out on its icon${theme === "dark" ? " in dark mode" : ""}`,
+                details: { tile, ratio: formatRatio(best) },
+            });
+        }
+        else {
+            const options = ["ground", "surface", "primary", "ink"];
+            const better = options
+                .map((role) => ({
+                role,
+                ratio: Math.max(...colors.map((color) => contrast(color, brand.colors[theme][role]))),
+            }))
+                .sort((a, b) => b.ratio - a.ratio)[0];
+            results.push({
+                id,
+                area: "logo",
+                level: "error",
+                title: `The logo is hard to see on its icon background${theme === "dark" ? " in dark mode" : ""}. Fix it`,
+                message: `It needs 3:1 and has ${formatRatio(best)}.`,
+                fix: better && better.ratio >= 3
+                    ? {
+                        kind: "set",
+                        label: `Put the logo on ${GROUND_WORDS[better.role]}`,
+                        changes: [
+                            {
+                                path: "mark.tile.fill",
+                                from: brand.mark.tile.fill,
+                                to: better.role,
+                            },
+                        ],
+                    }
+                    : undefined,
+                details: { tile, ratio: formatRatio(best), needed: "3:1" },
+            });
+        }
+    }
+    // Thin lines vanish at 16 px: the thinnest stroke must stay at 1 px or more.
+    const small = parseMark(brand.mark.small ?? brand.mark.svg);
+    const drawn = 16 * (1 - Math.min(brand.mark.tile.padding, 0.12));
+    const thinnest = (small.thinnestStroke * drawn) / Math.max(small.viewBox.w, small.viewBox.h);
+    if (Number.isFinite(thinnest)) {
+        results.push(thinnest >= 1
+            ? {
+                id: "logo.legibility.16",
+                area: "logo",
+                level: "pass",
+                title: "The logo reads at 16 px",
+                details: { thinnestLinePx: Math.round(thinnest * 100) / 100 },
+            }
+            : {
+                id: "logo.legibility.16",
+                area: "logo",
+                level: "warning",
+                title: "Thin lines in the logo fade out at 16 px. Add a simpler small version",
+                message: "Browser tabs show the logo at 16 px.",
+                details: { thinnestLinePx: Math.round(thinnest * 100) / 100, needed: 1 },
+            });
+    }
+    // Colors in the mark that are not in either palette.
+    const palette = new Set([
+        ...Object.values(brand.colors.light),
+        ...Object.values(brand.colors.dark),
+    ]);
+    const near = (hex) => [...palette].some((color) => oklabDistance(hex, color) < 0.03);
+    const outside = parseMark(brand.mark.svg).colors.filter((color) => color !== "#ffffff" && color !== "#000000" && !near(color));
+    results.push(outside.length
+        ? {
+            id: "logo.offPalette",
+            area: "logo",
+            level: "warning",
+            title: "The logo uses colors that are not in the palette",
+            message: "That's fine for a many-color logo. Otherwise, use the brand's colors so the files match.",
+            details: { colors: outside.join(" ") },
+        }
+        : {
+            id: "logo.offPalette",
+            area: "logo",
+            level: "pass",
+            title: "The logo uses the brand's colors",
+        });
+    return results;
+}
+function copyChecks(brand) {
+    const results = [];
+    const names = [brand.name, brand.shortName, brand.wordmark.text];
+    for (const locale of brand.locales) {
+        const copy = brand.copy[locale];
+        if (!copy)
+            continue;
+        const fields = [
+            ["tagline", copy.tagline, "tagline"],
+            ["description", copy.description, "description"],
+            ["card.title", copy.card.title, "title"],
+            ["card.subtitle", copy.card.subtitle, "subtitle"],
+        ];
+        for (const [field, text, kind] of fields) {
+            if (!text)
+                continue;
+            const issues = checkCopy(text, {
+                locale,
+                field: kind,
+                neverSay: brand.voice.neverSay,
+                names,
+            });
+            const id = `copy.${locale}.${field}`;
+            const path = `copy.${locale}.${field}`;
+            if (issues.length === 0) {
+                results.push({
+                    id,
+                    area: "copy",
+                    level: "pass",
+                    title: "The words read well",
+                    details: { locale, field },
+                });
+                continue;
+            }
+            const level = issues.some((issue) => issue.level === "error") ? "error" : "warning";
+            results.push({
+                id,
+                area: "copy",
+                level,
+                title: issues[0]?.message ?? "Rewrite this",
+                message: issues
+                    .slice(1)
+                    .map((issue) => issue.message)
+                    .join(" ") || undefined,
+                fix: { kind: "rewrite", label: "Write it again", path },
+                details: {
+                    locale,
+                    field,
+                    rules: issues.map((issue) => issue.rule).join(", "),
+                    text,
+                },
+            });
+        }
+    }
+    return results;
+}
+const SLOT_PATHS = {
+    title: (locale) => `copy.${locale}.card.title`,
+    subtitle: (locale) => `copy.${locale}.card.subtitle`,
+    tagline: (locale) => `copy.${locale}.tagline`,
+};
+async function textChecks(brand, ctx) {
+    if (!ctx.fonts) {
+        return [
+            {
+                id: "text.skipped",
+                area: "text",
+                level: "warning",
+                title: "Text fit was not checked",
+                message: "Pass the fonts to check() to measure it.",
+            },
+        ];
+    }
+    const results = [];
+    const engine = await engineFor(ctx.fonts);
+    // Every character of every piece of copy must exist in the font that draws it.
+    for (const role of ["display", "text"]) {
+        const font = await engine.font(fontFor(brand, role));
+        const texts = [
+            brand.name,
+            ...brand.locales.flatMap((locale) => {
+                const copy = brand.copy[locale];
+                return copy
+                    ? [copy.tagline, copy.description, copy.card.title, copy.card.subtitle ?? ""]
+                    : [];
+            }),
+        ];
+        if (brand.wordmark.font === role)
+            texts.push(brand.wordmark.text);
+        const missing = [...new Set(texts.join("").split(""))].filter((char) => char.trim() && !font.coverage.has(char.codePointAt(0) ?? 0));
+        results.push(missing.length
+            ? {
+                id: `fonts.glyphs.${role}`,
+                area: "fonts",
+                level: "error",
+                title: `${brand.fonts[role].family} has no ${missing.join(" ")}. Pick another font or change the words`,
+                details: { font: brand.fonts[role].id, missing: missing.join(" ") },
+            }
+            : {
+                id: `fonts.glyphs.${role}`,
+                area: "fonts",
+                level: "pass",
+                title: `${brand.fonts[role].family} has every letter the brand writes`,
+                details: { locales: brand.locales.join(", ") },
+            });
+    }
+    // Text fit, on the files that carry the brand's words.
+    const scenes = [];
+    for (const locale of brand.locales) {
+        scenes.push({ name: `og.${locale}`, locale, scene: ogScene(brand, locale) });
+        scenes.push({ name: `catalog.${locale}`, locale, scene: catalogScene(brand, locale) });
+        for (const [path, banner] of Object.entries(BANNERS))
+            scenes.push({
+                name: `${path}.${locale}`,
+                locale,
+                scene: bannerScene(brand, locale, banner.w, banner.h, banner.safe),
+            });
+        scenes.push({ name: `card.${locale}`, locale, scene: cardBackScene(brand, "br", locale) });
+        for (const page of ctx.pages ?? []) {
+            const copy = page.copy[locale];
+            if (copy)
+                scenes.push({
+                    name: `og.${page.slug}.${locale}`,
+                    locale,
+                    scene: ogScene(brand, locale, copy),
+                });
+        }
+    }
+    let fitErrors = 0;
+    for (const { name, locale, scene } of scenes) {
+        const result = await renderScene(scene, brand, { fonts: ctx.fonts });
+        for (const sceneCheck of result.checks) {
+            if (sceneCheck.rule !== "text.fit")
+                continue;
+            fitErrors++;
+            const layer = scene.pages[0]?.layers.find((item) => item.id === sceneCheck.layer);
+            const slot = layer?.type === "text" ? layer.slot : undefined;
+            const path = slot
+                ? SLOT_PATHS[slot]?.(locale)
+                : sceneCheck.layer === "name"
+                    ? "name"
+                    : undefined;
+            results.push({
+                id: `text.fit.${name}.${sceneCheck.layer ?? "text"}`,
+                area: "text",
+                level: "error",
+                title: `Too long for ${name.split(".")[0] === "og" ? "the share card" : name.split(".")[0]}: ${sceneCheck.message}`,
+                fix: path ? { kind: "rewrite", label: "Write it again", path } : undefined,
+                details: { file: name, ...sceneCheck.details },
+            });
+        }
+    }
+    if (fitErrors === 0)
+        results.push({
+            id: "text.fit",
+            area: "text",
+            level: "pass",
+            title: "Every text fits its space, in every language",
+            details: { files: scenes.length },
+        });
+    // Safe zones: the banners place everything inside each network's safe area.
+    for (const [path, banner] of Object.entries(BANNERS)) {
+        const result = await renderScene(bannerScene(brand, brand.defaultLocale, banner.w, banner.h, banner.safe), brand, { fonts: ctx.fonts });
+        const outside = Object.entries(result.boxes)
+            .filter(([id]) => !id.startsWith("glow"))
+            .filter(([, box]) => box.x < banner.safe.x - 0.5 ||
+            box.y < banner.safe.y - 0.5 ||
+            box.x + box.w > banner.safe.x + banner.safe.w + 0.5 ||
+            box.y + box.h > banner.safe.y + banner.safe.h + 0.5);
+        results.push({
+            id: `files.safe.${path}`,
+            area: "files",
+            level: outside.length ? "error" : "pass",
+            title: outside.length
+                ? `Part of ${path} could be cropped by the network`
+                : `${path} keeps everything where the network shows it`,
+            details: {
+                safe: `${banner.safe.w}x${banner.safe.h} at ${banner.safe.x},${banner.safe.y}`,
+            },
+        });
+    }
+    // The maskable icon's mark sits inside the 40% safe circle; the avatar's inside its circle.
+    const maskPadding = Math.max(brand.mark.tile.padding, 0.22);
+    const reach = (0.5 - maskPadding) * Math.SQRT2;
+    results.push({
+        id: "files.maskable",
+        area: "files",
+        level: reach <= 0.4 ? "pass" : "error",
+        title: reach <= 0.4
+            ? "The Android icon keeps the logo inside the safe circle"
+            : "Android could cut the logo's corners",
+        details: { cornerReach: Math.round(reach * 1000) / 1000, safeRadius: 0.4 },
+    });
+    const avatar = avatarScene(brand, 1080).pages[0]?.layers.find((layer) => layer.id === "mark");
+    if (avatar) {
+        const corner = Math.hypot(avatar.frame.w / 2, avatar.frame.h / 2);
+        results.push({
+            id: "files.avatar.circle",
+            area: "files",
+            level: corner <= 540 ? "pass" : "error",
+            title: corner <= 540
+                ? "Round profile pictures keep the whole logo"
+                : "Round profile pictures cut the logo",
+            details: { cornerPx: Math.round(corner), circlePx: 540 },
+        });
+    }
+    // The apple icon is opaque by construction; with pixels, it is measured.
+    if (ctx.rasterize) {
+        const svg = (await renderScene(tileScene(brand, { size: 180, padding: 0.1, opaque: true, variant: "mark" }), brand, { fonts: ctx.fonts })).svg;
+        const raster = await ctx.rasterize(svg, { width: 180 });
+        let transparent = 0;
+        for (let i = 3; i < raster.pixels.length; i += 4)
+            if ((raster.pixels[i] ?? 0) < 255)
+                transparent++;
+        results.push({
+            id: "files.apple.opaque",
+            area: "files",
+            level: transparent === 0 ? "pass" : "error",
+            title: transparent === 0
+                ? "The iPhone icon has no see-through corners"
+                : "The iPhone icon has see-through pixels, which iOS turns black",
+            details: { transparentPixels: transparent },
+        });
+    }
+    return results;
+}
+/** Upload limits per network, in bytes. */
+const SIZE_LIMITS = [
+    { match: /^og\//, max: 5 * 1024 * 1024, where: "X share cards (5 MB)" },
+    { match: /^social\/x\/avatar/, max: 2 * 1024 * 1024, where: "X profile pictures (2 MB)" },
+    { match: /^social\/youtube\/banner/, max: 6 * 1024 * 1024, where: "YouTube banners (6 MB)" },
+    { match: /^social\/linkedin\/cover/, max: 3 * 1024 * 1024, where: "LinkedIn covers (3 MB)" },
+    { match: /^social\/whatsapp\//, max: 5 * 1024 * 1024, where: "WhatsApp (5 MB)" },
+    { match: /^web\/web-app-manifest-512/, max: 1024 * 1024, where: "Google Play icons (1 MB)" },
+];
+function sizeChecks(files) {
+    const results = [];
+    for (const [path, file] of files) {
+        const limit = SIZE_LIMITS.find((rule) => rule.match.test(path));
+        if (!limit || file.bytes.length <= limit.max)
+            continue;
+        results.push({
+            id: `files.size.${path}`,
+            area: "files",
+            level: "error",
+            title: `${path} is too big for ${limit.where}`,
+            details: { bytes: file.bytes.length, max: limit.max },
+        });
+    }
+    if (results.length === 0)
+        results.push({
+            id: "files.size",
+            area: "files",
+            level: "pass",
+            title: "Every file is under each network's upload limit",
+        });
+    return results;
+}
+const ORDER = { error: 0, warning: 1, pass: 2 };
+/** Run every check. Errors come first, then warnings, then what passed. */
+export async function check(brand, ctx = {}) {
+    const results = [
+        ...contrastChecks(brand),
+        ...markChecks(brand),
+        ...copyChecks(brand),
+        ...(await textChecks(brand, ctx)),
+        ...(ctx.files ? sizeChecks(ctx.files) : []),
+    ];
+    return results.sort((a, b) => ORDER[a.level] - ORDER[b.level]);
+}
+/** "2 to fix" and friends, for the folded summary. */
+export function summarize(results) {
+    return {
+        errors: results.filter((result) => result.level === "error").length,
+        warnings: results.filter((result) => result.level === "warning").length,
+        passed: results.filter((result) => result.level === "pass").length,
+    };
+}

package/dist/color/contrast.d.ts

@@ -0,0 +1,41 @@
+export type Oklch = {
+    l: number;
+    c: number;
+    h: number;
+};
+/** A hex color's OKLCH coordinates. A gray has no hue; it reads as 0. */
+export declare function toOklch(hex: string): Oklch;
+/** Distance in OKLab between two hex colors: under 0.02 looks the same, 0.1 is clearly different. */
+export declare function oklabDistance(a: string, b: string): number;
+/**
+ * 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 declare function fromOklch({ l, c, h }: Oklch): string;
+export type ContrastFix = {
+    /** The color to use: the original when it already passed. */
+    hex: string;
+    /** Its WCAG 2 ratio against the background, measured on the final hex. */
+    ratio: number;
+    /** False when no lightness reaches the minimum (only possible above about 4.58:1). */
+    ok: boolean;
+    changed: boolean;
+};
+/**
+ * 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 declare function ensureContrast(fg: string, bg: string, min: number): ContrastFix;
+/**
+ * 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 declare function onColor(bg: string, ink?: string, light?: string): {
+    hex: string;
+    ratio: number;
+};
+/** True when `bg` is light enough that dark text is the natural pick. */
+export declare function isLight(hex: string): boolean;

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;
+};