An open source design system that's fully customizable and agent ready
TypeScript
docs(spec): VisuallyHidden records its shipped contract as current (#8712)
Cindy Zhanga955a9a54582
diff --git a/packages/core/src/VisuallyHidden/VisuallyHidden.spec.md b/packages/core/src/VisuallyHidden/VisuallyHidden.spec.mdnew file mode 100644index 0000000000..aac13991da--- /dev/null+++ b/packages/core/src/VisuallyHidden/VisuallyHidden.spec.md@@ -0,0 +1,170 @@+---+schema_version: 3+template_version: 7+kind: component+id: component:VisuallyHidden+authority: current+archive_reason: null+superseded_by: null+approved_by: cixzhang+approved_at: 2026-10-27+owners: [cixzhang]+review_triggers: [public-api, behavior, accessibility]+verified_by:+ [+ .github/visual-baseline/manifest.json,+ packages/core/src/VisuallyHidden/VisuallyHidden.test.tsx,+ apps/storybook/stories/VisuallyHidden.stories.tsx,+ ]+modules: []+families: []+design_specs: []+architecture: [architecture:public-component-api]+contributing: []+system_specs: [spec:AST-009, spec:AST-071]+---++# VisuallyHidden component contract++## Contract at a glance++| Area | Contract |+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Public contract | A wrapper with required `children` and an optional `as` element; accessibility and data props pass through. It accepts no `className` or `style` and ignores `xstyle` today (FR3 gap, OQ1). |+| Behavior | Content is clipped from sight by a fixed style block no caller input can displace, and stays in the accessibility tree unless the caller passes `hidden`, `inert`, or `aria-hidden`. |+| End-user impact | Screen-reader users hear names and announcements that sighted users do not need to see. |+| Builder impact | None; the record describes shipped behavior. |+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. One implementation gap is listed under Current-state impact; OQ1 is open. |+| Review checks | Reject a `display: none` or `visibility: hidden` hide, a caller input that displaces the clip, or dropped `aria-*` passthrough. |+| Governing rules | `architecture:public-component-api/INV5,INV6,INV8`; `spec:AST-071` FR2. |++This table is a review projection; the body below is authoritative.++## Intent++VisuallyHidden exposes content to assistive technology while keeping it out of+sight: names for icon-only controls, live announcement regions, and+supplementary screen-reader context. It owns the hiding technique and the+guarantee that the hidden node cannot be styled visible.++## Compatibility and migration++- Released default preserved: `yes`+- Compatibility class: records shipped behavior; no public prop, default, or+ DOM output changes. `xstyle` is accepted by the type and ignored;+ `className` and `style` are not accepted; the styling surface is the FR3 gap (OQ1)+- Controlled/uncontrolled behavior: not applicable+- Migration decision: none++Consumer migration instructions belong in consumer docs and release notes.++## Current-state impact++- **Styling inputs not accepted (FR3).** VisuallyHidden drops `className` and+ `style` and ignores `xstyle`, so callers cannot style the element, where+ `architecture:public-component-api` INV6 and `spec:AST-071` FR2 have root+ styling inputs compose. The consumer docs plan to remove `xstyle`; OQ1+ decides whether the component conforms or INV6's owner records it as an+ exception.++## Ownership boundary++**Owns**++- The rendered element and its fixed clip style block.+- Passing accessibility, identity, data, and event props through.++**Does not own / non-goals**++- What the hidden content says and whether it is a live region — owned by the+ caller, through `children`, `as`, and ARIA props.+- Shared status announcements — owned by `spec:AST-086` and its shared channel.+- Theming — VisuallyHidden has no theming target.++## Public concepts++| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |+| ------- | -------------------------------------------------------------------------------------------------- | -------------------------------------- | ----------------------------------------- | ------- | -------------------------- | --------- | --------------------------------------------------------------------------------------------------------------- |+| Element | An intrinsic element, or a component that forwards `className` and `ref` to the element it renders | The rendered element, inline or block. | Always | `span` | `component:VisuallyHidden` | Stable | A component that does not forward `className` and `ref` renders its content unclipped, and the ref stays unset. |++## Behavioral and layout contract++| ID | Invariant | Basis |+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |+| FR1 | VisuallyHidden renders `children` in the element named by `as` (default `span`). Its own hiding keeps the content in the accessibility tree; a caller's `hidden`, `inert`, or `aria-hidden` passes through and removes it, by the caller's choice. | Current source and tests |+| FR2 | When `as` is an intrinsic element or forwards `className` to the element it renders, that element is absolutely positioned at the inline-start and block-start of its containing block, 1px by 1px with a −1px margin, no padding or border, clipped to an empty rectangle with hidden overflow, unwrapped, and ignores pointer events and selection. | Current source and tests |+| FR3 | `ref` reaches the element (for a component `as`, when it forwards `ref`), and supported `aria-*`, `role`, `id`, `data-*`, and event props reach it. The clip styles apply after every caller input, so nothing displaces the clip. Root styling inputs compose on the element (`architecture:public-component-api` INV6, `spec:AST-071` FR2). Implementation gap: `className` and `style` are not accepted and `xstyle` is ignored; the consumer docs plan to remove `xstyle`, and OQ1 decides whether VisuallyHidden conforms or becomes a recorded INV6 exception (Current-state impact). | Current source and tests |++### Allowed variation++- **AV1 — Element choice.** Callers choose an inline or block element, such as+ a `div` for block content or a live region.++### Representative states++| State | Required invariant | Allowed variation |+| ----------------- | ----------------------------------------------------------------------- | ----------------- |+| Icon-only label | Hidden `span` gives the control its accessible name. | Text. |+| Live region | Block element with caller `aria-live` stays hidden and announced. | Politeness. |+| Styling attempted | The clip still wins; caller styling has no effect today (FR3 gap, OQ1). | — |++### Transformation and precedence order++- **ORD1 — Props.** Caller props → fixed clip styles, so the clip wins.++### Performance and resources++- **PR1 — Static render.** VisuallyHidden holds no state and uses no hooks.++## Accessibility contract++- **AR1 — Perceivable to assistive technology.** Hiding uses clipping, never+ `display: none`, `visibility: hidden`, or `aria-hidden`, so the content is+ read and can name or describe other elements.+- **AR2 — Live regions and hiding by caller choice.** VisuallyHidden adds no+ role or live region of its own; a caller's `role`, `aria-live`, `hidden`,+ `inert`, and `aria-hidden` pass through.++## Design relationships++| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |+| ---------------- | --------------------------------------------------- | ------------------------ | -------------- | ------------------ |+| Hidden content | Present to assistive technology, absent from sight. | Current source and docs | Supporting | FR1–FR3, AR1, AR2 |++Theming: VisuallyHidden has no theming target, by design; a visible style on a+hidden node would defeat its purpose.++## Family and system relationships++- `architecture:public-component-api` owns passthrough, ref, and styling-input+ rules; FR3 applies INV5, INV6, and INV8 and records the INV6 gap.++## Verification map++| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| -------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |+| FR1, AR1 | `VisuallyHidden.test.tsx` render and icon-label tests | Default, `as`, icon-only control | Content leaving the accessibility tree or a lost accessible name fails. Gap: no test covers a caller `hidden`, `inert`, or `aria-hidden` passing through. | `audit:VisuallyHidden/a11y` |+| FR2 | `VisuallyHidden.test.tsx` clip-style test; stable visual baseline `core-visuallyhidden--default` | Default | A `hidden` attribute fails the unit test; content that becomes visible comes back changed in the visual baseline. Gap: no unit test asserts a clip declaration, although the test environment exposes them. | `audit:VisuallyHidden/behavior` |+| FR3, AR2 | `VisuallyHidden.test.tsx` `as`, ref, passthrough, and styling tests | `as` with `aria-live`; ref; `id`, `role`, `data-testid`; `className`, `style`, `xstyle` | A lost `aria-live`, a missed ref, or a dropped `id` or `role` fails. The styling tests pin today's dropped `className`, `style`, and `xstyle` attribute, which pins the recorded FR3 gap, not the contract. Gap: no test asserts that VisuallyHidden adds no role or live region of its own; the ref test still passes when a wrapper receives the ref; no test asserts other `aria-*` or event props; no test checks that the clip wins over caller styles; and no test covers a component `as` that does or does not forward `className` and `ref`. | `audit:VisuallyHidden/behavior` |+| PR1 | Source review | Every state | Gap: no automated check fails if VisuallyHidden adds state or a hook. | `audit:VisuallyHidden/behavior` |+| AR1 | Accessibility-tree evidence (`spec:AST-009` FR3) | Icon-only label; live region | Gap: no accessibility-tree check proves the hidden content stays in the tree; the unit tests query the DOM. | `audit:VisuallyHidden/a11y` |++## Decision log++None recorded. The record describes shipped behavior; OQ1 is open.++## Open questions++- **OQ1 — Should VisuallyHidden accept root styling inputs?** (`human-api`)+ `architecture:public-component-api` INV6 has root styling inputs compose+ unless a family decision names an exception, and the consumer docs plan to+ remove `xstyle`; until an owner decides, the styling-free surface is the FR3+ gap. If styling-free is a deliberate exception, INV6's owner+ records it (with a `spec:AST-071` known-gap entry) and FR3 links it, and+ callers keep no way to style the element. If composition is the direction,+ FR3 stays as written and a conforming implementation closes the gap.++## Content boundary++This file does not duplicate consumer prop tables/examples, current audit+results, implementation steps, or family/system rules. It links to their owners.