@3fn/core 13.0.0 → 14.1.0

package/src/__tests__/stemma-system/input-text-native-base-call-alignment.test.ts

@@ -0,0 +1,298 @@
+/**
+ * Input-Text Native Base-Call Alignment Validation
+ *
+ * Static analysis tests that validate the native (iOS/Android) Input-Text
+ * semantic variants call InputTextBase with parameters the base actually
+ * declares. The native platform files are NOT compiled in CI — Swift/Kotlin
+ * sources are only validated by static-analysis Jest tests — so a call-site
+ * passing an undeclared parameter (or referencing a nonexistent enum member)
+ * would not compile on a real platform build but previously went undetected.
+ *
+ * Catches:
+ * - Callers passing named arguments the base does not declare
+ *   (e.g., `trailingContent` before the base grew that slot)
+ * - iOS callers passing memberwise-init arguments out of declaration order
+ * - References to InputType enum members that do not exist
+ *   (e.g., `InputType.PHONE` when the enum defines TEL)
+ *
+ * Stemma System: Form Inputs Family
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+const CORE = path.join(__dirname, '../../components/core');
+
+const IOS_BASE = path.join(CORE, 'Input-Text-Base/platforms/ios/InputTextBase.ios.swift');
+const ANDROID_BASE = path.join(CORE, 'Input-Text-Base/platforms/android/InputTextBase.android.kt');
+
+const IOS_CALLERS = [
+  'Input-Text-Password/platforms/ios/InputTextPassword.ios.swift',
+  'Input-Text-Email/platforms/ios/InputTextEmail.ios.swift',
+  'Input-Text-PhoneNumber/platforms/ios/InputTextPhoneNumber.ios.swift',
+].map((p) => path.join(CORE, p));
+
+const ANDROID_CALLERS = [
+  'Input-Text-Password/platforms/android/InputTextPassword.android.kt',
+  'Input-Text-Email/platforms/android/InputTextEmail.android.kt',
+  'Input-Text-PhoneNumber/platforms/android/InputTextPhoneNumber.android.kt',
+].map((p) => path.join(CORE, p));
+
+// ---------------------------------------------------------------------------
+// Source scanning helpers (string- and comment-aware, brace/paren-depth aware)
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract the balanced-parentheses body starting at `openParenIndex`
+ * (which must point at a '('). Skips string literals and line comments.
+ */
+function extractParenBody(source: string, openParenIndex: number): string {
+  let depth = 0;
+  for (let i = openParenIndex; i < source.length; i++) {
+    const ch = source[i];
+    if (ch === '"') {
+      // Skip string literal (handles escapes)
+      i++;
+      while (i < source.length && source[i] !== '"') {
+        if (source[i] === '\\') i++;
+        i++;
+      }
+    } else if (ch === '/' && source[i + 1] === '/') {
+      while (i < source.length && source[i] !== '\n') i++;
+    } else if (ch === '(') {
+      depth++;
+    } else if (ch === ')') {
+      depth--;
+      if (depth === 0) {
+        return source.slice(openParenIndex + 1, i);
+      }
+    }
+  }
+  throw new Error('Unbalanced parentheses in source');
+}
+
+/**
+ * Split an argument/parameter list into top-level entries — commas nested
+ * inside (), {}, [], strings, or line comments do not split.
+ */
+function splitTopLevel(body: string): string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let current = '';
+  for (let i = 0; i < body.length; i++) {
+    const ch = body[i];
+    if (ch === '"') {
+      current += ch;
+      i++;
+      while (i < body.length && body[i] !== '"') {
+        if (body[i] === '\\') {
+          current += body[i];
+          i++;
+        }
+        current += body[i];
+        i++;
+      }
+      current += body[i] ?? '';
+    } else if (ch === '/' && body[i + 1] === '/') {
+      while (i < body.length && body[i] !== '\n') i++;
+      current += '\n';
+    } else if ('({['.includes(ch)) {
+      depth++;
+      current += ch;
+    } else if (')}]'.includes(ch)) {
+      depth--;
+      current += ch;
+    } else if (ch === ',' && depth === 0) {
+      parts.push(current);
+      current = '';
+    } else {
+      current += ch;
+    }
+  }
+  if (current.trim()) parts.push(current);
+  return parts;
+}
+
+/** Find every `InputTextBase(...)` call in a source file and return its args. */
+function extractBaseCalls(source: string): string[][] {
+  const calls: string[][] = [];
+  const re = /\bInputTextBase\(/g;
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(source)) !== null) {
+    const body = extractParenBody(source, match.index + match[0].length - 1);
+    calls.push(splitTopLevel(body));
+    re.lastIndex = match.index + match[0].length;
+  }
+  return calls;
+}
+
+/** Labels of named arguments: Swift `label: value` / Kotlin `name = value`. */
+function argLabel(arg: string, platform: 'ios' | 'android'): string | null {
+  const m =
+    platform === 'ios'
+      ? arg.match(/^\s*(\w+)\s*:/)
+      : arg.match(/^\s*(\w+)\s*=(?!=)/);
+  return m ? m[1] : null;
+}
+
+// ---------------------------------------------------------------------------
+// Base declaration parsers
+// ---------------------------------------------------------------------------
+
+/**
+ * iOS base: settable stored properties of the InputTextBase struct, in
+ * declaration order. These define the memberwise initializer, so caller
+ * argument labels must be an in-order subsequence of this list.
+ * Excludes private state (@State/@FocusState/@Environment are all private)
+ * and the `body` computed property.
+ */
+function parseIOSBaseProperties(source: string): string[] {
+  const structStart = source.indexOf('struct InputTextBase: View {');
+  const bodyStart = source.indexOf('var body: some View', structStart);
+  const section = source.slice(structStart, bodyStart);
+  const props: string[] = [];
+  for (const line of section.split('\n')) {
+    if (line.includes('private')) continue;
+    const m = line.match(/^\s*(?:@Binding\s+)?(?:let|var)\s+(\w+)\s*[:=]/);
+    if (m) props.push(m[1]);
+  }
+  return props;
+}
+
+/** Android base: parameter names of the InputTextBase composable function. */
+function parseAndroidBaseParams(source: string): string[] {
+  const funIndex = source.indexOf('fun InputTextBase(');
+  const body = extractParenBody(source, funIndex + 'fun InputTextBase'.length);
+  return splitTopLevel(body)
+    .map((p) => p.match(/^\s*(\w+)\s*:/)?.[1])
+    .filter((name): name is string => Boolean(name));
+}
+
+/** Enum members: Swift `case xyz` / Kotlin `enum class InputType { A, B }`. */
+function parseInputTypeMembers(source: string, platform: 'ios' | 'android'): string[] {
+  if (platform === 'ios') {
+    const enumStart = source.indexOf('enum InputType {');
+    const enumBody = source.slice(enumStart, source.indexOf('}', enumStart));
+    return [...enumBody.matchAll(/case\s+(\w+)/g)].map((m) => m[1]);
+  }
+  const enumMatch = source.match(/enum class InputType \{([^}]*)\}/);
+  if (!enumMatch) return [];
+  return enumMatch[1]
+    .split(',')
+    .map((m) => m.trim())
+    .filter(Boolean);
+}
+
+/** Assert `subset` appears within `sequence` in order (subsequence check). */
+function isInOrderSubsequence(subset: string[], sequence: string[]): boolean {
+  let cursor = 0;
+  for (const item of subset) {
+    const found = sequence.indexOf(item, cursor);
+    if (found === -1) return false;
+    cursor = found + 1;
+  }
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('Input-Text native base-call alignment', () => {
+  const iosBaseSource = fs.readFileSync(IOS_BASE, 'utf-8');
+  const androidBaseSource = fs.readFileSync(ANDROID_BASE, 'utf-8');
+
+  const iosBaseProps = parseIOSBaseProperties(iosBaseSource);
+  const androidBaseParams = parseAndroidBaseParams(androidBaseSource);
+  const iosEnumMembers = parseInputTypeMembers(iosBaseSource, 'ios');
+  const androidEnumMembers = parseInputTypeMembers(androidBaseSource, 'android');
+
+  describe('base declaration parsing (sanity)', () => {
+    it('parses the iOS base memberwise properties', () => {
+      expect(iosBaseProps).toEqual(
+        expect.arrayContaining(['id', 'label', 'value', 'type', 'readOnly', 'trailingContent'])
+      );
+      expect(iosBaseProps.length).toBeGreaterThanOrEqual(15);
+    });
+
+    it('parses the Android base composable parameters', () => {
+      expect(androidBaseParams).toEqual(
+        expect.arrayContaining(['id', 'label', 'value', 'type', 'visualTransformation', 'trailingContent'])
+      );
+      expect(androidBaseParams.length).toBeGreaterThanOrEqual(15);
+    });
+
+    it('parses the InputType enums on both platforms', () => {
+      expect(iosEnumMembers).toEqual(['text', 'email', 'password', 'tel', 'url']);
+      expect(androidEnumMembers).toEqual(['TEXT', 'EMAIL', 'PASSWORD', 'TEL', 'URL']);
+    });
+  });
+
+  describe('iOS callers', () => {
+    // The iOS base preview also exercises the memberwise initializer
+    const files = [...IOS_CALLERS, IOS_BASE];
+
+    files.forEach((file) => {
+      const name = path.basename(file);
+
+      it(`${name}: every InputTextBase argument is a declared property, in declaration order`, () => {
+        const source = fs.readFileSync(file, 'utf-8');
+        const calls = extractBaseCalls(source);
+        expect(calls.length).toBeGreaterThan(0);
+
+        calls.forEach((args) => {
+          const labels = args
+            .map((a) => argLabel(a, 'ios'))
+            .filter((l): l is string => Boolean(l));
+
+          const undeclared = labels.filter((l) => !iosBaseProps.includes(l));
+          expect(undeclared).toEqual([]);
+
+          // Memberwise init requires arguments in property declaration order
+          expect(isInOrderSubsequence(labels, iosBaseProps)).toBe(true);
+        });
+      });
+
+      it(`${name}: type argument references a declared InputType case`, () => {
+        const source = fs.readFileSync(file, 'utf-8');
+        extractBaseCalls(source).forEach((args) => {
+          const typeArg = args.find((a) => argLabel(a, 'ios') === 'type');
+          if (!typeArg) return;
+          const caseMatch = typeArg.match(/:\s*\.(\w+)/);
+          if (caseMatch) {
+            expect(iosEnumMembers).toContain(caseMatch[1]);
+          }
+        });
+      });
+    });
+  });
+
+  describe('Android callers', () => {
+    ANDROID_CALLERS.forEach((file) => {
+      const name = path.basename(file);
+
+      it(`${name}: every InputTextBase named argument is a declared parameter`, () => {
+        const source = fs.readFileSync(file, 'utf-8');
+        const calls = extractBaseCalls(source);
+        expect(calls.length).toBeGreaterThan(0);
+
+        calls.forEach((args) => {
+          const labels = args
+            .map((a) => argLabel(a, 'android'))
+            .filter((l): l is string => Boolean(l));
+          expect(labels.length).toBeGreaterThan(0);
+
+          const undeclared = labels.filter((l) => !androidBaseParams.includes(l));
+          expect(undeclared).toEqual([]);
+        });
+      });
+
+      it(`${name}: every InputType reference is a declared enum member`, () => {
+        const source = fs.readFileSync(file, 'utf-8');
+        const refs = [...source.matchAll(/\bInputType\.(\w+)/g)].map((m) => m[1]);
+        const unknown = refs.filter((r) => !androidEnumMembers.includes(r));
+        expect(unknown).toEqual([]);
+      });
+    });
+  });
+});

package/src/blend/OklchBlendCalculator.ts

@@ -17,6 +17,8 @@
 
 import type { Oklch } from '../color/OklchConverter';
 
+// 'disabled' is deprecated calculator capability: DesignerPunk supports no disabled
+// states (adjudicated 2026-07-15) — no component may use it; removal at next major.
 export type InteractionState = 'hover' | 'pressed' | 'focused' | 'disabled';
 
 /** Thresholds for interaction state blends. */
@@ -24,6 +26,7 @@ export const INTERACTION_THRESHOLDS = {
   hover:    { deltaL: { min: 0.02, max: 0.05 }, deltaC: 0 },
   pressed:  { deltaL: { min: 0.05, max: 0.10 }, deltaC: 0 },
   focused:  { deltaL: 0, deltaC: { min: 0.02 } },
+  // deprecated 2026-07-15 (no-disabled-states philosophy) — removal at next major
   disabled: { deltaL: 0, deltaC: { min: 0.03 } },
 } as const;
 

package/src/blend/ThemeAwareBlendUtilities.android.kt

@@ -37,6 +37,7 @@ object BlendTokenValues {
     const val focusSaturate: Float = 0.08f
     
     /** Disabled state desaturation - blend300 (12%) */
+    @Deprecated("DesignerPunk does not support disabled states (adjudicated 2026-07-15). Removal at next major.")
     const val disabledDesaturate: Float = 0.12f
     
     /** Icon optical balance lightening - blend200 (8%) */
@@ -163,6 +164,7 @@ fun Color.focusBlend(): Color {
  *
  * @see Requirements: 11.4 - Theme-aware wrapper functions
  */
+@Deprecated("DesignerPunk does not support disabled states (adjudicated 2026-07-15) — if an action is unavailable, do not render the component. Use desaturate() for non-disabled desaturation. Removal at next major.")
 fun Color.disabledBlend(): Color {
     return this.desaturate(BlendTokenValues.disabledDesaturate)
 }
@@ -280,6 +282,7 @@ object BlendUtilitiesProvider {
      * @param color Base color
      * @return Desaturated color for disabled state
      */
+    @Deprecated("DesignerPunk does not support disabled states (adjudicated 2026-07-15) — if an action is unavailable, do not render the component. Removal at next major.")
     fun disabledColor(color: Color): Color {
         return color.disabledBlend()
     }

package/src/blend/ThemeAwareBlendUtilities.ios.swift

@@ -28,6 +28,7 @@ public struct BlendTokenValues {
     public static let focusSaturate: Double = 0.08
     
     /// Disabled state desaturation - blend300 (12%)
+    @available(*, deprecated, message: "DesignerPunk does not support disabled states (adjudicated 2026-07-15). Removal at next major.")
     public static let disabledDesaturate: Double = 0.12
     
     /// Icon optical balance lightening - blend200 (8%)
@@ -172,6 +173,7 @@ extension Color {
     /// ```
     ///
     /// @see Requirements: 11.4 - Theme-aware wrapper functions
+    @available(*, deprecated, message: "DesignerPunk does not support disabled states (adjudicated 2026-07-15) — if an action is unavailable, do not render the component. Use desaturate(_:) for non-disabled desaturation. Removal at next major.")
     public func disabledBlend() -> Color {
         return self.desaturate(BlendTokenValues.disabledDesaturate)
     }
@@ -276,6 +278,7 @@ public class BlendUtilitiesProvider {
     /// Calculate disabled color for a given base color
     /// - Parameter color: Base color
     /// - Returns: Desaturated color for disabled state
+    @available(*, deprecated, message: "DesignerPunk does not support disabled states (adjudicated 2026-07-15) — if an action is unavailable, do not render the component. Removal at next major.")
     public func disabledColor(_ color: Color) -> Color {
         return color.disabledBlend()
     }

package/src/blend/ThemeAwareBlendUtilities.web.ts

@@ -54,7 +54,11 @@ export const BlendTokenValues = {
   pressedDarker: 0.12,
   /** Focus state saturation increase - blend200 (8%) */
   focusSaturate: 0.08,
-  /** Disabled state desaturation - blend300 (12%) */
+  /**
+   * Disabled state desaturation - blend300 (12%)
+   * @deprecated 2026-07-15 — DesignerPunk does not support disabled states; if an action
+   * is unavailable, do not render the component. Scheduled for removal at the next major.
+   */
   disabledDesaturate: 0.12,
   /** Icon optical balance lightening - blend200 (8%) */
   iconLighter: 0.08
@@ -89,6 +93,9 @@ export interface BlendUtilitiesResult {
    * Calculate disabled color by desaturating the base color
    * @param baseColor - Base color as hex string (e.g., "#A855F7")
    * @returns Desaturated hex color string for disabled state
+   * @deprecated 2026-07-15 — DesignerPunk does not support disabled states; if an action
+   * is unavailable, do not render the component. For non-disabled desaturation, use the
+   * generic desaturate() utility. Scheduled for removal at the next major.
    */
   disabledColor: (baseColor: string) => string;
   
@@ -242,6 +249,7 @@ export function createBlendUtilities(): BlendUtilitiesResult {
     hoverColor: (baseColor: string) => darkerBlend(baseColor, BlendTokenValues.hoverDarker),
     pressedColor: (baseColor: string) => darkerBlend(baseColor, BlendTokenValues.pressedDarker),
     focusColor: (baseColor: string) => saturate(baseColor, BlendTokenValues.focusSaturate),
+    // deprecated 2026-07-15 (no-disabled-states philosophy) — removal at next major
     disabledColor: (baseColor: string) => desaturate(baseColor, BlendTokenValues.disabledDesaturate),
     iconColor: (baseColor: string) => lighterBlend(baseColor, BlendTokenValues.iconLighter),
     

package/src/blend/__tests__/InteractionStateAudit.test.ts

@@ -13,7 +13,10 @@
  *   hover:    ΔL ∈ [0.02, 0.05], preserve chroma
  *   pressed:  ΔL ∈ [0.05, 0.10], preserve chroma
  *   focused:  ΔC ≥ 0.02 (chroma boost)
- *   disabled: ΔC ≥ 0.03 (chroma reduction)
+ *   disabled: ΔC ≥ 0.03 (chroma reduction) — calculator capability only;
+ *             no component declares a disabled state (state_disabled removed
+ *             from Button-CTA 2026-07-15, completing the no-disabled-states
+ *             philosophy across the corpus)
  *
  * Components audited:
  *   Button-CTA, Button-Icon, Button-VerticalList-Item, Chip-Base,
@@ -125,14 +128,14 @@ describe('Spec 112 Task 5.1: Interaction State Visual Audit', () => {
   });
 
   describe('Disabled state (ΔC ≥ 0.03 reduction)', () => {
-    // Only Button-CTA has a disabled state in DesignerPunk
-    const cases: [string, Oklch][] = [
-      ['Button-CTA (primary)', primaryButton],
-    ];
-
-    it.each(cases)('%s — ΔC reduction meets minimum', (name, base) => {
-      const result = calc.interactionBlend(base, 'disabled', lightSurface);
-      const dc = deltaC(base, result);
+    // No component declares a disabled state (no-disabled-states philosophy).
+    // blend.disabledDesaturate was deprecated 2026-07-15 (PR #83, Button-CTA
+    // disabled-state adjudication). This test validates the calculator
+    // capability only, retained for backward compatibility; remove at the
+    // next major version alongside the token itself.
+    it('calculator disabled blend — ΔC reduction meets minimum', () => {
+      const result = calc.interactionBlend(primaryButton, 'disabled', lightSurface);
+      const dc = deltaC(primaryButton, result);
       // dc should be negative (chroma reduced), absolute value ≥ 0.03
       expect(dc).toBeLessThan(0);
       expect(Math.abs(dc)).toBeGreaterThanOrEqual(INTERACTION_THRESHOLDS.disabled.deltaC.min);

package/src/build/errors/__tests__/ErrorHandler.integration.test.ts

@@ -13,6 +13,14 @@ import { createBuildError } from '../BuildError';
 import { BuildResultSummary } from '../ErrorReporter';
 
 describe('ErrorHandler - ErrorReporter Integration', () => {
+  beforeEach(() => {
+    jest.spyOn(console, 'error').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
   describe('generateReport', () => {
     it('should generate report from logged errors', () => {
       const handler = new ErrorHandler();

package/src/build/errors/__tests__/ErrorHandler.test.ts

@@ -13,9 +13,14 @@ describe('ErrorHandler', () => {
   let errorHandler: ErrorHandler;
 
   beforeEach(() => {
+    jest.spyOn(console, 'error').mockImplementation(() => {});
     errorHandler = new ErrorHandler();
   });
 
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
   describe('constructor', () => {
     it('should create ErrorHandler with default options', () => {
       const handler = new ErrorHandler();

package/src/build/tokens/__tests__/defineComponentTokens.test.ts

@@ -392,6 +392,119 @@ describe('defineComponentTokens', () => {
     });
   });
 
+  describe('Family-mismatch guard (reference path)', () => {
+    // A reference literal that carries `category`, as every real primitive in
+    // src/tokens/** does. The guard keys off this field.
+    const createMockPrimitiveWithCategory = (
+      name: string,
+      baseValue: number,
+      category: string
+    ): PrimitiveTokenReference => ({ name, baseValue, category });
+
+    test('throws when a reference primitive belongs to a different family than declared', () => {
+      const size600 = createMockPrimitiveWithCategory('size600', 48, 'sizing');
+
+      expect(() =>
+        defineComponentTokens({
+          component: 'ButtonIcon',
+          family: 'spacing',
+          tokens: {
+            'size.large': { reference: size600, reasoning: 'Large button size' },
+          },
+        })
+      ).toThrow(/Token family mismatch/);
+    });
+
+    test('error names the component, token, declared family, primitive and its real family', () => {
+      const size600 = createMockPrimitiveWithCategory('size600', 48, 'sizing');
+
+      let message = '';
+      try {
+        defineComponentTokens({
+          component: 'ButtonIcon',
+          family: 'spacing',
+          tokens: {
+            'size.large': { reference: size600, reasoning: 'Large button size' },
+          },
+        });
+      } catch (error) {
+        message = (error as Error).message;
+      }
+
+      expect(message).toContain("component 'ButtonIcon'");
+      expect(message).toContain("token 'size.large'");
+      expect(message).toContain("'spacing' family call");
+      expect(message).toContain("'size600'");
+      expect(message).toContain("'sizing' family");
+    });
+
+    test('regression: the real Button-Icon defect (PR #126) now fails at authoring time', () => {
+      // Before PR #126, buttonIcon.tokens.ts declared family 'spacing' while referencing
+      // sizing primitives. That produced `SpacingTokens.size600` — a member no generated
+      // platform file defines — and was caught only by reading generated Swift/Kotlin.
+      expect(() =>
+        defineComponentTokens({
+          component: 'ButtonIcon',
+          family: 'spacing',
+          tokens: {
+            'inset.large': {
+              reference: createMockPrimitiveWithCategory('space150', 12, 'spacing'),
+              reasoning: 'Correctly family-matched spacing token',
+            },
+            'size.large': {
+              reference: createMockPrimitiveWithCategory('size600', 48, 'sizing'),
+              reasoning: 'Mis-stamped sizing token — the defect',
+            },
+          },
+        })
+      ).toThrow(/references primitive 'size600' from the 'sizing' family/);
+    });
+
+    test('accepts a reference whose category matches the declared family', () => {
+      const size600 = createMockPrimitiveWithCategory('size600', 48, 'sizing');
+
+      const result = defineComponentTokens({
+        component: 'ButtonIcon',
+        family: 'sizing',
+        tokens: {
+          'size.large': { reference: size600, reasoning: 'Large button size' },
+        },
+      });
+
+      expect(result['size.large']).toBe(48);
+      expect((getTokenContract(result) ?? [])[0].family).toBe('sizing');
+    });
+
+    test('does not fire for reference literals without a category (back-compat)', () => {
+      const bareRef = createMockPrimitiveToken('space100', 8);
+
+      expect(() =>
+        defineComponentTokens({
+          component: 'ButtonIcon',
+          family: 'sizing',
+          tokens: {
+            'inset.small': { reference: bareRef, reasoning: 'Bare reference literal' },
+          },
+        })
+      ).not.toThrow();
+    });
+
+    test('does not fire for value-path tokens (the Avatar icon-size case is NOT covered)', () => {
+      // Documents a real limitation: the Avatar `icon.size.*` gap fillers were mis-stamped
+      // `family: 'spacing'` on the VALUE path. No reference exists to cross-check, so this
+      // guard cannot catch that class of mislabel.
+      expect(() =>
+        defineComponentTokens({
+          component: 'Avatar',
+          family: 'spacing',
+          tokens: {
+            'icon.size.xs': { value: 12, reasoning: 'Dimensional value in a spacing call' },
+          },
+        })
+      ).not.toThrow();
+    });
+  });
+
   describe('Idempotent re-branding (Spec 124, caveat c)', () => {
     test('re-applying the brand to the same return does not throw', () => {
       const result = defineComponentTokens({

package/src/build/tokens/defineComponentTokens.ts

@@ -65,6 +65,16 @@ export interface PrimitiveTokenReference {
   name: string;
   /** Unitless base value from the primitive token */
   baseValue: number;
+  /**
+   * Primitive token family (the `category` field of a `PrimitiveToken`, e.g. 'spacing',
+   * 'sizing', 'radius'). OPTIONAL for backward compatibility: minimal `{ name, baseValue }`
+   * reference literals remain valid.
+   *
+   * When present, it is cross-checked against the call's declared `family` by the
+   * family-mismatch guard in {@link defineComponentTokens}. Real primitives from
+   * src/tokens/** always carry it, so the guard is active for all production authoring.
+   */
+  category?: string;
 }
 
 /**
@@ -216,8 +226,40 @@ export function defineComponentTokens<T extends Record<string, TokenDefinition>>
     if (isTokenWithReference(definition)) {
       // Token with primitive reference
       const primitiveToken = definition.reference;
+
+      // FAMILY-MISMATCH GUARD.
+      // The call's `family` is stamped onto every token it registers, and the generator
+      // derives platform output from it — notably the primitive class name used for
+      // reference-path tokens (getFamilyClassName) and the Android `.dp` suffix. A call
+      // that declares one family but references another family's primitive therefore emits
+      // a member that does not exist on the target platform. That is exactly the Button-Icon
+      // defect: a `family: 'spacing'` call referencing `sizingTokens.size600` generated
+      // `SpacingTokens.size600`, a non-existent member (PR #126).
+      //
+      // Only enforced when the reference carries a `category` — minimal `{ name, baseValue }`
+      // literals (used widely in tests) are intentionally exempt rather than rejected.
+      //
+      // Escape hatch: a token that legitimately needs another family's VALUE should use the
+      // value path (`value:`), which asserts no cross-family token-chain claim.
+      if (
+        typeof primitiveToken.category === 'string' &&
+        primitiveToken.category !== family
+      ) {
+        throw new Error(
+          `Token family mismatch in defineComponentTokens() for component '${component}': ` +
+          `token '${key}' is declared in a '${family}' family call but references primitive ` +
+          `'${primitiveToken.name}' from the '${primitiveToken.category}' family. ` +
+          `Every token in a call is stamped with that call's family, which drives platform ` +
+          `output (e.g. the generated '${family.charAt(0).toUpperCase() + family.slice(1)}Tokens' ` +
+          `class reference), so this would emit a non-existent platform member. ` +
+          `Fix: move '${key}' into a separate defineComponentTokens() call with ` +
+          `family: '${primitiveToken.category}', or use the value path if no token-chain ` +
+          `relationship is intended.`
+        );
+      }
+
       const value = primitiveToken.baseValue;
-      
+
       values[key] = value;
       registeredTokens.push({
         name: tokenName,

package/src/build/workflow/__tests__/CICDIntegration.test.ts

@@ -490,9 +490,20 @@ describe('CICDIntegration', () => {
   
   describe('Environment Detection', () => {
     const originalEnv = process.env;
-    
+
     beforeEach(() => {
       process.env = { ...originalEnv };
+      // Neutralize the HOST's own CI environment before each scenario. On a real CI
+      // runner (e.g. GitHub Actions) the ambient GITHUB_ACTIONS/CI vars leak into the
+      // copied env and win detectCICDEnvironment()'s precedence order, so the GitLab
+      // and generic-CI scenarios detected 'github' instead — these tests only ever
+      // passed on laptops because laptops aren't CI (125-A Task 6, lane-timing run #2
+      // finding). Each scenario sets exactly the vars it means to test.
+      delete process.env.GITHUB_ACTIONS;
+      delete process.env.GITHUB_WORKFLOW;
+      delete process.env.GITLAB_CI;
+      delete process.env.CI_PIPELINE_ID;
+      delete process.env.CI;
     });
     
     afterEach(() => {