@3fn/core 13.0.0 → 14.0.0

package/src/components/core/Input-Text-Email/platforms/ios/InputTextEmail.ios.swift

@@ -104,10 +104,7 @@ struct InputTextEmail: View {
     
     /// Maximum length for input value
     let maxLength: Int?
-    
-    /// Disabled state
-    let isDisabled: Bool
-    
+
     /// Custom invalid email message
     let invalidEmailMessage: String
     
@@ -155,7 +152,6 @@ struct InputTextEmail: View {
         readOnly: Bool = false,
         required: Bool = false,
         maxLength: Int? = nil,
-        isDisabled: Bool = false,
         invalidEmailMessage: String = defaultInvalidEmailMessage,
         customValidator: ((String) -> Bool)? = nil
     ) {
@@ -174,7 +170,6 @@ struct InputTextEmail: View {
         self.readOnly = readOnly
         self.required = required
         self.maxLength = maxLength
-        self.isDisabled = isDisabled
         self.invalidEmailMessage = invalidEmailMessage
         self.customValidator = customValidator
     }
@@ -207,8 +202,7 @@ struct InputTextEmail: View {
             placeholder: placeholder,
             readOnly: readOnly,
             required: required,
-            maxLength: maxLength,
-            isDisabled: isDisabled
+            maxLength: maxLength
         )
     }
     
@@ -268,14 +262,6 @@ struct InputTextEmail_Previews: PreviewProvider {
                 isSuccess: true
             )
             
-            InputTextEmail(
-                id: "preview-disabled",
-                label: "Email",
-                value: .constant("user@example.com"),
-                helperText: "This field is disabled",
-                isDisabled: true
-            )
-            
             InputTextEmail(
                 id: "preview-required",
                 label: "Email",

package/src/components/core/Input-Text-Password/Input-Text-Password.schema.yaml

@@ -103,7 +103,12 @@ properties:
     type: boolean
     required: false
     default: false
-    description: Read-only state (alternative to disabled)
+    description: >-
+      Accepted for API stability but IGNORED — readOnly is contracted out of
+      Input-Text-Password (contracts.yaml excludes.state_readonly; adjudication
+      .kiro/issues/input-text-base-ios-readonly-adjudication.md, RULED B-prime,
+      Peter 2026-07-15). Implementations never forward it to the base on any
+      platform.
   
   required:
     type: boolean
@@ -262,13 +267,15 @@ platform_notes:
   ios:
     implementation: SwiftUI View wrapping InputTextBase
     file: platforms/ios/InputTextPassword.ios.swift
-    toggle: Button with SF Symbol eye/eye.slash
+    toggle: Button with SF Symbol eye/eye.slash, injected via the base's trailingContent slot
     autocomplete: UITextContentType.password or .newPassword
+    visibility: Toggles by switching base type between .password and .text
   android:
     implementation: Jetpack Compose Composable wrapping InputTextBase
     file: platforms/android/InputTextPassword.android.kt
-    toggle: IconButton with visibility icons
+    toggle: IconButton with visibility icons, injected via the base's trailingContent slot
     autocomplete: Autofill framework password type
+    visibility: Toggles via the base's visualTransformation override (type stays PASSWORD)
 
 # Inheritance relationship
 inheritance:

package/src/components/core/Input-Text-Password/README.md

@@ -178,7 +178,7 @@ InputTextPassword(
 | `isSuccess` | boolean | No | false | Success state indicator |
 | `showInfoIcon` | boolean | No | false | Show info icon |
 | `placeholder` | string | No | - | Placeholder text |
-| `readOnly` | boolean | No | false | Read-only state |
+| `readOnly` | boolean | No | false | Accepted but **ignored** — readOnly is contracted out of Input-Text-Password (never forwarded to the base; see contracts.yaml `excludes.state_readonly` and the adjudication `.kiro/issues/input-text-base-ios-readonly-adjudication.md`, RULED B-prime 2026-07-15) |
 | `required` | boolean | No | false | Required field indicator |
 | `maxLength` | number | No | - | Maximum input length |
 | `testID` | string | No | - | Test ID for automation |
@@ -216,16 +216,17 @@ InputTextPassword(
 3. **validates_on_blur**: Validation triggers on blur
 4. **error_state_display**: Shows error message and styling
 5. **success_state_display**: Shows success styling
-6. **disabled_state**: Prevents interaction when disabled
-7. **trailing_icon_display**: Shows contextual trailing icons
-8. **focus_ring**: WCAG 2.4.7 focus visible indicator
-9. **reduced_motion_support**: Respects prefers-reduced-motion
+6. **trailing_icon_display**: Shows contextual trailing icons
+7. **focus_ring**: WCAG 2.4.7 focus visible indicator
+8. **reduced_motion_support**: Respects prefers-reduced-motion
+
+**Excluded**: `state_disabled` — DesignerPunk does not support disabled states for usability and accessibility reasons. If an action is unavailable, the component should not be rendered (adjudicated 2026-07-15).
 
 ### Password-Specific Contracts
 
-10. **provides_secure_input**: Masks password input by default
-11. **supports_password_toggle**: Show/hide password functionality
-12. **provides_password_autocomplete**: Enables browser/platform password autofill
+9. **provides_secure_input**: Masks password input by default
+10. **supports_password_toggle**: Show/hide password functionality
+11. **provides_password_autocomplete**: Enables browser/platform password autofill
 
 ## Validation
 

package/src/components/core/Input-Text-Password/contracts.yaml

@@ -61,3 +61,8 @@ 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
+
+  state_readonly:
+    reason: "readOnly is contracted out of Input-Text-Password: zero named consumers, and excluding it deletes a security fork — the base's iOS read-only path (B-prime) renders the value as selectable plaintext Text, which must never be reachable for a secret. The profile idiom for a locked password is a display row ('Password ••••••••') plus a Change action, not a read-only password field. Implementations strip/ignore the inherited readOnly prop. If a product case ever materializes, the invariant-based fallback rule recorded in the adjudication ([DATA R2] §3: masked value never copyable; plaintext never in the accessibility tree while masked; announced semantically as hidden; no keyboard; toggle functional; revealed plaintext selectable/copyable) is the recorded alternative."
+    category: state
+    reference: ".kiro/issues/input-text-base-ios-readonly-adjudication.md (RULED B-prime, Peter 2026-07-15, condition 4)"

package/src/components/core/Input-Text-Password/platforms/android/InputTextPassword.android.kt

@@ -117,12 +117,20 @@ private fun validatePasswordRequirements(
  * @param isSuccess Success state indicator
  * @param showInfoIcon Info icon support
  * @param placeholder Placeholder text (only shown when label is floated and input is empty)
- * @param readOnly Read-only state
+ * @param readOnly Read-only state — NOT SUPPORTED on Input-Text-Password.
+ *   readOnly is contracted OUT of the Password variant (see Input-Text-Password
+ *   contracts.yaml excludes.state_readonly; adjudication condition 4:
+ *   .kiro/issues/input-text-base-ios-readonly-adjudication.md — RULED B-prime,
+ *   Peter 2026-07-15). Zero named consumers; contracting it out deletes the
+ *   security fork rather than fencing it. Note this is contract conformance,
+ *   not a security fix: on Android the masked PasswordVisualTransformation
+ *   already suppresses copy/cut ([DATA R2] §3 verification). This param is
+ *   accepted for API stability but IGNORED: it is never forwarded to
+ *   InputTextBase.
  * @param required Required field indicator
  * @param maxLength Maximum length for input value
  * @param imeAction IME action for keyboard
  * @param keyboardActions Keyboard actions
- * @param isDisabled Disabled state
  * @param showToggle Whether to show the toggle button
  * @param isNewPassword Whether this is for a new password
  * @param invalidPasswordMessage Custom invalid password message
@@ -150,7 +158,6 @@ fun InputTextPassword(
     maxLength: Int? = null,
     imeAction: ImeAction = ImeAction.Done,
     keyboardActions: KeyboardActions = KeyboardActions.Default,
-    isDisabled: Boolean = false,
     showToggle: Boolean = true,
     isNewPassword: Boolean = false,
     invalidPasswordMessage: String = DEFAULT_INVALID_PASSWORD_MESSAGE,
@@ -212,8 +219,7 @@ fun InputTextPassword(
                 onClick = {
                     isPasswordVisible = !isPasswordVisible
                     onToggleVisibility?.invoke(isPasswordVisible)
-                },
-                enabled = !isDisabled
+                }
             ) {
                 Icon(
                     imageVector = if (isPasswordVisible) Icons.Filled.VisibilityOff else Icons.Filled.Visibility,
@@ -256,12 +262,16 @@ fun InputTextPassword(
         type = InputType.PASSWORD,
         visualTransformation = visualTransformation,
         placeholder = placeholder,
-        readOnly = readOnly,
+        // readOnly is contracted out of Input-Text-Password (excludes.state_readonly;
+        // adjudication condition 4: .kiro/issues/input-text-base-ios-readonly-adjudication.md
+        // — RULED B-prime, Peter 2026-07-15). Always stripped. Contract conformance,
+        // not a security fix — Android's masked PasswordVisualTransformation already
+        // suppresses copy/cut, so Android was never the hazard here ([DATA R2] §3).
+        readOnly = false,
         required = required,
         maxLength = maxLength,
         imeAction = imeAction,
         keyboardActions = keyboardActions,
-        isDisabled = isDisabled,
         trailingContent = toggleButton
     )
 }

package/src/components/core/Input-Text-Password/platforms/ios/InputTextPassword.ios.swift

@@ -132,7 +132,16 @@ struct InputTextPassword: View {
     /// Placeholder text (only shown when label is floated and input is empty)
     let placeholder: String?
     
-    /// Read-only state
+    /// Read-only state — NOT SUPPORTED on Input-Text-Password.
+    ///
+    /// readOnly is contracted OUT of the Password variant (see
+    /// contracts.yaml excludes.state_readonly; adjudication condition 4:
+    /// .kiro/issues/input-text-base-ios-readonly-adjudication.md — RULED
+    /// B-prime, Peter 2026-07-15). Zero named consumers, and the Base's
+    /// read-only path renders selectable plaintext Text — a readOnly
+    /// Password must never reach it, masked or revealed. This prop is
+    /// accepted for API stability but IGNORED: it is never forwarded to
+    /// InputTextBase.
     let readOnly: Bool
     
     /// Required field indicator
@@ -140,10 +149,7 @@ struct InputTextPassword: View {
     
     /// Maximum length for input value
     let maxLength: Int?
-    
-    /// Disabled state
-    let isDisabled: Bool
-    
+
     /// Whether to show the toggle button
     let showToggle: Bool
     
@@ -212,7 +218,6 @@ struct InputTextPassword: View {
         readOnly: Bool = false,
         required: Bool = false,
         maxLength: Int? = nil,
-        isDisabled: Bool = false,
         showToggle: Bool = true,
         isNewPassword: Bool = false,
         invalidPasswordMessage: String = defaultInvalidPasswordMessage,
@@ -235,7 +240,6 @@ struct InputTextPassword: View {
         self.readOnly = readOnly
         self.required = required
         self.maxLength = maxLength
-        self.isDisabled = isDisabled
         self.showToggle = showToggle
         self.isNewPassword = isNewPassword
         self.invalidPasswordMessage = invalidPasswordMessage
@@ -273,10 +277,14 @@ struct InputTextPassword: View {
                     type: .text,
                     autocomplete: contentType,
                     placeholder: placeholder,
-                    readOnly: readOnly,
+                    // SECURITY: readOnly is contracted out of Input-Text-Password
+                    // (adjudication, RULED B-prime, Peter 2026-07-15). The revealed
+                    // branch uses type .text — forwarding readOnly here would route
+                    // the secret to the Base's selectable plaintext Text path.
+                    // Always stripped.
+                    readOnly: false,
                     required: required,
                     maxLength: maxLength,
-                    isDisabled: isDisabled,
                     trailingContent: showToggle ? AnyView(toggleButton) : nil
                 )
             } else {
@@ -304,10 +312,13 @@ struct InputTextPassword: View {
                     type: .password,
                     autocomplete: contentType,
                     placeholder: placeholder,
-                    readOnly: readOnly,
+                    // SECURITY: readOnly is contracted out of Input-Text-Password
+                    // (adjudication, RULED B-prime, Peter 2026-07-15). Stripped on
+                    // the masked branch too — the Base additionally gates its
+                    // read-only Text path away from secure fields (defense in depth).
+                    readOnly: false,
                     required: required,
                     maxLength: maxLength,
-                    isDisabled: isDisabled,
                     trailingContent: showToggle ? AnyView(toggleButton) : nil
                 )
             }
@@ -327,7 +338,6 @@ struct InputTextPassword: View {
                 .contentShape(Rectangle())
         }
         .buttonStyle(PlainButtonStyle())
-        .disabled(isDisabled)
         .accessibilityLabel(isPasswordVisible ? "Hide password" : "Show password")
         .accessibilityAddTraits(.isButton)
     }
@@ -408,14 +418,6 @@ struct InputTextPassword_Previews: PreviewProvider {
                 isSuccess: true
             )
             
-            InputTextPassword(
-                id: "preview-disabled",
-                label: "Password",
-                value: .constant("secretpassword"),
-                helperText: "This field is disabled",
-                isDisabled: true
-            )
-            
             InputTextPassword(
                 id: "preview-new-password",
                 label: "New Password",

package/src/components/core/Input-Text-Password/platforms/web/InputTextPassword.web.ts

@@ -74,6 +74,9 @@ export class InputTextPassword extends HTMLElement {
       'error-message',
       'is-success',
       'show-info-icon',
+      // read-only is accepted for API stability but IGNORED — readOnly is
+      // contracted out of Input-Text-Password (see render(), and
+      // contracts.yaml excludes.state_readonly).
       'read-only',
       'required',
       'max-length',
@@ -154,7 +157,14 @@ export class InputTextPassword extends HTMLElement {
     const propsErrorMessage = this.getAttribute('error-message') || '';
     const isSuccess = this.getAttribute('is-success') === 'true';
     const showInfoIcon = this.getAttribute('show-info-icon') === 'true';
-    const readOnly = this.hasAttribute('read-only');
+    // read-only is NOT read or forwarded: readOnly is contracted out of
+    // Input-Text-Password (adjudication condition 4:
+    // .kiro/issues/input-text-base-ios-readonly-adjudication.md — RULED
+    // B-prime, Peter 2026-07-15). On web this is contract conformance, not a
+    // security fix — a readonly password input stays masked and browsers
+    // block copy from type=password — but the exclusion holds uniformly on
+    // all three platforms. The attribute is accepted (observedAttributes)
+    // for API stability and ignored.
     const required = this.hasAttribute('required');
     const maxLength = this.getAttribute('max-length');
     const showToggle = this.getAttribute('show-toggle') !== 'false'; // Default true
@@ -197,7 +207,6 @@ export class InputTextPassword extends HTMLElement {
           ${errorMessage ? `error-message="${errorMessage}"` : ''}
           ${isSuccess ? 'is-success="true"' : ''}
           ${showInfoIcon ? 'show-info-icon="true"' : ''}
-          ${readOnly ? 'read-only' : ''}
           ${required ? 'required' : ''}
           ${maxLength ? `max-length="${maxLength}"` : ''}
         ></input-text-base>

package/src/components/core/Input-Text-PhoneNumber/Input-Text-PhoneNumber.schema.yaml

@@ -103,7 +103,11 @@ properties:
     type: boolean
     required: false
     default: false
-    description: Read-only state (alternative to disabled)
+    description: >-
+      Read-only display state (state_readonly contract) — the value is
+      non-editable but stays perceivable, selectable, and copyable; no
+      keyboard/IME is raised and disabled semantics are never applied. iOS
+      renders it as selectable static text inside the field chrome.
   
   required:
     type: boolean

package/src/components/core/Input-Text-PhoneNumber/README.md

@@ -101,7 +101,7 @@ InputTextPhoneNumber(
 | `isSuccess` | boolean | No | false | Success state indicator |
 | `showInfoIcon` | boolean | No | false | Show info icon |
 | `placeholder` | string | No | - | Placeholder text |
-| `readOnly` | boolean | No | false | Read-only state |
+| `readOnly` | boolean | No | false | Read-only display state (`state_readonly` contract): value is non-editable but selectable and copyable; no keyboard raised; iOS renders selectable text in the field chrome |
 | `required` | boolean | No | false | Required field indicator |
 | `maxLength` | number | No | - | Maximum input length |
 | `testID` | string | No | - | Test ID for automation |
@@ -149,16 +149,17 @@ InputTextPhoneNumber(
 3. **validates_on_blur**: Validation triggers on blur
 4. **error_state_display**: Shows error message and styling
 5. **success_state_display**: Shows success styling
-6. **disabled_state**: Prevents interaction when disabled
-7. **trailing_icon_display**: Shows contextual trailing icons
-8. **focus_ring**: WCAG 2.4.7 focus visible indicator
-9. **reduced_motion_support**: Respects prefers-reduced-motion
+6. **trailing_icon_display**: Shows contextual trailing icons
+7. **focus_ring**: WCAG 2.4.7 focus visible indicator
+8. **reduced_motion_support**: Respects prefers-reduced-motion
+
+**Excluded**: `state_disabled` — DesignerPunk does not support disabled states for usability and accessibility reasons. If an action is unavailable, the component should not be rendered (adjudicated 2026-07-15).
 
 ### Phone-Specific Contracts
 
-10. **validates_phone_format**: Validates phone against country-specific patterns
-11. **provides_phone_formatting**: Formats phone numbers as user types
-12. **supports_international_formats**: Handles multiple country formats
+9. **validates_phone_format**: Validates phone against country-specific patterns
+10. **provides_phone_formatting**: Formats phone numbers as user types
+11. **supports_international_formats**: Handles multiple country formats
 
 ## Validation
 

package/src/components/core/Input-Text-PhoneNumber/platforms/android/InputTextPhoneNumber.android.kt

@@ -151,7 +151,6 @@ private fun isValidPhoneNumber(phoneNumber: String, countryCode: String = DEFAUL
  * @param maxLength Maximum length for input value
  * @param imeAction IME action for keyboard
  * @param keyboardActions Keyboard actions
- * @param isDisabled Disabled state
  * @param countryCode Country code for formatting and validation
  * @param autoFormat Whether to auto-format as user types
  * @param invalidPhoneMessage Custom invalid phone message
@@ -177,7 +176,6 @@ fun InputTextPhoneNumber(
     maxLength: Int? = null,
     imeAction: ImeAction = ImeAction.Done,
     keyboardActions: KeyboardActions = KeyboardActions.Default,
-    isDisabled: Boolean = false,
     countryCode: String = DEFAULT_COUNTRY_CODE,
     autoFormat: Boolean = true,
     invalidPhoneMessage: String = DEFAULT_INVALID_PHONE_MESSAGE,
@@ -252,14 +250,13 @@ fun InputTextPhoneNumber(
         errorMessage = effectiveErrorMessage,
         isSuccess = isSuccess,
         showInfoIcon = showInfoIcon,
-        type = InputType.PHONE,
+        type = InputType.TEL,
         placeholder = placeholder,
         readOnly = readOnly,
         required = required,
         maxLength = maxLength,
         imeAction = imeAction,
-        keyboardActions = keyboardActions,
-        isDisabled = isDisabled
+        keyboardActions = keyboardActions
     )
 }
 

package/src/components/core/Input-Text-PhoneNumber/platforms/ios/InputTextPhoneNumber.ios.swift

@@ -175,10 +175,7 @@ struct InputTextPhoneNumber: View {
     
     /// Maximum length for input value
     let maxLength: Int?
-    
-    /// Disabled state
-    let isDisabled: Bool
-    
+
     /// Country code for formatting and validation
     let countryCode: String
     
@@ -243,7 +240,6 @@ struct InputTextPhoneNumber: View {
         readOnly: Bool = false,
         required: Bool = false,
         maxLength: Int? = nil,
-        isDisabled: Bool = false,
         countryCode: String = defaultCountryCode,
         autoFormat: Bool = true,
         invalidPhoneMessage: String = defaultInvalidPhoneMessage,
@@ -264,7 +260,6 @@ struct InputTextPhoneNumber: View {
         self.readOnly = readOnly
         self.required = required
         self.maxLength = maxLength
-        self.isDisabled = isDisabled
         self.countryCode = countryCode
         self.autoFormat = autoFormat
         self.invalidPhoneMessage = invalidPhoneMessage
@@ -296,13 +291,12 @@ struct InputTextPhoneNumber: View {
             errorMessage: effectiveErrorMessage,
             isSuccess: isSuccess,
             showInfoIcon: showInfoIcon,
-            type: .phone,
+            type: .tel,
             autocomplete: .telephoneNumber,
             placeholder: placeholder,
             readOnly: readOnly,
             required: required,
-            maxLength: maxLength,
-            isDisabled: isDisabled
+            maxLength: maxLength
         )
         .onAppear {
             // Initialize formatted value from initial value
@@ -396,14 +390,6 @@ struct InputTextPhoneNumber_Previews: PreviewProvider {
                 countryCode: "GB"
             )
             
-            InputTextPhoneNumber(
-                id: "preview-disabled",
-                label: "Phone Number",
-                value: .constant("5551234567"),
-                helperText: "This field is disabled",
-                isDisabled: true
-            )
-            
             InputTextPhoneNumber(
                 id: "preview-required",
                 label: "Phone Number",

package/src/components/core/Nav-Header-App/contracts.yaml

@@ -12,7 +12,7 @@ contracts:
       may contain logos, search inputs, or other non-heading content.
       Heading semantics are the responsibility of Nav-Header-Page (h1)
       and future variants (Nav-Header-Modal: h2).
-    wcag: null
+    wcag: "N/A"  # legitimate-null: renders-no-heading negative guarantee, no positive WCAG SC (125-B 4.2)
     platforms: [web, ios, android]
     validation:
       - No h1/h2/h3 element rendered

package/src/components/core/Nav-SegmentedChoice-Base/contracts.yaml

@@ -122,7 +122,7 @@ contracts:
     description: Renders text label for text segments
     behavior: |
       When a segment has a label property, renders the label as text content.
-    wcag: null
+    wcag: "1.3.1 Info and Relationships"
     platforms: [web, ios, android]
     validation:
       - Text segment displays label string

package/src/components/core/Progress-Indicator-Connector-Base/contracts.yaml

@@ -59,7 +59,7 @@ contracts:
       Connector-Base is marked as decorative (aria-hidden on web,
       accessibilityHidden on iOS, clearAndSetSemantics on Android).
       Semantic variants provide ARIA roles and labels.
-    wcag: null
+    wcag: "1.1.1 Non-text Content"
     platforms: [web, ios, android]
     validation:
       - Connector has aria-hidden="true" (web)

package/src/components/core/Progress-Indicator-Label-Base/contracts.yaml

@@ -65,7 +65,7 @@ contracts:
       Label-Base is marked as decorative (aria-hidden on web,
       accessibilityHidden on iOS, clearAndSetSemantics on Android).
       Semantic variants provide ARIA roles and labels.
-    wcag: null
+    wcag: "1.1.1 Non-text Content"
     platforms: [web, ios, android]
     validation:
       - Label has aria-hidden="true" (web)

package/src/components/core/Progress-Indicator-Node-Base/contracts.yaml

@@ -85,7 +85,7 @@ contracts:
       Node-Base is marked as decorative (aria-hidden on web,
       accessibilityHidden on iOS, clearAndSetSemantics on Android).
       Semantic variants provide ARIA roles and labels.
-    wcag: null
+    wcag: "1.1.1 Non-text Content"
     platforms: [web, ios, android]
     validation:
       - Node has aria-hidden="true" (web)

package/src/components/core/Progress-Stepper-Base/__tests__/StepperBase.test.ts

@@ -255,8 +255,11 @@ describe('Progress-Stepper-Base', () => {
     });
 
     it('throws error when size="sm" (Req 8.10)', () => {
-      // jsdom's custom element lifecycle is async, so we need to catch the error differently
-      const errorHandler = jest.fn();
+      // jsdom's custom element lifecycle is async, so we need to catch the error differently.
+      // preventDefault() marks the error HANDLED, which stops jsdom's default reporter from
+      // printing an "Uncaught [Error: ...]" console.error block for this expected throw
+      // (CI-log noise; the assertion below still receives the event first).
+      const errorHandler = jest.fn((event: ErrorEvent) => event.preventDefault());
       window.addEventListener('error', errorHandler);
 
       createStepper({ 'total-steps': '3', 'current-step': '1', size: 'sm' });

package/src/components/core/Progress-Stepper-Detailed/__tests__/StepperDetailed.test.ts

@@ -353,8 +353,11 @@ describe('Progress-Stepper-Detailed', () => {
     });
 
     it('throws error when size="sm" (Req 8.10)', () => {
-      // jsdom's custom element lifecycle is async, so we need to catch the error differently
-      const errorHandler = jest.fn();
+      // jsdom's custom element lifecycle is async, so we need to catch the error differently.
+      // preventDefault() marks the error HANDLED, which stops jsdom's default reporter from
+      // printing an "Uncaught [Error: ...]" console.error block for this expected throw
+      // (CI-log noise; the assertion below still receives the event first).
+      const errorHandler = jest.fn((event: ErrorEvent) => event.preventDefault());
       window.addEventListener('error', errorHandler);
 
       createStepperDetailed({

package/src/generators/DTCGFormatGenerator.ts

@@ -724,6 +724,12 @@ export class DTCGFormatGenerator {
       } else if (token.direction === 'lighter') {
         extensions.blendType = 'lighterBlend';
       }
+      // Deprecation metadata (e.g. blend.disabledDesaturate) — lets includeDeprecated: false strip it
+      if (token.deprecated) {
+        extensions.deprecated = true;
+        if (token.deprecatedSince) extensions.deprecatedSince = token.deprecatedSince;
+        if (token.deprecatedReason) extensions.deprecatedReason = token.deprecatedReason;
+      }
 
       group[key] = this.toDTCGToken(aliasValue, 'number', token.description, extensions);
     }

package/src/generators/__tests__/DTCGConfigOptions.test.ts

@@ -200,9 +200,8 @@ describe('DTCGFormatGenerator Configuration Options', () => {
   // -------------------------------------------------------------------------
   describe('includeDeprecated: false', () => {
     it('should exclude tokens marked as deprecated', () => {
-      // Since no tokens currently have deprecated: true in their data,
-      // we verify the infrastructure works by generating with both configs
-      // and confirming the output is identical (no deprecated tokens to strip)
+      // blend.disabledDesaturate is deprecated (2026-07-15, no-disabled-states ruling)
+      // and is currently the only deprecated token in the corpus
       const withDeprecated = new DTCGFormatGenerator({ includeDeprecated: true });
       const withoutDeprecated = new DTCGFormatGenerator({ includeDeprecated: false });
 
@@ -213,10 +212,20 @@ describe('DTCGFormatGenerator Configuration Options', () => {
       expect(outputWith.$schema).toBeDefined();
       expect(outputWithout.$schema).toBeDefined();
 
-      // Since no tokens are currently deprecated, counts should match
+      // includeDeprecated: true keeps the token and carries deprecation metadata
+      const blendWith = outputWith.semanticBlend as Record<string, any>;
+      expect(blendWith['blend.disabledDesaturate']).toBeDefined();
+      expect(blendWith['blend.disabledDesaturate'].$extensions?.designerpunk?.deprecated).toBe(true);
+      expect(blendWith['blend.disabledDesaturate'].$extensions?.designerpunk?.deprecatedSince).toBe('2026-07-15');
+
+      // includeDeprecated: false strips it
+      const blendWithout = outputWithout.semanticBlend as Record<string, any>;
+      expect(blendWithout['blend.disabledDesaturate']).toBeUndefined();
+
+      // Exactly the deprecated token is stripped — nothing else
       const countWith = countAllTokens(outputWith);
       const countWithout = countAllTokens(outputWithout);
-      expect(countWith).toBe(countWithout);
+      expect(countWith).toBe(countWithout + 1);
     });
   });
 });

package/src/integration/BuildErrorHandler.ts

@@ -268,7 +268,7 @@ export class BuildErrorHandler {
         'Validate configuration against schema'
       ],
       documentation: [
-        'https://github.com/3fn/DesignerPunkv2/docs/build-integration.md'
+        'https://github.com/3fn/DesignerPunk/docs/build-integration.md'
       ]
     };
   }
@@ -293,7 +293,7 @@ export class BuildErrorHandler {
         'Ensure platform files are generated correctly'
       ],
       documentation: [
-        `https://github.com/3fn/DesignerPunkv2/docs/platforms/${platform}.md`
+        `https://github.com/3fn/DesignerPunk/docs/platforms/${platform}.md`
       ]
     };
   }

package/src/tokens/OpacityTokens.ts

@@ -113,7 +113,7 @@ export const opacityTokens: Record<string, PrimitiveToken> = {
     category: TokenCategory.OPACITY,
     baseValue: OPACITY_BASE_VALUE * 6,
     familyBaseValue: OPACITY_BASE_VALUE,
-    description: 'Disabled state - faded, very strong overlay',
+    description: 'Very strong transparency - background scrims and modal overlays (referenced by opacity.heavy)',
     mathematicalRelationship: 'base × 6 = 0.08 × 6 = 0.48',
     baselineGridAlignment: false,
     isStrategicFlexibility: false,

package/src/tokens/__tests__/OpacityTokens.test.ts

@@ -280,7 +280,9 @@ describe('Opacity Tokens', () => {
       
       expect(opacity000?.description).toContain('Fully transparent');
       expect(opacity008?.description).toContain('Subtle transparency');
-      expect(opacity048?.description).toContain('Disabled state');
+      // opacity048 description corrected 2026-07-15: disabled-state phrasing removed
+      // (no-disabled-states philosophy, Button-CTA adjudication)
+      expect(opacity048?.description).toContain('Very strong transparency');
       expect(opacity100?.description).toContain('Fully opaque');
     });