@astryxdesign/core 0.2.0 → 0.3.0-canary.0b5a38e

package/src/StatusDot/StatusDot.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: 'StatusDot',
@@ -49,15 +49,18 @@ export const docs = {
     description:
       'A small colored dot that communicates status like online/offline presence or severity levels. Supports five semantic variants and an optional pulse animation. Always pair with a visible text label, as color alone should not carry meaning.',
     bestPractices: [
+      { guidance: true, description: 'Use StatusDot as a binary present/absent signal; avoid encoding many distinct states in a single dot, since color and size alone cannot reliably distinguish them.' },
       { guidance: true, description: 'Always pair with a visible text label so status is not conveyed by color alone.' },
       { guidance: true, description: 'Provide a descriptive `label` prop for screen reader accessibility.' },
+      { guidance: true, description: 'Pair the dot with an icon that carries the status as a distinct shape when it must stand on its own without adjacent text, so meaning survives without color.' },
+      { guidance: true, description: 'If you can\'t add a label or an icon, make sure the status is conveyed elsewhere accessibly (e.g. adjacent text, a table column, or a live region).' },
+      { guidance: false, description: 'Rely on color alone to communicate status; StatusDot is not fully accessible in isolation, so the builder must make the status distinguishable in context via a label, an icon, or an accessible alternative.' },
       { guidance: false, description: 'Use the pulse animation for purely decorative purposes; reserve it for states that require immediate attention.' },
-      { guidance: false, description: 'Rely on color alone to communicate status; always include text.' },
     ],
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'StatusDot',
   displayName: 'Status Dot',
@@ -97,25 +100,31 @@ export const docsZh = {
     description:
       'A small colored dot that communicates status like online/offline presence or severity levels. Supports five semantic variants and an optional pulse animation. Always pair with a visible text label, as color alone should not carry meaning.',
     bestPractices: [
+      { guidance: true, description: 'Use StatusDot as a binary present/absent signal; avoid encoding many distinct states in a single dot, since color and size alone cannot reliably distinguish them.' },
       { guidance: true, description: 'Always pair with a visible text label so status is not conveyed by color alone.' },
       { guidance: true, description: 'Provide a descriptive `label` prop for screen reader accessibility.' },
+      { guidance: true, description: 'Pair the dot with an icon that carries the status as a distinct shape when it must stand on its own without adjacent text, so meaning survives without color.' },
+      { guidance: true, description: 'If you can\'t add a label or an icon, make sure the status is conveyed elsewhere accessibly (e.g. adjacent text, a table column, or a live region).' },
+      { guidance: false, description: 'Rely on color alone to communicate status; StatusDot is not fully accessible in isolation, so the builder must make the status distinguishable in context via a label, an icon, or an accessible alternative.' },
       { guidance: false, description: 'Use the pulse animation for purely decorative purposes; reserve it for states that require immediate attention.' },
-      { guidance: false, description: 'Rely on color alone to communicate status; always include text.' },
     ],
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'Small colored dot indicator for status display (online/offline, severity, etc).',
   usage: {
     description:
       'A small colored dot that communicates status like online/offline presence or severity levels. Supports five semantic variants and an optional pulse animation. Always pair with a visible text label, as color alone should not carry meaning.',
     bestPractices: [
+      { guidance: true, description: 'Use StatusDot as a binary present/absent signal; avoid encoding many distinct states in a single dot, since color and size alone cannot reliably distinguish them.' },
       { guidance: true, description: 'Always pair with a visible text label so status is not conveyed by color alone.' },
       { guidance: true, description: 'Provide a descriptive `label` prop for screen reader accessibility.' },
+      { guidance: true, description: 'Pair the dot with an icon that carries the status as a distinct shape when it must stand on its own without adjacent text, so meaning survives without color.' },
+      { guidance: true, description: 'If you can\'t add a label or an icon, make sure the status is conveyed elsewhere accessibly (e.g. adjacent text, a table column, or a live region).' },
+      { guidance: false, description: 'Rely on color alone to communicate status; StatusDot is not fully accessible in isolation, so the builder must make the status distinguishable in context via a label, an icon, or an accessible alternative.' },
       { guidance: false, description: 'Use the pulse animation for purely decorative purposes; reserve it for states that require immediate attention.' },
-      { guidance: false, description: 'Rely on color alone to communicate status; always include text.' },
     ],
   },
   propDescriptions: {

package/src/StatusDot/StatusDot.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/StatusDot/StatusDot.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/StatusDot/index.ts (exports if types change)
  * - /apps/storybook/stories/StatusDot.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/StatusDot/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/StatusDot/ (showcase blocks)
  */
 
 import * as stylex from '@stylexjs/stylex';
@@ -22,6 +22,7 @@ import type {BaseProps} from '../BaseProps';
 import {Tooltip} from '../Tooltip/Tooltip';
 import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
+import type {StatusDotVariantMap} from './index';
 
 /**
  * Pulse animation keyframes
@@ -77,27 +78,6 @@ const variants = stylex.create({
   },
 });
 
-/**
- * Extensible variant map for StatusDot.
- *
- * Theme packages can add custom variants via TypeScript module augmentation:
- * @example
- * ```
- * declare module '@astryxdesign/core/StatusDot' {
- *   interface StatusDotVariantMap {
- *     'critical': true;
- *   }
- * }
- * ```
- */
-export interface StatusDotVariantMap {
-  success: true;
-  warning: true;
-  error: true;
-  accent: true;
-  neutral: true;
-}
-
 /**
  * Status dot variant type derived from StatusDotVariantMap.
  * Extensible via module augmentation of StatusDotVariantMap.

package/src/StatusDot/index.ts

@@ -9,9 +9,26 @@
  * @position Entry point for StatusDot; re-exported by /packages/core/src/index.ts
  */
 
+/**
+ * Extensible variant map for StatusDot.
+ *
+ * Theme packages can add custom variants via TypeScript module augmentation:
+ * @example
+ * ```
+ * declare module '@astryxdesign/core/StatusDot' {
+ *   interface StatusDotVariantMap {
+ *     'critical': true;
+ *   }
+ * }
+ * ```
+ */
+export interface StatusDotVariantMap {
+  success: true;
+  warning: true;
+  error: true;
+  accent: true;
+  neutral: true;
+}
+
 export {StatusDot} from './StatusDot';
-export type {
-  StatusDotProps,
-  StatusDotVariant,
-  StatusDotVariantMap,
-} from './StatusDot';
+export type {StatusDotProps, StatusDotVariant} from './StatusDot';

package/src/Switch/Switch.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: 'Switch',
@@ -141,7 +141,7 @@ export const docs = {
       name: 'labelSpacing',
       type: "'hug' | 'spread'",
       description:
-        'Spacing behavior between label and switch. "hug" places them next to each other; "spread" pushes them to opposite ends of the container (full width). "default" is a deprecated alias for "hug".',
+        'Spacing behavior between label and switch. "hug" places them next to each other; "spread" pushes them to opposite ends of the container (full width).',
       default: "'hug'",
     },
     {
@@ -202,7 +202,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'Switch',
   displayName: 'Switch',
@@ -373,7 +373,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'Toggle switch for boolean values w/ integrated label support.',
   usage: {
@@ -429,6 +429,6 @@ export const docsDense = {
     labelTooltip: 'Tooltip text in info icon at label end.',
     labelPosition: 'Which side label appears; "start" places before switch.',
     labelSpacing:
-      'Spacing behavior; "hug" places next to each other, "spread" pushes to opposite ends (full width). "default" is deprecated alias for "hug".',
+      'Spacing behavior; "hug" places next to each other, "spread" pushes to opposite ends (full width).',
   },
 };

package/src/Switch/Switch.test.tsx

@@ -13,6 +13,10 @@ 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 {Switch} from './Switch';
+import {
+  getAllInjectedCss,
+  getForcedColorsRules,
+} from '../__tests__/forcedColors';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 
 afterEach(() => {
@@ -167,6 +171,40 @@ describe('Switch', () => {
     expect(switchEl).toHaveAttribute('aria-describedby', description.id);
   });
 
+  it('toggles when clicking on the description', async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+    render(
+      <Switch
+        label="Dark mode"
+        description="Switch to a darker color scheme"
+        value={false}
+        onChange={handleChange}
+      />,
+    );
+    await user.click(screen.getByText('Switch to a darker color scheme'));
+    expect(handleChange).toHaveBeenCalledWith(true, expect.any(Object));
+  });
+
+  it('does not fold the description into the switch accessible name', () => {
+    // Description stays a sibling of the <label>, so it must not become part
+    // of the switch's accessible name — it belongs in the accessible
+    // description (aria-describedby) only, to avoid double announcement.
+    render(
+      <Switch
+        label="Dark mode"
+        description="Switch to a darker color scheme"
+        value={false}
+        onChange={() => {}}
+      />,
+    );
+    const switchEl = screen.getByRole('switch');
+    expect(switchEl).toHaveAccessibleName('Dark mode');
+    expect(switchEl).toHaveAccessibleDescription(
+      'Switch to a darker color scheme',
+    );
+  });
+
   it('is disabled when isDisabled prop is true', () => {
     render(
       <Switch
@@ -581,31 +619,6 @@ describe('Switch', () => {
       expect(getField(explicit)).not.toHaveAttribute('data-label-spacing');
       expect(getField(explicit).className).toBe(getField(implicit).className);
     });
-
-    it("treats the deprecated 'default' value as an alias for hug", () => {
-      const {container: hug} = render(
-        <Switch
-          label="Notify"
-          value={false}
-          onChange={() => {}}
-          labelSpacing="hug"
-        />,
-      );
-      const {container: deprecated} = render(
-        <Switch
-          label="Notify"
-          value={false}
-          onChange={() => {}}
-          labelSpacing="default"
-        />,
-      );
-      expect(getField(deprecated)).not.toHaveAttribute('data-label-spacing');
-      expect(getField(deprecated).className).toBe(getField(hug).className);
-      // The switch row keeps the hug layout, not the spread justification.
-      expect(getField(deprecated).firstElementChild?.className).toBe(
-        getField(hug).firstElementChild?.className,
-      );
-    });
   });
   describe('form participation', () => {
     it('submits under htmlName when on', () => {
@@ -729,3 +742,36 @@ describe('Switch', () => {
     });
   });
 });
+
+// jsdom cannot emulate forced-colors rendering, so these assert that the
+// compiled output includes the forced-colors rules; visual behavior needs
+// manual verification under Windows High Contrast.
+describe('forced colors (WCAG 1.4.11)', () => {
+  it('compiles forced-colors overrides so on/off state survives Windows High Contrast', () => {
+    render(<Switch label="Notifications" value={true} onChange={() => {}} />);
+    const css = getForcedColorsRules();
+    // Track outline (backgrounds are stripped; the border keeps the bounds).
+    expect(css).toContain('border-color: canvastext;');
+    // Off track stays empty; on track uses the selection color.
+    expect(css).toContain('background-color: canvas;');
+    expect(css).toContain('background-color: highlight;');
+    // Thumb fill per state.
+    expect(css).toContain('background-color: canvastext;');
+    expect(css).toContain('background-color: highlighttext;');
+    // Disabled affordance (opacity dimming does not survive forcing).
+    expect(css).toContain('border-color: graytext;');
+  });
+
+  it('gates the hover tint out of forced colors so the thumb stays visible on hover', () => {
+    render(<Switch label="Notifications" value={true} onChange={() => {}} />);
+    // The ancestor-hover tint is a non-system color-mix whose rule outranks the
+    // plain forced-colors track rule. It is gated behind `forced-colors: none`
+    // so it cannot reassert on hover and flatten the Highlight track to white
+    // under the HighlightText thumb (white-on-white).
+    expect(getAllInjectedCss()).toContain(
+      '(hover: hover) and (forced-colors: none)',
+    );
+    // And the tint never leaks into the forced-colors output.
+    expect(getForcedColorsRules()).not.toContain('color-mix');
+  });
+});

package/src/Switch/Switch.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/Switch/Switch.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/Switch/index.ts (exports if types change)
  * - /apps/storybook/stories/Switch.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/Switch/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Switch/ (showcase blocks)
  */
 
 import {
@@ -173,6 +173,21 @@ const styles = stylex.create({
     },
     transitionTimingFunction: easeVars['--ease-standard'],
     boxSizing: 'border-box',
+    // Forced colors (Windows High Contrast) strips painted backgrounds, which
+    // would leave the track invisible. A system-color border keeps the
+    // control's bounds perceivable (WCAG 1.4.11).
+    borderWidth: {
+      default: 0,
+      '@media (forced-colors: active)': '1px',
+    },
+    borderStyle: {
+      default: 'none',
+      '@media (forced-colors: active)': 'solid',
+    },
+    borderColor: {
+      default: null,
+      '@media (forced-colors: active)': 'CanvasText',
+    },
   },
   trackFocus: {
     outline: {
@@ -189,21 +204,39 @@ const styles = stylex.create({
   trackOff: {
     backgroundColor: {
       default: colorVars['--color-background-gray'],
+      // Off = empty (Canvas) track; on = Highlight track, so the two states
+      // stay distinguishable under forced colors.
+      '@media (forced-colors: active)': 'Canvas',
+      // The ancestor-hover tint is a non-system color-mix, and its rule
+      // outranks the plain forced-colors rule above. Left ungated it would
+      // reassert on hover under forced colors, where the UA flattens the
+      // color-mix back to Canvas — so the HighlightText thumb would sit on a
+      // white track (white-on-white). Gating on `forced-colors: none` keeps
+      // the tint out of forced colors and lets the system-color track stand.
       [stylex.when.ancestor(':hover', switchScope)]: {
-        '@media (hover: hover)': `color-mix(in srgb, ${colorVars['--color-background-gray']}, ${colorVars['--color-tint-hover']} 5%)`,
+        '@media (hover: hover) and (forced-colors: none)': `color-mix(in srgb, ${colorVars['--color-background-gray']}, ${colorVars['--color-tint-hover']} 5%)`,
       },
     },
   },
   trackOn: {
     backgroundColor: {
       default: colorVars['--color-accent'],
+      '@media (forced-colors: active)': 'Highlight',
+      // See trackOff: gate the hover tint out of forced colors so it cannot
+      // flatten the Highlight track to white under the HighlightText thumb.
       [stylex.when.ancestor(':hover', switchScope)]: {
-        '@media (hover: hover)': `color-mix(in srgb, ${colorVars['--color-accent']}, ${colorVars['--color-tint-hover']} 15%)`,
+        '@media (hover: hover) and (forced-colors: none)': `color-mix(in srgb, ${colorVars['--color-accent']}, ${colorVars['--color-tint-hover']} 15%)`,
       },
     },
   },
   trackDisabled: {
     opacity: 0.5,
+    // Opacity dimming does not survive forced colors; GrayText is the
+    // platform's disabled affordance there.
+    borderColor: {
+      default: null,
+      '@media (forced-colors: active)': 'GrayText',
+    },
   },
   trackDisabledOff: {
     backgroundColor: colorVars['--color-background-gray'],
@@ -213,7 +246,6 @@ const styles = stylex.create({
     alignItems: 'center',
     justifyContent: 'center',
     borderRadius: radiusVars['--radius-full'],
-    backgroundColor: colorVars['--color-background-surface'],
     transitionProperty: 'transform, width, height',
     transitionDuration: {
       default: durationVars['--duration-fast'],
@@ -221,6 +253,22 @@ const styles = stylex.create({
     },
     transitionTimingFunction: easeVars['--ease-standard'],
   },
+  // The thumb fill lives on the on/off styles (not the shared thumb style)
+  // because forced colors needs a per-state system color: CanvasText on the
+  // empty off track, HighlightText on the Highlight on track. Sizing stays in
+  // thumbOffSizeStyles/thumbOnSizeStyles; only the fill is state-dependent.
+  thumbOff: {
+    backgroundColor: {
+      default: colorVars['--color-background-surface'],
+      '@media (forced-colors: active)': 'CanvasText',
+    },
+  },
+  thumbOn: {
+    backgroundColor: {
+      default: colorVars['--color-background-surface'],
+      '@media (forced-colors: active)': 'HighlightText',
+    },
+  },
   labelWrapper: {
     display: 'flex',
     flexDirection: 'column',
@@ -236,11 +284,7 @@ const styles = stylex.create({
 
 export type SwitchLabelPosition = 'start' | 'end';
 
-export type SwitchLabelSpacing =
-  | 'hug'
-  | 'spread'
-  /** @deprecated Use `'hug'` instead. */
-  | 'default';
+export type SwitchLabelSpacing = 'hug' | 'spread';
 
 export interface SwitchProps extends Omit<BaseProps, 'onChange'> {
   /** Ref forwarded to the root element */
@@ -354,8 +398,6 @@ export interface SwitchProps extends Omit<BaseProps, 'onChange'> {
    * Spacing behavior between label and switch.
    * - 'hug': Label and switch are positioned next to each other
    * - 'spread': Label and switch are pushed to opposite ends
-   *
-   * 'default' is a deprecated alias for 'hug'.
    * @default 'hug'
    */
   labelSpacing?: SwitchLabelSpacing;
@@ -434,10 +476,6 @@ export function Switch({
 
   const isOn = optimisticValue === true;
 
-  // 'default' is a deprecated alias for 'hug' (#2889).
-  const resolvedLabelSpacing: SwitchLabelSpacing =
-    labelSpacing === 'default' ? 'hug' : labelSpacing;
-
   // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
   // tooltip listeners attach to the switch row (which already exists) and the
   // native checkbox stays perceivable via aria-disabled instead of the disabled
@@ -537,6 +575,7 @@ export function Switch({
             stylex.props(
               styles.thumb,
               isOn ? thumbOnSizeStyles[size] : thumbOffSizeStyles[size],
+              isOn ? styles.thumbOn : styles.thumbOff,
             ),
           )}>
           {isBusy && <Spinner size="sm" />}
@@ -568,8 +607,7 @@ export function Switch({
       {...mergeProps(
         themeProps('switch-field', {
           labelPosition: labelPosition !== 'end' ? labelPosition : undefined,
-          labelSpacing:
-            resolvedLabelSpacing !== 'hug' ? resolvedLabelSpacing : undefined,
+          labelSpacing: labelSpacing !== 'hug' ? labelSpacing : undefined,
         }),
         stylex.props(width != null && dynamicWidthStyles.width(width), xstyle),
         className,
@@ -588,7 +626,7 @@ export function Switch({
         }}
         {...stylex.props(
           styles.container,
-          resolvedLabelSpacing === 'spread' && styles.containerSpread,
+          labelSpacing === 'spread' && styles.containerSpread,
           !isDisabled && switchScope,
         )}>
         {' '}
@@ -605,14 +643,13 @@ export function Switch({
         )}
       </div>
       {status?.message && (
-        <div {...stylex.props(styles.statusGap)}>
-          <FieldStatus
-            type={status.type}
-            message={status.message}
-            id={statusMessageID}
-            variant="detached"
-          />
-        </div>
+        <FieldStatus
+          type={status.type}
+          message={status.message}
+          id={statusMessageID}
+          variant="detached"
+          xstyle={styles.statusGap}
+        />
       )}
       {showsDisabledMessage &&
         disabledMessageTooltip.renderTooltip(disabledMessage)}

package/src/TabList/Tab.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: 'Tab',

package/src/TabList/Tab.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/TabList/TabList.doc.mjs
  * - /packages/core/src/TabList/index.ts
  * - /packages/core/src/TabList/TabList.test.tsx
- * - /packages/cli/templates/blocks/components/TabList/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/TabList/ (showcase blocks)
  */
 
 import React, {useCallback, type ReactNode} from 'react';

package/src/TabList/TabList.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: 'TabList',
@@ -99,7 +99,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
     description:
@@ -120,7 +120,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'Tab navigation w/ overflow menu support; semantic nav landmark w/ button or anchor tab items.',
   usage: {

package/src/TabList/TabList.test.tsx

@@ -687,10 +687,10 @@ describe('TabMenu', () => {
 
     // Menu items are rendered in DOM (popover controls visibility, hidden from a11y tree)
     expect(
-      screen.getByRole('menuitem', {name: 'Analytics', hidden: true}),
+      screen.getByRole('menuitemradio', {name: 'Analytics', hidden: true}),
     ).toBeInTheDocument();
     expect(
-      screen.getByRole('menuitem', {name: 'Reports', hidden: true}),
+      screen.getByRole('menuitemradio', {name: 'Reports', hidden: true}),
     ).toBeInTheDocument();
   });
 
@@ -726,7 +726,7 @@ describe('TabMenu', () => {
     await user.click(screen.getByRole('button', {name: /More/}));
 
     // Click the menu item (popover content, hidden from a11y tree in jsdom)
-    const menuItem = screen.getByRole('menuitem', {
+    const menuItem = screen.getByRole('menuitemradio', {
       name: 'Analytics',
       hidden: true,
     });
@@ -734,7 +734,7 @@ describe('TabMenu', () => {
     expect(handleChange).toHaveBeenCalledWith('analytics');
   });
 
-  it('marks menu item as selected with aria-current', () => {
+  it('exposes options as menuitemradio and marks the selected tab aria-checked', () => {
     render(
       <TabList value="analytics" onChange={() => {}}>
         <Tab value="home" label="Home" />
@@ -742,18 +742,21 @@ describe('TabMenu', () => {
       </TabList>,
     );
 
-    // Menu items are in DOM (popover content, hidden from a11y tree in jsdom)
-    const analyticsItem = screen.getByRole('menuitem', {
+    // Menu items are in DOM (popover content, hidden from a11y tree in jsdom).
+    // Single-select menu options carry radio semantics (APG menu-button):
+    // role="menuitemradio" + aria-checked, not menuitem + aria-current.
+    const analyticsItem = screen.getByRole('menuitemradio', {
       name: 'Analytics',
       hidden: true,
     });
-    expect(analyticsItem).toHaveAttribute('aria-current', 'true');
+    expect(analyticsItem).toHaveAttribute('aria-checked', 'true');
+    expect(analyticsItem).not.toHaveAttribute('aria-current');
 
-    const reportsItem = screen.getByRole('menuitem', {
+    const reportsItem = screen.getByRole('menuitemradio', {
       name: 'Reports',
       hidden: true,
     });
-    expect(reportsItem).not.toHaveAttribute('aria-current');
+    expect(reportsItem).toHaveAttribute('aria-checked', 'false');
   });
 });
 
@@ -774,11 +777,11 @@ describe('TabMenu keyboard navigation (roving tabindex)', () => {
 
     await user.click(screen.getByRole('button', {name: /More/}));
 
-    const analytics = screen.getByRole('menuitem', {
+    const analytics = screen.getByRole('menuitemradio', {
       name: 'Analytics',
       hidden: true,
     });
-    const reports = screen.getByRole('menuitem', {
+    const reports = screen.getByRole('menuitemradio', {
       name: 'Reports',
       hidden: true,
     });
@@ -804,11 +807,11 @@ describe('TabMenu keyboard navigation (roving tabindex)', () => {
 
     await user.click(screen.getByRole('button', {name: /More/}));
     const menu = screen.getByRole('menu', {hidden: true});
-    const analytics = screen.getByRole('menuitem', {
+    const analytics = screen.getByRole('menuitemradio', {
       name: 'Analytics',
       hidden: true,
     });
-    const reports = screen.getByRole('menuitem', {
+    const reports = screen.getByRole('menuitemradio', {
       name: 'Reports',
       hidden: true,
     });
@@ -834,11 +837,11 @@ describe('TabMenu keyboard navigation (roving tabindex)', () => {
 
     await user.click(screen.getByRole('button', {name: /More/}));
     const menu = screen.getByRole('menu', {hidden: true});
-    const analytics = screen.getByRole('menuitem', {
+    const analytics = screen.getByRole('menuitemradio', {
       name: 'Analytics',
       hidden: true,
     });
-    const reports = screen.getByRole('menuitem', {
+    const reports = screen.getByRole('menuitemradio', {
       name: 'Reports',
       hidden: true,
     });
@@ -867,11 +870,11 @@ describe('TabMenu keyboard navigation (roving tabindex)', () => {
 
     await user.click(screen.getByRole('button', {name: /More/}));
     const menu = screen.getByRole('menu', {hidden: true});
-    const analytics = screen.getByRole('menuitem', {
+    const analytics = screen.getByRole('menuitemradio', {
       name: 'Analytics',
       hidden: true,
     });
-    const exports = screen.getByRole('menuitem', {
+    const exports = screen.getByRole('menuitemradio', {
       name: 'Exports',
       hidden: true,
     });
@@ -894,7 +897,7 @@ describe('TabMenu keyboard navigation (roving tabindex)', () => {
     );
 
     await user.click(screen.getByRole('button', {name: /More/}));
-    const analytics = screen.getByRole('menuitem', {
+    const analytics = screen.getByRole('menuitemradio', {
       name: 'Analytics',
       hidden: true,
     });

package/src/TabList/TabList.tsx

@@ -14,7 +14,7 @@
  * - /packages/core/src/TabList/TabList.doc.mjs
  * - /packages/core/src/TabList/index.ts
  * - /packages/core/src/TabList/TabList.test.tsx
- * - /packages/cli/templates/blocks/components/TabList/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/TabList/ (showcase blocks)
  */
 
 import React, {useCallback, useMemo, type ReactNode} from 'react';