Docs: Fix A11y manual setup example #33456

jonniebigodes · 2026-01-02T17:52:28Z

Follows up on #32903

What I did

With this pull request, the A11y documentation, specifically the manual setup example, was updated to reflect the latest changes in Storybook. The example was previously outdated and no longer accurate, as it mentioned deprecated APIs and packages that are no longer available since version 9.0 and later. With this change, we ensure that the documentation aligns with the current state of Storybook and provides accurate guidance for users looking to set up A11y testing in their projects.

What was done:

Updated the A11y documentation's example to reflect the correct APIs and configurations for the users

@valentinpalkovic, when you have a moment, could you take a look at this, as you were the last person to update them, and provide any feedback?

Thanks in advance

Checklist for Contributors

Testing

The changes in this PR are covered in the following automated tests:

stories
unit tests
integration tests
end-to-end tests

Manual testing

This is a documentation only change, no testing is required

Documentation

Add or update documentation reflecting your changes
If you are deprecating/removing a feature, make sure to update
MIGRATION.MD

Checklist for Maintainers

When this PR is ready for testing, make sure to add ci:normal, ci:merged or ci:daily GH label to it to run a specific set of sandboxes. The particular set of sandboxes can be found in code/lib/cli-storybook/src/sandbox-templates.ts
Make sure this PR contains one of the labels below:
Available labels
- bug: Internal changes that fixes incorrect behavior.
- maintenance: User-facing maintenance tasks.
- dependencies: Upgrading (sometimes downgrading) dependencies.
- build: Internal-facing build tooling & test updates. Will not show up in release changelog.
- cleanup: Minor cleanup style change. Will not show up in release changelog.
- documentation: Documentation only changes. Will not show up in release changelog.
- feature request: Introducing a new feature.
- BREAKING CHANGE: Changes that break compatibility in some way with current major version.
- other: Changes that don't fit in the above categories.

🦋 Canary release

This PR does not have a canary release associated. You can request a canary release of this pull request by mentioning the @storybookjs/core team here.

core team members can create a canary release here or locally with gh workflow run --repo storybookjs/storybook publish.yml --field pr=<PR_NUMBER>

Summary by CodeRabbit

Documentation
- Updated accessibility testing guide with framework-agnostic configuration approach for improved compatibility across different development frameworks
- Simplified vitest accessibility testing setup with streamlined initialization and enhanced annotations configuration
- Improved code examples with better formatting for clearer implementation guidance

_{✏️ Tip: You can customize this high-level summary in your review settings.}

coderabbitai · 2026-01-02T17:56:40Z

📝 Walkthrough

Walkthrough

Documentation update to the Vitest accessibility testing setup example that makes the manual configuration framework-agnostic, introduces a local preview import in the annotations array, and removes a beforeAll hook invocation.

Changes

Cohort / File(s)	Summary
Vitest Accessibility Setup Documentation `docs/writing-tests/accessibility-testing.mdx`	Updated manual setup snippet to use `@storybook/your-framework` placeholder instead of renderer-specific imports, added local preview import to annotations array alongside a11y addon annotations, and removed `beforeAll` hook call; added code fence title attribute for TypeScript block

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

Docs: Fix annotation imports in the A11y testing documentation #33370 — Modifies the same Vitest accessibility setup snippet in documentation with changes to how preview and a11y annotations are imported and composed
Docs: Update CLI reference, add nextjs-vite guide #32903 — Updates the manual Vitest accessibility setup snippet in the same documentation file, making it framework-agnostic and adjusting the annotation composition pattern
Docs: Vitest plugin adjustments #32843 — Modifies Storybook Vitest setup documentation snippets with similar changes to setProjectAnnotations and preview import patterns

📜 Recent review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 7f193d3 and 80074f1.

📒 Files selected for processing (1)

docs/writing-tests/accessibility-testing.mdx

🧰 Additional context used

🧠 Learnings (13)

📓 Common learnings

Learnt from: Sidnioulz
Repo: storybookjs/storybook PR: 32458
File: code/core/src/components/components/Tabs/Tabs.stories.tsx:222-227
Timestamp: 2025-11-05T09:36:55.944Z
Learning: Repo: storybookjs/storybook PR: 32458 — In code/core/src/components/components/Button/Button.tsx (React/TypeScript), ButtonProps includes ariaLabel?: string | false and the component maps it to the DOM aria-label. Convention: ariaLabel is mandatory on all Button usages — provide a descriptive string for icon-only buttons; set ariaLabel=false when the button’s children already serve as the accessible name. Do not suggest using a raw aria-label prop on Button call sites.

Learnt from: CR
Repo: storybookjs/storybook PR: 0
File: .cursor/rules/spy-mocking.mdc:0-0
Timestamp: 2025-11-24T17:49:59.279Z
Learning: Applies to **/*.test.{ts,tsx,js,jsx} : Avoid inline mock implementations within test cases in Vitest tests

Learnt from: CR
Repo: storybookjs/storybook PR: 0
File: .cursor/rules/spy-mocking.mdc:0-0
Timestamp: 2025-11-24T17:49:59.279Z
Learning: Applies to **/*.test.{ts,tsx,js,jsx} : Avoid mock implementations outside of `beforeEach` blocks in Vitest tests

Learnt from: CR
Repo: storybookjs/storybook PR: 0
File: .cursor/rules/spy-mocking.mdc:0-0
Timestamp: 2025-11-24T17:49:59.279Z
Learning: Applies to **/*.test.{ts,tsx,js,jsx} : Document complex mock behaviors in Vitest tests

Learnt from: CR
Repo: storybookjs/storybook PR: 0
File: .cursor/rules/spy-mocking.mdc:0-0
Timestamp: 2025-11-24T17:49:59.279Z
Learning: Applies to **/*.test.{ts,tsx,js,jsx} : Implement mock behaviors in `beforeEach` blocks in Vitest tests

Learnt from: CR
Repo: storybookjs/storybook PR: 0
File: .cursor/rules/spy-mocking.mdc:0-0
Timestamp: 2025-11-24T17:49:59.279Z
Learning: Applies to **/*.test.{ts,tsx,js,jsx} : Avoid mocking only a subset of required dependencies in Vitest tests

Learnt from: CR
Repo: storybookjs/storybook PR: 0
File: .cursor/rules/spy-mocking.mdc:0-0
Timestamp: 2025-11-24T17:49:59.279Z
Learning: Applies to **/*.test.{ts,tsx,js,jsx} : Keep mock implementations simple and focused in Vitest tests

Learnt from: CR
Repo: storybookjs/storybook PR: 0
File: .cursorrules:0-0
Timestamp: 2025-11-24T17:49:31.838Z
Learning: Applies to code/vitest.workspace.ts : Vitest configuration is centralized in `code/vitest.workspace.ts` for workspace setup

Learnt from: CR
Repo: storybookjs/storybook PR: 0
File: .cursor/rules/spy-mocking.mdc:0-0
Timestamp: 2025-11-24T17:49:59.279Z
Learning: Applies to **/*.test.{ts,tsx,js,jsx} : Mock all required properties and methods that the test subject uses in Vitest tests

Learnt from: CR
Repo: storybookjs/storybook PR: 0
File: .cursor/rules/spy-mocking.mdc:0-0
Timestamp: 2025-11-24T17:49:59.279Z
Learning: Applies to **/*.test.{ts,tsx,js,jsx} : Mock at the highest level of abstraction needed in Vitest tests

Learnt from: CR
Repo: storybookjs/storybook PR: 0
File: .cursor/rules/spy-mocking.mdc:0-0
Timestamp: 2025-11-24T17:49:59.279Z
Learning: Applies to **/*.test.{ts,tsx,js,jsx} : Group related mocks together in Vitest tests

📚 Learning: 2025-11-24T17:49:59.279Z

Learnt from: CR
Repo: storybookjs/storybook PR: 0
File: .cursor/rules/spy-mocking.mdc:0-0
Timestamp: 2025-11-24T17:49:59.279Z
Learning: Applies to **/*.test.{ts,tsx,js,jsx} : Avoid inline mock implementations within test cases in Vitest tests

Applied to files:

docs/writing-tests/accessibility-testing.mdx

📚 Learning: 2025-11-24T17:49:59.279Z

Learnt from: CR
Repo: storybookjs/storybook PR: 0
File: .cursor/rules/spy-mocking.mdc:0-0
Timestamp: 2025-11-24T17:49:59.279Z
Learning: Applies to **/*.test.{ts,tsx,js,jsx} : Avoid mocking only a subset of required dependencies in Vitest tests

Applied to files:

docs/writing-tests/accessibility-testing.mdx

📚 Learning: 2025-11-24T17:49:59.279Z

Learnt from: CR
Repo: storybookjs/storybook PR: 0
File: .cursor/rules/spy-mocking.mdc:0-0
Timestamp: 2025-11-24T17:49:59.279Z
Learning: Applies to **/*.test.{ts,tsx,js,jsx} : Avoid mock implementations outside of `beforeEach` blocks in Vitest tests

Applied to files:

docs/writing-tests/accessibility-testing.mdx

📚 Learning: 2025-11-24T17:49:59.279Z

Learnt from: CR
Repo: storybookjs/storybook PR: 0
File: .cursor/rules/spy-mocking.mdc:0-0
Timestamp: 2025-11-24T17:49:59.279Z
Learning: Applies to **/*.test.{ts,tsx,js,jsx} : Document complex mock behaviors in Vitest tests

Applied to files:

docs/writing-tests/accessibility-testing.mdx

📚 Learning: 2025-11-24T17:49:59.279Z

Learnt from: CR
Repo: storybookjs/storybook PR: 0
File: .cursor/rules/spy-mocking.mdc:0-0
Timestamp: 2025-11-24T17:49:59.279Z
Learning: Applies to **/*.test.{ts,tsx,js,jsx} : Keep mock implementations simple and focused in Vitest tests

Applied to files:

docs/writing-tests/accessibility-testing.mdx

📚 Learning: 2025-11-05T09:36:55.944Z

Learnt from: Sidnioulz
Repo: storybookjs/storybook PR: 32458
File: code/core/src/components/components/Tabs/Tabs.stories.tsx:222-227
Timestamp: 2025-11-05T09:36:55.944Z
Learning: Repo: storybookjs/storybook PR: 32458 — In code/core/src/components/components/Button/Button.tsx (React/TypeScript), ButtonProps includes ariaLabel?: string | false and the component maps it to the DOM aria-label. Convention: ariaLabel is mandatory on all Button usages — provide a descriptive string for icon-only buttons; set ariaLabel=false when the button’s children already serve as the accessible name. Do not suggest using a raw aria-label prop on Button call sites.

Applied to files:

docs/writing-tests/accessibility-testing.mdx

📚 Learning: 2025-11-24T17:49:59.279Z

Learnt from: CR
Repo: storybookjs/storybook PR: 0
File: .cursor/rules/spy-mocking.mdc:0-0
Timestamp: 2025-11-24T17:49:59.279Z
Learning: Applies to **/*.test.{ts,tsx,js,jsx} : Implement mock behaviors in `beforeEach` blocks in Vitest tests

Applied to files:

docs/writing-tests/accessibility-testing.mdx

📚 Learning: 2025-11-24T17:49:59.279Z

Learnt from: CR
Repo: storybookjs/storybook PR: 0
File: .cursor/rules/spy-mocking.mdc:0-0
Timestamp: 2025-11-24T17:49:59.279Z
Learning: Applies to **/*.test.{ts,tsx,js,jsx} : Mock all required properties and methods that the test subject uses in Vitest tests

Applied to files:

docs/writing-tests/accessibility-testing.mdx

📚 Learning: 2025-11-05T09:38:47.712Z

Learnt from: Sidnioulz
Repo: storybookjs/storybook PR: 32458
File: code/core/src/components/components/Select/Select.tsx:200-204
Timestamp: 2025-11-05T09:38:47.712Z
Learning: Repo: storybookjs/storybook — Guidance: Until Storybook 11 is released, do not suggest using React.useId anywhere (e.g., in code/core/src/components/components/Select/Select.tsx) to maintain compatibility with React 17 runtimes. Prefer advising: accept a caller-provided props.id and, if needed, generate a client-only fallback id to minimize SSR hydration issues — but avoid useId. Resume prompting for useId after Storybook 11.

Applied to files:

docs/writing-tests/accessibility-testing.mdx

📚 Learning: 2025-11-05T09:37:25.920Z

Learnt from: Sidnioulz
Repo: storybookjs/storybook PR: 32458
File: code/core/src/components/components/tooltip/WithTooltip.tsx:54-96
Timestamp: 2025-11-05T09:37:25.920Z
Learning: Repo: storybookjs/storybook — In code/core/src/components/components/tooltip/WithTooltip.tsx, the legacy WithTooltip implementation is intentionally reintroduced for backward compatibility and is deprecated; maintainers (per Sidnioulz) do not want maintenance or improvements on it. Prefer WithTooltipNew/Popover; avoid suggesting changes to WithTooltip.* going forward.

Applied to files:

docs/writing-tests/accessibility-testing.mdx

📚 Learning: 2025-09-24T09:39:39.233Z

Learnt from: ndelangen
Repo: storybookjs/storybook PR: 32507
File: code/core/src/manager/globals/globals-module-info.ts:25-33
Timestamp: 2025-09-24T09:39:39.233Z
Learning: In Storybook, storybook/actions/decorator is a preview-only entrypoint and should not be included in manager globals configuration. The duplicatedKeys array in code/core/src/manager/globals/globals-module-info.ts is specifically for manager-side externalization, not preview entrypoints.

Applied to files:

docs/writing-tests/accessibility-testing.mdx

📚 Learning: 2025-12-22T22:03:40.123Z

Learnt from: CR
Repo: storybookjs/storybook PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-22T22:03:40.123Z
Learning: Applies to code/{renderers}/**/*.{ts,tsx,js,jsx} : Use `logger` from `storybook/internal/client-logger` for client-side logging in browser code

Applied to files:

docs/writing-tests/accessibility-testing.mdx

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

GitHub Check: Core Unit Tests, windows-latest

🔇 Additional comments (1)

docs/writing-tests/accessibility-testing.mdx (1)

53-64: Documentation is accurate and ready to merge.

The example correctly shows the framework-agnostic setup with valid package names. All referenced framework packages (@storybook/react-vite, @storybook/nextjs-vite) and the a11y addon exist and are current. The pattern matches Storybook v10.1.11's setup requirements.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai · 2026-01-02T17:57:52Z

Caution

Review failed

The head commit changed during the review from 80074f1 to 7cc26fd.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai · 2026-01-02T17:57:52Z

Caution

Review failed

The head commit changed during the review from 80074f1 to 7cc26fd.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Docs: Fix A11y manual setup example

80074f1

jonniebigodes requested a review from valentinpalkovic January 2, 2026 17:52

jonniebigodes self-assigned this Jan 2, 2026

jonniebigodes added the documentation label Jan 2, 2026

jonniebigodes requested a review from kylegach as a code owner January 2, 2026 17:52

jonniebigodes added the ci:docs Run the CI jobs for documentation checks only. label Jan 2, 2026

Merge branch 'next' into docs_fix_a11y_manual_config

7cc26fd

jonniebigodes added 3 commits January 4, 2026 19:56

Merge branch 'next' into docs_fix_a11y_manual_config

994719e

Merge branch 'next' into docs_fix_a11y_manual_config

ac6dafa

Merge branch 'next' into docs_fix_a11y_manual_config

dc24243

jonniebigodes merged commit c88b660 into next Jan 9, 2026
14 checks passed

jonniebigodes deleted the docs_fix_a11y_manual_config branch January 9, 2026 22:03

github-actions bot mentioned this pull request Jan 9, 2026

Release: Prerelease 10.2.0-alpha.15 #33489

Open

17 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Docs: Fix A11y manual setup example #33456

Docs: Fix A11y manual setup example #33456

Uh oh!

jonniebigodes commented Jan 2, 2026 •

edited

Loading

Uh oh!

coderabbitai bot commented Jan 2, 2026

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Uh oh!

coderabbitai bot commented Jan 2, 2026

Review failed

Uh oh!

coderabbitai bot commented Jan 2, 2026

Review failed

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Docs: Fix A11y manual setup example #33456

Docs: Fix A11y manual setup example #33456

Uh oh!

Conversation

jonniebigodes commented Jan 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What I did

Checklist for Contributors

Testing

The changes in this PR are covered in the following automated tests:

Manual testing

Documentation

Checklist for Maintainers

🦋 Canary release

Summary by CodeRabbit

Uh oh!

coderabbitai bot commented Jan 2, 2026

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Uh oh!

coderabbitai bot commented Jan 2, 2026

Review failed

Uh oh!

coderabbitai bot commented Jan 2, 2026

Review failed

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jonniebigodes commented Jan 2, 2026 •

edited

Loading