Skip to content

[Bug]: addon-a11y runs in docs mode and slows down large docs pages #30975

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kroeder opened this issue Mar 28, 2025 · 7 comments · May be fixed by #30976
Open

[Bug]: addon-a11y runs in docs mode and slows down large docs pages #30975

kroeder opened this issue Mar 28, 2025 · 7 comments · May be fixed by #30976

Comments

@kroeder
Copy link
Member

kroeder commented Mar 28, 2025

Describe the bug

We recently discovered in our internal Storybook that a large story in docs mode with a relatively complex component (many elements to check for axe.js) got significantly slower to a point where axe.js is a browser blocking task. Checking each story in story mode runs fast but in docs mode, it is just too much for axejs it seems. To confirm this, I disabled addon-a11y and the story was instantly rendered with no input lags.

We can't tell why addon-a11y suddenly is slow for this story (multiple seconds input lag until the page is fully loaded) but one solution would be to just not run addon-a11y in docs mode. Is there any reason it should run in docs mode? There are no controls to check for a11y violations and to me, it seems it would only make sense to have it turned on in story mode.

If you agree, I'll provide a small PR to fix this.

Reproduction link

https://stackblitz.com/edit/github-q96uz5cy?file=src%2Fstories%2FButton.mdx

Reproduction steps

  1. Go to stackblitz example
  2. Open dev console
  3. Open button story in docs mode
  4. See axe timing logs

System

System:
    OS: macOS 15.3.2
    CPU: (8) arm64 Apple M1 Pro
    Shell: 5.9 - /bin/zsh
  Binaries:
    Node: 22.13.1 - ~/.nvm/versions/node/v22.13.1/bin/node
    Yarn: 1.22.22 - /opt/homebrew/bin/yarn
    npm: 10.9.2 - ~/.nvm/versions/node/v22.13.1/bin/npm <----- active
    pnpm: 9.15.4 - ~/.nvm/versions/node/v22.13.1/bin/pnpm
  Browsers:
    Chrome: 134.0.6998.166
    Edge: 134.0.3124.85
    Safari: 18.3.1
  npmPackages:
    @storybook/addon-a11y: 8.6.11 => 8.6.11 
    @storybook/addon-essentials: 8.6.11 => 8.6.11 
    @storybook/addon-interactions: 8.6.11 => 8.6.11 
    @storybook/angular: 8.6.11 => 8.6.11 
    @storybook/blocks: ^8.6.11 => 8.6.11 
    @storybook/icons: ^1.4.0 => 1.4.0 
    @storybook/test: ^8.6.11 => 8.6.11 
    @storybook/theming: ^8.6.11 => 8.6.11 
    chromatic: ^11.12.6 => 11.12.6 
    eslint-plugin-storybook: ^0.10.1 => 0.10.1 
    storybook: ^8.4.2 => 8.6.11

Additional context

No response

Copy link
Contributor

greptile-apps bot commented Mar 28, 2025

** Disclaimer** This information might be inaccurate, due to it being generated automatically
In packages/addon-a11y/src/register.ts, wrap the axe initialization so it only runs in story mode. For example, add a helper:

function isDocsMode() {
return Boolean(document.body.getAttribute('data-is-docs'));
}

Then conditionally init axe:

if (!isDocsMode()) {
// Existing axe.js initialization
}

This disables axe.js in docs mode.

About Greptile

This response provides a starting point for your research, not a precise solution.

Help us improve! Please leave a 👍 if this is helpful and 👎 if it is irrelevant.

Edit Issue Bot Settings · Greptile

@kroeder kroeder linked a pull request Mar 28, 2025 that will close this issue
8 tasks
@kroeder
Copy link
Member Author

kroeder commented Mar 28, 2025

Since the change was no effort (besides having tons of issues with the Storybook repo setup...) I already created a PR.
Feel free to deny the PR, if you think running addon-a11y in docs mode make sense.

I'll try to create a repo with a relatively complex component (let's hope AI can help me out..) and try to reproduce the slow, if so

@smlimasu
Copy link

smlimasu commented Mar 28, 2025

Can confirm the same issue, it came suddenly in the last few weeks. One table heavy docs page freezed completely. Seeing axe in the performance panel as the culprit.

I've found that instead of disabling the complete addon, another workaround was to set the globals.a11y.manual to true, so that the accessibility addon panel can still be run via click on the little button in the story view.

Hint: We had the issues suddenly without upgrade being on SB Angular 8.5.5 for a while, but persisted after upgrading to 8.6.10

@guicara
Copy link

guicara commented Apr 3, 2025

We’re experiencing the same issue with large stories/components (like a MUI Table).

The browser almost freezes when rendering the story. Hover effects and interactions appear tens of seconds, making it nearly unusable.

Option 1:

Disabling addon-a11y "resolves" the issue for us as well.

const config: StorybookConfig = {
  addons: [
    // '@storybook/addon-a11y',
    ...
  ],
  ...
};

Option 2:

Setting globals.a11y.manual to true (as suggested by @smlimasu) fixes the issue.

const preview: Preview = {
  parameters: {
    globals: {
      a11y: {
        // Optional flag to prevent the automatic check
        // It fixes the issue with the a11y addon freezing
        // cf. https://github.com/storybookjs/storybook/issues/30975
        manual: true,
      },
    },
  }
}

However, according to @valentinpalkovic 's comment here, this setting will be removed in v9. So it's probably not a future-proof solution.

Not relevant anymore, since parameters.a11y.manual does not exist anymore in SB 9.0

@shilman
Copy link
Member

shilman commented Apr 3, 2025

@guicara Typo in your comment. I think you mean globals.a11y.manual not parameters.globals.a11y.manual.

globals.a11y.manual will not be removed in 9. parameters.a11y.manual will. Sorry for the confusion.

@guicara
Copy link

guicara commented Apr 3, 2025

@shilman Indeed, you're right!

@hernan-yadiel
Copy link

I saw this add-on clearly blocking the main thread on Chrome's Performance profiler. TY!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

5 participants