@astryxdesign/cli 0.5.2-canary.e4f7677 → 0.5.2-canary.e4f8e4e

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.e4f7677",
+  "version": "0.5.2-canary.e4f8e4e",
   "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.e4f7677",
-    "@astryxdesign/core": "0.5.2-canary.e4f7677",
-    "@astryxdesign/lab": "0.5.2-canary.e4f7677",
-    "@astryxdesign/theme-neutral": "0.5.2-canary.e4f7677",
+    "@astryxdesign/charts": "0.5.2-canary.e4f8e4e",
+    "@astryxdesign/core": "0.5.2-canary.e4f8e4e",
+    "@astryxdesign/lab": "0.5.2-canary.e4f8e4e",
+    "@astryxdesign/theme-neutral": "0.5.2-canary.e4f8e4e",
     "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
@@ -108,10 +108,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.5.2-canary.e4f7677",
-    "@astryxdesign/core": "0.5.2-canary.e4f7677",
-    "@astryxdesign/lab": "0.5.2-canary.e4f7677",
-    "@astryxdesign/theme-neutral": "0.5.2-canary.e4f7677",
+    "@astryxdesign/charts": "0.5.2-canary.e4f8e4e",
+    "@astryxdesign/core": "0.5.2-canary.e4f8e4e",
+    "@astryxdesign/lab": "0.5.2-canary.e4f8e4e",
+    "@astryxdesign/theme-neutral": "0.5.2-canary.e4f8e4e",
     "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {