@hraness/design-kit 0.31.1

package/src/palette-appearance.ts

@@ -0,0 +1,45 @@
+import { isDesignTheme, resolveDesignTheme, type ConcreteDesignTheme, type DesignTheme } from "./appearance.js";
+import { isDesignPalette, type DesignPalette } from "./palettes.js";
+
+export interface DesignPalettePreference {
+  readonly palette: DesignPalette;
+  readonly mode: DesignTheme;
+}
+
+export interface ConcreteDesignPalettePreference extends DesignPalettePreference {
+  readonly mode: ConcreteDesignTheme;
+}
+
+export const defaultDesignPalettePreference: ConcreteDesignPalettePreference = Object.freeze({
+  palette: "catppuccin",
+  mode: "dark",
+});
+export const designPaletteStorageKey = "hraness-design-palette-v1";
+
+/** Parses persisted JSON and application values without accepting partial preferences. */
+export function parseDesignPalettePreference(value: unknown): DesignPalettePreference | null {
+  if (typeof value === "string") {
+    if (value.length > 256) return null;
+    try { value = JSON.parse(value) as unknown; } catch { return null; }
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+  const record = value as Record<string, unknown>;
+  if (!isDesignPalette(record.palette) || !isDesignTheme(record.mode)) return null;
+  return Object.freeze({ palette: record.palette, mode: record.mode });
+}
+
+export function normalizeDesignPalettePreference(
+  value: unknown,
+  fallback: DesignPalettePreference = defaultDesignPalettePreference,
+): DesignPalettePreference {
+  return parseDesignPalettePreference(value)
+    ?? parseDesignPalettePreference(fallback)
+    ?? defaultDesignPalettePreference;
+}
+
+export function resolveDesignPalettePreference(
+  preference: DesignPalettePreference,
+  systemPrefersDark: boolean,
+): ConcreteDesignPalettePreference {
+  return { palette: preference.palette, mode: resolveDesignTheme(preference.mode, systemPrefersDark) };
+}

package/src/palette-bridge.css

@@ -0,0 +1,124 @@
+/* StyleX owns --hraness-palette-* values. This opt-in global boundary joins
+ * portable controls, product CSS, and compiled recipes without new runtime CSS.
+ * Import after the existing token boundary. Explicit palette islands carry
+ * their own complete theme class, including portalled overlays. Repeating the
+ * palette attribute outranks earlier or later legacy root and island tokens;
+ * bundlers may deduplicate a consumer's second bridge import. */
+@import "./palette-system.css";
+
+:root.hraness-palette[data-theme],
+.hraness-palette[data-theme],
+:root[data-palette][data-palette],
+[data-palette][data-palette] {
+  --background: var(--hraness-palette-background);
+  --foreground: var(--hraness-palette-foreground);
+  --muted: var(--hraness-palette-muted);
+  --faint: var(--hraness-palette-faint);
+  --grid: var(--hraness-palette-grid);
+  --line: var(--hraness-palette-line);
+  --control-border: var(--hraness-palette-control-border);
+  --surface: var(--hraness-palette-surface);
+  --surface-raised: var(--hraness-palette-surface-raised);
+  --surface-hover: var(--hraness-palette-surface-hover);
+  --card: var(--hraness-palette-card);
+  --card-foreground: var(--hraness-palette-card-foreground);
+  --popover: var(--hraness-palette-popover);
+  --popover-foreground: var(--hraness-palette-popover-foreground);
+  --primary: var(--hraness-palette-primary);
+  --primary-foreground: var(--hraness-palette-primary-foreground);
+  --primary-soft: var(--hraness-palette-primary-soft);
+  --secondary: var(--hraness-palette-secondary);
+  --secondary-foreground: var(--hraness-palette-secondary-foreground);
+  --accent: var(--hraness-palette-accent);
+  --accent-foreground: var(--hraness-palette-accent-foreground);
+  --focus: var(--hraness-palette-focus);
+  --scrim: var(--hraness-palette-scrim);
+  --disabled: var(--hraness-palette-disabled);
+  --disabled-foreground: var(--hraness-palette-disabled-foreground);
+  --inverse: var(--hraness-palette-inverse);
+  --inverse-foreground: var(--hraness-palette-inverse-foreground);
+  --danger: var(--hraness-palette-danger);
+  --danger-foreground: var(--hraness-palette-danger-foreground);
+  --danger-soft: var(--hraness-palette-danger-soft);
+  --warning: var(--hraness-palette-warning);
+  --warning-foreground: var(--hraness-palette-warning-foreground);
+  --warning-soft: var(--hraness-palette-warning-soft);
+  --success: var(--hraness-palette-success);
+  --success-foreground: var(--hraness-palette-success-foreground);
+  --success-soft: var(--hraness-palette-success-soft);
+  --info: var(--hraness-palette-info);
+  --info-foreground: var(--hraness-palette-info-foreground);
+  --info-soft: var(--hraness-palette-info-soft);
+  --ui-background: var(--hraness-palette-background);
+  --ui-foreground: var(--hraness-palette-foreground);
+  --ui-card: var(--hraness-palette-card);
+  --ui-card-foreground: var(--hraness-palette-card-foreground);
+  --ui-popover: var(--hraness-palette-popover);
+  --ui-popover-foreground: var(--hraness-palette-popover-foreground);
+  --ui-primary: var(--hraness-palette-primary);
+  --ui-primary-foreground: var(--hraness-palette-primary-foreground);
+  --ui-secondary: var(--hraness-palette-secondary);
+  --ui-secondary-foreground: var(--hraness-palette-secondary-foreground);
+  --ui-muted: var(--hraness-palette-surface-raised);
+  --ui-muted-foreground: var(--hraness-palette-muted);
+  --ui-accent: var(--hraness-palette-accent);
+  --ui-accent-foreground: var(--hraness-palette-accent-foreground);
+  --ui-destructive: var(--hraness-palette-danger);
+  --ui-destructive-foreground: var(--hraness-palette-danger-foreground);
+  --ui-destructive-soft: var(--hraness-palette-danger-soft);
+  --ui-border: var(--hraness-palette-line);
+  --ui-input: var(--hraness-palette-control-border);
+  --ui-ring: var(--hraness-palette-focus);
+  --ui-success: var(--hraness-palette-success);
+  --ui-success-foreground: var(--hraness-palette-success-foreground);
+  --ui-success-soft: var(--hraness-palette-success-soft);
+  --ui-warning: var(--hraness-palette-warning);
+  --ui-warning-foreground: var(--hraness-palette-warning-foreground);
+  --ui-warning-soft: var(--hraness-palette-warning-soft);
+  --ui-info: var(--hraness-palette-info);
+  --ui-info-foreground: var(--hraness-palette-info-foreground);
+  --ui-info-soft: var(--hraness-palette-info-soft);
+  --ui-chart-1: var(--hraness-palette-chart1);
+  --ui-chart-2: var(--hraness-palette-chart2);
+  --ui-chart-3: var(--hraness-palette-chart3);
+  --ui-chart-4: var(--hraness-palette-chart4);
+  --ui-chart-5: var(--hraness-palette-chart5);
+  --aurora-rose: var(--hraness-palette-chart1);
+  --aurora-mint: var(--hraness-palette-chart2);
+  --aurora-cyan: var(--hraness-palette-chart3);
+  --aurora-gold: var(--hraness-palette-chart4);
+  --aurora-violet: var(--hraness-palette-chart5);
+  --canvas-background: var(--hraness-palette-background);
+}
+
+.hraness-palette[data-theme="dark"] { color-scheme: dark; }
+.hraness-palette[data-theme="light"] { color-scheme: light; }
+
+@media (forced-colors: active) {
+  /* The pinned StyleX serializer doubles createTheme classes. Outrank those
+   * unlayered rules even when a compiler consumer loads its final union last. */
+  :root.hraness-palette.hraness-palette[data-palette],
+  .hraness-palette.hraness-palette[data-palette],
+  :root[data-palette][data-theme],
+  [data-palette][data-theme],
+  :root[data-palette]:not([data-theme]),
+  [data-palette]:not([data-theme]),
+  :root.hraness-palette.hraness-palette[data-theme],
+  .hraness-palette.hraness-palette[data-theme] {
+    --hraness-palette-background: Canvas;
+    --hraness-palette-foreground: CanvasText;
+    --hraness-palette-muted: CanvasText;
+    --hraness-palette-surface: Canvas;
+    --hraness-palette-surface-raised: Canvas;
+    --hraness-palette-surface-hover: Canvas;
+    --hraness-palette-card: Canvas;
+    --hraness-palette-card-foreground: CanvasText;
+    --hraness-palette-popover: Canvas;
+    --hraness-palette-popover-foreground: CanvasText;
+    --hraness-palette-line: CanvasText;
+    --hraness-palette-control-border: ButtonText;
+    --hraness-palette-primary: Highlight;
+    --hraness-palette-primary-foreground: HighlightText;
+    --hraness-palette-focus: Highlight;
+  }
+}

package/src/palette-color.ts

@@ -0,0 +1,41 @@
+/** sRGB contrast utilities for the authored, opaque palette recipes. */
+function channels(hex: string): readonly [number, number, number] {
+  if (!/^#[0-9a-f]{6}$/iu.test(hex)) throw new Error("Palette colors must be six-digit hex values.");
+  return [Number.parseInt(hex.slice(1, 3), 16), Number.parseInt(hex.slice(3, 5), 16), Number.parseInt(hex.slice(5, 7), 16)];
+}
+
+export function mixPaletteColor(color: string, toward: string, amount: number): string {
+  const target = channels(toward);
+  return `#${channels(color).map((value, index) =>
+    Math.round(value * (1 - amount) + (target[index] ?? 0) * amount).toString(16).padStart(2, "0")
+  ).join("")}`;
+}
+
+function luminance(hex: string): number {
+  const linearize = (channel: number): number => {
+    const value = channel / 255;
+    return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+  };
+  const [red, green, blue] = channels(hex);
+  return linearize(red) * 0.2126 + linearize(green) * 0.7152 + linearize(blue) * 0.0722;
+}
+
+export function paletteContrast(a: string, b: string): number {
+  const first = luminance(a);
+  const second = luminance(b);
+  return (Math.max(first, second) + 0.05) / (Math.min(first, second) + 0.05);
+}
+
+/** Retain the upstream hue; move toward readable ink only where contrast needs it. */
+export function readablePaletteColor(
+  color: string,
+  toward: string,
+  backgrounds: readonly string[],
+  minimum: number,
+): string {
+  for (let step = 0; step <= 100; step += 1) {
+    const candidate = mixPaletteColor(color, toward, step / 100);
+    if (backgrounds.every((background) => paletteContrast(candidate, background) >= minimum)) return candidate;
+  }
+  throw new Error("The authored palette cannot meet its contrast contract.");
+}