Addon A11y: Prevent setting highlights for old results

[ghengeveld]

Closes #32135

What I did

Prevent setting highlights for old a11y results. When switching stories, the a11y results from the previous story would apply highlights to the new story before the a11y results of the new story were ready, causing incorrect highlights to briefly appear. This is resolved by preventing a11y highlights from being set until the report is either running or ready (i.e. not initial).

Before:

Note how the outline buttons are already highlighted before the others.

Screen.Recording.2025-08-01.at.16.47.46.mov

After:

Screen.Recording.2025-08-01.at.16.45.45.mov

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

Have two stories, one of which renders a component in multiple variants, and the other renders one identical variant and one whole new variant. When switching between the stories, the identical variant should yield identical classnames. Now enable a11y highlights (e.g. passing) and switch between the stories. All highlights should clear before new highlights are added. Previously the identical component would "inherit" the highlight from the other story due to the identical classname.

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 pull request has been released as version 0.0.0-pr-32178-sha-9b4c95c0. Try it out in a new sandbox by running npx [email protected] sandbox or in an existing project with npx [email protected] upgrade.

More information

Published version	0.0.0-pr-32178-sha-9b4c95c0
Triggered by	@valentinpalkovic
Repository	storybookjs/storybook
Branch	clear-a11y-highlights-on-changed-story
Commit	9b4c95c0
Datetime	Thu Aug 14 11:01:51 UTC 2025 (1755169311)
Workflow run	16963328850

To request a new release of this pull request, mention the @storybookjs/core team.

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

Greptile Summary

This PR fixes a UX issue in the Accessibility addon where highlights from the previous story would briefly flash on a new story before the new story's accessibility analysis completed. The change modifies the A11yContextProvider component in A11yContext.tsx to add a guard that prevents setting highlights when the addon status is 'initial'.

The implementation adds an isInitial boolean flag that checks if the current status is 'initial', and updates the highlighting useEffect to return early when !highlighted || isInitial. This ensures highlights are only applied when the addon has progressed to either 'running' or 'ready' status, preventing stale highlights from appearing during story transitions.

Additionally, the PR adds defensive checks around HIGHLIGHT event emissions to only emit events when there are actual selectors to highlight, avoiding unnecessary empty highlight events. The useEffect dependency array is updated to include the isInitial flag to ensure proper re-evaluation when the status changes.

This change integrates well with the existing accessibility addon architecture, which already manages different status states ('initial', 'running', 'ready') throughout the accessibility testing lifecycle. The fix addresses the timing issue without disrupting the core functionality of the accessibility analysis and reporting system.

Confidence score: 4/5

• This is a focused bug fix that addresses a specific UX issue with minimal risk of breaking existing functionality
• The implementation follows existing patterns in the codebase and adds appropriate safeguards
• The change requires manual testing to verify the fix works as intended, as the issue involves timing and visual behavior during story transitions

[greptile-apps]

_{1 file reviewed, no comments}

_{Edit Code Review Bot Settings | Greptile}

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 9b4c95c

Command	Status	Duration	Result
nx run-many -t build --parallel=3	✅ Succeeded	1m 7s	View ↗

---

☁️ Nx Cloud last updated this comment at 2025-08-01 14:58:28 UTC

[storybook-app-bot]

Package Benchmarks

^{Commit: 9b4c95c, ran on 1 August 2025 at 14:44:34 UTC}

The following packages have significant changes to their size or dependencies:

storybook

	Before	After	Difference
Dependency count	51	51	0
Self size	41.75 MB	41.37 MB	🎉 -374 KB 🎉
Dependency size	18.13 MB	18.13 MB	0 B
Bundle Size Analyzer	Link	Link

sb

	Before	After	Difference
Dependency count	52	52	0
Self size	1 KB	1 KB	0 B
Dependency size	59.88 MB	59.51 MB	🎉 -374 KB 🎉
Bundle Size Analyzer	Link	Link

@storybook/cli

	Before	After	Difference
Dependency count	220	220	0
Self size	585 KB	585 KB	0 B
Dependency size	104.34 MB	103.97 MB	🎉 -374 KB 🎉
Bundle Size Analyzer	Link	Link

@storybook/codemod

	Before	After	Difference
Dependency count	189	189	0
Self size	31 KB	31 KB	0 B
Dependency size	88.43 MB	88.06 MB	🎉 -374 KB 🎉
Bundle Size Analyzer	Link	Link

[ndelangen]

@ghengeveld Please add manual testing instruction asap