An open source design system that's fully customizable and agent ready
TypeScript
[Component Audit] Citation: name inert references for screen readers (#6849)
Cindy Zhang34e0ad3cba3c
diff --git a/.changeset/citation-root-contract.md b/.changeset/citation-root-contract.mdnew file mode 100644index 0000000000..a32d63ca6f--- /dev/null+++ b/.changeset/citation-root-contract.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[fix] Give inert Citation references a supported accessible name, and document their linked and inert root contract.++@cixzhangdiff --git a/apps/storybook/rtl-audit/verified-not-applicable.json b/apps/storybook/rtl-audit/verified-not-applicable.jsonindex e002cd47d7..dd73dcc70c 100644--- a/apps/storybook/rtl-audit/verified-not-applicable.json+++ b/apps/storybook/rtl-audit/verified-not-applicable.json@@ -121,6 +121,15 @@"component": "core/Card","reason": "Card is a block container with symmetric radius, border, shadow, and logical padding. It owns no directional glyph, inline-axis ordering, physical positioning, scrolling action, dragging, overlay, or keyboard behavior."},+ {+ "component": "core/Citation",+ "reason": "Citation renders a direction-neutral inline chip or superscript badge in normal text flow. Its optional icon is caller-owned or a source image; spacing uses logical margin and padding, and the component owns no directional glyph, physical inline positioning, reordering, horizontal scrolling or dragging, side-placed overlay, or horizontal keyboard behavior.",+ "evidence": {+ "apps/storybook/stories/Citation.stories.tsx": "sha256:c2cafac52d87682547ccfff6185008d704421ef770e22edd7759ccd4b9673554",+ "packages/core/src/Citation/Citation.tsx": "sha256:3ddc76002e34bf99640b4d2ba3a62add63af29845dc1227825010a64628fc481",+ "packages/core/src/Citation/index.ts": "sha256:27df0cd0fd0aed1f3722d2b5e1b7be08e940b29094ad23410d7b639b5b9ad976"+ }+ },{"component": "core/Code","reason": "Code is an inline typographic treatment with a monospace font, symmetric background/radius, and logical padding. The code string owns its own bidi content; the component adds no directional visual, positioning, ordering, interaction, or overlay."diff --git a/packages/core/src/Citation/Citation.doc.mjs b/packages/core/src/Citation/Citation.doc.mjsindex d727ba6e7c..fc59118319 100644--- a/packages/core/src/Citation/Citation.doc.mjs+++ b/packages/core/src/Citation/Citation.doc.mjs@@ -33,7 +33,7 @@ export const docs = {name: 'Container',required: true,description:- 'The interactive wrapper. Renders as an anchor when a URL is provided, or a span otherwise.',+ 'The root wrapper. Accepted source URLs render an anchor; missing or rejected URLs render an inert span.',},{name: 'Icon',diff --git a/packages/core/src/Citation/Citation.spec.md b/packages/core/src/Citation/Citation.spec.mdnew file mode 100644index 0000000000..a0a6f2ba2d--- /dev/null+++ b/packages/core/src/Citation/Citation.spec.md@@ -0,0 +1,179 @@+---+schema_version: 3+template_version: 6+kind: component+id: component:Citation+authority: draft+archive_reason: null+superseded_by: null+approved_by: null+approved_at: null+owners: [cixzhang]+review_triggers: [public-api, behavior, theming, accessibility, visual]+verified_by:+ [+ packages/core/src/Citation/Citation.test.tsx,+ packages/core/src/utils/safeUrl.test.ts,+ apps/storybook/stories/Citation.stories.tsx,+ apps/storybook/rtl-audit/verified-not-applicable.json,+ ]+modules: []+families: [family:navigation-destinations]+design_specs: []+architecture:+ [+ architecture:public-component-api,+ architecture:component-theming-surface,+ architecture:component-test-sufficiency,+ architecture:interaction-modality,+ ]+contributing: []+system_specs: [spec:AST-005]+---++# Citation component contract++## Contract at a glance++| Area | Contract |+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |+| Public contract | `Citation` is exported from `@astryxdesign/core/Citation`; `source` and `number` are required, and `variant` defaults to `label`. |+| Behavior | An accepted source URL renders a native anchor in a new tab. A missing or rejected URL renders the same citation content in an inert span. Label and number variants preserve that navigation decision. |+| End-user impact | Readers receive a consistent citation label or numbered reference without a blocked destination becoming navigation or a decorative source icon being announced twice. |+| Builder impact | Builders may supply source text, a destination, an image or node icon, neutral DOM props, a root ref, and composed styling without replacing Citation’s navigation or accessibility ownership. |+| Compatibility/readiness | The released defaults, export, theme target, URL behavior, and visual presentation remain unchanged. The inert span now uses a noninteractive naming role so its existing translated label reaches assistive technology. |+| Review checks | Reject a blocked URL that becomes navigation, an accepted URL that loses native anchor affordances, an interactive or reference role on an inert citation, a missing inert accessible name, an announced decorative icon, dropped supported passthrough or ref behavior, or a new public theme target without authority. |+| Governing rules | `family:navigation-destinations/FR1,FR3–FR5,FR7–FR8`; `architecture:public-component-api/INV1,INV5,INV6,INV8,INV9`; `architecture:component-theming-surface/INV3–INV6`; `architecture:component-test-sufficiency/INV1–INV7,INV10–INV11`. |++This table is a review projection; the body below is authoritative only after owner approval.++## Intent++Present an inline reference to a source as a readable label or compact number while applying the shared navigation decision before any destination reaches the native anchor.++## Compatibility and migration++- Released default preserved: yes+- Compatibility class: restorative accessibility semantics plus observational documentation; no public-type, visual, layout, styling, or theme-target change+- Controlled/uncontrolled behavior: not applicable; Citation owns no state+- Migration decision: none; the existing package export and source shape remain unchanged++Consumer migration instructions belong in consumer docs and release notes.++## Ownership boundary++**Owns**++- Label and number presentation, accepted-link versus inert-span rendering, accessible citation naming, decorative icon treatment, and the `citation` root target.+- Supported neutral DOM and styling passthrough, including a ref to the rendered anchor or span.++**Does not own / non-goals**++- Which navigation schemes are accepted or blocked — owned by `family:navigation-destinations` and `spec:AST-005`.+- A general image or resource URL policy — source images remain outside the navigation-destination contract.+- The semantics or accessibility of a caller-supplied icon node outside Citation’s decorative wrapper.+- Citation ordering, bibliography management, content provenance, or surrounding prose — owned by the product callsite.++## Public concepts++| Concept | Closed values or states | Meaning | Availability | Default | Owner | Stability | Invalid-value behavior |+| ----------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------- | ----------------------------------- | -------------------------------- | ------------------------------ | ------------------------------------ |+| variant | `label`, `number` | Selects visible source-title or numbered-reference presentation. | Every render. | `label` | `component:Citation` | stable | rejected by the public type |+| destination | accepted, missing, rejected | Selects native-anchor or inert-span root after the shared navigation decision. | Every variant. | missing when `source.url` is absent | `family:navigation-destinations` | current family contract | rejected destinations render inertly |+| source icon | node, `src`, legacy string icon, absent | Supplies optional decorative source paint in the label variant. A non-string node wins over `src`; otherwise `src` wins over a legacy string icon URL. | Label variant only. | absent | `component:Citation` | shipped compatibility behavior | ordinary React rendering behavior |+| number | numeric value | Supplies the citation index and participates in the translated accessible name. | Every variant. | required | `component:Citation` | stable | rejected by the public type |++## Behavioral and layout contract++| ID | Candidate invariant | Basis | Draft review state |+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------ |+| FR1 | An accepted `source.url` MUST render a native anchor with the unchanged destination, `target="_blank"`, `rel="noopener noreferrer"`, `role="doc-noteref"`, and the current title and translated accessible name. | shipped source and tests; `family:navigation-destinations/FR1,FR3–FR5` | verify |+| FR2 | A missing or rejected destination MUST render the selected citation presentation in a noninteractive span with no navigation or reference role. The span MUST use a supported naming role so its translated label reaches assistive technology. Rejection MUST NOT derive navigation attributes from `source.url`, invent disabled semantics, or hide the citation. | shipped source and tests; `family:navigation-destinations/FR4,FR7`; WAI-ARIA naming rules | verify |+| FR3 | The label variant MUST present the source title, optional decorative source icon, and truncation behavior; the number variant MUST present the supplied number as the compact visible reference. | shipped source, docs, tests, and stories | verify |+| FR4 | Node icons MUST take precedence over `src`; otherwise `src` MUST take precedence over a legacy string `icon`. Every icon path remains decorative inside an `aria-hidden` wrapper. | shipped compatibility behavior and tests | verify |+| FR5 | Both root branches MUST preserve supported DOM props, `className`, `style`, `xstyle`, `data-*` attributes, and the declared `HTMLElement` ref while keeping the component-owned role and accessible name authoritative. | `architecture:public-component-api/INV5,INV6,INV8`; regression tests | verify |+| FR6 | Citation MUST keep one public `citation` target on the painted root and MUST NOT expose an internal icon or text target without an approved theming-contract change. | shipped docs/source; `architecture:component-theming-surface/INV3–INV6` | verify |+| FR7 | Component-owned accessible text MUST remain routed through `useTranslator`; visible source text and numeric content remain caller-supplied data. | shipped source and i18n infrastructure | verify |++### Allowed variation++- **AV1 — Theme paint.** The `citation` root target may change supported visual paint without changing variant, destination, role, or accessible-name behavior.+- **AV2 — Caller content.** Source titles, numeric values, image URLs, and node icons may vary within the released public types.+- **AV3 — Native destination behavior.** Accepted relative, fragment, protocol-relative, HTTP(S), mailto, tel, and safe custom destinations retain native browser handling and the component’s existing new-tab relationship.++### Representative states++| State | Required invariant | Allowed variation |+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------- |+| linked label | Native anchor, source title, optional decorative icon, translated accessible name. | Source content and root theme paint. |+| linked number | Native anchor, numeric visible reference, translated accessible name. | Number and root theme paint. |+| missing or rejected URL | Inert span with the same selected presentation, a supported naming role, and no navigation/reference role or attributes. | Source content and root theme paint. |+| node or image icon | Icon remains decorative and appears only in the label variant. | Caller-owned artwork or source image. |++### Transformation and precedence order++- **ORD1 — Destination.** `source.url` → shared safe-URL decision → native anchor or inert span.+- **ORD2 — Icon.** Non-string `source.icon` → `source.src` → legacy string `source.icon` → no icon.+- **ORD3 — Root props.** Caller passthrough → component-owned role, name, test id, and navigation attributes → theme and style composition.++### Performance and resources++- **PR1 — Pure render.** Citation owns no state, Effect, listener, observer, timer, or external resource lifecycle.+- **PR2 — Images.** Citation may emit one caller-supplied source image; fetching, validation, and resource policy are not decided by the navigation contract.++## Accessibility contract++- **AR1 — Linked reference.** An accepted destination exposes one native link with `doc-noteref` and the translated `Citation {number}: {title}` accessible name.+- **AR2 — Inert reference.** Missing or rejected destinations expose no interactive or navigation role or attributes. The inert span uses `role="group"` so its translated citation label remains an accessible name, including when the visible number has no source text.+- **AR3 — Decorative source mark.** Source image and node icon paint remains hidden from the accessibility tree so it does not duplicate the citation name.+- **AR4 — Focus ownership.** The native anchor remains the semantic focus owner. Citation adds no focus owner to the inert span.++## Design relationships++| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |+| ---------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------ | ------------------ |+| Root | Paints the label chip or numbered badge and owns the `citation` target. | observed shipped representation and public docs | supporting reference | FR1–FR3, FR5–FR6 |+| Source icon | Presents optional caller-supplied source identity without accessibility semantics. | observed shipped representation | decorative | FR3–FR4, AR3 |+| Label or number | Presents the source title or compact index. | observed shipped representation | primary citation content | FR3, FR7 |++Citation exposes only the documented `citation` root target. Internal icon and text parts currently have no public target; this observational draft neither adds nor promises one.++## Family and system relationships++- `family:navigation-destinations` owns the accept/block result for `source.url`, including native-anchor sinks and preservation of accepted browser behavior.+- `spec:AST-005` owns the normalized blocked-scheme rule that the family projects onto Citation.+- `architecture:public-component-api` owns export stability, passthrough, styling composition, ref reachability, and component-owned prop precedence.+- `architecture:component-theming-surface` owns public target qualification and placement.+- `architecture:component-test-sufficiency` owns mutation-sensitive evidence for each critical branch and public promise.+- `architecture:interaction-modality` owns shared modality behavior while Citation’s native anchor remains its own semantic focus owner.++## Verification map++| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ---------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |+| FR1–FR2, AR1–AR2 | `Citation.test.tsx` destination suites and `safeUrl.test.ts` matrix | accepted, missing, blocked schemes, normalized blocked text | A blocked URL creates navigation, an accepted URL loses its destination or native affordances, or an inert reference loses its supported naming role. | `audit:Citation/navigation` |+| FR3–FR4, AR3 | `Citation.test.tsx` variant and icon suites | label, number, no icon, node icon, `src`, legacy string icon | The wrong visible variant renders, icon precedence changes, or decorative source paint reaches the accessibility tree. | `audit:Citation/behavior` |+| FR5 | `Citation.test.tsx` root-contract suite and strict type/lint validation | anchor and span roots with ref, DOM props, class, inline style, and `xstyle` | Either root drops supported passthrough or ref behavior, or caller-supplied role/name overrides component ownership. | `audit:Citation/api` |+| FR6 | Public docs, source review, and theming-target inventories | linked and inert roots; both variants | The root target disappears, moves off the painter, or an undocumented internal target becomes public. | `audit:Citation/theming` |+| FR7 | Existing i18n build and Citation accessible-name assertions | linked label and number | Component-authored accessible text bypasses translation or loses source/number context. | `audit:Citation/i18n` |+| RTL N/A | `verified-not-applicable.json` source-hashed record | label and number stories; linked/inert source paths; icon/no-icon | A direction-sensitive glyph, physical inline placement, ordering, scrolling, overlay, or horizontal keyboard behavior appears without RTL evidence. | `audit:Citation/rtl` |+| All | `Citation.stories.tsx`, component tests, typecheck, lint, and exact-head CI | all documented variants and representative source states | A required state becomes unreachable or gains a build, accessibility, visual, or test regression. | `audit:Citation/testing` |++## Decision log++### DEC-1 — Inert references use a noninteractive naming role++**Reference:** `component:Citation/DEC-1`+**Decider:** `cixzhang`, `2026-10-01`++The existing inert span uses `role="group"` so its translated `aria-label` is valid without creating navigation, focus, or a visual/DOM child. A roleless generic span cannot be named; `group` is a noninteractive, name-supporting role and is the smallest restoration that preserves the current root and presentation.++Reconsider this mechanism if a supported platform primitive can name inert inline content without group-boundary announcements, or evidence shows the group semantics harm citation reading at volume.++## Open questions++None. This observational draft does not decide a general resource URL policy or add a component-local theming surface.++## Content boundary++This file does not duplicate consumer prop tables/examples, current audit results, implementation steps, navigation-system rationale, or resource policy. It links to their owners.diff --git a/packages/core/src/Citation/Citation.test.tsx b/packages/core/src/Citation/Citation.test.tsxindex 21ba9e9e54..5c6b288fad 100644--- a/packages/core/src/Citation/Citation.test.tsx+++ b/packages/core/src/Citation/Citation.test.tsx@@ -6,6 +6,7 @@* @output Tests for Citation component*/+import {createRef} from 'react';import {render, screen} from '@testing-library/react';import {describe, it, expect} from 'vitest';import * as stylex from '@stylexjs/stylex';@@ -20,6 +21,7 @@ const probe = stylex.create({secondaryText: {color: colorVars['--color-text-secondary']},accentText: {color: colorVars['--color-text-accent']},badgeBackground: {backgroundColor: colorVars['--color-accent-muted']},+ consumerOverride: {color: colorVars['--color-text-accent']},pointerCursor: {cursor: {default: 'pointer',@@ -58,6 +60,10 @@ describe('Citation', () => {const el = screen.getByTestId('citation');expect(el.tagName).toBe('A');expect(el).toHaveAttribute('href', 'https://example.com');+ expect(el).toHaveAttribute('target', '_blank');+ expect(el).toHaveAttribute('rel', 'noopener noreferrer');+ expect(el).toHaveAttribute('role', 'doc-noteref');+ expect(el).toHaveAttribute('aria-label', 'Citation 1: Example Source');expect(el).toHaveTextContent('Example Source');});@@ -86,9 +92,73 @@ describe('Citation', () => {);const el = screen.getByTestId('citation');expect(el.tagName).toBe('SPAN');- // doc-noteref is a reference role that is not permitted on a plain- // (unlinked) span (axe: aria-allowed-role), so it must be omitted here.- expect(el).not.toHaveAttribute('role');+ // `doc-noteref` is a link role and must be omitted on an inert span. A+ // supported naming role still lets the component-authored aria-label name+ // the inert citation, including the number-only variant.+ expect(el).toHaveAttribute('role', 'group');+ expect(el).toHaveAccessibleName('Citation 1: No link');+ expect(el).not.toHaveAttribute('href');+ expect(el).not.toHaveAttribute('target');+ expect(el).not.toHaveAttribute('rel');+ });++ it('names an inert number-only citation', () => {+ render(+ <Citation+ source={{title: 'No link'}}+ number={5}+ variant="number"+ data-testid="citation"+ />,+ );+ const el = screen.getByTestId('citation');+ expect(el).toHaveAttribute('role', 'group');+ expect(el).toHaveAccessibleName('Citation 5: No link');+ expect(el).not.toHaveAttribute('href');+ });++ it('forwards the ref and supported root props across linked and inert roots', () => {+ const ref = createRef<HTMLElement>();+ const rootProps = {+ ref,+ className: 'consumer-class',+ style: {opacity: 0.5},+ xstyle: probe.consumerOverride,+ role: 'button',+ 'aria-label': 'Caller label',+ 'data-owner': 'citation-consumer',+ 'data-testid': 'citation',+ } as const;+ const {rerender} = render(+ <Citation source={source} number={1} {...rootProps} />,+ );++ let el = screen.getByTestId('citation');+ expect(el.tagName).toBe('A');+ expect(ref.current).toBe(el);+ expect(el).toHaveAttribute('role', 'doc-noteref');+ expect(el).toHaveAccessibleName('Citation 1: Example Source');+ expect(el).toHaveClass('consumer-class');+ expect(el).toHaveStyle({opacity: 0.5});+ expect(el).toHaveAttribute('data-owner', 'citation-consumer');+ for (const cls of atomicClasses(probe.consumerOverride)) {+ expect(el.classList.contains(cls)).toBe(true);+ }++ rerender(+ <Citation source={{title: 'No link'}} number={1} {...rootProps} />,+ );+ el = screen.getByTestId('citation');+ expect(el.tagName).toBe('SPAN');+ expect(ref.current).toBe(el);+ expect(el).toHaveAttribute('role', 'group');+ expect(el).toHaveAccessibleName('Citation 1: No link');+ expect(el).toHaveClass('consumer-class');+ expect(el).toHaveStyle({opacity: 0.5});+ expect(el).toHaveAttribute('data-owner', 'citation-consumer');+ for (const cls of atomicClasses(probe.consumerOverride)) {+ expect(el.classList.contains(cls)).toBe(true);+ }});it('renders astryx-* class names for theme targeting', () => {diff --git a/packages/core/src/Citation/Citation.tsx b/packages/core/src/Citation/Citation.tsxindex d2465743bb..58ce033fcb 100644--- a/packages/core/src/Citation/Citation.tsx+++ b/packages/core/src/Citation/Citation.tsx@@ -5,7 +5,7 @@/*** @file Citation.tsx* @input Uses React, StyleX, theme tokens, and the shared navigation policy- * @output Exports Citation component for inline citation references+ * @output Exports Citation with safe navigation and named inert-reference states* @position Core implementation; consumed by index.ts** SYNC: When modified, update these files to stay in sync:@@ -205,10 +205,10 @@ export function Citation({const hasIcon = iconNode != null || imageSrc != null;const Tag = href ? 'a' : 'span';- // `doc-noteref` is a reference role — only appropriate on the interactive- // link form. On a plain (unlinked) span it is not a permitted role- // (axe: aria-allowed-role), so omit it there; the aria-label still names it.- const noteRole = href ? ('doc-noteref' as const) : undefined;+ // `doc-noteref` is a link role and is not permitted on the inert span. Give+ // that span a supported naming role so the component-authored aria-label+ // still identifies number-only citations to assistive technology.+ const noteRole = href ? ('doc-noteref' as const) : ('group' as const);const linkProps = href? {href,