@astryxdesign/core 0.1.9 → 0.2.0-canary.0b7a99e

package/src/CheckboxInput/CheckboxInput.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/CheckboxInput/CheckboxInput.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/CheckboxInput/index.ts (exports if types change)
  * - /apps/storybook/stories/CheckboxInput.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/CheckboxInput/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/CheckboxInput/ (showcase blocks)
  */
 
 import {
@@ -158,14 +158,29 @@ const styles = stylex.create({
   },
   checkmark: {
     display: 'none',
-    color: colorVars['--color-on-accent'],
+    color: {
+      default: colorVars['--color-on-accent'],
+      // Forced colors (Windows High Contrast) does not reliably force an SVG
+      // stroke painted with currentColor, so the check stays the same white as
+      // the flattened (Canvas) box fill — a white check on a white box.
+      // CanvasText keeps it perceivable on the Canvas box, matching the
+      // indeterminate mark (WCAG 1.4.11).
+      '@media (forced-colors: active)': 'CanvasText',
+    },
   },
   checkmarkVisible: {
     display: 'block',
   },
   indeterminateMark: {
     display: 'none',
-    backgroundColor: colorVars['--color-on-accent'],
+    backgroundColor: {
+      default: colorVars['--color-on-accent'],
+      // Forced colors (Windows High Contrast) strips painted backgrounds,
+      // which would make the indeterminate bar invisible; CanvasText keeps it
+      // perceivable on the Canvas box fill (WCAG 1.4.11). The checkmark carries
+      // the matching CanvasText treatment on its own style.
+      '@media (forced-colors: active)': 'CanvasText',
+    },
     borderRadius: radiusVars['--radius-full'],
   },
   indeterminateMarkVisible: {
@@ -198,12 +213,12 @@ const wrapperSizeStyles = stylex.create({
 
 const checkboxSizeStyles = stylex.create({
   sm: {
-    width: 18,
-    height: 18,
+    width: 20,
+    height: 20,
   },
   md: {
-    width: 22,
-    height: 22,
+    width: 24,
+    height: 24,
   },
 });
 

package/src/CheckboxList/CheckboxList.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'CheckboxList',
@@ -88,6 +88,12 @@ export const docs = {
       type: "{type: 'warning' | 'error' | 'success', message?: string}",
       description: 'Status indicator ({ type, message }).',
     },
+    {
+      name: 'width',
+      type: 'SizeValue',
+      description:
+        'Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned.',
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',
@@ -115,7 +121,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
     description: 'CheckboxList shows a small group of checkboxes so users can turn several options on or off at once. Place it in settings pages, filter panels, or forms where every choice should be visible without scrolling. For a single standalone checkbox (like "I agree to the terms"), use CheckboxInput instead. If only one option can be picked, use RadioList. If the list is long enough to need searching or scrolling, use MultiSelector instead.',
@@ -130,7 +136,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Checkbox group component for multi-value selection. Collection mode (parent state) + standalone mode (per-item state).',

package/src/CheckboxList/CheckboxList.test.tsx

@@ -154,14 +154,105 @@ describe('CheckboxList', () => {
       </CheckboxList>,
     );
 
-    // Click the interactive row (invisible-button pattern), which is where the
-    // composed onClick lives — not the inner checkbox.
-    await user.click(screen.getByRole('button', {name: 'Option B'}));
+    // The row is a pointer-only click surface (no invisible row button — the
+    // checkbox is the option's only tab stop). Click the row's label area,
+    // where the composed onClick fires — not the inner checkbox.
+    expect(
+      screen.queryByRole('button', {name: 'Option B'}),
+    ).not.toBeInTheDocument();
+    // The text also exists in the checkbox's visually hidden <label>; target
+    // the row's label <span> to click the row surface.
+    await user.click(screen.getByText('Option B', {selector: 'span'}));
 
     expect(handleClick).toHaveBeenCalledTimes(1);
     expect(handleChange).toHaveBeenCalledWith(['a', 'b']);
   });
 
+  describe('single tab stop per option (WCAG 4.1.2 / APG checkbox pattern)', () => {
+    it('renders exactly one focusable control per option — the checkbox, no row button', () => {
+      render(
+        <CheckboxList label="Preferences" value={['a']} onChange={() => {}}>
+          <CheckboxListItem label="Option A" value="a" />
+          <CheckboxListItem label="Option B" value="b" />
+        </CheckboxList>,
+      );
+      // No invisible whole-row button duplicating the checkbox's action.
+      expect(screen.queryByRole('button')).not.toBeInTheDocument();
+      for (const item of screen.getAllByRole('listitem')) {
+        const focusables = item.querySelectorAll(
+          'button, a[href], input, select, textarea, [tabindex]:not([tabindex="-1"])',
+        );
+        expect(focusables).toHaveLength(1);
+        expect(focusables[0]).toBe(within(item).getByRole('checkbox'));
+      }
+    });
+
+    it('Tab moves directly from one option checkbox to the next', async () => {
+      const user = userEvent.setup();
+      render(
+        <CheckboxList label="Preferences" value={[]} onChange={() => {}}>
+          <CheckboxListItem label="Option A" value="a" />
+          <CheckboxListItem label="Option B" value="b" />
+        </CheckboxList>,
+      );
+      await user.tab();
+      expect(screen.getByRole('checkbox', {name: 'Option A'})).toHaveFocus();
+      await user.tab();
+      expect(screen.getByRole('checkbox', {name: 'Option B'})).toHaveFocus();
+      // No further tab stop inside the list (the row itself is not focusable).
+      await user.tab();
+      expect(document.body).toHaveFocus();
+    });
+
+    it('clicking the row surface (outside the checkbox) still toggles', async () => {
+      const user = userEvent.setup();
+      const handleChange = vi.fn();
+      render(
+        <CheckboxList label="Preferences" value={['a']} onChange={handleChange}>
+          <CheckboxListItem label="Option A" value="a" />
+          <CheckboxListItem label="Option B" value="b" />
+        </CheckboxList>,
+      );
+      // The text also exists in the checkbox's visually hidden <label>;
+      // target the row's label <span> to click the row surface.
+      await user.click(screen.getByText('Option B', {selector: 'span'}));
+      expect(handleChange).toHaveBeenCalledTimes(1);
+      expect(handleChange).toHaveBeenCalledWith(['a', 'b']);
+    });
+
+    it('toggles with Space on the focused checkbox, which reports checked state', async () => {
+      const user = userEvent.setup();
+      const handleChange = vi.fn();
+      render(
+        <CheckboxList label="Preferences" value={['a']} onChange={handleChange}>
+          <CheckboxListItem label="Option A" value="a" />
+          <CheckboxListItem label="Option B" value="b" />
+        </CheckboxList>,
+      );
+      await user.tab();
+      // The focused control is the checkbox itself, so its accessible name
+      // and checked state are what assistive tech announces on focus.
+      const checkboxA = screen.getByRole('checkbox', {name: 'Option A'});
+      expect(checkboxA).toHaveFocus();
+      expect(checkboxA).toBeChecked();
+      await user.keyboard(' ');
+      expect(handleChange).toHaveBeenCalledTimes(1);
+      expect(handleChange).toHaveBeenCalledWith([]);
+    });
+
+    it('the row itself is not focusable', () => {
+      render(
+        <CheckboxList label="Preferences" value={[]} onChange={() => {}}>
+          <CheckboxListItem label="Option A" value="a" />
+        </CheckboxList>,
+      );
+      const item = screen.getByRole('listitem');
+      expect(item).not.toHaveAttribute('tabindex');
+      item.focus();
+      expect(item).not.toHaveFocus();
+    });
+  });
+
   it('disables all checkboxes when group isDisabled is true', () => {
     render(
       <CheckboxList

package/src/CheckboxList/CheckboxList.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/CheckboxList/CheckboxList.test.tsx
  * - /packages/core/src/CheckboxList/index.ts
  * - /apps/storybook/stories/CheckboxList.stories.tsx
- * - /packages/cli/templates/blocks/components/CheckboxList/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/CheckboxList/ (showcase blocks)
  */
 
 import {

package/src/CheckboxList/CheckboxListItem.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'CheckboxListItem',

package/src/CheckboxList/CheckboxListItem.tsx

@@ -13,15 +13,14 @@
  * - /packages/core/src/CheckboxList/CheckboxList.test.tsx
  * - /packages/core/src/CheckboxList/index.ts
  * - /apps/storybook/stories/CheckboxList.stories.tsx
- * - /packages/cli/templates/blocks/components/CheckboxList/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/CheckboxList/ (showcase blocks)
  */
 
-import {use, type MouseEvent, type ReactNode} from 'react';
+import {use, useRef, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {StyleXStyles} from '@stylexjs/stylex';
 import {colorVars} from '../theme/tokens.stylex';
 import type {BaseProps} from '../BaseProps';
-import {composeEventHandlers} from '../utils';
 import {useDevWarning} from '../hooks/useDevWarning';
 import {CheckboxInput} from '../CheckboxInput/CheckboxInput';
 import {ListItem} from '../List/ListItem';
@@ -212,6 +211,14 @@ export function CheckboxListItem({
   // Whether this item is interactive (has a toggle handler)
   const isInteractive = !effectiveReadOnly && (ctx != null || onCheck != null);
 
+  // The checkbox is the row's single keyboard control and action. The row is
+  // an enlarged click/tap target that delegates surface clicks to it via
+  // ListItem's `interactiveRef` (useClickableContainer), so each option is
+  // exactly one tab stop. Delegate whenever the row should respond to clicks:
+  // a toggleable item, or one carrying a consumer `onClick`.
+  const checkboxRef = useRef<HTMLInputElement | null>(null);
+  const hasRowInteraction = isInteractive || onClickProp != null;
+
   const handleToggle = () => {
     if (effectiveDisabled || effectiveReadOnly || isBusy) {
       return;
@@ -244,14 +251,12 @@ export function CheckboxListItem({
       description={description}
       endContent={endContent}
       isDisabled={effectiveDisabled}
-      onClick={
-        isInteractive || onClickProp
-          ? composeEventHandlers<MouseEvent>(
-              onClickProp as ((event: MouseEvent) => void) | undefined,
-              isInteractive ? handleToggle : undefined,
-            )
-          : undefined
-      }
+      // Delegate row clicks to the checkbox instead of wiring onClick (which
+      // would add an invisible row button = a second tab stop). The checkbox
+      // stays the option's sole focusable control (WCAG 4.1.2 / APG checkbox
+      // pattern). A consumer onClick rides on the checkbox itself (below), so
+      // it still fires for both direct and delegated (row-surface) clicks.
+      interactiveRef={hasRowInteraction ? checkboxRef : undefined}
       aria-busy={isBusy || undefined}
       xstyle={
         [
@@ -266,10 +271,12 @@ export function CheckboxListItem({
       style={style}
       startContent={
         <CheckboxInput
+          ref={checkboxRef}
           label={checkboxLabel}
           isLabelHidden
           value={resolvedChecked}
           onChange={() => handleToggle()}
+          onClick={onClickProp}
           isDisabled={effectiveDisabled}
           isReadOnly={effectiveReadOnly}
           isLoading={isBusy}

package/src/Citation/Citation.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'Citation',
@@ -39,7 +39,7 @@ export const docs = {
         name: 'Icon',
         required: false,
         description:
-          'An optional favicon or source icon displayed before the label text. Only available in the label variant.',
+          'An optional source icon shown before the label text. Accepts a favicon/logo image URL (via source.src) or a React node such as an Astryx <Icon>. Only available in the label variant.',
       },
       {
         name: 'Label text',
@@ -71,7 +71,7 @@ export const docs = {
       name: 'source',
       type: 'CitationSource',
       description:
-        'The citation source object containing title, url, and optional icon.',
+        'The citation source object containing title, url, an optional image src, and an optional icon node.',
       required: true,
     },
     {
@@ -95,7 +95,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Inline reference to external source. Attribute info in AI responses, articles, or anywhere provenance needed.',
@@ -121,7 +121,8 @@ export const docsDense = {
     ],
   },
   propDescriptions: {
-    source: 'citation source object with title, url, optional icon.',
+    source:
+      'citation source object with title, url, optional image src, and optional icon node.',
     number: 'display index for this citation.',
     variant: 'display style: label chip with source title or compact numbered badge.',
   },

package/src/Citation/Citation.test.tsx

@@ -169,4 +169,101 @@ describe('Citation', () => {
       expect(el.classList.contains(cls)).toBe(true);
     }
   });
+
+  // --- Source icon: image URL (back-compat) vs ReactNode ---------------------
+
+  it('renders a legacy string icon as a decorative image (back-compat)', () => {
+    // Existing callers pass a favicon URL to `source.icon`. A bare string must
+    // still render as <img src>, unchanged from the original behavior.
+    const {container} = render(
+      <Citation
+        source={{
+          title: 'GitHub',
+          url: 'https://github.com',
+          icon: 'https://example.com/favicon.png',
+        }}
+        number={1}
+        data-testid="citation"
+      />,
+    );
+    const img = container.querySelector('img');
+    expect(img).not.toBeNull();
+    expect(img).toHaveAttribute('src', 'https://example.com/favicon.png');
+    // Decorative: empty alt, and the wrapper is aria-hidden.
+    expect(img).toHaveAttribute('alt', '');
+    expect(container.querySelector('[aria-hidden="true"] img')).toBe(img);
+  });
+
+  it('renders source.src as a decorative image', () => {
+    const {container} = render(
+      <Citation
+        source={{
+          title: 'GitHub',
+          url: 'https://github.com',
+          src: 'https://example.com/logo.png',
+        }}
+        number={1}
+        data-testid="citation"
+      />,
+    );
+    const img = container.querySelector('img');
+    expect(img).toHaveAttribute('src', 'https://example.com/logo.png');
+    expect(img).toHaveAttribute('alt', '');
+  });
+
+  it('renders a ReactNode icon as-is (not an <img>)', () => {
+    const {container} = render(
+      <Citation
+        source={{
+          title: 'GitHub',
+          url: 'https://github.com',
+          icon: <svg data-testid="custom-icon" />,
+        }}
+        number={1}
+        data-testid="citation"
+      />,
+    );
+    // The node renders directly; no <img> is produced for a node icon.
+    expect(container.querySelector('img')).toBeNull();
+    expect(screen.getByTestId('custom-icon')).toBeInTheDocument();
+    // Still decorative — wrapped in an aria-hidden container.
+    expect(
+      container.querySelector(
+        '[aria-hidden="true"] [data-testid="custom-icon"]',
+      ),
+    ).not.toBeNull();
+  });
+
+  it('prefers a node icon over src when both are provided', () => {
+    const {container} = render(
+      <Citation
+        source={{
+          title: 'GitHub',
+          url: 'https://github.com',
+          src: 'https://example.com/logo.png',
+          icon: <svg data-testid="custom-icon" />,
+        }}
+        number={1}
+        data-testid="citation"
+      />,
+    );
+    expect(screen.getByTestId('custom-icon')).toBeInTheDocument();
+    expect(container.querySelector('img')).toBeNull();
+  });
+
+  it('keeps aria-label as the sole accessible name when an icon is present', () => {
+    render(
+      <Citation
+        source={{
+          title: 'GitHub',
+          url: 'https://github.com',
+          icon: 'https://example.com/favicon.png',
+        }}
+        number={2}
+        data-testid="citation"
+      />,
+    );
+    const el = screen.getByTestId('citation');
+    expect(el).toHaveAttribute('aria-label', 'Citation 2: GitHub');
+  });
 });

package/src/Citation/Citation.tsx

@@ -10,10 +10,14 @@
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Citation/index.ts (exports if types change)
- * - /packages/cli/templates/blocks/components/Citation/ (showcase blocks)
+ * - /packages/core/src/Citation/Citation.doc.mjs (props table, features)
+ * - /packages/core/src/Citation/Citation.test.tsx (tests for new/changed behavior)
+ * - /apps/storybook/stories/Citation.stories.tsx (storybook stories)
+ * - /packages/cli/assets/templates/blocks/components/Citation/ (showcase blocks)
  */
 
 import type React from 'react';
+import type {ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {
   colorVars,
@@ -29,11 +33,29 @@ import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
+import {renderIconSlot} from '../Icon';
 
 export interface CitationSource {
   title?: string;
   url?: string;
-  icon?: string;
+  /**
+   * Image URL for a favicon or source logo, rendered as `<img src>` inside the
+   * icon circle. This is the idiomatic field for image sources (mirrors
+   * `Avatar`/`Thumbnail` `src`). When both `src` and a non-string `icon` are
+   * provided, `icon` wins.
+   */
+  src?: string;
+  /**
+   * Source icon shown before the label text (label variant only). Accepts:
+   * - a React node / Astryx `<Icon>` / SVG element — rendered as-is, or
+   * - a string image URL — rendered as `<img src>` for backward compatibility
+   *   with callers that passed a favicon URL here.
+   *
+   * Note: unlike icon slots elsewhere in the system, a bare string is treated
+   * as an image URL (not a semantic icon name) to preserve the original
+   * favicon behavior. Pass an Astryx `<Icon>` (or other node) for a real icon.
+   */
+  icon?: ReactNode;
 }
 
 export interface CitationProps extends BaseProps<HTMLElement> {
@@ -162,7 +184,18 @@ export function Citation({
   const t = useTranslator();
   const title = source.title ?? String(number);
   const href = source.url;
-  const icon = source.icon;
+
+  // Resolve the source icon. A non-string `icon` node renders as-is (an Astryx
+  // <Icon>, SVG, avatar, etc.). Otherwise fall back to an image URL: `src`, or
+  // a legacy string passed to `icon` (back-compat — favicon URLs still render
+  // as <img>). The icon is decorative; the accessible name comes solely from
+  // the element's aria-label, so nothing is double-announced.
+  const iconNode =
+    source.icon != null && typeof source.icon !== 'string' ? source.icon : null;
+  const imageSrc =
+    source.src ?? (typeof source.icon === 'string' ? source.icon : undefined);
+  const hasIcon = iconNode != null || imageSrc != null;
+
   const Tag = href ? 'a' : 'span';
   // `doc-noteref` is a reference role — only appropriate on the interactive
   // link form. On a plain (unlinked) span it is not a permitted role
@@ -218,7 +251,7 @@ export function Citation({
         themeProps('citation', {variant}),
         stylex.props(
           styles.label,
-          icon != null && styles.labelWithIcon,
+          hasIcon && styles.labelWithIcon,
           href != null && styles.labelHover,
           href != null && styles.labelInteractive,
           xstyle,
@@ -226,14 +259,13 @@ export function Citation({
         className,
         style,
       )}>
-      {icon && (
-        <span {...stylex.props(styles.iconWrap)}>
-          <img
-            src={icon}
-            alt=""
-            aria-hidden="true"
-            {...stylex.props(styles.icon)}
-          />
+      {hasIcon && (
+        <span aria-hidden="true" {...stylex.props(styles.iconWrap)}>
+          {iconNode != null ? (
+            renderIconSlot(iconNode, {size: 'sm'})
+          ) : (
+            <img src={imageSrc} alt="" {...stylex.props(styles.icon)} />
+          )}
         </span>
       )}
       <span {...stylex.props(styles.labelText)}>{title}</span>

package/src/ClickableCard/ClickableCard.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docs = {
   name: 'ClickableCard',
   displayName: 'Clickable Card',
@@ -55,7 +55,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'Interactive card for navigation/action targets. Nested interactive elements work independently.',
   usage: {

package/src/ClickableCard/ClickableCard.tsx

@@ -12,9 +12,9 @@
  * - /packages/core/src/ClickableCard/ClickableCard.doc.mjs (props table, features)
  * - /packages/core/src/ClickableCard/index.ts (exports if types change)
  * - /apps/storybook/stories/ClickableCard.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/Card/ClickableCardShowcase.tsx (showcase block)
- * - /packages/cli/templates/blocks/components/Card/ClickableCardWithNestedButton.tsx (block)
- * - /packages/cli/templates/blocks/components/Card/ClickableCardElevated.tsx (block)
+ * - /packages/cli/assets/templates/blocks/components/Card/ClickableCardShowcase.tsx (showcase block)
+ * - /packages/cli/assets/templates/blocks/components/Card/ClickableCardWithNestedButton.tsx (block)
+ * - /packages/cli/assets/templates/blocks/components/Card/ClickableCardElevated.tsx (block)
  *
  * Composes Card for all visual styling (radius, padding, variants,
  * container tokens, theming). Adds an interactive wrapper with

package/src/Code/Code.tsx

@@ -10,8 +10,8 @@
  *
  * SYNC: When modified, update:
  * - /packages/core/src/CodeBlock/index.ts (exports if types change)
- * - /packages/cli/templates/blocks/components/Code/ (showcase blocks)
- * - /packages/cli/templates/blocks/components/CodeBlock/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Code/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/CodeBlock/ (showcase blocks)
  */
 
 import type {ReactNode} from 'react';

package/src/CodeBlock/Code.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'Code',

package/src/CodeBlock/CodeBlock.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docs = {
   name: 'CodeBlock',
   displayName: 'Code Block',
@@ -163,7 +163,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
     description: 'CodeBlock displays syntax-highlighted code snippets with optional line numbers, copy button, and collapsible sections. Use CodeBlock for fenced multi-line code and Code for inline code within prose.',
@@ -176,7 +176,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'syntax-highlighted code block via CSS Custom Highlight API (0-DOM overhead); span-based fallback; Code for inline code in prose',
   usage: {

package/src/CodeBlock/CodeBlock.test.tsx

@@ -14,6 +14,7 @@ import {act, render, screen, fireEvent, waitFor} from '@testing-library/react';
 import {CodeBlock} from './CodeBlock';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 import {dracula} from '../theme/syntax';
+import {InternationalizationProvider} from '../i18n';
 
 function politeRegion(): HTMLElement | null {
   return document.querySelector('[data-astryx-live-region="polite"]');
@@ -72,6 +73,22 @@ describe('CodeBlock', () => {
     });
   });
 
+  it('localizes the copy announcement through the i18n catalog', async () => {
+    render(
+      <InternationalizationProvider
+        locale="fr"
+        overrides={{fr: {'@astryx.codeBlock.copied': 'Copié'}}}>
+        <CodeBlock code="const x = 1;" language="javascript" />
+      </InternationalizationProvider>,
+    );
+    // The button label and the live-region announcement share the same key.
+    fireEvent.click(screen.getByRole('button', {name: 'Copy code'}));
+    await waitFor(() => {
+      expect(politeRegion()).toHaveTextContent('Copié');
+    });
+    expect(screen.getByRole('button', {name: 'Copié'})).toBeInTheDocument();
+  });
+
   it('keeps the copied indicator a full 2s after a rapid re-copy', async () => {
     vi.useFakeTimers();
     try {