A11y config based on global variables?

[hgarfinkle]

Summary

I have a Storybook project that offers a "high-contrast mode", which is controlled through an option in globalTypes in my preview.tsx. I'm working on setting up accessibility testing for my stories in that project. I only want to report "insufficient contrast" violations when in high-contrast mode, it doesn't bother me if contrast is lower on normal mode. Thus, what I want is to be able to change the a11y config in my preview.tsx to disable color-contrast violations when contrast-mode === 'standard'. Is this achievable without doing something hacky?

Additional information

No response

Create a reproduction

No response

[dosubot[bot]]

Hi @hgarfinkle! I'm Dosu and I'm helping the Storybook team.

The parameters.a11y configuration is static — it only accepts plain objects and can't reference globals at runtime [1]. There's no built-in way to conditionally toggle axe rules like color-contrast based on a global variable's current value.

Here are a couple of approaches you could consider:

• Separate stories per mode: Create variants of your stories (e.g., Default and HighContrast) and only enable the color-contrast rule on the high-contrast variant via story-level parameters:

  export const HighContrast: Story = {
    globals: { 'contrast-mode': 'high' },
    parameters: {
      a11y: {
        config: {
          rules: [{ id: 'color-contrast', enabled: true }],
        },
      },
    },
  };
  
  export const Standard: Story = {
    globals: { 'contrast-mode': 'standard' },
    parameters: {
      a11y: {
        config: {
          rules: [{ id: 'color-contrast', enabled: false }],
        },
      },
    },
  };

  This is the cleanest solution if you're running a11y checks in CI (e.g., via @storybook/addon-vitest), since each story gets its own static config.

• Manual mode: You can set globals.a11y.manual: true to prevent automatic checks, but that only controls when checks run — not which rules apply [1].

Dynamic rule configuration based on globals isn't currently supported. If the separate-stories approach doesn't fit your workflow, this would be a good candidate for a feature request on the repo.

Would you like more detail on structuring stories for per-mode a11y testing?

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[lizuju]

I would treat this as not supported by the addon today, at least for the automatic a11y run.

The a11y preview hook gets both parameters and globals, but the rule config comes only from parameters.a11y:

const a11yParameter = parameters.a11y
const a11yGlobals = globals.a11y
...
await run(a11yParameter, storyId)

globals.a11y.manual is checked, but only to decide whether the automatic run should happen. The current global values are not passed into parameters.a11y.config, and run() just calls axe.configure(config) with the already-resolved parameter object. So a toolbar global like contrast-mode cannot currently switch the color-contrast rule for the same story run.

The least hacky setup is to make the modes separate story variants or separate test entries, and put the a11y rule on those static variants:

export const Standard = {
  globals: { 'contrast-mode': 'standard' },
  parameters: {
    a11y: {
      config: {
        rules: [{ id: 'color-contrast', enabled: false }],
      },
    },
  },
}

export const HighContrast = {
  globals: { 'contrast-mode': 'high' },
  parameters: {
    a11y: {
      config: {
        rules: [{ id: 'color-contrast', enabled: true }],
      },
    },
  },
}

That also behaves better in CI, because each story has a deterministic static a11y config. If the goal is an interactive toolbar switch inside one story, you would need a feature change in the addon: something like a function-valued a11y config or passing story globals into the a11y runner before axe.configure().