@astryxdesign/core 0.2.0 → 0.3.0

package/src/Chat/ChatSendButton.tsx

@@ -20,7 +20,7 @@
 import React, {type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {Button} from '../Button';
-import {getIcon} from '../Icon/globalIconRegistry';
+import {useIcon} from '../Icon';
 import {useChatComposerContext} from './ChatContext';
 
 import type {BaseProps} from '../BaseProps';
@@ -95,6 +95,8 @@ export function ChatSendButton(props: ChatSendButtonProps): ReactNode {
   } = props;
 
   const handleSend = onSend ?? (() => context?.onSubmit(''));
+  const defaultStopIcon = useIcon('stop');
+  const defaultSendIcon = useIcon('arrowUp');
 
   return (
     <Button
@@ -108,8 +110,8 @@ export function ChatSendButton(props: ChatSendButtonProps): ReactNode {
       size={size}
       icon={
         isStopShown
-          ? (stopIcon ?? getIcon('stop'))
-          : (sendIcon ?? getIcon('arrowUp'))
+          ? (stopIcon ?? defaultStopIcon)
+          : (sendIcon ?? defaultSendIcon)
       }
       isIconOnly
       isDisabled={!isStopShown && isDisabled}

package/src/Chat/ChatSystemMessage.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: 'ChatSystemMessage',

package/src/Chat/ChatSystemMessage.tsx

@@ -16,7 +16,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Chat/index.ts (exports)
  * - /apps/storybook/stories/Chat.stories.tsx
- * - /packages/cli/templates/blocks/components/ChatSystemMessage/ (block examples)
+ * - /packages/cli/assets/templates/blocks/components/ChatSystemMessage/ (block examples)
  */
 
 import type {ReactNode} from 'react';

package/src/Chat/ChatTokenizedText.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: 'ChatTokenizedText',

package/src/Chat/ChatTokenizedText.tsx

@@ -14,7 +14,7 @@
  *
  * SYNC: When modified, update:
  * - /packages/core/src/Chat/index.ts
- * - /packages/cli/templates/blocks/components/ChatTokenizedText/ (block examples)
+ * - /packages/cli/assets/templates/blocks/components/ChatTokenizedText/ (block examples)
  */
 
 import React, {type ReactNode} from 'react';

package/src/Chat/ChatToolCalls.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: 'ChatToolCalls',
@@ -73,7 +73,7 @@ export const docs = {
   ],
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
     description:
@@ -97,7 +97,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'tool/function call display from LLM response; single=inline, multiple=collapsible summary w/ latest at surface',
   usage: {

package/src/CheckboxInput/CheckboxInput.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: 'CheckboxInput',
@@ -153,7 +153,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'CheckboxInput',
   displayName: 'Checkbox Input',
@@ -211,7 +211,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'single on/off toggle for settings, terms, and opt-in choices',
   usage: {

package/src/CheckboxInput/CheckboxInput.test.tsx

@@ -13,6 +13,7 @@ import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {CheckboxInput} from './CheckboxInput';
+import {getForcedColorsRules} from '../__tests__/forcedColors';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 
 afterEach(() => {
@@ -143,6 +144,39 @@ describe('CheckboxInput', () => {
     expect(checkbox).toHaveAttribute('aria-describedby', description.id);
   });
 
+  it('toggles when clicking on the description', async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+    render(
+      <CheckboxInput
+        label="Subscribe"
+        description="Receive weekly updates"
+        value={false}
+        onChange={handleChange}
+      />,
+    );
+    await user.click(screen.getByText('Receive weekly updates'));
+    expect(handleChange).toHaveBeenCalledWith(true, expect.any(Object));
+  });
+
+  it('does not fold the description into the checkbox accessible name', () => {
+    // The description stays a sibling of the <label>, so it must NOT become
+    // part of the checkbox's accessible name (which is computed from the
+    // associated label). It belongs in the accessible DESCRIPTION only
+    // (via aria-describedby) — otherwise screen readers announce it twice.
+    render(
+      <CheckboxInput
+        label="Email notifications"
+        description="We'll send weekly digests"
+        value={false}
+        onChange={() => {}}
+      />,
+    );
+    const checkbox = screen.getByRole('checkbox');
+    expect(checkbox).toHaveAccessibleName('Email notifications');
+    expect(checkbox).toHaveAccessibleDescription("We'll send weekly digests");
+  });
+
   it('is disabled when isDisabled prop is true', () => {
     render(
       <CheckboxInput
@@ -543,3 +577,25 @@ describe('CheckboxInput', () => {
     });
   });
 });
+
+// jsdom cannot emulate forced-colors rendering, so this asserts that the
+// compiled output includes the forced-colors rule; visual behavior needs
+// manual verification under Windows High Contrast.
+describe('forced colors (WCAG 1.4.11)', () => {
+  it('compiles a forced-colors fill so the indeterminate mark survives Windows High Contrast', () => {
+    render(
+      <CheckboxInput label="All" value="indeterminate" onChange={() => {}} />,
+    );
+    // The painted indeterminate bar would be stripped to Canvas (invisible);
+    // CanvasText keeps it perceivable.
+    expect(getForcedColorsRules()).toContain('background-color: canvastext;');
+  });
+
+  it('compiles a forced-colors color so the checkmark survives Windows High Contrast', () => {
+    render(<CheckboxInput label="Accept" value={true} onChange={() => {}} />);
+    // The check strokes with currentColor; forced colors leaves it the same
+    // white as the flattened box, so it needs its own CanvasText color to stay
+    // perceivable on the Canvas box.
+    expect(getForcedColorsRules()).toContain('color: canvastext;');
+  });
+});

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: {

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',
@@ -121,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.',
@@ -136,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',
@@ -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.',

package/src/Citation/Citation.tsx

@@ -13,7 +13,7 @@
  * - /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/templates/blocks/components/Citation/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Citation/ (showcase blocks)
  */
 
 import type React from 'react';

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 {

package/src/CodeBlock/CodeBlock.tsx

@@ -786,7 +786,7 @@ export function CodeBlock({
       setCopied(true);
       // Swapping the button's aria-label alone isn't reliably announced by
       // screen readers, so confirm the copy via a polite live region.
-      announce('Copied');
+      announce(t('@astryx.codeBlock.copied'));
       onCopy?.();
       // Restart the reset timer on every copy — otherwise a rapid re-copy
       // is reverted early by the previous click's timer.
@@ -800,7 +800,7 @@ export function CodeBlock({
     } catch {
       // Clipboard failures leave the copied state unchanged.
     }
-  }, [code, onCopy, announce]);
+  }, [code, onCopy, announce, t]);
 
   const sizeStyle = size === 'sm' ? styles.sizeSm : styles.sizeMd;
   // Digits in the largest line number — sizes the gutter column width.

package/src/Collapsible/Collapsible.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: 'Collapsible',
@@ -95,7 +95,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
     description: 'Collapsible hides and reveals content behind a trigger button. Use it in settings panels, FAQ pages, or detail views to keep the page scannable while letting users drill into sections they care about. Wrap multiple collapsibles in CollapsibleGroup for accordion behavior.',
@@ -112,7 +112,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'hide/reveal content behind a trigger; group for accordion behavior',
   usage: {