@nebutra/tokens 0.1.0 → 0.1.2

package/src/brand-package/infer-recipe.ts

@@ -0,0 +1,198 @@
+import type { ButtonDefaultStyle, Density, ElevationStyle } from "./types";
+
+export interface InferredRecipeHints {
+  buttonDefault?: ButtonDefaultStyle;
+  elevationPreset?: ElevationStyle;
+  density?: Density;
+  /** Free radii slots from DESIGN.md tables / free-text */
+  radii?: { button?: string; card?: string };
+  notes: string[];
+}
+
+/**
+ * Infer control recipe from DESIGN.md / agent prompt text.
+ * Used for generic brands and to refine known fixtures.
+ */
+export function inferRecipeFromDesignMd(designMd: string): InferredRecipeHints {
+  const t = designMd.toLowerCase();
+  const notes: string[] = [];
+  const hints: InferredRecipeHints = { notes };
+
+  const outlineFirst =
+    t.includes("outlined-only") ||
+    t.includes("outline-only") ||
+    t.includes("ghost pill") ||
+    t.includes("ghost-pill") ||
+    t.includes("no filled") ||
+    t.includes("don't add filled") ||
+    t.includes("do not add filled") ||
+    t.includes("never fill") ||
+    (t.includes("outlined") && t.includes("button") && !t.includes("filled cta"));
+
+  // Require explicit stroke CTA language — do NOT match hero artwork "gradient"
+  const gradientStroke =
+    t.includes("gradient-stroked") ||
+    t.includes("gradient stroke") ||
+    t.includes("gradient-stroked cta") ||
+    t.includes("border-image") ||
+    (t.includes("gradient border") && (t.includes("cta") || t.includes("button")));
+
+  // Raycast-style neutral CTA — do NOT match mere color-token name "mist" + "filled button"
+  const neutralFilled =
+    t.includes("no chromatic") ||
+    t.includes("deliberately neutral") ||
+    t.includes("neutral rather than chromatic") ||
+    t.includes("no chromatic action") ||
+    t.includes("don't use chromatic action") ||
+    t.includes("do not use chromatic action") ||
+    (t.includes("mist") && t.includes("filled") && (t.includes("iron") || t.includes("neutral")));
+
+  const solidCta =
+    neutralFilled ||
+    (t.includes("filled") &&
+      (t.includes("primary") ||
+        t.includes("cta") ||
+        t.includes("download") ||
+        t.includes("action button") ||
+        t.includes("primary action") ||
+        t.includes("filled button")));
+
+  if (gradientStroke) {
+    hints.buttonDefault = "gradient-stroke";
+    notes.push("DESIGN.md: gradient-stroke CTA");
+  } else if (outlineFirst && !solidCta) {
+    hints.buttonDefault = "outline";
+    notes.push("DESIGN.md: outline-first controls");
+  } else if (solidCta) {
+    hints.buttonDefault = "solid";
+    if (neutralFilled) notes.push("DESIGN.md: neutral filled CTA (not chromatic)");
+  }
+
+  // Explicit ban on all elevation shadows (Stripe/Vanta ledger systems)
+  const forbidsAnyShadow =
+    t.includes("avoids shadows") ||
+    t.includes("avoid shadows") ||
+    t.includes("avoids shadows entirely") ||
+    t.includes("no card has a box-shadow") ||
+    t.includes("no button has a shadow") ||
+    t.includes("never from box-shadow") ||
+    t.includes("never from elevation") ||
+    t.includes("depth comes from background tint") ||
+    t.includes("depth comes from background") ||
+    t.includes("no shadows, blurs") ||
+    t.includes("do not use shadows") ||
+    t.includes("don't use shadows") ||
+    t.includes("rejects drop shadows") ||
+    t.includes("reject drop shadows") ||
+    t.includes("don't drop shadows") ||
+    t.includes("do not drop shadows") ||
+    t.includes("don't apply drop shadows") ||
+    t.includes("do not apply drop shadows") ||
+    t.includes("don't add drop-shadows") ||
+    t.includes("do not add drop-shadows") ||
+    t.includes("never use drop-shadows") ||
+    t.includes("no drop shadow") ||
+    t.includes("no box-shadow") ||
+    t.includes("never via box-shadow") ||
+    t.includes("border is the elevation") ||
+    t.includes("no shadow — the border") ||
+    t.includes("no shadow - the border") ||
+    t.includes("depth is communicated only") ||
+    (t.includes("no shadow") && t.includes("border")) ||
+    (t.includes("flat") && t.includes("1px") && t.includes("border"));
+
+  const keyElev =
+    t.includes("keyboard key") ||
+    t.includes("key shadow") ||
+    t.includes("key cap") ||
+    (t.includes("inset top") && t.includes("highlight") && t.includes("shadow"));
+
+  // Vercel-style: affirmative *use* of stacked box-shadow rings (not "never box-shadow")
+  const hairlineRingElev =
+    !forbidsAnyShadow &&
+    (t.includes("stacked box-shadow") ||
+      t.includes("double-ring") ||
+      t.includes("build depth with hairline") ||
+      (t.includes("hairline") &&
+        t.includes("box-shadow") &&
+        (t.includes("never with drop-shadow") ||
+          t.includes("never use drop-shadow") ||
+          t.includes("not with drop-shadow"))));
+
+  if (keyElev) {
+    hints.elevationPreset = "key";
+    notes.push("DESIGN.md: key/inset elevation");
+  } else if (forbidsAnyShadow) {
+    hints.elevationPreset = "none";
+    notes.push("DESIGN.md: elevation=none (no box-shadow / tint+border depth)");
+  } else if (hairlineRingElev) {
+    hints.elevationPreset = "hairline";
+    notes.push("DESIGN.md: hairline ring elevation");
+  }
+
+  // Density: explicit catalog line beats incidental "compact pill padding"
+  if (
+    /\*\*density:\*\*\s*comfortable|density:\s*comfortable|\bdensity\b[^\n]{0,20}comfortable/i.test(
+      designMd,
+    )
+  ) {
+    hints.density = "comfortable";
+  } else if (/\*\*density:\*\*\s*spacious|density:\s*spacious/i.test(designMd)) {
+    hints.density = "spacious";
+  } else if (/\*\*density:\*\*\s*compact|density:\s*compact/i.test(designMd)) {
+    hints.density = "compact";
+  } else if (
+    (t.includes("compact density") || t.includes("8–12px") || t.includes("8-12px")) &&
+    !t.includes("comfortable")
+  ) {
+    hints.density = "compact";
+  } else if (t.includes("comfortable") || t.includes("spacious")) {
+    hints.density = t.includes("spacious") ? "spacious" : "comfortable";
+  }
+
+  // Radius: **token table rows win** over free-text / agent-prompt noise.
+  // e.g. Notion "| buttons | 8px |" must beat incidental "border-radius 4px" on a tertiary control.
+  const tableButton = designMd.match(/\|\s*buttons\s*\|\s*(\d+px|9999?px)\s*\|/i);
+  const tableCards = designMd.match(/\|\s*cards\s*\|\s*(\d+px|9999?px)\s*\|/i);
+  const tableButtonRadius = tableButton?.[1];
+  const tableCardsRadius = tableCards?.[1];
+  const radii: { button?: string; card?: string } = {};
+  if (tableButtonRadius) {
+    radii.button = tableButtonRadius;
+    notes.push(`DESIGN.md: table buttons radius ${tableButtonRadius}`);
+  } else if (
+    t.includes("4px border-radius on all buttons") ||
+    t.includes("use 4px border-radius on all") ||
+    (t.includes("never pill") && t.includes("4px") && t.includes("button"))
+  ) {
+    radii.button = "4px";
+    notes.push("DESIGN.md: 4px control radius (not pill)");
+  } else if (
+    ((t.includes("999px") || t.includes("9999px")) &&
+      (t.includes("button") || t.includes("pill-shaped")) &&
+      !t.includes("never pill") &&
+      !t.includes("not pill") &&
+      !t.includes("pills only")) ||
+    (t.includes("pill-shaped") && t.includes("button"))
+  ) {
+    radii.button = t.includes("9999px") ? "9999px" : "999px";
+    notes.push("DESIGN.md: full pill control radius");
+  } else if (/\bbuttons?\b[^\n.|]{0,48}\b8px\b/.test(t) || t.includes("8px for buttons")) {
+    radii.button = "8px";
+  } else if (/\bbuttons?\b[^\n.|]{0,48}\b6px\b/.test(t) || t.includes("button radius to 6px")) {
+    radii.button = "6px";
+  } else if (t.includes("100px") && (t.includes("button") || t.includes("pill button"))) {
+    radii.button = "100px";
+  }
+
+  if (tableCardsRadius) {
+    radii.card = tableCardsRadius;
+    notes.push(`DESIGN.md: table cards radius ${tableCardsRadius}`);
+  }
+
+  if (radii.button != null || radii.card != null) {
+    hints.radii = radii;
+  }
+
+  return hints;
+}

package/src/brand-package/normalize.ts

@@ -0,0 +1,295 @@
+/**
+ * Normalize Brand Packages into the carrier contract.
+ * Accepts legacy recipe fields and missing roles; always outputs full roles + free elev/radii.
+ */
+
+import { tryHexToHsl } from "./hex-to-hsl";
+import type {
+  BrandColorRoles,
+  BrandElevationTokens,
+  BrandModePalette,
+  BrandModes,
+  BrandPackage,
+  BrandPackageInput,
+  BrandRadii,
+  BrandRecipe,
+  BrandRecipeInput,
+  BrandSemanticColors,
+  ElevationStyle,
+} from "./types";
+
+const NONE = "0 0 #0000";
+
+const KEY_SHADOW =
+  "rgba(255, 255, 255, 0.05) 0px 1px 0px 0px inset, rgba(255, 255, 255, 0.25) 0px 0px 0px 1px, rgba(0, 0, 0, 0.2) 0px -1px 0px 0px inset";
+
+const HAIRLINE_SHADOW = "rgba(0, 0, 0, 0.08) 0px 0px 0px 1px, rgb(250, 250, 250) 0px 0px 0px 1px";
+
+const SOFT_CARD = "var(--shadow-sm, 0 1px 2px 0 rgb(0 0 0 / 0.05))";
+const SOFT_CONTROL = "var(--shadow-xs, 0 1px 2px 0 rgb(0 0 0 / 0.04))";
+const SOFT_RAISED = "var(--shadow-md, 0 4px 6px -1px rgb(0 0 0 / 0.1))";
+
+/** Ensure role color is HSL channels (accept hex for convenience). */
+function asChannels(value: string | undefined): string | undefined {
+  if (value == null || value === "") return undefined;
+  const v = value.trim();
+  if (v.startsWith("#")) return tryHexToHsl(v, "0 0% 50%");
+  return v;
+}
+
+/** Expand elevation preset → free CSS tokens. */
+export function elevationPresetToTokens(
+  preset: ElevationStyle | undefined,
+  cardShadow?: string,
+): BrandElevationTokens {
+  switch (preset) {
+    case "none":
+      return { card: NONE, control: NONE, raised: NONE };
+    case "key":
+      return {
+        card: cardShadow ?? KEY_SHADOW,
+        control: NONE,
+        raised: cardShadow ?? KEY_SHADOW,
+      };
+    case "hairline":
+      return {
+        card: cardShadow ?? HAIRLINE_SHADOW,
+        control: NONE,
+        raised: cardShadow ?? HAIRLINE_SHADOW,
+      };
+    case "raised":
+      return { card: SOFT_RAISED, control: SOFT_CONTROL, raised: SOFT_RAISED };
+    default:
+      return { card: SOFT_CARD, control: SOFT_CONTROL, raised: SOFT_RAISED };
+  }
+}
+
+export function rolesFromSemantic(
+  s: BrandSemanticColors,
+  brandMark?: { brand?: string; brandForeground?: string },
+): BrandColorRoles {
+  const roles: BrandColorRoles = {
+    canvas: s.background,
+    canvasForeground: s.foreground,
+    surface: s.card,
+    surfaceForeground: s.cardForeground,
+    action: s.primary,
+    actionForeground: s.primaryForeground,
+    quiet: s.secondary,
+    quietForeground: s.secondaryForeground,
+    muted: s.muted,
+    mutedForeground: s.mutedForeground,
+    border: s.border,
+    input: s.input,
+    ring: s.ring,
+    destructive: s.destructive,
+    destructiveForeground: s.destructiveForeground,
+  };
+  const brand = asChannels(brandMark?.brand);
+  if (brand) roles.brand = brand;
+  const brandFg = asChannels(brandMark?.brandForeground);
+  if (brandFg) roles.brandForeground = brandFg;
+  if (s.success) roles.success = s.success;
+  if (s.successForeground) roles.successForeground = s.successForeground;
+  if (s.warning) roles.warning = s.warning;
+  if (s.warningForeground) roles.warningForeground = s.warningForeground;
+  if (s.info) roles.info = s.info;
+  if (s.infoForeground) roles.infoForeground = s.infoForeground;
+  return roles;
+}
+
+/** roles → shadcn semantic: primary ALWAYS tracks action (CTA), never brand mark. */
+export function semanticFromRoles(r: BrandColorRoles): BrandSemanticColors {
+  const accent = r.brand ?? r.quiet;
+  const accentFg = r.brandForeground ?? r.quietForeground;
+  const semantic: BrandSemanticColors = {
+    background: r.canvas,
+    foreground: r.canvasForeground,
+    card: r.surface,
+    cardForeground: r.surfaceForeground,
+    popover: r.surface,
+    popoverForeground: r.surfaceForeground,
+    primary: r.action,
+    primaryForeground: r.actionForeground,
+    secondary: r.quiet,
+    secondaryForeground: r.quietForeground,
+    muted: r.muted,
+    mutedForeground: r.mutedForeground,
+    accent,
+    accentForeground: accentFg,
+    destructive: r.destructive,
+    destructiveForeground: r.destructiveForeground,
+    border: r.border,
+    input: r.input,
+    ring: r.ring,
+  };
+  if (r.success) semantic.success = r.success;
+  if (r.successForeground) semantic.successForeground = r.successForeground;
+  if (r.warning) semantic.warning = r.warning;
+  if (r.warningForeground) semantic.warningForeground = r.warningForeground;
+  if (r.info) semantic.info = r.info;
+  if (r.infoForeground) semantic.infoForeground = r.infoForeground;
+  return semantic;
+}
+
+function normalizeRadii(recipe: BrandRecipeInput): BrandRadii {
+  const button = recipe.radii?.button ?? recipe.buttonRadius ?? "0.375rem";
+  const card = recipe.radii?.card ?? recipe.cardRadius ?? "0.75rem";
+  const radii: BrandRadii = {
+    button,
+    card,
+    badge: recipe.radii?.badge ?? recipe.badgeRadius ?? "9999px",
+    input: recipe.radii?.input ?? recipe.inputRadius ?? button,
+    pill: recipe.radii?.pill ?? "9999px",
+  };
+  return radii;
+}
+
+function normalizeElevation(recipe: BrandRecipeInput): BrandElevationTokens {
+  if (recipe.elevationTokens?.card) {
+    const elev: BrandElevationTokens = { card: recipe.elevationTokens.card };
+    elev.control = recipe.elevationTokens.control ?? NONE;
+    elev.raised = recipe.elevationTokens.raised ?? recipe.elevationTokens.card;
+    return elev;
+  }
+  return elevationPresetToTokens(recipe.elevation, recipe.cardShadow);
+}
+
+function normalizeBadgeDefault(
+  badge: BrandRecipeInput["badgeDefault"],
+): NonNullable<BrandRecipe["badgeDefault"]> {
+  if (!badge || badge === "match-primary") return "match-action";
+  return badge;
+}
+
+function categoryBrandMark(brand: BrandPackage | BrandPackageInput): string | undefined {
+  return typeof brand.extensions?.categories?.brand === "string"
+    ? brand.extensions.categories.brand
+    : undefined;
+}
+
+/** Canonicalize one mode palette → full roles + semantic. */
+export function normalizeModePalette(
+  palette: BrandModePalette,
+  categoryBrand?: string,
+): { roles: BrandColorRoles; semantic: BrandSemanticColors } {
+  let baseRoles: BrandColorRoles;
+  if (palette.roles) {
+    baseRoles = { ...palette.roles };
+  } else if (palette.semantic) {
+    const mark: { brand?: string; brandForeground?: string } = {
+      brandForeground: palette.semantic.primaryForeground,
+    };
+    if (categoryBrand) mark.brand = categoryBrand;
+    baseRoles = rolesFromSemantic(palette.semantic, mark);
+  } else {
+    throw new Error("BrandModePalette requires roles or semantic");
+  }
+
+  const roles: BrandColorRoles = {
+    canvas: baseRoles.canvas,
+    canvasForeground: baseRoles.canvasForeground,
+    surface: baseRoles.surface,
+    surfaceForeground: baseRoles.surfaceForeground,
+    action: baseRoles.action,
+    actionForeground: baseRoles.actionForeground,
+    quiet: baseRoles.quiet,
+    quietForeground: baseRoles.quietForeground,
+    muted: baseRoles.muted,
+    mutedForeground: baseRoles.mutedForeground,
+    border: baseRoles.border,
+    input: baseRoles.input,
+    ring: baseRoles.ring,
+    destructive: baseRoles.destructive,
+    destructiveForeground: baseRoles.destructiveForeground,
+  };
+  const brandCh = asChannels(baseRoles.brand);
+  if (brandCh) roles.brand = brandCh;
+  const brandFg = asChannels(baseRoles.brandForeground) ?? baseRoles.actionForeground;
+  if (brandCh) roles.brandForeground = brandFg;
+  if (baseRoles.success) roles.success = baseRoles.success;
+  if (baseRoles.successForeground) roles.successForeground = baseRoles.successForeground;
+  if (baseRoles.warning) roles.warning = baseRoles.warning;
+  if (baseRoles.warningForeground) roles.warningForeground = baseRoles.warningForeground;
+  if (baseRoles.info) roles.info = baseRoles.info;
+  if (baseRoles.infoForeground) roles.infoForeground = baseRoles.infoForeground;
+
+  return { roles, semantic: semanticFromRoles(roles) };
+}
+
+function normalizeModes(
+  brand: BrandPackage | BrandPackageInput,
+  categoryBrand?: string,
+): BrandModes | undefined {
+  const raw = brand.modes;
+  if (!raw?.light && !raw?.dark) return undefined;
+
+  const modes: BrandModes = {};
+  if (raw.light) {
+    const n = normalizeModePalette(raw.light, categoryBrand);
+    modes.light = { roles: n.roles, semantic: n.semantic };
+  }
+  if (raw.dark) {
+    const n = normalizeModePalette(raw.dark, categoryBrand);
+    modes.dark = { roles: n.roles, semantic: n.semantic };
+  }
+  // Dual-mode complete: both present
+  if (modes.light && modes.dark) return modes;
+  // Partial modes still useful (e.g. only dark override)
+  return modes;
+}
+
+/** Ensure package has roles + free radii/elev; strip legacy recipe aliases from output. */
+export function normalizeBrandPackage(brand: BrandPackage | BrandPackageInput): BrandPackage {
+  const categoryBrand = categoryBrandMark(brand);
+  const modes = normalizeModes(brand, categoryBrand);
+
+  // Default mode palette: dual-mode prefers modes[darkDefault], else top-level semantic/roles
+  const defaultModeKey = brand.darkDefault ? "dark" : "light";
+  const defaultMode = modes?.[defaultModeKey] ?? modes?.light ?? modes?.dark;
+
+  let primaryPalette: BrandModePalette;
+  if (defaultMode?.roles || defaultMode?.semantic) {
+    primaryPalette = {};
+    if (defaultMode.roles) primaryPalette.roles = defaultMode.roles;
+    if (defaultMode.semantic) primaryPalette.semantic = defaultMode.semantic;
+  } else {
+    primaryPalette = { semantic: brand.semantic };
+    if (brand.roles) primaryPalette.roles = brand.roles;
+  }
+
+  const { roles, semantic } = normalizeModePalette(primaryPalette, categoryBrand);
+
+  const looseRecipe = brand.recipe as BrandRecipeInput;
+  const radii = normalizeRadii(looseRecipe);
+  const elevationTokens = normalizeElevation(looseRecipe);
+
+  const recipe: BrandRecipe = {
+    buttonDefault: looseRecipe.buttonDefault,
+    density: looseRecipe.density ?? "comfortable",
+    badgeDefault: normalizeBadgeDefault(looseRecipe.badgeDefault),
+    radii,
+    elevationTokens,
+  };
+  if (looseRecipe.primaryStrokeGradient) {
+    recipe.primaryStrokeGradient = looseRecipe.primaryStrokeGradient;
+  }
+  if (looseRecipe.outlineBorder) {
+    recipe.outlineBorder = looseRecipe.outlineBorder;
+  }
+
+  const out: BrandPackage = {
+    ...brand,
+    roles,
+    semantic,
+    recipe,
+  };
+  if (modes) out.modes = modes;
+  else delete (out as { modes?: BrandModes }).modes;
+  return out;
+}
+
+/** True when package has full dual light+dark palettes. */
+export function isDualModeBrand(brand: BrandPackage): boolean {
+  return Boolean(brand.modes?.light?.semantic && brand.modes?.dark?.semantic);
+}

package/src/brand-package/presets/context.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared context for named compile presets + generic fallback.
+ */
+
+import type { Json } from "../compile-helpers";
+import type { InferredRecipeHints } from "../infer-recipe";
+
+export interface CompileContext {
+  colors: Record<string, string>;
+  font: Json;
+  radius: Json;
+  refero: Json;
+  recipeHints: InferredRecipeHints;
+  warnings: string[];
+  id: string;
+  siteName: string;
+}