@3fn/core 14.0.0 → 15.0.0

package/src/components/core/Container-Base/platforms/ios/ContainerBase.ios.swift

@@ -11,7 +11,7 @@
  * This ensures cross-platform consistency with Web and Android implementations.
  * 
  * @see ../../../types.ts for ContainerBaseProps interface
- * @see ../../../tokens.ts for token reference mappings
+ * @see ../../../Container-Base.refs.ts for token reference mappings
  * @see .kiro/specs/010-container-component/design.md for complete design documentation
  * @see .kiro/specs/034-component-architecture-system for Stemma System details
  * @see .kiro/specs/031-blend-infrastructure-implementation for blend utilities
@@ -658,12 +658,12 @@ func mapContainerBaseBorderRadiusToCornerRadius(_ borderRadius: ContainerBaseBor
 }
 
 func mapContainerBaseBorderToLineWidth(_ border: ContainerBaseBorderValue) -> CGFloat {
-    // Token references: border.border.default, border.border.emphasis, border.border.heavy
+    // Token references: border.default, border.emphasis, border.heavy
     switch border {
     case .none: return 0
-    case .default: return borderDefault /* border.border.default */
-    case .emphasis: return borderEmphasis /* border.border.emphasis */
-    case .heavy: return borderHeavy /* border.border.heavy */
+    case .default: return borderDefault /* border.default */
+    case .emphasis: return borderEmphasis /* border.emphasis */
+    case .heavy: return borderHeavy /* border.heavy */
     }
 }
 

package/src/components/core/Container-Card-Base/platforms/android/ContainerCardBase.android.kt

@@ -18,7 +18,7 @@
  * This ensures cross-platform consistency with Web and iOS implementations.
  * 
  * @see ../../../types.ts for ContainerCardBaseProps interface
- * @see ../../../tokens.ts for token reference mappings
+ * @see ../../../Container-Card-Base.refs.ts for token reference mappings
  * @see .kiro/specs/043-container-card-base/design.md for complete design documentation
  * @see .kiro/specs/034-component-architecture-system for Stemma System details
  * @see src/tokens/semantic/AccessibilityTokens.ts for focus indicator tokens
@@ -625,7 +625,7 @@ fun getCardRoundedCornerShape(borderRadius: CardBorderRadius): RoundedCornerShap
 fun mapCardBorderToWidth(border: CardBorder): Dp {
     return when (border) {
         CardBorder.None -> 0.dp
-        CardBorder.Default -> borderDefault /* border.border.default */
+        CardBorder.Default -> borderDefault /* border.default */
     }
 }
 
@@ -691,7 +691,7 @@ private val radius100: Dp = DesignTokens.radius_100 /* radius-100 */
 private val radius200: Dp = DesignTokens.radius_200 /* radius-200 */
 
 // Border tokens
-private val borderDefault: Dp = DesignTokens.border_default /* border.border.default */
+private val borderDefault: Dp = DesignTokens.border_default /* border.default */
 
 // Color tokens
 

package/src/components/core/Container-Card-Base/platforms/ios/ContainerCardBase.ios.swift

@@ -17,7 +17,7 @@
  * This ensures cross-platform consistency with Web and Android implementations.
  * 
  * @see ../../../types.ts for ContainerCardBaseProps interface
- * @see ../../../tokens.ts for token reference mappings
+ * @see ../../../Container-Card-Base.refs.ts for token reference mappings
  * @see .kiro/specs/043-container-card-base/design.md for complete design documentation
  * @see .kiro/specs/034-component-architecture-system for Stemma System details
  * @see Requirements 3.1-3.14, 4.1-4.7, 5.1-5.10, 6.1-6.5, 7.1-7.6
@@ -768,7 +768,7 @@ func mapCardBorderRadiusToCornerRadius(_ borderRadius: CardBorderRadius) -> CGFl
 func mapCardBorderToLineWidth(_ border: CardBorder) -> CGFloat {
     switch border {
     case .none: return 0
-    case .default: return borderDefault /* border.border.default */
+    case .default: return borderDefault /* border.default */
     }
 }
 

package/src/components/core/Nav-Header-App/contracts.yaml

@@ -21,7 +21,7 @@ contracts:
       Render Nav-Header-App, verify no heading elements in DOM/tree.
     required: true
 
-excluded:
+excludes:
   state_disabled:
     reason: "DesignerPunk does not support disabled states."
     category: state

package/src/components/core/Nav-Header-Base/component-meta.yaml

@@ -1,6 +1,5 @@
 purpose: "Structural primitive for top-of-screen navigation bars providing safe area, background, layout regions, and landmark semantics. Internal only — use Nav-Header-Page or Nav-Header-App."
 
-# Derived from family-level guidance (Component-Family-Navigation.md)
 usage:
   when_to_use:
     - "Building a semantic header variant that needs safe area, background, layout regions, and landmark semantics"

package/src/components/core/Nav-Header-Base/contracts.yaml

@@ -171,7 +171,7 @@ contracts:
       and verify focus order matches specification.
     required: true
 
-excluded:
+excludes:
   state_disabled:
     reason: "DesignerPunk does not support disabled states. If an action is unavailable, do not render it."
     category: state

package/src/components/core/Nav-Header-Page/contracts.yaml

@@ -189,7 +189,7 @@ contracts:
       Render trailing action with various badge values, verify presence.
     required: true
 
-excluded:
+excludes:
   state_disabled:
     reason: "DesignerPunk does not support disabled states. Unavailable actions are not rendered."
     category: state

package/src/components/core/Nav-TabBar-Base/contracts.yaml

@@ -400,7 +400,7 @@ contracts:
 # EXCLUSIONS
 # ============================================================
 
-exclusions:
+excludes:
   state_disabled:
     reason: |
       No disabled state. Unavailable destinations should not be rendered.

package/src/components/core/Progress-Bar-Base/contracts.yaml

@@ -126,7 +126,7 @@ contracts:
       Pass out-of-range values, verify error thrown with correct message.
     required: true
 
-excluded:
+excludes:
   state_disabled:
     reason: "DesignerPunk does not support disabled states. If progress is not applicable, do not render the bar."
     category: state

package/src/tokens/BlurTokens.ts

@@ -17,7 +17,9 @@
  * - blur200: 32   (base × 2)
  * - blur250: 40   (base × 2.5)
  *
- * All values are multiples of 4 (baseline grid aligned).
+ * All values are multiples of 4 (the 4-unit subgrid). The `baselineGridAlignment`
+ * flag tracks the 8-unit baseline grid, so the 4/12/20 steps carry `false` — see
+ * the predicate on `PrimitiveToken.baselineGridAlignment`.
  */
 
 import { PrimitiveToken, TokenCategory, PlatformValues } from '../types/PrimitiveToken';
@@ -52,7 +54,7 @@ export const blur: Record<string, PrimitiveToken> = {
     familyBaseValue: BLUR_BASE_VALUE,
     description: 'Blur 025 - minimal blur',
     mathematicalRelationship: `base × 0.25 = ${BLUR_BASE_VALUE} × 0.25 = ${BLUR_BASE_VALUE * 0.25}`,
-    baselineGridAlignment: true,
+    baselineGridAlignment: false, // 4-unit subgrid value; not a multiple of the 8-unit baseline grid
     isStrategicFlexibility: false,
     isPrecisionTargeted: false,
     platforms: generateBlurPlatformValues(BLUR_BASE_VALUE * 0.25)
@@ -76,7 +78,7 @@ export const blur: Record<string, PrimitiveToken> = {
     familyBaseValue: BLUR_BASE_VALUE,
     description: 'Blur 075 - moderate blur',
     mathematicalRelationship: `base × 0.75 = ${BLUR_BASE_VALUE} × 0.75 = ${BLUR_BASE_VALUE * 0.75}`,
-    baselineGridAlignment: true,
+    baselineGridAlignment: false, // 4-unit subgrid value; not a multiple of the 8-unit baseline grid
     isStrategicFlexibility: false,
     isPrecisionTargeted: false,
     platforms: generateBlurPlatformValues(BLUR_BASE_VALUE * 0.75)
@@ -100,7 +102,7 @@ export const blur: Record<string, PrimitiveToken> = {
     familyBaseValue: BLUR_BASE_VALUE,
     description: 'Blur 125 - strong blur',
     mathematicalRelationship: `base × 1.25 = ${BLUR_BASE_VALUE} × 1.25 = ${BLUR_BASE_VALUE * 1.25}`,
-    baselineGridAlignment: true,
+    baselineGridAlignment: false, // 4-unit subgrid value; not a multiple of the 8-unit baseline grid
     isStrategicFlexibility: false,
     isPrecisionTargeted: false,
     platforms: generateBlurPlatformValues(BLUR_BASE_VALUE * 1.25)

package/src/tokens/ShadowOffsetTokens.ts

@@ -51,7 +51,7 @@ export const shadowOffsetX: Record<string, PrimitiveToken> = {
     familyBaseValue: SHADOW_OFFSET_BASE_VALUE,
     description: 'Sunrise shadow offset - large left offset',
     mathematicalRelationship: 'base × -3 = 4 × -3 = -12',
-    baselineGridAlignment: true, // 12 is 4px baseline grid aligned
+    baselineGridAlignment: false, // 4-unit shadow subgrid value; not a multiple of the 8-unit baseline grid
     isStrategicFlexibility: false,
     isPrecisionTargeted: false,
     platforms: generateShadowOffsetPlatformValues(SHADOW_OFFSET_BASE_VALUE * -3)
@@ -64,7 +64,7 @@ export const shadowOffsetX: Record<string, PrimitiveToken> = {
     familyBaseValue: SHADOW_OFFSET_BASE_VALUE,
     description: 'Strategic flexibility - medium-large left offset',
     mathematicalRelationship: 'base × -2 = 4 × -2 = -8',
-    baselineGridAlignment: true, // 8 is 4px baseline grid aligned
+    baselineGridAlignment: true, // 8 aligns with the 8-unit baseline grid
     isStrategicFlexibility: true,
     isPrecisionTargeted: false,
     platforms: generateShadowOffsetPlatformValues(SHADOW_OFFSET_BASE_VALUE * -2)
@@ -77,7 +77,7 @@ export const shadowOffsetX: Record<string, PrimitiveToken> = {
     familyBaseValue: SHADOW_OFFSET_BASE_VALUE,
     description: 'Morning shadow offset - medium left offset',
     mathematicalRelationship: 'base × -1.5 = 4 × -1.5 = -6',
-    baselineGridAlignment: false, // 6 is not 4px baseline grid aligned (strategic flexibility)
+    baselineGridAlignment: false, // 6 is a strategic flexibility value; not a multiple of the 8-unit baseline grid
     isStrategicFlexibility: true,
     isPrecisionTargeted: false,
     platforms: generateShadowOffsetPlatformValues(SHADOW_OFFSET_BASE_VALUE * -1.5)
@@ -90,7 +90,7 @@ export const shadowOffsetX: Record<string, PrimitiveToken> = {
     familyBaseValue: SHADOW_OFFSET_BASE_VALUE,
     description: 'Strategic flexibility - small left offset',
     mathematicalRelationship: 'base × -1 = 4 × -1 = -4',
-    baselineGridAlignment: true, // 4 is 4px baseline grid aligned
+    baselineGridAlignment: false, // 4-unit shadow subgrid value; not a multiple of the 8-unit baseline grid
     isStrategicFlexibility: true,
     isPrecisionTargeted: false,
     platforms: generateShadowOffsetPlatformValues(SHADOW_OFFSET_BASE_VALUE * -1)
@@ -103,7 +103,7 @@ export const shadowOffsetX: Record<string, PrimitiveToken> = {
     familyBaseValue: SHADOW_OFFSET_BASE_VALUE,
     description: 'Noon shadow offset - no horizontal offset',
     mathematicalRelationship: 'base × 0 = 4 × 0 = 0',
-    baselineGridAlignment: true, // 0 is baseline grid aligned
+    baselineGridAlignment: true, // 0 aligns with the 8-unit baseline grid
     isStrategicFlexibility: false,
     isPrecisionTargeted: false,
     platforms: generateShadowOffsetPlatformValues(0)
@@ -116,7 +116,7 @@ export const shadowOffsetX: Record<string, PrimitiveToken> = {
     familyBaseValue: SHADOW_OFFSET_BASE_VALUE,
     description: 'Strategic flexibility - small right offset',
     mathematicalRelationship: 'base × 1 = 4 × 1 = 4',
-    baselineGridAlignment: true, // 4 is 4px baseline grid aligned
+    baselineGridAlignment: false, // 4-unit shadow subgrid value; not a multiple of the 8-unit baseline grid
     isStrategicFlexibility: true,
     isPrecisionTargeted: false,
     platforms: generateShadowOffsetPlatformValues(SHADOW_OFFSET_BASE_VALUE)
@@ -129,7 +129,7 @@ export const shadowOffsetX: Record<string, PrimitiveToken> = {
     familyBaseValue: SHADOW_OFFSET_BASE_VALUE,
     description: 'Dusk shadow offset - medium right offset',
     mathematicalRelationship: 'base × 1.5 = 4 × 1.5 = 6',
-    baselineGridAlignment: false, // 6 is not 4px baseline grid aligned (strategic flexibility)
+    baselineGridAlignment: false, // 6 is a strategic flexibility value; not a multiple of the 8-unit baseline grid
     isStrategicFlexibility: true,
     isPrecisionTargeted: false,
     platforms: generateShadowOffsetPlatformValues(SHADOW_OFFSET_BASE_VALUE * 1.5)
@@ -142,7 +142,7 @@ export const shadowOffsetX: Record<string, PrimitiveToken> = {
     familyBaseValue: SHADOW_OFFSET_BASE_VALUE,
     description: 'Strategic flexibility - medium-large right offset',
     mathematicalRelationship: 'base × 2 = 4 × 2 = 8',
-    baselineGridAlignment: true, // 8 is 4px baseline grid aligned
+    baselineGridAlignment: true, // 8 aligns with the 8-unit baseline grid
     isStrategicFlexibility: true,
     isPrecisionTargeted: false,
     platforms: generateShadowOffsetPlatformValues(SHADOW_OFFSET_BASE_VALUE * 2)
@@ -155,7 +155,7 @@ export const shadowOffsetX: Record<string, PrimitiveToken> = {
     familyBaseValue: SHADOW_OFFSET_BASE_VALUE,
     description: 'Sunset shadow offset - large right offset',
     mathematicalRelationship: 'base × 3 = 4 × 3 = 12',
-    baselineGridAlignment: true, // 12 is 4px baseline grid aligned
+    baselineGridAlignment: false, // 4-unit shadow subgrid value; not a multiple of the 8-unit baseline grid
     isStrategicFlexibility: false,
     isPrecisionTargeted: false,
     platforms: generateShadowOffsetPlatformValues(SHADOW_OFFSET_BASE_VALUE * 3)
@@ -181,7 +181,7 @@ export const shadowOffsetY: Record<string, PrimitiveToken> = {
     familyBaseValue: SHADOW_OFFSET_BASE_VALUE,
     description: 'No vertical offset - flat surface with no shadow',
     mathematicalRelationship: 'base × 0 = 4 × 0 = 0',
-    baselineGridAlignment: true, // 0 is baseline grid aligned
+    baselineGridAlignment: true, // 0 aligns with the 8-unit baseline grid
     isStrategicFlexibility: false,
     isPrecisionTargeted: false,
     platforms: generateShadowOffsetPlatformValues(0)
@@ -194,7 +194,7 @@ export const shadowOffsetY: Record<string, PrimitiveToken> = {
     familyBaseValue: SHADOW_OFFSET_BASE_VALUE,
     description: 'Depth 100 / Noon - short shadow',
     mathematicalRelationship: 'base × 1 = 4 × 1 = 4',
-    baselineGridAlignment: true, // 4 is 4px baseline grid aligned
+    baselineGridAlignment: false, // 4-unit shadow subgrid value; not a multiple of the 8-unit baseline grid
     isStrategicFlexibility: false,
     isPrecisionTargeted: false,
     platforms: generateShadowOffsetPlatformValues(SHADOW_OFFSET_BASE_VALUE)
@@ -207,7 +207,7 @@ export const shadowOffsetY: Record<string, PrimitiveToken> = {
     familyBaseValue: SHADOW_OFFSET_BASE_VALUE,
     description: 'Depth 200 - medium shadow',
     mathematicalRelationship: 'base × 2 = 4 × 2 = 8',
-    baselineGridAlignment: true, // 8 is 4px baseline grid aligned
+    baselineGridAlignment: true, // 8 aligns with the 8-unit baseline grid
     isStrategicFlexibility: false,
     isPrecisionTargeted: false,
     platforms: generateShadowOffsetPlatformValues(SHADOW_OFFSET_BASE_VALUE * 2)
@@ -220,7 +220,7 @@ export const shadowOffsetY: Record<string, PrimitiveToken> = {
     familyBaseValue: SHADOW_OFFSET_BASE_VALUE,
     description: 'Morning/Dusk - medium-long shadow',
     mathematicalRelationship: 'base × 3 = 4 × 3 = 12',
-    baselineGridAlignment: true, // 12 is 4px baseline grid aligned
+    baselineGridAlignment: false, // 4-unit shadow subgrid value; not a multiple of the 8-unit baseline grid
     isStrategicFlexibility: false,
     isPrecisionTargeted: false,
     platforms: generateShadowOffsetPlatformValues(SHADOW_OFFSET_BASE_VALUE * 3)
@@ -233,7 +233,7 @@ export const shadowOffsetY: Record<string, PrimitiveToken> = {
     familyBaseValue: SHADOW_OFFSET_BASE_VALUE,
     description: 'Depth 300 / Sunrise/Sunset - long shadow',
     mathematicalRelationship: 'base × 4 = 4 × 4 = 16',
-    baselineGridAlignment: true, // 16 is 4px baseline grid aligned
+    baselineGridAlignment: true, // 16 aligns with the 8-unit baseline grid (8 × 2)
     isStrategicFlexibility: false,
     isPrecisionTargeted: false,
     platforms: generateShadowOffsetPlatformValues(SHADOW_OFFSET_BASE_VALUE * 4)

package/src/tokens/SizingTokens.ts

@@ -47,7 +47,7 @@ export const sizingTokens: Record<string, PrimitiveToken> = {
     familyBaseValue: SIZING_BASE_VALUE,
     description: 'Size 050 - smallest component dimension',
     mathematicalRelationship: `base × 0.5 = ${SIZING_BASE_VALUE} × 0.5 = ${SIZING_BASE_VALUE * 0.5}`,
-    baselineGridAlignment: true,
+    baselineGridAlignment: false, // 4-unit subgrid value; not a multiple of the 8-unit baseline grid
     isStrategicFlexibility: false,
     isPrecisionTargeted: false,
     platforms: generateSizingPlatformValues(SIZING_BASE_VALUE * 0.5)
@@ -71,7 +71,7 @@ export const sizingTokens: Record<string, PrimitiveToken> = {
     familyBaseValue: SIZING_BASE_VALUE,
     description: 'Size 150 - small component dimension',
     mathematicalRelationship: `base × 1.5 = ${SIZING_BASE_VALUE} × 1.5 = ${SIZING_BASE_VALUE * 1.5}`,
-    baselineGridAlignment: true,
+    baselineGridAlignment: false, // 4-unit subgrid value; not a multiple of the 8-unit baseline grid
     isStrategicFlexibility: false,
     isPrecisionTargeted: false,
     platforms: generateSizingPlatformValues(SIZING_BASE_VALUE * 1.5)
@@ -95,7 +95,7 @@ export const sizingTokens: Record<string, PrimitiveToken> = {
     familyBaseValue: SIZING_BASE_VALUE,
     description: 'Size 250 - medium component dimension',
     mathematicalRelationship: `base × 2.5 = ${SIZING_BASE_VALUE} × 2.5 = ${SIZING_BASE_VALUE * 2.5}`,
-    baselineGridAlignment: true,
+    baselineGridAlignment: false, // 4-unit subgrid value; not a multiple of the 8-unit baseline grid
     isStrategicFlexibility: false,
     isPrecisionTargeted: false,
     platforms: generateSizingPlatformValues(SIZING_BASE_VALUE * 2.5)

package/src/tokens/TapAreaTokens.ts

@@ -3,14 +3,16 @@
  * 
  * Tap area tokens use precision multipliers to achieve specific accessibility targets
  * while maintaining baseline grid alignment where possible.
- * Base value: 44 units (WCAG 2.1 AA minimum tap target size)
+ * Base value: 44 units — WCAG 2.5.5 Target Size (Level AAA), which also exceeds the
+ * WCAG 2.2 AA minimum of 24×24 (SC 2.5.8 Target Size (Minimum)).
  * Mathematical progression: Precision-targeted multipliers for accessibility compliance
  */
 
 import { PrimitiveToken, TokenCategory, PlatformValues } from '../types/PrimitiveToken';
 
 /**
- * Tap area token base value for mathematical calculations (WCAG 2.1 AA minimum)
+ * Tap area token base value for mathematical calculations
+ * (WCAG 2.5.5 Target Size, Level AAA — 44×44)
  */
 export const TAP_AREA_BASE_VALUE = 44;
 
@@ -34,7 +36,7 @@ export const tapAreaTokens: Record<string, PrimitiveToken> = {
     category: TokenCategory.TAP_AREA,
     baseValue: TAP_AREA_BASE_VALUE,
     familyBaseValue: TAP_AREA_BASE_VALUE,
-    description: 'Minimum tap area - WCAG 2.1 AA compliance (44pt)',
+    description: 'Minimum tap area - WCAG 2.5.5 Target Size, Level AAA (44pt); exceeds the 24pt WCAG 2.2 AA minimum (SC 2.5.8)',
     mathematicalRelationship: 'base × 1 = 44 × 1 = 44',
     baselineGridAlignment: false,
     isStrategicFlexibility: false,
@@ -103,22 +105,32 @@ export function getAllTapAreaTokens(): PrimitiveToken[] {
 
 /**
  * Validate tap area meets accessibility requirements
+ *
+ * Thresholds follow the WCAG success criteria, not platform guidelines:
+ * - ≥44: SC 2.5.5 Target Size (Level AAA)
+ * - ≥24: SC 2.5.8 Target Size (Minimum) (Level AA, WCAG 2.2)
+ * - <24: below the AA minimum
+ *
+ * Note: SC 2.5.8 additionally allows targets under 24×24 when sufficient spacing
+ * or an equivalent alternative exists. This function checks size only; spacing
+ * exceptions must be evaluated in component context.
  */
 export function validateTapAreaAccessibility(tapAreaValue: number): {
   isAccessible: boolean;
   level: 'AA' | 'AAA' | 'Below AA';
   recommendation?: string;
 } {
-  if (tapAreaValue >= 44) {
-    if (tapAreaValue >= 48) {
-      return { isAccessible: true, level: 'AAA' };
-    }
+  if (tapAreaValue >= TAP_AREA_BASE_VALUE) {
+    return { isAccessible: true, level: 'AAA' };
+  }
+
+  if (tapAreaValue >= 24) {
     return { isAccessible: true, level: 'AA' };
   }
 
   return {
     isAccessible: false,
     level: 'Below AA',
-    recommendation: `Increase tap area to at least ${TAP_AREA_BASE_VALUE}pt for WCAG 2.1 AA compliance`
+    recommendation: `Increase tap area to at least 24pt for WCAG 2.2 AA compliance (SC 2.5.8), or ${TAP_AREA_BASE_VALUE}pt for Level AAA (SC 2.5.5)`
   };
 }

package/src/tokens/__tests__/BaselineGridAlignmentFlag.test.ts

@@ -0,0 +1,116 @@
+/**
+ * @category evergreen
+ * @purpose Guard the system-wide baselineGridAlignment predicate against per-family drift
+ */
+/**
+ * Baseline Grid Alignment Flag — system-wide predicate guard
+ *
+ * The `baselineGridAlignment` flag had drifted to three different meanings across
+ * families: "multiple of 8" (spacing, radius), "multiple of 4" (sizing, blur,
+ * shadow offset), and "not applicable" (border width, breakpoint, density). The same
+ * value (4) therefore carried different flags in different families, which made the
+ * flag unusable by the family-agnostic consumers that read it (TokenSelector's
+ * selection reasoning, ValidationReasoning, ErrorValidator's flag-consistency check).
+ *
+ * Settled predicate:
+ *   baselineGridAlignment === true
+ *     iff baseValue is an exact multiple of 8
+ *     AND the family participates in the baseline grid (dimensional families).
+ *
+ * Non-participating families always carry `false` (meaning "not applicable").
+ * Sub-grid values (4, 12, 20) are `false` — valid values, not grid-aligned ones.
+ */
+
+import { describe, test, expect } from '@jest/globals';
+import { TokenCategory } from '../../types/PrimitiveToken';
+import type { PrimitiveToken } from '../../types/PrimitiveToken';
+
+import { spacingTokens } from '../SpacingTokens';
+import { radiusTokens } from '../RadiusTokens';
+import { sizingTokens } from '../SizingTokens';
+import { blur } from '../BlurTokens';
+import { shadowOffsetX, shadowOffsetY } from '../ShadowOffsetTokens';
+import { tapAreaTokens } from '../TapAreaTokens';
+import { borderWidthTokens } from '../BorderWidthTokens';
+import { breakpointTokens } from '../BreakpointTokens';
+import { densityTokens } from '../DensityTokens';
+import { fontSizeTokens } from '../FontSizeTokens';
+import { lineHeightTokens } from '../LineHeightTokens';
+
+const BASELINE_GRID_UNIT = 8;
+
+/** Families whose values live in the dimensional coordinate space the baseline grid measures. */
+const PARTICIPATING_CATEGORIES: TokenCategory[] = [
+  TokenCategory.SPACING,
+  TokenCategory.RADIUS,
+  TokenCategory.SIZING,
+  TokenCategory.BLUR,
+  TokenCategory.SHADOW,
+  TokenCategory.TAP_AREA,
+  TokenCategory.FONT_SIZE
+];
+
+const participating: Array<[string, Record<string, PrimitiveToken>]> = [
+  ['spacing', spacingTokens],
+  ['radius', radiusTokens],
+  ['sizing', sizingTokens],
+  ['blur', blur],
+  ['shadowOffsetX', shadowOffsetX],
+  ['shadowOffsetY', shadowOffsetY],
+  ['tapArea', tapAreaTokens],
+  ['fontSize', fontSizeTokens]
+];
+
+const nonParticipating: Array<[string, Record<string, PrimitiveToken>]> = [
+  ['borderWidth', borderWidthTokens],
+  ['breakpoint', breakpointTokens],
+  ['density', densityTokens],
+  ['lineHeight', lineHeightTokens]
+];
+
+describe('baselineGridAlignment predicate', () => {
+  describe('participating families: flag === (baseValue % 8 === 0)', () => {
+    test.each(participating)('%s tokens', (_family, tokens) => {
+      for (const token of Object.values(tokens)) {
+        const aligned = Number.isInteger(token.baseValue) && token.baseValue % BASELINE_GRID_UNIT === 0;
+        expect({ name: token.name, flag: token.baselineGridAlignment }).toEqual({
+          name: token.name,
+          flag: aligned
+        });
+      }
+    });
+  });
+
+  describe('non-participating families: flag is always false (not applicable)', () => {
+    test.each(nonParticipating)('%s tokens', (_family, tokens) => {
+      for (const token of Object.values(tokens)) {
+        expect({ name: token.name, flag: token.baselineGridAlignment }).toEqual({
+          name: token.name,
+          flag: false
+        });
+      }
+    });
+  });
+
+  test('participating categories are the dimensional families', () => {
+    for (const [, tokens] of participating) {
+      for (const token of Object.values(tokens)) {
+        expect(PARTICIPATING_CATEGORIES).toContain(token.category);
+      }
+    }
+  });
+
+  test('sub-grid values (4, 12, 20) are never flagged as grid-aligned', () => {
+    const subGridValues = [4, 12, 20, -4, -12, -20];
+    for (const [, tokens] of [...participating, ...nonParticipating]) {
+      for (const token of Object.values(tokens)) {
+        if (subGridValues.includes(token.baseValue)) {
+          expect({ name: token.name, flag: token.baselineGridAlignment }).toEqual({
+            name: token.name,
+            flag: false
+          });
+        }
+      }
+    }
+  });
+});

package/src/tokens/__tests__/BlurTokens.test.ts

@@ -59,10 +59,18 @@ describe('Unified Blur Tokens', () => {
       }
     });
 
-    it('should have all values as multiples of 4 (baseline grid aligned)', () => {
+    it('should have all values as multiples of 4 (4-unit subgrid)', () => {
       for (const token of getAllBlurTokens()) {
         expect(token.baseValue % 4).toBe(0);
-        expect(token.baselineGridAlignment).toBe(true);
+      }
+    });
+
+    it('should set baselineGridAlignment iff the value is an exact multiple of 8', () => {
+      // System-wide predicate: the flag records 8-unit baseline grid alignment,
+      // not 4-unit subgrid membership. blur025 (4), blur075 (12) and blur125 (20)
+      // are valid blur values on the 4-unit subgrid but are not grid-aligned.
+      for (const token of getAllBlurTokens()) {
+        expect(token.baselineGridAlignment).toBe(token.baseValue % 8 === 0);
       }
     });
 

package/src/tokens/__tests__/ProgressTokenCompliance.test.ts

@@ -22,18 +22,20 @@ import {
   PROGRESS_COLOR_TOKEN_COUNT,
 } from '../semantic/ColorTokens';
 import {
-  ProgressTokens,
+  getProgressRegisteredTokens,
   PROGRESS_COMPONENT_TOKEN_COUNT,
   progressComponentTokenNames,
 } from '../component/progress';
-import { getTokenContract } from '../../build/tokens';
 import type { RegisteredComponentToken } from '../../registries/ComponentTokenRegistry';
 
 // Spec 124: defineComponentTokens no longer self-registers into ComponentTokenRegistry;
 // the rich tokens ride back on the branded return and are recovered via getTokenContract.
 // (Was: reads of ComponentTokenRegistry.getByComponent('Progress') populated by the import
 // side effect — now empty/false-red.)
-const progressRegisteredTokens: RegisteredComponentToken[] = getTokenContract(ProgressTokens) ?? [];
+//
+// Progress registers through THREE family calls (sizing / spacing / borderWidth); the
+// helper concatenates their branded contracts in declaration order.
+const progressRegisteredTokens: RegisteredComponentToken[] = getProgressRegisteredTokens();
 
 describe('Progress Token Compliance', () => {
   // ==========================================================================

package/src/tokens/__tests__/ProgressTokenFormulas.test.ts

@@ -13,7 +13,7 @@
  * @see .kiro/specs/048-progress-family/design.md (Size Variant, Current Size Formula)
  */
 
-import { ProgressTokens } from '../component/progress';
+import { progressTokenValues } from '../component/progress';
 import { SPACING_BASE_VALUE } from '../SpacingTokens';
 
 describe('Progress Token Formula Validation', () => {
@@ -52,8 +52,8 @@ describe('Progress Token Formula Validation', () => {
         const calculated = SPACING_BASE_VALUE * multiplier;
         expect(calculated).toBe(expected);
 
-        const tokenKey = `node.size.${size}.current` as keyof typeof ProgressTokens;
-        expect(ProgressTokens[tokenKey]).toBe(expected);
+        const tokenKey = `node.size.${size}.current` as keyof typeof progressTokenValues;
+        expect(progressTokenValues[tokenKey]).toBe(expected);
       }
     );
   });
@@ -66,12 +66,12 @@ describe('Progress Token Formula Validation', () => {
     ] as const)(
       'should maintain +4px offset for %s (base %dpx → current %dpx)',
       (size, base, current) => {
-        const baseKey = `node.size.${size}` as keyof typeof ProgressTokens;
-        const currentKey = `node.size.${size}.current` as keyof typeof ProgressTokens;
+        const baseKey = `node.size.${size}` as keyof typeof progressTokenValues;
+        const currentKey = `node.size.${size}.current` as keyof typeof progressTokenValues;
 
-        expect(ProgressTokens[baseKey]).toBe(base);
-        expect(ProgressTokens[currentKey]).toBe(current);
-        expect(ProgressTokens[currentKey] - ProgressTokens[baseKey]).toBe(4);
+        expect(progressTokenValues[baseKey]).toBe(base);
+        expect(progressTokenValues[currentKey]).toBe(current);
+        expect(progressTokenValues[currentKey] - progressTokenValues[baseKey]).toBe(4);
       }
     );
   });
@@ -84,9 +84,9 @@ describe('Progress Token Formula Validation', () => {
     ] as const)(
       'should align %s (%dpx) to 4px baseline grid',
       (tokenName, expected) => {
-        const tokenKey = tokenName as keyof typeof ProgressTokens;
-        expect(ProgressTokens[tokenKey]).toBe(expected);
-        expect(ProgressTokens[tokenKey] % 4).toBe(0);
+        const tokenKey = tokenName as keyof typeof progressTokenValues;
+        expect(progressTokenValues[tokenKey]).toBe(expected);
+        expect(progressTokenValues[tokenKey] % 4).toBe(0);
       }
     );
   });