aeon-ui-engine 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to **aeon-ui-engine** are documented here.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0] - 2026-07-30
+
+### Added
+
+- **Brand palette bridge** — `applyBrandPalette`, `normalizeBrandPalette`, `brandPaletteToCssText` map product tokens onto Aeon CSS vars without a parallel token sheet.
+- **AppNav** — `appNavMachine` + `AppNav` / `useAppNavMachine` for section + detail stack navigation with breadcrumb/back parts.
+- **Prompt** — confirm/permission-style compound on top of Dialog (`eyebrow`, `meta`, `amount`, `actions`).
+- **StatusBanner** — non-blocking top-of-app notice compound.
+- **`useFitText`** — shrink-to-fit metric/title helper.
+- **Consumer shell CSS** — baseline Prompt / StatusBanner / AppNav styles in `aeon.css`.
+- **Electron chrome CSS** — optional `@aeon-ui/panda/electron.css` titlebar drag helpers.
+- Docs: [PRODUCT_SHELL.md](./docs/PRODUCT_SHELL.md).
+
+### Changed
+
+- Avatar root also projects `ready` alongside `loaded` for friendlier product CSS.
+- `aeonUiVitePlugin` aliases include consumer-shell and electron CSS paths.
+
 ## [1.1.0] - 2026-07-30
 
 ### Added
@@ -59,6 +77,7 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 - Initial npm release of **aeon-ui-engine** — monorepo bundle with headless statechart primitives, React bindings, Panda styled layer, and themes.
 
+[1.2.0]: https://github.com/GenericCPU/aeon-ui/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/GenericCPU/aeon-ui/compare/v1.0.3...v1.1.0
 [1.0.3]: https://github.com/GenericCPU/aeon-ui/compare/v1.0.2...v1.0.3
 [1.0.2]: https://github.com/GenericCPU/aeon-ui/compare/v1.0.1...v1.0.2

package/CONSUMER.md

@@ -60,6 +60,51 @@ Or extend directly:
 }
 ```
 
+## Optional: Brand palette (skip catalog themes)
+
+If your product already has tokens, map them onto Aeon CSS vars once at boot:
+
+```ts
+import { applyBrandPalette } from '@aeon-ui/core'
+
+applyBrandPalette(
+  {
+    bg: '#000000',
+    surface: '#0a0a0a',
+    border: '#262626',
+    text: '#fafafa',
+    muted: '#a1a1aa',
+    accent: '#57ff97',
+    font: "'Archivo', system-ui, sans-serif",
+  },
+  { mode: 'dark' },
+)
+```
+
+Then use `@aeon-ui/ui` without maintaining a parallel `--product-*` token sheet
+for Aeon components. See [docs/PRODUCT_SHELL.md](./docs/PRODUCT_SHELL.md).
+
+## Optional: Product shell compounds
+
+```tsx
+import { AppNav, Prompt, StatusBanner, AppShell } from '@aeon-ui/ui'
+
+// Section + detail stack (replaces ad-hoc nav stores)
+<AppNav.Root defaultSection="home">...</AppNav.Root>
+
+// Confirm / permission style dialog (portal + focus trap via Dialog)
+<Prompt.Root open={open} status="pending">...</Prompt.Root>
+
+// Non-blocking top banner (updates, sync, offline)
+<StatusBanner.Root status="ready">...</StatusBanner.Root>
+```
+
+Electron titlebar helpers (drag regions, traffic-light padding):
+
+```ts
+import '@aeon-ui/panda/electron.css'
+```
+
 ## Optional: Headless only
 
 Skip the styled layer and import headless components directly:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aeon-ui-engine",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "private": false,
   "type": "module",
   "bin": {

package/packages/core/dist/index.d.ts

@@ -26,6 +26,25 @@ declare const checkboxAnatomy: Record<"root" | "label" | "control" | "hiddenInpu
 declare const dialogAnatomy: Record<"root" | "trigger" | "portal" | "backdrop" | "positioner" | "content" | "title" | "description" | "closeTrigger", "root" | "trigger" | "portal" | "backdrop" | "positioner" | "content" | "title" | "description" | "closeTrigger"> & {
     scope: string;
 };
+/**
+ * Prompt — confirm / permission / update-style dialog on top of Dialog.
+ * Universal parts: eyebrow, meta, amount, actions (primary + secondary).
+ */
+declare const promptAnatomy: Record<"root" | "eyebrow" | "meta" | "amount" | "actions" | "primary" | "secondary", "root" | "eyebrow" | "meta" | "amount" | "actions" | "primary" | "secondary"> & {
+    scope: string;
+};
+/**
+ * AppNav — section + detail stack (list→detail, settings drill-in).
+ */
+declare const appNavAnatomy: Record<"root" | "rail" | "section" | "stage" | "breadcrumb" | "crumb" | "back", "root" | "rail" | "section" | "stage" | "breadcrumb" | "crumb" | "back"> & {
+    scope: string;
+};
+/**
+ * StatusBanner — non-blocking top-of-app notice (update ready, syncing, offline).
+ */
+declare const statusBannerAnatomy: Record<"root" | "title" | "actions" | "copy" | "body", "root" | "title" | "actions" | "copy" | "body"> & {
+    scope: string;
+};
 declare const tabsAnatomy: Record<"root" | "indicator" | "trigger" | "content" | "list", "root" | "indicator" | "trigger" | "content" | "list"> & {
     scope: string;
 };
@@ -33,7 +52,7 @@ declare const accordionAnatomy: Record<"root" | "item" | "itemTrigger" | "itemCo
     scope: string;
 };
 /** Async data region — track shows every lifecycle state; readout + actions mirror snapshot. */
-declare const asyncAnatomy: Record<"root" | "track" | "segment" | "readout" | "readoutRail" | "readoutBody" | "actions", "root" | "track" | "segment" | "readout" | "readoutRail" | "readoutBody" | "actions"> & {
+declare const asyncAnatomy: Record<"root" | "actions" | "track" | "segment" | "readout" | "readoutRail" | "readoutBody", "root" | "actions" | "track" | "segment" | "readout" | "readoutRail" | "readoutBody"> & {
     scope: string;
 };
 /** Form field — orthogonal interaction × validation × submission (see STATES.md). */
@@ -78,14 +97,14 @@ declare const avatarAnatomy: Record<"root" | "image" | "fallback" | "badge", "ro
  * Identity strip — avatar + primary/secondary text (items-market AvatarWithName).
  * Presentational; compose into ProfileHeader / ListRow / AccountCluster.
  */
-declare const identityAnatomy: Record<"root" | "title" | "avatar" | "subtitle" | "meta" | "trailing", "root" | "title" | "avatar" | "subtitle" | "meta" | "trailing"> & {
+declare const identityAnatomy: Record<"root" | "title" | "meta" | "avatar" | "subtitle" | "trailing", "root" | "title" | "meta" | "avatar" | "subtitle" | "trailing"> & {
     scope: string;
 };
 /**
  * Profile header — dense account hero (not dating). Media optional; metrics + actions zones.
  * Spatial: identity leading, metrics inline, actions trailing / bottom leading pair.
  */
-declare const profileHeaderAnatomy: Record<"root" | "actions" | "identity" | "media" | "metrics" | "body", "root" | "actions" | "identity" | "media" | "metrics" | "body"> & {
+declare const profileHeaderAnatomy: Record<"root" | "actions" | "body" | "identity" | "media" | "metrics", "root" | "actions" | "body" | "identity" | "media" | "metrics"> & {
     scope: string;
 };
 /**
@@ -94,7 +113,7 @@ declare const profileHeaderAnatomy: Record<"root" | "actions" | "identity" | "me
  * List stacks cards; Root is one card (idle | selected | muted).
  * Zones: header (leading · heading · meta) · media · body · values · actions · footer.
  */
-declare const entryAnatomy: Record<"values" | "root" | "title" | "list" | "actions" | "value" | "subtitle" | "meta" | "media" | "body" | "header" | "leading" | "heading" | "footer", "values" | "root" | "title" | "list" | "actions" | "value" | "subtitle" | "meta" | "media" | "body" | "header" | "leading" | "heading" | "footer"> & {
+declare const entryAnatomy: Record<"values" | "root" | "title" | "meta" | "actions" | "body" | "list" | "value" | "subtitle" | "media" | "header" | "leading" | "heading" | "footer", "values" | "root" | "title" | "meta" | "actions" | "body" | "list" | "value" | "subtitle" | "media" | "header" | "leading" | "heading" | "footer"> & {
     scope: string;
 };
 /**
@@ -115,13 +134,13 @@ declare const listRowAnatomy: Record<"root" | "label" | "description" | "trailin
  * Leading avatar · title · preview · meta (time) · badge (unread).
  * Item state: idle | unread | selected.
  */
-declare const conversationAnatomy: Record<"root" | "title" | "item" | "badge" | "meta" | "body" | "leading" | "preview", "root" | "title" | "item" | "badge" | "meta" | "body" | "leading" | "preview"> & {
+declare const conversationAnatomy: Record<"root" | "title" | "meta" | "body" | "item" | "badge" | "leading" | "preview", "root" | "title" | "meta" | "body" | "item" | "badge" | "leading" | "preview"> & {
     scope: string;
 };
 /**
  * Thread — message stream. Items project mine | theirs | pending | failed.
  */
-declare const threadAnatomy: Record<"root" | "list" | "item" | "meta" | "bubble" | "day", "root" | "list" | "item" | "meta" | "bubble" | "day"> & {
+declare const threadAnatomy: Record<"root" | "meta" | "list" | "item" | "bubble" | "day", "root" | "meta" | "list" | "item" | "bubble" | "day"> & {
     scope: string;
 };
 /**
@@ -174,7 +193,7 @@ declare const appShellAnatomy: Record<"root" | "content" | "header" | "footer" |
  * Content region — status-slotted body. Every contentRegionMachine state has a part.
  * Pair with Async for fetch; use slots for idle/pending/empty/error/ready/loadingMore/success.
  */
-declare const contentAnatomy: Record<"root" | "empty" | "body" | "toolbar" | "pending" | "error" | "success" | "sentinel", "root" | "empty" | "body" | "toolbar" | "pending" | "error" | "success" | "sentinel"> & {
+declare const contentAnatomy: Record<"root" | "body" | "empty" | "toolbar" | "pending" | "error" | "success" | "sentinel", "root" | "body" | "empty" | "toolbar" | "pending" | "error" | "success" | "sentinel"> & {
     scope: string;
 };
 /**
@@ -422,4 +441,65 @@ declare function initAeonTheme(themeMap?: Record<string, AeonThemeDefinition>):
     mode: AeonColorMode;
 };
 
-export { AEON_PRINCIPLE, AEON_THEME_TRANSITION_CLASS, type AeonActor, type AeonColorMode, type AeonContext, type AeonDataAttrs, type AeonEvent, type AeonPalette, type AeonSnapshot, type AeonStateValue, type AeonThemeDefinition, DEFAULT_COMPACT_MQ, type FieldFace, type LayoutComposition, type LayoutCompositionSpec, type LayoutMode, NORM_PLANE, type NormOrigin, type NormPoint, type NormRect, type RegionLayoutSlot, type ResponsiveLayoutSpec, type ScrollOverflow, type ScrollSnapshot, UI_IS_FUNCTION_OF_STATE, accordionAnatomy, anatomy, appShellAnatomy, applyAeonTheme, asyncAnatomy, avatarAnatomy, barAnatomy, buttonAnatomy, checkboxAnatomy, clampNorm, clientFromNorm, comboboxAnatomy, composerAnatomy, contentAnatomy, conversationAnatomy, dialogAnatomy, entryAnatomy, fieldAnatomy, fieldFace, fieldRegions, getCompactMq, getRegionValue, getScrollSnapshot, identityAnatomy, initAeonTheme, insetNormCluster, isAeonColorMode, isAeonMode, isAeonThemeId, layoutCompositionForMode, layoutModeAttrs, listRowAnatomy, matchLayoutMode, measureElement, menuAnatomy, metricStripAnatomy, navAnatomy, normFromClient, panelAnatomy, partAttrs, partOnlyAttrs, pinInputAnatomy, playSurfaceAnatomy, popoverAnatomy, profileHeaderAnatomy, progressAnatomy, radioGroupAnatomy, regionBoundsForMode, regionLeaf, regionMatches, regionPath, registerAeonThemes, resolveAeonColorMode, resolveRegionRect, runAeonThemeTransition, scopeAttrs, scrollAnatomy, selectAnatomy, separatorAnatomy, sliderAnatomy, stateToAttr, switchAnatomy, syncAeonColorMode, tabsAnatomy, themeSwitcherAnatomy, threadAnatomy, toastAnatomy, tooltipAnatomy };
+/**
+ * Brand → Aeon CSS variable bridge.
+ *
+ * Product apps often already have design tokens. Instead of maintaining a parallel
+ * `--product-*` layer forever, map them onto Aeon’s runtime vars so `@aeon-ui/ui`
+ * recipes and `aeon.css` pick up the brand without forking Panda.
+ */
+
+/** Minimal brand fields — anything omitted gets a safe default. */
+type BrandPaletteInput = {
+    bg: string;
+    surface: string;
+    surfaceRaised?: string;
+    border: string;
+    text: string;
+    muted: string;
+    accent: string;
+    accentDim?: string;
+    danger?: string;
+    dangerDim?: string;
+    gridLine?: string;
+    /** Optional product fonts (applied as --aeon-font / --aeon-font-display). */
+    font?: string;
+    fontDisplay?: string;
+    radius?: string;
+};
+type BrandPalette = Required<Pick<BrandPaletteInput, 'bg' | 'surface' | 'surfaceRaised' | 'border' | 'text' | 'muted' | 'accent' | 'accentDim' | 'danger' | 'dangerDim' | 'gridLine'>> & {
+    font?: string;
+    fontDisplay?: string;
+    radius?: string;
+    focusRing: string;
+};
+/** Normalize a partial brand palette into a full Aeon-compatible palette. */
+declare function normalizeBrandPalette(input: BrandPaletteInput, mode?: AeonColorMode): BrandPalette;
+/** CSS custom properties Aeon recipes already read. */
+declare function brandPaletteToCssVars(palette: BrandPalette): Record<string, string>;
+type ApplyBrandPaletteOptions = {
+    mode?: AeonColorMode;
+    /** Theme id stamped on <html> (default: `brand`). */
+    themeId?: string;
+    /** Persist mode/theme to localStorage (default: false — brand apps usually own prefs). */
+    persist?: boolean;
+    root?: HTMLElement;
+};
+/**
+ * Apply a product brand palette to the document so Aeon CSS vars match the app.
+ * Does not require registering a catalog theme — one call at boot is enough.
+ *
+ * @example
+ * applyBrandPalette({
+ *   bg: '#000', surface: '#0a0a0a', border: '#262626',
+ *   text: '#fafafa', muted: '#a1a1aa', accent: '#57ff97',
+ * }, { mode: 'dark' })
+ */
+declare function applyBrandPalette(input: BrandPaletteInput, options?: ApplyBrandPaletteOptions): BrandPalette;
+/** Serialize palette vars for injecting a `<style>` tag (SSR / non-DOM). */
+declare function brandPaletteToCssText(input: BrandPaletteInput, options?: {
+    mode?: AeonColorMode;
+    selector?: string;
+}): string;
+
+export { AEON_PRINCIPLE, AEON_THEME_TRANSITION_CLASS, type AeonActor, type AeonColorMode, type AeonContext, type AeonDataAttrs, type AeonEvent, type AeonPalette, type AeonSnapshot, type AeonStateValue, type AeonThemeDefinition, type ApplyBrandPaletteOptions, type BrandPalette, type BrandPaletteInput, DEFAULT_COMPACT_MQ, type FieldFace, type LayoutComposition, type LayoutCompositionSpec, type LayoutMode, NORM_PLANE, type NormOrigin, type NormPoint, type NormRect, type RegionLayoutSlot, type ResponsiveLayoutSpec, type ScrollOverflow, type ScrollSnapshot, UI_IS_FUNCTION_OF_STATE, accordionAnatomy, anatomy, appNavAnatomy, appShellAnatomy, applyAeonTheme, applyBrandPalette, asyncAnatomy, avatarAnatomy, barAnatomy, brandPaletteToCssText, brandPaletteToCssVars, buttonAnatomy, checkboxAnatomy, clampNorm, clientFromNorm, comboboxAnatomy, composerAnatomy, contentAnatomy, conversationAnatomy, dialogAnatomy, entryAnatomy, fieldAnatomy, fieldFace, fieldRegions, getCompactMq, getRegionValue, getScrollSnapshot, identityAnatomy, initAeonTheme, insetNormCluster, isAeonColorMode, isAeonMode, isAeonThemeId, layoutCompositionForMode, layoutModeAttrs, listRowAnatomy, matchLayoutMode, measureElement, menuAnatomy, metricStripAnatomy, navAnatomy, normFromClient, normalizeBrandPalette, panelAnatomy, partAttrs, partOnlyAttrs, pinInputAnatomy, playSurfaceAnatomy, popoverAnatomy, profileHeaderAnatomy, progressAnatomy, promptAnatomy, radioGroupAnatomy, regionBoundsForMode, regionLeaf, regionMatches, regionPath, registerAeonThemes, resolveAeonColorMode, resolveRegionRect, runAeonThemeTransition, scopeAttrs, scrollAnatomy, selectAnatomy, separatorAnatomy, sliderAnatomy, stateToAttr, statusBannerAnatomy, switchAnatomy, syncAeonColorMode, tabsAnatomy, themeSwitcherAnatomy, threadAnatomy, toastAnatomy, tooltipAnatomy };

package/packages/core/dist/index.js

@@ -37,6 +37,31 @@ var dialogAnatomy = anatomy("dialog", [
   "description",
   "closeTrigger"
 ]);
+var promptAnatomy = anatomy("prompt", [
+  "root",
+  "eyebrow",
+  "meta",
+  "amount",
+  "actions",
+  "primary",
+  "secondary"
+]);
+var appNavAnatomy = anatomy("appNav", [
+  "root",
+  "rail",
+  "section",
+  "stage",
+  "breadcrumb",
+  "crumb",
+  "back"
+]);
+var statusBannerAnatomy = anatomy("statusBanner", [
+  "root",
+  "copy",
+  "title",
+  "body",
+  "actions"
+]);
 var tabsAnatomy = anatomy("tabs", [
   "root",
   "list",
@@ -557,6 +582,87 @@ function initAeonTheme(themeMap) {
   applyAeonTheme(themeId, mode, themeMap);
   return { themeId, mode };
 }
+
+// src/brand-theme.ts
+var DEFAULT_DANGER = { light: "#dc2626", dark: "#f87171" };
+function focusRing(bg, accent) {
+  return `0 0 0 2px ${bg}, 0 0 0 4px ${accent}`;
+}
+function normalizeBrandPalette(input, mode = "dark") {
+  const danger = input.danger ?? DEFAULT_DANGER[mode];
+  return {
+    bg: input.bg,
+    surface: input.surface,
+    surfaceRaised: input.surfaceRaised ?? input.surface,
+    border: input.border,
+    text: input.text,
+    muted: input.muted,
+    accent: input.accent,
+    accentDim: input.accentDim ?? `${input.accent}2e`,
+    danger,
+    dangerDim: input.dangerDim ?? `${danger}18`,
+    gridLine: input.gridLine ?? (mode === "light" ? "rgba(15, 23, 42, 0.07)" : "rgba(255, 255, 255, 0.05)"),
+    font: input.font,
+    fontDisplay: input.fontDisplay,
+    radius: input.radius,
+    focusRing: focusRing(input.bg, input.accent)
+  };
+}
+function brandPaletteToCssVars(palette) {
+  const vars = {
+    "--colors-aeon-bg": palette.bg,
+    "--colors-aeon-surface": palette.surface,
+    "--colors-aeon-surface-raised": palette.surfaceRaised,
+    "--colors-aeon-border": palette.border,
+    "--colors-aeon-text": palette.text,
+    "--colors-aeon-muted": palette.muted,
+    "--colors-aeon-accent": palette.accent,
+    "--colors-aeon-accent-dim": palette.accentDim,
+    "--colors-aeon-danger": palette.danger,
+    "--colors-aeon-danger-dim": palette.dangerDim,
+    "--shadows-focus-ring": palette.focusRing,
+    "--aeon-grid-line": palette.gridLine
+  };
+  if (palette.font) vars["--aeon-font"] = palette.font;
+  if (palette.fontDisplay) vars["--aeon-font-display"] = palette.fontDisplay;
+  if (palette.radius) vars["--aeon-radius"] = palette.radius;
+  return vars;
+}
+function applyBrandPalette(input, options = {}) {
+  const mode = options.mode ?? "dark";
+  const palette = normalizeBrandPalette(input, mode);
+  if (typeof document === "undefined") return palette;
+  const root = options.root ?? document.documentElement;
+  const themeId = options.themeId ?? "brand";
+  root.dataset.aeonTheme = themeId;
+  root.dataset.aeonMode = mode;
+  root.style.colorScheme = mode;
+  const vars = brandPaletteToCssVars(palette);
+  for (const [key, value] of Object.entries(vars)) {
+    root.style.setProperty(key, value);
+  }
+  const meta = document.querySelector('meta[name="theme-color"]');
+  if (meta) meta.setAttribute("content", palette.bg);
+  if (options.persist) {
+    try {
+      localStorage.setItem("aeon-theme", themeId);
+      localStorage.setItem("aeon-mode", mode);
+    } catch {
+    }
+  }
+  return palette;
+}
+function brandPaletteToCssText(input, options = {}) {
+  const mode = options.mode ?? "dark";
+  const palette = normalizeBrandPalette(input, mode);
+  const vars = brandPaletteToCssVars(palette);
+  const body = Object.entries(vars).map(([k, v]) => `  ${k}: ${v};`).join("\n");
+  const selector = options.selector ?? "html";
+  return `${selector} {
+  color-scheme: ${mode};
+${body}
+}`;
+}
 export {
   AEON_PRINCIPLE,
   AEON_THEME_TRANSITION_CLASS,
@@ -565,11 +671,15 @@ export {
   UI_IS_FUNCTION_OF_STATE,
   accordionAnatomy,
   anatomy,
+  appNavAnatomy,
   appShellAnatomy,
   applyAeonTheme,
+  applyBrandPalette,
   asyncAnatomy,
   avatarAnatomy,
   barAnatomy,
+  brandPaletteToCssText,
+  brandPaletteToCssVars,
   buttonAnatomy,
   checkboxAnatomy,
   clampNorm,
@@ -602,6 +712,7 @@ export {
   metricStripAnatomy,
   navAnatomy,
   normFromClient,
+  normalizeBrandPalette,
   panelAnatomy,
   partAttrs,
   partOnlyAttrs,
@@ -610,6 +721,7 @@ export {
   popoverAnatomy,
   profileHeaderAnatomy,
   progressAnatomy,
+  promptAnatomy,
   radioGroupAnatomy,
   regionBoundsForMode,
   regionLeaf,
@@ -625,6 +737,7 @@ export {
   separatorAnatomy,
   sliderAnatomy,
   stateToAttr,
+  statusBannerAnatomy,
   switchAnatomy,
   syncAeonColorMode,
   tabsAnatomy,

package/packages/core/src/anatomy.ts

@@ -40,6 +40,44 @@ export const dialogAnatomy = anatomy('dialog', [
   'closeTrigger',
 ] as const)
 
+/**
+ * Prompt — confirm / permission / update-style dialog on top of Dialog.
+ * Universal parts: eyebrow, meta, amount, actions (primary + secondary).
+ */
+export const promptAnatomy = anatomy('prompt', [
+  'root',
+  'eyebrow',
+  'meta',
+  'amount',
+  'actions',
+  'primary',
+  'secondary',
+] as const)
+
+/**
+ * AppNav — section + detail stack (list→detail, settings drill-in).
+ */
+export const appNavAnatomy = anatomy('appNav', [
+  'root',
+  'rail',
+  'section',
+  'stage',
+  'breadcrumb',
+  'crumb',
+  'back',
+] as const)
+
+/**
+ * StatusBanner — non-blocking top-of-app notice (update ready, syncing, offline).
+ */
+export const statusBannerAnatomy = anatomy('statusBanner', [
+  'root',
+  'copy',
+  'title',
+  'body',
+  'actions',
+] as const)
+
 export const tabsAnatomy = anatomy('tabs', [
   'root',
   'list',

package/packages/core/src/brand-theme.ts

@@ -0,0 +1,172 @@
+/**
+ * Brand → Aeon CSS variable bridge.
+ *
+ * Product apps often already have design tokens. Instead of maintaining a parallel
+ * `--product-*` layer forever, map them onto Aeon’s runtime vars so `@aeon-ui/ui`
+ * recipes and `aeon.css` pick up the brand without forking Panda.
+ */
+import type { AeonColorMode } from './theme.js'
+
+/** Minimal brand fields — anything omitted gets a safe default. */
+export type BrandPaletteInput = {
+  bg: string
+  surface: string
+  surfaceRaised?: string
+  border: string
+  text: string
+  muted: string
+  accent: string
+  accentDim?: string
+  danger?: string
+  dangerDim?: string
+  gridLine?: string
+  /** Optional product fonts (applied as --aeon-font / --aeon-font-display). */
+  font?: string
+  fontDisplay?: string
+  radius?: string
+}
+
+export type BrandPalette = Required<
+  Pick<
+    BrandPaletteInput,
+    | 'bg'
+    | 'surface'
+    | 'surfaceRaised'
+    | 'border'
+    | 'text'
+    | 'muted'
+    | 'accent'
+    | 'accentDim'
+    | 'danger'
+    | 'dangerDim'
+    | 'gridLine'
+  >
+> & {
+  font?: string
+  fontDisplay?: string
+  radius?: string
+  focusRing: string
+}
+
+const DEFAULT_DANGER = { light: '#dc2626', dark: '#f87171' } as const
+
+function focusRing(bg: string, accent: string) {
+  return `0 0 0 2px ${bg}, 0 0 0 4px ${accent}`
+}
+
+/** Normalize a partial brand palette into a full Aeon-compatible palette. */
+export function normalizeBrandPalette(
+  input: BrandPaletteInput,
+  mode: AeonColorMode = 'dark',
+): BrandPalette {
+  const danger = input.danger ?? DEFAULT_DANGER[mode]
+  return {
+    bg: input.bg,
+    surface: input.surface,
+    surfaceRaised: input.surfaceRaised ?? input.surface,
+    border: input.border,
+    text: input.text,
+    muted: input.muted,
+    accent: input.accent,
+    accentDim: input.accentDim ?? `${input.accent}2e`,
+    danger,
+    dangerDim: input.dangerDim ?? `${danger}18`,
+    gridLine:
+      input.gridLine ??
+      (mode === 'light' ? 'rgba(15, 23, 42, 0.07)' : 'rgba(255, 255, 255, 0.05)'),
+    font: input.font,
+    fontDisplay: input.fontDisplay,
+    radius: input.radius,
+    focusRing: focusRing(input.bg, input.accent),
+  }
+}
+
+/** CSS custom properties Aeon recipes already read. */
+export function brandPaletteToCssVars(palette: BrandPalette): Record<string, string> {
+  const vars: Record<string, string> = {
+    '--colors-aeon-bg': palette.bg,
+    '--colors-aeon-surface': palette.surface,
+    '--colors-aeon-surface-raised': palette.surfaceRaised,
+    '--colors-aeon-border': palette.border,
+    '--colors-aeon-text': palette.text,
+    '--colors-aeon-muted': palette.muted,
+    '--colors-aeon-accent': palette.accent,
+    '--colors-aeon-accent-dim': palette.accentDim,
+    '--colors-aeon-danger': palette.danger,
+    '--colors-aeon-danger-dim': palette.dangerDim,
+    '--shadows-focus-ring': palette.focusRing,
+    '--aeon-grid-line': palette.gridLine,
+  }
+  if (palette.font) vars['--aeon-font'] = palette.font
+  if (palette.fontDisplay) vars['--aeon-font-display'] = palette.fontDisplay
+  if (palette.radius) vars['--aeon-radius'] = palette.radius
+  return vars
+}
+
+export type ApplyBrandPaletteOptions = {
+  mode?: AeonColorMode
+  /** Theme id stamped on <html> (default: `brand`). */
+  themeId?: string
+  /** Persist mode/theme to localStorage (default: false — brand apps usually own prefs). */
+  persist?: boolean
+  root?: HTMLElement
+}
+
+/**
+ * Apply a product brand palette to the document so Aeon CSS vars match the app.
+ * Does not require registering a catalog theme — one call at boot is enough.
+ *
+ * @example
+ * applyBrandPalette({
+ *   bg: '#000', surface: '#0a0a0a', border: '#262626',
+ *   text: '#fafafa', muted: '#a1a1aa', accent: '#57ff97',
+ * }, { mode: 'dark' })
+ */
+export function applyBrandPalette(
+  input: BrandPaletteInput,
+  options: ApplyBrandPaletteOptions = {},
+): BrandPalette {
+  const mode = options.mode ?? 'dark'
+  const palette = normalizeBrandPalette(input, mode)
+  if (typeof document === 'undefined') return palette
+
+  const root = options.root ?? document.documentElement
+  const themeId = options.themeId ?? 'brand'
+  root.dataset.aeonTheme = themeId
+  root.dataset.aeonMode = mode
+  root.style.colorScheme = mode
+
+  const vars = brandPaletteToCssVars(palette)
+  for (const [key, value] of Object.entries(vars)) {
+    root.style.setProperty(key, value)
+  }
+
+  const meta = document.querySelector('meta[name="theme-color"]')
+  if (meta) meta.setAttribute('content', palette.bg)
+
+  if (options.persist) {
+    try {
+      localStorage.setItem('aeon-theme', themeId)
+      localStorage.setItem('aeon-mode', mode)
+    } catch {
+      /* private mode */
+    }
+  }
+
+  return palette
+}
+
+/** Serialize palette vars for injecting a `<style>` tag (SSR / non-DOM). */
+export function brandPaletteToCssText(
+  input: BrandPaletteInput,
+  options: { mode?: AeonColorMode; selector?: string } = {},
+): string {
+  const mode = options.mode ?? 'dark'
+  const palette = normalizeBrandPalette(input, mode)
+  const vars = brandPaletteToCssVars(palette)
+  const body = Object.entries(vars)
+    .map(([k, v]) => `  ${k}: ${v};`)
+    .join('\n')
+  const selector = options.selector ?? 'html'
+  return `${selector} {\n  color-scheme: ${mode};\n${body}\n}`
+}

package/packages/core/src/index.ts

@@ -6,3 +6,4 @@ export * from './types.js'
 export * from './scroll.js'
 export * from './layout.js'
 export * from './theme.js'
+export * from './brand-theme.js'

package/packages/panda/aeon.css

@@ -5,3 +5,4 @@
 @import './theme-runtime.css';
 @import './src/theme/scrollbars.css';
 @import './src/theme/chrome.css';
+@import './src/theme/consumer-shell.css';