chore(storybook): refresh docs and interaction tests

Author: georg-schwarz

.agents/skills/storybook/SKILL.md

@@ -39,6 +39,8 @@ If the user asks to “review the component library in terms of Storybook best p
 - Use `argTypes` for clear control labels and documentation.
 - Avoid coupling stories to app-specific context unless the component requires it.
 - Prefer minimal decorators; if needed, document why they exist.
+- Interaction tests should include at least one assertion so failures are meaningful; use them for behaviors, not purely visual states.
+- Add play functions when user interactions change the UI, trigger callbacks, or guard accessibility flows; skip for static-only components.
 
 ## Repo-specific conventions
 
@@ -51,6 +53,7 @@ If the user asks to “review the component library in terms of Storybook best p
   rather than deep relative paths.
 - Use the `@/` alias for any imports within `src/`.
 - Do not import from `src/pages` or `src/layouts` in stories.
+- Always set `parameters.docs.description.component` with a concise usage note for every component story.
 
 ## Standard workflow
 

.github/workflows/ci.yml

@@ -29,5 +29,8 @@ jobs:
       - name: Typecheck
         run: bun run typecheck
 
+      - name: Storybook tests
+        run: bun run storybook:test
+
       - name: Build
         run: bun run build

.storybook/main.ts

@@ -3,7 +3,11 @@ import type { StorybookConfig } from "@storybook/react-vite";
 const config: StorybookConfig = {
   framework: "@storybook/react-vite",
   stories: ["../src/components/**/*.stories.@(ts|tsx|mdx)"],
-  addons: ["@storybook/addon-a11y"],
+  addons: [
+    "@storybook/addon-a11y",
+    "@storybook/addon-docs",
+    "@storybook/addon-vitest",
+  ],
   viteFinal: async (config) => {
     config.resolve = config.resolve ?? {};
     config.resolve.alias = {

bun.lock

@@ -13,6 +13,7 @@
     "typecheck": "astro check",
     "format": "prettier --write \"src/**/*.{ts,tsx,astro,css,md,mdx}\"",
     "storybook": "storybook dev -p 6006",
+    "storybook:test": "bun x @storybook/cli@10.2.15 test",
     "storybook:build": "storybook build"
   },
   "dependencies": {
@@ -29,6 +30,8 @@
   "devDependencies": {
     "@astrojs/check": "^0.9.6",
     "@storybook/addon-a11y": "^10.2.15",
+    "@storybook/addon-docs": "^10.2.15",
+    "@storybook/addon-vitest": "^10.2.15",
     "@storybook/react-vite": "10.2.15",
     "@tailwindcss/typography": "^0.5.15",
     "@types/node": "^22.10.5",
@@ -43,6 +46,7 @@
     "prettier-plugin-astro": "^0.14.1",
     "prettier-plugin-tailwindcss": "^0.6.9",
     "storybook": "10.2.15",
-    "typescript": "^5.7.2"
+    "typescript": "^5.7.2",
+    "vitest": "^4.0.18"
   }
 }

package.json

@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from "@storybook/react";
+import { expect, fn, userEvent, within } from "storybook/test";
 
 import { Button } from "@/components/atoms/Button";
 
@@ -10,6 +11,15 @@ const meta = {
     children: "Get started",
     variant: "primary",
     size: "md",
+    onClick: fn(),
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Primary action button with size and variant styling. Use `href` to render as a link.",
+      },
+    },
   },
 } satisfies Meta<typeof Button>;
 
@@ -19,6 +29,14 @@ type Story = StoryObj<typeof meta>;
 
 export const Primary: Story = {};
 
+export const Clicked: Story = {
+  play: async ({ args, canvasElement }) => {
+    const canvas = within(canvasElement);
+    await userEvent.click(canvas.getByRole("button"));
+    await expect(args.onClick).toHaveBeenCalled();
+  },
+};
+
 export const Secondary: Story = {
   args: {
     variant: "secondary",

src/components/atoms/Button/Button.stories.tsx

@@ -10,6 +10,14 @@ const meta = {
     title: "Understanding Your",
     highlight: "User Needs",
   },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Headline component that emphasizes a highlighted phrase for visual focus.",
+      },
+    },
+  },
 } satisfies Meta<typeof HighlightedTitle>;
 
 export default meta;

src/components/atoms/HighlightedTitle/HighlightedTitle.stories.tsx

@@ -10,6 +10,14 @@ const meta = {
     description:
       "Simple website software for research projects that want to understand their user needs.",
   },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Supporting text block for section intros and short explanatory copy.",
+      },
+    },
+  },
 } satisfies Meta<typeof SectionDescription>;
 
 export default meta;

src/components/atoms/SectionDescription/SectionDescription.stories.tsx

@@ -9,6 +9,13 @@ const meta = {
   args: {
     title: "What We Offer",
   },
+  parameters: {
+    docs: {
+      description: {
+        component: "Section title with consistent spacing for page headings.",
+      },
+    },
+  },
 } satisfies Meta<typeof SectionHeading>;
 
 export default meta;

src/components/atoms/SectionHeading/SectionHeading.stories.tsx

@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from "@storybook/react";
+import { expect, within } from "storybook/test";
 
 import { Card } from "@/components/molecules/Card";
 
@@ -10,6 +11,14 @@ const meta = {
     title: "Insight sprint",
     description: "Align on user research goals with a simple playbook.",
   },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Compact summary card for features or resources. Supports optional imagery.",
+      },
+    },
+  },
 } satisfies Meta<typeof Card>;
 
 export default meta;
@@ -24,3 +33,16 @@ export const WithImage: Story = {
     imageAlt: "Illustration for share cards",
   },
 };
+
+export const LinkOverlay: Story = {
+  args: {
+    href: "/resources/insight-sprint",
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByRole("link")).toHaveAttribute(
+      "href",
+      "/resources/insight-sprint",
+    );
+  },
+};