@accesslint/storybook-addon 0.6.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 AccessLint
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+[![npm version](https://img.shields.io/npm/v/@accesslint/storybook-addon)](https://www.npmjs.com/package/@accesslint/storybook-addon)
+[![npm downloads](https://img.shields.io/npm/dm/@accesslint/storybook-addon)](https://www.npmjs.com/package/@accesslint/storybook-addon)
+[![license](https://img.shields.io/github/license/AccessLint/storybook-addon)](https://github.com/AccessLint/storybook-addon/blob/main/LICENSE)
+
+# @accesslint/storybook-addon
+
+Catch accessibility violations in your Storybook stories as you develop. Powered by [@accesslint/core](https://core.accesslint.com).
+
+<!-- TODO: Add screenshot or GIF of the panel -->
+
+## Getting Started
+
+```sh
+npm install @accesslint/storybook-addon
+```
+
+Then add it to your `.storybook/main.ts` (or `.storybook/main.js`):
+
+```ts
+const config = {
+  addons: ["@accesslint/storybook-addon"],
+};
+
+export default config;
+```
+
+That's it. Restart Storybook and an **AccessLint** panel will appear in the addon bar.
+
+## Usage
+
+The addon automatically audits each story on render and displays violations sorted by severity. Expand any violation to see:
+
+- **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
+
+Selecting a violation highlights the affected element in the story preview.
+
+## Configuration
+
+Disable specific rules in your preview file:
+
+```ts
+// .storybook/preview.ts
+import { configureRules } from "@accesslint/core";
+
+configureRules({
+  disabledRules: ["accesslint-045"], // e.g. disable landmark region rule
+});
+```
+
+## Compatibility
+
+| Addon version | Storybook version |
+| ------------- | ----------------- |
+| 0.6.x         | 8.6.x             |
+
+## Issues
+
+Please report issues in the [AccessLint core repository](https://github.com/AccessLint/core/issues).
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,2 @@
+'use strict';
+

package/dist/index.d.cts

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

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1 @@
+

package/dist/manager.js

@@ -0,0 +1,278 @@
+import { addons, types, useAddonState, useChannel } from 'storybook/internal/manager-api';
+import { useMemo, useState, useRef, useEffect, useCallback } from 'react';
+import { useTheme } from 'storybook/internal/theming';
+import { AddonPanel } from 'storybook/internal/components';
+import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
+
+// src/manager.tsx
+
+// src/constants.ts
+var ADDON_ID = "accesslint/a11y";
+var PANEL_ID = `${ADDON_ID}/panel`;
+var IMPACT_COLOR = {
+  critical: "#d32f2f",
+  serious: "#d32f2f",
+  moderate: "#c43e00",
+  minor: "#999999"
+};
+var IMPACT_ICON = {
+  critical: "\u2716",
+  serious: "\u2716",
+  moderate: "\u26A0",
+  minor: "\xB7"
+};
+var IMPACT_ORDER = {
+  critical: 0,
+  serious: 1,
+  moderate: 2,
+  minor: 3
+};
+var LEVEL_COLOR = {
+  A: "#2e7d32",
+  AA: "#1565c0",
+  AAA: "#6a1b9a"
+};
+var HIGHLIGHT_ID = `${ADDON_ID}/highlight`;
+var Panel = ({ active, ...rest }) => {
+  const theme = useTheme();
+  const isDark = theme.base === "dark";
+  const colors = useMemo(() => ({
+    text: theme.textColor || (isDark ? "#e0e0e0" : "#424242"),
+    textMuted: theme.textMutedColor || (isDark ? "#999" : "#616161"),
+    bg: theme.appContentBg || (isDark ? "#1a1a1a" : "#fff"),
+    bgDetails: isDark ? "#2a2a2a" : "#f5f5f5",
+    bgSelected: isDark ? "#1a3a5c" : "#e3f2fd",
+    border: theme.appBorderColor || (isDark ? "#444" : "#f0f0f0"),
+    codeBg: isDark ? "#333" : "#fff",
+    codeBorder: isDark ? "#555" : "#e0e0e0",
+    tagBg: isDark ? "#444" : "#e0e0e0",
+    tagText: isDark ? "#ccc" : "#616161",
+    ruleId: isDark ? "#64b5f6" : "#1565c0"
+  }), [isDark, theme]);
+  const [violations, setViolations] = useAddonState(
+    ADDON_ID,
+    []
+  );
+  const [meta, setMeta] = useState(null);
+  const [expandedIndex, setExpandedIndex] = useState(null);
+  const buttonRefs = useRef([]);
+  const emit = useChannel({
+    [`${ADDON_ID}/results`]: (results) => {
+      setViolations(results);
+      setExpandedIndex(null);
+    },
+    [`${ADDON_ID}/meta`]: (data) => {
+      setMeta(data);
+    }
+  });
+  const sorted = [...violations].sort(
+    (a, b) => (IMPACT_ORDER[a.impact] ?? 4) - (IMPACT_ORDER[b.impact] ?? 4)
+  );
+  const expanded = expandedIndex !== null ? sorted[expandedIndex] : null;
+  useEffect(() => {
+    if (expanded?.selector) {
+      const local = expanded.selector.replace(/^.*>>>\s*iframe>\s*/, "");
+      emit("storybook/highlight/add", {
+        id: HIGHLIGHT_ID,
+        selectors: [local],
+        styles: {
+          outline: `2px solid ${IMPACT_COLOR[expanded.impact] || "#1565c0"}`,
+          outlineOffset: "2px"
+        }
+      });
+    } else {
+      emit("storybook/highlight/remove", { id: HIGHLIGHT_ID });
+    }
+  }, [expandedIndex]);
+  const handleKeyDown = useCallback((e, index) => {
+    let next = null;
+    switch (e.key) {
+      case "ArrowDown":
+        next = Math.min(index + 1, sorted.length - 1);
+        break;
+      case "ArrowUp":
+        next = Math.max(index - 1, 0);
+        break;
+      case "Home":
+        next = 0;
+        break;
+      case "End":
+        next = sorted.length - 1;
+        break;
+      default:
+        return;
+    }
+    e.preventDefault();
+    buttonRefs.current[next]?.focus();
+  }, [sorted.length]);
+  if (!active) return null;
+  return /* @__PURE__ */ jsx(AddonPanel, { active, ...rest, children: /* @__PURE__ */ jsxs("div", { style: { display: "flex", flexDirection: "column", height: "100%", fontFamily: "system-ui, sans-serif" }, children: [
+    meta && /* @__PURE__ */ jsxs("div", { style: {
+      display: "flex",
+      gap: "12px",
+      padding: "8px 12px",
+      fontSize: "11px",
+      color: colors.textMuted,
+      borderBottom: `1px solid ${colors.border}`,
+      flexShrink: 0
+    }, children: [
+      /* @__PURE__ */ jsxs("span", { children: [
+        meta.ruleCount,
+        " rules"
+      ] }),
+      /* @__PURE__ */ jsxs("span", { style: { color: "#2e7d32" }, children: [
+        meta.passed,
+        " passed"
+      ] }),
+      /* @__PURE__ */ jsxs("span", { style: { color: meta.failed > 0 ? "#d32f2f" : colors.textMuted }, children: [
+        meta.failed,
+        " failed"
+      ] }),
+      /* @__PURE__ */ jsxs("span", { children: [
+        meta.duration,
+        "ms"
+      ] })
+    ] }),
+    violations.length === 0 ? /* @__PURE__ */ jsx("p", { style: { padding: "12px", margin: 0, fontSize: "13px", color: colors.textMuted }, children: "No accessibility violations found." }) : /* @__PURE__ */ jsx("div", { style: { flex: 1, overflow: "auto", minHeight: 0 }, children: /* @__PURE__ */ jsx(
+      "ul",
+      {
+        style: { listStyle: "none", padding: 0, margin: 0 },
+        "aria-label": "Accessibility violations",
+        children: sorted.map((v, i) => {
+          const isOpen = expandedIndex === i;
+          return /* @__PURE__ */ jsxs("li", { style: { borderBottom: `1px solid ${colors.border}` }, children: [
+            /* @__PURE__ */ jsxs(
+              "button",
+              {
+                ref: (el) => {
+                  buttonRefs.current[i] = el;
+                },
+                type: "button",
+                onClick: () => setExpandedIndex(isOpen ? null : i),
+                onKeyDown: (e) => handleKeyDown(e, i),
+                "aria-expanded": isOpen,
+                style: {
+                  width: "100%",
+                  padding: "8px 12px",
+                  background: isOpen ? colors.bgSelected : "transparent",
+                  border: "none",
+                  font: "inherit",
+                  fontSize: "12px",
+                  textAlign: "left",
+                  cursor: "pointer",
+                  color: colors.text
+                },
+                children: [
+                  /* @__PURE__ */ jsxs("div", { style: { display: "flex", alignItems: "center", gap: "6px" }, children: [
+                    /* @__PURE__ */ jsx(
+                      "span",
+                      {
+                        "aria-hidden": "true",
+                        style: {
+                          color: IMPACT_COLOR[v.impact],
+                          fontWeight: "bold",
+                          fontSize: "12px"
+                        },
+                        children: IMPACT_ICON[v.impact]
+                      }
+                    ),
+                    /* @__PURE__ */ jsx("span", { style: { color: IMPACT_COLOR[v.impact], fontSize: "11px" }, children: v.impact }),
+                    /* @__PURE__ */ jsx("code", { style: { fontSize: "11px", color: colors.ruleId }, children: v.ruleId })
+                  ] }),
+                  /* @__PURE__ */ jsx("div", { style: { marginTop: "2px", color: colors.text, fontSize: "12px" }, children: v.message })
+                ]
+              }
+            ),
+            isOpen && /* @__PURE__ */ jsxs("div", { style: { padding: "4px 12px 12px", background: colors.bgDetails }, children: [
+              v.description && /* @__PURE__ */ jsx("p", { style: { margin: "4px 0 8px", fontSize: "12px", color: colors.text }, children: v.description }),
+              /* @__PURE__ */ jsxs("div", { style: { display: "flex", gap: "6px", flexWrap: "wrap", marginBottom: "8px" }, children: [
+                v.level && /* @__PURE__ */ jsxs("span", { style: {
+                  display: "inline-block",
+                  padding: "0 5px",
+                  fontSize: "10px",
+                  fontWeight: 600,
+                  borderRadius: "3px",
+                  color: "#fff",
+                  background: LEVEL_COLOR[v.level] || "#666",
+                  lineHeight: "18px"
+                }, children: [
+                  "WCAG ",
+                  v.level
+                ] }),
+                v.wcag?.map((ref) => /* @__PURE__ */ jsx(
+                  "span",
+                  {
+                    style: {
+                      display: "inline-block",
+                      padding: "0 5px",
+                      fontSize: "10px",
+                      fontWeight: 500,
+                      borderRadius: "3px",
+                      color: colors.tagText,
+                      background: colors.tagBg,
+                      lineHeight: "18px"
+                    },
+                    children: ref
+                  },
+                  ref
+                ))
+              ] }),
+              v.guidance && /* @__PURE__ */ jsxs("div", { style: { marginBottom: "8px" }, children: [
+                /* @__PURE__ */ jsx("div", { style: { fontSize: "11px", fontWeight: 500, color: colors.textMuted, marginBottom: "4px" }, children: "How to fix" }),
+                /* @__PURE__ */ jsx("p", { style: { margin: 0, fontSize: "12px", color: colors.text, whiteSpace: "pre-wrap" }, children: v.guidance })
+              ] }),
+              v.html && /* @__PURE__ */ jsxs("div", { style: { marginBottom: "8px" }, children: [
+                /* @__PURE__ */ jsx("div", { style: { fontSize: "11px", fontWeight: 500, color: colors.textMuted, marginBottom: "4px" }, children: "Element" }),
+                /* @__PURE__ */ jsx(
+                  "pre",
+                  {
+                    style: {
+                      margin: 0,
+                      padding: "6px 8px",
+                      fontSize: "11px",
+                      color: colors.text,
+                      background: colors.codeBg,
+                      border: `1px solid ${colors.codeBorder}`,
+                      borderRadius: "4px",
+                      overflow: "auto",
+                      whiteSpace: "pre-wrap",
+                      wordBreak: "break-all"
+                    },
+                    children: v.html
+                  }
+                )
+              ] })
+            ] })
+          ] }, i);
+        })
+      }
+    ) })
+  ] }) });
+};
+var Title = () => {
+  const [violations] = useAddonState(ADDON_ID, []);
+  const count = violations.length;
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    "AccessLint",
+    count > 0 && /* @__PURE__ */ jsx("span", { style: {
+      display: "inline-block",
+      marginLeft: "8px",
+      minWidth: "18px",
+      padding: "0 5px",
+      lineHeight: "18px",
+      borderRadius: "9px",
+      fontSize: "11px",
+      fontWeight: "bold",
+      textAlign: "center",
+      background: "currentColor",
+      color: "inherit"
+    }, children: /* @__PURE__ */ jsx("span", { style: { color: "#fff" }, children: count }) })
+  ] });
+};
+addons.register(ADDON_ID, () => {
+  addons.add(PANEL_ID, {
+    type: types.PANEL,
+    title: Title,
+    render: Panel
+  });
+});

package/dist/preview.cjs

@@ -0,0 +1,58 @@
+'use strict';
+
+var previewApi = require('storybook/internal/preview-api');
+var core = require('@accesslint/core');
+
+// src/preview.ts
+
+// src/constants.ts
+var ADDON_ID = "accesslint/a11y";
+
+// src/preview.ts
+core.configureRules({
+  disabledRules: ["accesslint-045"]
+});
+var decorator = (storyFn) => {
+  const story = storyFn();
+  setTimeout(async () => {
+    const start = performance.now();
+    const results = core.runAudit(document);
+    const duration = Math.round(performance.now() - start);
+    const root = document.getElementById("storybook-root");
+    const scoped = root ? results.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;
+      }
+    }) : results.violations;
+    const enriched = scoped.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
+      };
+    });
+    const failedRuleIds = new Set(scoped.map((v) => v.ruleId));
+    const channel = previewApi.addons.getChannel();
+    channel.emit(`${ADDON_ID}/results`, enriched);
+    channel.emit(`${ADDON_ID}/meta`, {
+      duration,
+      ruleCount: results.ruleCount,
+      failed: failedRuleIds.size,
+      passed: results.ruleCount - failedRuleIds.size,
+      violations: scoped.length
+    });
+  }, 0);
+  return story;
+};
+var decorators = [decorator];
+
+exports.decorators = decorators;

package/dist/preview.d.cts

@@ -0,0 +1,3 @@
+declare const decorators: ((storyFn: () => unknown) => unknown)[];
+
+export { decorators };

package/dist/preview.d.ts

@@ -0,0 +1,3 @@
+declare const decorators: ((storyFn: () => unknown) => unknown)[];
+
+export { decorators };

package/dist/preview.js

@@ -0,0 +1,56 @@
+import { addons } from 'storybook/internal/preview-api';
+import { configureRules, runAudit, getRuleById } from '@accesslint/core';
+
+// src/preview.ts
+
+// src/constants.ts
+var ADDON_ID = "accesslint/a11y";
+
+// src/preview.ts
+configureRules({
+  disabledRules: ["accesslint-045"]
+});
+var decorator = (storyFn) => {
+  const story = storyFn();
+  setTimeout(async () => {
+    const start = performance.now();
+    const results = runAudit(document);
+    const duration = Math.round(performance.now() - start);
+    const root = document.getElementById("storybook-root");
+    const scoped = root ? results.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;
+      }
+    }) : results.violations;
+    const enriched = scoped.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
+      };
+    });
+    const failedRuleIds = new Set(scoped.map((v) => v.ruleId));
+    const channel = addons.getChannel();
+    channel.emit(`${ADDON_ID}/results`, enriched);
+    channel.emit(`${ADDON_ID}/meta`, {
+      duration,
+      ruleCount: results.ruleCount,
+      failed: failedRuleIds.size,
+      passed: results.ruleCount - failedRuleIds.size,
+      violations: scoped.length
+    });
+  }, 0);
+  return story;
+};
+var decorators = [decorator];
+
+export { decorators };

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@accesslint/storybook-addon",
+  "version": "0.6.3",
+  "description": "Catch accessibility violations in your Storybook stories as you develop",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/AccessLint/core/issues"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./manager": "./dist/manager.js",
+    "./preview": {
+      "import": "./dist/preview.js",
+      "require": "./dist/preview.cjs"
+    }
+  },
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "*.js",
+    "*.d.ts"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "node -e \"const fs = require('fs'); const v = JSON.parse(fs.readFileSync('node_modules/@accesslint/core/package.json','utf8')).version; const pkg = JSON.parse(fs.readFileSync('package.json','utf8')); pkg.version = v; fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2) + '\\n');\"",
+    "build:watch": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@accesslint/core": "^0.6.3"
+  },
+  "devDependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "storybook": "^8.6.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.0"
+  },
+  "peerDependencies": {
+    "storybook": "^8.0.0"
+  },
+  "keywords": [
+    "storybook-addon",
+    "accessibility",
+    "a11y",
+    "wcag",
+    "aria",
+    "accesslint",
+    "test",
+    "component",
+    "react",
+    "vue",
+    "angular",
+    "svelte",
+    "web-components"
+  ],
+  "storybook": {
+    "displayName": "AccessLint",
+    "icon": "https://accesslint.com/icon.png"
+  },
+  "bundler": {
+    "nodeEntries": [
+      "./src/index.ts"
+    ],
+    "managerEntries": [
+      "./src/manager.tsx"
+    ],
+    "previewEntries": [
+      "./src/preview.ts"
+    ]
+  }
+}