@3fn/core 14.0.0 → 14.1.0

package/governance/release-management-system.md

@@ -1,14 +1,19 @@
 ---
 id: release-management-system
 inclusion: manual
+name: Release Management System
+description: The release recipe (derive-classify-ratify, hand-authored notes) and how agents discover what changed and why — replaces the retired automated release tool
+aliases: release recipe, release process, release notes, what changed, version bump, changelog, release delta
 ---
 
 # Release Management System
 
+> **Audience framing**: this documents **DesignerPunk's own** release process. Consumers of the package read it as a worked example of a recipe-over-tooling release model — the paths, scripts, and named roles below are DesignerPunk's, not yours. (Whether DesignerPunk's release notes themselves ship to consumers is an open Spec 123 question, deferred by the Q6 ballot.)
+
 **Date**: 2026-02-28
-**Last Reviewed**: 2026-07-05
-**Last Updated**: 2026-02-28
-**Purpose**: Mental model of the release management system for AI agents
+**Last Reviewed**: 2026-08-12
+**Last Updated**: 2026-08-12
+**Purpose**: Mental model of the release process for AI agents — the recipe, and how to discover what changed and why
 **Organization**: process-standard
 **Scope**: cross-project
 **Layer**: 2
@@ -18,72 +23,32 @@ inclusion: manual
 
 ## Overview
 
-The release tool is an on-demand CLI at `src/tools/release/`. It replaces the previous 203-file system with a focused pipeline: discover summary docs since last git tag → extract structured changes → classify by priority → recommend version bump → generate markdown release notes → optionally create GitHub release.
-
-**Key principles:**
-- Runs on-demand only. No timers, no hooks, no passive file generation.
-- Git tags are the only persistent state. No state files, no caches, no history accumulation.
-- Human-reviewed before publishing. The tool recommends; Peter decides.
+Releases are executed by a **documented recipe, not a standing tool**. The automated release manager (an on-demand CLI that scanned spec summary docs to recommend versions and generate notes) was **RETIRED on 2026-08-12** — Q6 ballot: `.kiro/docs/ballots/2026-08-12-q6-release-manager-retirement.md`. It was retired because the PR gate made it redundant-and-worse: every merge to `main` is one squash commit whose title is a disciplined change description, so the release delta is derivable with one `git log` — while the tool, reading only spec summaries, was structurally blind to issue-driven work and mis-recommended the v14.0.0 release outright (patch/"no consumer-facing changes" against a breaking component wave).
 
----
+**Key principles (unchanged by the retirement):**
+- Human-reviewed, human-decided: the recipe derives and drafts; **the repo's release owner (in DesignerPunk: Peter) ratifies the version bump and merges the release PR**.
+- Git tags are the only persistent release state.
+- Verification stays mechanized; judgment stays human. DesignerPunk's publish guard scripts (`check:drift`, `verify:token-index-clean`, the `prepublishOnly` chain — this repo's package scripts, not shipped to consumers) block a broken publish mechanically and are NOT part of the retired tool.
 
-## Architecture
+## The Release Recipe
 
-```
-CLI Entry Point (src/tools/release/cli/release-tool.ts)
-  ├── analyze  → ReleasePipeline.analyze()
-  ├── notes    → ReleasePipeline.generateNotes()
-  └── release  → ReleasePipeline.release()
+The operational sequence lives in `.kiro/hooks/RELEASE-FLOW.md` (the PR-gated release flow). The judgment half, summarized:
 
-ReleasePipeline (src/tools/release/cli/ReleasePipeline.ts)
-  ├── TagResolver        — git describe --tags --abbrev=0
-  ├── SummaryScanner     — git log + glob docs/specs/*/task-*-summary.md
-  ├── ChangeExtractor    — parse summary doc markdown sections
-  ├── ChangeClassifier   — map to 🔴 breaking / 🟡 prominent / 🔵 context
-  ├── NotesRenderer      — markdown generation (public + internal)
-  └── GitHubPublisher    — git tag + GitHub release creation
-```
-
----
+1. **Derive the delta**: `git log $(git describe --tags --abbrev=0)..main --oneline` — every line is a squash-merged PR title (the changelog spine). Scope a second pass to the shipped surface to separate consumer-facing from internal — **the authoritative shipped-surface list is `package.json` `files[]`** (fifteen-plus roots beyond `src/`, including `governance/` and the other served-content roots; scoping to `src/` alone would have dropped v14.0.0's docs-corpus entry).
+2. **Classify**: for each change, read its task summary (`docs/specs/…`) or PR body for substance; classify 🔴 breaking / 🟡 minor / 🔵 patch-or-internal. Issue-driven work has no summary doc — its PR title and body are the record; do not assume spec-shaped work is the whole delta (the retired tool's fatal assumption).
+3. **Recommend the bump; the release owner ratifies.** Removals or behavior breaks → major. New behavior → minor. Fixes/internal → patch.
+4. **Hand-author the notes** at `docs/releases/release-X.Y.Z.md` (v14.0.0 is the format precedent). Notes ride the release PR with the version bump and any token-index regeneration.
+5. **Publish per RELEASE-FLOW.md** (repo-internal; and the dual-registry playbook it references): release PR → the release owner merges → publish from merged `main` → then tag and GitHub release: `git tag -a vX.Y.Z && git push origin vX.Y.Z && gh release create vX.Y.Z --notes-file docs/releases/release-X.Y.Z.md`.
 
-## CLI Commands
-
-| Command | What It Does | When to Use |
-|---------|-------------|-------------|
-| `npm run release:analyze` | Scan changes since last tag, display recommendation | Check what's accumulated |
-| `npm run release:notes` | Generate markdown release notes to `docs/releases/` | Preview release content |
-| `npm run release:run` | Full release: notes + tag + GitHub publish | Actual release |
-| `npm run release:run -- --dry-run` | Preview release without tagging or publishing | Pre-release check |
-
-Shell wrapper: `./.kiro/hooks/release-manager.sh analyze|notes|release`
-
----
+## Discovering What Changed and Why
 
-## AI Agent Decision Points
+Agents answering "what changed, and why?" — for any purpose, not just releases — follow the record chain. *(Consumer note: in a consumer repo only the served governance corpus is reachable; the chain's other paths are DesignerPunk-internal — the PATTERN transfers, the paths don't.)*
 
-### 1. Summary Document Quality
-Release notes are generated from summary docs. Better summaries → better release notes.
-- **What Was Done** → becomes the change description
-- **Key Changes** → becomes the bullet points
-- **Deliverables** → drives priority classification (🔴/🟡/🔵)
+1. **What, at a glance**: squash-commit titles on `main` (`git log vX..vY --oneline`, or between any two points). Every commit is a PR with a disciplined title.
+2. **What, curated per release**: `docs/releases/release-X.Y.Z.md` — hand-authored, consumer-facing framing, breaking changes called out with migration guidance.
+3. **Why, per task**: `docs/specs/[spec]/task-N-summary.md` (public summary) and `.kiro/specs/[spec]/completion/` (detailed record) — for spec-shaped work. For issue-driven work: the PR body and any `.kiro/issues/` record.
+4. **Why, decision-grade**: `.kiro/docs/ballots/` (ratified decisions with their evidence and counter-arguments) and `governance/classification-map.md` (per-rule classifications with dated history). When a change traces to a ruling, the ballot is the authoritative why.
 
-### 2. Deliverables Section
-When present, the `## Deliverables *(optional)*` section drives classification directly:
-- `🔴` → breaking/consumer-facing → major bump
-- `🟡` → ecosystem → minor bump
-- `🔵` → internal/context → patch bump
-
-When absent, keyword heuristics apply (less accurate, human-reviewed anyway).
-
-### 3. Summary Document Location
-Must be `docs/specs/[spec-name]/task-N-summary.md` — the scanner looks here via git log.
-
----
-
-## Post-Commit Analysis
-
-`release:analyze` runs post-merge on `main` (non-blocking, informational) — merged history is the analysis's correct input. Run `npm run release:analyze` locally for on-demand detail.
-
----
+## Historical Note
 
-*For operational task completion workflow, see Process-Development-Workflow.md.*
+The retired tool's own history is instructive: it replaced a 203-file predecessor (Spec 065's rebuild), and its retirement continues that simplification — 203 files → 24 files → a recipe — completed once the PR gate supplied, as a by-product of merge discipline, the structured change record the tooling existed to reconstruct. Records: Spec 065 (the rebuild), the Q6 ballot (the retirement), `docs/releases/release-14.0.0.md` (the live trial that settled it).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@3fn/core",
-  "version": "14.0.0",
+  "version": "14.1.0",
   "description": "True Native cross-platform design system with mathematical foundations",
   "license": "Apache-2.0",
   "author": "Peter Michaels Allen",
@@ -115,11 +115,6 @@
     "test:performance:isolated": "jest --config jest.performance.config.js --runInBand",
     "test:watch": "jest --watch --config jest.functional.config.js",
     "test:coverage": "jest --coverage --config jest.functional.config.js",
-    "release:analyze": "npx tsx src/tools/release/cli/release-tool.ts analyze",
-    "release:notes": "npx tsx src/tools/release/cli/release-tool.ts notes",
-    "release:run": "npx tsx src/tools/release/cli/release-tool.ts release",
-    "validate:release-setup": "node scripts/validate-release-setup.js",
-    "diagnose:release-issues": "node scripts/diagnose-release-issues.js",
     "audit:tokens": "node scripts/audit-component-tokens.js",
     "audit:tokens:detailed": "node scripts/audit-component-tokens.js -- --detailed",
     "audit:coverage-map": "npx tsx tools/agent-generator/coverage-map.ts",
@@ -133,6 +128,7 @@
     "figma:generate-component": "npx tsx scripts/figma-component-generator.ts",
     "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",
     "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/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/components/core/Avatar-Base/avatar.tokens.ts

@@ -33,7 +33,16 @@
  * Icon Size Derivations (in Avatar.web.ts):
  * - xs: calc(icon.size050 × 0.75) = 12px
  * - xxl: calc(icon.size050 × 4) = 64px
- * 
+ *
+ * TOKEN FAMILY: all dimensional Avatar tokens (container `size.*` AND icon
+ * `icon.size.*` gap fillers) are registered by the single sizing-family call
+ * `AvatarSizingTokens` below. The `icon.size.*` pair previously lived in a
+ * separate `AvatarTokens` call stamped `family: 'spacing'` — a mislabel, since
+ * both are dimensional sizing values. `AvatarTokens` is removed; consumers use
+ * `AvatarSizingTokens` or the `getAvatarIconSize()` / `getAvatarSize()` accessors.
+ * Generated platform output is unaffected: both calls declare `component: 'Avatar'`,
+ * so all tokens still land in one `AvatarTokens` Swift enum / Kotlin object.
+ *
  * COLOR TOKENS (Spec 058):
  * Avatar color tokens are defined in this file following the Rosetta System architecture
  * which mandates component tokens live at src/components/[ComponentName]/tokens.ts.
@@ -56,13 +65,24 @@ import { defineComponentTokens } from '../../../build/tokens';
 import { SIZING_BASE_VALUE, sizingTokens } from '../../../tokens/SizingTokens';
 
 /**
- * Avatar sizing tokens — container dimensions for each size variant.
+ * Avatar sizing tokens — container dimensions and icon dimensions for each size variant.
  *
  * Previously in a separate file (avatar-sizing.tokens.ts). Inlined to prevent
  * architectural anomaly (no other component splits tokens across files) and
  * simplify the package surface for sync.
  *
+ * ONE CALL PER FAMILY. Every token registered by a single defineComponentTokens()
+ * call is stamped with that call's `family`, and the family drives platform output
+ * (Swift type, Kotlin `.dp` suffix, primitive class name). The `icon.size.*` gap
+ * fillers below are dimensional sizing values, so they live in this sizing-family
+ * call — they were previously mis-stamped `family: 'spacing'` in a separate
+ * `AvatarTokens` call, the same latent mislabel class fixed for Button-Icon.
+ * Do NOT spread/merge this result with another call's result — the rich metadata
+ * rides on a non-enumerable brand (see src/build/tokens/defineComponentTokens.ts,
+ * TOKEN_CONTRACT_BRAND) that a spread would silently drop.
+ *
  * @see .kiro/specs/092-sizing-token-family/design.md
+ * @see src/components/core/Button-Icon/buttonIcon.tokens.ts for the two-call pattern
  */
 export const AvatarSizingTokens = defineComponentTokens({
   component: 'Avatar',
@@ -92,38 +112,15 @@ export const AvatarSizingTokens = defineComponentTokens({
       reference: sizingTokens.size1600,
       reasoning: 'Extra extra large avatar (128px). Full profile view, onboarding.',
     },
-  },
-});
 
-/**
- * Avatar component tokens defined using the hybrid authoring API.
- * 
- * Each token either references a primitive spacing token or uses a family-conformant
- * derivation, and includes reasoning explaining why the token exists.
- * 
- * NOTE: Web platform uses CSS calc() with icon tokens for sizing (see Avatar.styles.css).
- * These component tokens are primarily used for iOS/Android platforms and documentation.
- * 
- * Size token values:
- * - size.xs: 24px (3 × base, references size300)
- * - size.sm: 32px (4 × base, references size400)
- * - size.md: 40px (5 × base, references size500)
- * - size.lg: 48px (6 × base, references size600)
- * - size.xl: 80px (10 × base, derivation)
- * - size.xxl: 128px (16 × base, derivation)
- * 
- * Icon size token values (gap fillers - web uses calc() instead):
- * - icon.size.xs: 12px (1.5 × base, derivation) - web uses calc(icon.size050 × 0.75)
- * - icon.size.xxl: 64px (8 × base, derivation) - web uses calc(icon.size050 × 4)
- * 
- * @see Requirements 2.1-2.6, 3.1, 3.6 in .kiro/specs/042-avatar-component/requirements.md
- */
-export const AvatarTokens = defineComponentTokens({
-  component: 'Avatar',
-  family: 'spacing',
-  tokens: {
-    // Icon size tokens (gap fillers for sizes without existing icon tokens)
-    // These fill gaps where no standard icon token exists at the required 50% ratio
+    // Icon size tokens (gap fillers for sizes without an existing icon token).
+    // Kept on the VALUE path deliberately: sizing primitives exist at both values
+    // (size150 = 12, size800 = 64), but the reference path currently emits a
+    // fabricated `SizingTokens.<name>` class on iOS/Android that no generated or
+    // hand-written platform file defines. Switching these to `reference:` would
+    // trade compiling output (`12.dp`) for non-compiling output and break
+    // Avatar.android.kt's `val iconSizeXs: Dp = GeneratedAvatarTokens.iconSizeXs`.
+    // Revisit once TokenFileGenerator.getFamilyClassName emits a real platform type.
     'icon.size.xs': {
       value: SIZING_BASE_VALUE * 1.5,
       reasoning: 'Icon size for xs avatar (12px = 1.5× base) maintains 50% ratio (12/24). No existing icon token at this size, so component token fills the gap.',
@@ -273,7 +270,7 @@ export function getAvatarSize(variant: AvatarSizeVariant): number {
  * @see Requirements 3.1, 3.6 in .kiro/specs/042-avatar-component/requirements.md
  */
 export function getAvatarIconSize(variant: AvatarIconSizeVariant): number {
-  return AvatarTokens[`icon.size.${variant}`];
+  return AvatarSizingTokens[`icon.size.${variant}`];
 }
 
 /**

package/src/components/core/Avatar-Base/index.ts

@@ -11,7 +11,7 @@ export { AVATAR_DEFAULTS } from './types';
 
 // Token exports
 export {
-  AvatarTokens,
+  AvatarSizingTokens,
   getAvatarSize,
   getAvatarIconSize,
   getAvatarSizeTokenReference,

package/src/components/core/Button-Icon/buttonIcon.tokens.ts

@@ -1,26 +1,35 @@
 /**
  * Button-Icon Component Token Definitions
- * 
+ *
  * Stemma System naming: [Family]-[Type] = Button-Icon
  * Type: Primitive (foundational component)
- * 
+ *
  * Platform-agnostic token definitions for the Button-Icon component.
  * Uses the defineComponentTokens() API to register tokens with the global
  * ComponentTokenRegistry for pipeline integration.
- * 
+ *
+ * Two separate defineComponentTokens() calls are used — one per token family
+ * (spacing, sizing) — following the Avatar-Base pattern (avatar.tokens.ts). Every
+ * token registered by a single call is stamped with that call's `family`, so inset
+ * (spacing) and size (sizing) tokens must NOT share a call even though they live in
+ * the same file. The two branded results are exported separately and must NOT be
+ * spread/merged into one object — the rich metadata rides on a non-enumerable brand
+ * (see src/build/tokens/defineComponentTokens.ts, TOKEN_CONTRACT_BRAND) that a spread
+ * would silently drop.
+ *
  * The build system generates platform-specific values from these definitions:
  * - Web: CSS custom properties (var(--buttonicon-inset-large))
  * - iOS: Swift constants (ButtonIconTokens.insetLarge)
  * - Android: Kotlin constants (ButtonIconTokens.insetLarge)
- * 
+ *
  * Token Relationships:
- * - buttonIcon.inset.large (12px) references space150
- * - buttonIcon.inset.medium (10px) references space125 (strategic flexibility token)
- * - buttonIcon.inset.small (8px) references space100
- * - buttonIcon.size.large (48px) references size600
- * - buttonIcon.size.medium (40px) references size500
- * - buttonIcon.size.small (32px) references size400
- * 
+ * - buttonIcon.inset.large (12px) references space150 — family: spacing
+ * - buttonIcon.inset.medium (10px) references space125 (strategic flexibility token) — family: spacing
+ * - buttonIcon.inset.small (8px) references space100 — family: spacing
+ * - buttonIcon.size.large (48px) references size600 — family: sizing
+ * - buttonIcon.size.medium (40px) references size500 — family: sizing
+ * - buttonIcon.size.small (32px) references size400 — family: sizing
+ *
  * @see .kiro/specs/035-button-icon-component/design.md for token consumption strategy
  * @see .kiro/specs/034-component-architecture-system for Stemma System details
  * @see .kiro/specs/037-component-token-generation-pipeline for pipeline integration
@@ -32,28 +41,21 @@ import { spacingTokens } from '../../../tokens/SpacingTokens';
 import { sizingTokens } from '../../../tokens/SizingTokens';
 
 /**
- * Button-Icon component tokens defined using the hybrid authoring API.
- * 
+ * Button-Icon inset (padding) tokens — reference spacing primitives.
+ *
  * Each token references a primitive token and includes reasoning
  * explaining why the token exists and its purpose in the component.
- * 
- * Inset (padding) token values — reference spacing primitives:
+ *
  * - inset.large: 12px (1.5 × base, references space150)
  * - inset.medium: 10px (1.25 × base, references space125 strategic flexibility token)
  * - inset.small: 8px (1 × base, references space100)
- * 
- * Size (width/height) token values:
- * - size.large: 48px (6 × base, references size600)
- * - size.medium: 40px (5 × base, references size500)
- * - size.small: 32px (4 × base, references size400)
- * 
+ *
  * @see Requirements 6.1, 6.2, 6.3 in .kiro/specs/040-component-alignment/requirements.md
  */
-export const ButtonIconTokens = defineComponentTokens({
+export const ButtonIconInsetTokens = defineComponentTokens({
   component: 'ButtonIcon',
   family: 'spacing',
   tokens: {
-    // Inset (padding) tokens
     'inset.large': {
       reference: spacingTokens.space150,
       reasoning: 'Large button variant requires 12px padding (1.5× base) for comfortable touch target and visual balance with larger icon sizes',
@@ -66,8 +68,22 @@ export const ButtonIconTokens = defineComponentTokens({
       reference: spacingTokens.space100,
       reasoning: 'Small button variant uses 8px padding (1× base) for minimal footprint in dense UI layouts while meeting minimum touch target requirements',
     },
-    // Size (width/height) tokens — reference sizing primitives, not spacing
-    // @see Requirements 6.1, 6.2, 6.3
+  },
+});
+
+/**
+ * Button-Icon size (width/height) tokens — reference sizing primitives, not spacing.
+ *
+ * - size.large: 48px (6 × base, references size600)
+ * - size.medium: 40px (5 × base, references size500)
+ * - size.small: 32px (4 × base, references size400)
+ *
+ * @see Requirements 6.1, 6.2, 6.3 in .kiro/specs/040-component-alignment/requirements.md
+ */
+export const ButtonIconSizeTokens = defineComponentTokens({
+  component: 'ButtonIcon',
+  family: 'sizing',
+  tokens: {
     'size.large': {
       reference: sizingTokens.size600,
       reasoning: 'Large button size (48px = 6× base) provides generous touch target exceeding tapAreaRecommended, calculated as icon (24px) + padding (12px × 2)',
@@ -107,7 +123,7 @@ export type ButtonIconSizeVariant = 'large' | 'medium' | 'small';
  * ```
  */
 export function getButtonIconInset(variant: ButtonIconInsetVariant): number {
-  return ButtonIconTokens[`inset.${variant}`];
+  return ButtonIconInsetTokens[`inset.${variant}`];
 }
 
 /**
@@ -126,7 +142,7 @@ export function getButtonIconInset(variant: ButtonIconInsetVariant): number {
  * @see Requirements 6.1, 6.2, 6.3 in .kiro/specs/040-component-alignment/requirements.md
  */
 export function getButtonIconSize(variant: ButtonIconSizeVariant): number {
-  return ButtonIconTokens[`size.${variant}`];
+  return ButtonIconSizeTokens[`size.${variant}`];
 }
 
 /**

package/src/generators/TokenFileGenerator.ts

@@ -565,6 +565,7 @@ export class TokenFileGenerator {
   private getiOSComponentTokenType(token: RegisteredComponentToken): string {
     switch (token.family) {
       case 'spacing':
+      case 'sizing':
       case 'radius':
       case 'fontSize':
       case 'tapArea':
@@ -619,8 +620,12 @@ export class TokenFileGenerator {
       const familyClass = this.getFamilyClassName(token.family);
       return `${familyClass}.${token.primitiveReference}`;
     }
-    // Dimensional families need .dp suffix to match primitive token output (Task 1.4)
-    const dimensionalFamilies = ['spacing', 'radius', 'tapArea', 'fontSize', 'borderWidth'];
+    // Dimensional families need .dp suffix to match primitive token output (Task 1.4).
+    // 'sizing' is dimensional (component width/height) and belongs here: without it, a
+    // value-path sizing token emits a bare Int, which fails to compile against consumers
+    // that type the member as Dp (e.g. Avatar.android.kt's
+    // `val iconSizeXs: Dp = GeneratedAvatarTokens.iconSizeXs`).
+    const dimensionalFamilies = ['spacing', 'sizing', 'radius', 'tapArea', 'fontSize', 'borderWidth'];
     if (dimensionalFamilies.includes(token.family)) {
       return `${token.value}.dp`;
     }

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', () => {
   // ==========================================================================