@vellira-ui/tokens 2.98.3 → 2.98.5

package/README.md

@@ -151,6 +151,59 @@ Verify that generated token types are up to date:
 pnpm --filter @vellira-ui/tokens generate:types:check
 ```
 
+### Token preservation baseline
+
+Token Architecture Normalization V1 uses a committed resolved-value baseline to
+prevent naming and ownership cleanup from silently redesigning Vellira.
+
+Verify the baseline with:
+
+```bash
+pnpm --filter @vellira-ui/tokens preservation:check
+```
+
+The preservation contract covers the complete current public visual surface:
+
+- every resolved scalar leaf under the Light, Dark, and High Contrast theme
+  graphs;
+- shared public visual tokens exported outside those theme graphs, including
+  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.
+
+Normal token changes must not regenerate the baseline just to make a failure
+disappear. Instead, record the change in
+`src/preservation/token-migrations.ts` as an explicit rename, compatibility
+alias, removal, addition, representation-only change, or approved visual
+change. Renames and aliases are checked against the previous resolved identity,
+so cleanup does not require obsolete token names to remain canonical forever.
+
+Representation-only migrations explicitly declare their layer. A `canonical`
+representation change is used when the renderer-neutral value changes shape or
+type while retaining the same rendered meaning, for example a reviewed numeric
+normalization such as `'1'` to `1`. A `platform-output` representation change
+must additionally name the affected Web or React Native platform. Both forms
+require explicit equivalence evidence; neither is an escape hatch for visual
+drift.
+
+`preservation:baseline` is a bootstrap command and refuses to overwrite an
+existing committed baseline during normal work. A deliberate reviewed reset
+requires the explicit `--force-reset` CLI flag. Resetting a baseline is never by
+itself evidence that a visual change is safe.
+
+Broad token migrations must also use the repository's canonical pinned Linux
+visual regression path:
+
+```bash
+pnpm test:e2e:web:visual:docker
+```
+
+Do not update visual baselines or the token preservation baseline merely to
+obtain green CI. Any intended visual change must be isolated and explicitly
+approved.
+
 ## Principles
 
 - Semantic tokens over hardcoded colors

package/dist/css/tokens.css

@@ -272,6 +272,17 @@
   --focus-ring-width: 2px;
   --focus-ring-shadow: 0 0 8px rgba(99, 70, 232, 0.14);
   --focus-ring-offset: #FFFFFF;
+  --icons-default: #3D3754;
+  --icons-secondary: #6B6386;
+  --icons-muted: #958CB0;
+  --icons-subtle: #958CB0;
+  --icons-disabled: #958CB0;
+  --icons-primary: #5037C8;
+  --icons-brand: #5037C8;
+  --icons-hover: #402C9F;
+  --icons-success: #14B8A6;
+  --icons-danger: #BE123C;
+  --icons-inverse: #FFFFFF;
   --menu-background: #FFFFFF;
   --menu-border: #E4DDF4;
   --menu-item-default-bg: transparent;
@@ -1320,8 +1331,8 @@
   --popover-content-shadow-native-y: 12px;
   --popover-content-shadow-native-blur: 32px;
   --popover-content-shadow-native-color: #000000;
-  --popover-content-shadow-native-opacity: 0.1px;
-  --popover-content-shadow-native-elevation: 8px;
+  --popover-content-shadow-native-opacity: 0.1;
+  --popover-content-shadow-native-elevation: 8;
   --popover-content-border-width: 1px;
   --popover-content-radius: 16px;
   --popover-content-padding: 16px;
@@ -1355,9 +1366,9 @@
   --radio-motion-easing: cubic-bezier(0.16, 1, 0.3, 1);
   --radio-motion-indicator-duration: 180ms;
   --radio-motion-selected-duration: 260ms;
-  --radio-motion-pressed-scale: 0.96px;
-  --radio-motion-active-scale: 0.92px;
-  --radio-motion-pressed-opacity: 0.8px;
+  --radio-motion-pressed-scale: 0.96;
+  --radio-motion-active-scale: 0.92;
+  --radio-motion-pressed-opacity: 0.8;
   --radio-default-bg: #FFFFFF;
   --radio-default-fg: #3D3754;
   --radio-default-border: #BBB2D2;
@@ -2349,7 +2360,7 @@
   --tooltip-content-compact-line-height: 16px;
   --tooltip-content-animation-duration: 150ms;
   --tooltip-content-translate-y: 2px;
-  --tooltip-content-scale: 0.98px;
+  --tooltip-content-scale: 0.98;
   --tooltip-arrow-bg: #FFFFFF;
   --tooltip-arrow-size: 10px;
   --tooltip-arrow-compact-size: 6px;
@@ -2571,6 +2582,17 @@
   --focus-ring-width: 2px;
   --focus-ring-shadow: 0 0 8px rgba(184, 168, 255, 0.14);
   --focus-ring-offset: #181521;
+  --icons-default: #F4F1FB;
+  --icons-secondary: #E5E7EB;
+  --icons-muted: #958CB0;
+  --icons-subtle: #6B6386;
+  --icons-disabled: #6B6386;
+  --icons-primary: #B8A8FF;
+  --icons-brand: #B8A8FF;
+  --icons-hover: #D4CCFF;
+  --icons-success: #2DD4BF;
+  --icons-danger: #FB7185;
+  --icons-inverse: #000000;
   --menu-background: #2F2A42;
   --menu-border: #4F4867;
   --menu-item-default-bg: transparent;
@@ -3619,8 +3641,8 @@
   --popover-content-shadow-native-y: 12px;
   --popover-content-shadow-native-blur: 32px;
   --popover-content-shadow-native-color: #000000;
-  --popover-content-shadow-native-opacity: 0.1px;
-  --popover-content-shadow-native-elevation: 8px;
+  --popover-content-shadow-native-opacity: 0.1;
+  --popover-content-shadow-native-elevation: 8;
   --popover-content-border-width: 1px;
   --popover-content-radius: 16px;
   --popover-content-padding: 16px;
@@ -3654,9 +3676,9 @@
   --radio-motion-easing: cubic-bezier(0.16, 1, 0.3, 1);
   --radio-motion-indicator-duration: 180ms;
   --radio-motion-selected-duration: 260ms;
-  --radio-motion-pressed-scale: 0.96px;
-  --radio-motion-active-scale: 0.92px;
-  --radio-motion-pressed-opacity: 0.8px;
+  --radio-motion-pressed-scale: 0.96;
+  --radio-motion-active-scale: 0.92;
+  --radio-motion-pressed-opacity: 0.8;
   --radio-default-bg: #2F2A42;
   --radio-default-fg: #F4F1FB;
   --radio-default-border: #4F4867;
@@ -4648,7 +4670,7 @@
   --tooltip-content-compact-line-height: 16px;
   --tooltip-content-animation-duration: 150ms;
   --tooltip-content-translate-y: 2px;
-  --tooltip-content-scale: 0.98px;
+  --tooltip-content-scale: 0.98;
   --tooltip-arrow-bg: #2F2A42;
   --tooltip-arrow-size: 10px;
   --tooltip-arrow-compact-size: 6px;
@@ -5929,8 +5951,8 @@
   --popover-content-shadow-native-y: 12px;
   --popover-content-shadow-native-blur: 32px;
   --popover-content-shadow-native-color: #000000;
-  --popover-content-shadow-native-opacity: 0.1px;
-  --popover-content-shadow-native-elevation: 8px;
+  --popover-content-shadow-native-opacity: 0.1;
+  --popover-content-shadow-native-elevation: 8;
   --popover-content-border-width: 1px;
   --popover-content-radius: 16px;
   --popover-content-padding: 16px;
@@ -5964,9 +5986,9 @@
   --radio-motion-easing: cubic-bezier(0.16, 1, 0.3, 1);
   --radio-motion-indicator-duration: 180ms;
   --radio-motion-selected-duration: 260ms;
-  --radio-motion-pressed-scale: 0.96px;
-  --radio-motion-active-scale: 0.92px;
-  --radio-motion-pressed-opacity: 0.8px;
+  --radio-motion-pressed-scale: 0.96;
+  --radio-motion-active-scale: 0.92;
+  --radio-motion-pressed-opacity: 0.8;
   --radio-default-bg: #000000;
   --radio-default-fg: #FFFFFF;
   --radio-default-border: #9CA3AF;
@@ -6958,7 +6980,7 @@
   --tooltip-content-compact-line-height: 16px;
   --tooltip-content-animation-duration: 150ms;
   --tooltip-content-translate-y: 2px;
-  --tooltip-content-scale: 0.98px;
+  --tooltip-content-scale: 0.98;
   --tooltip-arrow-bg: #FFFFFF;
   --tooltip-arrow-size: 10px;
   --tooltip-arrow-compact-size: 6px;

package/dist/dark/components/modal.d.ts

@@ -18,7 +18,7 @@ export declare const modal: {
         readonly nativeMaxHeight: "90%";
         readonly viewportMargin: number;
         readonly topOffset: number;
-        readonly zIndexOffset: "1";
+        readonly zIndexOffset: 1;
         readonly animationDuration: "180ms";
         readonly size: {
             readonly sm: 400;

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

@@ -3,6 +3,7 @@ export { border } from './border.js';
 export { control } from './control.js';
 export { divider } from './divider.js';
 export { focus } from './focus.js';
+export { icons } from './icons.js';
 export { menu } from './menu.js';
 export { navigation } from './navigation.js';
 export { overlay } from './overlay.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/dark/semantic/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/dark/semantic/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC"}

package/dist/dark/semantic/index.js

@@ -3,6 +3,7 @@ export { border } from './border.js';
 export { control } from './control.js';
 export { divider } from './divider.js';
 export { focus } from './focus.js';
+export { icons } from './icons.js';
 export { menu } from './menu.js';
 export { navigation } from './navigation.js';
 export { overlay } from './overlay.js';

package/dist/factories/createModalTokens.d.ts

@@ -84,7 +84,7 @@ export declare const createModalTokens: (config: ModalTokensConfig) => {
         readonly nativeMaxHeight: "90%";
         readonly viewportMargin: number;
         readonly topOffset: number;
-        readonly zIndexOffset: "1";
+        readonly zIndexOffset: 1;
         readonly animationDuration: "180ms";
         readonly size: {
             readonly sm: 400;
@@ -165,7 +165,7 @@ export declare const createModalTokensFromSemantics: ({ closeButtonHoverBg, clos
         readonly nativeMaxHeight: "90%";
         readonly viewportMargin: number;
         readonly topOffset: number;
-        readonly zIndexOffset: "1";
+        readonly zIndexOffset: 1;
         readonly animationDuration: "180ms";
         readonly size: {
             readonly sm: 400;

package/dist/factories/createModalTokens.js

@@ -1,7 +1,7 @@
 const modalLayout = {
     maxHeight: '90vh',
     nativeMaxHeight: '90%',
-    zIndexOffset: '1',
+    zIndexOffset: 1,
 };
 const modalMotion = {
     closeDuration: '150ms',

package/dist/highContrast/components/modal.d.ts

@@ -18,7 +18,7 @@ export declare const modal: {
         readonly nativeMaxHeight: "90%";
         readonly viewportMargin: number;
         readonly topOffset: number;
-        readonly zIndexOffset: "1";
+        readonly zIndexOffset: 1;
         readonly animationDuration: "180ms";
         readonly size: {
             readonly sm: 400;

package/dist/light/components/modal.d.ts

@@ -18,7 +18,7 @@ export declare const modal: {
         readonly nativeMaxHeight: "90%";
         readonly viewportMargin: number;
         readonly topOffset: number;
-        readonly zIndexOffset: "1";
+        readonly zIndexOffset: 1;
         readonly animationDuration: "180ms";
         readonly size: {
             readonly sm: 400;

package/dist/light/semantic/index.d.ts

@@ -3,6 +3,7 @@ export { border } from './border.js';
 export { control } from './control.js';
 export { divider } from './divider.js';
 export { focus } from './focus.js';
+export { icons } from './icons.js';
 export { menu } from './menu.js';
 export { navigation } from './navigation.js';
 export { overlay } from './overlay.js';

package/dist/light/semantic/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/light/semantic/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/light/semantic/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC"}

package/dist/light/semantic/index.js

@@ -3,6 +3,7 @@ export { border } from './border.js';
 export { control } from './control.js';
 export { divider } from './divider.js';
 export { focus } from './focus.js';
+export { icons } from './icons.js';
 export { menu } from './menu.js';
 export { navigation } from './navigation.js';
 export { overlay } from './overlay.js';

package/dist/preservation/token-migrations.d.ts

@@ -0,0 +1,90 @@
+export declare const tokenPreservationBaselineRevisionV1: "c218cd97244cf5738bb22b9fb1e5ce172c0f516a";
+export declare const tokenMigrationKinds: readonly ["rename", "alias", "remove", "addition", "representation-change", "visual-change"];
+export type TokenMigrationKind = (typeof tokenMigrationKinds)[number];
+export declare const tokenMigrationThemeNames: readonly ["light", "dark", "high-contrast"];
+export type TokenMigrationThemeName = (typeof tokenMigrationThemeNames)[number];
+export declare const tokenMigrationPlatforms: readonly ["web", "react-native"];
+export type TokenMigrationPlatform = (typeof tokenMigrationPlatforms)[number];
+type TokenMigrationBase = {
+    id: string;
+    issue: `#${number}`;
+    reason: string;
+    themes?: readonly TokenMigrationThemeName[];
+    platforms?: readonly TokenMigrationPlatform[];
+};
+export type TokenRenameMigration = TokenMigrationBase & {
+    kind: 'rename';
+    from: string;
+    to: string;
+};
+export type TokenAliasMigration = TokenMigrationBase & {
+    kind: 'alias';
+    from: string;
+    to: string;
+};
+export type TokenRemovalMigration = TokenMigrationBase & {
+    kind: 'remove';
+    from: string;
+};
+export type TokenAdditionMigration = TokenMigrationBase & {
+    kind: 'addition';
+    to: string;
+};
+type TokenRepresentationMigrationBase = Omit<TokenMigrationBase, 'platforms'> & {
+    kind: 'representation-change';
+    from: string;
+    to?: string;
+    equivalence: string;
+    evidence: string;
+};
+export type TokenCanonicalRepresentationMigration = TokenRepresentationMigrationBase & {
+    layer: 'canonical';
+    platforms?: never;
+};
+export type TokenPlatformRepresentationMigration = TokenRepresentationMigrationBase & {
+    layer: 'platform-output';
+    platforms: readonly [TokenMigrationPlatform, ...TokenMigrationPlatform[]];
+};
+export type TokenRepresentationMigration = TokenCanonicalRepresentationMigration | TokenPlatformRepresentationMigration;
+export type TokenVisualChangeMigration = TokenMigrationBase & {
+    kind: 'visual-change';
+    from?: string;
+    to?: string;
+    approved: true;
+    approvalEvidence: string;
+};
+export type TokenMigrationEntry = TokenRenameMigration | TokenAliasMigration | TokenRemovalMigration | TokenAdditionMigration | TokenRepresentationMigration | TokenVisualChangeMigration;
+/**
+ * Migration/test metadata only. This is not a runtime token registry.
+ *
+ * Every #879 token rename, alias, removal, addition, representation-only
+ * change, or intentionally approved visual change must be recorded here before
+ * the preservation baseline is allowed to accept it.
+ */
+export declare const tokenMigrationManifestV1: ({
+    id: string;
+    kind: "representation-change";
+    layer: "canonical";
+    issue: "#881";
+    reason: string;
+    from: string;
+    equivalence: string;
+    evidence: string;
+    platforms?: undefined;
+    approved?: undefined;
+    approvalEvidence?: undefined;
+} | {
+    id: string;
+    kind: "visual-change";
+    issue: "#881";
+    platforms: "web"[];
+    reason: string;
+    from: string;
+    approved: true;
+    approvalEvidence: string;
+    layer?: undefined;
+    equivalence?: undefined;
+    evidence?: undefined;
+})[];
+export {};
+//# sourceMappingURL=token-migrations.d.ts.map

package/dist/preservation/token-migrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-migrations.d.ts","sourceRoot":"","sources":["../../src/preservation/token-migrations.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,mCAAmC,EAC9C,0CAAmD,CAAC;AAEtD,eAAO,MAAM,mBAAmB,8FAOtB,CAAC;AAEX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE,eAAO,MAAM,wBAAwB,6CAI3B,CAAC;AAEX,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhF,eAAO,MAAM,uBAAuB,kCAAmC,CAAC;AAExE,MAAM,MAAM,sBAAsB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9E,KAAK,kBAAkB,GAAG;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,IAAI,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,SAAS,uBAAuB,EAAE,CAAC;IAC5C,SAAS,CAAC,EAAE,SAAS,sBAAsB,EAAE,CAAC;CAC/C,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,kBAAkB,GAAG;IACtD,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,kBAAkB,GAAG;IACrD,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG,kBAAkB,GAAG;IACvD,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG,kBAAkB,GAAG;IACxD,IAAI,EAAE,UAAU,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;CACZ,CAAC;AAEF,KAAK,gCAAgC,GAAG,IAAI,CAC1C,kBAAkB,EAClB,WAAW,CACZ,GAAG;IACF,IAAI,EAAE,uBAAuB,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAIF,MAAM,MAAM,qCAAqC,GAC/C,gCAAgC,GAAG;IACjC,KAAK,EAAE,WAAW,CAAC;IACnB,SAAS,CAAC,EAAE,KAAK,CAAC;CACnB,CAAC;AAEJ,MAAM,MAAM,oCAAoC,GAC9C,gCAAgC,GAAG;IACjC,KAAK,EAAE,iBAAiB,CAAC;IACzB,SAAS,EAAE,SAAS,CAAC,sBAAsB,EAAE,GAAG,sBAAsB,EAAE,CAAC,CAAC;CAC3E,CAAC;AAEJ,MAAM,MAAM,4BAA4B,GACtC,qCAAqC,GAAG,oCAAoC,CAAC;AAE/E,MAAM,MAAM,0BAA0B,GAAG,kBAAkB,GAAG;IAC5D,IAAI,EAAE,eAAe,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,IAAI,CAAC;IACf,gBAAgB,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAC3B,oBAAoB,GACpB,mBAAmB,GACnB,qBAAqB,GACrB,sBAAsB,GACtB,4BAA4B,GAC5B,0BAA0B,CAAC;AAK/B;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;IAgFK,CAAC"}

package/dist/preservation/token-migrations.js

@@ -0,0 +1,95 @@
+export const tokenPreservationBaselineRevisionV1 = 'c218cd97244cf5738bb22b9fb1e5ce172c0f516a';
+export const tokenMigrationKinds = [
+    'rename',
+    'alias',
+    'remove',
+    'addition',
+    'representation-change',
+    'visual-change',
+];
+export const tokenMigrationThemeNames = [
+    'light',
+    'dark',
+    'high-contrast',
+];
+export const tokenMigrationPlatforms = ['web', 'react-native'];
+const valueKindWebFixApproval = '#881 explicitly requires correcting invalid unitless CSS serialization; targeted serializer regressions and the pinned Linux visual suite are the approval evidence.';
+/**
+ * Migration/test metadata only. This is not a runtime token registry.
+ *
+ * Every #879 token rename, alias, removal, addition, representation-only
+ * change, or intentionally approved visual change must be recorded here before
+ * the preservation baseline is allowed to accept it.
+ */
+export const tokenMigrationManifestV1 = [
+    {
+        id: '881-modal-z-index-offset-number',
+        kind: 'representation-change',
+        layer: 'canonical',
+        issue: '#881',
+        reason: 'Remove a stringified-number workaround now that z-index/order has a canonical unitless numeric kind.',
+        from: 'components.modal.content.zIndexOffset',
+        equivalence: 'Canonical "1" and numeric 1 represent the same stack offset; Web serialization remains the literal value 1.',
+        evidence: 'The value-kind serializer regression locks Web output to 1 and current first-party Modal renderers do not consume the old string representation directly.',
+    },
+    {
+        id: '881-radio-pressed-scale-web',
+        kind: 'visual-change',
+        issue: '#881',
+        platforms: ['web'],
+        reason: 'Correct Radio pressed scale from invalid px-suffixed transform input to the intended unitless scale.',
+        from: 'components.radio.motion.pressedScale',
+        approved: true,
+        approvalEvidence: valueKindWebFixApproval,
+    },
+    {
+        id: '881-radio-active-scale-web',
+        kind: 'visual-change',
+        issue: '#881',
+        platforms: ['web'],
+        reason: 'Correct Radio active scale from invalid px-suffixed transform input to the intended unitless scale.',
+        from: 'components.radio.motion.activeScale',
+        approved: true,
+        approvalEvidence: valueKindWebFixApproval,
+    },
+    {
+        id: '881-radio-pressed-opacity-web',
+        kind: 'visual-change',
+        issue: '#881',
+        platforms: ['web'],
+        reason: 'Correct Radio pressed opacity from invalid px-suffixed output to the intended unitless opacity.',
+        from: 'components.radio.motion.pressedOpacity',
+        approved: true,
+        approvalEvidence: valueKindWebFixApproval,
+    },
+    {
+        id: '881-tooltip-scale-web',
+        kind: 'visual-change',
+        issue: '#881',
+        platforms: ['web'],
+        reason: 'Correct Tooltip content scale from invalid px-suffixed transform input to the intended unitless scale.',
+        from: 'components.tooltip.content.scale',
+        approved: true,
+        approvalEvidence: valueKindWebFixApproval,
+    },
+    {
+        id: '881-popover-native-shadow-opacity-web',
+        kind: 'visual-change',
+        issue: '#881',
+        platforms: ['web'],
+        reason: 'Publish the native Popover shadow opacity with its canonical unitless representation instead of an invalid px suffix.',
+        from: 'components.popover.content.shadow.native.opacity',
+        approved: true,
+        approvalEvidence: valueKindWebFixApproval,
+    },
+    {
+        id: '881-popover-native-shadow-elevation-web',
+        kind: 'visual-change',
+        issue: '#881',
+        platforms: ['web'],
+        reason: 'Publish the native Popover shadow elevation with its canonical unitless representation instead of an invalid px suffix.',
+        from: 'components.popover.content.shadow.native.elevation',
+        approved: true,
+        approvalEvidence: valueKindWebFixApproval,
+    },
+];

package/dist/token-architecture.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Canonical token architecture metadata for tooling, Generator V2, and agents.
+ *
+ * This file intentionally describes ownership, vocabulary, and audit findings
+ * without changing any resolved token value.
+ */
+export declare const tokenArchitectureLayers: readonly ["primitive", "semantic", "component-factory", "component", "platform-output", "consumer"];
+export declare const tokenArchitectureFlow: "primitive -> semantic -> component-factory -> component -> platform-output -> consumer";
+export declare const tokenValueKinds: readonly ["color", "length", "unitless-number", "opacity", "scale", "z-index", "duration", "easing", "shadow", "font-family", "font-weight", "font-size", "line-height", "raw-string"];
+export type TokenValueKind = (typeof tokenValueKinds)[number];
+export declare const tokenValueKindWebContract: {
+    readonly color: {
+        readonly numericUnit: null;
+    };
+    readonly length: {
+        readonly numericUnit: "px";
+    };
+    readonly 'unitless-number': {
+        readonly numericUnit: "";
+    };
+    readonly opacity: {
+        readonly numericUnit: "";
+    };
+    readonly scale: {
+        readonly numericUnit: "";
+    };
+    readonly 'z-index': {
+        readonly numericUnit: "";
+    };
+    readonly duration: {
+        readonly numericUnit: "ms";
+    };
+    readonly easing: {
+        readonly numericUnit: null;
+    };
+    readonly shadow: {
+        readonly numericUnit: null;
+    };
+    readonly 'font-family': {
+        readonly numericUnit: null;
+    };
+    readonly 'font-weight': {
+        readonly numericUnit: "";
+    };
+    readonly 'font-size': {
+        readonly numericUnit: "px";
+    };
+    readonly 'line-height': {
+        readonly numericUnit: "px";
+    };
+    readonly 'raw-string': {
+        readonly numericUnit: null;
+    };
+};
+/**
+ * Canonical numeric role families. Matching is by semantic role words, not by
+ * one-off full token paths. Compound roles may put the semantic family at
+ * either edge (`paddingBottom`, `borderWidth`, `contentScale`), and nested
+ * scales may inherit meaning from their nearest parent role (`size.sm`).
+ */
+export declare const canonicalComponentNumericRoleFamilies: {
+    readonly scale: readonly ["scale"];
+    readonly opacity: readonly ["opacity"];
+    readonly 'z-index': readonly ["zIndex", "zIndexOffset", "order"];
+    readonly 'unitless-number': readonly ["elevation"];
+    readonly 'font-weight': readonly ["fontWeight"];
+    readonly 'font-size': readonly ["fontSize"];
+    readonly 'line-height': readonly ["lineHeight"];
+    readonly duration: readonly ["duration"];
+    readonly length: readonly ["width", "height", "size", "gap", "padding", "paddingX", "paddingY", "radius", "margin", "marginX", "marginY", "offset", "blur", "translateX", "translateY", "travel"];
+};
+/**
+ * Resolve the canonical value kind for a scalar token path.
+ *
+ * Unknown strings remain explicit raw strings because CSS accepts many
+ * renderer-specific string representations. Unknown numeric paths are rejected
+ * by `requireTokenValueKind`: a number must always declare meaning through the
+ * canonical namespace or role vocabulary before it can reach a renderer.
+ */
+export declare function resolveTokenValueKind(tokenPath: string, value: string | number): TokenValueKind | null;
+export declare function requireTokenValueKind(tokenPath: string, value: string | number): TokenValueKind;
+export declare const canonicalTokenVocabulary: {
+    readonly surface: readonly ["canvas", "default", "subtle", "muted", "elevated", "hover", "active", "pressed", "disabled", "danger", "inverse"];
+    readonly state: readonly ["default", "hover", "active", "pressed", "selected", "disabled", "focus"];
+    readonly foreground: readonly ["primary", "secondary", "muted", "subtle", "disabled", "brand", "interactive", "interactiveHover", "interactiveActive", "inverse"];
+    readonly border: readonly ["subtle", "muted", "default", "strong", "elevated", "disabled"];
+    readonly intent: readonly ["primary", "neutral", "success", "warning", "danger"];
+    readonly status: readonly ["success", "error", "warning", "info"];
+};
+export declare const canonicalSemanticRolePaths: readonly ["surface.canvas", "surface.default", "surface.subtle", "surface.muted", "surface.elevated", "surface.hover", "surface.active", "surface.pressed", "surface.disabled", "surface.danger", "surface.inverse", "text.primary", "text.secondary", "text.muted", "text.subtle", "text.disabled", "text.brand", "text.interactive", "text.interactiveHover", "text.interactiveActive", "text.inverse", "border.subtle", "border.muted", "border.default", "border.strong", "border.elevated", "border.disabled", "border.focus", "divider.muted", "divider.default", "divider.strong", "focus.ring.color", "focus.ring.width", "focus.ring.shadow", "focus.ring.offset", "status.success.fg", "status.success.bg", "status.success.border", "status.success.ring", "status.success.strong", "status.error.fg", "status.error.bg", "status.error.border", "status.error.ring", "status.error.strong", "status.warning.fg", "status.warning.bg", "status.warning.border", "status.warning.ring", "status.warning.strong", "status.info.fg", "status.info.bg", "status.info.border", "status.info.ring", "status.info.strong", "overlay.backdrop", "overlay.tooltip.bg", "overlay.tooltip.fg", "overlay.tooltip.border", "overlay.popover.bg", "overlay.popover.border", "overlay.modal.bg", "overlay.modal.border"];
+export declare const componentTokenFactoryModel: {
+    readonly canonicalName: "create<Component>Tokens";
+    readonly legacyPaletteName: "create<Component>Palette is retained when the component exposes intent palettes.";
+    readonly role: "Factories compose semantic inputs and stable implementation primitives into component contracts.";
+    readonly transparentPrimitive: "transparent is an implementation primitive for absent paint, not a theme color.";
+    readonly generatorRule: "Reuse an existing factory when a generated component has equivalent state vocabulary; extend a reusable factory only when the existing component contract needs a stable shared state; introduce a component-specific factory only for a reusable component contract that generic semantic roles cannot express.";
+};
+export declare const maintainedComponentFactories: readonly [{
+    readonly name: "createAccordionTokens";
+    readonly source: "packages/tokens/src/factories/createAccordionTokens.ts";
+    readonly semanticAdapter: "createAccordionTokensFromSemantics";
+    readonly stateKeys: readonly ["default", "expanded", "hover", "pressed", "disabled"];
+}, {
+    readonly name: "createButtonPalette";
+    readonly source: "packages/tokens/src/factories/createButtonPalette.ts";
+    readonly semanticAdapter: null;
+    readonly stateKeys: readonly ["default", "hover", "pressed"];
+}, {
+    readonly name: "createCheckboxPalette";
+    readonly source: "packages/tokens/src/factories/createCheckboxPalette.ts";
+    readonly semanticAdapter: null;
+    readonly stateKeys: readonly ["default", "hover", "pressed"];
+}, {
+    readonly name: "createContextMenuTokens";
+    readonly source: "packages/tokens/src/factories/createContextMenuTokens.ts";
+    readonly semanticAdapter: "createContextMenuTokensFromSemantics";
+    readonly stateKeys: readonly ["default", "hover", "active", "pressed", "focus", "disabled"];
+}, {
+    readonly name: "createDropdownPalette";
+    readonly source: "packages/tokens/src/factories/createDropdownPalette.ts";
+    readonly semanticAdapter: null;
+    readonly stateKeys: readonly ["default", "hover", "focus", "active", "pressed"];
+}, {
+    readonly name: "createFormFieldTokensFromTheme";
+    readonly source: "packages/tokens/src/factories/createFormFieldTokens.ts";
+    readonly semanticAdapter: "createFormFieldTokensFromTheme";
+    readonly stateKeys: readonly ["default", "error", "success", "warning", "info", "disabled"];
+}, {
+    readonly name: "createInputPalette";
+    readonly source: "packages/tokens/src/factories/createInputPalette.ts";
+    readonly semanticAdapter: null;
+    readonly stateKeys: readonly ["default", "hover", "focus"];
+}, {
+    readonly name: "createModalTokens";
+    readonly source: "packages/tokens/src/factories/createModalTokens.ts";
+    readonly semanticAdapter: "createModalTokensFromSemantics";
+    readonly stateKeys: readonly ["default", "hover", "pressed", "focus", "disabled"];
+}, {
+    readonly name: "createPopoverTokens";
+    readonly source: "packages/tokens/src/factories/createPopoverTokens.ts";
+    readonly semanticAdapter: "createPopoverTokensFromTheme";
+    readonly stateKeys: readonly ["default"];
+}, {
+    readonly name: "createRadioGroupTokens";
+    readonly source: "packages/tokens/src/factories/createRadioGroupTokens.ts";
+    readonly semanticAdapter: "createRadioGroupTokensFromSpacing";
+    readonly stateKeys: readonly ["default"];
+}, {
+    readonly name: "createRadioPalette";
+    readonly source: "packages/tokens/src/factories/createRadioPalette.ts";
+    readonly semanticAdapter: null;
+    readonly stateKeys: readonly ["default", "hover", "pressed"];
+}, {
+    readonly name: "createSelectPalette";
+    readonly source: "packages/tokens/src/factories/createSelectPalette.ts";
+    readonly semanticAdapter: null;
+    readonly stateKeys: readonly ["default", "hover", "focus", "active", "pressed", "selected", "selectedHover", "selectedActive", "selectedPressed"];
+}, {
+    readonly name: "createSwitchTokens";
+    readonly source: "packages/tokens/src/factories/createSwitchTokens.ts";
+    readonly semanticAdapter: "createSwitchTokensFromSemantics";
+    readonly stateKeys: readonly ["default", "hover", "pressed", "disabled"];
+}, {
+    readonly name: "createTabsTokens";
+    readonly source: "packages/tokens/src/factories/createTabsTokens.ts";
+    readonly semanticAdapter: null;
+    readonly stateKeys: readonly ["default", "hover", "active", "disabled"];
+}, {
+    readonly name: "createTooltipTokens";
+    readonly source: "packages/tokens/src/factories/createTooltipTokens.ts";
+    readonly semanticAdapter: "createTooltipTokensFromTheme";
+    readonly stateKeys: readonly ["default"];
+}];
+export declare const tokenArchitectureAuditFindings: readonly [{
+    readonly id: "semantic-shape-parity";
+    readonly classification: "A";
+    readonly summary: "Light, dark, and high-contrast themes expose the same semantic token shape.";
+}, {
+    readonly id: "component-shape-parity";
+    readonly classification: "A";
+    readonly summary: "Light, dark, and high-contrast themes expose the same component token shape.";
+}, {
+    readonly id: "factory-layer";
+    readonly classification: "E";
+    readonly summary: "Component token factories are a first-class layer for stable component state contracts.";
+}, {
+    readonly id: "website-text-tertiary";
+    readonly classification: "H";
+    readonly summary: "Website CSS references --text-tertiary, which is not a canonical semantic token. Adding or remapping it would visibly affect website text and should be handled by a focused visual issue.";
+}, {
+    readonly id: "website-demo-raw-border";
+    readonly classification: "H";
+    readonly summary: "Some component catalog examples use raw demonstration border colors. Replacing them with tokens may alter examples and should be handled only with explicit visual approval.";
+}];
+//# sourceMappingURL=token-architecture.d.ts.map

package/dist/token-architecture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-architecture.d.ts","sourceRoot":"","sources":["../src/token-architecture.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,uBAAuB,qGAO1B,CAAC;AAEX,eAAO,MAAM,qBAAqB,EAChC,wFAAiG,CAAC;AAEpG,eAAO,MAAM,eAAe,wLAelB,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9D,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkBrC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,qCAAqC;;;;;;;;;;CA2BqB,CAAC;AAsHxE;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GAAG,MAAM,GACrB,cAAc,GAAG,IAAI,CAwCvB;AAED,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GAAG,MAAM,GACrB,cAAc,CAQhB;AAED,eAAO,MAAM,wBAAwB;;;;;;;CAsC3B,CAAC;AAEX,eAAO,MAAM,0BAA0B,svCAgE7B,CAAC;AAEX,eAAO,MAAM,0BAA0B;;;;;;CAS7B,CAAC;AAEX,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqG/B,CAAC;AAEX,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;EA+BjC,CAAC"}

package/dist/token-architecture.js

@@ -0,0 +1,461 @@
+/**
+ * Canonical token architecture metadata for tooling, Generator V2, and agents.
+ *
+ * This file intentionally describes ownership, vocabulary, and audit findings
+ * without changing any resolved token value.
+ */
+export const tokenArchitectureLayers = [
+    'primitive',
+    'semantic',
+    'component-factory',
+    'component',
+    'platform-output',
+    'consumer',
+];
+export const tokenArchitectureFlow = 'primitive -> semantic -> component-factory -> component -> platform-output -> consumer';
+export const tokenValueKinds = [
+    'color',
+    'length',
+    'unitless-number',
+    'opacity',
+    'scale',
+    'z-index',
+    'duration',
+    'easing',
+    'shadow',
+    'font-family',
+    'font-weight',
+    'font-size',
+    'line-height',
+    'raw-string',
+];
+export const tokenValueKindWebContract = {
+    color: { numericUnit: null },
+    length: { numericUnit: 'px' },
+    'unitless-number': { numericUnit: '' },
+    opacity: { numericUnit: '' },
+    scale: { numericUnit: '' },
+    'z-index': { numericUnit: '' },
+    duration: { numericUnit: 'ms' },
+    easing: { numericUnit: null },
+    shadow: { numericUnit: null },
+    'font-family': { numericUnit: null },
+    'font-weight': { numericUnit: '' },
+    'font-size': { numericUnit: 'px' },
+    'line-height': { numericUnit: 'px' },
+    'raw-string': { numericUnit: null },
+};
+/**
+ * Canonical numeric role families. Matching is by semantic role words, not by
+ * one-off full token paths. Compound roles may put the semantic family at
+ * either edge (`paddingBottom`, `borderWidth`, `contentScale`), and nested
+ * scales may inherit meaning from their nearest parent role (`size.sm`).
+ */
+export const canonicalComponentNumericRoleFamilies = {
+    scale: ['scale'],
+    opacity: ['opacity'],
+    'z-index': ['zIndex', 'zIndexOffset', 'order'],
+    'unitless-number': ['elevation'],
+    'font-weight': ['fontWeight'],
+    'font-size': ['fontSize'],
+    'line-height': ['lineHeight'],
+    duration: ['duration'],
+    length: [
+        'width',
+        'height',
+        'size',
+        'gap',
+        'padding',
+        'paddingX',
+        'paddingY',
+        'radius',
+        'margin',
+        'marginX',
+        'marginY',
+        'offset',
+        'blur',
+        'translateX',
+        'translateY',
+        'travel',
+    ],
+};
+const componentStringRoleFamilies = {
+    duration: ['duration'],
+    easing: ['easing'],
+    color: [
+        'bg',
+        'fg',
+        'border',
+        'ring',
+        'color',
+        'placeholder',
+        'icon',
+        'indicator',
+        'divider',
+    ],
+    shadow: ['shadow'],
+};
+function lastTokenPathSegment(tokenPath) {
+    return tokenPath.split('.').at(-1) ?? '';
+}
+function splitRoleWords(role) {
+    return role
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/[^a-zA-Z0-9]+/g, ' ')
+        .trim()
+        .toLowerCase()
+        .split(/\s+/)
+        .filter(Boolean);
+}
+function matchesRoleFamily(role, families) {
+    const roleWords = splitRoleWords(role);
+    return families.some((family) => {
+        const familyWords = splitRoleWords(family);
+        if (familyWords.length > roleWords.length)
+            return false;
+        const prefixMatches = familyWords.every((word, index) => roleWords[index] === word);
+        const suffixStart = roleWords.length - familyWords.length;
+        const suffixMatches = familyWords.every((word, index) => roleWords[suffixStart + index] === word);
+        return prefixMatches || suffixMatches;
+    });
+}
+function resolveRoleKind(role, families) {
+    for (const [kind, roleFamilies] of Object.entries(families)) {
+        if (matchesRoleFamily(role, roleFamilies))
+            return kind;
+    }
+    return null;
+}
+function resolveShadowLeafKind(tokenPath) {
+    const role = lastTokenPathSegment(tokenPath).toLowerCase();
+    if (role === 'x' || role === 'y' || role === 'blur')
+        return 'length';
+    if (role === 'opacity')
+        return 'opacity';
+    if (role === 'elevation')
+        return 'unitless-number';
+    if (role === 'color')
+        return 'color';
+    return null;
+}
+function componentRoleSegments(tokenPath) {
+    const segments = tokenPath.split('.');
+    if (tokenPath.startsWith('components.') ||
+        tokenPath.startsWith('tokens.controlSizes.')) {
+        return segments.slice(2);
+    }
+    return segments;
+}
+function resolveComponentValueKind(tokenPath, value) {
+    if (tokenPath.includes('.shadow.native.')) {
+        const shadowKind = resolveShadowLeafKind(tokenPath);
+        if (shadowKind)
+            return shadowKind;
+    }
+    const roleSegments = componentRoleSegments(tokenPath);
+    // Token meaning comes from its canonical path, not from the runtime storage
+    // type. This keeps stringified numeric workarounds visible to validation.
+    for (let index = roleSegments.length - 1; index >= 0; index -= 1) {
+        const numericRoleKind = resolveRoleKind(roleSegments[index], canonicalComponentNumericRoleFamilies);
+        if (numericRoleKind)
+            return numericRoleKind;
+    }
+    if (typeof value === 'number')
+        return null;
+    const role = roleSegments.at(-1) ?? '';
+    return resolveRoleKind(role, componentStringRoleFamilies) ?? 'raw-string';
+}
+/**
+ * Resolve the canonical value kind for a scalar token path.
+ *
+ * Unknown strings remain explicit raw strings because CSS accepts many
+ * renderer-specific string representations. Unknown numeric paths are rejected
+ * by `requireTokenValueKind`: a number must always declare meaning through the
+ * canonical namespace or role vocabulary before it can reach a renderer.
+ */
+export function resolveTokenValueKind(tokenPath, value) {
+    if (tokenPath.startsWith('colors.'))
+        return 'color';
+    if (tokenPath.startsWith('primitives.overlay.'))
+        return 'color';
+    if (tokenPath.startsWith('semantic.')) {
+        if (tokenPath.startsWith('semantic.shadow.') ||
+            tokenPath.endsWith('.shadow')) {
+            return 'shadow';
+        }
+        if (tokenPath === 'semantic.focus.ring.width')
+            return 'length';
+        return 'color';
+    }
+    if (tokenPath.startsWith('tokens.spacing.'))
+        return 'length';
+    if (tokenPath.startsWith('tokens.radius.'))
+        return 'length';
+    if (tokenPath.startsWith('tokens.zIndex.'))
+        return 'z-index';
+    if (tokenPath.startsWith('tokens.typography.family.'))
+        return 'font-family';
+    if (tokenPath.startsWith('tokens.typography.weight.'))
+        return 'font-weight';
+    if (tokenPath.startsWith('tokens.typography.size.'))
+        return 'font-size';
+    if (tokenPath.startsWith('tokens.typography.lineHeight.')) {
+        return 'line-height';
+    }
+    if (tokenPath.startsWith('tokens.shadows.')) {
+        return resolveShadowLeafKind(tokenPath);
+    }
+    if (tokenPath.startsWith('tokens.controlSizes.')) {
+        return resolveComponentValueKind(tokenPath, value);
+    }
+    if (tokenPath.startsWith('components.')) {
+        return resolveComponentValueKind(tokenPath, value);
+    }
+    return typeof value === 'number' ? null : 'raw-string';
+}
+export function requireTokenValueKind(tokenPath, value) {
+    const kind = resolveTokenValueKind(tokenPath, value);
+    if (kind)
+        return kind;
+    throw new Error(`Unknown numeric token value kind for "${tokenPath}". Add a canonical namespace or role rule before serializing this token.`);
+}
+export const canonicalTokenVocabulary = {
+    surface: [
+        'canvas',
+        'default',
+        'subtle',
+        'muted',
+        'elevated',
+        'hover',
+        'active',
+        'pressed',
+        'disabled',
+        'danger',
+        'inverse',
+    ],
+    state: [
+        'default',
+        'hover',
+        'active',
+        'pressed',
+        'selected',
+        'disabled',
+        'focus',
+    ],
+    foreground: [
+        'primary',
+        'secondary',
+        'muted',
+        'subtle',
+        'disabled',
+        'brand',
+        'interactive',
+        'interactiveHover',
+        'interactiveActive',
+        'inverse',
+    ],
+    border: ['subtle', 'muted', 'default', 'strong', 'elevated', 'disabled'],
+    intent: ['primary', 'neutral', 'success', 'warning', 'danger'],
+    status: ['success', 'error', 'warning', 'info'],
+};
+export const canonicalSemanticRolePaths = [
+    'surface.canvas',
+    'surface.default',
+    'surface.subtle',
+    'surface.muted',
+    'surface.elevated',
+    'surface.hover',
+    'surface.active',
+    'surface.pressed',
+    'surface.disabled',
+    'surface.danger',
+    'surface.inverse',
+    'text.primary',
+    'text.secondary',
+    'text.muted',
+    'text.subtle',
+    'text.disabled',
+    'text.brand',
+    'text.interactive',
+    'text.interactiveHover',
+    'text.interactiveActive',
+    'text.inverse',
+    'border.subtle',
+    'border.muted',
+    'border.default',
+    'border.strong',
+    'border.elevated',
+    'border.disabled',
+    'border.focus',
+    'divider.muted',
+    'divider.default',
+    'divider.strong',
+    'focus.ring.color',
+    'focus.ring.width',
+    'focus.ring.shadow',
+    'focus.ring.offset',
+    'status.success.fg',
+    'status.success.bg',
+    'status.success.border',
+    'status.success.ring',
+    'status.success.strong',
+    'status.error.fg',
+    'status.error.bg',
+    'status.error.border',
+    'status.error.ring',
+    'status.error.strong',
+    'status.warning.fg',
+    'status.warning.bg',
+    'status.warning.border',
+    'status.warning.ring',
+    'status.warning.strong',
+    'status.info.fg',
+    'status.info.bg',
+    'status.info.border',
+    'status.info.ring',
+    'status.info.strong',
+    'overlay.backdrop',
+    'overlay.tooltip.bg',
+    'overlay.tooltip.fg',
+    'overlay.tooltip.border',
+    'overlay.popover.bg',
+    'overlay.popover.border',
+    'overlay.modal.bg',
+    'overlay.modal.border',
+];
+export const componentTokenFactoryModel = {
+    canonicalName: 'create<Component>Tokens',
+    legacyPaletteName: 'create<Component>Palette is retained when the component exposes intent palettes.',
+    role: 'Factories compose semantic inputs and stable implementation primitives into component contracts.',
+    transparentPrimitive: 'transparent is an implementation primitive for absent paint, not a theme color.',
+    generatorRule: 'Reuse an existing factory when a generated component has equivalent state vocabulary; extend a reusable factory only when the existing component contract needs a stable shared state; introduce a component-specific factory only for a reusable component contract that generic semantic roles cannot express.',
+};
+export const maintainedComponentFactories = [
+    {
+        name: 'createAccordionTokens',
+        source: 'packages/tokens/src/factories/createAccordionTokens.ts',
+        semanticAdapter: 'createAccordionTokensFromSemantics',
+        stateKeys: ['default', 'expanded', 'hover', 'pressed', 'disabled'],
+    },
+    {
+        name: 'createButtonPalette',
+        source: 'packages/tokens/src/factories/createButtonPalette.ts',
+        semanticAdapter: null,
+        stateKeys: ['default', 'hover', 'pressed'],
+    },
+    {
+        name: 'createCheckboxPalette',
+        source: 'packages/tokens/src/factories/createCheckboxPalette.ts',
+        semanticAdapter: null,
+        stateKeys: ['default', 'hover', 'pressed'],
+    },
+    {
+        name: 'createContextMenuTokens',
+        source: 'packages/tokens/src/factories/createContextMenuTokens.ts',
+        semanticAdapter: 'createContextMenuTokensFromSemantics',
+        stateKeys: ['default', 'hover', 'active', 'pressed', 'focus', 'disabled'],
+    },
+    {
+        name: 'createDropdownPalette',
+        source: 'packages/tokens/src/factories/createDropdownPalette.ts',
+        semanticAdapter: null,
+        stateKeys: ['default', 'hover', 'focus', 'active', 'pressed'],
+    },
+    {
+        name: 'createFormFieldTokensFromTheme',
+        source: 'packages/tokens/src/factories/createFormFieldTokens.ts',
+        semanticAdapter: 'createFormFieldTokensFromTheme',
+        stateKeys: ['default', 'error', 'success', 'warning', 'info', 'disabled'],
+    },
+    {
+        name: 'createInputPalette',
+        source: 'packages/tokens/src/factories/createInputPalette.ts',
+        semanticAdapter: null,
+        stateKeys: ['default', 'hover', 'focus'],
+    },
+    {
+        name: 'createModalTokens',
+        source: 'packages/tokens/src/factories/createModalTokens.ts',
+        semanticAdapter: 'createModalTokensFromSemantics',
+        stateKeys: ['default', 'hover', 'pressed', 'focus', 'disabled'],
+    },
+    {
+        name: 'createPopoverTokens',
+        source: 'packages/tokens/src/factories/createPopoverTokens.ts',
+        semanticAdapter: 'createPopoverTokensFromTheme',
+        stateKeys: ['default'],
+    },
+    {
+        name: 'createRadioGroupTokens',
+        source: 'packages/tokens/src/factories/createRadioGroupTokens.ts',
+        semanticAdapter: 'createRadioGroupTokensFromSpacing',
+        stateKeys: ['default'],
+    },
+    {
+        name: 'createRadioPalette',
+        source: 'packages/tokens/src/factories/createRadioPalette.ts',
+        semanticAdapter: null,
+        stateKeys: ['default', 'hover', 'pressed'],
+    },
+    {
+        name: 'createSelectPalette',
+        source: 'packages/tokens/src/factories/createSelectPalette.ts',
+        semanticAdapter: null,
+        stateKeys: [
+            'default',
+            'hover',
+            'focus',
+            'active',
+            'pressed',
+            'selected',
+            'selectedHover',
+            'selectedActive',
+            'selectedPressed',
+        ],
+    },
+    {
+        name: 'createSwitchTokens',
+        source: 'packages/tokens/src/factories/createSwitchTokens.ts',
+        semanticAdapter: 'createSwitchTokensFromSemantics',
+        stateKeys: ['default', 'hover', 'pressed', 'disabled'],
+    },
+    {
+        name: 'createTabsTokens',
+        source: 'packages/tokens/src/factories/createTabsTokens.ts',
+        semanticAdapter: null,
+        stateKeys: ['default', 'hover', 'active', 'disabled'],
+    },
+    {
+        name: 'createTooltipTokens',
+        source: 'packages/tokens/src/factories/createTooltipTokens.ts',
+        semanticAdapter: 'createTooltipTokensFromTheme',
+        stateKeys: ['default'],
+    },
+];
+export const tokenArchitectureAuditFindings = [
+    {
+        id: 'semantic-shape-parity',
+        classification: 'A',
+        summary: 'Light, dark, and high-contrast themes expose the same semantic token shape.',
+    },
+    {
+        id: 'component-shape-parity',
+        classification: 'A',
+        summary: 'Light, dark, and high-contrast themes expose the same component token shape.',
+    },
+    {
+        id: 'factory-layer',
+        classification: 'E',
+        summary: 'Component token factories are a first-class layer for stable component state contracts.',
+    },
+    {
+        id: 'website-text-tertiary',
+        classification: 'H',
+        summary: 'Website CSS references --text-tertiary, which is not a canonical semantic token. Adding or remapping it would visibly affect website text and should be handled by a focused visual issue.',
+    },
+    {
+        id: 'website-demo-raw-border',
+        classification: 'H',
+        summary: 'Some component catalog examples use raw demonstration border colors. Replacing them with tokens may alter examples and should be handled only with explicit visual approval.',
+    },
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellira-ui/tokens",
-  "version": "2.98.3",
+  "version": "2.98.5",
   "description": "Design tokens for Vellira Design System",
   "keywords": [
     "vellira",
@@ -52,10 +52,12 @@
     "clean:build": "node --input-type=module -e \"import fs from 'node:fs'; if (fs.existsSync('dist')) for (const entry of fs.readdirSync('dist')) { if (entry !== 'css') fs.rmSync('dist/' + entry, { recursive: true, force: true }); }\"",
     "generate:types": "tsx scripts/generate-token-types.ts",
     "generate:types:check": "tsx scripts/generate-token-types.ts --check",
+    "preservation:baseline": "tsx scripts/token-preservation-cli.ts --write",
+    "preservation:check": "tsx scripts/token-preservation-cli.ts --check",
     "build:tokens": "pnpm run generate:types && tsx scripts/generate-css.ts",
     "build": "pnpm run clean:build && pnpm run build:tokens && tsc -p tsconfig.build.json",
-    "typecheck": "pnpm run generate:types:check && tsc -p tsconfig.json --noEmit && tsc -p tsconfig.scripts.json --noEmit",
-    "test": "pnpm run generate:types:check && vitest run"
+    "typecheck": "pnpm run generate:types:check && pnpm run preservation:check && tsc -p tsconfig.json --noEmit && tsc -p tsconfig.scripts.json --noEmit",
+    "test": "pnpm run generate:types:check && pnpm run preservation:check && vitest run"
   },
   "publishConfig": {
     "access": "public"