Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(cli): add component accessibility sections

rubyycheung88fde9103f89
diff --git a/.changeset/cli-component-accessibility-guidance.md b/.changeset/cli-component-accessibility-guidance.md
new file mode 100644
index 0000000000..2e1ad41521
--- /dev/null
+++ b/.changeset/cli-component-accessibility-guidance.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[feat] Component docs can declare structured `usage.accessibility` requirements, and `astryx component` renders them as a dedicated Accessibility section in full and compact output. Translated and dense documentation overlays preserve the base accessibility guidance unless they explicitly replace it.
+
+@rubyycheung
diff --git a/packages/cli/authoring/doctypes/base/type.ts b/packages/cli/authoring/doctypes/base/type.ts
index 71b7d18180..221567c24e 100644
--- a/packages/cli/authoring/doctypes/base/type.ts
+++ b/packages/cli/authoring/doctypes/base/type.ts
@@ -48,6 +48,26 @@ export interface ComponentBestPractice {
description: string;
}
+/**
+ * A component-specific accessibility requirement.
+ *
+ * Keep this focused on what a consumer must preserve in the rendered result:
+ * naming, semantics, keyboard behavior, state exposure, contrast, and supported
+ * content combinations. Repository audit procedure belongs in the wiki rubric,
+ * not in this field.
+ *
+ * @example
+ * ```
+ * {name: 'Loading', description: 'Expose aria-busy and prevent duplicate activation unless the action is explicitly interruptible.'}
+ * ```
+ */
+export interface ComponentAccessibilityRequirement {
+ /** Short scannable label, e.g. `"Accessible name"` or `"Loading"`. */
+ name: string;
+ /** The accessibility contract consumers must preserve. */
+ description: string;
+}
+
/**
* Code example for a component or sub-component.
*/
@@ -406,8 +426,8 @@ export interface HookReturnDoc {
}
/**
- * Component usage documentation — a concise summary, design guidance
- * best practices, and optional visual anatomy.
+ * Component usage documentation — a concise summary, design guidance,
+ * component-specific accessibility requirements, and optional visual anatomy.
*
* ## description
* Exactly 2-3 short sentences:
@@ -439,6 +459,9 @@ export interface UsageDoc {
/** 3-4 do/don't design guidance items. Usually 2 Do's then 1-2 Don'ts.
* Focus on how a designer would USE the component, not how it's built. */
bestPractices?: ComponentBestPractice[];
+ /** Accessibility requirements specific to this component and its supported
+ * content combinations. Generic audit procedure stays in the wiki rubric. */
+ accessibility?: ComponentAccessibilityRequirement[];
/** 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). */
diff --git a/packages/cli/authoring/doctypes/component/component.doc.mjs b/packages/cli/authoring/doctypes/component/component.doc.mjs
index d73c9ab169..41267df932 100644
--- a/packages/cli/authoring/doctypes/component/component.doc.mjs
+++ b/packages/cli/authoring/doctypes/component/component.doc.mjs
@@ -112,7 +112,7 @@ export const doc = {
name: 'usage',
type: 'UsageDoc',
description:
- 'Component usage documentation: concise summary, best practices, and optional visual anatomy. (Optional on SubComponentDoc, where the sub-component description is used instead.)',
+ 'Component usage documentation: concise summary, best practices, component-specific accessibility requirements, and optional visual anatomy. (Optional on SubComponentDoc, where the sub-component description is used instead.)',
required: true,
fields: [
{
@@ -128,6 +128,12 @@ export const doc = {
description:
"3-4 do/don't design-guidance items ({guidance: boolean, description: string}). Never start the description with 'Do' or 'Don't'.",
},
+ {
+ 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.',
+ },
{
name: 'usage.anatomy',
type: 'ComponentAnatomyElement[]',
diff --git a/packages/cli/authoring/doctypes/component/type.ts b/packages/cli/authoring/doctypes/component/type.ts
index a802e450b2..ffc17c5022 100644
--- a/packages/cli/authoring/doctypes/component/type.ts
+++ b/packages/cli/authoring/doctypes/component/type.ts
@@ -5,6 +5,7 @@
*/
import type {
+ ComponentAccessibilityRequirement,
ComponentAnatomyElement,
ComponentBestPractice,
ComponentExampleDoc,
@@ -251,6 +252,7 @@ export interface ComponentTranslationDoc {
usage?: {
description?: string;
bestPractices?: ComponentBestPractice[];
+ accessibility?: ComponentAccessibilityRequirement[];
anatomy?: ComponentAnatomyElement[];
};
/** Sub-component translations. Must match docs.components length and order (if present). */
diff --git a/packages/cli/authoring/doctypes/function/function.doc.mjs b/packages/cli/authoring/doctypes/function/function.doc.mjs
index 1fa916544f..173aec5a36 100644
--- a/packages/cli/authoring/doctypes/function/function.doc.mjs
+++ b/packages/cli/authoring/doctypes/function/function.doc.mjs
@@ -191,7 +191,7 @@ export const doc = {
name: 'usage',
type: 'UsageDoc',
description:
- 'Usage documentation (hooks): description, best practices, anatomy. Same shape as HookDoc.usage.',
+ 'Usage documentation (hooks): description, best practices, accessibility requirements, and anatomy. Same shape as HookDoc.usage.',
},
{
name: 'command',
diff --git a/packages/cli/authoring/doctypes/hook/hook.doc.mjs b/packages/cli/authoring/doctypes/hook/hook.doc.mjs
index 01b08a9c77..5888e48b78 100644
--- a/packages/cli/authoring/doctypes/hook/hook.doc.mjs
+++ b/packages/cli/authoring/doctypes/hook/hook.doc.mjs
@@ -133,6 +133,12 @@ export const doc = {
description:
"3-4 do/don't design-guidance items ({guidance: boolean, description: string}).",
},
+ {
+ name: 'usage.accessibility',
+ type: 'ComponentAccessibilityRequirement[]',
+ description:
+ 'Accessibility requirements specific to using the hook ({name, description}).',
+ },
{
name: 'usage.anatomy',
type: 'ComponentAnatomyElement[]',
diff --git a/packages/cli/authoring/doctypes/hook/type.ts b/packages/cli/authoring/doctypes/hook/type.ts
index 8653d890c2..d2cb1246d9 100644
--- a/packages/cli/authoring/doctypes/hook/type.ts
+++ b/packages/cli/authoring/doctypes/hook/type.ts
@@ -5,6 +5,7 @@
*/
import type {
+ ComponentAccessibilityRequirement,
ComponentBestPractice,
HookParamDoc,
HookReturnDoc,
@@ -73,5 +74,6 @@ export interface HookTranslationDoc {
usage?: {
description?: string;
bestPractices?: ComponentBestPractice[];
+ accessibility?: ComponentAccessibilityRequirement[];
};
}
diff --git a/packages/cli/authoring/index.d.ts b/packages/cli/authoring/index.d.ts
index 6f1fba37a5..de8164261c 100644
--- a/packages/cli/authoring/index.d.ts
+++ b/packages/cli/authoring/index.d.ts
@@ -67,6 +67,7 @@ export type {
ComponentPropDoc,
ComponentExampleDoc,
ComponentAnatomyElement,
+ ComponentAccessibilityRequirement,
ComponentBestPractice,
ComponentSlotElement,
ComponentPlaygroundConfig,
diff --git a/packages/cli/clients/cli/lib/component-format.mjs b/packages/cli/clients/cli/lib/component-format.mjs
index 6bef6d03af..972f16c86c 100644
--- a/packages/cli/clients/cli/lib/component-format.mjs
+++ b/packages/cli/clients/cli/lib/component-format.mjs
@@ -71,6 +71,21 @@ function formatPropsTable(props) {
return lines.join('\n');
}
+/**
+ * Render component-specific accessibility requirements.
+ * @param {{name: string, description: string}[] | undefined} accessibility
+ * @param {'##' | '####'} [heading]
+ * @returns {string[]}
+ */
+export function formatAccessibility(accessibility, heading = '##') {
+ if (!Array.isArray(accessibility) || accessibility.length === 0) return [];
+ return [
+ `${heading} Accessibility\n`,
+ ...accessibility.map(item => `- **${item.name}:** ${item.description}`),
+ '',
+ ];
+}
+
/**
* Render a sub-component block (the `### Name` sections under "## Components").
*
@@ -88,6 +103,7 @@ function formatSubComponent(comp) {
if (comp.description) {
out.push(comp.description + '\n');
}
+ out.push(...formatAccessibility(comp.usage?.accessibility, '####'));
const table = formatPropsTable(comp.props);
if (table) {
out.push(table + '\n');
@@ -224,6 +240,8 @@ export function formatFull(docs, options = {}) {
sections.push('');
}
+ sections.push(...formatAccessibility(docs.usage?.accessibility));
+
// Single component props
if ('props' in docs) {
sections.push('## Props\n');
@@ -388,6 +406,8 @@ export function formatCompact(docs, componentName, importHint) {
sections.push('');
}
+ sections.push(...formatAccessibility(docs.usage?.accessibility));
+
// Props
if ('props' in docs) {
sections.push('## Props\n');
diff --git a/packages/cli/clients/cli/lib/component-format.test.mjs b/packages/cli/clients/cli/lib/component-format.test.mjs
index d8dc736da2..7699930fe0 100644
--- a/packages/cli/clients/cli/lib/component-format.test.mjs
+++ b/packages/cli/clients/cli/lib/component-format.test.mjs
@@ -1,7 +1,44 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
import {describe, it, expect} from 'vitest';
-import {formatBrief, formatFull} from './component-format.mjs';
+import {formatBrief, formatCompact, formatFull} from './component-format.mjs';
+
+describe('component accessibility guidance', () => {
+ const docs = {
+ name: 'Button',
+ description: 'An action.',
+ usage: {
+ accessibility: [
+ {name: 'Loading', description: 'Expose aria-busy and block duplicate activation.'},
+ ],
+ },
+ props: [],
+ };
+
+ it('renders a dedicated section in full output', () => {
+ const out = formatFull(docs);
+ expect(out).toContain('## Accessibility');
+ expect(out).toContain('- **Loading:** Expose aria-busy and block duplicate activation.');
+ });
+
+ it('keeps accessibility guidance in compact agent output', () => {
+ const out = formatCompact(docs, 'Button');
+ expect(out).toContain('## Accessibility');
+ expect(out).toContain('Expose aria-busy and block duplicate activation.');
+ });
+
+ it('omits the section when a component has no authored requirements', () => {
+ expect(formatFull({...docs, usage: {}})).not.toContain('## Accessibility');
+ });
+
+ it('ignores legacy non-array accessibility content', () => {
+ const legacyDocs = {...docs, usage: {accessibility: 'Follow WCAG guidance.'}};
+
+ expect(() => formatFull(legacyDocs)).not.toThrow();
+ expect(formatFull(legacyDocs)).not.toContain('## Accessibility');
+ expect(formatCompact(legacyDocs, 'Button')).not.toContain('## Accessibility');
+ });
+});
describe('formatFull sub-component rendering', () => {
// Regression guard: sub-components are sometimes declared as a bare
diff --git a/packages/cli/clients/cli/lib/hook-format.mjs b/packages/cli/clients/cli/lib/hook-format.mjs
index 030b8a4e86..08b511a8eb 100644
--- a/packages/cli/clients/cli/lib/hook-format.mjs
+++ b/packages/cli/clients/cli/lib/hook-format.mjs
@@ -11,7 +11,7 @@
import {discoverHooks, findHookDoc} from '../../../foundation/discovery/hook-discovery.mjs';
import {loadDocs} from '../../../foundation/discovery/component-loader.mjs';
-import {mdCell} from './component-format.mjs';
+import {formatAccessibility, mdCell} from './component-format.mjs';
/**
* Build a signature string from hook docs.
@@ -111,6 +111,8 @@ export function formatHookFull(docs) {
sections.push('');
}
+ sections.push(...formatAccessibility(docs.usage?.accessibility));
+
// Parameters (analogous to ## Props)
if (docs.params?.length) {
sections.push('## Parameters\n');
@@ -161,6 +163,8 @@ export function formatHookCompact(docs, importPath) {
sections.push('');
}
+ sections.push(...formatAccessibility(docs.usage?.accessibility));
+
// Parameters (matches ## Props in component compact)
if (docs.params?.length) {
sections.push('## Parameters\n');
diff --git a/packages/cli/clients/cli/lib/hook-format.test.mjs b/packages/cli/clients/cli/lib/hook-format.test.mjs
new file mode 100644
index 0000000000..42c7f5bcc4
--- /dev/null
+++ b/packages/cli/clients/cli/lib/hook-format.test.mjs
@@ -0,0 +1,35 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {formatHookCompact, formatHookFull} from './hook-format.mjs';
+
+describe('hook accessibility guidance', () => {
+ const docs = {
+ name: 'useButton',
+ usage: {
+ description: 'Provides button behavior.',
+ accessibility: [
+ {
+ name: 'Keyboard activation',
+ description: 'Preserve Enter and Space activation.',
+ },
+ ],
+ },
+ params: [],
+ returns: [],
+ };
+
+ it('renders accessibility guidance in full output', () => {
+ const out = formatHookFull(docs);
+
+ expect(out).toContain('## Accessibility');
+ expect(out).toContain('- **Keyboard activation:** Preserve Enter and Space activation.');
+ });
+
+ it('renders accessibility guidance in compact output', () => {
+ const out = formatHookCompact(docs);
+
+ expect(out).toContain('## Accessibility');
+ expect(out).toContain('Preserve Enter and Space activation.');
+ });
+});
diff --git a/packages/cli/foundation/discovery/__fixtures__/component-accessibility-overlay.doc.mjs b/packages/cli/foundation/discovery/__fixtures__/component-accessibility-overlay.doc.mjs
new file mode 100644
index 0000000000..a66a3eca97
--- /dev/null
+++ b/packages/cli/foundation/discovery/__fixtures__/component-accessibility-overlay.doc.mjs
@@ -0,0 +1,37 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+export const docs = {
+ name: 'AccessibilityOverlayFixture',
+ displayName: 'Accessibility Overlay Fixture',
+ category: 'Test',
+ usage: {
+ description: 'Base description.',
+ bestPractices: [
+ {
+ guidance: true,
+ description: 'Base-only best practice.',
+ },
+ ],
+ accessibility: [
+ {
+ name: 'Accessible name',
+ description: 'Provide an accessible name.',
+ },
+ ],
+ anatomy: [
+ {
+ name: 'Base-only anatomy',
+ required: true,
+ description: 'This must not leak into translated output.',
+ },
+ ],
+ },
+ props: [],
+};
+
+export const docsDense = {
+ usage: {
+ description: 'Dense description.',
+ },
+ props: [],
+};
diff --git a/packages/cli/foundation/discovery/component-loader.mjs b/packages/cli/foundation/discovery/component-loader.mjs
index 82fd0d56ff..90fe76f5ea 100644
--- a/packages/cli/foundation/discovery/component-loader.mjs
+++ b/packages/cli/foundation/discovery/component-loader.mjs
@@ -73,6 +73,7 @@ export function mergeTranslation(docs, translation) {
if (translation.usage?.description) merged.usage.description = translation.usage.description;
else if (translation.description) merged.usage.description = translation.description;
if (translation.usage?.bestPractices) merged.usage.bestPractices = translation.usage.bestPractices;
+ if (translation.usage?.accessibility) merged.usage.accessibility = translation.usage.accessibility;
}
// Legacy top-level fields (for docsZh that are full ComponentDoc clones)
@@ -193,7 +194,19 @@ function overlayComponentDoc(docs, translation) {
});
};
- const merged = {...docs, ...translation};
+ /** Preserve the new accessibility field 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};
+ };
+
+ const merged = {...docs, ...translation, usage: mergeUsage(docs.usage, translation.usage)};
merged.props = overlayProps(docs.props, translation.props);
@@ -204,7 +217,7 @@ function overlayComponentDoc(docs, translation) {
merged.components = docs.components.map((/** @type {any} */ base) => {
const t = tByName.get(base.name);
if (!t) return base;
- return {...base, ...t, props: overlayProps(base.props, t.props)};
+ return {...base, ...t, usage: mergeUsage(base.usage, t.usage), props: overlayProps(base.props, t.props)};
});
}
@@ -215,4 +228,4 @@ function overlayComponentDoc(docs, translation) {
* Find the doc file for a component, checking both top-level
* and nested directories. Prefers {Name}.doc.mjs, then README.md
* (for backward compatibility).
- */
\ No newline at end of file
+ */
diff --git a/packages/cli/foundation/discovery/componentDocOverlay.test.mjs b/packages/cli/foundation/discovery/componentDocOverlay.test.mjs
index d5e13895fd..14ef83fd48 100644
--- a/packages/cli/foundation/discovery/componentDocOverlay.test.mjs
+++ b/packages/cli/foundation/discovery/componentDocOverlay.test.mjs
@@ -108,4 +108,19 @@ describe('the reported symptom', () => {
const merged = zh.props.find(p => p.name === 'variant');
expect(merged.description).toBe(translated.description);
});
+
+ it('keeps base accessibility guidance when a translation does not replace it', async () => {
+ const docPath = path.join(
+ import.meta.dirname,
+ '__fixtures__',
+ 'component-accessibility-overlay.doc.mjs',
+ );
+ const english = await loadDocs(docPath);
+ const dense = await loadDocs(docPath, {dense: true});
+
+ expect(english.usage.accessibility.length).toBeGreaterThan(0);
+ expect(dense.usage.accessibility).toEqual(english.usage.accessibility);
+ expect(dense.usage.bestPractices).toBeUndefined();
+ expect(dense.usage.anatomy).toBeUndefined();
+ });
});