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.mdnew file mode 100644index 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.++@rubyycheungdiff --git a/packages/cli/authoring/doctypes/base/type.ts b/packages/cli/authoring/doctypes/base/type.tsindex 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.mjsindex 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.tsindex 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.mjsindex 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.mjsindex 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.tsindex 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.tsindex 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.mjsindex 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 propsif ('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));+// Propsif ('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.mjsindex 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 barediff --git a/packages/cli/clients/cli/lib/hook-format.mjs b/packages/cli/clients/cli/lib/hook-format.mjsindex 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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.mjsindex 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.mjsindex 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();+ });});