@astryxdesign/cli 0.5.2-canary.c9c8564 → 0.5.2-canary.fbfe729

package/assets/templates/blocks/components/ContextMenu/ContextMenuBasic.doc.mjs

@@ -7,7 +7,7 @@ export const doc = {
   name: 'ContextMenu — Basic',
   displayName: 'ContextMenu — Basic',
   description:
-    'A right-click area with action items and a divider separating a destructive action. Use to provide contextual actions for a specific element or region.',
+    'An adaptive context area: long-press opens a BottomSheet on compact touch screens, while right-click opens a cursor-positioned menu elsewhere.',
   isReady: true,
   aspectRatio: 16 / 9,
   componentsUsed: ['ContextMenu'],

package/assets/templates/blocks/components/ContextMenu/ContextMenuBasic.tsx

@@ -7,6 +7,7 @@ import {ContextMenu} from '@astryxdesign/core/ContextMenu';
 export default function ContextMenuBasic() {
   return (
     <ContextMenu
+      presentation="adaptive"
       items={[
         {label: 'Cut', onClick: () => {}},
         {label: 'Copy', onClick: () => {}},
@@ -25,7 +26,7 @@ export default function ContextMenuBasic() {
           color: '#6b7280',
           userSelect: 'none',
         }}>
-        Right-click this area
+        Long-press or right-click this area
       </div>
     </ContextMenu>
   );

package/assets/templates/blocks/components/ContextMenu/ContextMenuBottomSheet.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'ContextMenu',
+  name: 'ContextMenu — Bottom Sheet',
+  displayName: 'ContextMenu — Bottom Sheet',
+  description:
+    'A ContextMenu using the explicit BottomSheet presentation. Long-press the target on touch devices or right-click it with a pointer. Keep a visible menu trigger for important mobile actions.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['ContextMenu'],
+};

package/assets/templates/blocks/components/ContextMenu/ContextMenuBottomSheet.tsx

@@ -0,0 +1,59 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {
+  DocumentDuplicateIcon,
+  PencilIcon,
+  ShareIcon,
+  TrashIcon,
+} from '@heroicons/react/24/outline';
+import {ContextMenu} from '@astryxdesign/core/ContextMenu';
+
+export default function ContextMenuBottomSheet() {
+  return (
+    <ContextMenu
+      presentation="bottom-sheet"
+      label="Document actions"
+      items={[
+        {
+          label: 'Rename document',
+          description: 'Change the title shown to collaborators.',
+          icon: PencilIcon,
+          onClick: () => {},
+        },
+        {
+          label: 'Duplicate document',
+          description: 'Create a copy in the same workspace.',
+          icon: DocumentDuplicateIcon,
+          onClick: () => {},
+        },
+        {
+          label: 'Share document',
+          description: 'Invite people or copy a share link.',
+          icon: ShareIcon,
+          onClick: () => {},
+        },
+        {
+          label: 'Delete document',
+          description: 'Move this document to the trash.',
+          icon: TrashIcon,
+          variant: 'destructive',
+          onClick: () => {},
+        },
+      ]}>
+      <div
+        style={{
+          display: 'flex',
+          flexDirection: 'column',
+          gap: '8px',
+          padding: '32px',
+          border: '1px solid #d1d5db',
+          borderRadius: '12px',
+        }}>
+        <strong>Quarterly plan</strong>
+        <span>Long-press on touch or right-click for document actions.</span>
+      </div>
+    </ContextMenu>
+  );
+}

package/assets/templates/blocks/components/ContextMenu/ContextMenuShowcase.doc.mjs

@@ -6,7 +6,7 @@ export const doc = {
   name: 'ContextMenu',
   displayName: 'Context Menu',
   description:
-    'A right-click area that opens a context menu with action items.',
+    'An adaptive context area that supports long-press on compact touch screens and right-click elsewhere.',
   isReady: true,
   isShowcase: true,
   aspectRatio: 1,

package/assets/templates/blocks/components/ContextMenu/ContextMenuShowcase.tsx

@@ -6,6 +6,7 @@ import {ContextMenu} from '@astryxdesign/core/ContextMenu';
 export default function ContextMenuShowcase() {
   return (
     <ContextMenu
+      presentation="adaptive"
       items={[
         {label: 'Cut', onClick: () => {}},
         {label: 'Copy', onClick: () => {}},
@@ -22,7 +23,7 @@ export default function ContextMenuShowcase() {
           color: '#6b7280',
           userSelect: 'none',
         }}>
-        Right-click this area
+        Long-press or right-click this area
       </div>
     </ContextMenu>
   );

package/assets/templates/blocks/components/DropdownMenu/DropdownMenuBottomSheet.doc.mjs

@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'DropdownMenu',
+  alsoExampleFor: ['BottomSheet', 'useMediaQuery'],
+  name: 'DropdownMenu — Adaptive presentation',
+  displayName: 'DropdownMenu — Adaptive presentation',
+  description:
+    'Chooses a bottom sheet for compact touch surfaces and an anchored popover otherwise. The media query is product policy, while DropdownMenu owns both presentations.',
+  isReady: true,
+  aspectRatio: 3 / 4,
+  componentsUsed: ['DropdownMenu', 'Stack', 'Text', 'useMediaQuery'],
+};

package/assets/templates/blocks/components/DropdownMenu/DropdownMenuBottomSheet.tsx

@@ -0,0 +1,49 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {
+  ArchiveBoxIcon,
+  DocumentDuplicateIcon,
+  PencilIcon,
+  ShareIcon,
+} from '@heroicons/react/24/outline';
+import {DropdownMenu} from '@astryxdesign/core/DropdownMenu';
+import {VStack} from '@astryxdesign/core/Stack';
+import {Text} from '@astryxdesign/core/Text';
+import {useMediaQuery} from '@astryxdesign/core/hooks';
+
+const COMPACT_TOUCH_QUERY =
+  '(max-width: 639px) and (pointer: coarse) and (hover: none)';
+
+const ACTIONS = [
+  {label: 'Edit project', icon: PencilIcon},
+  {label: 'Duplicate project', icon: DocumentDuplicateIcon},
+  {label: 'Share project', icon: ShareIcon},
+  {label: 'Archive project', icon: ArchiveBoxIcon},
+] as const;
+
+export default function DropdownMenuBottomSheet() {
+  const [lastAction, setLastAction] = useState<string | null>(null);
+  const isCompactTouchSurface = useMediaQuery(COMPACT_TOUCH_QUERY);
+
+  return (
+    <VStack gap={3}>
+      <DropdownMenu
+        button={{label: 'Project actions'}}
+        presentation={isCompactTouchSurface ? 'bottom-sheet' : 'popover'}
+        items={ACTIONS.map(({label, icon}) => ({
+          label,
+          icon,
+          onClick: () => setLastAction(label),
+        }))}
+      />
+      {lastAction && (
+        <Text type="supporting" color="secondary">
+          Last action: {lastAction}
+        </Text>
+      )}
+    </VStack>
+  );
+}

package/assets/templates/blocks/components/MoreMenu/MoreMenuBottomSheet.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'MoreMenu',
+  name: 'MoreMenu — Bottom Sheet',
+  displayName: 'MoreMenu — Bottom Sheet',
+  description:
+    'A visible overflow trigger that opens actions in a BottomSheet. Use this presentation for short action sets on compact touch surfaces.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['MoreMenu'],
+};

package/assets/templates/blocks/components/MoreMenu/MoreMenuBottomSheet.tsx

@@ -0,0 +1,63 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {
+  DocumentDuplicateIcon,
+  PencilIcon,
+  ShareIcon,
+  TrashIcon,
+} from '@heroicons/react/24/outline';
+import {MoreMenu} from '@astryxdesign/core/MoreMenu';
+
+export default function MoreMenuBottomSheet() {
+  return (
+    <div
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'space-between',
+        gap: '16px',
+        width: 'min(100%, 360px)',
+        padding: '16px',
+        border: '1px solid #d1d5db',
+        borderRadius: '12px',
+      }}>
+      <div style={{display: 'flex', flexDirection: 'column', gap: '4px'}}>
+        <strong>Quarterly plan</strong>
+        <span>Updated a few minutes ago</span>
+      </div>
+      <MoreMenu
+        presentation="bottom-sheet"
+        label="Project actions"
+        items={[
+          {
+            label: 'Rename project',
+            description: 'Update the project title.',
+            icon: PencilIcon,
+            onClick: () => {},
+          },
+          {
+            label: 'Duplicate project',
+            description: 'Create a copy in this workspace.',
+            icon: DocumentDuplicateIcon,
+            onClick: () => {},
+          },
+          {
+            label: 'Share project',
+            description: 'Invite people to collaborate.',
+            icon: ShareIcon,
+            onClick: () => {},
+          },
+          {
+            label: 'Delete project',
+            description: 'Move this project to the trash.',
+            icon: TrashIcon,
+            variant: 'destructive',
+            onClick: () => {},
+          },
+        ]}
+      />
+    </div>
+  );
+}

package/assets/templates/blocks/components/MultiSelector/MultiSelectorBottomSheet.doc.mjs

@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'MultiSelector',
+  alsoExampleFor: ['BottomSheet'],
+  name: 'MultiSelector — Bottom Sheet',
+  displayName: 'MultiSelector — Bottom Sheet',
+  description:
+    'Keeps a multi-selection list open in a bottom sheet while choices are toggled.',
+  isReady: true,
+  aspectRatio: 3 / 4,
+  componentsUsed: ['MultiSelector'],
+};

package/assets/templates/blocks/components/MultiSelector/MultiSelectorBottomSheet.tsx

@@ -0,0 +1,26 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {MultiSelector} from '@astryxdesign/core/MultiSelector';
+
+const OPTIONS = ['Design', 'Engineering', 'Marketing', 'Operations'];
+
+export default function MultiSelectorBottomSheet() {
+  const [value, setValue] = useState<string[]>([]);
+
+  return (
+    <div style={{width: 320, maxWidth: '100%'}}>
+      <MultiSelector
+        label="Teams"
+        options={OPTIONS}
+        value={value}
+        onChange={setValue}
+        placeholder="Choose teams"
+        hasSelectAll
+        presentation="bottom-sheet"
+      />
+    </div>
+  );
+}

package/assets/templates/blocks/components/Popover/PopoverBottomSheetAlternative.doc.mjs

@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'Popover',
+  name: 'Popover — Bottom Sheet Alternative',
+  displayName: 'Popover — Bottom Sheet Alternative',
+  description:
+    'Opt-in BottomSheet alternative for compact touch surfaces where actions should use a modal presentation anchored to the bottom edge.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: [
+    'BottomSheet',
+    'Button',
+    'Icon',
+    'Section',
+    'Layout',
+    'Text',
+    'List',
+  ],
+};

package/assets/templates/blocks/components/Popover/PopoverBottomSheetAlternative.tsx

@@ -0,0 +1,71 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {CalendarIcon, TagIcon, UserIcon} from '@heroicons/react/24/outline';
+import {BottomSheet} from '@astryxdesign/core/BottomSheet';
+import {Button} from '@astryxdesign/core/Button';
+import {Icon} from '@astryxdesign/core/Icon';
+import {List, ListItem} from '@astryxdesign/core/List';
+import {VStack} from '@astryxdesign/core/Layout';
+import {Section} from '@astryxdesign/core/Section';
+import {Heading, Text} from '@astryxdesign/core/Text';
+import {spacingVars} from '@astryxdesign/core/theme/tokens.stylex';
+
+const styles = stylex.create({
+  header: {
+    // Match the unchanged spacious ListItem inset so the title and description
+    // align with the action icons.
+    marginInlineStart: spacingVars['--spacing-3'],
+  },
+});
+
+const PROJECT_ACTIONS = [
+  [UserIcon, 'Assign owner', 'Route follow-up to a teammate.'],
+  [TagIcon, 'Add label', 'Group this item with related work.'],
+  [CalendarIcon, 'Set due date', 'Pick a reminder for review.'],
+] as const;
+
+export default function PopoverBottomSheetAlternative() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <>
+      <Button label="Open project actions" onClick={() => setIsOpen(true)}>
+        Open project actions
+      </Button>
+      <BottomSheet
+        isOpen={isOpen}
+        onOpenChange={setIsOpen}
+        label="Project actions"
+        height="hug">
+        <Section paddingBlock={4} paddingInline={1}>
+          <VStack gap={3}>
+            <VStack gap={1} xstyle={styles.header}>
+              <Heading level={3}>Project actions</Heading>
+              <Text type="supporting" color="secondary">
+                Use this modal touch surface when the task should move away from
+                its trigger and stay close to the bottom edge.
+              </Text>
+            </VStack>
+            <List density="spacious">
+              {PROJECT_ACTIONS.map(([icon, label, description]) => (
+                <ListItem
+                  key={label}
+                  label={label}
+                  description={description}
+                  startContent={
+                    <Icon icon={icon} size="md" color="secondary" />
+                  }
+                  onClick={() => setIsOpen(false)}
+                />
+              ))}
+            </List>
+          </VStack>
+        </Section>
+      </BottomSheet>
+    </>
+  );
+}

package/assets/templates/blocks/components/Selector/SelectorBottomSheet.doc.mjs

@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'Selector',
+  alsoExampleFor: ['BottomSheet'],
+  name: 'Selector — Bottom Sheet',
+  displayName: 'Selector — Bottom Sheet',
+  description:
+    'Presents a single-selection list in a bottom sheet for compact touch interfaces.',
+  isReady: true,
+  aspectRatio: 3 / 4,
+  componentsUsed: ['Selector'],
+};

package/assets/templates/blocks/components/Selector/SelectorBottomSheet.tsx

@@ -0,0 +1,30 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {Selector} from '@astryxdesign/core/Selector';
+
+const OPTIONS = [
+  {value: 'design', label: 'Design'},
+  {value: 'engineering', label: 'Engineering'},
+  {value: 'marketing', label: 'Marketing'},
+  {value: 'operations', label: 'Operations'},
+];
+
+export default function SelectorBottomSheet() {
+  const [value, setValue] = useState<string | undefined>();
+
+  return (
+    <div style={{width: 320, maxWidth: '100%'}}>
+      <Selector
+        label="Team"
+        options={OPTIONS}
+        value={value}
+        onChange={setValue}
+        placeholder="Choose a team"
+        presentation="bottom-sheet"
+      />
+    </div>
+  );
+}

package/authoring/doctypes/base/type.ts

@@ -64,8 +64,96 @@ export interface ComponentBestPractice {
 export interface ComponentAccessibilityRequirement {
   /** Short scannable label, e.g. `"Accessible name"` or `"Loading"`. */
   name: string;
-  /** The accessibility contract consumers must preserve. */
+  /**
+   * The accessibility contract consumers must preserve. Write at about a
+   * grade-7 reading level with short sentences, common words, and active
+   * voice. For color contrast, put the ratio in `requirement`; name the exact
+   * foreground, background, state, and any overlay in `description`; explain
+   * exceptions in plain language; and include enough detail for a human or
+   * agent to reproduce the check.
+   */
   description: string;
+  /** Groups related requirements in the docsite Accessibility tab. */
+  category?: 'Color contrast' | 'Keyboard' | 'Semantics' | 'Content';
+  /** Relevant WCAG success criterion, e.g. `"1.4.3 Contrast (Minimum)"`. */
+  criterion?: string;
+  /** Short threshold or rule, e.g. `"4.5:1"`, `"3:1"`, or `"Exempt"`. */
+  requirement?: string;
+  /** Component states covered by this requirement. */
+  states?: string[];
+}
+
+export type ComponentAccessibilityThemeStatus = 'Pass' | 'Fail' | 'Not tested';
+
+export type ComponentAccessibilityThemeApplicability =
+  'Required' | 'Conditional' | 'Supplemental' | 'Decorative';
+
+export interface ComponentAccessibilityThemeMeasurement {
+  /** Column heading, e.g. `"Rest"` or `"Spinner"`. */
+  label: string;
+  /** Display value, e.g. `"15.13:1"`. */
+  value: string;
+  /** Optional supporting detail shown below the value, such as a worst case. */
+  detail?: string;
+  /**
+   * Whether this measurement is required for every use, required only in some
+   * contexts, shown as a supplemental cue, or decorative. Each theme declares
+   * this intent, informed by the component contract. Never infer it from the
+   * measured ratio. Non-required measurements do not determine row status.
+   */
+  applicability?: ComponentAccessibilityThemeApplicability;
+  /** Rendered foreground and background colors used for this measurement. */
+  colorPair?: {
+    foreground: string;
+    background: string;
+  };
+  /** Optional per-variant results shown from a compact details trigger. */
+  breakdown?: Array<{
+    label: string;
+    value: string;
+    detail?: string;
+    colorPair: {
+      foreground: string;
+      background: string;
+    };
+    status?: 'Pass' | 'Fail';
+  }>;
+  /** Mark a failed measurement so the docsite can emphasize it. */
+  status?: 'Pass' | 'Fail';
+}
+
+export interface ComponentAccessibilityThemeResult {
+  /** Row heading, usually a component variant. */
+  name: string;
+  /** Measurements shown between the row heading and status. */
+  measurements: ComponentAccessibilityThemeMeasurement[];
+  /** Overall result for the row. */
+  status: ComponentAccessibilityThemeStatus;
+}
+
+export interface ComponentAccessibilityThemeMode {
+  /** Theme mode covered by these results. */
+  mode: 'Light' | 'Dark';
+  /** Detailed results for the component in this mode. */
+  results: ComponentAccessibilityThemeResult[];
+}
+
+export interface ComponentAccessibilityThemeTable {
+  /** Optional heading for one complete group of measurements. */
+  title?: string;
+  /** Explains the scope of this measurement group. */
+  description?: string;
+  /** Detailed results separated by theme mode. */
+  modes: ComponentAccessibilityThemeMode[];
+}
+
+export interface ComponentAccessibilityThemeCoverage {
+  /** Display name of the audited theme. */
+  theme: string;
+  /** Complete groups of measurements for this theme and component. */
+  tables: ComponentAccessibilityThemeTable[];
+  /** Theme visuals intentionally excluded from measurement, with a reason. */
+  notMeasured?: string[];
 }
 
 /**
@@ -462,6 +550,8 @@ export interface UsageDoc {
   /** Accessibility requirements specific to this component and its supported
    * content combinations. Generic audit procedure stays in the wiki rubric. */
   accessibility?: ComponentAccessibilityRequirement[];
+  /** Verified color-accessibility coverage for bundled themes. */
+  accessibilityThemeCoverage?: ComponentAccessibilityThemeCoverage[];
   /** Structural/visual anatomy of the component. Each entry describes one
    *  element that makes up the component (icon slot, label, container, etc.).
    *  Order entries in the visual reading order (leading → trailing, top → bottom). */

package/authoring/doctypes/component/component.doc.mjs

@@ -132,7 +132,13 @@ export const doc = {
           name: 'usage.accessibility',
           type: 'ComponentAccessibilityRequirement[]',
           description:
-            'Component-specific accessibility requirements ({name, description}) rendered as a dedicated Accessibility section. Keep audit procedures in the wiki rubric.',
+            'Component-specific requirements rendered in the shared Accessibility tab. Write at about a grade-7 reading level with short sentences, common words, and active voice. For color contrast, put the ratio in `requirement`; name the exact foreground, background, state, and any overlay in `description`; explain exceptions in plain language; and give a human or agent enough detail to reproduce the check. Keep repository audit procedures in the wiki rubric.',
+        },
+        {
+          name: 'usage.accessibilityThemeCoverage',
+          type: 'ComponentAccessibilityThemeCoverage[]',
+          description:
+            'Verified per-theme accessibility measurements rendered in the shared Accessibility tab. Record light and dark mode separately, include rendered color pairs, and mark failed measurements. Put visuals excluded from the audit in `notMeasured` with a short reason; do not add them as table measurements. Each theme declares `applicability` for measured values, informed by the component contract and never inferred from the ratio: `Conditional` is required only in some contexts, `Supplemental` adds another meaningful cue, and `Decorative` has no required meaning. These values do not change row status. Provide a complete breakdown when one cell summarizes multiple combinations, and protect derived values with an automated audit.',
         },
         {
           name: 'usage.anatomy',

package/authoring/index.d.ts

@@ -68,6 +68,13 @@ export type {
   ComponentExampleDoc,
   ComponentAnatomyElement,
   ComponentAccessibilityRequirement,
+  ComponentAccessibilityThemeStatus,
+  ComponentAccessibilityThemeApplicability,
+  ComponentAccessibilityThemeMeasurement,
+  ComponentAccessibilityThemeResult,
+  ComponentAccessibilityThemeMode,
+  ComponentAccessibilityThemeTable,
+  ComponentAccessibilityThemeCoverage,
   ComponentBestPractice,
   ComponentSlotElement,
   ComponentPlaygroundConfig,

package/foundation/discovery/__fixtures__/component-accessibility-overlay.doc.d.mts

@@ -15,6 +15,16 @@ export namespace docs {
             name: string;
             description: string;
         }[];
+        let accessibilityThemeCoverage: {
+            theme: string;
+            tables: {
+                modes: {
+                    mode: string;
+                    results: never[];
+                }[];
+            }[];
+            notMeasured: string[];
+        }[];
         let anatomy: {
             name: string;
             required: boolean;

package/foundation/discovery/__fixtures__/component-accessibility-overlay.doc.mjs

@@ -18,6 +18,20 @@ export const docs = {
         description: 'Provide an accessible name.',
       },
     ],
+    accessibilityThemeCoverage: [
+      {
+        theme: 'Fixture',
+        tables: [
+          {
+            modes: [
+              {mode: 'Light', results: []},
+              {mode: 'Dark', results: []},
+            ],
+          },
+        ],
+        notMeasured: ['Decorative track — Not part of the contrast audit.'],
+      },
+    ],
     anatomy: [
       {
         name: 'Base-only anatomy',

package/foundation/discovery/component-loader.mjs

@@ -194,16 +194,23 @@ function overlayComponentDoc(docs, translation) {
     });
   };
 
-  /** Preserve the new accessibility field without changing established translated output.
+  /** Preserve structured accessibility data without changing established translated output.
    * @param {any} baseUsage
    * @param {any} translatedUsage
    */
   const mergeUsage = (baseUsage, translatedUsage) => {
     if (!translatedUsage) return baseUsage;
-    if (!baseUsage?.accessibility || translatedUsage.accessibility !== undefined) {
-      return translatedUsage;
-    }
-    return {...translatedUsage, accessibility: baseUsage.accessibility};
+    return {
+      ...translatedUsage,
+      ...(translatedUsage.accessibility === undefined &&
+      baseUsage?.accessibility !== undefined
+        ? {accessibility: baseUsage.accessibility}
+        : null),
+      ...(translatedUsage.accessibilityThemeCoverage === undefined &&
+      baseUsage?.accessibilityThemeCoverage !== undefined
+        ? {accessibilityThemeCoverage: baseUsage.accessibilityThemeCoverage}
+        : null),
+    };
   };
 
   const merged = {...docs, ...translation, usage: mergeUsage(docs.usage, translation.usage)};

package/foundation/discovery/componentDocOverlay.test.mjs

@@ -120,6 +120,12 @@ describe('the reported symptom', () => {
 
     expect(english.usage.accessibility.length).toBeGreaterThan(0);
     expect(dense.usage.accessibility).toEqual(english.usage.accessibility);
+    expect(dense.usage.accessibilityThemeCoverage).toEqual(
+      english.usage.accessibilityThemeCoverage,
+    );
+    expect(dense.usage.accessibilityThemeCoverage[0].notMeasured).toContain(
+      'Decorative track — Not part of the contrast audit.',
+    );
     expect(dense.usage.bestPractices).toBeUndefined();
     expect(dense.usage.anatomy).toBeUndefined();
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.5.2-canary.c9c8564",
+  "version": "0.5.2-canary.fbfe729",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -87,10 +87,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "0.5.2-canary.c9c8564",
-    "@astryxdesign/core": "0.5.2-canary.c9c8564",
-    "@astryxdesign/lab": "0.5.2-canary.c9c8564",
-    "@astryxdesign/theme-neutral": "0.5.2-canary.c9c8564",
+    "@astryxdesign/charts": "0.5.2-canary.fbfe729",
+    "@astryxdesign/core": "0.5.2-canary.fbfe729",
+    "@astryxdesign/lab": "0.5.2-canary.fbfe729",
+    "@astryxdesign/theme-neutral": "0.5.2-canary.fbfe729",
     "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
@@ -108,10 +108,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.5.2-canary.c9c8564",
-    "@astryxdesign/core": "0.5.2-canary.c9c8564",
-    "@astryxdesign/lab": "0.5.2-canary.c9c8564",
-    "@astryxdesign/theme-neutral": "0.5.2-canary.c9c8564",
+    "@astryxdesign/charts": "0.5.2-canary.fbfe729",
+    "@astryxdesign/core": "0.5.2-canary.fbfe729",
+    "@astryxdesign/lab": "0.5.2-canary.fbfe729",
+    "@astryxdesign/theme-neutral": "0.5.2-canary.fbfe729",
     "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {