@accesslint/storybook-addon 0.6.9 → 0.8.0

package/README.md

@@ -7,7 +7,6 @@ Catch accessibility violations in your Storybook stories as you develop. Powered
 
 <img width="637" height="414" alt="Storybook screenshot with alt text violation in the details of the AccessLint tab" src="https://github.com/user-attachments/assets/01d2de92-0769-4564-8971-f6edc1986010" />
 
-
 ## Getting Started
 
 ```sh
@@ -18,52 +17,138 @@ Add the addon to your `.storybook/main.ts` (or `.storybook/main.js`):
 
 ```ts
 const config = {
-  addons: ["@storybook/addon-vitest", "@accesslint/storybook-addon"],
+  addons: ["@accesslint/storybook-addon"],
 };
 
 export default config;
 ```
 
-Add the vitest plugin to your `vite.config.ts`:
+Restart Storybook and an **AccessLint** panel will appear in the addon bar. Every story is audited automatically after it renders.
+
+## Vitest integration
+
+If you use [`@storybook/addon-vitest`](https://storybook.js.org/docs/writing-tests/vitest-plugin), add the AccessLint plugin next to `storybookTest()` in your Vite config:
 
 ```ts
-import { storybookTest } from "@storybook/addon-vitest/vitest-plugin";
 import { accesslintTest } from "@accesslint/storybook-addon/vitest-plugin";
 
-export default defineConfig({
-  plugins: [
-    storybookTest({ configDir: ".storybook" }),
-    accesslintTest(),
-  ],
+// Inside your Storybook test project:
+plugins: [
+  storybookTest({ configDir: ".storybook" }),
+  accesslintTest(),
+],
+```
+
+This gives you:
+
+- Per-story status dots in the sidebar (green/yellow/red)
+- A test widget in the sidebar's testing module
+- The `toBeAccessible()` matcher registered automatically
+- Accessibility results in CI alongside your component tests
+
+## Accessibility assertions
+
+Use `toBeAccessible()` to make accessibility a first-class assertion in your tests and play functions.
+
+### With the Vitest plugin
+
+If you added `accesslintTest()` above, the matcher is already registered. Use it directly in play functions:
+
+```ts
+import { expect } from "storybook/test";
+
+export const Default = {
+  play: async ({ canvasElement }) => {
+    await expect(canvasElement).toBeAccessible();
+  },
+};
+```
+
+### Without the Vitest plugin
+
+For play functions or standalone tests without the plugin, import the matchers entry point to register `toBeAccessible()`:
+
+```ts
+import "@accesslint/storybook-addon/matchers";
+```
+
+Then use it in a play function:
+
+```ts
+import { expect } from "storybook/test";
+import "@accesslint/storybook-addon/matchers";
+
+export const Default = {
+  play: async ({ canvasElement }) => {
+    await expect(canvasElement).toBeAccessible();
+  },
+};
+```
+
+Or in a standalone Vitest/Jest test:
+
+```ts
+import "@accesslint/storybook-addon/matchers";
+import { render } from "@testing-library/react";
+
+test("LoginForm is accessible", () => {
+  const { container } = render(<LoginForm />);
+  expect(container).toBeAccessible();
+});
+```
+
+### Disabling rules per assertion
+
+```ts
+await expect(canvasElement).toBeAccessible({
+  disabledRules: ["accesslint-045"],
 });
 ```
 
-Restart Storybook and an **AccessLint** panel will appear in the addon bar.
+### Failure output
 
-## Usage
+When the assertion fails, the error message lists each violation with its rule ID, WCAG criteria, conformance level, message, and the CSS selector of the failing element:
 
-The addon audits each story after it renders and displays violations sorted by severity. Expand any violation to see:
+```
+Expected element to have no accessibility violations, but found 2:
+
+  accesslint-001 [A] (1.1.1): Image is missing alt text
+    img[src="hero.png"]
+
+  accesslint-012 [A] (1.3.1): Form input is missing a label
+    input[type="email"]
+```
+
+### TypeScript support
+
+Add the type reference to your `tsconfig.json`:
 
-- **Impact level** — critical, serious, moderate, or minor
-- **WCAG criteria** and conformance level (A, AA, AAA)
-- **How to fix** guidance for each rule
-- **Element HTML** snippet of the failing element
+```json
+{
+  "compilerOptions": {
+    "types": ["@accesslint/storybook-addon/matchers"]
+  }
+}
+```
+
+Or add a triple-slash reference in a `.d.ts` file:
+
+```ts
+/// <reference types="@accesslint/storybook-addon/matchers" />
+```
 
 ## Configuration
 
-### Parameters
+### Test mode
 
-Control AccessLint behavior per-story or globally via `parameters.accesslint`:
+Control how violations are reported via `parameters.accesslint`:
 
 ```ts
-// .storybook/preview.ts
+// .storybook/preview.ts — applies to all stories
 const preview = {
   parameters: {
     accesslint: {
-      // 'todo' - show violations as warnings in the test UI
-      // 'error' - fail CI on violations
-      // 'off' - skip checks entirely
-      test: "todo",
+      test: "todo", // "error" (default) | "todo" | "off"
     },
   },
 };
@@ -71,9 +156,25 @@ const preview = {
 export default preview;
 ```
 
+| Mode | Behavior |
+| --- | --- |
+| `"error"` | Violations fail the test (default) |
+| `"todo"` | Violations show as warnings — yellow sidebar dots, non-blocking in CI |
+| `"off"` | Skip auditing entirely |
+
+Override per-story:
+
+```ts
+export const Experimental = {
+  parameters: {
+    accesslint: { test: "off" },
+  },
+};
+```
+
 ### Disabling rules
 
-Disable specific rules in your preview file:
+Disable specific rules globally in your preview file:
 
 ```ts
 // .storybook/preview.ts
@@ -84,10 +185,110 @@ configureRules({
 });
 ```
 
+### Skipping stories with tags
+
+Tag individual stories or entire components with `"no-a11y"` to skip auditing:
+
+```ts
+// Skip a single story
+export const Prototype = {
+  tags: ["no-a11y"],
+};
+
+// Skip all stories for a component
+export default {
+  component: ExperimentalWidget,
+  tags: ["no-a11y"],
+};
+```
+
+With the Vitest plugin, you can also define custom skip tags:
+
+```ts
+accesslintTest({
+  tags: { skip: ["no-a11y", "wip"] },
+});
+```
+
+## Portable stories
+
+Use AccessLint with [`composeStories`](https://storybook.js.org/docs/api/portable-stories/portable-stories-vitest) outside of Storybook (plain Vitest, Jest, or Playwright CT).
+
+In your test setup file, pass the AccessLint annotations to `setProjectAnnotations`:
+
+```ts
+// vitest.setup.ts
+import { setProjectAnnotations } from "@storybook/react";
+import { enableAccessLint } from "@accesslint/storybook-addon/portable";
+import * as previewAnnotations from "./.storybook/preview";
+
+const project = setProjectAnnotations([
+  previewAnnotations,
+  enableAccessLint(),
+]);
+
+beforeAll(project.beforeAll);
+```
+
+Then in your tests:
+
+```ts
+import { composeStories } from "@storybook/react";
+import * as stories from "./Button.stories";
+
+const { Primary } = composeStories(stories);
+
+test("Primary button is accessible", async () => {
+  await Primary.run();
+  // AccessLint afterEach runs automatically via the annotations
+});
+```
+
+## API reference
+
+### Exports
+
+| Entry point | Description |
+| --- | --- |
+| `@accesslint/storybook-addon` | Main addon registration (manager + preview) |
+| `@accesslint/storybook-addon/vitest-plugin` | `accesslintTest()` Vite plugin for Vitest integration |
+| `@accesslint/storybook-addon/vitest-setup` | Setup file registered by the Vite plugin |
+| `@accesslint/storybook-addon/matchers` | `toBeAccessible()` custom matcher |
+| `@accesslint/storybook-addon/portable` | `enableAccessLint()` for portable stories |
+| `@accesslint/storybook-addon/preview` | Preview annotations (afterEach hook) |
+
+### `accesslintTest(options?)`
+
+Vite plugin that registers AccessLint's `afterEach` annotation and the `toBeAccessible()` matcher for Vitest story tests.
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `tags.skip` | `string[]` | Stories with any of these tags will not be audited |
+
+### `parameters.accesslint`
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `test` | `"todo" \| "error" \| "off"` | `"error"` | Controls how violations are reported |
+| `disable` | `boolean` | `false` | Set to `true` to skip auditing (same as `test: "off"`) |
+
+### `toBeAccessible(options?)`
+
+Custom matcher for asserting an element has no accessibility violations.
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `disabledRules` | `string[]` | Rule IDs to skip for this assertion |
+
+### `enableAccessLint()`
+
+Returns AccessLint's preview annotations for use with `setProjectAnnotations` in portable stories setups.
+
 ## Compatibility
 
 | Addon version | Storybook version |
 | ------------- | ----------------- |
+| 0.7.x         | 10.x              |
 | 0.6.x         | 10.x              |
 
 ## Issues

package/dist/manager.js

@@ -1,14 +1,20 @@
 import React, { useMemo, useState, useRef, useCallback } from 'react';
-import { addons, types, useChannel, useStorybookApi } from 'storybook/internal/manager-api';
-import { ActionList, Form } from 'storybook/internal/components';
+import * as managerApi from 'storybook/internal/manager-api';
+import { useChannel } from 'storybook/internal/manager-api';
 import { styled, useTheme } from 'storybook/internal/theming';
 import { STORY_CHANGED, STORY_FINISHED } from 'storybook/internal/core-events';
 
-// src/manager.tsx
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
 
 // src/constants.ts
 var ADDON_ID = "accesslint/a11y";
 var PARAM_KEY = "accesslint";
+var STATUS_TYPE_ID = "accesslint/a11y";
 var IMPACT_COLOR = {
   critical: "#d32f2f",
   serious: "#d32f2f",
@@ -193,11 +199,31 @@ var Panel = ({ active }) => {
 };
 
 // src/manager.tsx
+var { addons, types, useChannel: useChannel2, useStorybookApi } = managerApi;
 var PANEL_ID = `${ADDON_ID}/panel`;
 var TEST_PROVIDER_ID = `${ADDON_ID}/test-provider`;
+var _getStatusStore = managerApi.experimental_getStatusStore;
+var _getTestProviderStore = managerApi.experimental_getTestProviderStore;
+var _useTestProviderStore = managerApi.experimental_useTestProviderStore ?? null;
+var hasTestProvider = !!(_getStatusStore && _getTestProviderStore);
+var statusStore = hasTestProvider ? _getStatusStore(STATUS_TYPE_ID) : null;
+var testProviderStore = hasTestProvider ? _getTestProviderStore(TEST_PROVIDER_ID) : null;
+if (testProviderStore && statusStore) {
+  testProviderStore.onClearAll(() => {
+    statusStore.unset();
+  });
+}
+var ActionList = null;
+var Form = null;
+try {
+  const components = __require("storybook/internal/components");
+  ActionList = components.ActionList ?? null;
+  Form = components.Form ?? null;
+} catch {
+}
 var Title = () => {
   const [count, setCount] = React.useState(0);
-  useChannel({
+  useChannel2({
     [STORY_FINISHED]: ({ reporters }) => {
       const report = reporters.find((r) => r.type === "accesslint");
       const violations = report?.result?.violations;
@@ -218,9 +244,7 @@ var Title = () => {
     color: "inherit"
   } }, /* @__PURE__ */ React.createElement("span", { style: { color: "#fff" } }, count)));
 };
-var StyledActionList = styled(ActionList)({
-  padding: 0
-});
+var StyledActionList = ActionList ? styled(ActionList)({ padding: 0 }) : styled.div({ padding: 0 });
 var StatusDot = styled.div(
   {
     width: 6,
@@ -242,12 +266,36 @@ var StatusDot = styled.div(
 var TestProviderWidget = () => {
   const [violationCount, setViolationCount] = React.useState(null);
   const api = useStorybookApi();
-  useChannel({
-    [STORY_FINISHED]: ({ reporters }) => {
+  const providerState = _useTestProviderStore ? _useTestProviderStore((state) => state[TEST_PROVIDER_ID]) : null;
+  React.useEffect(() => {
+    if (!statusStore) return;
+    const unsub = statusStore.onSelect(() => {
+      api.setSelectedPanel(PANEL_ID);
+      api.togglePanel(true);
+    });
+    return unsub;
+  }, [api]);
+  useChannel2({
+    [STORY_FINISHED]: ({ storyId, reporters }) => {
       const report = reporters.find((r) => r.type === "accesslint");
       if (!report) return;
-      const violations = report.result?.violations;
-      setViolationCount(violations?.length ?? 0);
+      const violations = report.result?.violations ?? [];
+      setViolationCount(violations.length);
+      if (statusStore) {
+        const hasViolations2 = violations.length > 0;
+        const isWarning = report.status === "warning";
+        statusStore.set([{
+          value: hasViolations2 ? isWarning ? "status-value:warning" : "status-value:error" : "status-value:success",
+          typeId: STATUS_TYPE_ID,
+          storyId,
+          title: "AccessLint",
+          description: hasViolations2 ? `${violations.length} violation${violations.length === 1 ? "" : "s"}` : "No violations",
+          sidebarContextMenu: true
+        }]);
+      }
+      if (testProviderStore && providerState === "test-provider-state:running") {
+        testProviderStore.setState("test-provider-state:succeeded");
+      }
     }
   });
   const hasViolations = violationCount !== null && violationCount > 0;
@@ -256,16 +304,43 @@ var TestProviderWidget = () => {
     api.setSelectedPanel(PANEL_ID);
     api.togglePanel(true);
   };
-  return /* @__PURE__ */ React.createElement(StyledActionList, null, /* @__PURE__ */ React.createElement(ActionList.Item, null, /* @__PURE__ */ React.createElement(ActionList.Action, { as: "label", readOnly: true }, /* @__PURE__ */ React.createElement(ActionList.Icon, null, /* @__PURE__ */ React.createElement(Form.Checkbox, { name: "AccessLint", checked: true, disabled: true })), /* @__PURE__ */ React.createElement(ActionList.Text, null, "AccessLint")), /* @__PURE__ */ React.createElement(
-    ActionList.Button,
+  if (ActionList && Form) {
+    return /* @__PURE__ */ React.createElement(StyledActionList, null, /* @__PURE__ */ React.createElement(ActionList.Item, null, /* @__PURE__ */ React.createElement(ActionList.Action, { as: "label", readOnly: true }, /* @__PURE__ */ React.createElement(ActionList.Icon, null, /* @__PURE__ */ React.createElement(Form.Checkbox, { name: "AccessLint", checked: true, disabled: true })), /* @__PURE__ */ React.createElement(ActionList.Text, null, "AccessLint")), /* @__PURE__ */ React.createElement(
+      ActionList.Button,
+      {
+        ariaLabel: violationCount === null ? "AccessLint: not run yet" : hasViolations ? `AccessLint: ${violationCount} violation${violationCount === 1 ? "" : "s"}` : "AccessLint: no violations",
+        disabled: violationCount === null,
+        onClick: openPanel
+      },
+      hasViolations ? violationCount : null,
+      /* @__PURE__ */ React.createElement(StatusDot, { status })
+    )));
+  }
+  return /* @__PURE__ */ React.createElement(
+    StyledActionList,
     {
-      ariaLabel: violationCount === null ? "AccessLint: not run yet" : hasViolations ? `AccessLint: ${violationCount} violation${violationCount === 1 ? "" : "s"}` : "AccessLint: no violations",
-      disabled: violationCount === null,
+      style: { display: "flex", alignItems: "center", gap: 8, padding: "6px 8px", cursor: "pointer" },
       onClick: openPanel
     },
-    hasViolations ? violationCount : null,
-    /* @__PURE__ */ React.createElement(StatusDot, { status })
-  )));
+    /* @__PURE__ */ React.createElement(StatusDot, { status }),
+    /* @__PURE__ */ React.createElement("span", { style: { fontSize: 12 } }, "AccessLint"),
+    hasViolations && /* @__PURE__ */ React.createElement("span", { style: { fontSize: 11, fontWeight: "bold" } }, violationCount)
+  );
+};
+var SidebarContextMenu = ({ context }) => {
+  const api = useStorybookApi();
+  if (context.type !== "story" || !ActionList) return null;
+  return /* @__PURE__ */ React.createElement(
+    ActionList.Item,
+    {
+      onClick: () => {
+        api.selectStory(context.id);
+        api.setSelectedPanel(PANEL_ID);
+        api.togglePanel(true);
+      }
+    },
+    /* @__PURE__ */ React.createElement(ActionList.Text, null, "View AccessLint results")
+  );
 };
 addons.register(ADDON_ID, () => {
   addons.add(PANEL_ID, {
@@ -274,8 +349,11 @@ addons.register(ADDON_ID, () => {
     render: Panel,
     paramKey: PARAM_KEY
   });
-  addons.add(TEST_PROVIDER_ID, {
-    type: types.experimental_TEST_PROVIDER,
-    render: () => /* @__PURE__ */ React.createElement(TestProviderWidget, null)
-  });
+  if (hasTestProvider && types.experimental_TEST_PROVIDER) {
+    addons.add(TEST_PROVIDER_ID, {
+      type: types.experimental_TEST_PROVIDER,
+      render: () => /* @__PURE__ */ React.createElement(TestProviderWidget, null),
+      sidebarContextMenu: ({ context }) => /* @__PURE__ */ React.createElement(SidebarContextMenu, { context })
+    });
+  }
 });

package/dist/matchers.cjs

@@ -0,0 +1,14 @@
+'use strict';
+
+var matchers = require('@accesslint/vitest/matchers');
+
+
+
+Object.defineProperty(exports, "accesslintMatchers", {
+  enumerable: true,
+  get: function () { return matchers.accesslintMatchers; }
+});
+Object.defineProperty(exports, "toBeAccessible", {
+  enumerable: true,
+  get: function () { return matchers.toBeAccessible; }
+});

package/dist/matchers.d.cts

@@ -0,0 +1 @@
+export { AccessibleMatcherOptions, accesslintMatchers, toBeAccessible } from '@accesslint/vitest/matchers';

package/dist/matchers.d.ts

@@ -0,0 +1 @@
+export { AccessibleMatcherOptions, accesslintMatchers, toBeAccessible } from '@accesslint/vitest/matchers';

package/dist/matchers.js

@@ -0,0 +1 @@
+export { accesslintMatchers, toBeAccessible } from '@accesslint/vitest/matchers';

package/dist/portable.cjs

@@ -0,0 +1,80 @@
+'use strict';
+
+var core = require('@accesslint/core');
+
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/preview.ts
+var preview_exports = {};
+__export(preview_exports, {
+  afterEach: () => afterEach
+});
+core.configureRules({
+  disabledRules: ["accesslint-045"]
+});
+function scopeViolations(violations) {
+  const root = document.getElementById("storybook-root");
+  if (!root) return violations;
+  return violations.filter((v) => {
+    const local = v.selector.replace(/^.*>>>\s*iframe>\s*/, "");
+    try {
+      const el = document.querySelector(local);
+      return el && root.contains(el);
+    } catch {
+      return false;
+    }
+  });
+}
+function enrichViolations(violations) {
+  return violations.map((v) => {
+    const rule = core.getRuleById(v.ruleId);
+    return {
+      ...v,
+      element: void 0,
+      // not serializable
+      description: rule?.description,
+      wcag: rule?.wcag,
+      level: rule?.level,
+      guidance: rule?.guidance
+    };
+  });
+}
+var afterEach = async ({
+  reporting,
+  parameters,
+  viewMode,
+  tags
+}) => {
+  const accesslintParam = parameters?.accesslint;
+  if (accesslintParam?.disable === true || accesslintParam?.test === "off") return;
+  if (viewMode !== "story") return;
+  if (tags?.includes("no-a11y")) return;
+  const skipTags = typeof __ACCESSLINT_SKIP_TAGS__ !== "undefined" ? __ACCESSLINT_SKIP_TAGS__ : [];
+  if (skipTags.length > 0 && tags?.some((t) => skipTags.includes(t))) return;
+  const result = core.runAudit(document);
+  const scoped = scopeViolations(result.violations);
+  const enriched = enrichViolations(scoped);
+  const hasViolations = enriched.length > 0;
+  const mode = accesslintParam?.test === "todo" ? "warning" : "failed";
+  reporting.addReport({
+    type: "accesslint",
+    version: 1,
+    result: {
+      violations: enriched,
+      ruleCount: result.ruleCount
+    },
+    status: hasViolations ? mode : "passed"
+  });
+};
+
+// src/portable.ts
+function enableAccessLint() {
+  return preview_exports;
+}
+
+exports.accesslintAnnotations = preview_exports;
+exports.enableAccessLint = enableAccessLint;

package/dist/portable.d.cts

@@ -0,0 +1,46 @@
+declare const afterEach: ({ reporting, parameters, viewMode, tags, }: {
+    reporting: {
+        addReport: (report: Record<string, unknown>) => void;
+    };
+    parameters: Record<string, unknown>;
+    viewMode: string;
+    tags?: string[];
+}) => Promise<void>;
+
+declare const accesslintAnnotations_afterEach: typeof afterEach;
+declare namespace accesslintAnnotations {
+  export { accesslintAnnotations_afterEach as afterEach };
+}
+
+/**
+ * Portable stories helper for using AccessLint with composeStories
+ * outside of Storybook (plain Vitest, Jest, Playwright CT).
+ *
+ * Usage in your test setup file:
+ *
+ *   import { enableAccessLint } from "@accesslint/storybook-addon/portable";
+ *   import { setProjectAnnotations } from "@storybook/react";
+ *   import * as previewAnnotations from "./.storybook/preview";
+ *
+ *   const project = setProjectAnnotations([
+ *     previewAnnotations,
+ *     enableAccessLint(),
+ *   ]);
+ *   beforeAll(project.beforeAll);
+ *
+ * Then in tests:
+ *
+ *   import { composeStories } from "@storybook/react";
+ *   import * as stories from "./Button.stories";
+ *
+ *   const { Primary } = composeStories(stories);
+ *
+ *   test("is accessible", async () => {
+ *     await Primary.run();
+ *     // AccessLint afterEach runs automatically and reports violations
+ *   });
+ */
+
+declare function enableAccessLint(): typeof accesslintAnnotations;
+
+export { accesslintAnnotations, enableAccessLint };

package/dist/portable.d.ts

@@ -0,0 +1,46 @@
+declare const afterEach: ({ reporting, parameters, viewMode, tags, }: {
+    reporting: {
+        addReport: (report: Record<string, unknown>) => void;
+    };
+    parameters: Record<string, unknown>;
+    viewMode: string;
+    tags?: string[];
+}) => Promise<void>;
+
+declare const accesslintAnnotations_afterEach: typeof afterEach;
+declare namespace accesslintAnnotations {
+  export { accesslintAnnotations_afterEach as afterEach };
+}
+
+/**
+ * Portable stories helper for using AccessLint with composeStories
+ * outside of Storybook (plain Vitest, Jest, Playwright CT).
+ *
+ * Usage in your test setup file:
+ *
+ *   import { enableAccessLint } from "@accesslint/storybook-addon/portable";
+ *   import { setProjectAnnotations } from "@storybook/react";
+ *   import * as previewAnnotations from "./.storybook/preview";
+ *
+ *   const project = setProjectAnnotations([
+ *     previewAnnotations,
+ *     enableAccessLint(),
+ *   ]);
+ *   beforeAll(project.beforeAll);
+ *
+ * Then in tests:
+ *
+ *   import { composeStories } from "@storybook/react";
+ *   import * as stories from "./Button.stories";
+ *
+ *   const { Primary } = composeStories(stories);
+ *
+ *   test("is accessible", async () => {
+ *     await Primary.run();
+ *     // AccessLint afterEach runs automatically and reports violations
+ *   });
+ */
+
+declare function enableAccessLint(): typeof accesslintAnnotations;
+
+export { accesslintAnnotations, enableAccessLint };

package/dist/portable.js

@@ -0,0 +1,77 @@
+import { configureRules, runAudit, getRuleById } from '@accesslint/core';
+
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/preview.ts
+var preview_exports = {};
+__export(preview_exports, {
+  afterEach: () => afterEach
+});
+configureRules({
+  disabledRules: ["accesslint-045"]
+});
+function scopeViolations(violations) {
+  const root = document.getElementById("storybook-root");
+  if (!root) return violations;
+  return violations.filter((v) => {
+    const local = v.selector.replace(/^.*>>>\s*iframe>\s*/, "");
+    try {
+      const el = document.querySelector(local);
+      return el && root.contains(el);
+    } catch {
+      return false;
+    }
+  });
+}
+function enrichViolations(violations) {
+  return violations.map((v) => {
+    const rule = getRuleById(v.ruleId);
+    return {
+      ...v,
+      element: void 0,
+      // not serializable
+      description: rule?.description,
+      wcag: rule?.wcag,
+      level: rule?.level,
+      guidance: rule?.guidance
+    };
+  });
+}
+var afterEach = async ({
+  reporting,
+  parameters,
+  viewMode,
+  tags
+}) => {
+  const accesslintParam = parameters?.accesslint;
+  if (accesslintParam?.disable === true || accesslintParam?.test === "off") return;
+  if (viewMode !== "story") return;
+  if (tags?.includes("no-a11y")) return;
+  const skipTags = typeof __ACCESSLINT_SKIP_TAGS__ !== "undefined" ? __ACCESSLINT_SKIP_TAGS__ : [];
+  if (skipTags.length > 0 && tags?.some((t) => skipTags.includes(t))) return;
+  const result = runAudit(document);
+  const scoped = scopeViolations(result.violations);
+  const enriched = enrichViolations(scoped);
+  const hasViolations = enriched.length > 0;
+  const mode = accesslintParam?.test === "todo" ? "warning" : "failed";
+  reporting.addReport({
+    type: "accesslint",
+    version: 1,
+    result: {
+      violations: enriched,
+      ruleCount: result.ruleCount
+    },
+    status: hasViolations ? mode : "passed"
+  });
+};
+
+// src/portable.ts
+function enableAccessLint() {
+  return preview_exports;
+}
+
+export { preview_exports as accesslintAnnotations, enableAccessLint };

package/dist/preview.cjs

@@ -36,11 +36,15 @@ function enrichViolations(violations) {
 var afterEach = async ({
   reporting,
   parameters,
-  viewMode
+  viewMode,
+  tags
 }) => {
   const accesslintParam = parameters?.accesslint;
   if (accesslintParam?.disable === true || accesslintParam?.test === "off") return;
   if (viewMode !== "story") return;
+  if (tags?.includes("no-a11y")) return;
+  const skipTags = typeof __ACCESSLINT_SKIP_TAGS__ !== "undefined" ? __ACCESSLINT_SKIP_TAGS__ : [];
+  if (skipTags.length > 0 && tags?.some((t) => skipTags.includes(t))) return;
   const result = core.runAudit(document);
   const scoped = scopeViolations(result.violations);
   const enriched = enrichViolations(scoped);

package/dist/preview.d.cts

@@ -1,9 +1,10 @@
-declare const afterEach: ({ reporting, parameters, viewMode, }: {
+declare const afterEach: ({ reporting, parameters, viewMode, tags, }: {
     reporting: {
         addReport: (report: Record<string, unknown>) => void;
     };
     parameters: Record<string, unknown>;
     viewMode: string;
+    tags?: string[];
 }) => Promise<void>;
 
 export { afterEach };

package/dist/preview.d.ts

@@ -1,9 +1,10 @@
-declare const afterEach: ({ reporting, parameters, viewMode, }: {
+declare const afterEach: ({ reporting, parameters, viewMode, tags, }: {
     reporting: {
         addReport: (report: Record<string, unknown>) => void;
     };
     parameters: Record<string, unknown>;
     viewMode: string;
+    tags?: string[];
 }) => Promise<void>;
 
 export { afterEach };

package/dist/preview.js

@@ -34,11 +34,15 @@ function enrichViolations(violations) {
 var afterEach = async ({
   reporting,
   parameters,
-  viewMode
+  viewMode,
+  tags
 }) => {
   const accesslintParam = parameters?.accesslint;
   if (accesslintParam?.disable === true || accesslintParam?.test === "off") return;
   if (viewMode !== "story") return;
+  if (tags?.includes("no-a11y")) return;
+  const skipTags = typeof __ACCESSLINT_SKIP_TAGS__ !== "undefined" ? __ACCESSLINT_SKIP_TAGS__ : [];
+  if (skipTags.length > 0 && tags?.some((t) => skipTags.includes(t))) return;
   const result = runAudit(document);
   const scoped = scopeViolations(result.violations);
   const enriched = enrichViolations(scoped);

package/dist/vitest-plugin.cjs

@@ -2,12 +2,12 @@
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 // src/vitest-plugin.ts
-function accesslintTest() {
+function accesslintTest(options) {
   const distDir = new URL(".", (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('vitest-plugin.cjs', document.baseURI).href))).pathname;
   return {
     name: "@accesslint/storybook-addon",
     config() {
-      return {
+      const config = {
         server: {
           fs: {
             allow: [distDir]
@@ -17,6 +17,12 @@ function accesslintTest() {
           setupFiles: ["@accesslint/storybook-addon/vitest-setup"]
         }
       };
+      if (options?.tags) {
+        config.define = {
+          "__ACCESSLINT_SKIP_TAGS__": JSON.stringify(options.tags.skip ?? [])
+        };
+      }
+      return config;
     }
   };
 }

package/dist/vitest-plugin.d.cts

@@ -11,9 +11,21 @@
  *     plugins: [storybookTest(), accesslintTest()],
  *   });
  */
-declare function accesslintTest(): {
+interface AccessLintTestOptions {
+    /**
+     * Tags-based filtering for which stories to audit.
+     *
+     *   accesslintTest({ tags: { skip: ["no-a11y"] } })
+     *
+     * Stories with any of the `skip` tags will not be audited.
+     */
+    tags?: {
+        skip?: string[];
+    };
+}
+declare function accesslintTest(options?: AccessLintTestOptions): {
     name: string;
     config: () => Record<string, unknown>;
 };
 
-export { accesslintTest };
+export { type AccessLintTestOptions, accesslintTest };

package/dist/vitest-plugin.d.ts

@@ -11,9 +11,21 @@
  *     plugins: [storybookTest(), accesslintTest()],
  *   });
  */
-declare function accesslintTest(): {
+interface AccessLintTestOptions {
+    /**
+     * Tags-based filtering for which stories to audit.
+     *
+     *   accesslintTest({ tags: { skip: ["no-a11y"] } })
+     *
+     * Stories with any of the `skip` tags will not be audited.
+     */
+    tags?: {
+        skip?: string[];
+    };
+}
+declare function accesslintTest(options?: AccessLintTestOptions): {
     name: string;
     config: () => Record<string, unknown>;
 };
 
-export { accesslintTest };
+export { type AccessLintTestOptions, accesslintTest };

package/dist/vitest-plugin.js

@@ -1,10 +1,10 @@
 // src/vitest-plugin.ts
-function accesslintTest() {
+function accesslintTest(options) {
   const distDir = new URL(".", import.meta.url).pathname;
   return {
     name: "@accesslint/storybook-addon",
     config() {
-      return {
+      const config = {
         server: {
           fs: {
             allow: [distDir]
@@ -14,6 +14,12 @@ function accesslintTest() {
           setupFiles: ["@accesslint/storybook-addon/vitest-setup"]
         }
       };
+      if (options?.tags) {
+        config.define = {
+          "__ACCESSLINT_SKIP_TAGS__": JSON.stringify(options.tags.skip ?? [])
+        };
+      }
+      return config;
     }
   };
 }

package/dist/vitest-setup.cjs

@@ -1,7 +1,10 @@
 'use strict';
 
+var test = require('storybook/test');
+var vitest = require('vitest');
 var previewApi = require('storybook/preview-api');
 var core = require('@accesslint/core');
+var matchers = require('@accesslint/vitest/matchers');
 
 var __defProp = Object.defineProperty;
 var __export = (target, all) => {
@@ -47,11 +50,15 @@ function enrichViolations(violations) {
 var afterEach = async ({
   reporting,
   parameters,
-  viewMode
+  viewMode,
+  tags
 }) => {
   const accesslintParam = parameters?.accesslint;
   if (accesslintParam?.disable === true || accesslintParam?.test === "off") return;
   if (viewMode !== "story") return;
+  if (tags?.includes("no-a11y")) return;
+  const skipTags = typeof __ACCESSLINT_SKIP_TAGS__ !== "undefined" ? __ACCESSLINT_SKIP_TAGS__ : [];
+  if (skipTags.length > 0 && tags?.some((t) => skipTags.includes(t))) return;
   const result = core.runAudit(document);
   const scoped = scopeViolations(result.violations);
   const enriched = enrichViolations(scoped);
@@ -67,8 +74,8 @@ var afterEach = async ({
     status: hasViolations ? mode : "passed"
   });
 };
-
-// src/vitest-setup.ts
+test.expect.extend(matchers.accesslintMatchers);
+vitest.expect.extend(matchers.accesslintMatchers);
 var g = globalThis;
 var existing = g.globalProjectAnnotations;
 g.globalProjectAnnotations = existing ? previewApi.composeConfigs([existing, preview_exports]) : previewApi.composeConfigs([preview_exports]);

package/dist/vitest-setup.d.cts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/vitest-setup.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/vitest-setup.js

@@ -1,5 +1,8 @@
+import { expect } from 'storybook/test';
+import { expect as expect$1 } from 'vitest';
 import { composeConfigs } from 'storybook/preview-api';
 import { configureRules, runAudit, getRuleById } from '@accesslint/core';
+import { accesslintMatchers } from '@accesslint/vitest/matchers';
 
 var __defProp = Object.defineProperty;
 var __export = (target, all) => {
@@ -45,11 +48,15 @@ function enrichViolations(violations) {
 var afterEach = async ({
   reporting,
   parameters,
-  viewMode
+  viewMode,
+  tags
 }) => {
   const accesslintParam = parameters?.accesslint;
   if (accesslintParam?.disable === true || accesslintParam?.test === "off") return;
   if (viewMode !== "story") return;
+  if (tags?.includes("no-a11y")) return;
+  const skipTags = typeof __ACCESSLINT_SKIP_TAGS__ !== "undefined" ? __ACCESSLINT_SKIP_TAGS__ : [];
+  if (skipTags.length > 0 && tags?.some((t) => skipTags.includes(t))) return;
   const result = runAudit(document);
   const scoped = scopeViolations(result.violations);
   const enriched = enrichViolations(scoped);
@@ -65,8 +72,8 @@ var afterEach = async ({
     status: hasViolations ? mode : "passed"
   });
 };
-
-// src/vitest-setup.ts
+expect.extend(accesslintMatchers);
+expect$1.extend(accesslintMatchers);
 var g = globalThis;
 var existing = g.globalProjectAnnotations;
 g.globalProjectAnnotations = existing ? composeConfigs([existing, preview_exports]) : composeConfigs([preview_exports]);

package/matchers.d.ts

@@ -0,0 +1,10 @@
+import type { AccessibleMatcherOptions } from "@accesslint/vitest/matchers";
+
+declare module "vitest" {
+  interface Assertion<T> {
+    toBeAccessible(options?: AccessibleMatcherOptions): void;
+  }
+  interface AsymmetricMatchersContaining {
+    toBeAccessible(options?: AccessibleMatcherOptions): void;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@accesslint/storybook-addon",
-  "version": "0.6.9",
+  "version": "0.8.0",
   "description": "Catch accessibility violations in your Storybook stories as you develop",
   "license": "MIT",
   "publishConfig": {
@@ -30,8 +30,17 @@
       "require": "./dist/vitest-plugin.cjs"
     },
     "./vitest-setup": {
+      "types": "./dist/vitest-setup.d.ts",
       "import": "./dist/vitest-setup.js",
       "require": "./dist/vitest-setup.cjs"
+    },
+    "./matchers": {
+      "import": "./dist/matchers.js",
+      "require": "./dist/matchers.cjs"
+    },
+    "./portable": {
+      "import": "./dist/portable.js",
+      "require": "./dist/portable.cjs"
     }
   },
   "main": "dist/index.cjs",
@@ -49,17 +58,19 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@accesslint/core": "^0.6.5"
+    "@accesslint/core": "^0.6.5",
+    "@accesslint/vitest": "^0.1.3"
   },
   "devDependencies": {
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "storybook": "^10.2.0",
     "tsup": "^8.4.0",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
   },
   "peerDependencies": {
-    "storybook": "^10.0.0"
+    "storybook": "^9.0.0 || ^10.0.0"
   },
   "keywords": [
     "storybook-addon",