Storybookで画面操作説明の画像をAI Agentに作らせる

src/
├── Counter.tsx                     # 画面本体（識別子を付ける対象）
├── anchors.ts                      # 識別子集約 module
└── spec-stories/
    ├── withSpecCallouts.tsx        # decorator（全画面共通）
    └── counter.spec.stories.tsx    # 画面ごとに1本（parameters に番号と handler を宣言）

// src/spec-stories/counter.spec.stories.tsx （抜粋）
import type { Meta, StoryObj } from "@storybook/react-vite";
import { delay, http, HttpResponse } from "msw";
import { Counter } from "../Counter";
import { anchors } from "../anchors";
import { SpecCallout, withSpecCallouts } from "./withSpecCallouts"; // decorator の実体は後述

// バッジ番号ごとに、どの要素を指すかだけ宣言する。座標は書かない
const callouts: SpecCallout[] = [
  { n: 1, anchor: { by: "testId", value: anchors.counter.increment } }, // Increment ボタン
  { n: 2, anchor: { by: "role", role: "button", name: "Decrement" } },   // Decrement ボタン (role で拾う)
  { n: 3, anchor: { by: "testId", value: anchors.counter.users } },      // Active users セクション
];

const meta: Meta<typeof Counter> = {
  title: "spec/counter", // 画面IDを名前空間として使う。撮影対象の絞り込みキーになる
  component: Counter,
  parameters: {
    // interval 再計測が落ち着いてから storycap がシャッターを切る
    screenshot: { delay: 1800 },
    specCallouts: callouts,
    // MSW handler で画面が叩く API を止め、表示状態を story ごとに固定する
    msw: {
      handlers: [
        http.get("/api/users", async () => {
          await delay(500); // 非同期ロードの実運用を模す
          return HttpResponse.json([
            { id: 1, name: "Ada Lovelace" },
            { id: 2, name: "Alan Turing" },
          ]);
        }),
      ],
    },
  },
  // decorator が specCallouts を読んで、描画後に番号バッジを重ねる
  decorators: [withSpecCallouts],
};

export default meta;
type Story = StoryObj<typeof Counter>;

// この story の状態を Default という名前で公開する
export const Default: Story = {};

// src/spec-stories/withSpecCallouts.tsx (抜粋)
import type { Decorator } from "@storybook/react-vite";
import { ReactElement, useEffect, useState } from "react";
import { createPortal } from "react-dom";

// 対象要素の指し方は 2 種類。どちらも「壊れにくい識別子」の要件を満たす
export type CalloutAnchor =
  | { by: "testId"; value: string } // data-testid 属性の値で拾う
  | { by: "role"; role: string; name: string }; // ARIA role と accessible name で拾う

// 1 個のコールアウトは「番号 + どの要素を指すか」の組。offsetX/offsetY は微調整用
export interface SpecCallout {
  n: number;
  anchor: CalloutAnchor;
  offsetX?: number;
  offsetY?: number;
}

// role 名から native element の暗黙 role を含めて拾える CSS selector を作る
const IMPLICIT_ROLE_SELECTORS: Record<string, string> = {
  button: "button, [role='button']",
  link: "a[href], [role='link']",
  heading: "h1, h2, h3, h4, h5, h6, [role='heading']",
  textbox: "input:not([type='button']):not([type='submit']), textarea, [role='textbox']",
};

// 識別子から対象 DOM 要素を 1 つ探す
function findElement(anchor: CalloutAnchor): Element | null {
  if (anchor.by === "testId") {
    // testId は data-testid 属性の値で一意に取れる
    return document.querySelector(`[data-testid="${anchor.value}"]`);
  }
  // role の場合は候補を全部拾い、accessible name が一致するものに絞る
  const selector =
    IMPLICIT_ROLE_SELECTORS[anchor.role] ?? `[role="${anchor.role}"]`;
  const candidates = Array.from(document.querySelectorAll(selector));
  for (const el of candidates) {
    const name = (
      el.getAttribute("aria-label") ??
      el.textContent ??
      ""
    ).trim();
    if (name === anchor.name) return el;
  }
  return null;
}

// src/spec-stories/withSpecCallouts.tsx (抜粋)
import type { Decorator } from "@storybook/react-vite";

// Storybook が各 story を描くたびに Story と context を渡してくる
export const withSpecCallouts: Decorator = (Story, context): ReactElement => {
  // story parameters.specCallouts に宣言された配列を取り出す
  const raw: unknown = context.parameters.specCallouts;
  const callouts: SpecCallout[] = Array.isArray(raw)
    ? (raw as SpecCallout[])
    : [];

  return (
    <>
      {/* まず本来の画面を描く */}
      <Story />
      {/* その上に番号バッジをかぶせる。CalloutOverlay の中身は後述 (H2-5) */}
      {callouts.length > 0 && <CalloutOverlay callouts={callouts} />}
    </>
  );
};

// src/spec-stories/counter.spec.stories.tsx (抜粋)
import { anchors } from "../anchors";
import { SpecCallout, withSpecCallouts } from "./withSpecCallouts";

// バッジ番号ごとに、どの要素を指すかだけ宣言する。座標は書かない
const callouts: SpecCallout[] = [
  { n: 1, anchor: { by: "testId", value: anchors.counter.increment } }, // Increment ボタン
  { n: 2, anchor: { by: "role", role: "button", name: "Decrement" } },   // Decrement ボタン (role で拾う)
  { n: 3, anchor: { by: "testId", value: anchors.counter.users } },      // Active users セクション
];

// counter.spec.stories.tsx の meta
const meta: Meta<typeof Counter> = {
  title: "spec/counter", // ← 撮影対象を絞り込むためのキー
  component: Counter,
  parameters: { specCallouts: callouts, msw: { handlers } },
  decorators: [withSpecCallouts],
};

# 撮影対象を spec/** のみに絞る
storycap --serverCmd "npx http-server storybook-static -p 6006 --silent" \
  http://127.0.0.1:6006 \
  --include 'spec/**' \
  --viewport '1280x720' \
  --serverTimeout 90000 \
  --captureTimeout 30000 \
  -o artifacts/screenshots
# --include: title 名前空間で絞る。他の story は撮らない
# --viewport: 撮影時の window サイズを固定する
# --serverTimeout / --captureTimeout: build 済み Storybook が重いときの猶予
# -o: PNG の出力先。title に対応するパスへ書き出される

// src/spec-stories/withSpecCallouts.tsx (抜粋)
function CalloutOverlay({ callouts }: { callouts: SpecCallout[] }) {
  // rects: 番号ごとの実測 (top, left) を保持する
  const [rects, setRects] = useState<CalloutRect[]>([]);

  useEffect(() => {
    // 対象要素を全部拾い、getBoundingClientRect() の結果を rects に書く
    const update = () => setRects(measure(callouts));
    update(); // 初回計測

    // 非同期ロードで DOM が確定するまで、250ms 間隔で再計測を繰り返す
    const interval = window.setInterval(update, 250);
    // 最大 3 秒経ったら interval を止める
    const stop = window.setTimeout(
      () => window.clearInterval(interval),
      3000,
    );
    // storycap が撮影直前に viewport を変えても追従できるように resize を拾う
    window.addEventListener("resize", update);

    // 片付け
    return () => {
      window.clearInterval(interval);
      window.clearTimeout(stop);
      window.removeEventListener("resize", update);
    };
  }, [callouts]);

  // rects から番号バッジを作り、document.body 直下に portal する。詳細は後述
  return createPortal(/* バッジ描画 */, document.body);
}

// counter.spec.stories.tsx (抜粋)
parameters: {
  // 上の interval 再計測が落ち着いてから storycap がシャッターを切る
  screenshot: { delay: 1800 },
  specCallouts: callouts, // 前節の callouts 配列
  msw: {
    handlers: [
      http.get("/api/users", async () => {
        await delay(500); // 実運用の非同期を模して 500ms 待たせる
        return HttpResponse.json([...]);
      }),
    ],
  },
},

一覧画面をローディング中で撮って。
検索バーと結果テーブルに番号を付ける。

{
  "type": "module",
  "dependencies": {
    "react": "18.3.1",
    "react-dom": "18.3.1"
  },
  "devDependencies": {
    "@storybook/react": "8.6.14",
    "@storybook/react-vite": "8.6.14",
    "@types/react": "18.3.12",
    "@types/react-dom": "18.3.1",
    "@vitejs/plugin-react": "4.3.3",
    "http-server": "14.1.1",
    "msw": "2.6.6",
    "msw-storybook-addon": "2.0.4",
    "storybook": "8.6.14",
    "storycap": "5.0.1",
    "typescript": "5.6.3",
    "vite": "5.4.11"
  },
  "scripts": {
    "storybook": "storybook dev -p 6006 --no-open",
    "build-storybook": "storybook build --output-dir storybook-static",
    "screenshot": "storycap --serverCmd \"npx http-server storybook-static -p 6006 --silent\" http://127.0.0.1:6006 --include 'spec/**' --viewport '1280x720' --serverTimeout 90000 --captureTimeout 30000 -o artifacts/screenshots",
    "msw-init": "msw init public --no-save"
  },
  "msw": { "workerDirectory": ["public"] }
}

// .storybook/main.ts
import type { StorybookConfig } from "@storybook/react-vite";

const config: StorybookConfig = {
  stories: ["../src/**/*.stories.@(ts|tsx)"],
  framework: { name: "@storybook/react-vite", options: {} },
  // MSW の service worker (public/mockServiceWorker.js) を配信する
  staticDirs: ["../public"],
  addons: [],
};
export default config;

// .storybook/preview.tsx
import type { Preview } from "@storybook/react-vite";
import { initialize, mswLoader } from "msw-storybook-addon";

// MSW を browser 環境で立ち上げる。未定義エンドポイントは実 fetch にそのまま通す
initialize({ onUnhandledRequest: "bypass" });

const preview: Preview = {
  parameters: {},
  // 各 story の parameters.msw.handlers を読み取って mock を差し込む
  loaders: [mswLoader],
};
export default preview;

// src/anchors.ts
// 画面ごとに、番号が指しうる要素の識別子を集約する
export const anchors = {
  counter: {
    decrement: "counter-decrement", // data-testid の値と 1:1 対応
    count: "counter-count",
    increment: "counter-increment",
    users: "counter-users",
  },
} as const;

// src/Counter.tsx (抜粋)
import { useEffect, useState } from "react";
import { anchors } from "./anchors";

type User = { id: number; name: string };

export function Counter(): JSX.Element {
  const [count, setCount] = useState(0);
  // users は null が「未取得」を表す。story 側では MSW handler が response を返すまで null のままになる
  const [users, setUsers] = useState<User[] | null>(null);

  // マウント時に /api/users を叩く。story 側で MSW が intercept する
  useEffect(() => {
    fetch("/api/users")
      .then((r) => r.json() as Promise<User[]>)
      .then(setUsers);
  }, []);

  return (
    <main>
      <h1>Counter</h1>
      {/* data-testid の値は anchors.ts から引く。story はここを識別子として拾う */}
      <button data-testid={anchors.counter.decrement}>Decrement</button>
      <span data-testid={anchors.counter.count}>{count}</span>
      <button data-testid={anchors.counter.increment}>Increment</button>
      <section data-testid={anchors.counter.users}>
        {/* users が null の間は Loading 表示。MSW handler の delay で観測できる */}
        {users === null ? <p>Loading users...</p> : <ul>{/* ... */}</ul>}
      </section>
    </main>
  );
}

// src/spec-stories/counter.spec.stories.tsx
import type { Meta, StoryObj } from "@storybook/react-vite";
import { delay, http, HttpResponse } from "msw";
import { Counter } from "../Counter";
import { anchors } from "../anchors";
import { SpecCallout, withSpecCallouts } from "./withSpecCallouts";

const callouts: SpecCallout[] = [
  { n: 1, anchor: { by: "testId", value: anchors.counter.increment } },
  { n: 2, anchor: { by: "role", role: "button", name: "Decrement" } },
  { n: 3, anchor: { by: "testId", value: anchors.counter.users } },
];

const meta: Meta<typeof Counter> = {
  title: "spec/counter",
  component: Counter,
  parameters: {
    screenshot: { delay: 1800 },
    specCallouts: callouts,
    msw: {
      handlers: [
        http.get("/api/users", async () => {
          await delay(500);
          return HttpResponse.json([
            { id: 1, name: "Ada Lovelace" },
            { id: 2, name: "Alan Turing" },
          ]);
        }),
      ],
    },
  },
  decorators: [withSpecCallouts],
};

export default meta;
type Story = StoryObj<typeof Counter>;
export const Default: Story = {};