@moldable-ai/ui 0.2.26 → 0.2.31

package/src/components/ui/toolbar.md

@@ -12,9 +12,9 @@ embedded view.
     <ToolbarDescription>Local workspace</ToolbarDescription>
   </ToolbarContent>
   <ToolbarActions>
-    <Button size="icon-sm" aria-label="New note">
+    <ToolbarIconButton label="New note" tooltip>
       <Plus />
-    </Button>
+    </ToolbarIconButton>
   </ToolbarActions>
 </Toolbar>
 ```
@@ -28,12 +28,18 @@ when there is no useful view context; the remaining toolbar still provides a
 drag surface and a safe home for right-aligned actions.
 
 The `inset` prop defaults to `auto`. Use `none` for a top toolbar that is not
-window chrome, `windowControls` to force the standard control lane, or
-`windowControlsAndButton` when another leading control sits beside the native
-traffic lights. Set `draggable={false}` only for top toolbars that are nested
-inside app content.
+window chrome, `windowControls` to explicitly declare the standard control
+lane, or `windowControlsAndButton` when another leading control sits beside
+the native traffic lights. Set `draggable={false}` only for top toolbars that
+are nested inside app content.
 
 The default toolbar uses `material="regular"`. The `plain` and `panel` variants
 default to `material="none"`; pass a material explicitly only when the toolbar
 actually floats over content. Reserve `material="clear"` for compact controls
 over media or a richly colored canvas.
+
+Use the precomposed controls in
+[`toolbar-controls.md`](./toolbar-controls.md) for native-sized Back, Sidebar,
+Overflow, grouped-action, and editable-title behavior. Keep only closely
+related actions in a shared group; a single capsule containing every command
+does not communicate command hierarchy.

package/src/styles/index.css

@@ -1,5 +1,6 @@
 @import 'tailwindcss';
 @import 'tw-animate-css';
+@import '../tokens/index.css';
 
 @plugin "@tailwindcss/typography";
 
@@ -186,11 +187,17 @@
   --font-sans: var(--font-family-ui);
   --font-mono: var(--font-family-mono);
 
+  --text-10: 10px;
   --text-11: 11px;
+  --text-12: 12px;
   --text-13: 13px;
+  --text-15: 15px;
   --text-16: 16px;
+  --text-17: 17px;
   --text-18: 18px;
+  --text-22: 22px;
   --text-24: 24px;
+  --text-26: 26px;
   --text-ui-display: var(--type-display-size);
   --text-ui-display--line-height: var(--type-display-line-height);
   --text-ui-display--font-weight: var(--type-display-weight);
@@ -232,6 +239,7 @@
   --spacing-control-sm: var(--density-control-height-sm);
   --spacing-control-md: var(--density-control-height-md);
   --spacing-control-lg: var(--density-control-height-lg);
+  --spacing-control-xl: var(--density-control-height-xl);
   --spacing-row: var(--density-row-height);
   --spacing-toolbar: var(--density-toolbar-height);
   --spacing-pane: var(--density-pane-padding);
@@ -241,6 +249,7 @@
   --ease-enter: var(--motion-ease-enter);
   --ease-exit: var(--motion-ease-exit);
   --ease-spring: var(--motion-ease-spring);
+  --shadow-card: var(--material-shadow-card);
   --shadow-panel: var(--material-shadow-panel);
   --shadow-overlay: var(--material-shadow-overlay);
   --shadow-dialog: var(--material-shadow-dialog);
@@ -268,6 +277,10 @@
   --color-control-disabled: var(--control-disabled);
   --color-control-focus: var(--control-focus);
   --color-control-invalid: var(--control-invalid);
+  --color-toolbar-control: var(--toolbar-control-background);
+  --color-toolbar-control-hover: var(--toolbar-control-hover);
+  --color-toolbar-control-pressed: var(--toolbar-control-pressed);
+  --color-toolbar-control-border: var(--toolbar-control-border);
   --color-window-chrome: var(--window-chrome-background);
   --color-window-chrome-foreground: var(--window-chrome-foreground);
   --color-window-chrome-muted: var(--window-chrome-muted-foreground);
@@ -278,6 +291,8 @@
   --color-popover-foreground: var(--popover-foreground);
   --color-primary: var(--primary);
   --color-primary-foreground: var(--primary-foreground);
+  --color-prominent: var(--prominent);
+  --color-prominent-foreground: var(--prominent-foreground);
   --color-secondary: var(--secondary);
   --color-secondary-foreground: var(--secondary-foreground);
   --color-muted: var(--muted);
@@ -718,38 +733,43 @@
     system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
   --font-family-mono: ui-monospace, Menlo, Consolas, monospace;
 
-  --type-display-size: var(--text-24);
-  --type-display-line-height: 28px;
-  --type-display-weight: 600;
-  --type-display-tracking: -0.02em;
-  --type-heading-size: var(--text-18);
+  --type-display-size: var(--text-26);
+  --type-display-line-height: 32px;
+  --type-display-weight: 700;
+  --type-display-tracking: 0;
+  --type-heading-size: var(--text-17);
   --type-heading-line-height: 22px;
-  --type-heading-weight: 600;
-  --type-heading-tracking: -0.012em;
-  --type-title-size: var(--text-16);
+  --type-heading-weight: 700;
+  --type-heading-tracking: 0;
+  --type-title-size: var(--text-15);
   --type-title-line-height: 20px;
   --type-title-weight: 600;
-  --type-title-tracking: -0.006em;
+  --type-title-tracking: 0;
   --type-body-size: var(--text-13);
-  --type-body-line-height: 18px;
+  --type-body-line-height: 16px;
   --type-label-size: var(--text-13);
   --type-label-line-height: 16px;
   --type-caption-size: var(--text-11);
   --type-caption-line-height: 14px;
-
-  --density-control-height-xs: 1.5rem;
-  --density-control-height-sm: 1.75rem;
-  --density-control-height-md: 2rem;
-  --density-control-height-lg: 2.25rem;
-  --density-control-gap: 0.3125rem;
+  --type-badge-size: var(--text-11);
+  --type-badge-line-height: 14px;
+
+  --density-control-height-xs: 1rem;
+  --density-control-height-sm: 1.25rem;
+  --density-control-height-md: 1.5rem;
+  --density-control-height-lg: 1.75rem;
+  --density-control-height-xl: 2.25rem;
+  --density-control-gap: 0.25rem;
   --density-control-padding-inline: 0.625rem;
+  --density-badge-height: 1.125rem;
+  --density-badge-padding-inline: 0.375rem;
   --density-row-height: 2rem;
   --density-toolbar-height: 2.375rem;
   --density-pane-padding: 0.625rem;
   --density-section-gap: 0.875rem;
 
-  --shape-control: 10px;
-  --shape-checkbox: 4px;
+  --shape-control: 6px;
+  --shape-checkbox: 5px;
   --shape-popover: 12px;
   --shape-card: 12px;
   --shape-group: 12px;
@@ -769,24 +789,26 @@
   --motion-ease-spring: cubic-bezier(0.22, 1.15, 0.36, 1);
 
   --radius: var(--shape-card);
-  --background: oklch(1 0 0);
-  --foreground: oklch(0.141 0.005 285.823);
-  --card: oklch(1 0 0);
-  --card-foreground: oklch(0.141 0.005 285.823);
-  --popover: oklch(1 0 0);
-  --popover-foreground: oklch(0.141 0.005 285.823);
+  --background: #fff;
+  --foreground: rgb(0 0 0 / 85%);
+  --card: #fff;
+  --card-foreground: rgb(0 0 0 / 85%);
+  --popover: #fff;
+  --popover-foreground: rgb(0 0 0 / 85%);
   --primary: oklch(0.205 0 0);
   --primary-foreground: oklch(0.985 0 0);
-  --secondary: oklch(0.967 0.001 286.375);
-  --secondary-foreground: oklch(0.21 0.006 285.885);
-  --muted: oklch(0.967 0.001 286.375);
-  --muted-foreground: oklch(0.5 0.016 285.938);
-  --accent: oklch(0.967 0.001 286.375);
-  --accent-foreground: oklch(0.21 0.006 285.885);
+  --prominent: #0088ff;
+  --prominent-foreground: #fff;
+  --secondary: rgb(0 0 0 / 8%);
+  --secondary-foreground: rgb(0 0 0 / 85%);
+  --muted: rgb(0 0 0 / 5%);
+  --muted-foreground: rgb(0 0 0 / 50%);
+  --accent: rgb(0 0 0 / 10%);
+  --accent-foreground: rgb(0 0 0 / 85%);
   --destructive: oklch(0.5866 0.1994 31.76);
   --destructive-foreground: oklch(0.985 0 0);
-  --border: oklch(0.92 0.004 286.32);
-  --input: oklch(0.92 0.004 286.32);
+  --border: rgb(0 0 0 / 10%);
+  --input: rgb(0 0 0 / 10%);
   --ring: oklch(0.2 0 0 / 48%);
   --model-effort-blue: #339cff;
   --model-effort-purple: #924ff7;
@@ -851,46 +873,60 @@
   );
   --control-focus: var(--ring);
   --control-invalid: var(--destructive);
-
-  --material-blur-toolbar: 16px;
-  --material-blur-overlay: 20px;
-  --material-saturation: 1.12;
-  --material-regular-fill: color-mix(
+  --toolbar-control-background: rgb(255 255 255 / 42%);
+  --toolbar-control-hover: color-mix(
     in oklch,
-    var(--background) 76%,
-    transparent
+    var(--background) 84%,
+    var(--foreground) 8%
   );
-  --material-regular-fallback: color-mix(
+  --toolbar-control-pressed: color-mix(
     in oklch,
-    var(--background) 94%,
-    var(--foreground) 6%
+    var(--background) 74%,
+    var(--foreground) 14%
   );
+  --toolbar-control-border: rgb(0 0 0 / 10%);
+  --toolbar-control-shadow:
+    inset 0 1px 0 color-mix(in oklch, white 42%, transparent),
+    0 1px 2px oklch(0.15 0.005 285 / 8%);
+
+  --material-blur-toolbar: 6px;
+  --material-blur-overlay: 30px;
+  --material-saturation: 1;
+  --material-ultra-thick-fill: rgb(236 236 236 / 88%);
+  --material-thick-fill: rgb(246 246 246 / 72%);
+  --material-medium-fill: rgb(246 246 246 / 60%);
+  --material-thin-fill: rgb(246 246 246 / 48%);
+  --material-ultra-thin-fill: rgb(246 246 246 / 36%);
+  --material-ultra-thick-fallback: #ececec;
+  --material-thick-fallback: #f6f6f6;
+  --material-medium-fallback: #f6f6f6;
+  --material-thin-fallback: #f6f6f6;
+  --material-ultra-thin-fallback: #f6f6f6;
+  --material-standard-blur: 30px;
+  --material-regular-fill: var(--material-medium-fill);
+  --material-regular-fallback: var(--material-medium-fallback);
   --material-regular-border: color-mix(
     in oklch,
     var(--foreground) 10%,
     transparent
   );
   --material-regular-highlight: oklch(1 0 0 / 42%);
-  --material-regular-blur: 20px;
-  --material-regular-saturation: 1.18;
-  --material-clear-fill: color-mix(
-    in oklch,
-    var(--background) 24%,
-    transparent
-  );
-  --material-clear-fallback: color-mix(
-    in oklch,
-    var(--background) 88%,
-    var(--foreground) 12%
-  );
+  --material-regular-blur: var(--material-standard-blur);
+  --material-regular-saturation: 1;
+  --material-clear-fill: var(--material-ultra-thin-fill);
+  --material-clear-fallback: var(--material-ultra-thin-fallback);
   --material-clear-border: color-mix(
     in oklch,
     var(--foreground) 14%,
     transparent
   );
   --material-clear-highlight: oklch(1 0 0 / 28%);
-  --material-clear-blur: 12px;
-  --material-clear-saturation: 1.24;
+  --material-clear-blur: var(--material-standard-blur);
+  --material-clear-saturation: 1;
+  /* In-flow structure: never map this role to overlay or glass elevation. */
+  --material-shadow-card: 0 1px 2px oklch(0.15 0.005 285 / 6%);
+  --material-shadow-sidebar:
+    0 1px 2px oklch(0.15 0.005 285 / 4%), 0 3px 10px oklch(0.15 0.005 285 / 4%);
   --material-shadow-panel:
     inset 0 0 0 1px var(--separator), 0 1px 2px oklch(0.15 0.005 285 / 5%),
     0 5px 14px oklch(0.15 0.005 285 / 5%);
@@ -952,9 +988,7 @@
  * toolbars retain their density-specific compact sizing.
  */
 :root[data-moldable-display-mode='window'][data-moldable-window-titlebar='app']
-  [data-slot='toolbar'][data-position='top']:not(
-    [data-window-inset='none']
-  ) {
+  [data-slot='toolbar'][data-position='top']:not([data-window-inset='none']) {
   min-height: max(3.25rem, var(--window-titlebar-height, 0px));
   padding-inline-start: max(
     var(--density-control-padding-inline, 0.625rem),
@@ -975,10 +1009,11 @@
 }
 
 :where([data-density='compact']) {
-  --density-control-height-xs: 1.375rem;
-  --density-control-height-sm: 1.75rem;
-  --density-control-height-md: 2rem;
-  --density-control-height-lg: 2.25rem;
+  --density-control-height-xs: 1rem;
+  --density-control-height-sm: 1.25rem;
+  --density-control-height-md: 1.5rem;
+  --density-control-height-lg: 1.75rem;
+  --density-control-height-xl: 2.25rem;
   --density-control-gap: 0.25rem;
   --density-control-padding-inline: 0.625rem;
   --density-row-height: 1.875rem;
@@ -992,6 +1027,7 @@
   --density-control-height-sm: 2.25rem;
   --density-control-height-md: 2.5rem;
   --density-control-height-lg: 2.75rem;
+  --density-control-height-xl: 3rem;
   --density-control-gap: 0.5rem;
   --density-control-padding-inline: 1rem;
   --density-row-height: 2.75rem;
@@ -1001,20 +1037,22 @@
 }
 
 .dark {
-  --background: oklch(0.235 0 0);
-  --foreground: oklch(0.985 0 0);
-  --card: oklch(0.269 0.0018 286.28);
-  --card-foreground: oklch(0.985 0 0);
-  --popover: oklch(0.269 0.0018 286.28);
-  --popover-foreground: oklch(0.985 0 0);
+  --background: #1d1f1f;
+  --foreground: rgb(255 255 255 / 85%);
+  --card: #242424;
+  --card-foreground: rgb(255 255 255 / 85%);
+  --popover: #242424;
+  --popover-foreground: rgb(255 255 255 / 85%);
   --primary: oklch(0.985 0 0);
   --primary-foreground: oklch(0.205 0 0);
-  --secondary: oklch(0.3375 0.0035 286.21);
-  --secondary-foreground: oklch(0.985 0 0);
-  --muted: oklch(0.3375 0.0035 286.21);
-  --muted-foreground: oklch(0.74 0.012 286);
-  --accent: oklch(0.3375 0.0035 286.21);
-  --accent-foreground: oklch(0.985 0 0);
+  --prominent: #0091ff;
+  --prominent-foreground: #fff;
+  --secondary: rgb(255 255 255 / 8%);
+  --secondary-foreground: rgb(255 255 255 / 85%);
+  --muted: rgb(255 255 255 / 5%);
+  --muted-foreground: rgb(255 255 255 / 55%);
+  --accent: rgb(255 255 255 / 10%);
+  --accent-foreground: rgb(255 255 255 / 85%);
   --destructive: oklch(0.704 0.191 22.216);
   --destructive-foreground: oklch(0.985 0 0);
   --border: oklch(1 0 0 / 10%);
@@ -1028,13 +1066,13 @@
   --chart-3: var(--pending);
   --chart-4: var(--neutral);
   --chart-5: var(--accent-foreground);
-  --sidebar: oklch(0.235 0 0);
+  --sidebar: #1b1d1e;
   --sidebar-foreground: oklch(0.985 0 0);
   --sidebar-primary: oklch(0.7145 0.185 45.03);
   --sidebar-primary-foreground: oklch(0.985 0 0);
-  --sidebar-accent: oklch(0.3375 0.0035 286.21);
-  --sidebar-accent-foreground: oklch(0.985 0 0);
-  --sidebar-border: oklch(1 0 0 / 10%);
+  --sidebar-accent: color-mix(in srgb, #0091ff 14%, transparent);
+  --sidebar-accent-foreground: #0091ff;
+  --sidebar-border: #394043;
   --sidebar-ring: var(--ring);
   --info: oklch(0.72 0.15 250);
   --info-foreground: oklch(0.78 0.11 250);
@@ -1050,30 +1088,30 @@
   --status-stopped: var(--neutral);
   --status-pending: var(--pending);
   --status-error: var(--destructive);
-  --material-regular-fill: color-mix(
-    in oklch,
-    var(--background) 68%,
-    transparent
-  );
-  --material-regular-fallback: color-mix(
-    in oklch,
-    var(--background) 88%,
-    var(--foreground) 12%
-  );
+  --toolbar-control-background: rgb(153 153 153 / 17%);
+  --toolbar-control-border: rgb(255 255 255 / 10%);
+  --material-ultra-thick-fill: rgb(0 0 0 / 50%);
+  --material-thick-fill: rgb(0 0 0 / 40%);
+  --material-medium-fill: rgb(0 0 0 / 29%);
+  --material-thin-fill: rgb(0 0 0 / 20%);
+  --material-ultra-thin-fill: rgb(0 0 0 / 10%);
+  --material-ultra-thick-fallback: #000;
+  --material-thick-fallback: #000;
+  --material-medium-fallback: #000;
+  --material-thin-fallback: #000;
+  --material-ultra-thin-fallback: #000;
+  --material-regular-fill: var(--material-medium-fill);
+  --material-regular-fallback: var(--material-medium-fallback);
   --material-regular-border: oklch(1 0 0 / 14%);
   --material-regular-highlight: oklch(1 0 0 / 12%);
-  --material-clear-fill: color-mix(
-    in oklch,
-    var(--background) 20%,
-    transparent
-  );
-  --material-clear-fallback: color-mix(
-    in oklch,
-    var(--background) 78%,
-    var(--foreground) 22%
-  );
+  --material-clear-fill: var(--material-ultra-thin-fill);
+  --material-clear-fallback: var(--material-ultra-thin-fallback);
   --material-clear-border: oklch(1 0 0 / 18%);
   --material-clear-highlight: oklch(1 0 0 / 10%);
+  /* In-flow structure: never map this role to overlay or glass elevation. */
+  --material-shadow-card: 0 1px 2px oklch(0 0 0 / 24%);
+  --material-shadow-sidebar:
+    0 1px 2px oklch(0 0 0 / 18%), 0 3px 10px oklch(0 0 0 / 12%);
   --material-shadow-panel:
     inset 0 0 0 1px var(--separator), 0 2px 5px oklch(0 0 0 / 28%),
     0 8px 22px oklch(0 0 0 / 22%);
@@ -1132,6 +1170,7 @@
       transparent
     );
     --material-clear-border: var(--separator-strong);
+    --material-shadow-card: none;
     --material-shadow-panel: inset 0 0 0 1px var(--separator-strong);
     --material-shadow-overlay: inset 0 0 0 1px var(--separator-strong);
     --material-shadow-dialog: inset 0 0 0 1px var(--separator-strong);
@@ -1175,6 +1214,7 @@
     transparent
   );
   --material-clear-border: var(--separator-strong);
+  --material-shadow-card: none;
   --material-shadow-panel: inset 0 0 0 1px var(--separator-strong);
   --material-shadow-overlay: inset 0 0 0 1px var(--separator-strong);
   --material-shadow-dialog: inset 0 0 0 1px var(--separator-strong);
@@ -1204,6 +1244,11 @@
     --control-disabled: transparent;
     --control-focus: Highlight;
     --control-invalid: Mark;
+    --toolbar-control-background: Canvas;
+    --toolbar-control-hover: Canvas;
+    --toolbar-control-pressed: Canvas;
+    --toolbar-control-border: ButtonBorder;
+    --toolbar-control-shadow: none;
     --material-regular-fill: Canvas;
     --material-regular-fallback: Canvas;
     --material-regular-border: ButtonBorder;
@@ -1219,6 +1264,7 @@
     --material-blur-toolbar: 0px;
     --material-blur-overlay: 0px;
     --material-saturation: 1;
+    --material-shadow-card: none;
     --material-shadow-panel: none;
     --material-shadow-overlay: none;
     --material-shadow-dialog: none;
@@ -1229,6 +1275,10 @@
 :where([data-transparency='reduced']) {
   --surface-toolbar: var(--background);
   --surface-overlay: var(--popover);
+  --toolbar-control-background: var(--background);
+  --toolbar-control-hover: var(--accent);
+  --toolbar-control-pressed: var(--control-pressed);
+  --toolbar-control-shadow: inset 0 0 0 1px var(--separator);
   --material-regular-fill: var(--material-regular-fallback);
   --material-regular-blur: 0px;
   --material-regular-saturation: 1;
@@ -1244,6 +1294,10 @@
   :root {
     --surface-toolbar: var(--background);
     --surface-overlay: var(--popover);
+    --toolbar-control-background: var(--background);
+    --toolbar-control-hover: var(--accent);
+    --toolbar-control-pressed: var(--control-pressed);
+    --toolbar-control-shadow: inset 0 0 0 1px var(--separator);
     --material-regular-fill: var(--material-regular-fallback);
     --material-regular-blur: 0px;
     --material-regular-saturation: 1;
@@ -1278,8 +1332,6 @@
   .moldable-material {
     --material-active-fill: var(--material-regular-fill);
     --material-active-fallback: var(--material-regular-fallback);
-    --material-active-border: var(--material-regular-border);
-    --material-active-highlight: var(--material-regular-highlight);
     --material-active-blur: var(--material-regular-blur);
     --material-active-saturation: var(--material-regular-saturation);
     --material-active-shadow: none;
@@ -1287,21 +1339,61 @@
     position: relative;
     isolation: isolate;
     background-color: var(--material-active-fallback);
-    border-color: var(--material-active-border);
-    box-shadow:
-      inset 0 1px 0 var(--material-active-highlight),
-      var(--material-active-shadow);
+    box-shadow: var(--material-active-shadow);
   }
 
   .moldable-material[data-material='clear'] {
     --material-active-fill: var(--material-clear-fill);
     --material-active-fallback: var(--material-clear-fallback);
-    --material-active-border: var(--material-clear-border);
-    --material-active-highlight: var(--material-clear-highlight);
     --material-active-blur: var(--material-clear-blur);
     --material-active-saturation: var(--material-clear-saturation);
   }
 
+  .moldable-material[data-material='ultra-thick'] {
+    --material-active-fill: var(--material-ultra-thick-fill);
+    --material-active-fallback: var(--material-ultra-thick-fallback);
+    --material-active-blur: var(--material-standard-blur);
+    --material-active-saturation: 1;
+  }
+
+  .moldable-material[data-material='thick'] {
+    --material-active-fill: var(--material-thick-fill);
+    --material-active-fallback: var(--material-thick-fallback);
+    --material-active-blur: var(--material-standard-blur);
+    --material-active-saturation: 1;
+  }
+
+  .moldable-material[data-material='medium'] {
+    --material-active-fill: var(--material-medium-fill);
+    --material-active-fallback: var(--material-medium-fallback);
+    --material-active-blur: var(--material-standard-blur);
+    --material-active-saturation: 1;
+  }
+
+  .moldable-material[data-material='thin'] {
+    --material-active-fill: var(--material-thin-fill);
+    --material-active-fallback: var(--material-thin-fallback);
+    --material-active-blur: var(--material-standard-blur);
+    --material-active-saturation: 1;
+  }
+
+  .moldable-material[data-material='ultra-thin'] {
+    --material-active-fill: var(--material-ultra-thin-fill);
+    --material-active-fallback: var(--material-ultra-thin-fallback);
+    --material-active-blur: var(--material-standard-blur);
+    --material-active-saturation: 1;
+  }
+
+  :where(
+    [data-slot='button'][data-variant='toolbar'],
+    [data-slot='toolbar-control-group'][data-appearance='chrome']
+  ) {
+    -webkit-backdrop-filter: blur(var(--material-blur-toolbar))
+      saturate(var(--material-saturation));
+    backdrop-filter: blur(var(--material-blur-toolbar))
+      saturate(var(--material-saturation));
+  }
+
   .moldable-material[data-material-elevation='panel'] {
     --material-active-shadow: var(--material-shadow-panel);
   }

package/src/tokens/contracts.ts

@@ -0,0 +1,131 @@
+export type UITheme = 'platform' | 'moldable'
+
+export type UIPlatform = 'macos' | 'windows' | 'web'
+
+export type UIPlatformVersion = string
+
+/**
+ * A component recipe can intentionally come from a different versioned
+ * platform source than the application's base platform pack.
+ *
+ * Public names describe the anatomy an app is choosing. The registry below
+ * records which immutable platform source defines each recipe.
+ */
+export type UISidebarStyle = 'platform' | 'floating' | 'edge-to-edge'
+
+export type PlatformPackId = `${UIPlatform}-${string}`
+
+export interface UIPlatformPack {
+  id: PlatformPackId
+  platform: UIPlatform
+  version: UIPlatformVersion
+  capabilities: {
+    nativeMaterials: boolean
+    nativeWindowChrome: boolean
+    overlayScrollbars: boolean
+  }
+}
+
+export type UIAppearance = 'light' | 'dark' | 'system'
+
+export type ResolvedUIAppearance = Exclude<UIAppearance, 'system'>
+
+export type ControlSize = 'mini' | 'small' | 'medium' | 'large' | 'xl'
+
+export type LayoutDensity = 'compact' | 'regular' | 'comfortable'
+
+export type MaterialThickness =
+  | 'ultra-thick'
+  | 'thick'
+  | 'medium'
+  | 'thin'
+  | 'ultra-thin'
+
+export type MaterialContext = 'content' | 'over-glass'
+
+export type ContrastPreference = 'system' | 'standard' | 'increased'
+
+export type TransparencyPreference = 'system' | 'standard' | 'reduced'
+
+export type MotionPreference = 'system' | 'standard' | 'reduced'
+
+export interface UIPreferences {
+  contrast?: ContrastPreference
+  transparency?: TransparencyPreference
+  motion?: MotionPreference
+}
+
+export const CONTROL_SIZES = [
+  'mini',
+  'small',
+  'medium',
+  'large',
+  'xl',
+] as const satisfies readonly ControlSize[]
+
+export const MATERIAL_THICKNESSES = [
+  'ultra-thick',
+  'thick',
+  'medium',
+  'thin',
+  'ultra-thin',
+] as const satisfies readonly MaterialThickness[]
+
+export const SIDEBAR_STYLES = {
+  platform: {
+    id: 'platform',
+    sourcePlatform: null,
+    sourceVersion: null,
+  },
+  floating: {
+    id: 'floating',
+    sourcePlatform: 'macos',
+    sourceVersion: '26',
+  },
+  'edge-to-edge': {
+    id: 'edge-to-edge',
+    sourcePlatform: 'macos',
+    sourceVersion: '27',
+  },
+} as const satisfies Record<
+  UISidebarStyle,
+  {
+    id: UISidebarStyle
+    sourcePlatform: UIPlatform | null
+    sourceVersion: UIPlatformVersion | null
+  }
+>
+
+export const PLATFORM_PACKS = {
+  'macos-27': {
+    id: 'macos-27',
+    platform: 'macos',
+    version: '27',
+    capabilities: {
+      nativeMaterials: true,
+      nativeWindowChrome: true,
+      overlayScrollbars: true,
+    },
+  },
+  'web-default': {
+    id: 'web-default',
+    platform: 'web',
+    version: 'default',
+    capabilities: {
+      nativeMaterials: false,
+      nativeWindowChrome: false,
+      overlayScrollbars: false,
+    },
+  },
+} as const satisfies Record<string, UIPlatformPack>
+
+export function resolvePlatformPack(
+  platform: UIPlatform,
+  version: UIPlatformVersion,
+): UIPlatformPack {
+  const exact = Object.values(PLATFORM_PACKS).find(
+    (pack) => pack.platform === platform && pack.version === version,
+  )
+
+  return exact ?? PLATFORM_PACKS['web-default']
+}