origam 2.5.0 → 2.6.1

package/dist/src/themes/origam.theme.d.ts

@@ -0,0 +1,4 @@
+import type { IOrigamTheme } from '../interfaces';
+export declare const origamLightTheme: IOrigamTheme;
+export declare const origamDarkTheme: IOrigamTheme;
+export declare const origamTheme: IOrigamTheme[];

package/dist/src/themes/origam.theme.js

@@ -0,0 +1,379 @@
+export const origamLightTheme = {
+  label: "Origam",
+  description: "Calm, neutral surfaces with a single violet accent \u2014 the default origam identity.",
+  vars: {
+    color: {
+      surface: {
+        default: "#ffffff",
+        raised: "#fafafa",
+        sunken: "#f5f5f5",
+        overlay: "#f5f5f5",
+        disabled: "#e6e6e6"
+      },
+      text: {
+        primary: "#0a0a0a",
+        secondary: "#525252",
+        tertiary: "#737373",
+        disabled: "#a3a3a3",
+        inverse: "#ffffff",
+        onColor: "#ffffff",
+        ink: "#0a0a0a"
+      },
+      action: {
+        primary: {
+          bg: "#7c3aed",
+          bgHover: "#6d28d9",
+          bgDisabled: "#e6e6e6",
+          bgSubtle: "rgba(124, 58, 237, 0.10)",
+          fg: "#ffffff",
+          fgDisabled: "#a3a3a3",
+          fgSubtle: "#6d28d9"
+        },
+        secondary: {
+          bg: "#f5f5f5",
+          bgHover: "#e6e6e6",
+          bgDisabled: "#fafafa",
+          fg: "#171717",
+          fgDisabled: "#a3a3a3"
+        },
+        ghost: {
+          bg: "rgba(0, 0, 0, 0)",
+          bgHover: "rgba(0, 0, 0, 0.06)",
+          bgDisabled: "rgba(0, 0, 0, 0)",
+          fg: "#7c3aed",
+          fgDisabled: "#a3a3a3"
+        }
+      },
+      border: {
+        default: "rgba(0, 0, 0, 0.08)",
+        subtle: "rgba(0, 0, 0, 0.04)",
+        "subtle-alpha": "rgba(0, 0, 0, 0.08)",
+        strong: "rgba(0, 0, 0, 0.16)",
+        ghost: "rgba(0, 0, 0, 0.08)",
+        focus: "#7c3aed"
+      },
+      feedback: {
+        danger: { bg: "#dc2626", bgSubtle: "rgba(220, 38, 38, 0.08)", fg: "#ffffff", fgSubtle: "#b91c1c", border: "#dc2626" },
+        info: { bg: "#2563eb", bgSubtle: "rgba(37, 99, 235, 0.08)", fg: "#ffffff", fgSubtle: "#1d4ed8", border: "#2563eb" },
+        success: { bg: "#16a34a", bgSubtle: "rgba(22, 163, 74, 0.08)", fg: "#ffffff", fgSubtle: "#15803d", border: "#16a34a" },
+        warning: { bg: "#d97706", bgSubtle: "rgba(217, 119, 6, 0.08)", fg: "#ffffff", fgSubtle: "#b45309", border: "#d97706" }
+      }
+    },
+    rounded: {
+      none: "0px",
+      xs: "2px",
+      sm: "4px",
+      md: "8px",
+      lg: "12px",
+      xl: "16px",
+      "2xl": "24px",
+      full: "9999px"
+    },
+    border: {
+      width: { "0": "0px", thin: "1px", "2": "2px", "4": "4px" },
+      style: { solid: "solid", dashed: "dashed", dotted: "dotted" }
+    },
+    typo: {
+      family: {
+        sans: "Inter, 'Helvetica Neue', Arial, sans-serif",
+        serif: "Georgia, 'Times New Roman', serif",
+        mono: "'JetBrains Mono', 'Fira Code', monospace"
+      },
+      size: {
+        xs: "0.625rem",
+        sm: "0.75rem",
+        md: "0.875rem",
+        lg: "1rem",
+        xl: "1.125rem",
+        "2xl": "1.25rem",
+        "3xl": "1.5rem",
+        "4xl": "1.875rem",
+        "5xl": "2.25rem"
+      },
+      weight: { regular: 400, medium: 500, semibold: 600, bold: 700 },
+      lineHeight: { none: 1, tight: 1.25, snug: 1.375, normal: 1.5, relaxed: 1.625, loose: 2 },
+      letterSpacing: {
+        tight: "-0.025em",
+        normal: "0em",
+        wide: "0.0094em",
+        wider: "0.0125em",
+        widest: "0.0893em"
+      }
+    },
+    shadow: {
+      none: "0px 0px 0px 0px rgba(0,0,0,0)",
+      xs: "0px 1px 2px 0px rgba(0,0,0,0.05)",
+      sm: "0px 1px 3px 0px rgba(0,0,0,0.1), 0px 1px 2px -1px rgba(0,0,0,0.1)",
+      md: "0px 6px 24px 0px rgba(0,0,0,0.05), 0px 0px 0px 1px rgba(0,0,0,0.08)",
+      lg: "0px 5px 5px -3px rgba(0,0,0,0.2), 0px 8px 10px 1px rgba(0,0,0,0.14), 0px 3px 14px 2px rgba(0,0,0,0.12)",
+      xl: "0px 11px 15px -7px rgba(0,0,0,0.2), 0px 24px 38px 3px rgba(0,0,0,0.14), 0px 9px 46px 8px rgba(0,0,0,0.12)",
+      "btn-primary": "rgba(255, 255, 255, 0.20) 0px 1px 0px 0px inset, rgba(124, 58, 237, 0.50) 0px 8px 24px -8px",
+      "btn-secondary": "none",
+      "card-elevated": "0 1px 3px rgba(0, 0, 0, 0.04), 0 8px 24px -16px rgba(0, 0, 0, 0.18)",
+      "glow-primary": "inset 0 1px 0 rgba(255, 255, 255, 0.2), 0 8px 24px -8px rgba(124, 58, 237, 0.5)"
+    },
+    spacing: {
+      "0": "0px",
+      "1": "4px",
+      "2": "8px",
+      "3": "12px",
+      "4": "16px",
+      "5": "20px",
+      "6": "24px",
+      "8": "32px",
+      "10": "40px",
+      "12": "48px",
+      "14": "56px",
+      "16": "64px",
+      "20": "80px"
+    },
+    motion: {
+      duration: {
+        instant: "0ms",
+        fast: "100ms",
+        normal: "150ms",
+        medium: "200ms",
+        slow: "280ms",
+        xslow: "400ms"
+      },
+      easing: {
+        linear: "cubic-bezier(0, 0, 1, 1)",
+        standard: "cubic-bezier(0.4, 0, 0.2, 1)",
+        accelerate: "cubic-bezier(0.4, 0, 1, 1)",
+        decelerate: "cubic-bezier(0, 0, 0.2, 1)",
+        sharp: "cubic-bezier(0.4, 0, 0.6, 1)"
+      }
+    }
+  },
+  cssVars: {},
+  components: {
+    "origam-alert": { tag: "div", density: "default" },
+    "origam-audio": { tag: "article", variant: "expanded", position: "relative" },
+    "origam-avatar": { tag: "div", size: "default", rounded: "lg", color: "primary" },
+    "origam-badge": { tag: "div", location: "top right" },
+    "origam-blockquote": { tag: "blockquote", variant: "default" },
+    "origam-bottom-nav": { tag: "nav", position: "start" },
+    "origam-bracket": { tag: "div", variant: "single-elimination", color: "primary" },
+    "origam-breadcrumb": { tag: "nav", density: "default" },
+    "origam-btn": { variant: "text", size: "small" },
+    "origam-btn-group": { variant: "text", size: "small" },
+    "origam-btn-toggle": { variant: "text", size: "small" },
+    "origam-card": { tag: "div", density: "default", rounded: "lg", border: true, flat: true },
+    "origam-checkbox": { density: "default" },
+    "origam-chip": { size: "small", variant: "outlined", color: "primary", pill: true, border: true, borderColor: "var(--origam-color__action--primary---bg)" },
+    "origam-clipboard": { tag: "span" },
+    "origam-code": { tag: "figure", rounded: "lg", compact: true },
+    "origam-color-picker-field": { density: "default", border: true, rounded: true },
+    "origam-confirm-wrapper": { density: "default" },
+    "origam-contextual-menu": { location: "right" },
+    "origam-counter": { tag: "div" },
+    "origam-data-table": { tag: "div", density: "default" },
+    "origam-date-picker-field": { density: "default", border: true, rounded: true },
+    "origam-divider": { color: "var(--origam-color__border---default)" },
+    "origam-drawer": { tag: "nav", location: "left" },
+    "origam-empty-state": { size: "md", align: "center" },
+    "origam-field": { variant: "outlined", density: "default" },
+    "origam-file-field": { density: "default", border: true, rounded: true },
+    "origam-grid": { gap: "1rem", tag: "ul" },
+    "origam-grid-item": { tag: "li" },
+    "origam-input": { density: "default" },
+    "origam-kbd": { variant: "outlined" },
+    "origam-list": { tag: "div", density: "compact" },
+    "origam-list-item": { density: "compact" },
+    "origam-loader": { tag: "span" },
+    "origam-main": { tag: "main" },
+    "origam-masonry": { tag: "div", gap: "md", align: "top" },
+    "origam-menu": { location: "bottom" },
+    "origam-messages": { tag: "div", density: "default" },
+    "origam-number-field": { border: true, rounded: true },
+    "origam-number-format": { tag: "span" },
+    "origam-overlay": { location: "bottom" },
+    "origam-pagination": { tag: "div" },
+    "origam-parallax": { tag: "div" },
+    "origam-password-field": { density: "default", rounded: true },
+    "origam-progress": { tag: "div", size: "default" },
+    "origam-qr-code": { tag: "div", color: "currentColor" },
+    "origam-rating-field": { tag: "div", size: "default" },
+    "origam-select": { border: true, rounded: true, variant: "outlined", density: "compact" },
+    "origam-sheet": { border: true, borderColor: "var(--origam-color__border---default)" },
+    "origam-skeleton": { variant: "text", rounded: "sm" },
+    "origam-slider-field": { variant: "field" },
+    "origam-snackbar": { location: "bottom", border: true, rounded: true, elevation: 1 },
+    "origam-stepper": { size: "default" },
+    "origam-switch": { density: "compact" },
+    "origam-system-bar": { tag: "div" },
+    "origam-table": { tag: "div", border: true, rounded: "lg" },
+    "origam-tabs": { tag: "div", variant: "default" },
+    "origam-text-field": { rounded: "lg", variant: "outlined", density: "compact" },
+    "origam-text-mask": { tag: "span", align: "left" },
+    "origam-textarea-field": { density: "default", rounded: true },
+    "origam-theme-provider": { tag: "div" },
+    "origam-timeline": { tag: "div" },
+    "origam-title": { tag: "h2" },
+    "origam-toolbar": { tag: "header", density: "default" },
+    "origam-tooltip": { location: "right" },
+    "origam-treeview": { density: "default", size: "default" },
+    "origam-watermark": { tag: "div", color: "currentColor" },
+    "origam-window": { tag: "div" },
+    "origam-calendar": { rounded: "lg", density: "compact", border: true },
+    "origam-chart": { rounded: "lg" },
+    "origam-color-picker": { rounded: "lg", border: true },
+    "origam-data-list": { rounded: "lg", density: "compact", border: true },
+    "origam-date-picker": { rounded: "lg", border: true },
+    "origam-expansion-panel": { rounded: "md", density: "compact", border: true },
+    "origam-otp-input-field": { variant: "outlined" },
+    "origam-radio": { density: "compact" },
+    "origam-selection-control": { density: "compact" }
+  }
+};
+export const origamDarkTheme = {
+  mode: "dark",
+  label: "Origam",
+  description: "Calm, neutral surfaces with a single violet accent \u2014 the default origam identity.",
+  vars: {
+    color: {
+      surface: {
+        default: "#0a0a0a",
+        raised: "#0e0e0e",
+        sunken: "#171717",
+        overlay: "#0e0e0e",
+        disabled: "#262626"
+      },
+      text: {
+        primary: "#fafafa",
+        secondary: "#a3a3a3",
+        tertiary: "#737373",
+        disabled: "#525252",
+        inverse: "#0a0a0a",
+        onColor: "#ffffff",
+        ink: "#fafafa"
+      },
+      action: {
+        primary: {
+          bg: "#8b5cf6",
+          bgHover: "#7c3aed",
+          bgDisabled: "#262626",
+          bgSubtle: "rgba(124, 58, 237, 0.14)",
+          fg: "#ffffff",
+          fgDisabled: "#525252",
+          fgSubtle: "#c4b5fd"
+        },
+        secondary: {
+          bg: "#262626",
+          bgHover: "#404040",
+          bgDisabled: "#171717",
+          fg: "#fafafa",
+          fgDisabled: "#525252"
+        },
+        ghost: {
+          bg: "rgba(0, 0, 0, 0)",
+          bgHover: "rgba(255, 255, 255, 0.06)",
+          bgDisabled: "rgba(0, 0, 0, 0)",
+          fg: "#c4b5fd",
+          fgDisabled: "#525252"
+        }
+      },
+      border: {
+        default: "rgba(255, 255, 255, 0.08)",
+        subtle: "rgba(255, 255, 255, 0.04)",
+        "subtle-alpha": "rgba(255, 255, 255, 0.08)",
+        strong: "rgba(255, 255, 255, 0.16)",
+        ghost: "rgba(255, 255, 255, 0.08)",
+        focus: "#a78bfa"
+      },
+      feedback: {
+        danger: { bg: "#dc2626", bgSubtle: "rgba(220, 38, 38, 0.12)", fg: "#ffffff", fgSubtle: "#f87171", border: "#f87171" },
+        info: { bg: "#2563eb", bgSubtle: "rgba(37, 99, 235, 0.12)", fg: "#ffffff", fgSubtle: "#60a5fa", border: "#60a5fa" },
+        success: { bg: "#16a34a", bgSubtle: "rgba(22, 163, 74, 0.12)", fg: "#ffffff", fgSubtle: "#6ee7b7", border: "#6ee7b7" },
+        warning: { bg: "#d97706", bgSubtle: "rgba(217, 119, 6, 0.12)", fg: "#ffffff", fgSubtle: "#fbbf24", border: "#fbbf24" }
+      }
+    },
+    shadow: {
+      "btn-primary": "rgba(255, 255, 255, 0.08) 0px 1px 0px 0px inset, rgba(139, 92, 246, 0.50) 0px 8px 24px -8px",
+      "btn-secondary": "none",
+      "card-elevated": "inset 0 1px 0 rgba(255, 255, 255, 0.03), 0 8px 24px -16px rgba(0, 0, 0, 0.6)",
+      "glow-primary": "inset 0 1px 0 rgba(255, 255, 255, 0.15), 0 8px 24px -8px rgba(139, 92, 246, 0.5)"
+    }
+  },
+  cssVars: {},
+  components: {
+    "origam-alert": { tag: "div", density: "default" },
+    "origam-audio": { tag: "article", variant: "expanded", position: "relative" },
+    "origam-avatar": { tag: "div", size: "default", rounded: "lg", color: "primary" },
+    "origam-badge": { tag: "div", location: "top right" },
+    "origam-blockquote": { tag: "blockquote", variant: "default" },
+    "origam-bottom-nav": { tag: "nav", position: "start" },
+    "origam-bracket": { tag: "div", variant: "single-elimination", color: "primary" },
+    "origam-breadcrumb": { tag: "nav", density: "default" },
+    "origam-btn": { variant: "text", size: "small" },
+    "origam-btn-group": { variant: "text", size: "small" },
+    "origam-btn-toggle": { variant: "text", size: "small" },
+    "origam-card": { tag: "div", density: "default", rounded: "lg", border: true, flat: true },
+    "origam-checkbox": { density: "default" },
+    "origam-chip": { size: "small", variant: "outlined", color: "primary", pill: true, border: true, borderColor: "var(--origam-color__action--primary---bg)" },
+    "origam-clipboard": { tag: "span" },
+    "origam-code": { tag: "figure", rounded: "lg", compact: true },
+    "origam-color-picker-field": { density: "default", border: true, rounded: true },
+    "origam-confirm-wrapper": { density: "default" },
+    "origam-contextual-menu": { location: "right" },
+    "origam-counter": { tag: "div" },
+    "origam-data-table": { tag: "div", density: "default" },
+    "origam-date-picker-field": { density: "default", border: true, rounded: true },
+    "origam-divider": { color: "var(--origam-color__border---default)" },
+    "origam-drawer": { tag: "nav", location: "left" },
+    "origam-empty-state": { size: "md", align: "center" },
+    "origam-field": { variant: "outlined", density: "default" },
+    "origam-file-field": { density: "default", border: true, rounded: true },
+    "origam-grid": { gap: "1rem", tag: "ul" },
+    "origam-grid-item": { tag: "li" },
+    "origam-input": { density: "default" },
+    "origam-kbd": { variant: "outlined" },
+    "origam-list": { tag: "div", density: "compact" },
+    "origam-list-item": { density: "compact" },
+    "origam-loader": { tag: "span" },
+    "origam-main": { tag: "main" },
+    "origam-masonry": { tag: "div", gap: "md", align: "top" },
+    "origam-menu": { location: "bottom" },
+    "origam-messages": { tag: "div", density: "default" },
+    "origam-number-field": { border: true, rounded: true },
+    "origam-number-format": { tag: "span" },
+    "origam-overlay": { location: "bottom" },
+    "origam-pagination": { tag: "div" },
+    "origam-parallax": { tag: "div" },
+    "origam-password-field": { density: "default", rounded: true },
+    "origam-progress": { tag: "div", size: "default" },
+    "origam-qr-code": { tag: "div", color: "currentColor" },
+    "origam-rating-field": { tag: "div", size: "default" },
+    "origam-select": { border: true, rounded: true, variant: "outlined", density: "compact" },
+    "origam-sheet": { border: true, borderColor: "var(--origam-color__border---default)" },
+    "origam-skeleton": { variant: "text", rounded: "sm" },
+    "origam-slider-field": { variant: "field" },
+    "origam-snackbar": { location: "bottom", border: true, rounded: true, elevation: 1 },
+    "origam-stepper": { size: "default" },
+    "origam-switch": { density: "compact" },
+    "origam-system-bar": { tag: "div" },
+    "origam-table": { tag: "div", border: true, rounded: "lg" },
+    "origam-tabs": { tag: "div", variant: "default" },
+    "origam-text-field": { rounded: "lg", variant: "outlined", density: "compact" },
+    "origam-text-mask": { tag: "span", align: "left" },
+    "origam-textarea-field": { density: "default", rounded: true },
+    "origam-theme-provider": { tag: "div" },
+    "origam-timeline": { tag: "div" },
+    "origam-title": { tag: "h2" },
+    "origam-toolbar": { tag: "header", density: "default" },
+    "origam-tooltip": { location: "right" },
+    "origam-treeview": { density: "default", size: "default" },
+    "origam-watermark": { tag: "div", color: "currentColor" },
+    "origam-window": { tag: "div" },
+    "origam-calendar": { rounded: "lg", density: "compact", border: true },
+    "origam-chart": { rounded: "lg" },
+    "origam-color-picker": { rounded: "lg", border: true },
+    "origam-data-list": { rounded: "lg", density: "compact", border: true },
+    "origam-date-picker": { rounded: "lg", border: true },
+    "origam-expansion-panel": { rounded: "md", density: "compact", border: true },
+    "origam-otp-input-field": { variant: "outlined" },
+    "origam-radio": { density: "compact" },
+    "origam-selection-control": { density: "compact" }
+  }
+};
+export const origamTheme = [origamLightTheme, origamDarkTheme];

package/dist/src/types/BottomNav/bottom-nav.type.d.ts

@@ -1,2 +1,4 @@
 import { OrigamBottomNav } from '../../components';
+import type { BOTTOM_NAV_POSITION } from '../../enums';
 export type TOrigamBottomNav = InstanceType<typeof OrigamBottomNav>;
+export type TBottomNavPosition = `${BOTTOM_NAV_POSITION}`;

package/dist/src/types/Commons/font-family.type.cjs

@@ -0,0 +1 @@
+"use strict";

package/dist/src/types/Commons/font-family.type.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Font-family token keys (map to `--origam-font__family---{key}`):
+ *   sans (Inter / Helvetica Neue / Arial) · mono (JetBrains Mono / Fira Code) · serif (Georgia / Times New Roman)
+ */
+export type TFontFamily = 'sans' | 'mono' | 'serif';

package/dist/src/types/Commons/font-size.type.cjs

@@ -0,0 +1 @@
+"use strict";

package/dist/src/types/Commons/font-size.type.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Font-size token keys (map to `--origam-font__size---{key}`):
+ *   xs 0.625rem · sm 0.75rem · md 0.875rem · lg 1rem · xl 1.125rem
+ *   2xl 1.25rem · 3xl 1.5rem · 4xl 1.875rem · 5xl 2.25rem
+ */
+export type TFontSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl' | '5xl';

package/dist/src/types/Commons/font-weight.type.cjs

@@ -0,0 +1 @@
+"use strict";

package/dist/src/types/Commons/font-weight.type.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Font-weight token keys (map to `--origam-font__weight---{key}`):
+ *   regular 400 · medium 500 · semibold 600 · bold 700 · extrabold 800 · black 900
+ */
+export type TFontWeight = 'regular' | 'medium' | 'semibold' | 'bold' | 'extrabold' | 'black';

package/dist/src/types/Commons/letter-spacing.type.cjs

@@ -0,0 +1 @@
+"use strict";

package/dist/src/types/Commons/letter-spacing.type.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Letter-spacing token keys (map to `--origam-font__letterSpacing---{key}`):
+ *   tight -0.025em · normal 0em · wide 0.0094em · wider 0.0125em · widest 0.0893em
+ */
+export type TLetterSpacing = 'tight' | 'normal' | 'wide' | 'wider' | 'widest';

package/dist/src/types/Commons/line-height.type.cjs

@@ -0,0 +1 @@
+"use strict";

package/dist/src/types/Commons/line-height.type.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Line-height token keys (map to `--origam-font__lineHeight---{key}`):
+ *   none 1 · tight 1.25 · snug 1.375 · normal 1.5 · relaxed 1.625 · loose 2
+ */
+export type TLineHeight = 'none' | 'tight' | 'snug' | 'normal' | 'relaxed' | 'loose';

package/dist/src/types/Commons/mode.type.d.ts

@@ -1,2 +1,2 @@
 import { MODE } from '../../enums';
-export type TMode = `${MODE}`;
+export type TNavMode = `${MODE}`;

package/dist/src/types/Theme/installed-theme.type.cjs

@@ -0,0 +1 @@
+"use strict";

package/dist/src/types/Theme/installed-theme.type.d.ts

@@ -0,0 +1,31 @@
+import type { TModeResolved } from './theme.type';
+/**
+ * Summary of one installed brand theme, derived from the `IOrigamTheme[]`
+ * objects passed to `createOrigam({ themes })`. Several `IOrigamTheme` objects
+ * may share the same `name` (one per mode); they are collapsed into a single
+ * entry whose `modes` lists every concrete mode that brand was installed for.
+ *
+ * Consumers (e.g. a theme switcher) map over this list instead of hard-coding
+ * the available brands — the list is the single source of truth for "what was
+ * installed".
+ */
+export interface TInstalledTheme {
+    /** Brand name, applied as `data-theme="<name>"`. */
+    name: string;
+    /** Concrete modes this brand ships (`'light'` / `'dark'`). */
+    modes: TModeResolved[];
+    /**
+     * Human-readable label for UI. Defaults to `name` when no installed object
+     * for this brand provided a `label`.
+     */
+    label: string;
+    /** Short description for UI, when an installed object provided one. */
+    description?: string;
+    /** CSS background for a brand swatch preview, when provided. */
+    swatch?: string;
+}
+/**
+ * The full installed-themes list provided by `createOrigam` and read back via
+ * `useInstalledThemes()`.
+ */
+export type TInstalledThemes = TInstalledTheme[];

package/dist/src/types/Theme/semantic-tree.type.cjs

@@ -0,0 +1 @@
+"use strict";

package/dist/src/types/Theme/semantic-tree.type.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Plain, hand-authored semantic tree — the NORMAL way to write an origam theme
+ * (ADR-004 DX). A node is either a bare value (`string | number`) or a nested
+ * group of further nodes. No DTCG `$value` ceremony, no `--origam-*` prefixes:
+ * you write intentions (`surface.default`, `text.secondary`, `action.primary.bg`)
+ * and the DS resolves each leaf path to its `--origam-*` CSS variable through the
+ * shared `tokenPathToCssVar` naming grammar.
+ *
+ * A leaf VALUE is free-form CSS for its slot:
+ *   - a color slot accepts any CSS color OR a gradient
+ *     (`'#171717'`, `'rgb(23,23,23)'`, `'hsl(...)'`, `'linear-gradient(...)'`),
+ *   - a dimension slot accepts any CSS length (`'0.5rem'`, `'8px'`, `0`),
+ *   - a duration/easing slot accepts the matching CSS value (`'200ms'`,
+ *     `'cubic-bezier(.4,0,.2,1)'`).
+ *
+ * Everything is plain JSON — fully serialisable, so a Theme Builder export can
+ * round-trip it without losing fidelity.
+ */
+export type TSemanticLeaf = string | number;
+export interface ISemanticTree {
+    [key: string]: TSemanticLeaf | ISemanticTree;
+}
+/**
+ * Structured token-configuration bucket — THE way to author a theme's global
+ * design tokens (the JSON that generates every global `--origam-*` variable).
+ *
+ * Each key is a friendly token GROUP whose nested tree resolves to the matching
+ * `--origam-*` namespace through the shared naming grammar:
+ *   - `color`   → `--origam-color-*`   (`color.surface.default`, `color.text.primary`, `color.action.primary.bg`, …)
+ *   - `rounded` → `--origam-radius-*`  (`rounded.sm`, `rounded.md`, `rounded.lg`, …)
+ *   - `border`  → `--origam-border-*`  (`border.width.thin`, …)
+ *   - `typo`    → `--origam-font-*`    (`typo.family.sans`, `typo.size.md`, `typo.weight.bold`, …)
+ *   - `shadow`  → `--origam-shadow-*`  (`shadow.sm`, `shadow.md`, …)
+ *   - `spacing` → `--origam-space-*`   (`spacing.4`, `spacing.12`, …)
+ *   - `motion`  → `--origam-motion-*`  (`motion.duration.fast`, `motion.easing.standard`, …)
+ *
+ * A leaf value is free-form CSS for its slot (a color slot also accepts a
+ * gradient). Plain JSON — fully serialisable for Theme-Builder round-trips.
+ */
+export interface IThemeVars {
+    color?: ISemanticTree;
+    rounded?: ISemanticTree;
+    border?: ISemanticTree;
+    typo?: ISemanticTree;
+    shadow?: ISemanticTree;
+    spacing?: ISemanticTree;
+    motion?: ISemanticTree;
+}

package/dist/src/types/Theme/theme.type.d.ts

@@ -1,11 +1,14 @@
 /**
- * Runtime theme name applied to `<html data-theme="…">` (or to a sub-tree
- * via `<OrigamThemeProvider>`).
+ * Runtime theme (brand) name applied to `<html data-theme="…">` (or to a
+ * sub-tree via `<OrigamThemeProvider>`).
  *
- * - `'auto'`  : no `data-theme` attribute set; the browser picks light/dark
- *               from `prefers-color-scheme`.
- * - `'light'` : default light theme.
- * - `'dark'`  : dark theme.
+ * The theme axis carries the **brand** identity (`'default'`, `'brand-a'`,
+ * …). It is orthogonal to the light/dark `mode` axis (`data-mode`).
+ *
+ * - `'auto'`  : no `data-theme` attribute set; children resolve against the
+ *               closest ancestor (or the default brand at document root).
+ * - `'light'` : legacy alias kept for back-compat (was the default brand).
+ * - `'dark'`  : legacy alias kept for back-compat.
  * - any other string is treated as a custom theme (e.g. `'brand-a'`) — the
  *   matching CSS file must be loaded by the consumer.
  */
@@ -16,3 +19,21 @@ export type TTheme = 'auto' | 'light' | 'dark' | (string & {});
  * effective theme (e.g. switching an SVG asset).
  */
 export type TThemeResolved = Exclude<TTheme, 'auto'>;
+/**
+ * Runtime color mode applied to `<html data-mode="…">` (or to a sub-tree
+ * via `<OrigamThemeProvider mode="…">`).
+ *
+ * The mode axis is orthogonal to the brand `theme` axis: any brand can be
+ * rendered in light or dark.
+ *
+ * - `'auto'`  : no `data-mode` attribute set; the browser/tokens pick
+ *               light/dark from `prefers-color-scheme`.
+ * - `'light'` : forced light mode.
+ * - `'dark'`  : forced dark mode.
+ */
+export type TMode = 'auto' | 'light' | 'dark';
+/**
+ * Concrete (resolved) mode — what `data-mode` actually equals after
+ * resolving `'auto'` against `prefers-color-scheme`.
+ */
+export type TModeResolved = Exclude<TMode, 'auto'>;

package/dist/src/types/Theme/token-tree.type.cjs

@@ -0,0 +1 @@
+"use strict";

package/dist/src/types/Theme/token-tree.type.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A fully-resolved theme variable map: CSS custom-property name → value.
+ * This is what `resolveThemeVars` produces and what the `cssVars` escape hatch
+ * accepts. Keys may be supplied with or without the leading `--`; `createOrigam`
+ * normalises them.
+ *
+ *   { '--origam-color__action--primary---bg': '#7c3aed' }
+ *   { 'origam-radius---md': '0.5rem' }
+ */
+export type TThemeVars = Record<string, string | number>;