@3fn/core 14.1.0 → 15.0.0

package/mcp-server/src/tools/validate-metadata.ts

@@ -16,6 +16,7 @@ import { ErrorHandler, MCPError } from '../utils/error-handler';
  */
 export const validateMetadataTool = {
   name: 'validate_metadata',
+  annotations: { readOnlyHint: true },
   description: 'Validate document metadata schema. Checks for required fields (Date, Purpose, Organization, Scope, Layer, Relevant Tasks) and returns specific error messages for each issue.',
   inputSchema: {
     type: 'object' as const,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@3fn/core",
-  "version": "14.1.0",
+  "version": "15.0.0",
   "description": "True Native cross-platform design system with mathematical foundations",
   "license": "Apache-2.0",
   "author": "Peter Michaels Allen",
@@ -13,19 +13,31 @@
   "browser": "./dist/browser/designerpunk.esm.js",
   "types": "./dist/browser-entry.d.ts",
   "files": [
-    "src/",
+    "CHANGELOG.md",
     "dist/browser/designerpunk.esm.js",
     "dist/browser/designerpunk.esm.min.js",
     "dist/browser-entry.d.ts",
     "dist/**/*.{js,d.ts,json,css,swift,kt}",
     "!dist/**/__tests__/**",
+    "!dist/ios/**",
+    "!dist/android/**",
+    "!dist/web/**",
+    "dist/consumer-canonical/**",
+    "dist/generator/**",
     "dist/__tests__/fixtures/acknowledged-differences.json",
+    "dist/mcp/tool-manifest.json",
+    "dist/name-contract.json",
     "bin/",
     "src/cli/templates/",
-    ".kiro/steering/",
+    ".kiro/steering/Agent-Directory.md",
+    ".kiro/steering/AI-Collaboration-Principles.md",
+    ".kiro/steering/Civitas-System-Overview.md",
+    ".kiro/steering/core-goals.md",
+    ".kiro/steering/DesignerPunk-Systems-Overview.md",
+    ".kiro/steering/Spec-Feedback-Protocol.md",
+    ".kiro/steering/start-up-tasks.md",
+    ".kiro/steering/Task-Completion-Protocol.md",
     "governance/",
-    ".kiro/agents/",
-    "product-template/",
     "mcp-server/src/",
     "mcp-server/package.json",
     "mcp-server/tsconfig.json",
@@ -38,7 +50,38 @@
     "token-index/",
     "family-registry.yaml",
     "design-language/",
-    "designerpunk.config.ts"
+
+    "src/tokens/**",
+    "src/styles/",
+    "src/assets/fonts/**",
+    "!src/assets/fonts/__tests__/**",
+    "src/components/**/{*.schema.yaml,contracts.yaml,component-meta.yaml}",
+
+    "src/types/PrimitiveToken.ts",
+    "src/types/SemanticToken.ts",
+    "src/build/tokens/ComponentToken.ts",
+    "src/build/tokens/ComponentTokenGenerator.ts",
+    "src/build/tokens/PlatformTokens.ts",
+    "src/build/tokens/TokenIntegrator.ts",
+    "src/build/tokens/TokenSelection.ts",
+    "src/build/tokens/TokenSelector.ts",
+    "src/build/tokens/UnitConverter.ts",
+    "src/build/tokens/defineComponentTokens.ts",
+    "src/build/tokens/index.ts",
+    "src/build/tokens/types.ts",
+    "src/build/types/Platform.ts",
+    "src/registries/PrimitiveTokenRegistry.ts",
+    "src/registries/SemanticTokenRegistry.ts",
+    "src/constants/StrategicFlexibilityTokens.ts",
+
+    "src/components/core/**/platforms/ios/*.swift",
+    "!src/components/core/**/platforms/ios/*Tests.swift",
+    "src/components/core/**/platforms/android/*.kt",
+    "!src/components/core/**/platforms/android/*Test.kt",
+    "src/components/core/**/platforms/android/res/**",
+    "src/components/core/**/platforms/android/.gitkeep",
+    "src/blend/*.ios.swift",
+    "src/blend/*.android.kt"
   ],
   "exports": {
     ".": {
@@ -80,7 +123,6 @@
       "require": "./dist/testing/index.js"
     },
     "./grid.css": "./src/styles/responsive-grid.css",
-    "./fonts/inter.css": "./src/assets/fonts/inter/inter.css",
     "./fonts/rajdhani.css": "./src/assets/fonts/rajdhani/rajdhani.css",
     "./fonts/figtree.css": "./src/assets/fonts/figtree/figtree.css",
     "./fonts/commit-mono.css": "./src/assets/fonts/commit-mono/commit-mono.css",
@@ -97,11 +139,16 @@
     "generate:platform-tokens": "tsx scripts/generate-platform-tokens.ts",
     "extract:meta": "tsx scripts/extract-component-meta.ts",
     "prebuild": "npm run generate:types && npm run generate:platform-tokens",
-    "build": "tsc --skipLibCheck && npm run build:validate && npm run build:browser && npm run build:mcp",
+    "build": "tsc --skipLibCheck && npm run build:validate && npm run build:browser && npm run build:name-contract && npm run build:mcp && npm run build:generator",
     "typecheck:scripts": "tsc -p tsconfig.scripts.json",
+    "typecheck": "tsc --noEmit",
     "build:browser": "node scripts/build-browser-bundles.js",
-    "build:mcp": "npm run build:mcp-shared && npx esbuild application-mcp-server/src/index.ts --bundle --platform=node --format=cjs --outfile=dist/mcp/application-mcp.js && npx esbuild mcp-server/src/index.ts --bundle --platform=node --format=cjs --outfile=dist/mcp/docs-mcp.js && npx esbuild product-mcp-server/src/index.ts --bundle --platform=node --format=cjs --outfile=dist/mcp/product-mcp.js",
-    "build:mcp-shared": "npx esbuild src/cli/shared/resolvePackageRoot.ts src/cli/shared/mcpDataRoots.ts --outdir=dist/cli/shared --platform=node --format=cjs --sourcemap",
+    "build:mcp": "npm run build:mcp-shared && npx esbuild application-mcp-server/src/index.ts --bundle --platform=node --format=cjs --outfile=dist/mcp/application-mcp.js && npx esbuild mcp-server/src/index.ts --bundle --platform=node --format=cjs --outfile=dist/mcp/docs-mcp.js && npx esbuild product-mcp-server/src/index.ts --bundle --platform=node --format=cjs --outfile=dist/mcp/product-mcp.js && npm run build:tool-manifest",
+    "build:mcp-shared": "npx esbuild src/cli/shared/resolvePackageRoot.ts src/cli/shared/mcpDataRoots.ts src/cli/shared/bornRepo.ts src/cli/shared/errorCatalog.ts --outdir=dist/cli/shared --platform=node --format=cjs --sourcemap",
+    "build:tool-manifest": "npx tsx scripts/build-tool-manifest.ts",
+    "build:name-contract": "npx tsx scripts/build-name-contract.ts",
+    "build:consumer-canonical": "tsx tools/agent-generator/consumer-entry.ts prepack",
+    "build:generator": "npm run build:consumer-canonical && npx esbuild tools/agent-generator/consumer-entry.ts --bundle --platform=node --format=cjs --define:require.main=undefined --drop-labels=STEWARD_CLI --log-level=warning --outfile=dist/generator/consumer-entry.js",
     "build:watch": "tsc --watch --skipLibCheck",
     "build:verify": "node verify-build.js",
     "build:validate": "npx tsx src/validators/buildValidation.ts",
@@ -109,7 +156,12 @@
     "test": "jest --config jest.functional.config.js",
     "test:all": "jest",
     "test:agent-generator": "jest --config tools/agent-generator/jest.config.js",
+    "test:scripts": "jest --config scripts/jest.config.js",
     "test:consumer": "jest --roots='<rootDir>/tests' --testMatch='**/consumer-integration.test.ts' --runInBand --testTimeout=120000 --forceExit",
+    "test:guard:dynamic-import": "jest --testPathPatterns='DynamicImportGuard' --no-coverage --runInBand",
+    "test:smoke:mcp-boot": "jest --roots='<rootDir>/tests' --testMatch='**/mcp-boot-smoke.test.ts' --no-coverage --runInBand --testTimeout=60000",
+    "test:smoke:browser-boot": "jest --roots='<rootDir>/tests' --testMatch='**/browser-boot-smoke.test.ts' --no-coverage --runInBand --testTimeout=60000",
+    "test:smoke:tool-boot": "jest --roots='<rootDir>/tests' --testMatch='**/tool-boot-smoke.test.ts' --no-coverage --runInBand --testTimeout=60000",
     "test:resolution-matrix": "node src/config/__resolution-matrix__/run-matrix.js",
     "test:performance": "jest --testPathPatterns='performance/__tests__|__tests__/performance'",
     "test:performance:isolated": "jest --config jest.performance.config.js --runInBand",
@@ -119,7 +171,7 @@
     "audit:tokens:detailed": "node scripts/audit-component-tokens.js -- --detailed",
     "audit:coverage-map": "npx tsx tools/agent-generator/coverage-map.ts",
     "audit:mode-parity": "npx tsx src/validators/ModeParity.ts",
-    "audit:theme-drift": "npx tsx src/tools/ThemeFileGenerator.ts > /tmp/theme-skeleton-check.ts && diff -u src/tokens/themes/dark/SemanticOverrides.ts /tmp/theme-skeleton-check.ts || echo '⚠️  Theme file drift detected — regenerate with: npm run generate:theme-skeleton'",
+    "audit:theme-drift": "npx tsx src/tools/ThemeFileGenerator.ts > /tmp/theme-skeleton-check.ts && diff -u src/tokens/themes/dark/SemanticOverrides.ts /tmp/theme-skeleton-check.ts || (echo '✖ Theme skeleton differs from the live theme file (or the generator failed). READ THE DIFF FIRST: this comparison is comment-sensitive, so hand-written rationale comments in the theme file always show as differences. Regenerating (npm run generate:theme-skeleton) preserves override VALUES but DELETES those comments — only do it for real token additions/removals, and restore the rationale afterward.' && exit 1)",
     "generate:theme-skeleton": "npx tsx src/tools/ThemeFileGenerator.ts",
     "serve": "python3 -m http.server 8001",
     "server": "python3 -m http.server 8001",
@@ -129,6 +181,18 @@
     "check:drift": "node scripts/check-package-name-drift.js",
     "check:id-uniqueness": "tsx scripts/check-id-uniqueness.ts",
     "check:section-citations": "tsx scripts/check-section-citations.ts",
+    "check:completion-criteria-parity": "tsx scripts/check-completion-criteria-parity.ts",
+    "check:122:noop-probe": "tsx tools/agent-generator/sweeps/noop-probe.ts",
+    "check:122:diff-guard": "tsx tools/agent-generator/diff-guard.ts",
+    "check:122:canonical-vs-truth": "tsx tools/agent-generator/canonical-vs-truth.ts",
+    "check:122:sweep-1-refs": "tsx tools/agent-generator/sweeps/sweep-1-refs.ts",
+    "check:122:sweep-2-skills": "tsx tools/agent-generator/sweeps/sweep-2-skills.ts",
+    "check:122:sweep-3-dupes": "tsx tools/agent-generator/sweeps/sweep-3-dupes.ts",
+    "check:122:sweep-4-ambient": "tsx tools/agent-generator/sweeps/sweep-4-ambient.ts",
+    "check:122:sweep-5-corrected-state": "tsx tools/agent-generator/sweeps/sweep-5-corrected.ts",
+    "check:122:sweep-6-declarations": "tsx tools/agent-generator/sweeps/sweep-6-declarations.ts",
+    "check:122:sweep-7-dispositions": "tsx tools/agent-generator/sweeps/sweep-7-dispositions.ts",
+    "check:122:sweep-8-demotion": "tsx tools/agent-generator/sweeps/sweep-8-demotion.ts",
     "prepack": "npm run build",
     "verify:token-index-clean": "git diff --quiet token-index/ || (echo '✖ token-index/ is stale relative to the committed state. Regenerate and commit it on the RELEASE BRANCH (it traverses the PR gate with the version bump) before publishing. See .kiro/hooks/RELEASE-FLOW.md.' && exit 1)",
     "prepublishOnly": "npm run build && npm run check:drift && npm run verify:token-index-clean",

package/src/cli/templates/mcp-config.json.template

@@ -8,16 +8,7 @@
       "env": {
         "MCP_STEERING_DIR": "./node_modules/@3fn/core/governance"
       },
-      "disabled": false,
-      "autoApprove": [
-        "get_document_summary",
-        "get_document_full",
-        "get_section",
-        "list_cross_references",
-        "validate_metadata",
-        "get_index_health",
-        "rebuild_index"
-      ]
+      "disabled": false
     },
     "designerpunk-application": {
       "command": "node",
@@ -25,22 +16,26 @@
         "./node_modules/@3fn/core/dist/mcp/application-mcp.js"
       ],
       "env": {
-        "COMPONENTS_DIR": "./src/components/core",
+        "COMPONENTS_DIR": "./src/components",
         "PATTERNS_DIR": "./node_modules/@3fn/core/experience-patterns",
         "TEMPLATES_DIR": "./node_modules/@3fn/core/layout-templates",
         "GUIDANCE_DIR": "./node_modules/@3fn/core/family-guidance",
         "REGISTRY_PATH": "./node_modules/@3fn/core/family-registry.yaml",
         "TOKEN_INDEX_DIR": "./token-index"
       },
-      "disabled": false,
-      "autoApprove": [
-        "get_component_catalog",
-        "get_component_summary",
-        "get_component_full",
-        "find_components",
-        "validate_component",
-        "get_component_health"
-      ]
+      "disabled": false
+    },
+    "designerpunk-product": {
+      "command": "node",
+      "args": [
+        "./node_modules/@3fn/core/dist/mcp/product-mcp.js"
+      ],
+      "env": {
+        "PRODUCT_DIR": "./product",
+        "COMPONENT_DIR": "./src/components",
+        "TOKEN_INDEX_DIR": "./token-index"
+      },
+      "disabled": false
     }
   }
 }

package/src/components/core/Avatar-Base/platforms/android/AvatarPreview.kt

@@ -36,11 +36,15 @@ import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
-import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.text.font.FontFamily
 import androidx.compose.ui.tooling.preview.Preview
 import androidx.compose.ui.unit.dp
 
+// Import DesignTokens for semantic color token references (matches Avatar.android.kt's
+// consumption pattern for non-theme-varying tokens — see Rosetta System Architecture §
+// "Module-Resolution Contract").
+import com.designerpunk.tokens.DesignTokens
+
 // MARK: - Main Preview
 
 /**
@@ -316,7 +320,10 @@ private fun ImageExamplesSection() {
                     Text(
                         text = "src ignored",
                         style = MaterialTheme.typography.labelSmall,
-                        color = Color(0xFFFF9800) /* orange400 - warning color */
+                        // color.feedback.warning.text (→ orange400; no dark-mode override,
+                        // see src/tokens/themes/dark/SemanticOverrides.ts) — was a hardcoded
+                        // hex literal duplicating this token's value (2026-09-13 audit finding).
+                        color = DesignTokens.color_feedback_warning_text
                     )
                 }
                 

package/src/components/core/Container-Base/Container-Base.schema.yaml

@@ -197,9 +197,9 @@ properties:
     description: |
       Border width for the container. Maps to border tokens.
       - none: No border
-      - default: 1px (border.border.default)
-      - emphasis: 2px (border.border.emphasis)
-      - heavy: 4px (border.border.heavy)
+      - default: 1px (border.default)
+      - emphasis: 2px (border.emphasis)
+      - heavy: 4px (border.heavy)
       Border color uses borderColor prop or defaults to color.border.default.
   
   borderColor:
@@ -309,12 +309,10 @@ tokens:
     - space.inset.300
     - space.inset.400
   color:
-    - color.background
-    - color.surface
-    - color.border.default
+    - color.structure.surface
+    - color.structure.border
     - color.structure.border.subtle
-    - color.border.emphasis
-    - color.canvas
+    - color.structure.canvas
   shadow:
     - shadow.container
     - shadow.navigation
@@ -323,9 +321,9 @@ tokens:
     - shadow.toast
     - shadow.tooltip
   border:
-    - border.border.default
-    - border.border.emphasis
-    - border.border.heavy
+    - border.default
+    - border.emphasis
+    - border.heavy
   radius:
     - radius-050
     - radius-100

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

@@ -23,7 +23,7 @@
  * - Hover state support via blend utilities (desktop/ChromeOS with pointer)
  * 
  * @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
@@ -569,12 +569,12 @@ fun resolveContainerBaseBorderColor(borderColor: String?, theme: DesignerPunkThe
 }
 
 fun mapContainerBaseBorderToWidth(border: ContainerBaseBorderValue): Dp {
-    // Token references: border.border.default, border.border.emphasis, border.border.heavy
+    // Token references: border.default, border.emphasis, border.heavy
     return when (border) {
         ContainerBaseBorderValue.None -> 0.dp
-        ContainerBaseBorderValue.Default -> borderDefault /* border.border.default */
-        ContainerBaseBorderValue.Emphasis -> borderEmphasis /* border.border.emphasis */
-        ContainerBaseBorderValue.Heavy -> borderHeavy /* border.border.heavy */
+        ContainerBaseBorderValue.Default -> borderDefault /* border.default */
+        ContainerBaseBorderValue.Emphasis -> borderEmphasis /* border.emphasis */
+        ContainerBaseBorderValue.Heavy -> borderHeavy /* border.heavy */
     }
 }
 

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)