@hewnui/themes 0.0.0-stage → 0.1.0

package/dist/authoring/propose.d.ts

@@ -0,0 +1,21 @@
+import { type BasePackId, type OverrideMap, type RadiusPreset } from "./types";
+export type ThemeProposal = {
+    basePackId: BasePackId;
+    accentSeed: string;
+    radiusPreset: RadiusPreset;
+    notes: string[];
+};
+/** Pull hex / oklch color strings from CSS or Tailwind snippets. */
+export declare function extractColorsFromCss(source: string): string[];
+export declare function pickAccentFromColors(colors: string[]): string | null;
+export declare function suggestBasePack(accentSeed: string, hint?: string): BasePackId;
+export declare function suggestRadius(hint?: string): RadiusPreset;
+/** Deterministic proposal from colors + optional free-text hint (no LLM). */
+export declare function proposeFromPalette(colors: string[], hint?: string): ThemeProposal | null;
+/** Offline prompt migration: keywords + embedded colors; never throws. */
+export declare function proposeFromPrompt(prompt: string): ThemeProposal;
+export declare function proposalToOverrideMap(proposal: ThemeProposal, packId?: string): OverrideMap;
+/** Validate raw LLM/model JSON into a ThemeProposal via override normalize. */
+export declare function parseAiProposal(raw: unknown): ThemeProposal | {
+    error: string;
+};

package/dist/authoring/propose.js

@@ -0,0 +1,162 @@
+import { formatHex, parseColor } from "./oklch.js";
+import { normalizeOverrideMap } from "./override-map.js";
+import { BASE_PACK_IDS, SCHEMA_VERSION, } from "./types.js";
+const HEX_FIND = /#([0-9a-f]{3}|[0-9a-f]{6})\b/gi;
+const OKLCH_FIND = /oklch\(\s*[0-9.]+\s+[0-9.]+\s+[0-9.]+(?:\s*\/\s*[0-9.]+%?)?\s*\)/gi;
+const PACK_BY_HUE = [
+    { pack: "clay", min: 10, max: 45 },
+    { pack: "dune", min: 45, max: 85 },
+    { pack: "forest", min: 110, max: 165 },
+    { pack: "tide", min: 175, max: 230 },
+    { pack: "graphite", min: 230, max: 280 },
+    { pack: "ember", min: 0, max: 25 },
+];
+const PACK_KEYWORDS = [
+    { pack: "forest", words: ["forest", "green", "nature", "leaf"] },
+    { pack: "tide", words: ["tide", "ocean", "sea", "blue", "cyan"] },
+    { pack: "graphite", words: ["graphite", "slate", "mono", "neutral", "gray", "grey"] },
+    { pack: "dune", words: ["dune", "sand", "desert", "beige", "warm"] },
+    { pack: "clay", words: ["clay", "terracotta", "earthy", "pottery"] },
+    { pack: "ember", words: ["ember", "fire", "night", "dark", "crimson"] },
+];
+/** Pull hex / oklch color strings from CSS or Tailwind snippets. */
+export function extractColorsFromCss(source) {
+    const found = [];
+    for (const match of source.matchAll(HEX_FIND)) {
+        const normalized = normalizeHex(match[0]);
+        if (normalized)
+            found.push(normalized);
+    }
+    for (const match of source.matchAll(OKLCH_FIND)) {
+        const parsed = parseColor(match[0]);
+        if (parsed)
+            found.push(formatHex(parsed));
+    }
+    return [...new Set(found)];
+}
+export function pickAccentFromColors(colors) {
+    let best = null;
+    for (const hex of colors) {
+        const color = parseColor(hex);
+        if (!color)
+            continue;
+        if (color.l < 0.2 || color.l > 0.9)
+            continue;
+        const score = color.c * (1 - Math.abs(color.l - 0.55));
+        if (!best || score > best.score)
+            best = { hex, score };
+    }
+    return best?.hex ?? colors[0] ?? null;
+}
+function normalizeHex(raw) {
+    const match = raw.trim().match(/^#([0-9a-f]{3}|[0-9a-f]{6})$/i);
+    if (!match?.[1])
+        return null;
+    const hex = match[1];
+    const full = hex.length === 3
+        ? hex
+            .split("")
+            .map((ch) => ch + ch)
+            .join("")
+        : hex;
+    return `#${full.toLowerCase()}`;
+}
+export function suggestBasePack(accentSeed, hint = "") {
+    const lower = hint.toLowerCase();
+    for (const entry of PACK_KEYWORDS) {
+        if (entry.words.some((w) => lower.includes(w)))
+            return entry.pack;
+    }
+    const color = parseColor(accentSeed);
+    if (!color || color.c < 0.02)
+        return "graphite";
+    const h = color.h;
+    for (const band of PACK_BY_HUE) {
+        if (h >= band.min && h < band.max)
+            return band.pack;
+    }
+    return "forest";
+}
+export function suggestRadius(hint = "") {
+    const lower = hint.toLowerCase();
+    if (/\b(sharp|square|brutal)\b/.test(lower))
+        return "sharp";
+    if (/\b(pill|full.?round|capsule)\b/.test(lower))
+        return "pill";
+    if (/\b(rounded|soft.?round|friendly)\b/.test(lower))
+        return "rounded";
+    return "soft";
+}
+/** Deterministic proposal from colors + optional free-text hint (no LLM). */
+export function proposeFromPalette(colors, hint = "") {
+    const accent = pickAccentFromColors(colors);
+    if (!accent)
+        return null;
+    const basePackId = suggestBasePack(accent, hint);
+    const radiusPreset = suggestRadius(hint);
+    return {
+        basePackId,
+        accentSeed: accent,
+        radiusPreset,
+        notes: [
+            `Accent from palette (${colors.length} color${colors.length === 1 ? "" : "s"})`,
+            `Base pack suggested: ${basePackId}`,
+        ],
+    };
+}
+/** Offline prompt migration: keywords + embedded colors; never throws. */
+export function proposeFromPrompt(prompt) {
+    const colors = extractColorsFromCss(prompt);
+    const fromPalette = proposeFromPalette(colors, prompt);
+    if (fromPalette)
+        return fromPalette;
+    const basePackId = suggestBasePack("#2f6b4f", prompt);
+    return {
+        basePackId,
+        accentSeed: defaultAccentFor(basePackId),
+        radiusPreset: suggestRadius(prompt),
+        notes: ["No colors in prompt — used keyword defaults"],
+    };
+}
+export function proposalToOverrideMap(proposal, packId = "studio-draft") {
+    return {
+        schemaVersion: SCHEMA_VERSION,
+        basePackId: proposal.basePackId,
+        packId,
+        accentSeed: proposal.accentSeed,
+        radiusPreset: proposal.radiusPreset,
+    };
+}
+/** Validate raw LLM/model JSON into a ThemeProposal via override normalize. */
+export function parseAiProposal(raw) {
+    const normalized = normalizeOverrideMap({
+        schemaVersion: SCHEMA_VERSION,
+        ...(typeof raw === "object" && raw !== null ? raw : {}),
+    });
+    if (!normalized.ok) {
+        return { error: normalized.errors.join("; ") };
+    }
+    const { basePackId, accentSeed, radiusPreset } = normalized.map;
+    if (!accentSeed)
+        return { error: "accentSeed required" };
+    if (!BASE_PACK_IDS.includes(basePackId)) {
+        return { error: "invalid basePackId" };
+    }
+    return {
+        basePackId,
+        accentSeed,
+        radiusPreset: radiusPreset ?? "soft",
+        notes: ["Validated AI proposal"],
+    };
+}
+function defaultAccentFor(pack) {
+    const map = {
+        forest: "#2f6b4f",
+        tide: "#2f6f8f",
+        graphite: "#4a5568",
+        dune: "#b08968",
+        clay: "#a65d45",
+        ember: "#c45c3e",
+    };
+    return map[pack];
+}

package/dist/authoring/ramps.d.ts

@@ -0,0 +1,13 @@
+import type { Oklch, ThemeMode } from "./types";
+export type AccentSet = {
+    accent: Oklch;
+    accentForeground: Oklch;
+    ring: Oklch;
+    glassTint: Oklch;
+};
+export declare function accentSetFromSeed(seedInput: string, mode: ThemeMode): {
+    set: AccentSet;
+    adjustments: string[];
+} | {
+    error: string;
+};

package/dist/authoring/ramps.js

@@ -0,0 +1,40 @@
+import { contrastForeground, parseColor } from "./oklch.js";
+export function accentSetFromSeed(seedInput, mode) {
+    const seed = parseColor(seedInput);
+    if (!seed) {
+        return { error: `invalid accent seed: "${seedInput}"` };
+    }
+    const adjustments = [];
+    const accent = mode === "dark"
+        ? { ...seed, l: Math.min(0.82, Math.max(0.62, seed.l + 0.12)) }
+        : { ...seed, l: Math.min(0.62, Math.max(0.42, seed.l)) };
+    if (accent.l !== seed.l) {
+        adjustments.push(`${mode} accent lightness clamped to ${accent.l.toFixed(2)} for surface contrast`);
+    }
+    // Dark packs use light accents; prefer light ink so AA holds without
+    // brightening the accent beyond the pack character.
+    const preferFg = {
+        l: 0.98,
+        c: Math.min(0.02, accent.c),
+        h: accent.h,
+    };
+    const fg = contrastForeground(accent, preferFg);
+    if (fg.adjusted) {
+        adjustments.push(`${mode} accent-foreground adjusted to meet WCAG AA against accent`);
+    }
+    const ring = { ...accent, c: Math.min(0.14, accent.c + 0.01) };
+    const glassTint = {
+        ...accent,
+        l: mode === "dark" ? Math.min(0.7, accent.l) : Math.min(0.82, accent.l + 0.15),
+        alpha: mode === "dark" ? 0.24 : 0.28,
+    };
+    return {
+        set: {
+            accent,
+            accentForeground: fg.color,
+            ring,
+            glassTint,
+        },
+        adjustments,
+    };
+}

package/dist/authoring/status-ramps.d.ts

@@ -0,0 +1,13 @@
+import type { BasePackId, Oklch, StatusModeColors, ThemeMode } from "./types";
+/** Pack-character hues for semantic status families (not accent clones). */
+export declare const PACK_STATUS_HUES: Record<BasePackId, {
+    success: number;
+    warning: number;
+    info: number;
+}>;
+/** Derive danger/success/warning/info (+ fg/subtle/border) for a mode. */
+export declare function statusColors(mode: ThemeMode, danger: Oklch, hues: {
+    success: number;
+    warning: number;
+    info: number;
+}): StatusModeColors;

package/dist/authoring/status-ramps.js

@@ -0,0 +1,76 @@
+/** Pack-character hues for semantic status families (not accent clones). */
+export const PACK_STATUS_HUES = {
+    forest: { success: 148, warning: 78, info: 220 },
+    tide: { success: 165, warning: 75, info: 230 },
+    graphite: { success: 150, warning: 75, info: 250 },
+    dune: { success: 140, warning: 70, info: 230 },
+    clay: { success: 145, warning: 55, info: 230 },
+    ember: { success: 145, warning: 70, info: 230 },
+};
+function o(l, c, h, alpha) {
+    return alpha === undefined ? { l, c, h } : { l, c, h, alpha };
+}
+function family(mode, hue, kind, dangerSeed) {
+    const dark = mode === "dark";
+    if (kind === "danger" && dangerSeed) {
+        const base = dangerSeed;
+        return {
+            base,
+            fg: o(0.985, 0.01, base.h),
+            subtle: dark ? o(0.32, 0.05, base.h) : o(0.94, 0.035, base.h),
+            border: dark ? o(0.72, 0.1, base.h, 0.4) : o(0.56, 0.12, base.h, 0.4),
+        };
+    }
+    if (kind === "warning") {
+        const base = dark ? o(0.78, 0.12, hue) : o(0.75, 0.14, hue);
+        const fg = dark ? o(0.22, 0.04, hue) : o(0.25, 0.05, hue);
+        return {
+            base,
+            fg,
+            subtle: dark ? o(0.34, 0.04, hue) : o(0.94, 0.04, hue),
+            border: dark ? o(0.78, 0.1, hue, 0.4) : o(0.72, 0.12, hue, 0.4),
+        };
+    }
+    if (kind === "info") {
+        const base = dark ? o(0.72, 0.1, hue) : o(0.52, 0.11, hue);
+        return {
+            base,
+            fg: o(0.985, 0.01, hue),
+            subtle: dark ? o(0.32, 0.035, hue) : o(0.94, 0.03, hue),
+            border: dark ? o(0.72, 0.08, hue, 0.4) : o(0.52, 0.09, hue, 0.4),
+        };
+    }
+    // success — tide dark needs a slightly deeper base for light-fg AA
+    const successL = dark ? (hue === 165 ? 0.71 : 0.72) : 0.55;
+    const base = dark ? o(successL, 0.14, hue) : o(0.55, 0.15, hue);
+    return {
+        base,
+        fg: o(0.985, 0.01, hue),
+        subtle: dark ? o(0.32, 0.045, hue) : o(0.94, 0.035, hue),
+        border: dark ? o(0.72, 0.1, hue, 0.4) : o(0.55, 0.12, hue, 0.4),
+    };
+}
+/** Derive danger/success/warning/info (+ fg/subtle/border) for a mode. */
+export function statusColors(mode, danger, hues) {
+    const dangerSet = family(mode, danger.h, "danger", danger);
+    const success = family(mode, hues.success, "success");
+    const warning = family(mode, hues.warning, "warning");
+    const info = family(mode, hues.info, "info");
+    return {
+        dangerForeground: dangerSet.fg,
+        dangerSubtle: dangerSet.subtle,
+        dangerBorder: dangerSet.border,
+        success: success.base,
+        successForeground: success.fg,
+        successSubtle: success.subtle,
+        successBorder: success.border,
+        warning: warning.base,
+        warningForeground: warning.fg,
+        warningSubtle: warning.subtle,
+        warningBorder: warning.border,
+        info: info.base,
+        infoForeground: info.fg,
+        infoSubtle: info.subtle,
+        infoBorder: info.border,
+    };
+}

package/dist/authoring/token-entries.d.ts

@@ -0,0 +1,10 @@
+import type { ResolvedMode, ResolvedPack, ThemeMode } from "./types";
+export type TokenEntry = {
+    name: string;
+    value: string;
+    kind: "color" | "number" | "string";
+};
+export declare function modeOrder(pack: ResolvedPack): ThemeMode[];
+export declare function colorEntries(mode: ResolvedMode): TokenEntry[];
+export declare function structuralEntries(mode: ResolvedMode): TokenEntry[];
+export declare function primaryMode(pack: ResolvedPack): ResolvedMode;

package/dist/authoring/token-entries.js

@@ -0,0 +1,52 @@
+import { formatOklch } from "./oklch.js";
+export function modeOrder(pack) {
+    const order = ["light", "dark"];
+    return order.filter((mode) => pack.modes[mode]);
+}
+export function colorEntries(mode) {
+    return [
+        { name: "background", value: formatOklch(mode.background), kind: "color" },
+        { name: "foreground", value: formatOklch(mode.foreground), kind: "color" },
+        { name: "surface", value: formatOklch(mode.surface), kind: "color" },
+        { name: "surface-raised", value: formatOklch(mode.surfaceRaised), kind: "color" },
+        { name: "muted", value: formatOklch(mode.muted), kind: "color" },
+        { name: "muted-foreground", value: formatOklch(mode.mutedForeground), kind: "color" },
+        { name: "accent", value: formatOklch(mode.accent), kind: "color" },
+        { name: "accent-foreground", value: formatOklch(mode.accentForeground), kind: "color" },
+        { name: "border", value: formatOklch(mode.border), kind: "color" },
+        { name: "ring", value: formatOklch(mode.ring), kind: "color" },
+        { name: "danger", value: formatOklch(mode.danger), kind: "color" },
+        { name: "danger-foreground", value: formatOklch(mode.dangerForeground), kind: "color" },
+        { name: "danger-subtle", value: formatOklch(mode.dangerSubtle), kind: "color" },
+        { name: "danger-border", value: formatOklch(mode.dangerBorder), kind: "color" },
+        { name: "success", value: formatOklch(mode.success), kind: "color" },
+        { name: "success-foreground", value: formatOklch(mode.successForeground), kind: "color" },
+        { name: "success-subtle", value: formatOklch(mode.successSubtle), kind: "color" },
+        { name: "success-border", value: formatOklch(mode.successBorder), kind: "color" },
+        { name: "warning", value: formatOklch(mode.warning), kind: "color" },
+        { name: "warning-foreground", value: formatOklch(mode.warningForeground), kind: "color" },
+        { name: "warning-subtle", value: formatOklch(mode.warningSubtle), kind: "color" },
+        { name: "warning-border", value: formatOklch(mode.warningBorder), kind: "color" },
+        { name: "info", value: formatOklch(mode.info), kind: "color" },
+        { name: "info-foreground", value: formatOklch(mode.infoForeground), kind: "color" },
+        { name: "info-subtle", value: formatOklch(mode.infoSubtle), kind: "color" },
+        { name: "info-border", value: formatOklch(mode.infoBorder), kind: "color" },
+        { name: "glass-tint", value: formatOklch(mode.glassTint), kind: "color" },
+    ];
+}
+export function structuralEntries(mode) {
+    return [
+        { name: "radius-sm", value: mode.radiusSm, kind: "string" },
+        { name: "radius-md", value: mode.radiusMd, kind: "string" },
+        { name: "radius-lg", value: mode.radiusLg, kind: "string" },
+        { name: "radius-panel", value: mode.radiusPanel, kind: "string" },
+        { name: "density", value: String(mode.density), kind: "number" },
+        { name: "motion-duration", value: mode.motionDuration, kind: "string" },
+        { name: "motion-stiffness", value: String(mode.motionStiffness), kind: "number" },
+        { name: "motion-damping", value: String(mode.motionDamping), kind: "number" },
+    ];
+}
+export function primaryMode(pack) {
+    const modes = modeOrder(pack);
+    return pack.modes[modes[0]];
+}

package/dist/authoring/types.d.ts

@@ -0,0 +1,110 @@
+export declare const SCHEMA_VERSION: 2;
+/** Flip when monetization lands — Studio UI reads this stub gate. */
+export declare const PRO_AUTHORING_UNLOCKED = false;
+export declare const BASE_PACK_IDS: readonly ["forest", "tide", "graphite", "dune", "clay", "ember"];
+export type BasePackId = (typeof BASE_PACK_IDS)[number];
+export type ThemeMode = "light" | "dark";
+export type RadiusPreset = "sharp" | "soft" | "rounded" | "pill";
+export type Oklch = {
+    l: number;
+    c: number;
+    h: number;
+    alpha?: number;
+};
+/** Core semantic surfaces + accent + danger seed (curated per pack mode). */
+export type CoreModeColors = {
+    background: Oklch;
+    foreground: Oklch;
+    surface: Oklch;
+    surfaceRaised: Oklch;
+    muted: Oklch;
+    mutedForeground: Oklch;
+    accent: Oklch;
+    accentForeground: Oklch;
+    border: Oklch;
+    ring: Oklch;
+    danger: Oklch;
+    glassTint: Oklch;
+};
+/** Status families — base + foreground / subtle / border variants. */
+export type StatusModeColors = {
+    dangerForeground: Oklch;
+    dangerSubtle: Oklch;
+    dangerBorder: Oklch;
+    success: Oklch;
+    successForeground: Oklch;
+    successSubtle: Oklch;
+    successBorder: Oklch;
+    warning: Oklch;
+    warningForeground: Oklch;
+    warningSubtle: Oklch;
+    warningBorder: Oklch;
+    info: Oklch;
+    infoForeground: Oklch;
+    infoSubtle: Oklch;
+    infoBorder: Oklch;
+};
+/** Full semantic color tokens authored per mode. */
+export type ModeColorTokens = CoreModeColors & StatusModeColors;
+export type StructuralTokens = {
+    radiusSm: string;
+    radiusMd: string;
+    radiusLg: string;
+    radiusPanel: string;
+    density: number;
+    motionDuration: string;
+    motionStiffness: number;
+    motionDamping: number;
+};
+export type ResolvedMode = ModeColorTokens & StructuralTokens & {
+    mode: ThemeMode;
+    colorScheme: ThemeMode;
+};
+export type ResolvedPack = {
+    id: string;
+    basePackId: BasePackId;
+    supportedModes: readonly ThemeMode[];
+    modes: Partial<Record<ThemeMode, ResolvedMode>>;
+    adjustments: string[];
+};
+export type DensityPreset = "compact" | "default" | "comfortable";
+export type MotionCharacter = "snappy" | "balanced" | "soft";
+/** Pro — neutrals / surfaces (constrained bias, not free-form tokens). */
+export type NeutralOverrides = {
+    /** Lightness shift −0.08…0.08 applied to surfaces. */
+    surfaceShift?: number;
+    /** Chroma multiplier 0.5…1.5 for tinted neutrals. */
+    chromaScale?: number;
+};
+/** Pro — semantic colors beyond accent. */
+export type SemanticOverrides = {
+    /** Danger seed as `oklch(...)` or `#rrggbb`. */
+    dangerSeed?: string;
+};
+/** Pro — density (radius stays free via radiusPreset). */
+export type ShapeOverrides = {
+    density?: DensityPreset;
+};
+/** Pro — glass tint strength. */
+export type GlassOverrides = {
+    /** Alpha multiplier 0.5…1.5 on glassTint. */
+    tintStrength?: number;
+};
+/**
+ * Override map — free fields + optional Pro groups.
+ * schemaVersion migrations keep older maps valid.
+ */
+export type OverrideMap = {
+    schemaVersion: typeof SCHEMA_VERSION | number;
+    basePackId: BasePackId;
+    /** Pack id for CSS `[data-theme="…"]` — kebab-case. */
+    packId?: string;
+    /** Accent seed as `oklch(...)` or `#rrggbb`. */
+    accentSeed?: string;
+    radiusPreset?: RadiusPreset;
+    neutrals?: NeutralOverrides;
+    semantic?: SemanticOverrides;
+    shape?: ShapeOverrides;
+    glass?: GlassOverrides;
+    motion?: MotionCharacter;
+};

package/dist/authoring/types.js

@@ -0,0 +1,11 @@
+export const SCHEMA_VERSION = 2;
+/** Flip when monetization lands — Studio UI reads this stub gate. */
+export const PRO_AUTHORING_UNLOCKED = false;
+export const BASE_PACK_IDS = [
+    "forest",
+    "tide",
+    "graphite",
+    "dune",
+    "clay",
+    "ember",
+];

package/exports/clay/DESIGN.md

@@ -0,0 +1,138 @@
+# Clay — Design brief
+
+> Generated from Hewn curated theme packs. Semantic OKLCH tokens; do not edit by hand.
+
+## Identity
+
+Warm stone and terracotta.
+
+- **Pack id:** `clay`
+- **Base pack:** `clay`
+- **Supported modes:** light
+- **Color scheme (primary):** light
+
+## Palette
+
+| Token | Role | light |
+|---|---|---|
+| `background` | Page and app canvas | `oklch(0.955 0.02 55)` |
+| `foreground` | Primary text and icons | `oklch(0.27 0.045 40)` |
+| `surface` | Cards, panels, and elevated chrome | `oklch(0.98 0.012 50)` |
+| `surface-raised` | Overlays and nested elevation | `oklch(0.995 0.006 45)` |
+| `muted` | Subtle fills and disabled wells | `oklch(0.915 0.025 50)` |
+| `muted-foreground` | Secondary text and captions | `oklch(0.5 0.045 40)` |
+| `accent` | Primary actions and focus accents | `oklch(0.55 0.12 40)` |
+| `accent-foreground` | Text/icons on accent | `oklch(0.98 0.01 50)` |
+| `border` | Separators and control outlines | `oklch(0.4 0.05 40 / 16%)` |
+| `ring` | Focus ring | `oklch(0.6 0.13 40)` |
+| `danger` | Destructive and error states | `oklch(0.54 0.17 28)` |
+| `danger-foreground` | danger-foreground | `oklch(0.985 0.01 28)` |
+| `danger-subtle` | danger-subtle | `oklch(0.94 0.035 28)` |
+| `danger-border` | danger-border | `oklch(0.56 0.12 28 / 40%)` |
+| `success` | success | `oklch(0.55 0.15 145)` |
+| `success-foreground` | success-foreground | `oklch(0.985 0.01 145)` |
+| `success-subtle` | success-subtle | `oklch(0.94 0.035 145)` |
+| `success-border` | success-border | `oklch(0.55 0.12 145 / 40%)` |
+| `warning` | warning | `oklch(0.75 0.14 55)` |
+| `warning-foreground` | warning-foreground | `oklch(0.25 0.05 55)` |
+| `warning-subtle` | warning-subtle | `oklch(0.94 0.04 55)` |
+| `warning-border` | warning-border | `oklch(0.72 0.12 55 / 40%)` |
+| `info` | info | `oklch(0.52 0.11 230)` |
+| `info-foreground` | info-foreground | `oklch(0.985 0.01 230)` |
+| `info-subtle` | info-subtle | `oklch(0.94 0.03 230)` |
+| `info-border` | info-border | `oklch(0.52 0.09 230 / 40%)` |
+| `glass-tint` | Tinted frosted glass material | `oklch(0.74 0.1 45 / 28%)` |
+
+## Typography
+
+| Role | Stack | Usage |
+|---|---|---|
+| Sans | IBM Plex Sans, ui-sans-serif, system-ui | UI chrome, body, headings |
+| Mono | IBM Plex Mono, ui-monospace | Labels, code, tabular metrics |
+| Display | Space Grotesk → sans | Marketing hero H1 and brand wordmark ≥18px only |
+
+Body text uses pretty wrapping; headings use balanced wrapping; dynamic numbers use `tabular-nums`.
+
+## Radius & density
+
+- `radius-sm`: `0.5rem`
+- `radius-md`: `0.8rem`
+- `radius-lg`: `1.05rem`
+- `radius-panel`: `1.05rem`
+- `density`: `1`
+- `motion-duration`: `270ms`
+- `motion-stiffness`: `320`
+- `motion-damping`: `27`
+
+Density scales control spacing rhythm. Panel radius (`radius-panel`) caps menus and dialogs so they never go full-pill.
+
+## Motion
+
+- Duration: `270ms`
+- Spring stiffness: `320`
+- Spring damping: `27`
+- Reduced motion always wins over global motion toggles.
+- Prefer transform / opacity / filter; never animate layout properties continuously.
+
+## Material
+
+- `solid` — structured product surfaces and separators
+- `glass` — accent-tinted frosted surfaces (blur, saturation, refraction, opaque fallback)
+
+## Do
+
+- Use semantic OKLCH tokens (`--kp-*` / `--color-*`); never hard-code theme hues.
+- Typography: IBM Plex Sans (UI), IBM Plex Mono (code/labels), Space Grotesk only for marketing hero H1 and brand wordmark ≥18px.
+- Icons: Phosphor. Interactive hit targets ≥40×40px; press feedback `scale(0.96)`.
+- Motion: animate transform, opacity, and filter; reduced motion always wins.
+- Radius: concentric scale; panels use `--kp-radius-panel` (never full-pill menus/dialogs).
+- Glass is a global material — tint, blur, saturation, refraction edge, opaque fallback.
+
+## Don't
+
+- No purple/lila defaults, neon glow, pure black, Inter, emoji, or generic centered heroes.
+- Never `transition: all` — list exact properties.
+- Never `h-screen` for full-height sections — use `min-h-[100dvh]`.
+- No per-component `glass` prop; material is global.
+- Do not invent unsupported light/dark combinations for a pack.
+- Do not put Space Grotesk in UI chrome, forms, or dense product copy.
+
+## Token reference (primary mode)
+
+```
+--kp-background: oklch(0.955 0.02 55);
+--kp-foreground: oklch(0.27 0.045 40);
+--kp-surface: oklch(0.98 0.012 50);
+--kp-surface-raised: oklch(0.995 0.006 45);
+--kp-muted: oklch(0.915 0.025 50);
+--kp-muted-foreground: oklch(0.5 0.045 40);
+--kp-accent: oklch(0.55 0.12 40);
+--kp-accent-foreground: oklch(0.98 0.01 50);
+--kp-border: oklch(0.4 0.05 40 / 16%);
+--kp-ring: oklch(0.6 0.13 40);
+--kp-danger: oklch(0.54 0.17 28);
+--kp-danger-foreground: oklch(0.985 0.01 28);
+--kp-danger-subtle: oklch(0.94 0.035 28);
+--kp-danger-border: oklch(0.56 0.12 28 / 40%);
+--kp-success: oklch(0.55 0.15 145);
+--kp-success-foreground: oklch(0.985 0.01 145);
+--kp-success-subtle: oklch(0.94 0.035 145);
+--kp-success-border: oklch(0.55 0.12 145 / 40%);
+--kp-warning: oklch(0.75 0.14 55);
+--kp-warning-foreground: oklch(0.25 0.05 55);
+--kp-warning-subtle: oklch(0.94 0.04 55);
+--kp-warning-border: oklch(0.72 0.12 55 / 40%);
+--kp-info: oklch(0.52 0.11 230);
+--kp-info-foreground: oklch(0.985 0.01 230);
+--kp-info-subtle: oklch(0.94 0.03 230);
+--kp-info-border: oklch(0.52 0.09 230 / 40%);
+--kp-glass-tint: oklch(0.74 0.1 45 / 28%);
+--kp-radius-sm: 0.5rem;
+--kp-radius-md: 0.8rem;
+--kp-radius-lg: 1.05rem;
+--kp-radius-panel: 1.05rem;
+--kp-density: 1;
+--kp-motion-duration: 270ms;
+--kp-motion-stiffness: 320;
+--kp-motion-damping: 27;
+```