@nebutra/tokens 0.1.0 → 0.1.2

package/src/brand-package/emit-css.ts

@@ -0,0 +1,468 @@
+/**
+ * Emit carrier CSS from a normalized Brand Package.
+ * Components bind: --primary (= action), --brand-mark, --elevation-*, --radius-*.
+ */
+
+import { isDualModeBrand, normalizeBrandPackage } from "./normalize";
+import type {
+  BrandColorRoles,
+  BrandFontFace,
+  BrandPackage,
+  BrandRecipe,
+  BrandSemanticColors,
+  BrandTypeStep,
+  BrandZones,
+  BrandZoneTypography,
+} from "./types";
+
+/** Biome CSS formatter prefers double-quoted font families over single quotes. */
+function cssFontStack(stack: string): string {
+  return stack.replace(/'/g, '"');
+}
+
+function recipeVars(recipe: BrandRecipe): string[] {
+  const radii = recipe.radii;
+  const elev = recipe.elevationTokens;
+
+  const lines: string[] = [
+    `  /* Shape slots */`,
+    `  --btn-default-radius: ${radii.button};`,
+    `  --radius-button: ${radii.button};`,
+    `  --radius-buttons: ${radii.button};`,
+    `  --radius-md: ${radii.button};`,
+    `  --radius-card: ${radii.card};`,
+    `  --radius-lg: ${radii.card};`,
+    `  --radius-badge: ${radii.badge ?? "9999px"};`,
+    `  --badge-default-radius: ${radii.badge ?? "9999px"};`,
+    `  --radius-inputs: ${radii.input ?? radii.button};`,
+    `  --input-radius: ${radii.input ?? radii.button};`,
+    `  --radius-pill: ${radii.pill ?? "9999px"};`,
+    ``,
+    `  /* Free elevation (carrier-provided CSS shadows) */`,
+    `  --elevation-card: ${elev.card};`,
+    `  --elevation-control: ${elev.control ?? "0 0 #0000"};`,
+    `  --elevation-raised: ${elev.raised ?? elev.card};`,
+    // Kill Tailwind drop defaults when brand uses custom elev stacks
+    `  --shadow-xs: ${elev.control ?? "0 0 #0000"};`,
+    `  --shadow-sm: ${elev.card};`,
+    `  --shadow-md: ${elev.raised ?? elev.card};`,
+    `  --shadow-lg: ${elev.raised ?? elev.card};`,
+    `  --btn-default-shadow: 0 0 #0000;`,
+  ];
+
+  switch (recipe.buttonDefault) {
+    case "outline": {
+      const edge = recipe.outlineBorder ?? "hsl(var(--foreground))";
+      lines.push("  --btn-default-bg: transparent;");
+      lines.push("  --btn-default-fg: hsl(var(--foreground));");
+      lines.push("  --btn-default-border-width: 1px;");
+      lines.push("  --btn-default-border: transparent;");
+      lines.push(`  --btn-default-stroke-gradient: linear-gradient(${edge}, ${edge});`);
+      lines.push("  --btn-default-hover-bg: hsl(var(--foreground) / 0.06);");
+      break;
+    }
+    case "gradient-stroke": {
+      const grad =
+        recipe.primaryStrokeGradient ??
+        "linear-gradient(135deg, hsl(var(--primary)), color-mix(in srgb, hsl(var(--primary)) 55%, white))";
+      lines.push("  --btn-default-bg: transparent;");
+      lines.push("  --btn-default-fg: hsl(var(--foreground));");
+      lines.push("  --btn-default-border-width: 1.5px;");
+      lines.push("  --btn-default-border: transparent;");
+      lines.push(`  --btn-default-stroke-gradient: ${grad};`);
+      lines.push("  --btn-default-hover-bg: hsl(var(--primary) / 0.08);");
+      break;
+    }
+    default:
+      lines.push("  --btn-default-bg: hsl(var(--primary));");
+      lines.push("  --btn-default-fg: hsl(var(--primary-foreground));");
+      lines.push("  --btn-default-border-width: 0px;");
+      lines.push("  --btn-default-border: transparent;");
+      lines.push("  --btn-default-stroke-gradient: transparent;");
+      lines.push(
+        "  --btn-default-hover-bg: color-mix(in srgb, hsl(var(--primary)) 90%, transparent);",
+      );
+      break;
+  }
+
+  const badgeMode = recipe.badgeDefault ?? "match-action";
+  if (badgeMode === "outline") {
+    const edge = recipe.outlineBorder ?? "hsl(var(--border))";
+    lines.push("  --badge-default-bg: transparent;");
+    lines.push("  --badge-default-fg: hsl(var(--foreground));");
+    lines.push(`  --badge-default-border: ${edge};`);
+    lines.push("  --badge-default-hover-bg: hsl(var(--foreground) / 0.06);");
+  } else if (badgeMode === "muted") {
+    lines.push("  --badge-default-bg: hsl(var(--secondary));");
+    lines.push("  --badge-default-fg: hsl(var(--secondary-foreground));");
+    lines.push("  --badge-default-border: transparent;");
+    lines.push("  --badge-default-hover-bg: color-mix(in srgb, hsl(var(--secondary)) 90%, white);");
+  } else if (badgeMode === "brand") {
+    lines.push("  --badge-default-bg: hsl(var(--brand-mark, var(--accent)));");
+    lines.push(
+      "  --badge-default-fg: hsl(var(--brand-mark-foreground, var(--accent-foreground)));",
+    );
+    lines.push("  --badge-default-border: transparent;");
+    lines.push(
+      "  --badge-default-hover-bg: color-mix(in srgb, hsl(var(--brand-mark, var(--accent))) 85%, transparent);",
+    );
+  } else if (recipe.buttonDefault === "outline" || recipe.buttonDefault === "gradient-stroke") {
+    const edge = recipe.outlineBorder ?? "hsl(var(--foreground))";
+    lines.push("  --badge-default-bg: transparent;");
+    lines.push("  --badge-default-fg: hsl(var(--foreground));");
+    lines.push(`  --badge-default-border: ${edge};`);
+    lines.push("  --badge-default-hover-bg: hsl(var(--foreground) / 0.06);");
+  } else {
+    // match-action
+    lines.push("  --badge-default-bg: hsl(var(--primary));");
+    lines.push("  --badge-default-fg: hsl(var(--primary-foreground));");
+    lines.push("  --badge-default-border: transparent;");
+    lines.push(
+      "  --badge-default-hover-bg: color-mix(in srgb, hsl(var(--primary)) 80%, transparent);",
+    );
+  }
+
+  if (recipe.density === "compact") {
+    lines.push("  --btn-default-padding-y: 0.5rem;");
+    lines.push("  --btn-default-padding-x: 0.875rem;");
+    lines.push("  --control-height-tiny: 1.25rem;");
+    lines.push("  --control-height-sm: 1.75rem;");
+    lines.push("  --control-height-md: 2rem;");
+    lines.push("  --control-height-lg: 2.5rem;");
+    lines.push("  --control-font-size-md: 0.8125rem;");
+  } else if (recipe.density === "spacious") {
+    lines.push("  --btn-default-padding-y: 0.875rem;");
+    lines.push("  --btn-default-padding-x: 1.5rem;");
+    lines.push("  --control-height-tiny: 1.75rem;");
+    lines.push("  --control-height-sm: 2.25rem;");
+    lines.push("  --control-height-md: 2.75rem;");
+    lines.push("  --control-height-lg: 3.25rem;");
+  }
+
+  return lines;
+}
+
+function emitFontFaces(faces: BrandFontFace[] | undefined): string[] {
+  if (!faces?.length) return [];
+  const out: string[] = ["/* Brand font faces */"];
+  for (const face of faces) {
+    const src = face.src
+      .map((s) => {
+        const fmt = s.format ? ` format("${s.format}")` : "";
+        return `url("${s.url}")${fmt}`;
+      })
+      .join(", ");
+    out.push("@font-face {");
+    out.push(`  font-family: "${face.family}";`);
+    out.push(`  src: ${src};`);
+    if (face.weight != null) out.push(`  font-weight: ${face.weight};`);
+    if (face.style) out.push(`  font-style: ${face.style};`);
+    out.push(`  font-display: ${face.display ?? "swap"};`);
+    if (face.unicodeRange) out.push(`  unicode-range: ${face.unicodeRange};`);
+    out.push("}");
+    out.push("");
+  }
+  return out;
+}
+
+function stepVars(prefix: string, step: BrandTypeStep | undefined, role: string): string[] {
+  if (!step) return [];
+  const lines = [`  --${prefix}-${role}-size: ${step.fontSize};`];
+  if (step.lineHeight != null) lines.push(`  --${prefix}-${role}-leading: ${step.lineHeight};`);
+  if (step.letterSpacing != null) {
+    lines.push(`  --${prefix}-${role}-tracking: ${step.letterSpacing};`);
+  }
+  if (step.fontWeight != null) lines.push(`  --${prefix}-${role}-weight: ${step.fontWeight};`);
+  return lines;
+}
+
+function zoneScaleVars(
+  zone: "product" | "marketing",
+  scale: BrandZoneTypography | undefined,
+): string[] {
+  if (!scale) return [];
+  const p = `zone-${zone}`;
+  return [
+    ...stepVars(p, scale.caption, "caption"),
+    ...stepVars(p, scale.bodySm, "body-sm"),
+    ...stepVars(p, scale.body, "body"),
+    ...stepVars(p, scale.bodyLg, "body-lg"),
+    ...stepVars(p, scale.subheading, "subheading"),
+    ...stepVars(p, scale.headingSm, "heading-sm"),
+    ...stepVars(p, scale.heading, "heading"),
+    ...stepVars(p, scale.headingLg, "heading-lg"),
+    ...stepVars(p, scale.display, "display"),
+  ];
+}
+
+function zoneConsumerBlock(
+  zone: "product" | "marketing",
+  scale: BrandZoneTypography | undefined,
+): string[] {
+  if (!scale) return [];
+  const p = `zone-${zone}`;
+  const body = scale.body;
+  const lines = [
+    ``,
+    `/* Zone: ${zone} — product never inherits marketing display */`,
+    // Multi-line selector list matches Biome CSS formatter output (CI governance).
+    `[data-zone="${zone}"],`,
+    `.zone-${zone} {`,
+  ];
+  if (body?.fontSize) lines.push(`  font-size: var(--${p}-body-size, ${body.fontSize});`);
+  if (body?.lineHeight != null) {
+    lines.push(`  line-height: var(--${p}-body-leading, ${body.lineHeight});`);
+  }
+  if (body?.fontWeight != null) {
+    lines.push(`  font-weight: var(--${p}-body-weight, ${body.fontWeight});`);
+  }
+  if (body?.letterSpacing != null) {
+    lines.push(`  letter-spacing: var(--${p}-body-tracking, ${body.letterSpacing});`);
+  }
+  const roles = [
+    "caption",
+    "body-sm",
+    "body",
+    "body-lg",
+    "subheading",
+    "heading-sm",
+    "heading",
+    "heading-lg",
+    "display",
+  ] as const;
+  for (const role of roles) {
+    // Product zone hard-cap: display falls back to heading if product display is unset.
+    // Emit once — a second --text-display trips biome noDuplicateCustomProperties.
+    if (zone === "product" && role === "display") {
+      lines.push(`  --text-display: var(--${p}-display-size, var(--${p}-heading-size, inherit));`);
+    } else {
+      lines.push(`  --text-${role}: var(--${p}-${role}-size, inherit);`);
+    }
+    lines.push(`  --leading-${role}: var(--${p}-${role}-leading, inherit);`);
+    lines.push(`  --tracking-${role}: var(--${p}-${role}-tracking, inherit);`);
+  }
+  lines.push(`}`);
+  return lines;
+}
+
+function emitZones(zones: BrandZones | undefined): string[] {
+  if (!zones) return [];
+  return [
+    ``,
+    `  /* Zone type scales */`,
+    ...zoneScaleVars("product", zones.product),
+    ...zoneScaleVars("marketing", zones.marketing),
+  ];
+}
+
+export type EmitBrandCssMode =
+  /** Single-skin import / Create Center inject — also binds :root (global swap) */
+  | "global"
+  /** Multi-language catalog — only activates under html[data-brand] */
+  | "scoped";
+
+export interface EmitBrandCssOptions {
+  /**
+   * `global` (default): `:root` + `html[data-brand]` — one import recolors the app.
+   * Single-mode dark packs also include `.dark`.
+   * Dual-mode packs (`modes.light` + `modes.dark`) emit separate light/dark color blocks.
+   * `scoped`: only `html[data-brand]` (+ `html.dark[data-brand]` when dual).
+   */
+  mode?: EmitBrandCssMode;
+}
+
+/** Global single-skin selector list — single-mode packs only. */
+export function emitGlobalSkinSelector(brandId: string, darkDefault: boolean): string {
+  if (darkDefault) {
+    return `:root,\n.dark,\nhtml[data-brand="${brandId}"] {`;
+  }
+  return `:root,\nhtml[data-brand="${brandId}"] {`;
+}
+
+/** Light mode selector (dual-mode). */
+export function emitLightModeSelector(brandId: string, mode: EmitBrandCssMode): string {
+  if (mode === "scoped") return `html[data-brand="${brandId}"] {`;
+  return `:root,\nhtml[data-brand="${brandId}"] {`;
+}
+
+/** Dark mode selector (dual-mode) — never paints light colors under .dark. */
+export function emitDarkModeSelector(brandId: string, mode: EmitBrandCssMode): string {
+  if (mode === "scoped") return `html.dark[data-brand="${brandId}"] {`;
+  return `.dark,\nhtml.dark[data-brand="${brandId}"] {`;
+}
+
+function emitColorVars(s: BrandSemanticColors, r: BrandColorRoles | undefined): string[] {
+  const roleLines: string[] = [
+    `  /* ── Color roles (carrier) ── */`,
+    `  --role-canvas: ${r?.canvas ?? s.background};`,
+    `  --role-canvas-fg: ${r?.canvasForeground ?? s.foreground};`,
+    `  --role-surface: ${r?.surface ?? s.card};`,
+    `  --role-surface-fg: ${r?.surfaceForeground ?? s.cardForeground};`,
+    `  --role-action: ${r?.action ?? s.primary};`,
+    `  --role-action-fg: ${r?.actionForeground ?? s.primaryForeground};`,
+    `  --role-quiet: ${r?.quiet ?? s.secondary};`,
+    `  --role-quiet-fg: ${r?.quietForeground ?? s.secondaryForeground};`,
+    `  --role-muted: ${r?.muted ?? s.muted};`,
+    `  --role-muted-fg: ${r?.mutedForeground ?? s.mutedForeground};`,
+    `  --role-border: ${r?.border ?? s.border};`,
+    `  --role-input: ${r?.input ?? s.input};`,
+    `  --role-ring: ${r?.ring ?? s.ring};`,
+  ];
+  if (r?.brand) {
+    roleLines.push(`  --role-brand: ${r.brand};`);
+    roleLines.push(
+      `  --role-brand-fg: ${r.brandForeground ?? r.actionForeground ?? s.primaryForeground};`,
+    );
+    roleLines.push(`  --brand-mark: ${r.brand};`);
+    roleLines.push(
+      `  --brand-mark-foreground: ${r.brandForeground ?? r.actionForeground ?? s.primaryForeground};`,
+    );
+  }
+
+  const semantic = [
+    ``,
+    `  /* ── shadcn bridge (primary = action CTA) ── */`,
+    `  --background: ${s.background};`,
+    `  --foreground: ${s.foreground};`,
+    `  --card: ${s.card};`,
+    `  --card-foreground: ${s.cardForeground};`,
+    `  --popover: ${s.popover};`,
+    `  --popover-foreground: ${s.popoverForeground};`,
+    `  --primary: ${s.primary};`,
+    `  --primary-foreground: ${s.primaryForeground};`,
+    `  --secondary: ${s.secondary};`,
+    `  --secondary-foreground: ${s.secondaryForeground};`,
+    `  --muted: ${s.muted};`,
+    `  --muted-foreground: ${s.mutedForeground};`,
+    `  --accent: ${s.accent};`,
+    `  --accent-foreground: ${s.accentForeground};`,
+    `  --destructive: ${s.destructive};`,
+    `  --destructive-foreground: ${s.destructiveForeground};`,
+    `  --border: ${s.border};`,
+    `  --input: ${s.input};`,
+    `  --ring: ${s.ring};`,
+  ];
+
+  if (s.success) semantic.push(`  --success: ${s.success};`);
+  if (s.successForeground) semantic.push(`  --success-foreground: ${s.successForeground};`);
+  if (s.warning) semantic.push(`  --warning: ${s.warning};`);
+  if (s.warningForeground) semantic.push(`  --warning-foreground: ${s.warningForeground};`);
+  if (s.info) semantic.push(`  --info: ${s.info};`);
+  if (s.infoForeground) semantic.push(`  --info-foreground: ${s.infoForeground};`);
+
+  semantic.push(
+    `  --sidebar: ${s.card};`,
+    `  --sidebar-foreground: ${s.foreground};`,
+    `  --sidebar-primary: ${s.primary};`,
+    `  --sidebar-primary-foreground: ${s.primaryForeground};`,
+    `  --sidebar-accent: ${s.accent};`,
+    `  --sidebar-accent-foreground: ${s.accentForeground};`,
+    `  --sidebar-border: ${s.border};`,
+    `  --sidebar-ring: ${s.ring};`,
+    `  --brand-gradient: hsl(var(--primary));`,
+    `  --brand-gradient-reverse: hsl(var(--primary));`,
+    `  --brand-gradient-vertical: hsl(var(--primary));`,
+    `  --brand-gradient-radial: hsl(var(--primary));`,
+  );
+
+  return [...roleLines, ...semantic];
+}
+
+/**
+ * Emit a single opt-in skin CSS file from a Brand Package.
+ */
+export function emitBrandCss(brand: BrandPackage, options: EmitBrandCssOptions = {}): string {
+  const mode = options.mode ?? "global";
+  const b = normalizeBrandPackage(brand);
+  const t = b.typography;
+  const dual = isDualModeBrand(b);
+
+  const parts: string[] = [
+    `/**`,
+    ` * Brand carrier skin: ${b.name} (${b.id}) v${b.version}`,
+    ` * darkDefault=${b.darkDefault} dualMode=${dual} button=${b.recipe.buttonDefault}`,
+    ` * fonts=${t.faces?.length ?? 0} zones=${b.zones ? "yes" : "no"} mode=${mode}`,
+    ` * Contract: roles.action → --primary; roles.brand → --brand-mark (never default CTA)`,
+    ` */`,
+    ``,
+    ...emitFontFaces(t.faces),
+  ];
+
+  // Biome CSS formatter prefers double-quoted font families.
+  const fontSans = cssFontStack(t.fontSans);
+  const fontDisplay = cssFontStack(t.fontDisplay ?? t.fontSans);
+  const typeLines = [
+    `  --font-sans: ${fontSans};`,
+    `  --font-heading: ${fontDisplay};`,
+    `  --font-display: ${fontDisplay};`,
+  ];
+  if (t.fontMono) typeLines.push(`  --font-mono: ${cssFontStack(t.fontMono)};`);
+  if (t.headingWeight != null) {
+    typeLines.push(`  --font-weight-heading: ${t.headingWeight};`);
+  }
+
+  const cats = b.extensions?.categories;
+  const decorative = b.extensions?.decorative;
+  const extLines: string[] = [];
+  if (cats) {
+    for (const [key, value] of Object.entries(cats)) {
+      const safe = key.replace(/[^a-z0-9_-]/gi, "-").toLowerCase();
+      extLines.push(`  --brand-category-${safe}: ${value};`);
+    }
+  }
+  if (decorative) {
+    for (const [key, value] of Object.entries(decorative)) {
+      const safe = key.replace(/[^a-z0-9_-]/gi, "-").toLowerCase();
+      extLines.push(`  --brand-decorative-${safe}: ${value};`);
+    }
+  }
+
+  const sharedChrome = [
+    ``,
+    `  /* Recipe (action language + free elev/radii) */`,
+    ...recipeVars(b.recipe),
+    ``,
+    `  /* Typography */`,
+    ...typeLines,
+    ...emitZones(b.zones),
+    ...(extLines.length
+      ? ["", "  /* Taxonomy / decorative (not product CTA) */", ...extLines]
+      : []),
+  ];
+
+  if (dual && b.modes?.light?.semantic && b.modes?.dark?.semantic) {
+    // Light block: colors + shared chrome
+    parts.push(emitLightModeSelector(b.id, mode));
+    parts.push(
+      ...emitColorVars(b.modes.light.semantic, b.modes.light.roles),
+      ...sharedChrome,
+      `}`,
+      ``,
+    );
+    // Dark block: colors only (chrome inherits)
+    parts.push(emitDarkModeSelector(b.id, mode));
+    parts.push(...emitColorVars(b.modes.dark.semantic, b.modes.dark.roles), `}`, ``);
+  } else {
+    // Single-mode: one selector + full block
+    const selector =
+      mode === "scoped"
+        ? `html[data-brand="${b.id}"] {`
+        : emitGlobalSkinSelector(b.id, b.darkDefault);
+    parts.push(selector);
+    parts.push(...emitColorVars(b.semantic, b.roles), ...sharedChrome, `}`, ``);
+  }
+
+  parts.push(
+    ...zoneConsumerBlock("product", b.zones?.product),
+    ...zoneConsumerBlock("marketing", b.zones?.marketing),
+    ``,
+    `/* Product chrome must not use decorative gradients as action fills */`,
+    `[data-zone="product"] .btn-brand-default,`,
+    `.zone-product .btn-brand-default {`,
+    `  /* intentional no-op: documents contract; action uses --primary only */`,
+    `}`,
+    ``,
+  );
+
+  return parts.join("\n");
+}

package/src/brand-package/hex-to-hsl.ts

@@ -0,0 +1,100 @@
+/** Convert #rgb / #rrggbb to HSL channel triple "H S% L%" for shadcn-style vars. */
+export function hexToHslChannels(hex: string): string {
+  let h = hex.trim().replace(/^#/, "");
+  if (h.length === 3) {
+    h = h
+      .split("")
+      .map((c) => c + c)
+      .join("");
+  }
+  if (h.length !== 6 || !/^[0-9a-fA-F]+$/.test(h)) {
+    throw new Error(`Invalid hex color: ${hex}`);
+  }
+  const r = Number.parseInt(h.slice(0, 2), 16) / 255;
+  const g = Number.parseInt(h.slice(2, 4), 16) / 255;
+  const b = Number.parseInt(h.slice(4, 6), 16) / 255;
+  return srgbToHslChannels(r, g, b);
+}
+
+function srgbToHslChannels(r: number, g: number, b: number): string {
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const l = (max + min) / 2;
+  let s = 0;
+  let hue = 0;
+  if (max !== min) {
+    const d = max - min;
+    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    switch (max) {
+      case r:
+        hue = (g - b) / d + (g < b ? 6 : 0);
+        break;
+      case g:
+        hue = (b - r) / d + 2;
+        break;
+      default:
+        hue = (r - g) / d + 4;
+    }
+    hue /= 6;
+  }
+  const H = Math.round(hue * 360);
+  const S = Math.round(s * 100);
+  const L = Math.round(l * 100);
+  return `${H} ${S}% ${L}%`;
+}
+
+/** Already a shadcn-style channel triple? e.g. "228 85% 56%" */
+const HSL_CHANNELS_RE = /^(\d+(?:\.\d+)?)\s+(\d+(?:\.\d+)?)%\s+(\d+(?:\.\d+)?)%$/;
+
+/**
+ * Normalize any common color input to HSL channel triple "H S% L%".
+ * Accepts: #hex, "H S% L%", hsl()/hsla(), rgb()/rgba().
+ */
+export function colorToHslChannels(color: string): string {
+  const t = color.trim();
+  if (!t) throw new Error("Empty color");
+
+  const channels = t.match(HSL_CHANNELS_RE);
+  if (channels) {
+    return `${Math.round(Number(channels[1]))} ${Math.round(Number(channels[2]))}% ${Math.round(Number(channels[3]))}%`;
+  }
+
+  // Parse hsl()/rgb() without open-ended \s* quantifiers (ReDoS-safe).
+  const hslPrefix = t.match(/^hsla?\(/i);
+  if (hslPrefix) {
+    const inner = t.slice(hslPrefix[0].length).split(")")[0] ?? "";
+    const nums = inner.match(/[\d.]+/g) ?? [];
+    if (nums.length >= 3) {
+      return `${Math.round(Number(nums[0]))} ${Math.round(Number(nums[1]))}% ${Math.round(Number(nums[2]))}%`;
+    }
+  }
+
+  const rgbPrefix = t.match(/^rgba?\(/i);
+  if (rgbPrefix) {
+    const inner = t.slice(rgbPrefix[0].length).split(")")[0] ?? "";
+    const nums = inner.match(/[\d.]+/g) ?? [];
+    if (nums.length >= 3) {
+      return srgbToHslChannels(Number(nums[0]) / 255, Number(nums[1]) / 255, Number(nums[2]) / 255);
+    }
+  }
+
+  if (t.startsWith("#") || /^[0-9a-fA-F]{3,8}$/.test(t)) {
+    return hexToHslChannels(t.startsWith("#") ? t : `#${t}`);
+  }
+
+  throw new Error(`Unsupported color: ${color}`);
+}
+
+/** Prefer {@link colorToHslChannels}; hex-only name kept for call sites. */
+export function tryHexToHsl(hex: string | undefined, fallback: string): string {
+  return tryColorToHsl(hex, fallback);
+}
+
+export function tryColorToHsl(color: string | undefined, fallback: string): string {
+  if (!color) return fallback;
+  try {
+    return colorToHslChannels(color);
+  } catch {
+    return fallback;
+  }
+}

package/src/brand-package/index.ts

@@ -0,0 +1,71 @@
+export {
+  type ApplyBrandOptions,
+  applyBrandCss,
+  applyBrandPackage,
+  BRAND_STORAGE_KEY,
+  BRAND_STYLE_ELEMENT_ID,
+  clearBrand,
+  getActiveBrandId,
+  restorePersistedBrand,
+} from "./apply-brand";
+export { compileReferoTokens } from "./compile-refero";
+export {
+  type EmitBrandCssMode,
+  type EmitBrandCssOptions,
+  emitBrandCss,
+  emitDarkModeSelector,
+  emitGlobalSkinSelector,
+  emitLightModeSelector,
+} from "./emit-css";
+export {
+  colorToHslChannels,
+  hexToHslChannels,
+  tryColorToHsl,
+  tryHexToHsl,
+} from "./hex-to-hsl";
+export { type InferredRecipeHints, inferRecipeFromDesignMd } from "./infer-recipe";
+export {
+  elevationPresetToTokens,
+  isDualModeBrand,
+  normalizeBrandPackage,
+  normalizeModePalette,
+  rolesFromSemantic,
+  semanticFromRoles,
+} from "./normalize";
+export type {
+  BadgeDefaultStyle,
+  BrandColorRoles,
+  BrandElevationTokens,
+  BrandExtensions,
+  BrandFontFace,
+  BrandFontSource,
+  BrandModePalette,
+  BrandModes,
+  BrandPackage,
+  BrandPackageInput,
+  BrandRadii,
+  BrandRecipe,
+  BrandRecipeInput,
+  BrandSemanticColors,
+  BrandTypeStep,
+  BrandTypography,
+  BrandZoneId,
+  BrandZones,
+  BrandZoneTypography,
+  ButtonDefaultStyle,
+  CompileResult,
+  CssColor,
+  Density,
+  ElevationStyle,
+  HslChannels,
+} from "./types";
+export {
+  applyBrandToIframe,
+  type BrandIframePreviewOptions,
+  type UseBrandIframePreviewResult,
+  type UseBrandOptions,
+  type UseBrandResult,
+  useBrand,
+  useBrandIframePreview,
+} from "./use-brand";
+export { type ValidationResult, validateBrandPackage } from "./validate";