@3fn/core 13.0.0 → 14.1.0

package/dist/browser/tokens.css

@@ -1,6 +1,6 @@
 /**
  * DesignerPunk Design System - Web Tokens
- * Generated: 2026-07-05T14:35:59.888Z
+ * Generated: 2026-08-26T14:15:24.233Z
  * Version: 1.0.0
  * Platform: Web (CSS Custom Properties)
  *
@@ -998,6 +998,8 @@
   --inputradio-box-lg: var(--size-500);
 
   /* Progress Component Tokens */
+  /* Connector line thickness (1px). References borderDefault primitive for consistent border treatment across the design system. */
+  --progress-connector-thickness: var(--border-width-100);
   /* Small node base size (12px). Inactive dots in compact mobile contexts. */
   --progress-node-size-sm: var(--size-150);
   /* Medium node base size (16px). Default inactive dot size. */
@@ -1016,8 +1018,6 @@
   --progress-node-gap-md: var(--space-100);
   /* Large gap between nodes (12px = 1.5× base). Generous spacing for detailed steppers with labels in desktop contexts. */
   --progress-node-gap-lg: var(--space-150);
-  /* Connector line thickness (1px). References borderDefault primitive for consistent border treatment across the design system. */
-  --progress-connector-thickness: var(--border-width-100);
 
   /* VerticalListItem Component Tokens */
   /* Block padding at rest state (1px border). 11px padding + 1px border = 12px per side, achieving 48px total with 24px content. Uses TokenWithValue pattern as no primitive token exists for 11px. */

package/dist/build/tokens/defineComponentTokens.d.ts

@@ -60,6 +60,16 @@ export interface PrimitiveTokenReference {
     name: string;
     /** Unitless base value from the primitive token */
     baseValue: number;
+    /**
+     * Primitive token family (the `category` field of a `PrimitiveToken`, e.g. 'spacing',
+     * 'sizing', 'radius'). OPTIONAL for backward compatibility: minimal `{ name, baseValue }`
+     * reference literals remain valid.
+     *
+     * When present, it is cross-checked against the call's declared `family` by the
+     * family-mismatch guard in {@link defineComponentTokens}. Real primitives from
+     * src/tokens/** always carry it, so the guard is active for all production authoring.
+     */
+    category?: string;
 }
 /**
  * Token definition with primitive reference

package/dist/build/tokens/defineComponentTokens.js

@@ -125,6 +125,32 @@ function defineComponentTokens(config) {
         if (isTokenWithReference(definition)) {
             // Token with primitive reference
             const primitiveToken = definition.reference;
+            // FAMILY-MISMATCH GUARD.
+            // The call's `family` is stamped onto every token it registers, and the generator
+            // derives platform output from it — notably the primitive class name used for
+            // reference-path tokens (getFamilyClassName) and the Android `.dp` suffix. A call
+            // that declares one family but references another family's primitive therefore emits
+            // a member that does not exist on the target platform. That is exactly the Button-Icon
+            // defect: a `family: 'spacing'` call referencing `sizingTokens.size600` generated
+            // `SpacingTokens.size600`, a non-existent member (PR #126).
+            //
+            // Only enforced when the reference carries a `category` — minimal `{ name, baseValue }`
+            // literals (used widely in tests) are intentionally exempt rather than rejected.
+            //
+            // Escape hatch: a token that legitimately needs another family's VALUE should use the
+            // value path (`value:`), which asserts no cross-family token-chain claim.
+            if (typeof primitiveToken.category === 'string' &&
+                primitiveToken.category !== family) {
+                throw new Error(`Token family mismatch in defineComponentTokens() for component '${component}': ` +
+                    `token '${key}' is declared in a '${family}' family call but references primitive ` +
+                    `'${primitiveToken.name}' from the '${primitiveToken.category}' family. ` +
+                    `Every token in a call is stamped with that call's family, which drives platform ` +
+                    `output (e.g. the generated '${family.charAt(0).toUpperCase() + family.slice(1)}Tokens' ` +
+                    `class reference), so this would emit a non-existent platform member. ` +
+                    `Fix: move '${key}' into a separate defineComponentTokens() call with ` +
+                    `family: '${primitiveToken.category}', or use the value path if no token-chain ` +
+                    `relationship is intended.`);
+            }
             const value = primitiveToken.baseValue;
             values[key] = value;
             registeredTokens.push({

package/dist/components/core/Avatar-Base/avatar.tokens.d.ts

@@ -34,6 +34,15 @@
  * - xs: calc(icon.size050 × 0.75) = 12px
  * - xxl: calc(icon.size050 × 4) = 64px
  *
+ * TOKEN FAMILY: all dimensional Avatar tokens (container `size.*` AND icon
+ * `icon.size.*` gap fillers) are registered by the single sizing-family call
+ * `AvatarSizingTokens` below. The `icon.size.*` pair previously lived in a
+ * separate `AvatarTokens` call stamped `family: 'spacing'` — a mislabel, since
+ * both are dimensional sizing values. `AvatarTokens` is removed; consumers use
+ * `AvatarSizingTokens` or the `getAvatarIconSize()` / `getAvatarSize()` accessors.
+ * Generated platform output is unaffected: both calls declare `component: 'Avatar'`,
+ * so all tokens still land in one `AvatarTokens` Swift enum / Kotlin object.
+ *
  * COLOR TOKENS (Spec 058):
  * Avatar color tokens are defined in this file following the Rosetta System architecture
  * which mandates component tokens live at src/components/[ComponentName]/tokens.ts.
@@ -52,13 +61,24 @@
  * @see .kiro/specs/058-component-token-architecture-cleanup for color token migration
  */
 /**
- * Avatar sizing tokens — container dimensions for each size variant.
+ * Avatar sizing tokens — container dimensions and icon dimensions for each size variant.
  *
  * Previously in a separate file (avatar-sizing.tokens.ts). Inlined to prevent
  * architectural anomaly (no other component splits tokens across files) and
  * simplify the package surface for sync.
  *
+ * ONE CALL PER FAMILY. Every token registered by a single defineComponentTokens()
+ * call is stamped with that call's `family`, and the family drives platform output
+ * (Swift type, Kotlin `.dp` suffix, primitive class name). The `icon.size.*` gap
+ * fillers below are dimensional sizing values, so they live in this sizing-family
+ * call — they were previously mis-stamped `family: 'spacing'` in a separate
+ * `AvatarTokens` call, the same latent mislabel class fixed for Button-Icon.
+ * Do NOT spread/merge this result with another call's result — the rich metadata
+ * rides on a non-enumerable brand (see src/build/tokens/defineComponentTokens.ts,
+ * TOKEN_CONTRACT_BRAND) that a spread would silently drop.
+ *
  * @see .kiro/specs/092-sizing-token-family/design.md
+ * @see src/components/core/Button-Icon/buttonIcon.tokens.ts for the two-call pattern
  */
 export declare const AvatarSizingTokens: import("../../../build/tokens").ComponentTokenValues<{
     'size.xs': {
@@ -85,31 +105,6 @@ export declare const AvatarSizingTokens: import("../../../build/tokens").Compone
         reference: import("../../../types").PrimitiveToken;
         reasoning: string;
     };
-}>;
-/**
- * Avatar component tokens defined using the hybrid authoring API.
- *
- * Each token either references a primitive spacing token or uses a family-conformant
- * derivation, and includes reasoning explaining why the token exists.
- *
- * NOTE: Web platform uses CSS calc() with icon tokens for sizing (see Avatar.styles.css).
- * These component tokens are primarily used for iOS/Android platforms and documentation.
- *
- * Size token values:
- * - size.xs: 24px (3 × base, references size300)
- * - size.sm: 32px (4 × base, references size400)
- * - size.md: 40px (5 × base, references size500)
- * - size.lg: 48px (6 × base, references size600)
- * - size.xl: 80px (10 × base, derivation)
- * - size.xxl: 128px (16 × base, derivation)
- *
- * Icon size token values (gap fillers - web uses calc() instead):
- * - icon.size.xs: 12px (1.5 × base, derivation) - web uses calc(icon.size050 × 0.75)
- * - icon.size.xxl: 64px (8 × base, derivation) - web uses calc(icon.size050 × 4)
- *
- * @see Requirements 2.1-2.6, 3.1, 3.6 in .kiro/specs/042-avatar-component/requirements.md
- */
-export declare const AvatarTokens: import("../../../build/tokens").ComponentTokenValues<{
     'icon.size.xs': {
         value: number;
         reasoning: string;

package/dist/components/core/Avatar-Base/avatar.tokens.js

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

package/dist/components/core/Avatar-Base/index.d.ts

@@ -6,7 +6,7 @@
  */
 export type { AvatarProps, AvatarType, AvatarSize } from './types';
 export { AVATAR_DEFAULTS } from './types';
-export { AvatarTokens, getAvatarSize, getAvatarIconSize, getAvatarSizeTokenReference, getAvatarIconSizeTokenReference, AvatarSizeTokenReferences, AvatarIconSizeTokenReferences, } from './avatar.tokens';
+export { AvatarSizingTokens, getAvatarSize, getAvatarIconSize, getAvatarSizeTokenReference, getAvatarIconSizeTokenReference, AvatarSizeTokenReferences, AvatarIconSizeTokenReferences, } from './avatar.tokens';
 export type { AvatarSizeVariant, AvatarIconSizeVariant } from './avatar.tokens';
 export { AvatarBaseElement } from './platforms/web/Avatar.web';
 //# sourceMappingURL=index.d.ts.map

package/dist/components/core/Avatar-Base/index.js

@@ -6,12 +6,12 @@
  * @see .kiro/specs/042-avatar-component/requirements.md for requirements
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AvatarBaseElement = exports.AvatarIconSizeTokenReferences = exports.AvatarSizeTokenReferences = exports.getAvatarIconSizeTokenReference = exports.getAvatarSizeTokenReference = exports.getAvatarIconSize = exports.getAvatarSize = exports.AvatarTokens = exports.AVATAR_DEFAULTS = void 0;
+exports.AvatarBaseElement = exports.AvatarIconSizeTokenReferences = exports.AvatarSizeTokenReferences = exports.getAvatarIconSizeTokenReference = exports.getAvatarSizeTokenReference = exports.getAvatarIconSize = exports.getAvatarSize = exports.AvatarSizingTokens = exports.AVATAR_DEFAULTS = void 0;
 var types_1 = require("./types");
 Object.defineProperty(exports, "AVATAR_DEFAULTS", { enumerable: true, get: function () { return types_1.AVATAR_DEFAULTS; } });
 // Token exports
 var avatar_tokens_1 = require("./avatar.tokens");
-Object.defineProperty(exports, "AvatarTokens", { enumerable: true, get: function () { return avatar_tokens_1.AvatarTokens; } });
+Object.defineProperty(exports, "AvatarSizingTokens", { enumerable: true, get: function () { return avatar_tokens_1.AvatarSizingTokens; } });
 Object.defineProperty(exports, "getAvatarSize", { enumerable: true, get: function () { return avatar_tokens_1.getAvatarSize; } });
 Object.defineProperty(exports, "getAvatarIconSize", { enumerable: true, get: function () { return avatar_tokens_1.getAvatarIconSize; } });
 Object.defineProperty(exports, "getAvatarSizeTokenReference", { enumerable: true, get: function () { return avatar_tokens_1.getAvatarSizeTokenReference; } });

package/dist/components/core/Avatar-Base/platforms/web/Avatar.web.js

@@ -643,11 +643,30 @@ class AvatarBaseElement extends HTMLElement {
         // Generate aria-hidden attribute for decorative avatars
         // @see Requirements: 9.2 - Apply aria-hidden="true" when decorative prop is true
         const ariaHiddenAttr = decorative ? ' aria-hidden="true"' : '';
-        // Warn in development if src is provided without alt
-        // @see Requirements: 5.4 - Require alt prop when src is provided
-        if (src && !alt && typeof console !== 'undefined') {
-            console.warn('AvatarBaseElement: "alt" prop is required when "src" is provided for accessibility. ' +
-                'Please add an alt attribute describing the image.');
+        // Warn in development if a human-type avatar is missing alt text for its image.
+        // @see Requirements: 5.4 - Human type + src SHALL require alt for accessibility
+        // @see Requirements: 5 AC 5 - Agent type SHALL ignore src entirely (src not
+        //   rendered as an image), so agent-type avatars never warn regardless of alt.
+        //
+        // Settled edge semantics (Spec 126, O2, ratified 2026-07-09):
+        // - Scope is human-type only — Req 5.4 is human-type-scoped, and Req 5 AC 5
+        //   affirmatively establishes that agent-type SHALL ignore src, so a src+no-alt
+        //   agent avatar is not a violation of anything.
+        // - `alt == null` (loose equality — also excludes `undefined`), not `!alt`, is the
+        //   test. The `alt` attribute getter returns `getAttribute('alt')`. Raw
+        //   `setAttribute('alt', '')` yields `alt === ''`, which is the HTML-idiomatic
+        //   explicit-empty-alt signal and must NOT warn. The `alt` *property setter*
+        //   (see below) treats a falsy value as "remove the attribute," so
+        //   `avatar.alt = ''` collapses to `alt === null` — indistinguishable from
+        //   omitting alt entirely, and DOES warn under this condition.
+        // - `!decorative` is the operative fix for the confirmed false positive: a
+        //   `decorative` avatar is the component's official signal that the image is
+        //   non-informative (Req 9.2 applies `aria-hidden="true"`), so it must never warn
+        //   regardless of alt.
+        if (type === 'human' && src && alt == null && !decorative && typeof console !== 'undefined') {
+            console.warn('AvatarBaseElement: "alt" is required when "src" is provided. ' +
+                'Add an alt description of the image; or, if this avatar is purely decorative ' +
+                '(non-informative), set the "decorative" prop to hide it from screen readers.');
         }
         // Render different structures based on type
         // Agent type uses SVG-based hexagon with Bézier curves for true rounded corners

package/dist/components/core/Button-CTA/examples/BasicUsage.d.ts

@@ -19,7 +19,6 @@
  * - size: 'medium' (48px height)
  * - variant: 'primary' (filled background with primary color)
  * - noWrap: false (text wraps if needed)
- * - disabled: false (interactive)
  *
  * @example
  * ```html
@@ -54,7 +53,6 @@ export declare function customLabelButton(): void;
  *
  * The 'press' event:
  * - Bubbles up through the DOM
- * - Is not called when button is disabled
  * - Works with click, tap, Enter key, and Space key
  * - Provides originalEvent in event.detail for advanced use cases
  *
@@ -67,39 +65,29 @@ export declare function customLabelButton(): void;
  */
 export declare function buttonWithHandler(): void;
 /**
- * Example 4: Disabled Button
+ * Example 4: Unavailable Actions (no disabled state)
  *
- * Demonstrates how to disable a button to prevent user interaction.
- * Disabled buttons are commonly used during form submission, when prerequisites
- * aren't met, or when an action is temporarily unavailable.
+ * DesignerPunk does not support disabled states for usability and
+ * accessibility reasons. If an action is unavailable, the component
+ * should not be rendered.
  *
- * Disabled button behavior:
- * - Not keyboard focusable (skipped in Tab order)
- * - Does not respond to clicks or keyboard activation
- * - Visual styling indicates non-interactive state
- * - Screen readers announce disabled state
- * - onPress handler is not called
- *
- * Common use cases:
- * - Form submission in progress
- * - Required fields not filled
- * - User lacks permissions
- * - Action temporarily unavailable
- *
- * @example
- * ```html
- * <button-cta label="Submit" disabled></button-cta>
- * ```
+ * For in-flight async operations (e.g. form submission), use the loading
+ * state instead of disabling the button. For actions the user cannot take
+ * yet, keep the button interactive and validate on press, or do not render
+ * the button at all.
  *
  * @example
  * ```typescript
- * // Conditional disable based on form state
- * const button = document.createElement('button-cta') as ButtonCTA;
- * button.label = 'Submit';
- * button.disabled = isSubmitting || !isFormValid;
+ * // Conditionally render instead of disabling
+ * if (userCanSubmit) {
+ *   const button = document.createElement('button-cta') as ButtonCTA;
+ *   button.label = 'Submit';
+ *   button.addEventListener('press', handleSubmit);
+ *   document.body.appendChild(button);
+ * }
  * ```
  */
-export declare function disabledButton(): void;
+export declare function conditionallyRenderedButton(): void;
 /**
  * Example 5: All Examples Together
  *

package/dist/components/core/Button-CTA/examples/BasicUsage.js

@@ -14,7 +14,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.defaultButton = defaultButton;
 exports.customLabelButton = customLabelButton;
 exports.buttonWithHandler = buttonWithHandler;
-exports.disabledButton = disabledButton;
+exports.conditionallyRenderedButton = conditionallyRenderedButton;
 exports.renderAllBasicExamples = renderAllBasicExamples;
 /**
  * Example 1: Default Button (Medium, Primary)
@@ -26,7 +26,6 @@ exports.renderAllBasicExamples = renderAllBasicExamples;
  * - size: 'medium' (48px height)
  * - variant: 'primary' (filled background with primary color)
  * - noWrap: false (text wraps if needed)
- * - disabled: false (interactive)
  *
  * @example
  * ```html
@@ -77,7 +76,6 @@ function customLabelButton() {
  *
  * The 'press' event:
  * - Bubbles up through the DOM
- * - Is not called when button is disabled
  * - Works with click, tap, Enter key, and Space key
  * - Provides originalEvent in event.detail for advanced use cases
  *
@@ -105,52 +103,35 @@ function buttonWithHandler() {
     document.body.appendChild(button);
 }
 /**
- * Example 4: Disabled Button
+ * Example 4: Unavailable Actions (no disabled state)
  *
- * Demonstrates how to disable a button to prevent user interaction.
- * Disabled buttons are commonly used during form submission, when prerequisites
- * aren't met, or when an action is temporarily unavailable.
+ * DesignerPunk does not support disabled states for usability and
+ * accessibility reasons. If an action is unavailable, the component
+ * should not be rendered.
  *
- * Disabled button behavior:
- * - Not keyboard focusable (skipped in Tab order)
- * - Does not respond to clicks or keyboard activation
- * - Visual styling indicates non-interactive state
- * - Screen readers announce disabled state
- * - onPress handler is not called
- *
- * Common use cases:
- * - Form submission in progress
- * - Required fields not filled
- * - User lacks permissions
- * - Action temporarily unavailable
- *
- * @example
- * ```html
- * <button-cta label="Submit" disabled></button-cta>
- * ```
+ * For in-flight async operations (e.g. form submission), use the loading
+ * state instead of disabling the button. For actions the user cannot take
+ * yet, keep the button interactive and validate on press, or do not render
+ * the button at all.
  *
  * @example
  * ```typescript
- * // Conditional disable based on form state
- * const button = document.createElement('button-cta') as ButtonCTA;
- * button.label = 'Submit';
- * button.disabled = isSubmitting || !isFormValid;
+ * // Conditionally render instead of disabling
+ * if (userCanSubmit) {
+ *   const button = document.createElement('button-cta') as ButtonCTA;
+ *   button.label = 'Submit';
+ *   button.addEventListener('press', handleSubmit);
+ *   document.body.appendChild(button);
+ * }
  * ```
  */
-function disabledButton() {
+function conditionallyRenderedButton() {
     const button = document.createElement('button-cta');
     button.label = 'Submit';
-    button.disabled = true; // Button is non-interactive
-    // This handler will NOT be called when button is disabled
     button.addEventListener('press', () => {
-        console.log('This will not be logged when button is disabled');
+        console.log('Submitted');
     });
     document.body.appendChild(button);
-    // Example: Enable button after 3 seconds (simulating async operation)
-    setTimeout(() => {
-        button.disabled = false;
-        console.log('Button is now enabled');
-    }, 3000);
 }
 /**
  * Example 5: All Examples Together
@@ -188,12 +169,6 @@ function renderAllBasicExamples() {
         alert('Form submitted successfully!');
     });
     container.appendChild(handlerBtn);
-    // Example 4: Disabled
-    const disabledBtn = document.createElement('button-cta');
-    disabledBtn.label = 'Disabled Button';
-    disabledBtn.disabled = true;
-    disabledBtn.addEventListener('press', () => console.log('This will not log'));
-    container.appendChild(disabledBtn);
     // Add container to document
     document.body.appendChild(container);
 }

package/dist/components/core/Button-CTA/platforms/web/ButtonCTA.web.d.ts

@@ -12,7 +12,7 @@
  * composition pattern as iOS and Android platforms. This ensures cross-platform
  * consistency and single source of truth for icon rendering.
  *
- * Uses theme-aware blend utilities for state colors (hover, pressed, disabled, icon)
+ * Uses theme-aware blend utilities for state colors (hover, pressed, icon)
  * instead of opacity or filter workarounds. This ensures cross-platform consistency
  * with iOS and Android implementations.
  *
@@ -32,13 +32,12 @@ import '../../../Icon-Base/platforms/web/IconBase.web';
  * - Semantic `<button>` element with proper accessibility
  * - Token-based styling via CSS custom properties
  * - Supports text wrapping by default (accessibility-first)
- * - Uses blend utilities for state colors (hover, pressed, disabled, icon)
+ * - Uses blend utilities for state colors (hover, pressed, icon)
  * - WCAG 2.1 AA compliant:
  *   - Keyboard navigation (Tab, Enter, Space)
  *   - Focus indicators with 3:1 contrast ratio
  *   - Color contrast 4.5:1 for all styles
  *   - Screen reader support with ARIA attributes
- *   - Proper disabled state handling
  *
  * @example
  * ```html
@@ -52,7 +51,6 @@ import '../../../Icon-Base/platforms/web/IconBase.web';
  *   variant="primary"
  *   icon="arrow-right"
  *   no-wrap="false"
- *   disabled="false"
  *   test-id="submit-button"
  * ></button-cta>
  * ```
@@ -77,7 +75,6 @@ export declare class ButtonCTA extends HTMLElement {
     private _blendUtils;
     private _hoverColor;
     private _pressedColor;
-    private _disabledColor;
     private _iconColor;
     private _iconOpticalBalanceColor;
     /**
@@ -108,7 +105,7 @@ export declare class ButtonCTA extends HTMLElement {
      * Calculate blend colors from CSS custom properties.
      *
      * Reads base colors from CSS custom properties and applies theme-aware blend
-     * utilities to generate state colors (hover, pressed, disabled, icon).
+     * utilities to generate state colors (hover, pressed, icon).
      *
      * Uses getBlendUtilities() factory functions instead of direct blend calculations
      * for cross-platform consistency with iOS and Android implementations.
@@ -116,7 +113,6 @@ export declare class ButtonCTA extends HTMLElement {
      * State color mappings:
      * - Hover: darkerBlend(color.action.primary, blend.hoverDarker) - 8% darker
      * - Pressed: darkerBlend(color.action.primary, blend.pressedDarker) - 12% darker
-     * - Disabled: desaturate(color.action.primary, blend.disabledDesaturate) - 12% less saturated
      * - Icon: lighterBlend(color.contrast.onAction, blend.iconLighter) - 8% lighter
      *
      * @see Requirements: 7.1, 7.2, 7.3, 7.4 - Button-CTA state colors
@@ -180,14 +176,6 @@ export declare class ButtonCTA extends HTMLElement {
      * Set the no-wrap state.
      */
     set noWrap(value: boolean);
-    /**
-     * Get the disabled state.
-     */
-    get disabled(): boolean;
-    /**
-     * Set the disabled state.
-     */
-    set disabled(value: boolean);
     /**
      * Get the test ID.
      */