@3fn/core 14.0.0 → 14.1.0

package/dist/tokens/component/progress.js

@@ -21,7 +21,8 @@
  * @see .kiro/specs/048-progress-family/design.md (Size Variant, Token Usage sections)
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.progressComponentTokenNames = exports.PROGRESS_COMPONENT_TOKEN_COUNT = exports.ProgressTokens = void 0;
+exports.progressComponentTokenNames = exports.PROGRESS_COMPONENT_TOKEN_COUNT = exports.progressTokenValues = exports.ProgressBorderWidthTokens = exports.ProgressSpacingTokens = exports.ProgressSizingTokens = void 0;
+exports.getProgressRegisteredTokens = getProgressRegisteredTokens;
 exports.validateProgressComponentTokenCount = validateProgressComponentTokenCount;
 exports.getProgressComponentToken = getProgressComponentToken;
 exports.getAllProgressComponentTokens = getAllProgressComponentTokens;
@@ -30,20 +31,37 @@ const SpacingTokens_1 = require("../../tokens/SpacingTokens");
 const SizingTokens_1 = require("../../tokens/SizingTokens");
 const BorderWidthTokens_1 = require("../../tokens/BorderWidthTokens");
 /**
- * Progress Indicator component tokens defined using the hybrid authoring API.
+ * 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 — notably the primitive class
+ * name emitted for reference-path tokens (TokenFileGenerator.getFamilyClassName) and the
+ * Android `.dp` suffix. These 10 tokens span THREE primitive families, so they require
+ * three calls. A single `family: 'spacing'` call previously produced
+ * `SpacingTokens.size150` / `SpacingTokens.borderWidth100` — members no generated platform
+ * file defines — the same defect fixed for Button-Icon in PR #126.
+ *
+ * The three branded results MUST NOT be spread/merged into one registration object: the
+ * rich metadata rides on a non-enumerable brand (src/build/tokens/defineComponentTokens.ts,
+ * TOKEN_CONTRACT_BRAND) that a spread silently drops. The harvest in loadComponentTokens
+ * collects each branded export separately. Use {@link progressTokenValues} for flat
+ * value lookups and {@link getProgressRegisteredTokens} for the rich metadata.
+ *
+ * All three calls declare `component: 'Progress'`, so platform output is still a single
+ * `ProgressTokens` Swift enum / Kotlin object.
+ */
+/**
+ * Node dimension tokens — reference sizing primitives (dimensions, not spacing).
  *
- * 13 tokens organized by concept:
  * - node.size.{sm|md|lg}         — base node dimensions
  * - node.size.{sm|md|lg}.current — emphasized node dimensions (+4px)
- * - node.gap.{sm|md|lg}          — spacing between nodes
- * - connector.thickness           — connector line width
  */
-exports.ProgressTokens = (0, tokens_1.defineComponentTokens)({
+exports.ProgressSizingTokens = (0, tokens_1.defineComponentTokens)({
     component: 'Progress',
-    family: 'spacing',
+    family: 'sizing',
     tokens: {
         // ========================================================================
-        // BASE NODE SIZES — reference sizing primitives (dimensions, not spacing)
+        // BASE NODE SIZES
         // ========================================================================
         'node.size.sm': {
             reference: SizingTokens_1.sizingTokens.size150,
@@ -58,7 +76,7 @@ exports.ProgressTokens = (0, tokens_1.defineComponentTokens)({
             reasoning: 'Large node base size (20px). Inactive dots in desktop contexts.',
         },
         // ========================================================================
-        // CURRENT NODE SIZES — reference sizing primitives directly (+4px emphasis)
+        // CURRENT NODE SIZES — +4px emphasis
         // Provides non-color visual differentiation of active position
         // ========================================================================
         'node.size.sm.current': {
@@ -73,9 +91,17 @@ exports.ProgressTokens = (0, tokens_1.defineComponentTokens)({
             reference: SizingTokens_1.sizingTokens.size300,
             reasoning: 'Current node emphasis for lg (24px). +4px over base 20px for non-color visual differentiation.',
         },
-        // ========================================================================
-        // GAP TOKENS — spacing between nodes (gaps are spacing, not sizing)
-        // ========================================================================
+    },
+});
+/**
+ * Node gap tokens — reference spacing primitives (gaps are spacing, not sizing).
+ *
+ * - node.gap.{sm|md|lg} — spacing between nodes
+ */
+exports.ProgressSpacingTokens = (0, tokens_1.defineComponentTokens)({
+    component: 'Progress',
+    family: 'spacing',
+    tokens: {
         'node.gap.sm': {
             reference: SpacingTokens_1.spacingTokens.space075,
             reasoning: 'Small gap between nodes (6px = 0.75× base). Tight spacing for compact pagination dots in mobile contexts.',
@@ -88,15 +114,50 @@ exports.ProgressTokens = (0, tokens_1.defineComponentTokens)({
             reference: SpacingTokens_1.spacingTokens.space150,
             reasoning: 'Large gap between nodes (12px = 1.5× base). Generous spacing for detailed steppers with labels in desktop contexts.',
         },
-        // ========================================================================
-        // CONNECTOR TOKENS — line connecting nodes in steppers
-        // ========================================================================
+    },
+});
+/**
+ * Connector tokens — line connecting nodes in steppers. References a borderWidth primitive.
+ *
+ * - connector.thickness — connector line width
+ */
+exports.ProgressBorderWidthTokens = (0, tokens_1.defineComponentTokens)({
+    component: 'Progress',
+    family: 'borderWidth',
+    tokens: {
         'connector.thickness': {
             reference: BorderWidthTokens_1.borderWidthTokens.borderWidth100,
             reasoning: 'Connector line thickness (1px). References borderDefault primitive for consistent border treatment across the design system.',
         },
     },
 });
+/**
+ * Flat value map across all three Progress token calls — a READ-ONLY convenience for
+ * value lookups (`progressTokenValues['node.size.md']`).
+ *
+ * NOT a registration surface: spreading drops the non-enumerable brand, so this object
+ * deliberately harvests to zero and cannot double-register. For the rich metadata use
+ * {@link getProgressRegisteredTokens}, never `getTokenContract(progressTokenValues)`.
+ */
+exports.progressTokenValues = {
+    ...exports.ProgressSizingTokens,
+    ...exports.ProgressSpacingTokens,
+    ...exports.ProgressBorderWidthTokens,
+};
+/**
+ * All Progress component tokens with their rich metadata, concatenated across the three
+ * family calls in declaration order (sizing → spacing → borderWidth).
+ *
+ * This is the brand-safe replacement for `getTokenContract(ProgressTokens)`, which is no
+ * longer meaningful now that Progress registers through three calls.
+ */
+function getProgressRegisteredTokens() {
+    return [
+        ...((0, tokens_1.getTokenContract)(exports.ProgressSizingTokens) ?? []),
+        ...((0, tokens_1.getTokenContract)(exports.ProgressSpacingTokens) ?? []),
+        ...((0, tokens_1.getTokenContract)(exports.ProgressBorderWidthTokens) ?? []),
+    ];
+}
 // ============================================================================
 // Constants and Utilities
 // ============================================================================
@@ -128,18 +189,18 @@ exports.progressComponentTokenNames = [
  * Validate that the progress component token count matches the expected count (13)
  */
 function validateProgressComponentTokenCount() {
-    return Object.keys(exports.ProgressTokens).length === exports.PROGRESS_COMPONENT_TOKEN_COUNT;
+    return Object.keys(exports.progressTokenValues).length === exports.PROGRESS_COMPONENT_TOKEN_COUNT;
 }
 /**
  * Get a single progress component token value by key
  */
 function getProgressComponentToken(key) {
-    return exports.ProgressTokens[key];
+    return exports.progressTokenValues[key];
 }
 /**
  * Get all progress component token entries as key-value pairs
  */
 function getAllProgressComponentTokens() {
-    return Object.entries(exports.ProgressTokens).map(([name, value]) => ({ name, value }));
+    return Object.entries(exports.progressTokenValues).map(([name, value]) => ({ name, value }));
 }
 //# sourceMappingURL=progress.js.map

package/dist/types/generated/TokenTypes.d.ts

@@ -6,7 +6,7 @@
  *
  * To regenerate: npm run generate:types
  *
- * Generated: 2026-08-12T03:23:16.669Z
+ * Generated: 2026-08-26T14:15:23.873Z
  */
 /**
  * Union type of all semantic color token names

package/dist/types/generated/TokenTypes.js

@@ -7,7 +7,7 @@
  *
  * To regenerate: npm run generate:types
  *
- * Generated: 2026-08-12T03:23:16.669Z
+ * Generated: 2026-08-26T14:15:23.873Z
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isColorTokenName = isColorTokenName;

package/dist/web/DesignTokens.web.css

@@ -1,6 +1,6 @@
 /**
  * DesignerPunk Design System - Web Tokens
- * Generated: 2026-08-02T19:49:06.807Z
+ * Generated: 2026-08-26T02:25:48.240Z
  * Version: 1.0.0
  * Platform: Web (CSS Custom Properties)
  *

package/governance/BUILD-SYSTEM-SETUP.md

@@ -125,7 +125,7 @@ The `build:verify` script (`verify-build.js`) checks that:
 
 ### You DON'T need to build when:
 - Running tests with `npm test` (ts-jest handles compilation)
-- Using CLI tools that run via tsx (e.g., the release tool: `npx tsx src/tools/release/cli/release-tool.ts analyze`)
+- Using CLI tools that run via tsx (e.g., the agent generator: `npx tsx tools/agent-generator/generate.ts`)
 - Making changes and running tests immediately
 
 ## Development Workflow
@@ -215,7 +215,6 @@ The build system now enforces full TypeScript type safety:
 ### Option 1: Separate Build Configs
 Create separate `tsconfig.json` files for different parts of the codebase:
 - `tsconfig.tokens.json` - Just token generation code
-- `tsconfig.release.json` - Release analysis code
 
 ### Module-resolution direction (settled — Spec 118)
 *(Supersedes the former "Go Full ts-node" option, which is moot: ts-node is retired from the governed surface.)* The settled direction is **compiled-`dist/` for package own code** (Class A — CLI, generators, exports run as compiled JS) and **scoped `tsx`** as the sole runtime-TS mechanism for consumer `.ts` (Class B). See the Rosetta-System-Architecture "Module-Resolution Contract (Spec 118)" for the full contract; full ESM modernization is a separate, externally-triggered future migration tracked in `docs/roadmap/m0a-deferred-items.md`.

package/governance/Component-Development-Guide.md

@@ -1876,7 +1876,7 @@ Components come with their own unique properties that might include, but are not
 5. **README** (required) - Create comprehensive component documentation
 6. **HTML Canaries** (required) - Create validation examples
 7. **Implementation** (required) - Build component across platforms
-8. **Dark Mode Token Population** (if component has dark mode differentiation) - Coordinate with Ada to populate the component's semantic color token entries in the dark theme file (`src/tokens/themes/dark/SemanticOverrides.ts`). Identify which tokens need Level 2 overrides (different primitive name in dark mode) and populate those entries. Leave Level 1 tokens (same primitive name, different value per mode) as commented-out — they resolve automatically via primitive dark values. Without this step, the component will silently render light-mode fallback values in dark mode for any tokens that need Level 2 overrides. *(Added by Spec 080, Lina R2 F36)*
+8. **Dark Mode Token Population** (if component has dark mode differentiation) - Coordinate with Ada to populate the component's semantic color token entries in the dark theme file (`src/tokens/themes/dark/SemanticOverrides.ts`). Identify which tokens need Level 2 overrides (different primitive in dark mode) and populate those entries. Leave Level 1 tokens as commented-out — Level 1 means the token deliberately resolves to the *same* value in both modes (primitives have no mode dimension, so a commented-out entry falls back to the base/light reference). Without this step, the component will silently render light-mode fallback values in dark mode for any tokens that need Level 2 overrides. *(Added by Spec 080, Lina R2 F36)*
 9. **Demo Page** (if web implementation) - Create or update demo in `demos/` (see Demo Maintenance Checklist)
 
 This workflow produces clearer requirements, better documentation, and validation that ensures documentation stays accurate.

package/governance/Component-Development-Standards.md

@@ -36,7 +36,7 @@ This document provides comprehensive guidelines for creating new component famil
 |-----------|----------|---------|
 | **Shared Purpose** | Do components share a common purpose that doesn't fit existing families? | "Progress indication" doesn't fit Form Inputs or Buttons |
 | **Multiple Variants** | Can you identify at least 3 potential semantic variants? | Loading: Spinner, Progress, Skeleton |
-| **Clear Base Behaviors** | Can you define foundational behaviors that ALL variants share? | All loading indicators: `indicates_loading`, `accessible_label` |
+| **Clear Base Behaviors** | Can you define foundational behaviors that ALL variants share? | All loading indicators: `state_loading`, `accessibility_aria_label` |
 | **Cross-Platform Need** | Is this needed across web, iOS, and Android? | Yes - all platforms need loading indicators |
 
 **Do NOT create a new family when**:
@@ -113,7 +113,7 @@ List the foundational behaviors that ALL semantic variants will inherit.
 **Behavior Identification Checklist**:
 - [ ] What interaction patterns are common to all variants?
 - [ ] What accessibility requirements apply to all variants?
-- [ ] What visual states are shared (focus, error, disabled)?
+- [ ] What visual states are shared (focus, error, loading)?
 - [ ] What token dependencies are universal?
 
 **Template**:
@@ -319,29 +319,28 @@ properties:
     type: string
     required: false
     description: Error message to display
-  disabled:
-    type: boolean
-    required: false
-    default: false
-    description: Whether input is disabled
+  # No disabled prop: disabled states are not supported corpus-wide, zero
+  # exceptions (adjudicated 2026-07-15 — .kiro/issues/button-cta-disabled-state-adjudication.md).
+  # Components declare the standardized `excludes: state_disabled` block in
+  # contracts.yaml instead; use state_loading or validate-on-press/blur.
 
 contracts:
-  - name: focusable
+  - name: interaction_focusable
     description: Can receive keyboard focus via Tab key navigation
     platforms: [web, ios, android]
     required: true
     wcag: "2.1.1"
-  - name: float_label_animation
+  - name: content_float_label
     description: Label animates from placeholder to floating position on focus
     platforms: [web, ios, android]
     required: true
     wcag: "2.3.3"
-  - name: validates_on_blur
+  - name: validation_on_blur
     description: Validation triggers when field loses focus
     platforms: [web, ios, android]
     required: true
     wcag: "3.3.1"
-  - name: error_state_display
+  - name: state_error
     description: Displays error message and visual error indication
     platforms: [web, ios, android]
     required: true
@@ -510,7 +509,6 @@ Add the new family to the Component Family Inheritance Structures document.
 Verify all schemas are valid and complete:
 - [ ] All required fields present
 - [ ] Property types are valid
-- [ ] Contracts reference valid WCAG criteria
 - [ ] Token patterns exist in token system
 - [ ] Platforms list is complete
 
@@ -683,7 +681,6 @@ Complete these checks before starting implementation:
 - [ ] **Schema Location Correct**: `src/components/core/[Component-Name]/[Component-Name].schema.yaml`
 - [ ] **Required Fields Present**: name, type, family, behaviors, properties, contracts, tokens, platforms, readiness
 - [ ] **Property Types Valid**: All properties have valid type definitions
-- [ ] **Contracts Reference WCAG**: Accessibility contracts include WCAG criterion references
 - [ ] **Token Patterns Exist**: All referenced tokens exist in the token system
 - [ ] **Platforms List Complete**: All supported platforms listed (web, ios, android)
 
@@ -803,16 +800,20 @@ This section defines the formal review process for ensuring new component famili
 **Automated Validation Checks**:
 ```yaml
 schema_validation:
+  # Per spec 063, contracts live in contracts.yaml — NOT in the schema. These
+  # five fields are what schema validation actually requires (see
+  # src/__tests__/stemma-system/behavioral-contract-validation.test.ts).
   required_fields:
     - name
     - type
     - family
     - behaviors
-    - properties
-    - contracts
-    - tokens
     - platforms
-    - readiness
+
+  # Authored by convention, but NOT presence-checked by schema validation:
+  #   properties, tokens, readiness (and `inherits` on semantic variants)
+  # Contract-level checks below read the component's contracts.yaml, not the
+  # schema; contracts.yaml must exist and declare at least one contract.
   
   type_validation:
     - type must be: primitive | semantic | standalone
@@ -821,7 +822,7 @@ schema_validation:
   
   contract_validation:
     - Each contract must have: description, platforms, validation
-    - WCAG-referenced contracts must have: wcag field
+    - Allowlisted contracts (exact names + accessibility_*/content_*_label prefixes) must carry a wcag value ('N/A' when genuinely not applicable)
   
   token_validation:
     - All token patterns must exist in token system

package/governance/Component-Family-Avatar.md

@@ -80,13 +80,13 @@ Avatar-Base (Primitive) [IMPLEMENTED]
 
 | Contract | Description | WCAG | Platforms |
 |----------|-------------|------|-----------|
-| `shape_differentiation` | Circle for human, hexagon for agent | 1.4.1 | web, ios, android |
-| `displays_image` | Shows user image when available (human only) | 1.1.1 | web, ios, android |
-| `displays_fallback` | Shows icon when image unavailable or agent type | 1.1.1 | web, ios, android |
+| `visual_entity_shape` | Circle for human, hexagon for agent | 1.4.1 | web, ios, android |
+| `content_displays_image` | Shows user image when available (human only) | 1.1.1 | web, ios, android |
+| `content_displays_fallback` | Shows icon when image unavailable or agent type | 1.1.1 | web, ios, android |
 | `error_handling` | Falls back to icon on image load failure | N/A | web, ios, android |
-| `size_variants` | Supports six size variants (xs-xxl) | N/A | web, ios, android |
-| `interactive_feedback` | Shows hover visual feedback when interactive | N/A | web, ios, android |
-| `decorative_mode` | Hides from screen readers when decorative | 1.1.1 | web, ios, android |
+| `visual_size_variants` | Supports six size variants (xs-xxl) | N/A | web, ios, android |
+| `interaction_hover` | Shows hover visual feedback when interactive | N/A | web, ios, android |
+| `accessibility_decorative_mode` | Hides from screen readers when decorative | 1.1.1 | web, ios, android |
 | `wrapper_delegation` | No onClick/onPress - wrapper handles interaction | 2.1.1 | web, ios, android |
 
 ---

package/governance/Component-Family-Badge.md

@@ -77,24 +77,24 @@ Badge (Family)
 
 | Contract | Description | WCAG | Platforms |
 |----------|-------------|------|-----------|
-| displays_label | Renders text label visibly | 1.3.1 | web, ios, android |
-| non_interactive | Does not respond to user interaction | — | web, ios, android |
-| supports_icon | Optionally displays leading icon via Icon-Base | 1.3.1 | web, ios, android |
-| supports_truncation | Truncates with ellipsis when truncate=true; full text accessible | 1.3.1 | web, ios, android |
-| color_contrast | Meets WCAG AA contrast requirements (4.5:1) | 1.4.3 | web, ios, android |
-| text_scaling | Scales proportionally with user font size preferences | 1.4.4 | web, ios, android |
+| content_displays_label | Renders text label visibly | 1.3.1 | web, ios, android |
+| accessibility_non_interactive | Does not respond to user interaction | — | web, ios, android |
+| content_supports_icon | Optionally displays leading icon via Icon-Base | 1.3.1 | web, ios, android |
+| content_truncation | Truncates with ellipsis when truncate=true; full text accessible | 1.3.1 | web, ios, android |
+| accessibility_color_contrast | Meets WCAG AA contrast requirements (4.5:1) | 1.4.3 | web, ios, android |
+| accessibility_text_scaling | Scales proportionally with user font size preferences | 1.4.4 | web, ios, android |
 
 ### Base Contracts (Badge-Count-Base)
 
 | Contract | Description | WCAG | Platforms |
 |----------|-------------|------|-----------|
-| displays_count | Shows numeric value | 1.3.1 | web, ios, android |
-| truncates_at_max | Shows "[max]+" when count exceeds max | 1.3.1 | web, ios, android |
-| circular_single_digit | Renders circular for single-digit counts | — | web, ios, android |
-| pill_multi_digit | Renders pill shape for multi-digit counts | — | web, ios, android |
-| non_interactive | Does not respond to user interaction | — | web, ios, android |
-| color_contrast | Meets WCAG AA contrast requirements (4.5:1) | 1.4.3 | web, ios, android |
-| text_scaling | Scales proportionally with user font size preferences | 1.4.4 | web, ios, android |
+| content_displays_count | Shows numeric value | 1.3.1 | web, ios, android |
+| content_truncates_at_max | Shows "[max]+" when count exceeds max | 1.3.1 | web, ios, android |
+| visual_circular_shape | Renders circular for single-digit counts | — | web, ios, android |
+| visual_pill_shape | Renders pill shape for multi-digit counts | — | web, ios, android |
+| accessibility_non_interactive | Does not respond to user interaction | — | web, ios, android |
+| accessibility_color_contrast | Meets WCAG AA contrast requirements (4.5:1) | 1.4.3 | web, ios, android |
+| accessibility_text_scaling | Scales proportionally with user font size preferences | 1.4.4 | web, ios, android |
 
 ### Extended Contracts (Badge-Count-Notification)
 
@@ -102,13 +102,13 @@ Inherits all contracts from Badge-Count-Base, plus:
 
 | Contract | Description | WCAG | Platforms |
 |----------|-------------|------|-----------|
-| notification_semantics | Conveys notification/alert meaning through color | 1.3.1 | web, ios, android |
-| announces_count_changes | Announces count changes to screen readers when enabled | 4.1.3 | web, ios, android |
-| pluralized_announcements | Uses correct pluralization in announcements | 4.1.3 | web, ios, android |
+| visual_notification_color | Conveys notification/alert meaning through color | 1.3.1 | web, ios, android |
+| accessibility_announces_changes | Announces count changes to screen readers when enabled | 4.1.3 | web, ios, android |
+| accessibility_pluralized_announcements | Uses correct pluralization in announcements | 4.1.3 | web, ios, android |
 
 ### Contract Details
 
-#### displays_label
+#### content_displays_label
 
 **Description**: Renders the provided text label visibly within the badge container.
 
@@ -121,7 +121,7 @@ Inherits all contracts from Badge-Count-Base, plus:
 
 **WCAG Compliance**: 1.3.1 Info and Relationships
 
-#### non_interactive
+#### accessibility_non_interactive
 
 **Description**: Badge components do not respond to user interaction.
 
@@ -132,7 +132,7 @@ Inherits all contracts from Badge-Count-Base, plus:
 - iOS: No onTapGesture, not focusable
 - Android: No clickable modifier, not focusable
 
-#### announces_count_changes
+#### accessibility_announces_changes
 
 **Description**: When count changes and announceChanges is enabled, screen readers are notified.
 

package/governance/Component-Family-Button.md

@@ -101,16 +101,16 @@ All Button-CTA instances implement these 6 foundational contracts:
 
 | Contract | Description | WCAG | Platforms |
 |----------|-------------|------|-----------|
-| `focusable` | Can receive keyboard focus | 2.1.1, 2.4.7 | web, ios, android |
-| `pressable` | Responds to press/click events | 2.1.1 | web, ios, android |
-| `hover_state` | Visual feedback on hover (desktop) | 1.4.13 | web |
-| `pressed_state` | Visual feedback when pressed | 2.4.7 | web, ios, android |
-| `loading_state` | Shows loading indicator during async | 4.1.3 | web, ios, android |
-| `focus_ring` | WCAG 2.4.7 focus visible indicator | 2.4.7 | web, ios, android |
+| `interaction_focusable` | Can receive keyboard focus | 2.1.1, 2.4.7 | web, ios, android |
+| `interaction_pressable` | Responds to press/click events | 2.1.1 | web, ios, android |
+| `interaction_hover` | Visual feedback on hover (desktop) | 1.4.13 | web |
+| `interaction_pressed` | Visual feedback when pressed | 2.4.7 | web, ios, android |
+| `state_loading` | Shows loading indicator during async | 4.1.3 | web, ios, android |
+| `interaction_focus_ring` | WCAG 2.4.7 focus visible indicator | 2.4.7 | web, ios, android |
 
 ### Contract Details
 
-#### focusable
+#### interaction_focusable
 
 **Description**: Component can receive keyboard focus via Tab key navigation.
 
@@ -118,7 +118,7 @@ All Button-CTA instances implement these 6 foundational contracts:
 
 **WCAG Compliance**: 2.1.1 Keyboard, 2.4.7 Focus Visible
 
-#### pressable
+#### interaction_pressable
 
 **Description**: Component responds to click, tap, Enter key, and Space key.
 
@@ -126,7 +126,7 @@ All Button-CTA instances implement these 6 foundational contracts:
 
 **WCAG Compliance**: 2.1.1 Keyboard
 
-#### hover_state
+#### interaction_hover
 
 **Description**: Visual feedback on hover (desktop only).
 
@@ -134,7 +134,7 @@ All Button-CTA instances implement these 6 foundational contracts:
 
 **WCAG Compliance**: 1.4.13 Content on Hover or Focus
 
-#### pressed_state
+#### interaction_pressed
 
 **Description**: Visual feedback when pressed.
 
@@ -142,7 +142,7 @@ All Button-CTA instances implement these 6 foundational contracts:
 
 **WCAG Compliance**: 2.4.7 Focus Visible
 
-#### focus_ring
+#### interaction_focus_ring
 
 **Description**: WCAG 2.4.7 focus visible indicator.
 
@@ -292,14 +292,14 @@ Container component that orchestrates selection behavior across child Button-Ver
 
 | Contract | Description | WCAG |
 |----------|-------------|------|
-| `mode_driven` | Behavior determined by mode prop | - |
-| `controlled_state` | Selection state managed by parent via props | - |
-| `state_coordination` | Derives and propagates visual states to children | - |
+| `state_mode_driven` | Behavior determined by mode prop | - |
+| `state_controlled` | Selection state managed by parent via props | - |
+| `composition_state_coordination` | Derives and propagates visual states to children | - |
 | `animation_coordination` | Coordinates transition timing across children | 2.3.3 |
-| `keyboard_navigation` | Arrow keys, Home, End, Enter, Space support | 2.1.1 |
-| `roving_tabindex` | Single tab stop with arrow key navigation | 2.4.3 |
-| `error_propagation` | Error state propagates to all children | 3.3.1 |
-| `aria_roles` | Appropriate ARIA roles based on mode | 4.1.2 |
+| `interaction_keyboard_navigation` | Arrow keys, Home, End, Enter, Space support | 2.1.1 |
+| `interaction_roving_tabindex` | Single tab stop with arrow key navigation | 2.4.3 |
+| `composition_error_propagation` | Error state propagates to all children | 3.3.1 |
+| `accessibility_aria_roles` | Appropriate ARIA roles based on mode | 4.1.2 |
 
 #### Usage Example
 
@@ -383,14 +383,14 @@ Presentational button component for vertical list selection patterns. Renders vi
 
 | Contract | Description | WCAG |
 |----------|-------------|------|
-| `focusable` | Can receive keyboard focus | 2.1.1, 2.4.7 |
-| `pressable` | Responds to press/click events | 2.1.1 |
-| `hover_state` | Visual feedback on hover | 1.4.13 |
-| `pressed_state` | Visual feedback when pressed | 2.4.7 |
-| `visual_state_driven` | Renders appearance based on visualState prop | - |
-| `checkmark_animation` | Animated selection indicator | 2.3.3 |
-| `error_state_display` | Shows error styling when error=true | 3.3.1 |
-| `focus_ring` | WCAG 2.4.7 focus visible indicator | 2.4.7 |
+| `interaction_focusable` | Can receive keyboard focus | 2.1.1, 2.4.7 |
+| `interaction_pressable` | Responds to press/click events | 2.1.1 |
+| `interaction_hover` | Visual feedback on hover | 1.4.13 |
+| `interaction_pressed` | Visual feedback when pressed | 2.4.7 |
+| `state_visual_driven` | Renders appearance based on visualState prop | - |
+| `animation_checkmark` | Animated selection indicator | 2.3.3 |
+| `state_error` | Shows error styling when error=true | 3.3.1 |
+| `interaction_focus_ring` | WCAG 2.4.7 focus visible indicator | 2.4.7 |
 
 #### Usage Example
 

package/governance/Component-Family-Chip.md

@@ -83,13 +83,13 @@ Chip (Family)
 
 | Contract | Description | WCAG | Platforms |
 |----------|-------------|------|-----------|
-| renders_pill_container | Renders pill-shaped container with label text | — | web, ios, android |
-| renders_icon | Optionally displays leading icon via Icon-Base at icon.size075 | — | web, ios, android |
-| press_interaction | Responds to press/click/tap events, calls onPress callback | 2.1.1 | web, ios, android |
+| visual_pill_container | Renders pill-shaped container with label text | — | web, ios, android |
+| visual_renders_icon | Optionally displays leading icon via Icon-Base at icon.size075 | — | web, ios, android |
+| interaction_pressable | Responds to press/click/tap events, calls onPress callback | 2.1.1 | web, ios, android |
 | state_styling | Visual feedback for default, hover, pressed states | 1.4.13 | web, ios, android |
-| keyboard_focusable | Can receive keyboard focus via Tab key | 2.1.1, 2.4.7 | web, ios, android |
-| keyboard_activation | Activates on Space/Enter key press | 2.1.1 | web |
-| expanded_tap_area | 48px tap area exceeds WCAG 44px minimum | 2.5.5 | web, ios, android |
+| interaction_focusable | Can receive keyboard focus via Tab key | 2.1.1, 2.4.7 | web, ios, android |
+| interaction_keyboard_activation | Activates on Space/Enter key press | 2.1.1 | web |
+| interaction_expanded_tap_area | 48px tap area exceeds WCAG 44px minimum | 2.5.5 | web, ios, android |
 | accessibility_role | Announces as button to assistive technology | 4.1.2 | web, ios, android |
 
 ### Extended Contracts (Chip-Filter)
@@ -98,10 +98,10 @@ Inherits all contracts from Chip-Base, plus:
 
 | Contract | Description | WCAG | Platforms |
 |----------|-------------|------|-----------|
-| toggle_selection | Toggles selected state on press, calls onSelectionChange | 4.1.2 | web, ios, android |
-| selected_styling | Visual feedback for selected state using select feedback colors | 1.4.1 | web, ios, android |
-| checkmark_icon | Displays checkmark icon when selected (replaces leading icon) | — | web, ios, android |
-| aria_pressed | Announces selection state via aria-pressed attribute | 4.1.2 | web |
+| interaction_toggle_selection | Toggles selected state on press, calls onSelectionChange | 4.1.2 | web, ios, android |
+| state_selected_styling | Visual feedback for selected state using select feedback colors | 1.4.1 | web, ios, android |
+| visual_checkmark_icon | Displays checkmark icon when selected (replaces leading icon) | — | web, ios, android |
+| accessibility_aria_pressed | Announces selection state via aria-pressed attribute | 4.1.2 | web |
 
 ### Extended Contracts (Chip-Input)
 
@@ -109,10 +109,10 @@ Inherits most contracts from Chip-Base, plus:
 
 | Contract | Description | WCAG | Platforms |
 |----------|-------------|------|-----------|
-| dismiss_on_press | Dismisses chip on press anywhere, calls onDismiss | 2.1.1 | web, ios, android |
-| trailing_x_icon | Always displays X icon as trailing element | — | web, ios, android |
-| dual_icons | Supports both leading icon AND trailing X icon | — | web, ios, android |
-| x_icon_accessible_label | X icon has accessible label "Remove [label]" | 4.1.2 | web, ios, android |
+| interaction_dismiss | Dismisses chip on press anywhere, calls onDismiss | 2.1.1 | web, ios, android |
+| content_trailing_dismiss_icon | Always displays X icon as trailing element | — | web, ios, android |
+| content_dual_icons | Supports both leading icon AND trailing X icon | — | web, ios, android |
+| accessibility_dismiss_label | X icon has accessible label "Remove [label]" | 4.1.2 | web, ios, android |
 
 ---
 

package/governance/Component-Family-Container.md

@@ -97,17 +97,17 @@ All components in the Containers family inherit these 7 foundational contracts f
 
 | Contract | Description | WCAG | Platforms |
 |----------|-------------|------|-----------|
-| `contains_children` | Can contain child components | 1.3.1 | web, ios, android |
-| `applies_padding` | Applies consistent internal padding | 1.4.12 | web, ios, android |
-| `applies_background` | Applies background color styling | 1.4.3 | web, ios, android |
-| `applies_shadow` | Applies shadow/elevation styling | 1.4.11 | web, ios, android |
-| `applies_border` | Applies border styling | 1.4.11 | web, ios, android |
-| `applies_radius` | Applies border radius styling | N/A | web, ios, android |
-| `hover_state` | Visual feedback on hover (pointer devices) | 1.4.13 | web, ios, android |
+| `layout_contains_children` | Can contain child components | 1.3.1 | web, ios, android |
+| `layout_padding` | Applies consistent internal padding | 1.4.12 | web, ios, android |
+| `visual_background` | Applies background color styling | 1.4.3 | web, ios, android |
+| `visual_shadow` | Applies shadow/elevation styling | 1.4.11 | web, ios, android |
+| `visual_border` | Applies border styling | 1.4.11 | web, ios, android |
+| `visual_radius` | Applies border radius styling | N/A | web, ios, android |
+| `interaction_hover` | Visual feedback on hover (pointer devices) | 1.4.13 | web, ios, android |
 
 ### Contract Details
 
-#### contains_children
+#### layout_contains_children
 
 **Description**: Container-Base can contain any child components or content.
 
@@ -115,7 +115,7 @@ All components in the Containers family inherit these 7 foundational contracts f
 
 **WCAG Compliance**: 1.3.1 Info and Relationships
 
-#### applies_padding
+#### layout_padding
 
 **Description**: Applies consistent internal padding using space.inset tokens.
 
@@ -123,7 +123,7 @@ All components in the Containers family inherit these 7 foundational contracts f
 
 **WCAG Compliance**: 1.4.12 Text Spacing
 
-#### applies_background
+#### visual_background
 
 **Description**: Applies background color styling.
 
@@ -131,7 +131,7 @@ All components in the Containers family inherit these 7 foundational contracts f
 
 **WCAG Compliance**: 1.4.3 Contrast (Minimum)
 
-#### applies_shadow
+#### visual_shadow
 
 **Description**: Applies shadow/elevation styling.
 
@@ -139,7 +139,7 @@ All components in the Containers family inherit these 7 foundational contracts f
 
 **WCAG Compliance**: 1.4.11 Non-text Contrast
 
-#### hover_state
+#### interaction_hover
 
 **Description**: Visual feedback on hover (pointer devices only).