@praxisui/core 10.0.0-rc.3 → 10.0.0-rc.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praxisui/core",
-  "version": "10.0.0-rc.3",
+  "version": "10.0.0-rc.30",
   "description": "Core library for Praxis UI Workspace: types, tokens, services and utilities shared across @praxisui/* packages.",
   "peerDependencies": {
     "@angular/cdk": "^21.0.0",
@@ -19,6 +19,12 @@
   "license": "Apache-2.0",
   "exports": {
     "./theme-bridge.css": "./theme-bridge.css",
+    "./theming": {
+      "sass": "./theming/_theming.scss",
+      "style": "./theming/_theming.scss",
+      "default": "./theming/_theming.scss"
+    },
+    "./theming/*": "./theming/*",
     "./package.json": {
       "default": "./package.json"
     },
@@ -26,6 +32,10 @@
       "types": "./types/praxisui-core.d.ts",
       "default": "./fesm2022/praxisui-core.mjs"
     },
+    "./schema": {
+      "types": "./types/praxisui-core-schema.d.ts",
+      "default": "./fesm2022/praxisui-core-schema.mjs"
+    },
     "./ai/component-registry.json": {
       "default": "./ai/component-registry.json"
     }
@@ -41,11 +51,13 @@
     "core",
     "design-system",
     "tokens",
+    "theming",
     "widgets",
     "configuration"
   ],
   "sideEffects": [
-    "./theme-bridge.css"
+    "./theme-bridge.css",
+    "./theming/**"
   ],
   "module": "fesm2022/praxisui-core.mjs",
   "typings": "types/praxisui-core.d.ts",

package/theming/README.md

@@ -0,0 +1,63 @@
+# @praxisui/core - Canonical SCSS Theming & Design Token Bridge
+
+This module provides the official Sass mixins and design token bridge for integrating Praxis UI with host applications, design systems (Material Design 3, Tailwind, shadcn/ui, OKLCH tokens), and custom enterprise palettes.
+
+## Features
+
+- **Material Design 3 & Angular Material M3 Bridge**: Automatically derives `--md-sys-color-*` and `--mat-sys-*` tokens.
+- **Praxis Platform Tokens**: Full bridge for `--pdx-material-*`, `--pdx-overlay-*`, `--pdx-page-*`, `--pdx-shell-*`, and `--prx-rich-*`.
+- **Dynamic Color Mixing**: Utilizes modern native CSS `color-mix(in oklab, ...)` for predictable perceptual container/state tinting.
+- **Enterprise Dark Mode**: Declarative `@mixin praxis-dark-theme-overrides` for high-contrast, polished dark surfaces.
+- **Widget Shell & Tooltip Refinements**: Built-in responsive full-screen UX behaviors, solid non-bleeding surfaces, and enterprise-grade tooltip styling.
+
+## Quick Start
+
+### 1. Bundle (All-in-One)
+
+In your global styles (`styles.scss`):
+
+```scss
+@use '@praxisui/core/theming' as praxis;
+
+@include praxis.praxis-theme-bundle();
+```
+
+### 2. Granular / Custom Configuration
+
+If your host defines custom CSS variables or design tokens:
+
+```scss
+@use '@praxisui/core/theming' as praxis;
+
+:root {
+  @include praxis.define-praxis-theme((
+    'primary': var(--primary),
+    'secondary': var(--secondary),
+    'surface': var(--card),
+    'background': var(--background),
+    'foreground': var(--foreground),
+    'border': var(--border),
+    'radius-lg': var(--radius-lg, 12px)
+  ));
+}
+
+.dark {
+  @include praxis.praxis-dark-theme-overrides((
+    'primary': var(--primary),
+    'surface': var(--card),
+    'border': var(--border)
+  ));
+}
+
+// Include UX enhancements for shell dialogs and Material tooltips:
+@include praxis.praxis-shell-styles();
+@include praxis.praxis-tooltip-styles();
+```
+
+## Available Mixins
+
+- `define-praxis-theme($config: ())`: Emits root / light CSS variables.
+- `praxis-dark-theme-overrides($config: ())`: Emits dark mode CSS variable overrides.
+- `praxis-shell-styles()`: Emits fullscreen, backdrop, and expanded widget shell rules.
+- `praxis-tooltip-styles()`: Emits solid surface and high-contrast refinements for Angular Material tooltips.
+- `praxis-theme-bundle($config: (), $dark-config: (), $dark-selector: '.dark')`: Bundles all the above in one declaration.

package/theming/_theming.scss

@@ -0,0 +1,543 @@
+@use 'sass:map';
+
+// =============================================================================
+// Praxis Platform - Canonical SCSS Theming & Design Token Bridge
+// =============================================================================
+
+/// Helper function to retrieve a key from a config map with fallback.
+@function _get-token($config, $key, $fallback) {
+  @if map.has-key($config, $key) {
+    @return map.get($config, $key);
+  }
+  @return $fallback;
+}
+
+/// Emits the canonical Praxis UI tokens for a light or standard theme.
+///
+/// Can be included in `:root`, inside a theme selector (e.g. `.theme-light`),
+/// or at a component container boundary.
+///
+/// @param {Map} $config Optional overrides for theme tokens.
+@mixin define-praxis-theme($config: ()) {
+  $primary: _get-token($config, 'primary', var(--primary, #006a6a));
+  $on-primary: _get-token($config, 'on-primary', var(--primary-foreground, #ffffff));
+  $secondary: _get-token($config, 'secondary', var(--secondary, #4a6363));
+  $on-secondary: _get-token($config, 'on-secondary', var(--secondary-foreground, #ffffff));
+  $tertiary: _get-token($config, 'tertiary', var(--tertiary, var(--cobalt, #4b607c)));
+  $on-tertiary: _get-token($config, 'on-tertiary', var(--tertiary-foreground, #ffffff));
+  $error: _get-token($config, 'error', var(--destructive, var(--error, #ba1a1a)));
+  $on-error: _get-token($config, 'on-error', var(--destructive-foreground, var(--on-error, #ffffff)));
+
+  $surface: _get-token($config, 'surface', var(--card, var(--surface, #fbfcfc)));
+  $background: _get-token($config, 'background', var(--background, #f2f6f5));
+  $foreground: _get-token($config, 'foreground', var(--foreground, #191c1c));
+  $muted: _get-token($config, 'muted', var(--muted, #dae5e3));
+  $muted-foreground: _get-token($config, 'muted-foreground', var(--muted-foreground, #3f4948));
+  $border: _get-token($config, 'border', var(--border, #6f7978));
+
+  $popover: _get-token($config, 'popover', var(--popover, #{$surface}));
+  $popover-foreground: _get-token($config, 'popover-foreground', var(--popover-foreground, #{$foreground}));
+
+  $primary-container: _get-token($config, 'primary-container', color-mix(in oklab, #{$primary} 16%, #{$surface}));
+  $on-primary-container: _get-token($config, 'on-primary-container', #{$primary});
+
+  $secondary-container: _get-token($config, 'secondary-container', color-mix(in oklab, #{$secondary} 30%, #{$surface}));
+  $on-secondary-container: _get-token($config, 'on-secondary-container', #{$foreground});
+
+  $tertiary-container: _get-token($config, 'tertiary-container', color-mix(in oklab, #{$tertiary} 18%, #{$surface}));
+  $on-tertiary-container: _get-token($config, 'on-tertiary-container', #{$tertiary});
+
+  $error-container: _get-token($config, 'error-container', color-mix(in oklab, #{$error} 18%, #{$surface}));
+  $on-error-container: _get-token($config, 'on-error-container', #{$error});
+
+  $surface-lowest: _get-token($config, 'surface-container-lowest', #{$surface});
+  $surface-low: _get-token($config, 'surface-container-low', color-mix(in oklab, #{$surface} 95%, #{$background}));
+  $surface-container: _get-token($config, 'surface-container', color-mix(in oklab, #{$surface} 90%, #{$background}));
+  $surface-high: _get-token($config, 'surface-container-high', color-mix(in oklab, #{$surface} 85%, #{$background}));
+  $surface-highest: _get-token($config, 'surface-container-highest', color-mix(in oklab, #{$surface} 80%, #{$background}));
+
+  $inverse-surface: _get-token($config, 'inverse-surface', oklch(0.24 0.03 260));
+  $inverse-on-surface: _get-token($config, 'inverse-on-surface', oklch(0.98 0.005 240));
+
+  $outline: _get-token($config, 'outline', #{$border});
+  $outline-variant: _get-token($config, 'outline-variant', color-mix(in oklab, #{$outline} 60%, transparent));
+
+  $shadow: _get-token($config, 'shadow', oklch(0.1 0.02 240 / 12%));
+  $scrim: _get-token($config, 'scrim', oklch(0.05 0.01 240 / 45%));
+
+  $elevation-1: _get-token($config, 'elevation-1', var(--shadow-panel, var(--mat-app-elevation-shadow-level1, 0 1px 2px rgba(0, 0, 0, 0.14))));
+  $elevation-2: _get-token($config, 'elevation-2', var(--shadow-panel, var(--mat-app-elevation-shadow-level2, 0 2px 6px rgba(0, 0, 0, 0.16))));
+  $elevation-3: _get-token($config, 'elevation-3', var(--shadow-command, var(--mat-app-elevation-shadow-level3, 0 4px 12px rgba(0, 0, 0, 0.18))));
+
+  $radius-sm: _get-token($config, 'radius-sm', var(--radius-sm, 6px));
+  $radius-lg: _get-token($config, 'radius-lg', var(--radius-lg, 12px));
+  $radius-xl: _get-token($config, 'radius-xl', var(--radius-xl, 20px));
+
+  $font-sans: _get-token($config, 'font-sans', var(--font-sans, inherit));
+  $font-display: _get-token($config, 'font-display', var(--font-display, inherit));
+
+  // 1. Material Design 3 System Color Tokens (--md-sys-color-*)
+  --md-sys-color-primary: #{$primary};
+  --md-sys-color-on-primary: #{$on-primary};
+  --md-sys-color-primary-container: #{$primary-container};
+  --md-sys-color-on-primary-container: #{$on-primary-container};
+
+  --md-sys-color-secondary: #{$secondary};
+  --md-sys-color-on-secondary: #{$on-secondary};
+  --md-sys-color-secondary-container: #{$secondary-container};
+  --md-sys-color-on-secondary-container: #{$on-secondary-container};
+
+  --md-sys-color-tertiary: #{$tertiary};
+  --md-sys-color-on-tertiary: #{$on-tertiary};
+  --md-sys-color-tertiary-container: #{$tertiary-container};
+  --md-sys-color-on-tertiary-container: #{$on-tertiary-container};
+
+  --md-sys-color-error: #{$error};
+  --md-sys-color-on-error: #{$on-error};
+  --md-sys-color-error-container: #{$error-container};
+  --md-sys-color-on-error-container: #{$on-error-container};
+
+  --md-sys-color-surface: #{$surface};
+  --md-sys-color-surface-container-lowest: #{$surface-lowest};
+  --md-sys-color-surface-container-low: #{$surface-low};
+  --md-sys-color-surface-container: #{$surface-container};
+  --md-sys-color-surface-container-high: #{$surface-high};
+  --md-sys-color-surface-container-highest: #{$surface-highest};
+  --md-sys-color-surface-variant: #{$muted};
+
+  --md-sys-color-on-surface: #{$foreground};
+  --md-sys-color-on-surface-variant: #{$muted-foreground};
+
+  --md-sys-color-inverse-surface: #{$inverse-surface};
+  --md-sys-color-inverse-on-surface: #{$inverse-on-surface};
+
+  --md-sys-color-outline: #{$outline};
+  --md-sys-color-outline-variant: #{$outline-variant};
+
+  --md-sys-color-shadow: #{$shadow};
+  --md-sys-color-scrim: #{$scrim};
+
+  --md-sys-elevation-level1: #{$elevation-1};
+  --md-sys-elevation-level2: #{$elevation-2};
+  --md-sys-elevation-level3: #{$elevation-3};
+
+  // 1.1 Angular Material M3 & Tooltip Tokens Bridge (--mat-sys-*, --mat-tooltip-*)
+  --mat-sys-surface: #{$surface};
+  --mat-sys-on-surface: #{$foreground};
+  --mat-sys-surface-container: #{$surface-container};
+  --mat-sys-surface-container-high: #{$surface-high};
+  --mat-sys-surface-variant: #{$muted};
+  --mat-sys-on-surface-variant: #{$muted-foreground};
+  --mat-sys-outline: #{$outline};
+  --mat-sys-outline-variant: #{$outline-variant};
+  --mat-sys-primary: #{$primary};
+  --mat-sys-on-primary: #{$on-primary};
+  --mat-sys-inverse-surface: #{$inverse-surface};
+  --mat-sys-inverse-on-surface: #{$inverse-on-surface};
+  --mat-sys-corner-extra-small: #{$radius-sm};
+  --mat-sys-body-small-font: #{$font-sans};
+  --mat-sys-body-small-size: 12px;
+  --mat-sys-body-small-weight: 500;
+  --mat-sys-body-small-line-height: 16px;
+  --mat-sys-body-small-tracking: 0.01em;
+
+  --mat-tooltip-container-color: var(--mat-sys-inverse-surface);
+  --mat-tooltip-supporting-text-color: var(--mat-sys-inverse-on-surface);
+  --mat-tooltip-container-shape: #{$radius-sm};
+  --mat-tooltip-supporting-text-font: #{$font-sans};
+  --mat-tooltip-supporting-text-size: 12px;
+  --mat-tooltip-supporting-text-weight: 500;
+  --mat-tooltip-supporting-text-line-height: 16px;
+  --mat-tooltip-supporting-text-tracking: 0.01em;
+
+  // 1.2 Angular Material M3 Menu Tokens Bridge (--mat-menu-*)
+  --mat-menu-container-color: var(--card, var(--surface, #{$surface}));
+  --mat-menu-container-shape: var(--radius-md, var(--radius-lg, 14px));
+  --mat-menu-item-label-text-color: #{$foreground};
+  --mat-menu-item-icon-color: #{$muted-foreground};
+  --mat-menu-item-hover-state-layer-color: color-mix(in oklab, #{$primary} 12%, transparent);
+  --mat-menu-item-focus-state-layer-color: color-mix(in oklab, #{$primary} 18%, transparent);
+
+  // 2. Praxis Core Bridge Tokens (--pdx-material-*, --pdx-overlay-*)
+  --pdx-material-surface: #{$surface};
+  --pdx-material-surface-high: #{$surface-container};
+  --pdx-material-on-surface: #{$foreground};
+  --pdx-material-on-surface-muted: #{$muted-foreground};
+  --pdx-material-outline: #{$border};
+  --pdx-material-focus-outline: #{$primary};
+
+  --pdx-overlay-surface: #{$popover};
+  --pdx-overlay-on-surface: #{$popover-foreground};
+  --pdx-overlay-on-surface-muted: #{$muted-foreground};
+  --pdx-overlay-state-layer: color-mix(in oklab, #{$primary} 10%, transparent);
+
+  // 3. Dynamic Widget Page & Widget Shell Tokens (--pdx-page-*, --pdx-shell-*)
+  --pdx-page-bg: transparent;
+  --pdx-page-surface: #{$surface};
+  --pdx-page-gap: 20px;
+  --pdx-page-card-radius: #{$radius-lg};
+  --pdx-page-card-shadow: #{$elevation-1};
+  --pdx-page-accent: #{$primary};
+
+  --pdx-shell-card-bg: color-mix(in oklab, #{$surface} 75%, transparent);
+  --pdx-shell-card-border: #{$border};
+  --pdx-shell-card-radius: #{$radius-lg};
+  --pdx-shell-card-shadow: #{$elevation-1};
+  --pdx-shell-card-backdrop-filter: blur(14px);
+  --pdx-shell-header-bg: transparent;
+  --pdx-shell-header-border: #{$border};
+  --pdx-shell-title-color: #{$foreground};
+  --pdx-shell-subtitle-color: #{$muted-foreground};
+  --pdx-shell-icon-color: #{$primary};
+  --pdx-shell-body-bg: transparent;
+  --pdx-shell-body-color: #{$foreground};
+  --pdx-shell-body-padding: 16px;
+
+  // 4. Praxis Rich Content Tokens (--prx-rich-*)
+  --prx-rich-card-tone-bg: color-mix(in oklab, #{$surface} 80%, transparent);
+  --prx-rich-content-inline-gap: 8px;
+
+  // 5. Legacy Praxis Component Bridge Tokens
+  --praxis-color-primary: #{$primary};
+  --praxis-color-surface: #{$surface};
+  --praxis-color-text: #{$foreground};
+  --praxis-color-border: #{$border};
+  --pdx-shell-fullscreen-bg: #{$surface};
+}
+
+/// Emits canonical dark theme token overrides.
+///
+/// Can be included in `.dark`, `[data-theme="dark"]`, or `@media (prefers-color-scheme: dark)`.
+///
+/// @param {Map} $config Optional overrides for dark theme tokens.
+@mixin praxis-dark-theme-overrides($config: ()) {
+  $primary: _get-token($config, 'primary', var(--primary, #80d5d4));
+  $on-primary: _get-token($config, 'on-primary', var(--primary-foreground, #003737));
+  $secondary: _get-token($config, 'secondary', var(--secondary, #b1cccb));
+  $on-secondary: _get-token($config, 'on-secondary', var(--secondary-foreground, #1b3535));
+  $tertiary: _get-token($config, 'tertiary', var(--tertiary, var(--cobalt, #b2c8e8)));
+  $on-tertiary: _get-token($config, 'on-tertiary', var(--tertiary-foreground, #1a314b));
+  $error: _get-token($config, 'error', var(--destructive, var(--error, #ffb4ab)));
+  $on-error: _get-token($config, 'on-error', var(--destructive-foreground, var(--on-error, #690005)));
+
+  $surface: _get-token($config, 'surface', var(--card, var(--surface, #1e2222)));
+  $foreground: _get-token($config, 'foreground', var(--foreground, #e0e3e2));
+  $muted: _get-token($config, 'muted', var(--muted, #3f4948));
+  $muted-foreground: _get-token($config, 'muted-foreground', var(--muted-foreground, #bec9c7));
+  $border: _get-token($config, 'border', var(--border, #4a5453));
+
+  $popover: _get-token($config, 'popover', var(--popover, #{$surface}));
+  $popover-foreground: _get-token($config, 'popover-foreground', var(--popover-foreground, #{$foreground}));
+
+  $primary-container: _get-token($config, 'primary-container', color-mix(in oklab, #{$primary} 22%, #{$surface}));
+  $on-primary-container: _get-token($config, 'on-primary-container', #{$on-primary});
+
+  $secondary-container: _get-token($config, 'secondary-container', color-mix(in oklab, #{$secondary} 40%, #{$surface}));
+  $on-secondary-container: _get-token($config, 'on-secondary-container', #{$foreground});
+
+  $tertiary-container: _get-token($config, 'tertiary-container', color-mix(in oklab, #{$tertiary} 25%, #{$surface}));
+  $on-tertiary-container: _get-token($config, 'on-tertiary-container', #{$foreground});
+
+  $error-container: _get-token($config, 'error-container', color-mix(in oklab, #{$error} 25%, #{$surface}));
+  $on-error-container: _get-token($config, 'on-error-container', #{$on-error});
+
+  $surface-lowest: _get-token($config, 'surface-container-lowest', oklch(0.12 0.025 264));
+  $surface-low: _get-token($config, 'surface-container-low', oklch(0.15 0.03 260));
+  $surface-container: _get-token($config, 'surface-container', #{$surface});
+  $surface-high: _get-token($config, 'surface-container-high', oklch(0.22 0.035 260));
+  $surface-highest: _get-token($config, 'surface-container-highest', oklch(0.26 0.04 260));
+
+  $inverse-surface: _get-token($config, 'inverse-surface', oklch(0.24 0.035 260));
+  $inverse-on-surface: _get-token($config, 'inverse-on-surface', oklch(0.96 0.01 240));
+
+  $outline: _get-token($config, 'outline', #{$border});
+  $outline-variant: _get-token($config, 'outline-variant', color-mix(in oklab, #{$outline} 50%, transparent));
+
+  $shadow: _get-token($config, 'shadow', oklch(0.02 0.01 250 / 60%));
+  $scrim: _get-token($config, 'scrim', oklch(0.02 0.01 250 / 80%));
+
+  // 1. Dark Mode: Material Design 3 System Color Tokens
+  --md-sys-color-primary: #{$primary};
+  --md-sys-color-on-primary: #{$on-primary};
+  --md-sys-color-primary-container: #{$primary-container};
+  --md-sys-color-on-primary-container: #{$on-primary-container};
+
+  --md-sys-color-secondary: #{$secondary};
+  --md-sys-color-on-secondary: #{$on-secondary};
+  --md-sys-color-secondary-container: #{$secondary-container};
+  --md-sys-color-on-secondary-container: #{$on-secondary-container};
+
+  --md-sys-color-tertiary: #{$tertiary};
+  --md-sys-color-on-tertiary: #{$on-tertiary};
+  --md-sys-color-tertiary-container: #{$tertiary-container};
+  --md-sys-color-on-tertiary-container: #{$on-tertiary-container};
+
+  --md-sys-color-error: #{$error};
+  --md-sys-color-on-error: #{$on-error};
+  --md-sys-color-error-container: #{$error-container};
+  --md-sys-color-on-error-container: #{$on-error-container};
+
+  --md-sys-color-surface: #{$surface};
+  --md-sys-color-surface-container-lowest: #{$surface-lowest};
+  --md-sys-color-surface-container-low: #{$surface-low};
+  --md-sys-color-surface-container: #{$surface-container};
+  --md-sys-color-surface-container-high: #{$surface-high};
+  --md-sys-color-surface-container-highest: #{$surface-highest};
+  --md-sys-color-surface-variant: #{$muted};
+
+  --md-sys-color-on-surface: #{$foreground};
+  --md-sys-color-on-surface-variant: #{$muted-foreground};
+
+  --md-sys-color-inverse-surface: #{$inverse-surface};
+  --md-sys-color-inverse-on-surface: #{$inverse-on-surface};
+
+  --md-sys-color-outline: #{$outline};
+  --md-sys-color-outline-variant: #{$outline-variant};
+
+  --md-sys-color-shadow: #{$shadow};
+  --md-sys-color-scrim: #{$scrim};
+
+  // 1.1 Dark Mode: Angular Material M3 & Tooltip Tokens Bridge
+  --mat-sys-surface: #{$surface};
+  --mat-sys-on-surface: #{$foreground};
+  --mat-sys-surface-container: #{$surface-low};
+  --mat-sys-surface-container-high: #{$surface-high};
+  --mat-sys-surface-variant: #{$muted};
+  --mat-sys-on-surface-variant: #{$muted-foreground};
+  --mat-sys-outline: #{$outline};
+  --mat-sys-outline-variant: #{$outline-variant};
+  --mat-sys-primary: #{$primary};
+  --mat-sys-on-primary: #{$on-primary};
+  --mat-sys-inverse-surface: #{$inverse-surface};
+  --mat-sys-inverse-on-surface: #{$inverse-on-surface};
+
+  --mat-tooltip-container-color: var(--mat-sys-inverse-surface);
+  --mat-tooltip-supporting-text-color: var(--mat-sys-inverse-on-surface);
+
+  // 1.2 Dark Mode: Angular Material M3 Menu Tokens Bridge
+  --mat-menu-container-color: var(--card, var(--surface, #{$surface}));
+  --mat-menu-container-shape: var(--radius-md, var(--radius-lg, 14px));
+  --mat-menu-item-label-text-color: #{$foreground};
+  --mat-menu-item-icon-color: #{$muted-foreground};
+  --mat-menu-item-hover-state-layer-color: color-mix(in oklab, #{$primary} 18%, transparent);
+  --mat-menu-item-focus-state-layer-color: color-mix(in oklab, #{$primary} 24%, transparent);
+
+  // 2. Dark Mode: Praxis Core Bridge Tokens
+  --pdx-material-surface: #{$surface};
+  --pdx-material-surface-high: #{$surface-high};
+  --pdx-material-on-surface: #{$foreground};
+  --pdx-material-on-surface-muted: #{$muted-foreground};
+  --pdx-material-outline: #{$border};
+  --pdx-material-focus-outline: #{$primary};
+
+  --pdx-overlay-surface: #{$popover};
+  --pdx-overlay-on-surface: #{$popover-foreground};
+  --pdx-overlay-on-surface-muted: #{$muted-foreground};
+  --pdx-overlay-state-layer: color-mix(in oklab, #{$primary} 15%, transparent);
+
+  // 3. Dark Mode: Dynamic Widget Page & Widget Shell Tokens
+  --pdx-page-bg: transparent;
+  --pdx-page-surface: #{$surface};
+  --pdx-page-accent: #{$primary};
+
+  --pdx-shell-card-bg: color-mix(in oklab, #{$surface} 60%, transparent);
+  --pdx-shell-card-border: #{$border};
+  --pdx-shell-card-backdrop-filter: blur(16px);
+  --pdx-shell-header-bg: transparent;
+  --pdx-shell-header-border: #{$border};
+  --pdx-shell-title-color: #{$foreground};
+  --pdx-shell-subtitle-color: #{$muted-foreground};
+  --pdx-shell-icon-color: #{$primary};
+  --pdx-shell-body-bg: transparent;
+  --pdx-shell-body-color: #{$foreground};
+
+  // 4. Dark Mode: Rich Content Tokens
+  --prx-rich-card-tone-bg: color-mix(in oklab, #{$surface} 65%, transparent);
+
+  // 5. Dark Mode: Legacy Praxis Component Bridge Tokens
+  --praxis-color-primary: #{$primary};
+  --praxis-color-surface: #{$surface};
+  --praxis-color-text: #{$foreground};
+  --praxis-color-border: #{$border};
+  --pdx-shell-fullscreen-bg: #{$surface};
+}
+
+/// Emits responsive and solid surface styling for Widget Shell expanded and fullscreen modes.
+@mixin praxis-shell-styles() {
+  .pdx-shell-backdrop {
+    position: fixed !important;
+    inset: 0 !important;
+    z-index: 1280 !important;
+    background: color-mix(in oklab, var(--overlay, rgba(0, 0, 0, 0.6)) 85%, black) !important;
+    backdrop-filter: blur(14px) saturate(130%) !important;
+    -webkit-backdrop-filter: blur(14px) saturate(130%) !important;
+  }
+
+  .pdx-shell.fullscreen,
+  .pdx-shell.expanded {
+    background: var(--pdx-shell-fullscreen-bg, var(--card, #ffffff)) !important;
+    color: var(--pdx-shell-body-color, var(--foreground, inherit)) !important;
+    border: 1px solid var(--pdx-shell-card-border, var(--border, rgba(0, 0, 0, 0.12))) !important;
+    box-shadow: var(--shadow-command, var(--md-sys-elevation-level3, 0 4px 12px rgba(0, 0, 0, 0.18))) !important;
+  }
+
+  .pdx-shell.fullscreen {
+    inset: 24px !important;
+    width: auto !important;
+    height: auto !important;
+    border-radius: var(--radius-xl, 20px) !important;
+    overflow: hidden !important;
+  }
+
+  @media (max-width: 768px), (max-height: 800px) {
+    .pdx-shell.fullscreen {
+      inset: 12px !important;
+      border-radius: var(--radius-lg, 14px) !important;
+    }
+  }
+
+  .pdx-shell.fullscreen > .pdx-shell-header,
+  .pdx-shell.expanded > .pdx-shell-header {
+    padding: 16px 24px !important;
+    background: color-mix(in oklab, var(--pdx-shell-fullscreen-bg, var(--card, #ffffff)) 95%, var(--background, #f2f6f5)) !important;
+    border-bottom: 1px solid var(--pdx-shell-card-border, var(--border, rgba(0, 0, 0, 0.12))) !important;
+
+    .pdx-shell-title-text {
+      font-family: var(--font-display, inherit) !important;
+      font-size: 1.15rem !important;
+      font-weight: 700 !important;
+    }
+
+    .pdx-shell-subtitle {
+      font-size: 0.85rem !important;
+      color: var(--pdx-shell-subtitle-color, var(--muted-foreground, #666666)) !important;
+    }
+  }
+
+  @media (max-height: 800px) {
+    .pdx-shell.fullscreen > .pdx-shell-header,
+    .pdx-shell.expanded > .pdx-shell-header {
+      padding: 10px 18px !important;
+    }
+  }
+
+  .pdx-shell.fullscreen > .pdx-shell-body,
+  .pdx-shell.expanded > .pdx-shell-body {
+    padding: 24px 32px !important;
+    background: var(--pdx-shell-fullscreen-bg, var(--card, #ffffff)) !important;
+  }
+
+  @media (max-height: 800px) {
+    .pdx-shell.fullscreen > .pdx-shell-body,
+    .pdx-shell.expanded > .pdx-shell-body {
+      padding: 14px 20px !important;
+    }
+  }
+
+  .pdx-shell.fullscreen praxis-chart,
+  .pdx-shell.expanded praxis-chart {
+    width: 100% !important;
+    height: 100% !important;
+    display: block !important;
+  }
+}
+
+/// Emits solid surface and high-contrast refinements for Angular Material Tooltips.
+@mixin praxis-tooltip-styles() {
+  .mat-mdc-tooltip-surface {
+    background-color: var(--mat-tooltip-container-color, var(--mat-sys-inverse-surface, oklch(0.24 0.03 260))) !important;
+    color: var(--mat-tooltip-supporting-text-color, var(--mat-sys-inverse-on-surface, oklch(0.98 0.005 240))) !important;
+    border-radius: var(--radius-sm, 8px) !important;
+    padding: 6px 12px !important;
+    box-shadow: 0 4px 18px rgba(0, 0, 0, 0.25), 0 1px 3px rgba(0, 0, 0, 0.12) !important;
+    border: 1px solid color-mix(in oklab, var(--border, rgba(255, 255, 255, 0.15)) 45%, transparent) !important;
+    font-family: var(--font-sans, inherit) !important;
+    font-size: 12px !important;
+    font-weight: 500 !important;
+    line-height: 1.35 !important;
+    letter-spacing: 0.01em !important;
+    backdrop-filter: blur(8px) !important;
+    -webkit-backdrop-filter: blur(8px) !important;
+  }
+}
+
+/// Emits refined surface styling, command shadow, backdrop filter,
+/// and state layer hover animations for Angular Material Menus.
+@mixin praxis-menu-styles() {
+  .mat-mdc-menu-panel {
+    border-radius: var(--radius-md, 14px) !important;
+    background: color-mix(in oklab, var(--mat-menu-container-color, var(--card, var(--surface, #ffffff))) 92%, var(--background, #f2f6f5)) !important;
+    border: 1px solid var(--border, var(--md-sys-color-outline-variant, rgba(0, 0, 0, 0.12))) !important;
+    box-shadow: var(--shadow-command, var(--md-sys-elevation-level3, 0 4px 12px rgba(0, 0, 0, 0.18))), 0 12px 32px rgba(0, 0, 0, 0.18) !important;
+    backdrop-filter: blur(18px) saturate(140%) !important;
+    -webkit-backdrop-filter: blur(18px) saturate(140%) !important;
+    padding: 6px !important;
+    overflow: hidden !important;
+  }
+
+  .mat-mdc-menu-item {
+    min-height: 40px !important;
+    border-radius: var(--radius-sm, 10px) !important;
+    margin: 2px 0 !important;
+    padding: 0 14px !important;
+    font-family: var(--font-sans, inherit) !important;
+    font-size: 0.85rem !important;
+    font-weight: 500 !important;
+    color: var(--mat-menu-item-label-text-color, var(--foreground, inherit)) !important;
+    transition: background-color 0.15s ease, color 0.15s ease, transform 0.15s ease !important;
+
+    .mat-icon {
+      margin-right: 12px !important;
+      color: var(--mat-menu-item-icon-color, var(--muted-foreground, inherit)) !important;
+      font-size: 20px !important;
+      width: 20px !important;
+      height: 20px !important;
+      transition: color 0.15s ease, transform 0.15s ease !important;
+    }
+
+    &:hover:not([disabled]) {
+      background-color: var(--mat-menu-item-hover-state-layer-color, color-mix(in oklab, var(--primary) 12%, transparent)) !important;
+      color: var(--foreground, inherit) !important;
+      transform: translateX(3px);
+
+      .mat-icon {
+        color: var(--primary, var(--md-sys-color-primary)) !important;
+        transform: scale(1.08);
+      }
+    }
+
+    &:focus-visible:not([disabled]),
+    &.cdk-program-focused:not([disabled]) {
+      background-color: var(--mat-menu-item-focus-state-layer-color, color-mix(in oklab, var(--primary) 18%, transparent)) !important;
+      outline: 2px solid var(--primary, var(--md-sys-color-primary)) !important;
+      outline-offset: -2px;
+    }
+
+    &[disabled] {
+      opacity: 0.42 !important;
+      cursor: not-allowed !important;
+      pointer-events: none !important;
+      transform: none !important;
+    }
+  }
+}
+
+/// Convenience mixin that bundles all theme definitions, dark mode overrides,
+/// widget shell rules, tooltip enhancements, and menu state layer styles.
+///
+/// @param {Map} $config Optional overrides for root theme tokens.
+/// @param {Map} $dark-config Optional overrides for dark theme tokens.
+/// @param {String} $dark-selector Selector used for dark mode (defaults to '.dark').
+@mixin praxis-theme-bundle($config: (), $dark-config: (), $dark-selector: '.dark') {
+  :root {
+    @include define-praxis-theme($config);
+  }
+
+  #{$dark-selector} {
+    @include praxis-dark-theme-overrides($dark-config);
+  }
+
+  @include praxis-shell-styles();
+  @include praxis-tooltip-styles();
+  @include praxis-menu-styles();
+}

package/theming/index.scss

@@ -0,0 +1 @@
+@forward 'theming';

package/theming/theming.scss

@@ -0,0 +1 @@
+@forward 'theming';