@3fn/core 13.0.0 → 14.1.0

package/governance/Component-Quick-Reference.md

@@ -69,7 +69,7 @@ Type primitives are specialized components within a family that provide opiniona
 
 For detailed Container-Card-Base documentation including props mapping, interactive behavior, and usage examples:
 ```
-get_section({ path: ".kiro/steering/Component-Family-Container.md", heading: "Container-Card-Base" })
+get_section({ path: "component-family-container", heading: "Container-Card-Base" })
 ```
 
 ## Naming Convention
@@ -156,22 +156,22 @@ Returns metadata and outline (~200 tokens) to understand document structure befo
 
 ```
 // Understand Form Inputs family structure
-get_document_summary({ path: ".kiro/steering/Component-Family-Form-Inputs.md" })
+get_document_summary({ path: "component-family-form-inputs" })
 
 // Understand Button family structure
-get_document_summary({ path: ".kiro/steering/Component-Family-Button.md" })
+get_document_summary({ path: "component-family-button" })
 
 // Understand Container family structure
-get_document_summary({ path: ".kiro/steering/Component-Family-Container.md" })
+get_document_summary({ path: "component-family-container" })
 
 // Understand Icon family structure
-get_document_summary({ path: ".kiro/steering/Component-Family-Icon.md" })
+get_document_summary({ path: "component-family-icon" })
 
 // Understand Chip family structure
-get_document_summary({ path: ".kiro/steering/Component-Family-Chip.md" })
+get_document_summary({ path: "component-family-chip" })
 
 // Get Container-Card-Base type primitive details
-get_section({ path: ".kiro/steering/Component-Family-Container.md", heading: "Container-Card-Base" })
+get_section({ path: "component-family-container", heading: "Container-Card-Base" })
 ```
 
 **Returns**: Document metadata (purpose, layer, relevant tasks) plus section outline with headings.
@@ -182,37 +182,37 @@ Returns targeted content (~500-2,000 tokens) for specific information needs:
 
 ```
 // Get component behavioral contracts
-get_section({ path: ".kiro/steering/Component-Family-Form-Inputs.md", heading: "Behavioral Contracts" })
+get_section({ path: "component-family-form-inputs", heading: "Behavioral Contracts" })
 
 // Get contract system conventions (taxonomy, naming, format)
-get_section({ path: ".kiro/steering/Contract-System-Reference.md", heading: "Taxonomy" })
-get_section({ path: ".kiro/steering/Contract-System-Reference.md", heading: "Naming Convention" })
-get_section({ path: ".kiro/steering/Contract-System-Reference.md", heading: "Canonical Format" })
+get_section({ path: "contract-system-reference", heading: "Taxonomy" })
+get_section({ path: "contract-system-reference", heading: "Naming Convention" })
+get_section({ path: "contract-system-reference", heading: "Canonical Format" })
 
 // Get inheritance structure
-get_section({ path: ".kiro/steering/Component-Family-Button.md", heading: "Inheritance Structure" })
+get_section({ path: "component-family-button", heading: "Inheritance Structure" })
 
 // Get token dependencies
-get_section({ path: ".kiro/steering/Component-Family-Container.md", heading: "Token Dependencies" })
+get_section({ path: "component-family-container", heading: "Token Dependencies" })
 
 // Get usage guidelines
-get_section({ path: ".kiro/steering/Component-Family-Icon.md", heading: "Usage Guidelines" })
+get_section({ path: "component-family-icon", heading: "Usage Guidelines" })
 
 // Get Chip family behavioral contracts
-get_section({ path: ".kiro/steering/Component-Family-Chip.md", heading: "Behavioral Contracts" })
+get_section({ path: "component-family-chip", heading: "Behavioral Contracts" })
 
 // Get cross-platform notes
-get_section({ path: ".kiro/steering/Component-Family-Form-Inputs.md", heading: "Cross-Platform Notes" })
+get_section({ path: "component-family-form-inputs", heading: "Cross-Platform Notes" })
 
 // Get radio component details
-get_section({ path: ".kiro/steering/Component-Family-Form-Inputs.md", heading: "Input-Radio-Base" })
-get_section({ path: ".kiro/steering/Component-Family-Form-Inputs.md", heading: "Input-Radio-Set" })
+get_section({ path: "component-family-form-inputs", heading: "Input-Radio-Base" })
+get_section({ path: "component-family-form-inputs", heading: "Input-Radio-Set" })
 
 // Get component schema definitions
-get_section({ path: ".kiro/steering/Component-Family-Button.md", heading: "Component Schemas" })
+get_section({ path: "component-family-button", heading: "Component Schemas" })
 
 // Get placeholder family planned characteristics
-get_section({ path: ".kiro/steering/Component-Family-Modal.md", heading: "Planned Characteristics" })
+get_section({ path: "component-family-modal", heading: "Planned Characteristics" })
 ```
 
 **Returns**: Section content with parent heading context for document location.
@@ -223,10 +223,10 @@ Returns complete content (~2,000-10,000 tokens) when comprehensive reference is
 
 ```
 // Full Form Inputs family reference
-get_document_full({ path: ".kiro/steering/Component-Family-Form-Inputs.md" })
+get_document_full({ path: "component-family-form-inputs" })
 
 // Full Button family reference
-get_document_full({ path: ".kiro/steering/Component-Family-Button.md" })
+get_document_full({ path: "component-family-button" })
 ```
 
 **Use sparingly**: Only when you need complete component family documentation.
@@ -241,10 +241,10 @@ find_docs({ concept: "form inputs" })   // discover by concept/keyword
 find_docs({ list: true })               // full catalog, paginated
 
 // List cross-references in a document
-list_cross_references({ path: ".kiro/steering/Component-Family-Form-Inputs.md" })
+list_cross_references({ path: "component-family-form-inputs" })
 
 // Validate document metadata schema
-validate_metadata({ path: ".kiro/steering/Component-Family-Button.md" })
+validate_metadata({ path: "component-family-button" })
 
 // Check documentation index health
 get_index_health()
@@ -270,30 +270,30 @@ rebuild_index()
 **Example: Building a Login Form:**
 ```
 // Step 1: Get Form Inputs overview
-get_document_summary({ path: ".kiro/steering/Component-Family-Form-Inputs.md" })
+get_document_summary({ path: "component-family-form-inputs" })
 
 // Step 2: Get specific component contracts
-get_section({ path: ".kiro/steering/Component-Family-Form-Inputs.md", heading: "Input-Text-Email" })
-get_section({ path: ".kiro/steering/Component-Family-Form-Inputs.md", heading: "Input-Text-Password" })
+get_section({ path: "component-family-form-inputs", heading: "Input-Text-Email" })
+get_section({ path: "component-family-form-inputs", heading: "Input-Text-Password" })
 
 // Step 3: Get button for submit action
-get_section({ path: ".kiro/steering/Component-Family-Button.md", heading: "Button-CTA" })
+get_section({ path: "component-family-button", heading: "Button-CTA" })
 
 // Step 4: Get container for layout
-get_section({ path: ".kiro/steering/Component-Family-Container.md", heading: "Container-Base" })
+get_section({ path: "component-family-container", heading: "Container-Base" })
 ```
 
 **Example: Building a Survey with Radio Groups:**
 ```
 // Step 1: Get radio component details
-get_section({ path: ".kiro/steering/Component-Family-Form-Inputs.md", heading: "Input-Radio-Base" })
-get_section({ path: ".kiro/steering/Component-Family-Form-Inputs.md", heading: "Input-Radio-Set" })
+get_section({ path: "component-family-form-inputs", heading: "Input-Radio-Base" })
+get_section({ path: "component-family-form-inputs", heading: "Input-Radio-Set" })
 
 // Step 2: Get container for section layout
-get_section({ path: ".kiro/steering/Component-Family-Container.md", heading: "Container-Base" })
+get_section({ path: "component-family-container", heading: "Container-Base" })
 
 // Step 3: Get button for submit
-get_section({ path: ".kiro/steering/Component-Family-Button.md", heading: "Button-CTA" })
+get_section({ path: "component-family-button", heading: "Button-CTA" })
 ```
 
 ## Related Documentation

package/governance/Component-Readiness-Status.md

@@ -13,7 +13,7 @@ description: Readiness status definitions, usage recommendations, and transition
 **Scope**: cross-project
 **Layer**: 2
 **Relevant Tasks**: component-development, architecture, spec-planning
-**Last Reviewed**: 2026-01-01
+**Last Reviewed**: 2026-07-09
 
 ---
 
@@ -520,17 +520,16 @@ metadata:
 **Query component readiness**:
 ```
 get_section({ 
-  path: ".kiro/steering/Component-Family-Form-Inputs.md", 
-  heading: "Component Readiness" 
+  path: "component-readiness-status", 
+  heading: "Individual Component Status" 
 })
 ```
 
 **Response includes**:
-- Component name
-- Current readiness status
-- Status indicator emoji
-- Usage recommendations
-- Migration guidance (if deprecated)
+- Component name and family
+- Roll-up status indicator (production-ready / web-ready-mobile-scaffold / scaffold)
+- Per-platform readiness breakdown (web / iOS / Android)
+- Implementation path
 
 ---
 
@@ -544,54 +543,70 @@ get_section({
 | Component Family | Shared Need/Purpose | Status | MCP Document Path |
 |------------------|---------------------|--------|-------------------|
 | Buttons | User interaction and actions | 🟢 | `.kiro/steering/Component-Family-Button.md` |
-| Form Inputs | Data collection and validation | 🟢 | `.kiro/steering/Component-Family-Form-Inputs.md` |
-| Containers | Layout and content organization | 🟢 | `.kiro/steering/Component-Family-Container.md` |
-| Icons | Visual communication | 🔴 | `.kiro/steering/Component-Family-Icon.md` |
+| Form Inputs | Data collection and validation | 🟡 | `.kiro/steering/Component-Family-Form-Inputs.md` |
+| Containers | Layout and content organization | 🟡 | `.kiro/steering/Component-Family-Container.md` |
+| Icons | Visual communication | 🟡 | `.kiro/steering/Component-Family-Icon.md` |
+| Avatars | Identity representation | 🟡 | `.kiro/steering/Component-Family-Avatar.md` |
+| Badges & Tags | Status and labeling | 🟡 | `.kiro/steering/Component-Family-Badge.md` |
+| Chips | Selection, filtering, and input tokens | 🟡 | `.kiro/steering/Component-Family-Chip.md` |
+| Navigation | Wayfinding | 🟡 | `.kiro/steering/Component-Family-Navigation.md` |
+| Progress Indicators | Progress and step indication | 🟡 | `.kiro/steering/Component-Family-Progress.md` |
 | Modals | Overlay interactions | 🔴 | `.kiro/steering/Component-Family-Modal.md` |
-| Avatars | Identity representation | 🔴 | `.kiro/steering/Component-Family-Avatar.md` |
-| Badges & Tags | Status and labeling | 🔴 | `.kiro/steering/Component-Family-Badge.md` |
 | Data Displays | Information presentation | 🔴 | `.kiro/steering/Component-Family-Data-Display.md` |
 | Dividers | Visual separation | 🔴 | `.kiro/steering/Component-Family-Divider.md` |
 | Loading | Progress indication | 🔴 | `.kiro/steering/Component-Family-Loading.md` |
-| Navigation | Wayfinding | 🔴 | `.kiro/steering/Component-Family-Navigation.md` |
 ```
 
+> **🟡 in this table = "shipping, web production-ready, iOS/Android scaffold"** — the family has usable web implementations but has not reached the strict all-platform 🟢 bar. Per-component per-platform detail is in the Individual Component Status table below. Buttons is 🟢 only because it contains all-platform-production components (Button-VerticalList-Item/Set); its CTA/Icon members are themselves web-ready/mobile-scaffold. 🔴 families are genuine placeholders (no components ship).
+
 ---
 
 ## Individual Component Status
 
 This section lists all implemented components with their readiness status and implementation paths. Used by extraction workflows to check component existence and status.
 
-| Component | Family | Status | Implementation Path |
-|-----------|--------|--------|---------------------|
-| Avatar | Avatars | 🟡 Beta | `src/components/core/Avatar/` |
-| BadgeCountBase | Badges & Tags | 🟢 Production Ready | `src/components/core/Badge-Count-Base/` |
-| BadgeCountNotification | Badges & Tags | 🟢 Production Ready | `src/components/core/Badge-Count-Notification/` |
-| BadgeLabelBase | Badges & Tags | 🟢 Production Ready | `src/components/core/Badge-Label-Base/` |
-| ButtonCTA | Buttons | 🟢 Production Ready | `src/components/core/Button-CTA/` |
-| ButtonIcon | Buttons | 🟢 Production Ready | `src/components/core/Button-Icon/` |
-| ButtonVerticalListItem | Buttons | 🟢 Production Ready | `src/components/core/Button-VerticalList-Item/` |
-| ButtonVerticalListSet | Buttons | 🟢 Production Ready | `src/components/core/Button-VerticalList-Set/` |
-| ChipBase | Badges & Tags | 🟢 Production Ready | `src/components/core/Chip-Base/` |
-| ChipFilter | Badges & Tags | 🟢 Production Ready | `src/components/core/Chip-Filter/` |
-| ChipInput | Badges & Tags | 🟢 Production Ready | `src/components/core/Chip-Input/` |
-| ContainerBase | Containers | 🟢 Production Ready | `src/components/core/Container-Base/` |
-| ContainerCardBase | Containers | 🟢 Production Ready | `src/components/core/Container-Card-Base/` |
-| IconBase | Icons | 🟢 Production Ready | `src/components/core/Icon-Base/` |
-| InputCheckboxBase | Form Inputs | 🟢 Production Ready | `src/components/core/Input-Checkbox-Base/` |
-| InputCheckboxLegal | Form Inputs | 🟢 Production Ready | `src/components/core/Input-Checkbox-Legal/` |
-| InputRadioBase | Form Inputs | 🟢 Production Ready | `src/components/core/Input-Radio-Base/` |
-| InputRadioSet | Form Inputs | 🟢 Production Ready | `src/components/core/Input-Radio-Set/` |
-| InputTextBase | Form Inputs | ⚠️ Deprecated | `src/components/core/Input-Text-Base/` |
-| InputTextEmail | Form Inputs | 🟢 Production Ready | `src/components/core/Input-Text-Email/` |
-| InputTextPassword | Form Inputs | 🟢 Production Ready | `src/components/core/Input-Text-Password/` |
-| InputTextPhoneNumber | Form Inputs | 🟢 Production Ready | `src/components/core/Input-Text-PhoneNumber/` |
-| ProgressIndicatorConnectorBase | Loading | 🟢 Production Ready | `src/components/core/Progress-Indicator-Connector-Base/` |
-| ProgressIndicatorLabelBase | Loading | 🟢 Production Ready | `src/components/core/Progress-Indicator-Label-Base/` |
-| ProgressIndicatorNodeBase | Loading | 🟢 Production Ready | `src/components/core/Progress-Indicator-Node-Base/` |
-| ProgressPaginationBase | Loading | 🟢 Production Ready | `src/components/core/Progress-Pagination-Base/` |
-| ProgressStepperBase | Loading | 🟢 Production Ready | `src/components/core/Progress-Stepper-Base/` |
-| ProgressStepperDetailed | Loading | 🟢 Production Ready | `src/components/core/Progress-Stepper-Detailed/` |
+**Per-platform status convention**: readiness is tracked per platform (web / iOS / Android). The **Status** column carries a single roll-up indicator; the **Platform Readiness** column shows the honest per-platform breakdown so no component's mobile immaturity is hidden behind a green light.
+
+- 🟢 **Production Ready** — production-ready across ALL declared platforms (web, iOS, Android), per the strict definition above. Currently only Button-VerticalList-Item and Button-VerticalList-Set meet this bar.
+- 🟡 **Web-ready, mobile-scaffold** — web is production-ready (implemented, tested, documented) but iOS and Android are scaffold (structure present, not test-covered). Safe to consume on web; treat mobile as not-yet-ready.
+- 🟡 **Scaffold (all platforms)** — structure present on all platforms but none production-ready; intentional for permissive/internal primitives (noted inline).
+
+| Component | Family | Status | Platform Readiness (web / iOS / Android) | Implementation Path |
+|-----------|--------|--------|------------------------------------------|---------------------|
+| Avatar-Base | Avatar | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Avatar-Base/` |
+| Badge-Count-Base | Badge | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Badge-Count-Base/` |
+| Badge-Count-Notification | Badge | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Badge-Count-Notification/` |
+| Badge-Label-Base | Badge | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Badge-Label-Base/` |
+| Button-CTA | Button | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Button-CTA/` |
+| Button-Icon | Button | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Button-Icon/` |
+| Button-VerticalList-Item | Button | 🟢 | 🟢 / 🟢 / 🟢 | `src/components/core/Button-VerticalList-Item/` |
+| Button-VerticalList-Set | Button | 🟢 | 🟢 / 🟢 / 🟢 | `src/components/core/Button-VerticalList-Set/` |
+| Chip-Base | Chip | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Chip-Base/` |
+| Chip-Filter | Chip | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Chip-Filter/` |
+| Chip-Input | Chip | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Chip-Input/` |
+| Container-Base | Container | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Container-Base/` |
+| Container-Card-Base | Container | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Container-Card-Base/` |
+| Icon-Base | Icon | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Icon-Base/` |
+| Input-Checkbox-Base | Form Inputs | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Input-Checkbox-Base/` |
+| Input-Checkbox-Legal | Form Inputs | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Input-Checkbox-Legal/` |
+| Input-Radio-Base | Form Inputs | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Input-Radio-Base/` |
+| Input-Radio-Set | Form Inputs | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Input-Radio-Set/` |
+| Input-Text-Base | Form Inputs | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Input-Text-Base/` |
+| Input-Text-Email | Form Inputs | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Input-Text-Email/` |
+| Input-Text-Password | Form Inputs | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Input-Text-Password/` |
+| Input-Text-PhoneNumber | Form Inputs | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Input-Text-PhoneNumber/` |
+| Nav-Header-Page | Navigation | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Nav-Header-Page/` |
+| Nav-SegmentedChoice-Base | Navigation | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Nav-SegmentedChoice-Base/` |
+| Nav-TabBar-Base | Navigation | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Nav-TabBar-Base/` |
+| Nav-Header-App | Navigation | 🟡 | scaffold / scaffold / scaffold — permissive scaffold by design | `src/components/core/Nav-Header-App/` |
+| Nav-Header-Base | Navigation | 🟡 | scaffold / scaffold / scaffold — internal-only primitive | `src/components/core/Nav-Header-Base/` |
+| Progress-Bar-Base | Progress Indicators | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Progress-Bar-Base/` |
+| Progress-Indicator-Node-Base | Progress Indicators | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Progress-Indicator-Node-Base/` |
+| Progress-Pagination-Base | Progress Indicators | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Progress-Pagination-Base/` |
+| Progress-Stepper-Base | Progress Indicators | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Progress-Stepper-Base/` |
+| Progress-Stepper-Detailed | Progress Indicators | 🟡 | 🟢 / scaffold / scaffold | `src/components/core/Progress-Stepper-Detailed/` |
+| Progress-Indicator-Connector-Base | Progress Indicators | 🟡 | scaffold / scaffold / scaffold | `src/components/core/Progress-Indicator-Connector-Base/` |
+| Progress-Indicator-Label-Base | Progress Indicators | 🟡 | scaffold / scaffold / scaffold | `src/components/core/Progress-Indicator-Label-Base/` |
 
 **Usage:**
 

package/governance/Component-Templates.md

@@ -12,7 +12,7 @@ aliases: how do i scaffold a new component, scaffold a new component template, n
 **Scope**: cross-project
 **Layer**: 2
 **Relevant Tasks**: component-development, architecture, spec-planning
-**Last Reviewed**: 2026-01-02
+**Last Reviewed**: 2026-07-15
 
 ---
 
@@ -412,14 +412,6 @@ properties:
       - secondary: [description]
       - tertiary: [description]
   
-  # State properties
-  disabled:
-    type: boolean
-    required: false
-    default: false
-    description: |
-      When true, component is non-interactive with disabled visual styling.
-  
   # Callback properties
   [callbackProp]:
     type: "() => void"
@@ -704,29 +696,27 @@ Use when semantic variants represent different states or statuses.
 #### Focusable Contract
 
 ```yaml
-focusable:
+interaction_focusable:
   description: Can receive keyboard focus
   behavior: |
     Component can receive focus via Tab key navigation.
     Focus state is visually indicated with a focus ring.
-    Focus is managed appropriately when disabled state changes.
   wcag: "2.1.1 Keyboard, 2.4.7 Focus Visible"
   platforms: [web, ios, android]
   validation: |
     - Tab key moves focus to component
     - Focus state is visually distinct with focus ring
     - Focus ring meets 3:1 contrast ratio
-    - Disabled components are not focusable
 ```
 
 #### Pressable Contract
 
 ```yaml
-pressable:
+interaction_pressable:
   description: Responds to press/click events
   behavior: |
     Component responds to click, tap, Enter key, and Space key.
-    Press triggers the callback when not disabled.
+    Press triggers the callback.
     Platform-appropriate feedback is provided during press.
   wcag: "2.1.1 Keyboard"
   platforms: [web, ios, android]
@@ -734,25 +724,22 @@ pressable:
     - Click/tap triggers callback
     - Enter key triggers callback
     - Space key triggers callback
-    - Callback not called when disabled
 ```
 
 #### Hoverable Contract
 
 ```yaml
-hoverable:
+interaction_hover:
   description: Visual feedback on hover (pointer devices only)
   behavior: |
     On pointer devices, component shows visual feedback when mouse
     hovers over the component. Uses blend.hoverDarker token.
-    Hover state not shown when disabled.
   wcag: "1.4.13 Content on Hover or Focus"
   platforms: [web, ios, android]
   validation: |
     - Visual feedback shown on mouse enter
     - Visual feedback removed on mouse leave
     - Hover uses blend.hoverDarker token
-    - Hover state not shown when disabled
     - iOS: Only on macOS/iPadOS with pointer
     - Android: Only on desktop/ChromeOS with pointer
 ```
@@ -761,32 +748,42 @@ hoverable:
 
 ### Contract Category 2: State Contracts
 
-#### Disabled State Contract
+#### No Disabled States — Standardized Exclusion
+
+**DesignerPunk components MUST NOT declare a disabled-state contract.** Per the
+2026-07-15 adjudication (`.kiro/issues/button-cta-disabled-state-adjudication.md`),
+the no-disabled-states philosophy now holds corpus-wide with zero exceptions —
+Button-CTA was the last remaining component with a live `disabled_state`
+contract, and it has been removed in favor of the standardized exclusion below.
+
+If an action is temporarily unavailable, use one of these alternatives instead:
+
+- **`state_loading`** — the action is in-flight (async operation running).
+- **Validate-on-press / validate-on-blur** — the action is available but the
+  current input is invalid; surface the error rather than disabling the trigger.
+- **Do not render the component** — if an action is genuinely unavailable
+  (no valid path forward), omit the component entirely rather than rendering
+  it in a disabled state.
+
+Every component's `contracts.yaml` MUST carry the standardized exclusion block
+(mirrored corpus-wide, e.g. `src/components/core/Button-CTA/contracts.yaml`):
 
 ```yaml
-disabled_state:
-  description: Prevents interaction when disabled
-  behavior: |
-    When disabled, component:
-    - Cannot receive focus
-    - Cannot be interacted with
-    - Uses desaturated colors (blend.disabledDesaturate)
-    - Shows cursor: not-allowed (web)
-    - Communicates disabled state to assistive technology
-  wcag: "4.1.2 Name, Role, Value"
-  platforms: [web, ios, android]
-  validation: |
-    - Component cannot receive focus when disabled
-    - Interactions do not trigger callbacks when disabled
-    - Visual styling indicates disabled state
-    - aria-disabled="true" set (web)
-    - Disabled state announced to screen readers
+excludes:
+  state_disabled:
+    reason: "DesignerPunk does not support disabled states for usability and accessibility reasons. If an action is unavailable, the component should not be rendered."
+    category: state
 ```
 
+Do not scaffold a `disabled` prop, a `disabled_state` contract, or any
+disabled-specific validation steps in new components. For the full rationale,
+see the exclusion reason above and the 2026-07-15 adjudication ruling
+(`.kiro/issues/button-cta-disabled-state-adjudication.md`).
+
 #### Error State Contract
 
 ```yaml
-error_state:
+state_error:
   description: Shows error message and styling
   behavior: |
     When in error state, component displays:
@@ -807,7 +804,7 @@ error_state:
 #### Success State Contract
 
 ```yaml
-success_state:
+state_success:
   description: Shows success styling
   behavior: |
     When in success state, component displays:
@@ -825,12 +822,12 @@ success_state:
 #### Loading State Contract
 
 ```yaml
-loading_state:
+state_loading:
   description: Shows loading indicator during async operations
   behavior: |
     When in loading state, component:
     - Shows loading spinner or indicator
-    - Prevents interaction (similar to disabled)
+    - Prevents interaction while the async operation is in-flight
     - Maintains dimensions to prevent layout shift
     - Communicates loading state to assistive technology
   wcag: "4.1.3 Status Messages"
@@ -849,7 +846,7 @@ loading_state:
 #### Focus Ring Contract
 
 ```yaml
-focus_ring:
+interaction_focus_ring:
   description: WCAG 2.4.7 focus visible indicator
   behavior: |
     When focused via keyboard, component displays:
@@ -870,7 +867,7 @@ focus_ring:
 #### Reduced Motion Support Contract
 
 ```yaml
-reduced_motion_support:
+accessibility_reduced_motion:
   description: Respects prefers-reduced-motion
   behavior: |
     When user has reduced motion preference:
@@ -913,7 +910,7 @@ accessibility_hidden:
 #### Float Label Animation Contract
 
 ```yaml
-float_label_animation:
+content_float_label:
   description: Label animates on focus
   behavior: |
     Label smoothly transitions from placeholder position inside component
@@ -932,7 +929,7 @@ float_label_animation:
 #### Pressed State Visual Contract
 
 ```yaml
-pressed_state:
+interaction_pressed:
   description: Visual feedback when pressed
   behavior: |
     Component shows visual feedback during active press/click.
@@ -947,13 +944,12 @@ pressed_state:
     - Visual feedback shown during press
     - Feedback uses blend.pressedDarker token
     - Platform-appropriate animation/effect applied
-    - Pressed state not shown when disabled
 ```
 
 #### Gradient Glow Contract
 
 ```yaml
-gradient_glow:
+visual_gradient_glow:
   description: Radial gradient background providing state-dependent visual emphasis
   behavior: |
     Component renders an elliptical radial gradient background on
@@ -979,7 +975,7 @@ gradient_glow:
 #### Validates On Blur Contract
 
 ```yaml
-validates_on_blur:
+validation_on_blur:
   description: Validation triggers on blur
   behavior: |
     Validation state is evaluated when component loses focus.
@@ -1018,7 +1014,7 @@ custom_validation:
 #### Contains Children Contract
 
 ```yaml
-contains_children:
+layout_contains_children:
   description: Can contain child components
   behavior: |
     Component can contain any child components or content.
@@ -1038,7 +1034,7 @@ contains_children:
 #### Renders SVG Contract
 
 ```yaml
-renders_svg:
+visual_renders_svg:
   description: Renders inline SVG with correct attributes
   behavior: |
     Component renders an inline SVG element with:
@@ -1046,7 +1042,7 @@ renders_svg:
     - Appropriate fill/stroke attributes
     - Proper sizing based on size prop
     SVG content is loaded based on name from internal map.
-  wcag: N/A
+  wcag: null
   platforms: [web, ios, android]
   validation: |
     - SVG element renders with correct viewBox
@@ -1081,18 +1077,18 @@ renders_svg:
 
 | Behavior Needed | Contract(s) to Include |
 |-----------------|------------------------|
-| Keyboard navigation | focusable, focus_ring |
-| Click/tap interaction | pressable, pressed_state |
-| Mouse hover feedback | hoverable |
-| Disabled state | disabled_state |
-| Error handling | error_state, validates_on_blur |
-| Success feedback | success_state |
-| Loading indication | loading_state |
-| Animation support | reduced_motion_support |
+| Keyboard navigation | interaction_focusable, interaction_focus_ring |
+| Click/tap interaction | interaction_pressable, interaction_pressed |
+| Mouse hover feedback | interaction_hover |
+| Action temporarily unavailable | state_loading (in-flight), validation_on_blur (invalid input), or do not render (no valid path) — never a disabled-state contract; see "No Disabled States — Standardized Exclusion" |
+| Error handling | state_error, validation_on_blur |
+| Success feedback | state_success |
+| Loading indication | state_loading |
+| Animation support | accessibility_reduced_motion |
 | Decorative elements | accessibility_hidden |
-| Form validation | validates_on_blur, custom_validation |
-| Container behavior | contains_children |
-| Icon rendering | renders_svg, accessibility_hidden |
+| Form validation | validation_on_blur, custom_validation |
+| Container behavior | layout_contains_children |
+| Icon rendering | visual_renders_svg, accessibility_hidden |
 
 ### Application MCP Checklist
 

package/governance/Contract-System-Reference.md

@@ -2,7 +2,7 @@
 id: contract-system-reference
 inclusion: manual
 name: Contract-System-Reference
-description: Uniform behavioral contract system reference — 10-category taxonomy with definitions, concept catalog with all 136 concepts, {category}_{concept} naming convention, canonical contracts.yaml format, exclusion format, inheritance and composition patterns, classification rules. Load when creating or modifying component contracts, auditing contract coverage, or building contract-consuming systems.
+description: Uniform behavioral contract system reference — 10-category taxonomy with definitions, concept catalog with all 137 concepts, {category}_{concept} naming convention, canonical contracts.yaml format, exclusion format, inheritance and composition patterns, classification rules. Load when creating or modifying component contracts, auditing contract coverage, or building contract-consuming systems.
 ---
 
 # Contract System Reference
@@ -46,9 +46,9 @@ This document is the authoritative reference for contract conventions. For the d
 
 ## Concept Catalog
 
-136 concepts across 10 categories. Originally 116, derived from the 29 deployed contracts.yaml files in the Spec 078 audit; grown since through governed additions (`gradient_glow` ballot measure, Spec 088 Nav-Header concepts, Spec 090 Progress-Bar-Base concepts).
+137 concepts across 10 categories. Originally 116, derived from the 29 deployed contracts.yaml files in the Spec 078 audit; grown since through governed additions (`gradient_glow` ballot measure, Spec 088 Nav-Header concepts, Spec 090 Progress-Bar-Base concepts, `readonly` ballot measure 2026-07-15).
 
-*Adjudicated 2026-07-03 (Lina): 136 counted empirically from the per-category lists below (26+6+7+17+19+6+1+15+10+29), which are the enforced source of truth via `src/__tests__/stemma-system/contract-catalog-name-validation.test.ts`; the stale "117" figures dated from the last full-sweep update (gradient_glow, 2026-03-18), while only this section's rolling "Updated:" line had tracked subsequent additions to 136.*
+*Adjudicated 2026-07-03 (Lina): 137 counted empirically from the per-category lists below (26+6+7+17+19+6+1+16+10+29), which are the enforced source of truth via `src/__tests__/stemma-system/contract-catalog-name-validation.test.ts`; the stale "117" figures dated from the last full-sweep update (gradient_glow, 2026-03-18), while only this section's rolling "Updated:" line had tracked subsequent additions to 136. state grew to 16 via the 2026-07-15 readonly ballot.*
 
 ### accessibility (26)
 
@@ -78,9 +78,9 @@ This document is the authoritative reference for contract conventions. For the d
 
 `virtualization`
 
-### state (15)
+### state (16)
 
-`binary_derivation` · `checked` · `connector_derivation` · `controlled` · `disabled` · `error` · `indeterminate` · `loading` · `mode_driven` · `priority_derivation` · `selected` · `selected_styling` · `styling` · `success` · `visual_driven`
+`binary_derivation` · `checked` · `connector_derivation` · `controlled` · `disabled` · `error` · `indeterminate` · `loading` · `mode_driven` · `priority_derivation` · `readonly` · `selected` · `selected_styling` · `styling` · `success` · `visual_driven`
 
 ### validation (10)
 
@@ -110,7 +110,7 @@ All contract names follow `{category}_{concept}` in `snake_case`. No `supports_`
 | Checkmark animation | `animation_checkmark` |
 | Circular shape | `visual_circular_shape` |
 
-The Concept Catalog above lists all 136 concepts. For the historical migration mapping (113 source names → 104 canonical names, pre-Task 2.1), see `.kiro/specs/063-uniform-contract-system/findings/canonical-name-mapping.md`.
+The Concept Catalog above lists all 137 concepts. For the historical migration mapping (113 source names → 104 canonical names, pre-Task 2.1), see `.kiro/specs/063-uniform-contract-system/findings/canonical-name-mapping.md`.
 
 ---
 
@@ -180,7 +180,7 @@ excludes:
 | `category` | Taxonomy category (redundant with name prefix — enables validation) |
 | `description` | Short description of the behavioral guarantee |
 | `behavior` | Detailed behavior description |
-| `wcag` | WCAG criterion this contract supports (null if not applicable) |
+| `wcag` | WCAG criterion this contract supports — required for allowlisted contracts (use the 'N/A' sentinel when genuinely not applicable); null only for non-allowlisted contracts |
 | `platforms` | Platforms where this contract applies |
 | `validation` | Testable criteria for verifying the contract |
 | `test_approach` | How to test this contract |