@vellira-ui/tokens 2.100.0 → 2.101.0

package/README.md

@@ -23,31 +23,37 @@ pnpm add @vellira-ui/tokens
 
 ## Usage
 
+Choose a named theme explicitly:
+
 ```ts
-import {
-  darkTheme,
-  highContrastTheme,
-  lightTheme,
-  theme,
-} from '@vellira-ui/tokens';
-
-theme.semantic.surface.default;
-theme.semantic.text.primary;
-theme.semantic.border.default;
-theme.semantic.status.success.fg;
-
-theme.components.button.primary.solid.default.bg;
-theme.components.input.default.bg;
-
-theme.tokens.typography.family.regular;
-theme.tokens.spacing[4];
-theme.tokens.radius.md;
-
-lightTheme.name;
-darkTheme.name;
-highContrastTheme.name;
+import { darkTheme, highContrastTheme, lightTheme } from '@vellira-ui/tokens';
+
+darkTheme.semantic.surface.default;
+darkTheme.semantic.surface.panel;
+darkTheme.semantic.text.primary;
+darkTheme.semantic.border.default;
+darkTheme.semantic.status.success.fg;
+
+darkTheme.components.button.primary.solid.default.bg;
+darkTheme.components.input.default.bg;
+
+darkTheme.tokens.typography.family.regular;
+darkTheme.tokens.spacing[4];
+darkTheme.tokens.radius.md;
+
+lightTheme.name; // 'light'
+darkTheme.name; // 'dark'
+highContrastTheme.name; // 'high-contrast'
 ```
 
+There is no implicit current/default JavaScript theme object. The historical
+`theme` export is a deprecated partial view of `darkTheme`; use `darkTheme`
+directly. The compatibility export is scheduled for removal in Vellira 3.0.0.
+
+The generated Web CSS separately uses Light values for `:root`, so pages without
+a theme attribute have a deterministic browser fallback. That CSS default does
+not make `lightTheme` an implicit JavaScript default.
+
 ## Semantic Tokens
 
 The package provides semantic groups that describe intent instead of coupling
@@ -62,7 +68,6 @@ Current semantic groups include:
 - `focus`
 - `icons`
 - `menu`
-- `navigation`
 - `overlay`
 - `shadow`
 - `skeleton`
@@ -73,18 +78,23 @@ Current semantic groups include:
 Example:
 
 ```ts
-theme.semantic.surface.default;
-theme.semantic.surface.elevated;
+darkTheme.semantic.surface.canvas;
+darkTheme.semantic.surface.panel;
+darkTheme.semantic.surface.elevated;
 
-theme.semantic.text.primary;
-theme.semantic.text.secondary;
+darkTheme.semantic.text.primary;
+darkTheme.semantic.text.secondary;
 
-theme.semantic.border.default;
+darkTheme.semantic.border.default;
 
-theme.semantic.status.success.fg;
-theme.semantic.status.error.fg;
+darkTheme.semantic.status.success.fg;
+darkTheme.semantic.status.error.fg;
 ```
 
+`surface.canvas` is the application/root backdrop, `surface.panel` is bounded
+neutral container/chrome, and `surface.elevated` is reserved for genuinely
+raised or floating layers.
+
 Using semantic tokens instead of raw palette values keeps component styling
 consistent across renderers and themes.
 
@@ -94,12 +104,12 @@ Component tokens define renderer-neutral values for component states and
 surfaces.
 
 ```ts
-theme.components.button.primary.solid.default.bg;
-theme.components.input.focus.border;
-theme.components.dropdown.content.bg;
-theme.components.popover.content.bg;
-theme.components.modal.content.bg;
-theme.components.tooltip.content.bg;
+darkTheme.components.button.primary.solid.default.bg;
+darkTheme.components.input.focus.border;
+darkTheme.components.dropdown.content.bg;
+darkTheme.components.popover.content.bg;
+darkTheme.components.modal.content.bg;
+darkTheme.components.tooltip.content.bg;
 ```
 
 Color-like component tokens may use either colors or the literal `transparent`
@@ -117,12 +127,51 @@ Examples:
 
 ```css
 --color-mono-0
---surface-default
+--surface-canvas
+--surface-panel
 --text-primary
 --border-default
 --button-primary-solid-default-bg
 ```
 
+Canonical token-path types describe only the current renderer-neutral token
+contract. During Vellira 2.x, a bounded set of legacy CSS variables is still
+generated for migration compatibility. Those aliases remain in the generated
+CSS-variable name unions because they are actually emitted, but they are not
+canonical `TokenPath`/`ComponentTokenPath` entries and new code must not adopt
+them.
+
+The compatibility aliases, replacements, migration evidence, and removal
+release are tracked in
+`src/platform-output/component-token-web-compatibility.ts`. They are scheduled
+for removal in Vellira 3.0.0.
+
+## Public API deprecation policy
+
+Public token/theme cleanup follows one bounded policy:
+
+- named theme objects are canonical (`lightTheme`, `darkTheme`,
+  `highContrastTheme`);
+- deprecated root exports preserve their existing behavior during the 2.x
+  compatibility window and name a canonical replacement;
+- deprecated Web CSS variables remain platform-output aliases only and do not
+  re-enter canonical token-path unions;
+- every alias has migration/preservation evidence and an explicit removal
+  boundary;
+- Token Architecture Normalization V1 removes these compatibility aliases at
+  Vellira 3.0.0 unless a separately reviewed policy revision supersedes it.
+
+The machine-readable contract lives in `src/public-api-policy.ts`. The detailed
+architecture note is `docs/architecture/token-public-api-v1.md`.
+
+## React and React Native
+
+The shared theme/token source is renderer-neutral. React/Web consumers can use
+named theme objects or generated CSS variables. React Native consumes the same
+canonical component intent and resolves platform representation through the
+native output adapter; renderer-specific token branches are not part of the
+public canonical component contract.
+
 ## Documentation
 
 - [Design Tokens](https://docs.vellira.dev/design-system/tokens)
@@ -170,8 +219,8 @@ The preservation contract covers the complete current public visual surface:
   overlay primitives and control-size values;
 - generated Web CSS variable names together with their serialized values, using
   the same serializer as the published `@vellira-ui/tokens/css` artifact;
-- the current React Native output contract, which consumes the canonical theme
-  objects directly until a dedicated native platform adapter is introduced.
+- the current React Native output contract derived from canonical component
+  intents and platform adapters.
 
 Normal token changes must not regenerate the baseline just to make a failure
 disappear. Instead, record the change in

package/css.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/css/tokens.css

@@ -38,6 +38,7 @@
   --font-weight-regular: 400;
   --font-weight-medium: 500;
   --font-weight-semibold: 600;
+  --font-weight-bold: 700;
   --font-size-xs: 12px;
   --font-size-sm: 14px;
   --font-size-md: 16px;

package/dist/dark/semantic/focus.d.ts

@@ -2,7 +2,7 @@ export declare const focus: {
     readonly ring: {
         readonly color: "#B8A8FF";
         readonly width: "2px";
-        readonly shadow: "0 0 8px rgba(184, 168, 255, 0.14)";
+        readonly shadow: string;
         readonly offsetColor: "#181521";
     };
 };

package/dist/dark/semantic/focus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"focus.d.ts","sourceRoot":"","sources":["../../../src/dark/semantic/focus.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,KAAK;;;;;;;CAOR,CAAC"}
+{"version":3,"file":"focus.d.ts","sourceRoot":"","sources":["../../../src/dark/semantic/focus.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,KAAK;;;;;;;CAOR,CAAC"}

package/dist/dark/semantic/focus.js

@@ -1,9 +1,10 @@
+import { createFocusRingShadowToken } from '../../effects/shadow-system.js';
 import { colors } from '../../primitives/colors.js';
 export const focus = {
     ring: {
         color: colors.primary[300],
         width: '2px',
-        shadow: '0 0 8px rgba(184, 168, 255, 0.14)',
+        shadow: createFocusRingShadowToken('dark'),
         offsetColor: colors.vellira[950],
     },
 };

package/dist/dark/semantic/shadow.d.ts

@@ -1,8 +1,8 @@
 export declare const shadow: {
-    readonly sm: "0 1px 2px rgba(0, 0, 0, 0.12)";
-    readonly md: "0 4px 12px rgba(0, 0, 0, 0.22)";
-    readonly lg: "0 12px 40px rgba(0, 0, 0, 0.35), 0 2px 8px rgba(0, 0, 0, 0.25)";
-    readonly xl: "0 20px 60px rgba(0, 0, 0, 0.45), 0 4px 16px rgba(0, 0, 0, 0.3)";
-    readonly inset: "inset 0 1px 0 rgba(255, 255, 255, 0.06)";
+    readonly sm: string;
+    readonly md: string;
+    readonly lg: string;
+    readonly xl: string;
+    readonly inset: string;
 };
 //# sourceMappingURL=shadow.d.ts.map

package/dist/dark/semantic/shadow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shadow.d.ts","sourceRoot":"","sources":["../../../src/dark/semantic/shadow.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,MAAM;;;;;;CAMT,CAAC"}
+{"version":3,"file":"shadow.d.ts","sourceRoot":"","sources":["../../../src/dark/semantic/shadow.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,MAAM;;;;;;CAAqC,CAAC"}

package/dist/dark/semantic/shadow.js

@@ -1,7 +1,2 @@
-export const shadow = {
-    sm: '0 1px 2px rgba(0, 0, 0, 0.12)',
-    md: '0 4px 12px rgba(0, 0, 0, 0.22)',
-    lg: '0 12px 40px rgba(0, 0, 0, 0.35), 0 2px 8px rgba(0, 0, 0, 0.25)',
-    xl: '0 20px 60px rgba(0, 0, 0, 0.45), 0 4px 16px rgba(0, 0, 0, 0.3)',
-    inset: 'inset 0 1px 0 rgba(255, 255, 255, 0.06)',
-};
+import { createSemanticShadowTokens } from '../../effects/shadow-system.js';
+export const shadow = createSemanticShadowTokens('dark');

package/dist/dark/theme.d.ts

@@ -152,30 +152,30 @@ export declare const darkTheme: {
             readonly full: 999;
         };
         readonly shadows: {
-            readonly sm: {
-                readonly x: 0;
-                readonly y: 1;
-                readonly blur: 3;
-                readonly color: "#000000";
-                readonly opacity: 0.04;
-                readonly elevation: 1;
-            };
-            readonly md: {
-                readonly x: 0;
-                readonly y: 6;
-                readonly blur: 16;
-                readonly color: "#000000";
-                readonly opacity: 0.08;
-                readonly elevation: 4;
-            };
-            readonly lg: {
-                readonly x: 0;
-                readonly y: 12;
-                readonly blur: 32;
-                readonly color: "#000000";
-                readonly opacity: 0.1;
-                readonly elevation: 8;
-            };
+            readonly sm: Readonly<{
+                x: number;
+                y: number;
+                blur: number;
+                color: string;
+                opacity: number;
+                elevation: number;
+            }>;
+            readonly md: Readonly<{
+                x: number;
+                y: number;
+                blur: number;
+                color: string;
+                opacity: number;
+                elevation: number;
+            }>;
+            readonly lg: Readonly<{
+                x: number;
+                y: number;
+                blur: number;
+                color: string;
+                opacity: number;
+                elevation: number;
+            }>;
         };
         readonly spacing: {
             readonly 0: 0;
@@ -213,6 +213,7 @@ export declare const darkTheme: {
                 readonly regular: "400";
                 readonly medium: "500";
                 readonly semibold: "600";
+                readonly bold: "700";
             };
             readonly lineHeight: {
                 readonly xs: 16;

package/dist/dark/theme.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../../src/dark/theme.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,UAAU,MAAM,uBAAuB,CAAC;AACpD,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAC;AAEhD,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAYZ,CAAC"}
+{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../../src/dark/theme.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,UAAU,MAAM,uBAAuB,CAAC;AACpD,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAC;AAEhD,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAYZ,CAAC"}

package/dist/effects/shadow-system.d.ts

@@ -0,0 +1,181 @@
+export declare const shadowThemeNames: readonly ["light", "dark", "high-contrast"];
+export type ShadowThemeName = (typeof shadowThemeNames)[number];
+export declare const elevationShadowLevels: readonly ["sm", "md", "lg", "xl"];
+export type ElevationShadowLevel = (typeof elevationShadowLevels)[number];
+export type ShadowLayer = Readonly<{
+    x: number;
+    y: number;
+    blur: number;
+    spread: number;
+    color: string;
+    opacity: number;
+    inset: boolean;
+}>;
+export type ShadowEffect = Readonly<{
+    layers: readonly ShadowLayer[];
+}>;
+export type ReactNativeShadowOutput = Readonly<{
+    x: number;
+    y: number;
+    blur: number;
+    color: string;
+    opacity: number;
+    elevation: number;
+}>;
+export declare const canonicalShadowEffects: {
+    readonly elevation: {
+        readonly sm: {
+            readonly themes: {
+                readonly light: Readonly<{
+                    layers: readonly ShadowLayer[];
+                }>;
+                readonly dark: Readonly<{
+                    layers: readonly ShadowLayer[];
+                }>;
+                readonly 'high-contrast': Readonly<{
+                    layers: readonly ShadowLayer[];
+                }>;
+            };
+            readonly reactNativeApproximation: {
+                readonly kind: "direct";
+                readonly output: Readonly<{
+                    x: number;
+                    y: number;
+                    blur: number;
+                    color: string;
+                    opacity: number;
+                    elevation: number;
+                }>;
+            };
+        };
+        readonly md: {
+            readonly themes: {
+                readonly light: Readonly<{
+                    layers: readonly ShadowLayer[];
+                }>;
+                readonly dark: Readonly<{
+                    layers: readonly ShadowLayer[];
+                }>;
+                readonly 'high-contrast': Readonly<{
+                    layers: readonly ShadowLayer[];
+                }>;
+            };
+            readonly reactNativeApproximation: {
+                readonly kind: "direct";
+                readonly output: Readonly<{
+                    x: number;
+                    y: number;
+                    blur: number;
+                    color: string;
+                    opacity: number;
+                    elevation: number;
+                }>;
+            };
+        };
+        readonly lg: {
+            readonly themes: {
+                readonly light: Readonly<{
+                    layers: readonly ShadowLayer[];
+                }>;
+                readonly dark: Readonly<{
+                    layers: readonly ShadowLayer[];
+                }>;
+                readonly 'high-contrast': Readonly<{
+                    layers: readonly ShadowLayer[];
+                }>;
+            };
+            readonly reactNativeApproximation: {
+                readonly kind: "direct";
+                readonly output: Readonly<{
+                    x: number;
+                    y: number;
+                    blur: number;
+                    color: string;
+                    opacity: number;
+                    elevation: number;
+                }>;
+            };
+        };
+        readonly xl: {
+            readonly themes: {
+                readonly light: Readonly<{
+                    layers: readonly ShadowLayer[];
+                }>;
+                readonly dark: Readonly<{
+                    layers: readonly ShadowLayer[];
+                }>;
+                readonly 'high-contrast': Readonly<{
+                    layers: readonly ShadowLayer[];
+                }>;
+            };
+            readonly reactNativeApproximation: {
+                readonly kind: "reference";
+                readonly level: "lg";
+                readonly reason: "React Native preserves the pre-unification Modal output by approximating xl with lg.";
+            };
+        };
+    };
+    readonly inset: {
+        readonly themes: {
+            readonly light: Readonly<{
+                layers: readonly ShadowLayer[];
+            }>;
+            readonly dark: Readonly<{
+                layers: readonly ShadowLayer[];
+            }>;
+            readonly 'high-contrast': Readonly<{
+                layers: readonly ShadowLayer[];
+            }>;
+        };
+    };
+    readonly focusRing: {
+        readonly themes: {
+            readonly light: Readonly<{
+                layers: readonly ShadowLayer[];
+            }>;
+            readonly dark: Readonly<{
+                layers: readonly ShadowLayer[];
+            }>;
+            readonly 'high-contrast': Readonly<{
+                layers: readonly ShadowLayer[];
+            }>;
+        };
+    };
+};
+export declare function serializeShadowEffectForWeb(value: ShadowEffect): string;
+export declare function createSemanticShadowTokens(themeName: ShadowThemeName): {
+    readonly sm: string;
+    readonly md: string;
+    readonly lg: string;
+    readonly xl: string;
+    readonly inset: string;
+};
+export declare function createFocusRingShadowToken(themeName: ShadowThemeName): string;
+export declare function resolveReactNativeElevationShadow(level: ElevationShadowLevel): ReactNativeShadowOutput;
+export declare function createReactNativeShadowTokens(): {
+    readonly sm: Readonly<{
+        x: number;
+        y: number;
+        blur: number;
+        color: string;
+        opacity: number;
+        elevation: number;
+    }>;
+    readonly md: Readonly<{
+        x: number;
+        y: number;
+        blur: number;
+        color: string;
+        opacity: number;
+        elevation: number;
+    }>;
+    readonly lg: Readonly<{
+        x: number;
+        y: number;
+        blur: number;
+        color: string;
+        opacity: number;
+        elevation: number;
+    }>;
+};
+//# sourceMappingURL=shadow-system.d.ts.map

package/dist/effects/shadow-system.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shadow-system.d.ts","sourceRoot":"","sources":["../../src/effects/shadow-system.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,gBAAgB,6CAA8C,CAAC;AAC5E,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhE,eAAO,MAAM,qBAAqB,mCAAoC,CAAC;AACvE,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1E,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC;IACjC,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC;IAClC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;CAChC,CAAC,CAAC;AAEH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC,CAAC;AAsDH,eAAO,MAAM,sBAAsB;;;;;4BAhEzB,SAAS,WAAW,EAAE;;;4BAAtB,SAAS,WAAW,EAAE;;;4BAAtB,SAAS,WAAW,EAAE;;;;;;uBAI3B,MAAM;uBACN,MAAM;0BACH,MAAM;2BACL,MAAM;6BACJ,MAAM;+BACJ,MAAM;;;;;;;4BATT,SAAS,WAAW,EAAE;;;4BAAtB,SAAS,WAAW,EAAE;;;4BAAtB,SAAS,WAAW,EAAE;;;;;;uBAI3B,MAAM;uBACN,MAAM;0BACH,MAAM;2BACL,MAAM;6BACJ,MAAM;+BACJ,MAAM;;;;;;;4BATT,SAAS,WAAW,EAAE;;;4BAAtB,SAAS,WAAW,EAAE;;;4BAAtB,SAAS,WAAW,EAAE;;;;;;uBAI3B,MAAM;uBACN,MAAM;0BACH,MAAM;2BACL,MAAM;6BACJ,MAAM;+BACJ,MAAM;;;;;;;4BATT,SAAS,WAAW,EAAE;;;4BAAtB,SAAS,WAAW,EAAE;;;4BAAtB,SAAS,WAAW,EAAE;;;;;;;;;;;;;wBAAtB,SAAS,WAAW,EAAE;;;wBAAtB,SAAS,WAAW,EAAE;;;wBAAtB,SAAS,WAAW,EAAE;;;;;;;wBAAtB,SAAS,WAAW,EAAE;;;wBAAtB,SAAS,WAAW,EAAE;;;wBAAtB,SAAS,WAAW,EAAE;;;;CAkIW,CAAC;AA2D5C,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAMvE;AAED,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,eAAe;;;;;;EAkBpE;AAED,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,eAAe,GAAG,MAAM,CAI7E;AAED,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,oBAAoB,GAC1B,uBAAuB,CASzB;AAED,wBAAgB,6BAA6B;;WAxOxC,MAAM;WACN,MAAM;cACH,MAAM;eACL,MAAM;iBACJ,MAAM;mBACJ,MAAM;;;WALd,MAAM;WACN,MAAM;cACH,MAAM;eACL,MAAM;iBACJ,MAAM;mBACJ,MAAM;;;WALd,MAAM;WACN,MAAM;cACH,MAAM;eACL,MAAM;iBACJ,MAAM;mBACJ,MAAM;;EAyOlB"}

package/dist/effects/shadow-system.js

@@ -0,0 +1,134 @@
+import { colors } from '../primitives/colors.js';
+export const shadowThemeNames = ['light', 'dark', 'high-contrast'];
+export const elevationShadowLevels = ['sm', 'md', 'lg', 'xl'];
+const effect = (...layers) => ({ layers });
+const layer = (x, y, blur, spread, color, opacity, inset = false) => ({ x, y, blur, spread, color, opacity, inset });
+const nativeShadow = (x, y, blur, color, opacity, elevation) => ({ x, y, blur, color, opacity, elevation });
+const nativeSm = nativeShadow(0, 1, 3, colors.mono[950], 0.04, 1);
+const nativeMd = nativeShadow(0, 6, 16, colors.mono[950], 0.08, 4);
+const nativeLg = nativeShadow(0, 12, 32, colors.mono[950], 0.1, 8);
+export const canonicalShadowEffects = {
+    elevation: {
+        sm: {
+            themes: {
+                light: effect(layer(0, 1, 2, 0, colors.vellira[950], 0.08)),
+                dark: effect(layer(0, 1, 2, 0, colors.mono[950], 0.12)),
+                'high-contrast': effect(layer(0, 1, 2, 0, colors.mono[950], 0.5)),
+            },
+            reactNativeApproximation: { kind: 'direct', output: nativeSm },
+        },
+        md: {
+            themes: {
+                light: effect(layer(0, 4, 12, 0, colors.vellira[950], 0.12)),
+                dark: effect(layer(0, 4, 12, 0, colors.mono[950], 0.22)),
+                'high-contrast': effect(layer(0, 4, 12, 0, colors.mono[950], 0.6)),
+            },
+            reactNativeApproximation: { kind: 'direct', output: nativeMd },
+        },
+        lg: {
+            themes: {
+                light: effect(layer(0, 12, 40, 0, colors.vellira[950], 0.16), layer(0, 2, 8, 0, colors.vellira[950], 0.1)),
+                dark: effect(layer(0, 12, 40, 0, colors.mono[950], 0.35), layer(0, 2, 8, 0, colors.mono[950], 0.25)),
+                'high-contrast': effect(layer(0, 12, 40, 0, colors.mono[950], 0.7)),
+            },
+            reactNativeApproximation: { kind: 'direct', output: nativeLg },
+        },
+        xl: {
+            themes: {
+                light: effect(layer(0, 20, 60, 0, colors.vellira[950], 0.2), layer(0, 4, 16, 0, colors.vellira[950], 0.14)),
+                dark: effect(layer(0, 20, 60, 0, colors.mono[950], 0.45), layer(0, 4, 16, 0, colors.mono[950], 0.3)),
+                'high-contrast': effect(layer(0, 20, 60, 0, colors.mono[950], 0.8)),
+            },
+            reactNativeApproximation: {
+                kind: 'reference',
+                level: 'lg',
+                reason: 'React Native preserves the pre-unification Modal output by approximating xl with lg.',
+            },
+        },
+    },
+    inset: {
+        themes: {
+            light: effect(layer(0, 1, 0, 0, colors.mono[50], 0.55, true)),
+            dark: effect(layer(0, 1, 0, 0, colors.mono[50], 0.06, true)),
+            'high-contrast': effect(layer(0, 1, 0, 0, colors.mono[50], 0.14, true)),
+        },
+    },
+    focusRing: {
+        themes: {
+            light: effect(layer(0, 0, 8, 0, colors.primary[600], 0.14)),
+            dark: effect(layer(0, 0, 8, 0, colors.primary[300], 0.14)),
+            'high-contrast': effect(layer(0, 0, 0, 1, colors.mono[50], 0.28)),
+        },
+    },
+};
+function parseHexColor(color) {
+    const match = color.match(/^#([0-9a-f]{6})$/i);
+    if (!match) {
+        throw new Error(`Shadow layer color must be a six-digit hex value, received ${color}.`);
+    }
+    const value = match[1];
+    return [
+        Number.parseInt(value.slice(0, 2), 16),
+        Number.parseInt(value.slice(2, 4), 16),
+        Number.parseInt(value.slice(4, 6), 16),
+    ];
+}
+function formatLength(value) {
+    if (!Number.isFinite(value)) {
+        throw new Error(`Shadow length must be finite, received ${value}.`);
+    }
+    return value === 0 ? '0' : `${value}px`;
+}
+function serializeLayerForWeb(value) {
+    if (!Number.isFinite(value.blur) || value.blur < 0) {
+        throw new Error(`Shadow blur must be finite and non-negative, received ${value.blur}.`);
+    }
+    if (!Number.isFinite(value.opacity) ||
+        value.opacity < 0 ||
+        value.opacity > 1) {
+        throw new Error(`Shadow opacity must be finite and within [0, 1], received ${value.opacity}.`);
+    }
+    const [red, green, blue] = parseHexColor(value.color);
+    const lengths = [
+        formatLength(value.x),
+        formatLength(value.y),
+        formatLength(value.blur),
+    ];
+    if (value.spread !== 0) {
+        lengths.push(formatLength(value.spread));
+    }
+    const color = `rgba(${red}, ${green}, ${blue}, ${value.opacity})`;
+    return `${value.inset ? 'inset ' : ''}${lengths.join(' ')} ${color}`;
+}
+export function serializeShadowEffectForWeb(value) {
+    if (value.layers.length === 0) {
+        throw new Error('Shadow effect must contain at least one layer.');
+    }
+    return value.layers.map(serializeLayerForWeb).join(', ');
+}
+export function createSemanticShadowTokens(themeName) {
+    return {
+        sm: serializeShadowEffectForWeb(canonicalShadowEffects.elevation.sm.themes[themeName]),
+        md: serializeShadowEffectForWeb(canonicalShadowEffects.elevation.md.themes[themeName]),
+        lg: serializeShadowEffectForWeb(canonicalShadowEffects.elevation.lg.themes[themeName]),
+        xl: serializeShadowEffectForWeb(canonicalShadowEffects.elevation.xl.themes[themeName]),
+        inset: serializeShadowEffectForWeb(canonicalShadowEffects.inset.themes[themeName]),
+    };
+}
+export function createFocusRingShadowToken(themeName) {
+    return serializeShadowEffectForWeb(canonicalShadowEffects.focusRing.themes[themeName]);
+}
+export function resolveReactNativeElevationShadow(level) {
+    const approximation = canonicalShadowEffects.elevation[level].reactNativeApproximation;
+    if (approximation.kind === 'direct') {
+        return approximation.output;
+    }
+    return resolveReactNativeElevationShadow(approximation.level);
+}
+export function createReactNativeShadowTokens() {
+    return {
+        sm: resolveReactNativeElevationShadow('sm'),
+        md: resolveReactNativeElevationShadow('md'),
+        lg: resolveReactNativeElevationShadow('lg'),
+    };
+}