@3fn/core 14.0.0 → 15.0.0

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).
 

package/governance/Component-Family-Form-Inputs.md

@@ -106,20 +106,20 @@ All text input components in the Form Inputs family inherit these 8 foundational
 
 | Contract | Description | WCAG | Platforms |
 |----------|-------------|------|-----------|
-| `focusable` | Can receive keyboard focus | 2.1.1 | web, ios, android |
-| `float_label_animation` | Label animates on focus | 2.3.3 | web, ios, android |
-| `validates_on_blur` | Validation triggers on blur | 3.3.1 | web, ios, android |
-| `error_state_display` | Shows error message and styling | 3.3.1, 1.4.1 | web, ios, android |
-| `success_state_display` | Shows success styling | 1.4.1 | web, ios, android |
-| `trailing_icon_display` | Shows contextual trailing icons | 1.4.1 | web, ios, android |
-| `focus_ring` | WCAG 2.4.7 focus visible indicator | 2.4.7 | web, ios, android |
-| `reduced_motion_support` | Respects prefers-reduced-motion | 2.3.3 | web, ios, android |
+| `interaction_focusable` | Can receive keyboard focus | 2.1.1 | web, ios, android |
+| `content_float_label` | Label animates on focus | 2.3.3 | web, ios, android |
+| `validation_on_blur` | Validation triggers on blur | 3.3.1 | web, ios, android |
+| `state_error` | Shows error message and styling | 3.3.1, 1.4.1 | web, ios, android |
+| `state_success` | Shows success styling | 1.4.1 | web, ios, android |
+| `content_trailing_icon` | Shows contextual trailing icons | 1.4.1 | web, ios, android |
+| `interaction_focus_ring` | WCAG 2.4.7 focus visible indicator | 2.4.7 | web, ios, android |
+| `accessibility_reduced_motion` | Respects prefers-reduced-motion | 2.3.3 | web, ios, android |
 
-**Excluded**: `disabled_state` — DesignerPunk does not support disabled states for usability and accessibility reasons. If an input is unavailable, it should not be rendered (adjudicated 2026-07-15; see `.kiro/issues/button-cta-disabled-state-adjudication.md`).
+**Excluded**: `state_disabled` — DesignerPunk does not support disabled states for usability and accessibility reasons. If an input is unavailable, it should not be rendered (adjudicated 2026-07-15; see `.kiro/issues/button-cta-disabled-state-adjudication.md`).
 
 ### Contract Details
 
-#### focusable
+#### interaction_focusable
 
 **Description**: Component can receive keyboard focus via Tab key navigation.
 
@@ -127,7 +127,7 @@ All text input components in the Form Inputs family inherit these 8 foundational
 
 **WCAG Compliance**: 2.1.1 Keyboard
 
-#### float_label_animation
+#### content_float_label
 
 **Description**: Label smoothly transitions from placeholder position inside input to floated position above input when focused or filled.
 
@@ -135,7 +135,7 @@ All text input components in the Form Inputs family inherit these 8 foundational
 
 **WCAG Compliance**: 2.3.3 Animation from Interactions
 
-#### error_state_display
+#### state_error
 
 **Description**: When in error state, component displays red border, red label text, error icon, and error message.
 
@@ -143,7 +143,7 @@ All text input components in the Form Inputs family inherit these 8 foundational
 
 **WCAG Compliance**: 3.3.1 Error Identification, 1.4.1 Use of Color
 
-#### focus_ring
+#### interaction_focus_ring
 
 **Description**: When focused via keyboard, component displays a visible focus indicator.
 
@@ -157,24 +157,24 @@ All text input components in the Form Inputs family inherit these 8 foundational
 
 | Contract | Description | WCAG |
 |----------|-------------|------|
-| `validates_email_format` | Validates email against RFC 5322 pattern | 3.3.1 |
-| `provides_email_autocomplete` | Enables browser/platform email autofill | 1.3.5 |
+| `validation_email_format` | Validates email against RFC 5322 pattern | 3.3.1 |
+| `interaction_email_autocomplete` | Enables browser/platform email autofill | 1.3.5 |
 
 #### Input-Text-Password Extended Contracts
 
 | Contract | Description | WCAG |
 |----------|-------------|------|
-| `provides_secure_input` | Masks password input by default | 3.3.2 |
-| `supports_password_toggle` | Provides show/hide password functionality | 2.1.1, 4.1.2 |
-| `provides_password_autocomplete` | Enables browser/platform password autofill | 1.3.5 |
+| `interaction_secure_input` | Masks password input by default | 3.3.2 |
+| `interaction_password_toggle` | Provides show/hide password functionality | 2.1.1, 4.1.2 |
+| `interaction_password_autocomplete` | Enables browser/platform password autofill | 1.3.5 |
 
 #### Input-Text-PhoneNumber Extended Contracts
 
 | Contract | Description | WCAG |
 |----------|-------------|------|
-| `validates_phone_format` | Validates phone number against country-specific patterns | 3.3.1 |
-| `provides_phone_formatting` | Formats phone numbers as user types | 3.3.2 |
-| `supports_international_formats` | Handles multiple country phone number formats | 3.3.2 |
+| `validation_phone_format` | Validates phone number against country-specific patterns | 3.3.1 |
+| `content_phone_formatting` | Formats phone numbers as user types | 3.3.2 |
+| `content_international_formats` | Handles multiple country phone number formats | 3.3.2 |
 
 ### Checkbox Base Contracts (Inherited by Checkbox Components)
 
@@ -182,19 +182,19 @@ All checkbox components in the Form Inputs family inherit these 9 foundational c
 
 | Contract | Description | WCAG | Platforms |
 |----------|-------------|------|-----------|
-| `focusable` | Can receive keyboard focus | 2.1.1 | web, ios, android |
-| `pressable` | Responds to click/tap on entire label area | 2.1.1 | web, ios, android |
-| `hover_state` | Visual feedback on hover (web) | 1.4.13 | web |
-| `pressed_state` | Visual feedback when pressed | 2.4.7 | web, ios, android |
-| `checked_state` | Shows checkmark icon when checked | 1.4.1 | web, ios, android |
-| `indeterminate_state` | Shows minus icon for partial selection | 1.4.1 | web, ios, android |
-| `error_state_display` | Shows error border and message | 3.3.1 | web, ios, android |
-| `focus_ring` | WCAG 2.4.7 focus visible indicator | 2.4.7 | web, ios, android |
-| `form_integration` | Native form submission and reset | 4.1.2 | web, ios, android |
+| `interaction_focusable` | Can receive keyboard focus | 2.1.1 | web, ios, android |
+| `interaction_pressable` | Responds to click/tap on entire label area | 2.1.1 | web, ios, android |
+| `interaction_hover` | Visual feedback on hover (web) | 1.4.13 | web |
+| `interaction_pressed` | Visual feedback when pressed | 2.4.7 | web, ios, android |
+| `state_checked` | Shows checkmark icon when checked | 1.4.1 | web, ios, android |
+| `state_indeterminate` | Shows minus icon for partial selection | 1.4.1 | web, ios, android |
+| `state_error` | Shows error border and message | 3.3.1 | web, ios, android |
+| `interaction_focus_ring` | WCAG 2.4.7 focus visible indicator | 2.4.7 | web, ios, android |
+| `validation_form_integration` | Native form submission and reset | 4.1.2 | web, ios, android |
 
 ### Checkbox Contract Details
 
-#### checked_state
+#### state_checked
 
 **Description**: When checked, component displays filled background with checkmark icon via Icon-Base.
 
@@ -202,7 +202,7 @@ All checkbox components in the Form Inputs family inherit these 9 foundational c
 
 **WCAG Compliance**: 1.4.1 Use of Color (icon provides non-color indication)
 
-#### indeterminate_state
+#### state_indeterminate
 
 **Description**: When indeterminate, component displays filled background with horizontal minus icon via Icon-Base.
 
@@ -210,7 +210,7 @@ All checkbox components in the Form Inputs family inherit these 9 foundational c
 
 **WCAG Compliance**: 1.4.1 Use of Color (icon provides non-color indication)
 
-#### form_integration
+#### validation_form_integration
 
 **Description**: Checkbox integrates with native form submission and reset.
 
@@ -222,8 +222,8 @@ All checkbox components in the Form Inputs family inherit these 9 foundational c
 
 | Contract | Description | WCAG |
 |----------|-------------|------|
-| `explicit_consent` | Prevents pre-checking with console warning | N/A |
-| `audit_trail` | Provides ISO 8601 timestamp and metadata | N/A |
+| `validation_explicit_consent` | Prevents pre-checking with console warning | N/A |
+| `validation_audit_trail` | Provides ISO 8601 timestamp and metadata | N/A |
 | `required_indicator` | Shows "Required" indicator by default | 3.3.2 |
 
 ### Radio Base Contracts (Inherited by Radio Components)
@@ -232,18 +232,18 @@ All radio components in the Form Inputs family inherit these 8 foundational cont
 
 | Contract | Description | WCAG | Platforms |
 |----------|-------------|------|-----------|
-| `focusable` | Can receive keyboard focus | 2.1.1 | web, ios, android |
-| `pressable` | Responds to click/tap on entire label area | 2.1.1 | web, ios, android |
-| `hover_state` | Visual feedback on hover (web) | 1.4.13 | web |
-| `pressed_state` | Visual feedback when pressed | 2.4.7 | web, ios, android |
-| `selected_state` | Shows filled dot when selected | 1.4.1 | web, ios, android |
-| `error_state` | Shows error border and message | 3.3.1 | web, ios, android |
-| `focus_ring` | WCAG 2.4.7 focus visible indicator | 2.4.7 | web, ios, android |
-| `form_integration` | Native form submission | 4.1.2 | web, ios, android |
+| `interaction_focusable` | Can receive keyboard focus | 2.1.1 | web, ios, android |
+| `interaction_pressable` | Responds to click/tap on entire label area | 2.1.1 | web, ios, android |
+| `interaction_hover` | Visual feedback on hover (web) | 1.4.13 | web |
+| `interaction_pressed` | Visual feedback when pressed | 2.4.7 | web, ios, android |
+| `state_selected` | Shows filled dot when selected | 1.4.1 | web, ios, android |
+| `state_error` | Shows error border and message | 3.3.1 | web, ios, android |
+| `interaction_focus_ring` | WCAG 2.4.7 focus visible indicator | 2.4.7 | web, ios, android |
+| `validation_form_integration` | Native form submission | 4.1.2 | web, ios, android |
 
 ### Radio Contract Details
 
-#### selected_state
+#### state_selected
 
 **Description**: When selected, component displays a filled circular dot centered within the outer circle.
 
@@ -263,21 +263,21 @@ All radio components in the Form Inputs family inherit these 8 foundational cont
 
 | Contract | Description | WCAG | Platforms |
 |----------|-------------|------|-----------|
-| `mutual_exclusivity` | Only one radio selected at a time | N/A | web, ios, android |
-| `keyboard_navigation` | Arrow keys navigate within group | 2.1.1 | web, ios, android |
-| `group_validation` | Required validation at group level | 3.3.1 | web, ios, android |
-| `error_announcement` | Error message announced to screen readers | 4.1.3 | web, ios, android |
-| `radiogroup_role` | Proper ARIA role for group | 4.1.2 | web, ios, android |
+| `composition_mutual_exclusivity` | Only one radio selected at a time | N/A | web, ios, android |
+| `interaction_keyboard_navigation` | Arrow keys navigate within group | 2.1.1 | web, ios, android |
+| `validation_group_required` | Required validation at group level | 3.3.1 | web, ios, android |
+| `accessibility_error_announcement` | Error message announced to screen readers | 4.1.3 | web, ios, android |
+| `accessibility_radiogroup_role` | Proper ARIA role for group | 4.1.2 | web, ios, android |
 
 ### Radio Set Contract Details
 
-#### mutual_exclusivity
+#### composition_mutual_exclusivity
 
 **Description**: Only one radio within the group can be selected at any time.
 
 **Behavior**: When a user selects a radio, the previously selected radio becomes unselected. Clicking an already-selected radio does NOT deselect it (radio convention). The Set coordinates this via event listening (web), environment values (iOS), or CompositionLocal (Android).
 
-#### keyboard_navigation
+#### interaction_keyboard_navigation
 
 **Description**: Arrow keys navigate between radios within the group following WAI-ARIA radio group pattern.
 
@@ -372,8 +372,8 @@ InputTextBase(
 
 | Contract | Description | Platforms |
 |----------|-------------|-----------|
-| `validates_email_format` | Validates email against RFC 5322 pattern on blur | web, ios, android |
-| `provides_email_autocomplete` | Enables browser/platform email autofill | web, ios, android |
+| `validation_email_format` | Validates email against RFC 5322 pattern on blur | web, ios, android |
+| `interaction_email_autocomplete` | Enables browser/platform email autofill | web, ios, android |
 
 #### Usage Example
 
@@ -426,9 +426,9 @@ InputTextEmail(
 
 | Contract | Description | Platforms |
 |----------|-------------|-----------|
-| `provides_secure_input` | Masks password input by default | web, ios, android |
-| `supports_password_toggle` | Provides show/hide password functionality | web, ios, android |
-| `provides_password_autocomplete` | Enables browser/platform password autofill | web, ios, android |
+| `interaction_secure_input` | Masks password input by default | web, ios, android |
+| `interaction_password_toggle` | Provides show/hide password functionality | web, ios, android |
+| `interaction_password_autocomplete` | Enables browser/platform password autofill | web, ios, android |
 
 #### Usage Example
 
@@ -480,9 +480,9 @@ InputTextPassword(
 
 | Contract | Description | Platforms |
 |----------|-------------|-----------|
-| `validates_phone_format` | Validates phone number against country-specific patterns | web, ios, android |
-| `provides_phone_formatting` | Formats phone numbers as user types | web, ios, android |
-| `supports_international_formats` | Handles multiple country phone number formats | web, ios, android |
+| `validation_phone_format` | Validates phone number against country-specific patterns | web, ios, android |
+| `content_phone_formatting` | Formats phone numbers as user types | web, ios, android |
+| `content_international_formats` | Handles multiple country phone number formats | web, ios, android |
 
 #### Supported Countries
 
@@ -666,8 +666,8 @@ interface ConsentChangeData {
 
 | Contract | Description | Platforms |
 |----------|-------------|-----------|
-| `explicit_consent` | Prevents pre-checking with console warning | web, ios, android |
-| `audit_trail` | Provides ISO 8601 timestamp and metadata | web, ios, android |
+| `validation_explicit_consent` | Prevents pre-checking with console warning | web, ios, android |
+| `validation_audit_trail` | Provides ISO 8601 timestamp and metadata | web, ios, android |
 | `required_indicator` | Shows "Required" indicator by default | web, ios, android |
 
 #### Usage Example

package/governance/Component-Family-Icon.md

@@ -84,15 +84,15 @@ All components in the Icons family inherit these 5 foundational contracts from I
 
 | Contract | Description | WCAG | Platforms |
 |----------|-------------|------|-----------|
-| `renders_svg` | Renders inline SVG with correct viewBox and stroke | N/A | web, ios, android |
-| `color_inheritance` | Inherits color from parent via currentColor | 1.4.1 | web, ios, android |
-| `size_variants` | Supports 11 size variants from typography scale | N/A | web, ios, android |
-| `optical_balance` | Optional 8% lighter blend for icon-text pairing | 1.4.3 | web, ios, android |
+| `visual_renders_svg` | Renders inline SVG with correct viewBox and stroke | N/A | web, ios, android |
+| `visual_color_inheritance` | Inherits color from parent via currentColor | 1.4.1 | web, ios, android |
+| `visual_size_variants` | Supports 11 size variants from typography scale | N/A | web, ios, android |
+| `visual_optical_balance` | Optional 8% lighter blend for icon-text pairing | 1.4.3 | web, ios, android |
 | `accessibility_hidden` | Decorative icons hidden from assistive technology | 1.1.1 | web, ios, android |
 
 ### Contract Details
 
-#### renders_svg
+#### visual_renders_svg
 
 **Description**: Renders inline SVG with correct viewBox and stroke attributes.
 
@@ -100,7 +100,7 @@ All components in the Icons family inherit these 5 foundational contracts from I
 
 **WCAG Compliance**: N/A
 
-#### color_inheritance
+#### visual_color_inheritance
 
 **Description**: Inherits color from parent via currentColor.
 
@@ -108,7 +108,7 @@ All components in the Icons family inherit these 5 foundational contracts from I
 
 **WCAG Compliance**: 1.4.1 Use of Color
 
-#### size_variants
+#### visual_size_variants
 
 **Description**: Supports 11 size variants calculated from typography scale.
 
@@ -125,7 +125,7 @@ All components in the Icons family inherit these 5 foundational contracts from I
 
 **WCAG Compliance**: N/A
 
-#### optical_balance
+#### visual_optical_balance
 
 **Description**: Optional 8% lighter blend for icon-text pairing.
 

package/governance/Component-Family-Navigation.md

@@ -21,11 +21,11 @@ description: Navigation component family — wayfinding and view-switching compo
 
 **Family**: Navigation
 **Shared Need**: Wayfinding and view switching
-**Readiness**: 🟡 Beta (2 components implemented, family hierarchy evolving)
+**Readiness**: 🟡 Beta (5 components implemented, family hierarchy evolving)
 
 ### Purpose
 
-The Navigation family provides components for user wayfinding and switching between views. Implemented components include a segmented control for mutually exclusive content views and a primary bottom tab bar for top-level app destinations.
+The Navigation family provides components for user wayfinding and switching between views. Five components are implemented: a segmented control for mutually exclusive content views, a primary bottom tab bar for top-level app destinations, and three top-of-screen navigation headers (Nav-Header-Base, Nav-Header-Page, Nav-Header-App).
 
 ### Key Characteristics
 
@@ -143,7 +143,7 @@ Nav-Header-Base (Primitive) [PLANNED]
 | `accessibility_touch_target` | accessibility | 2.5.5 | web, ios, android |
 | `validation_selection_constraints` | validation | — | web, ios, android |
 
-**Exclusions**: `state_disabled`, `interaction_hoverable` — No disabled or hover states on tab bar.
+**Exclusions**: `state_disabled`, `interaction_hover` — No disabled or hover states on tab bar.
 
 ---
 

package/governance/Component-Inheritance-Structures.md

@@ -76,22 +76,23 @@ Input-Text-Base (Primitive) │ ├── Input-Text-Email (Semantic) │ └─
 
 ### Behavioral Contracts
 
-**Base Contracts (8 total)**:
-- `focusable` - Keyboard focus support (WCAG 2.1.1)
-- `float_label_animation` - Label animates on focus (WCAG 2.3.3)
-- `validates_on_blur` - Validation triggers on blur (WCAG 3.3.1)
-- `error_state_display` - Error message and styling (WCAG 3.3.1, 1.4.1)
-- `success_state_display` - Success styling (WCAG 1.4.1)
-- `trailing_icon_display` - Contextual trailing icons
-- `focus_ring` - WCAG 2.4.7 focus visible indicator
-- `reduced_motion_support` - Respects prefers-reduced-motion
-
-**Excluded**: `disabled_state` — DesignerPunk does not support disabled states for usability and accessibility reasons (adjudicated 2026-07-15; see `.kiro/issues/button-cta-disabled-state-adjudication.md`).
+**Base Contracts (9 total)**:
+- `interaction_focusable` - Keyboard focus support (WCAG 2.1.1)
+- `content_float_label` - Label animates on focus (WCAG 2.3.3)
+- `validation_on_blur` - Validation triggers on blur (WCAG 3.3.1)
+- `state_error` - Error message and styling (WCAG 3.3.1)
+- `state_readonly` - Non-editable value that stays perceivable, selectable, and copyable — never disabled semantics (WCAG 4.1.2)
+- `state_success` - Success styling (WCAG 1.4.1)
+- `content_trailing_icon` - Contextual trailing icons (WCAG 1.4.1)
+- `interaction_focus_ring` - WCAG 2.4.7 focus visible indicator
+- `accessibility_reduced_motion` - Respects prefers-reduced-motion (WCAG 2.3.3)
+
+**Excluded**: `state_disabled` — DesignerPunk does not support disabled states for usability and accessibility reasons (adjudicated 2026-07-15; see `.kiro/issues/button-cta-disabled-state-adjudication.md`).
 
 **Extended Contracts by Variant**:
-- **Email**: `validates_email_format`, `provides_email_autocomplete`
-- **Password**: `provides_secure_input`, `supports_password_toggle`, `provides_password_autocomplete`
-- **PhoneNumber**: `validates_phone_format`, `provides_phone_formatting`, `supports_international_formats`
+- **Email**: `validation_email_format`, `interaction_email_autocomplete`
+- **Password**: `interaction_secure_input`, `interaction_password_toggle`, `interaction_password_autocomplete` (also excludes `state_readonly`)
+- **PhoneNumber**: `validation_phone_format`, `content_phone_formatting`, `content_international_formats`
 
 ### Token Dependencies
 
@@ -144,14 +145,14 @@ Button-CTA uses the `[Family]-[Type]` pattern (not `[Family]-[Type]-Base`) becau
 ### Behavioral Contracts
 
 **Contracts (6 total)**:
-- `clickable` - Responds to click/tap interactions (WCAG 2.1.1)
-- `focusable` - Keyboard focus support (WCAG 2.1.1)
-- `loading_state` - Shows loading indicator during async operations
+- `interaction_pressable` - Responds to click/tap interactions (WCAG 2.1.1)
+- `interaction_focusable` - Keyboard focus support (WCAG 2.1.1)
+- `state_loading` - Shows loading indicator during async operations
 - `icon_support` - Supports leading/trailing icons
-- `focus_ring` - WCAG 2.4.7 focus visible indicator
+- `interaction_focus_ring` - WCAG 2.4.7 focus visible indicator
 - `reduced_motion_support` - Respects prefers-reduced-motion
 
-**Excluded**: `disabled_state` — DesignerPunk does not support disabled states for usability and accessibility reasons (adjudicated 2026-07-15; see `.kiro/issues/button-cta-disabled-state-adjudication.md`).
+**Excluded**: `state_disabled` — DesignerPunk does not support disabled states for usability and accessibility reasons (adjudicated 2026-07-15; see `.kiro/issues/button-cta-disabled-state-adjudication.md`).
 
 ### Token Dependencies
 
@@ -200,12 +201,12 @@ Container-Base uses the `[Family]-Base` pattern because:
 ### Behavioral Contracts
 
 **Contracts (7 total)**:
-- `contains_children` - Can contain child components
-- `applies_padding` - Applies consistent internal padding
-- `applies_background` - Supports background color/image
-- `applies_border` - Supports border styling
-- `applies_shadow` - Supports elevation shadow
-- `applies_radius` - Supports border radius
+- `layout_contains_children` - Can contain child components
+- `layout_padding` - Applies consistent internal padding
+- `visual_background` - Supports background color/image
+- `visual_border` - Supports border styling
+- `visual_shadow` - Supports elevation shadow
+- `visual_radius` - Supports border radius
 - `responsive_layout` - Adapts to container width
 
 ### Token Dependencies
@@ -253,9 +254,9 @@ Icon-Base uses the `[Family]-Base` pattern because:
 ### Behavioral Contracts
 
 **Contracts (5 total)**:
-- `renders_svg` - Renders SVG icon content
-- `scales_with_size` - Scales proportionally with size prop
-- `inherits_color` - Inherits color from parent or uses explicit color
+- `visual_renders_svg` - Renders SVG icon content
+- `visual_size_variants` - Scales proportionally with size prop
+- `visual_color_inheritance` - Inherits color from parent or uses explicit color
 - `accessible_label` - Provides accessible label for screen readers
 - `decorative_mode` - Can be marked as decorative (aria-hidden)