Request Demo

Support

How can we help you?

Get answers to all your Stark-related questions with
step-by-step guides from our Support center.

Using the Storybook Addon

Get Stark's comprehensive WCAG Audit right in your Storybook panel.

Quick-start with an AI prompt

Copy this into your AI coding agent of choice to get set up without having to work through the steps below by hand.

Set up Stark's Storybook addon and CLI scanning in this project.

Facts to use as-is (don't guess at flags or invent options):
- Package: `@stark-lab-inc/storybook-addon-stark`, installed as a dev dependency from
  the public npm registry.
- Register it in the `addons` array in `.storybook/main.*`.
- The CLI ships inside the addon — no separate install:
      npx stark-scan-storybook
  It builds your Storybook, iterates every story, scans each story frame (not the
  surrounding Storybook UI), and uploads results to Stark.
- It needs Playwright's Chromium to run scans, and will prompt to install it
  (`npx playwright install chromium`) if it's missing.
- Token comes from `--stark-token <token>` or the `STARK_TOKEN` environment variable.
- CLI options, and only these: `--help`, `--storybook-script` (default: `storybook build`),
  `--out-dir` (default: `storybook-static`), `--scan-variants`, `--include`,
  `--skip-build`, `--port`, `--silent`.
- `--include` matches against both story title and file path — e.g. "Button",
  "Components/Button*", "src/components/**".
- `--scan-variants` scans each story once per enumerable control value (boolean, select,
  radio), grouping results by story.
- There is no `--name` flag and no dry-run mode. The asset name is set once in the Stark
  UI, and every CLI run uploads. Don't look for a way to scan without sending results.
- My Stark token: PASTE_YOUR_TOKEN_HERE

Steps:
1. Report the setup before changing anything: Storybook version, which config file
   exists (`.storybook/main.ts`, `.js`, `.cjs`, `.mjs`), whether it uses ESM or CommonJS
   export syntax, and roughly how many stories are in the repo.
2. Install the addon as a dev dependency.
3. Add it to the existing `addons` array — merge, don't replace, and match the file's
   existing export style.
4. Put the token in `.env` as `STARK_TOKEN` rather than passing `--stark-token` on the
   command line, and verify `.env` is gitignored before writing it. If it isn't, stop
   and tell me.
5. Before the first scan: tell me whether Playwright's Chromium is already installed. If
   it isn't, tell me the download is needed and wait — don't install it unprompted.
6. Run a narrow first scan using `--include` against a single component directory, not
   the whole library. Confirm the target with me first.
7. Report what came back, grouped by story: violations, potentials, passed.

Once I've reviewed:
8. Propose a full run. If the story count is large, tell me the expected scan count
   before running, and flag that `--scan-variants` multiplies it by the number of
   enumerable control values per story — don't enable it without asking.
9. Propose a CI step using `--skip-build` against an already-built `storybook-static`
   plus `--silent`, with the token as a secret.

Constraints: use only the flags listed above, don't add Storybook config the docs don't
describe, and if the build or scan fails show me the real output before proposing a fix.

With Stark's Storybook Addon, you can quickly run WCAG Audits right from within your Storybook panels, and test your designs against all of Stark's vision simulations.

Installing the Add-on

Run the following command to install the addon in your Storybook repo:

npm install -D @stark-lab-inc/storybook-addon-stark

Then include Stark's Storybook Addon in your addons list:

// .storybook/main.ts
export default {
  addons: ["@stark-lab-inc/storybook-addon-stark"],
};

Using the Addon

There are two main ways to use the Stark addon:

Vision Simulator

  1. At the top of the Storybook preview, click the Stark logo and select a Vision Simulation from the dropdown.
  2. To remove the simulation, simply select Reset Vision Simulation from the dropdown.

WCAG Audit Panel

  1. In the Storybook Panels, select Stark.
  2. Stark will automatically audit the Storybook preview frame for accessibility issues.
  3. Change between Violations, Potentials, and Passed test results by using the tabs at the top.
  4. More information on how to fix issues can be found by clicking the "WCAG Explained" links below each code block.

Using the CLI

The CLI tool in the Stark Storybook addon allows you to push complete WCAG audit results up to Stark. This is typically much quicker than setting up a CI/CD workflow, as Stark will just automatically iterate through all of your stories and upload the results. It's built right into the addon, so if you followed the installation steps above, you can get started:

Begin in Stark

  1. In the project that you'd like Storybook results to be sent to, scroll down to where it says Add Storybook.
  2. Upon clicking that, you'll see two fields: a Stark token you'll need when you run the CLI tool and a name you want to give the asset for easy reference.
  3. Once you've copied out that token and hit the Save Storybook Integration button, we can jump over to using the CLI tool.

Sending results up via the CLI

  1. Back in your terminal, simply run the following command, making sure to put in your unique project token:
    npx stark-scan-storybook --stark-token stark_1234567890
  2. Running that command will automatically build your Storybook and iterate through each of your stories and run a scan. Don't worry, it'll only scan your story frame and not all of the Storybook UI. It may ask you to install Playwright (to run the scans) if you don't have it installed already:
    npx playwright install chromium
  3. Reminder that you can put your Stark token into an environment variable (STARK_TOKEN).

Options
You can pass in the following (optional) parameters:

  • --help: View some help instructions as well as all of the parameters you can pass in.
  • --storybook-script: Your custom script cmd if it differs from the default. (Default: storybook build)
  • --out-dir: Built Storybook output directory (Default: storybook-static)
  • --scan-variants: Scan each story with all enumerable control values (boolean, select, radio). Results are grouped by story.
  • --include: Only scan stories matching the pattern (matches title and file path). Examples: "Button", "Components/Button*", "src/components/**" 
  • --skip-build: Skip the build step and use an existing out-dir. Helpful if you've already built your Storybook previously in other scripts/runs.
  • --port: Static server port (default: auto-detect)
  • --silent: Suppress all output except errors

Have any questions about using our Storybook Addon? Suggestions or feedback? Don’t hesitate to reach out to us at support@getstark.co.

Go back to articles