@3fn/core 13.0.0 → 14.1.0

package/src/cli/__tests__/init.test.ts

@@ -23,11 +23,45 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { runInit } from '../init';
+import { resolvePackageRoot } from '../shared/resolvePackageRoot';
 
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * Count files recursively under `dir`, matching `copyDir()`'s counting semantics
+ * in init.ts (files only, descending into subdirectories).
+ *
+ * Used to DERIVE the expected governance-doc count from the same source `init`
+ * copies from, rather than hard-coding a literal. The governance corpus is the
+ * relocated non-identity docs (Spec 119-A) and grows by design — a hard-coded
+ * count drifts (and repeatedly HAS drifted, e.g. 80 → 81 → 82) every time a doc
+ * is added, with no relation to the behavior under test. Deriving from source
+ * keeps the real check — "init copies EVERY governance doc, dropping none" —
+ * while decoupling it from the corpus's exact size.
+ */
+function countFilesRecursive(dir: string): number {
+  let count = 0;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    count += entry.isDirectory()
+      ? countFilesRecursive(path.join(dir, entry.name))
+      : entry.isFile()
+        ? 1
+        : 0;
+  }
+  return count;
+}
+
+// The package root `init` copies from is resolved by `resolvePackageRoot(<init's
+// dir>)` = two levels up from `src/cli/`. This test file lives one level deeper
+// (`src/cli/__tests__/`), so pass its parent (`src/cli/`) to resolve the SAME root.
+const PKG_ROOT = resolvePackageRoot(path.join(__dirname, '..'));
+
+// Expected governance-doc count, derived from source (see countFilesRecursive).
+// NOT hard-coded: governance/ grows as the corpus grows.
+const GOVERNANCE_DOC_COUNT = countFilesRecursive(path.join(PKG_ROOT, 'governance'));
+
 /**
  * Create a unique scratch directory under the OS temp dir.
  * Returns the absolute path. Caller is responsible for cleanup.
@@ -140,11 +174,12 @@ describe('CLI init — integration', () => {
       expect(secondOutput).toContain('existing files preserved');
       // Spec 119-A two-root split: 9 identity docs ship in .kiro/steering/
       // (8 identity + the NEW Task-Completion-Protocol added in Task 8; the
-      // meta-guide was removed in 119-A Task 10.5 → back to 9),
-      // and the 81 relocated non-identity docs ship in governance/
-      // (80 + Steering-Addressing-Conventions.md added in Task 12).
+      // meta-guide was removed in 119-A Task 10.5 → back to 9). The identity set
+      // is a LOCKED always-set — asserted as exactly 9 on purpose, so a change to
+      // it is a signal worth catching. The governance corpus, by contrast, grows
+      // routinely, so its count is derived from source (GOVERNANCE_DOC_COUNT).
       expect(secondOutput).toContain('✓ steering docs: 9 existing files preserved');
-      expect(secondOutput).toContain('✓ governance docs: 81 existing files preserved');
+      expect(secondOutput).toContain(`✓ governance docs: ${GOVERNANCE_DOC_COUNT} existing files preserved`);
     });
 
     test('preserves existing files — no overwrites after second run', async () => {
@@ -190,11 +225,11 @@ describe('CLI init — integration', () => {
       // Spec 119-A two-root split: the package contributes 9 identity steering
       // files (8 identity + the NEW Task-Completion-Protocol from Task 8; the
       // meta-guide was removed in Task 10.5; no conflict with designerpunk.md
-      // because the package doesn't have a file by that name) and 81 relocated
-      // docs into the separate governance/ dir
-      // (80 + Steering-Addressing-Conventions.md added in Task 12).
+      // because the package doesn't have a file by that name) and the relocated
+      // non-identity docs into the separate governance/ dir. Steering is the
+      // locked 9; governance is derived from source (grows with the corpus).
       expect(output).toContain('✓ steering docs: 9 new files');
-      expect(output).toContain('✓ governance docs: 81 new files');
+      expect(output).toContain(`✓ governance docs: ${GOVERNANCE_DOC_COUNT} new files`);
 
       // Custom file preserved
       expect(
@@ -205,10 +240,9 @@ describe('CLI init — integration', () => {
       const steeringFiles = fs.readdirSync(path.join(scratchDir, '.kiro/steering'));
       expect(steeringFiles.length).toBe(10);
 
-      // The 81 relocated docs land in governance/
-      // (80 + Steering-Addressing-Conventions.md added in Task 12)
+      // The relocated docs land in governance/ — every one init copied from source.
       const governanceFiles = fs.readdirSync(path.join(scratchDir, 'governance'));
-      expect(governanceFiles.length).toBe(81);
+      expect(governanceFiles.length).toBe(GOVERNANCE_DOC_COUNT);
     });
   });
 

package/src/components/core/Avatar-Base/Avatar-Base.schema.yaml

@@ -60,7 +60,7 @@ properties:
   alt:
     type: string
     required: false
-    description: Alt text for accessibility. Required if src provided.
+    description: Alt text for accessibility. Required if src provided on human type, unless decorative is true (agent type ignores src entirely, per Req 5 AC 5).
   interactive:
     type: boolean
     required: false

package/src/components/core/Avatar-Base/__tests__/Avatar.accessibility.test.ts

@@ -212,14 +212,20 @@ describe('Avatar Component Accessibility', () => {
     });
 
     it('should apply empty alt when alt is empty string', async () => {
+      // Spec 126 (O2): uses the raw-attribute form (setAttribute) to produce a
+      // genuine alt="" — the `alt` *property* setter treats '' as falsy and calls
+      // removeAttribute, collapsing `avatar.alt = ''` to the same "absent" state as
+      // omitting alt entirely (see Avatar.web.ts `set alt`). Only the attribute form
+      // yields a real empty-string alt, and under the settled warn condition
+      // (`alt == null`), a real empty-string alt does not warn — so no spy is needed.
       const avatar = document.createElement('avatar-base') as AvatarBaseElement;
       avatar.type = 'human';
       avatar.src = 'https://example.com/profile.jpg';
-      avatar.alt = '';
+      avatar.setAttribute('alt', '');
       document.body.appendChild(avatar);
-      
+
       await new Promise(resolve => setTimeout(resolve, 0));
-      
+
       const img = avatar.shadowRoot?.querySelector('.avatar__image');
       expect(img).toBeTruthy();
       expect(img?.getAttribute('alt')).toBe('');
@@ -285,16 +291,124 @@ describe('Avatar Component Accessibility', () => {
 
     it('should NOT warn when no src is provided', async () => {
       const consoleSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
-      
+
       const avatar = document.createElement('avatar-base') as AvatarBaseElement;
       avatar.type = 'human';
       // No src, no alt
       document.body.appendChild(avatar);
-      
+
       await new Promise(resolve => setTimeout(resolve, 0));
-      
+
       expect(consoleSpy).not.toHaveBeenCalled();
-      
+
+      consoleSpy.mockRestore();
+    });
+  });
+
+  // ============================================================================
+  // Alt Text Warning — Decorative & Type-Scope Edge Semantics (Spec 126, O2)
+  // ============================================================================
+  //
+  // Settled warn condition: `type === 'human' && src && alt == null && !decorative`
+  // @see Requirements: 5.4 - Human type + src SHALL require alt for accessibility
+  // @see Requirements: 5 AC 5 - Agent type SHALL ignore src entirely
+  // @see .kiro/specs/126-avatar-decorative-warn/design-outline.md § 4/5
+  //
+  // Together with the sentinel test above ('should warn when src is provided
+  // without alt'), this block forms the six-test matrix settled by Spec 126 § 5
+  // item 2. The sentinel is left unchanged (Spec 126 § 7 non-regression signal).
+  describe('Alt Text Warning — Decorative & Type-Scope Edge Semantics (Spec 126)', () => {
+    it('should NOT warn when alt="" is set via raw attribute (explicit empty, not "absent")', async () => {
+      const consoleSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+
+      const avatar = document.createElement('avatar-base') as AvatarBaseElement;
+      avatar.type = 'human';
+      avatar.src = 'https://example.com/profile.jpg';
+      // Raw attribute form is the only path that yields a genuine alt="" (getter
+      // returns '', not null) — the `alt` property setter collapses falsy values to
+      // removeAttribute, so this test must use setAttribute to exercise the real case.
+      avatar.setAttribute('alt', '');
+      document.body.appendChild(avatar);
+
+      await new Promise(resolve => setTimeout(resolve, 0));
+
+      expect(consoleSpy).not.toHaveBeenCalled();
+
+      consoleSpy.mockRestore();
+    });
+
+    it('should warn when alt is set to empty string via the property (collapses to null via the setter)', async () => {
+      const consoleSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+
+      const avatar = document.createElement('avatar-base') as AvatarBaseElement;
+      avatar.type = 'human';
+      avatar.src = 'https://example.com/profile.jpg';
+      // Property-form empty string: the `alt` setter treats '' as falsy and calls
+      // removeAttribute('alt'), so this lands in the "alt absent" bucket and warns —
+      // pins the attribute-vs-property collapse explicitly (Spec 126 § 5 item 2).
+      avatar.alt = '';
+      document.body.appendChild(avatar);
+
+      await new Promise(resolve => setTimeout(resolve, 0));
+
+      expect(consoleSpy).toHaveBeenCalledWith(
+        expect.stringContaining('alt')
+      );
+
+      consoleSpy.mockRestore();
+    });
+
+    it('should NOT warn when decorative is true, even without alt (co-asserted with aria-hidden)', async () => {
+      const consoleSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+
+      const avatar = document.createElement('avatar-base') as AvatarBaseElement;
+      avatar.type = 'human';
+      avatar.src = 'https://example.com/profile.jpg';
+      avatar.decorative = true;
+      // No alt provided
+      document.body.appendChild(avatar);
+
+      await new Promise(resolve => setTimeout(resolve, 0));
+
+      expect(consoleSpy).not.toHaveBeenCalled();
+
+      // Co-assert the semantic linkage (Req 9.2): the warn is correctly suppressed
+      // because the avatar is genuinely hidden from screen readers, not incidentally.
+      const container = avatar.shadowRoot?.querySelector('.avatar');
+      expect(container?.getAttribute('aria-hidden')).toBe('true');
+
+      consoleSpy.mockRestore();
+    });
+
+    it('should NOT warn for agent type with src and no alt (Req 5 AC 5 — agent ignores src entirely)', async () => {
+      const consoleSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+
+      const avatar = document.createElement('avatar-base') as AvatarBaseElement;
+      avatar.type = 'agent';
+      avatar.src = 'https://example.com/profile.jpg';
+      // No alt provided
+      document.body.appendChild(avatar);
+
+      await new Promise(resolve => setTimeout(resolve, 0));
+
+      expect(consoleSpy).not.toHaveBeenCalled();
+
+      consoleSpy.mockRestore();
+    });
+
+    it('should NOT warn for agent type with src and alt both present (confirms silencing is type-driven, not alt-driven)', async () => {
+      const consoleSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+
+      const avatar = document.createElement('avatar-base') as AvatarBaseElement;
+      avatar.type = 'agent';
+      avatar.src = 'https://example.com/profile.jpg';
+      avatar.alt = 'Ignored for agent type';
+      document.body.appendChild(avatar);
+
+      await new Promise(resolve => setTimeout(resolve, 0));
+
+      expect(consoleSpy).not.toHaveBeenCalled();
+
       consoleSpy.mockRestore();
     });
   });

package/src/components/core/Avatar-Base/__tests__/Avatar.image.test.ts

@@ -287,6 +287,7 @@ describe('Avatar Component Image Handling', () => {
       const avatar = document.createElement('avatar-base') as AvatarBaseElement;
       avatar.type = 'agent';
       avatar.src = 'https://example.com/agent-image.jpg';
+      avatar.alt = 'Agent profile'; // honor the alt-with-src contract (Req 5.4)
       document.body.appendChild(avatar);
       
       await new Promise(resolve => setTimeout(resolve, 0));
@@ -299,6 +300,7 @@ describe('Avatar Component Image Handling', () => {
       const avatar = document.createElement('avatar-base') as AvatarBaseElement;
       avatar.type = 'agent';
       avatar.src = 'https://example.com/agent-image.jpg';
+      avatar.alt = 'Agent profile'; // honor the alt-with-src contract (Req 5.4)
       document.body.appendChild(avatar);
       
       await new Promise(resolve => setTimeout(resolve, 0));
@@ -311,6 +313,7 @@ describe('Avatar Component Image Handling', () => {
       const avatar = document.createElement('avatar-base') as AvatarBaseElement;
       avatar.type = 'agent';
       avatar.src = 'https://example.com/agent-image.jpg';
+      avatar.alt = 'Agent profile'; // honor the alt-with-src contract (Req 5.4)
       document.body.appendChild(avatar);
       
       await new Promise(resolve => setTimeout(resolve, 0));

package/src/components/core/Avatar-Base/__tests__/Avatar.test.ts

@@ -218,27 +218,33 @@ describe('Avatar Component Core API', () => {
   // ============================================================================
   
   describe('Src Prop', () => {
+    // Fixtures set `alt` alongside `src` so they honor the component's own a11y
+    // contract (Req 5.4: alt is required with src) — otherwise the component
+    // rightly warns, polluting CI logs. The assertions below are about src only.
     it('should accept src value', () => {
       const avatar = document.createElement('avatar-base') as AvatarBaseElement;
       avatar.src = 'https://example.com/image.jpg';
+      avatar.alt = 'Test avatar';
       document.body.appendChild(avatar);
-      
+
       expect(avatar.src).toBe('https://example.com/image.jpg');
       expect(avatar.getAttribute('src')).toBe('https://example.com/image.jpg');
     });
 
     it('should update src via attribute', () => {
       const avatar = document.createElement('avatar-base') as AvatarBaseElement;
+      avatar.alt = 'Test avatar';
       document.body.appendChild(avatar);
-      
+
       avatar.setAttribute('src', 'https://example.com/new-image.jpg');
       expect(avatar.src).toBe('https://example.com/new-image.jpg');
     });
 
     it('should update src via property', () => {
       const avatar = document.createElement('avatar-base') as AvatarBaseElement;
+      avatar.alt = 'Test avatar';
       document.body.appendChild(avatar);
-      
+
       avatar.src = 'https://example.com/profile.png';
       expect(avatar.getAttribute('src')).toBe('https://example.com/profile.png');
     });
@@ -246,8 +252,9 @@ describe('Avatar Component Core API', () => {
     it('should remove src attribute when set to null', () => {
       const avatar = document.createElement('avatar-base') as AvatarBaseElement;
       avatar.src = 'https://example.com/image.jpg';
+      avatar.alt = 'Test avatar';
       document.body.appendChild(avatar);
-      
+
       avatar.src = null;
       expect(avatar.src).toBeNull();
       expect(avatar.hasAttribute('src')).toBe(false);
@@ -566,8 +573,9 @@ describe('Avatar Component Core API', () => {
 
     it('should reflect src property to attribute', () => {
       const avatar = document.createElement('avatar-base') as AvatarBaseElement;
+      avatar.alt = 'Test avatar'; // honor the alt-with-src contract (Req 5.4)
       document.body.appendChild(avatar);
-      
+
       avatar.src = 'https://example.com/test.jpg';
       expect(avatar.getAttribute('src')).toBe('https://example.com/test.jpg');
     });
@@ -629,8 +637,9 @@ describe('Avatar Component Core API', () => {
     it('should read src attribute as property', () => {
       const avatar = document.createElement('avatar-base') as AvatarBaseElement;
       avatar.setAttribute('src', 'https://example.com/img.png');
+      avatar.setAttribute('alt', 'Test avatar'); // honor the alt-with-src contract (Req 5.4)
       document.body.appendChild(avatar);
-      
+
       expect(avatar.src).toBe('https://example.com/img.png');
     });
 

package/src/components/core/Avatar-Base/avatar.tokens.ts

@@ -33,7 +33,16 @@
  * Icon Size Derivations (in Avatar.web.ts):
  * - 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.
@@ -56,13 +65,24 @@ import { defineComponentTokens } from '../../../build/tokens';
 import { SIZING_BASE_VALUE, sizingTokens } from '../../../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
  */
 export const AvatarSizingTokens = defineComponentTokens({
   component: 'Avatar',
@@ -92,38 +112,15 @@ export const AvatarSizingTokens = defineComponentTokens({
       reference: 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
- */
-export const AvatarTokens = 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: 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.',
@@ -273,7 +270,7 @@ export function getAvatarSize(variant: AvatarSizeVariant): number {
  * @see Requirements 3.1, 3.6 in .kiro/specs/042-avatar-component/requirements.md
  */
 export function getAvatarIconSize(variant: AvatarIconSizeVariant): number {
-  return AvatarTokens[`icon.size.${variant}`];
+  return AvatarSizingTokens[`icon.size.${variant}`];
 }
 
 /**

package/src/components/core/Avatar-Base/contracts.yaml

@@ -162,7 +162,17 @@ contracts:
       When not decorative, Avatar provides accessible name:
       - If alt prop provided: uses alt text
       - If no alt prop (iOS/Android): "User avatar" for human, "AI agent avatar" for agent
-      - Web requires alt prop when src is provided
+      - Web requires alt prop when src is provided, scoped to human type only
+        (agent type ignores src entirely — Req 5 AC 5) and only when decorative
+        is false (decorative is the component's own non-informative signal,
+        Req 9.2, and takes precedence over the alt requirement)
+      - Web edge semantics (settled Spec 126, O2, ratified 2026-07-09): the dev
+        warn fires iff `type === 'human' && src && alt == null && !decorative`.
+        A raw explicit empty alt (`setAttribute('alt', '')`) does not warn —
+        it is treated as the deliberate empty-alt signal. The `alt` property
+        setter collapses a falsy value (including '') to removeAttribute, so
+        setting `avatar.alt = ''` via the property lands in the "absent" bucket
+        and DOES warn — this is a setter-collapse detail, not a design gap.
     wcag: "1.1.1 Non-text Content"
     platforms: [web, ios, android]
     validation:

package/src/components/core/Avatar-Base/index.ts

@@ -11,7 +11,7 @@ export { AVATAR_DEFAULTS } from './types';
 
 // Token exports
 export {
-  AvatarTokens,
+  AvatarSizingTokens,
   getAvatarSize,
   getAvatarIconSize,
   getAvatarSizeTokenReference,

package/src/components/core/Avatar-Base/platforms/web/Avatar.web.ts

@@ -700,12 +700,31 @@ export class AvatarBaseElement extends HTMLElement {
     // @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') {
+    // 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" prop is required when "src" is provided for accessibility. ' +
-        'Please add an alt attribute describing the image.'
+        '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.'
       );
     }
     

package/src/components/core/Badge-Count-Base/contracts.yaml

@@ -102,7 +102,7 @@ contracts:
       - No hover or press visual feedback
       - pointer-events: none (web)
       - No gesture handlers (native)
-    wcag: null
+    wcag: "N/A"  # legitimate-null: non-interactive negative guarantee, no positive WCAG SC (125-B 4.2)
     platforms: [web, ios, android]
     validation:
       - Badge cannot receive keyboard focus

package/src/components/core/Badge-Label-Base/contracts.yaml

@@ -77,7 +77,7 @@ contracts:
       - No hover or press visual feedback
       - pointer-events: none (web)
       - No gesture handlers (native)
-    wcag: null
+    wcag: "N/A"  # legitimate-null: non-interactive negative guarantee, no positive WCAG SC (125-B 4.2)
     platforms: [web, ios, android]
     validation:
       - Badge cannot receive keyboard focus

package/src/components/core/Button-CTA/Button-CTA.schema.yaml

@@ -90,20 +90,12 @@ properties:
       When true, text is truncated with ellipsis instead of wrapping.
       Default (false) allows text wrapping for accessibility and i18n support.
   
-  disabled:
-    type: boolean
-    required: false
-    default: false
-    description: |
-      When true, button is non-interactive with disabled visual styling.
-      Disabled buttons are not keyboard focusable and onPress is not called.
-  
   onPress:
     type: "() => void"
     required: true
     description: |
       Callback function invoked when button is clicked, tapped, or activated
-      via keyboard (Enter/Space). Not called when disabled.
+      via keyboard (Enter/Space).
   
   testID:
     type: string
@@ -153,7 +145,6 @@ tokens:
   blend:
     - blend.hoverDarker
     - blend.pressedDarker
-    - blend.disabledDesaturate
     - blend.iconLighter
   component:
     - buttonCTA.minWidth.small
@@ -247,11 +238,10 @@ accessibility:
     - "1.4.11 Non-text Contrast - Focus ring meets 3:1 contrast"
     - "2.1.1 Keyboard - Fully keyboard accessible (Tab, Enter, Space)"
     - "2.4.7 Focus Visible - Clear focus indicator with :focus-visible"
-    - "4.1.2 Name, Role, Value - Proper ARIA attributes and disabled state"
+    - "4.1.2 Name, Role, Value - Proper ARIA attributes"
     - "2.5.5 Target Size - Touch targets meet 44px minimum"
   aria_attributes:
     - role: button (implicit from semantic element)
-    - aria-disabled: true when disabled
     - aria-label: label prop value
   keyboard_navigation:
     - Tab: Move focus to/from button

package/src/components/core/Button-CTA/README.md

@@ -41,10 +41,11 @@ This component guarantees 7 behavioral contracts across all platforms:
 | `pressable` | Responds to press/click events | web, ios, android | 2.1.1 |
 | `hover_state` | Visual feedback on hover | web | 1.4.13 |
 | `pressed_state` | Visual feedback when pressed | web, ios, android | 2.4.7 |
-| `disabled_state` | Prevents interaction when disabled | web, ios, android | 4.1.2 |
 | `loading_state` | Shows loading indicator | web, ios, android | 4.1.3 |
 | `focus_ring` | WCAG 2.4.7 focus visible indicator | web, ios, android | 2.4.7 |
 
+**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).
+
 ---
 
 ## Usage
@@ -62,7 +63,6 @@ This component guarantees 7 behavioral contracts across all platforms:
   variant="primary"
   icon="arrow-right"
   no-wrap="false"
-  disabled="false"
   test-id="submit-button"
 ></button-cta>
 ```
@@ -122,7 +122,6 @@ ButtonCTA(
 | `variant` | `'primary' \| 'secondary' \| 'tertiary'` | No | `'primary'` | Button visual variant |
 | `icon` | `IconName` | No | - | Optional leading icon |
 | `noWrap` | `boolean` | No | `false` | Prevent text wrapping |
-| `disabled` | `boolean` | No | `false` | Disable button interaction |
 | `onPress` | `() => void` | ✅ Yes | - | Press/click handler |
 | `testID` | `string` | No | - | Test identifier |
 
@@ -177,7 +176,6 @@ ButtonCTA(
 ### Blend
 - `blend.hoverDarker` - Hover state (8% darker)
 - `blend.pressedDarker` - Pressed state (12% darker)
-- `blend.disabledDesaturate` - Disabled state (12% less saturated)
 - `blend.iconLighter` - Icon optical balance (8% lighter)
 
 ### Accessibility
@@ -205,7 +203,7 @@ ButtonCTA(
 | 2.1.1 Keyboard | ✅ | Fully keyboard accessible (Tab, Enter, Space) |
 | 2.4.7 Focus Visible | ✅ | Clear focus indicator with :focus-visible |
 | 2.5.5 Target Size | ✅ | Touch targets meet 44px minimum |
-| 4.1.2 Name, Role, Value | ✅ | Proper ARIA attributes and disabled state |
+| 4.1.2 Name, Role, Value | ✅ | Proper ARIA attributes |
 
 ### Keyboard Navigation
 
@@ -219,7 +217,6 @@ ButtonCTA(
 
 - Semantic `<button>` element provides implicit role
 - `aria-label` set from label prop
-- `aria-disabled="true"` when disabled
 - State changes announced to assistive technology
 
 ---