CLI: Sync storybook setup prompt with eval pattern-copy-play improvements

[kasperpeulen]

What I did

Brings the CLI's shipped storybook setup AI prompt (code/lib/cli-storybook/src/ai/prompt.ts) up to parity with recent improvements made to the eval harness's pattern-copy-play prompt. The two were near-identical until recently, but eval-side edits have drifted forward. This PR ports the drift that applies to end-users without touching anything eval-only.

Three synced pieces:

1. New Step 7: "Prove CSS is loaded in exactly one story" — asks the agent to include, in exactly one story, a play function that asserts a component-specific computed style via getComputedStyle. Catches the "component renders but CSS never loaded" failure (missing global CSS import, Tailwind not configured, theme provider not wired up) that otherwise passes toBeVisible checks. Step 8/9 renumbered accordingly.

2. End-state paragraph in the intro — clarifies the goal: the shared preview should own all providers/CSS/browser state/network mocks so that just rendering the component in the story is enough. (Original eval text said "the component import and a render call", which biased toward render: () => ...; softened in a later commit here to avoid that bias.)

3. New #### Args vs render subsection under Step 5 — teaches when to prefer args vs when to reach for render, with two full examples (Button with args, Button inside Card with render). Follows the existing hasCsfFactoryPreview / CSF3 branch pattern via two new helpers: getArgsStoryExample and getRenderCompositionExample.

None of this changes behavior — it's prompt content shipped to the user as markdown by storybook setup. The only code additions are the two new helper functions that follow the style of the existing getStoryExample / getNeedsWorkTagExample / getPageStoryExample helpers.

Checklist for Contributors

Testing

The changes in this PR are covered in the following automated tests:

• stories
• unit tests
• integration tests
• end-to-end tests

Pure prompt content change in a function that returns a dedented markdown string. No existing tests target getSetupInstructions output; I did not add snapshot tests — the prompt evolves too often for snapshots to be useful, and the behavior we care about is "does the agent follow the prompt", which is measured by the eval harness (companion PR #34595 adds a diff-level assertion for the CSS step specifically).

Manual testing

1. Run storybook setup (or storybook init flow that invokes it) against a small React app.
2. Inspect the generated prompt markdown (or the transcript it was sent to the agent).
3. Verify:
   • The intro contains "The end state should be a Storybook where any component..."
   • Step 5 has a #### Args vs render subsection with two code examples.
   • Step 7 is "Prove CSS is loaded in exactly one story" with a getComputedStyle example.
   • Steps 8 and 9 renumbered from the previous 7 and 8.
4. For CSF Factory projects, verify both new examples use preview.meta(...) / meta.story(...) syntax; for CSF3 projects, they use Meta<typeof ...> / StoryObj<typeof meta>.

Documentation

• Add or update documentation reflecting your changes
• If you are deprecating/removing a feature, make sure to update MIGRATION.MD

No user-facing documentation changes — the prompt itself is the doc, delivered at storybook setup time.

Checklist for Maintainers

• When this PR is ready for testing, make sure to add ci:normal, ci:merged or ci:daily GH label to it to run a specific set of sandboxes.
• Make sure this PR contains one of the labels below.

Labels applied: build, ci:normal.

🦋 Canary release

This PR does not have a canary release associated. You can request a canary release of this pull request by mentioning the @storybookjs/core team here.

core team members can create a canary release here or locally with gh workflow run --repo storybookjs/storybook publish.yml --field pr=<PR_NUMBER>

Summary by CodeRabbit

• Documentation

  • Stricter Storybook setup instructions requiring shared preview for providers, CSS, browser state, and network mocks
  • New "Args vs render" guidance with two story templates showing args-driven and render-based composition
  • Step sequence updated so verification steps are renumbered and validation requirements clarified

• New Features

  • Added a dedicated CSS-check story pattern to assert computed component styles

[nx-cloud]

View your CI Pipeline Execution ↗ for commit ed2f5dd

Command	Status	Duration	Result
nx run-many -t compile,check,knip,test,lint,fmt...	✅ Succeeded	12m 34s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-04-20 14:29:13 UTC

[coderabbitai]

📝 Walkthrough

Walkthrough

Updated the Storybook AI prompt generator to require a shared preview for providers/CSS/network mocks, add an "Args vs render" guidance with two story templates, replace Step 7 with a single CssCheck story using getComputedStyle, and renumber verification steps.

Changes

Cohort / File(s)	Summary
Prompt Template & helper updates code/lib/cli-storybook/src/ai/prompt.ts	Extended setup instructions to enforce shared preview (providers, CSS, browser state, network mocks); added "Args vs render" guidance and two generators (getArgsStoryExample, getRenderCompositionExample) that emit CSF/preview-aware snippets; replaced Step 7 with a single CssCheck story asserting computed CSS via getComputedStyle; renumbered subsequent verification steps.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• CLI: Improve ai prepare prompt #34532 — Modifies the same code/lib/cli-storybook/src/ai/prompt.ts file with overlapping changes to generated setup instructions and story/snippet helper logic.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

code/lib/cli-storybook/src/ai/prompt.ts (1)

777-780: Add a post-interaction assertion (or remove the click) in InsideCard examples.

Right now the example performs a click without verifying its effect, which models “click-around” behavior instead of behavior validation.

Suggested adjustment

-      play: async ({ canvas, userEvent }) => {
+      play: async ({ canvas }) => {
         await expect(canvas.getByRole('button', { name: /save/i })).toBeVisible();
-        await userEvent.click(canvas.getByRole('button', { name: /save/i }));
       },

-    play: async ({ canvas, userEvent }) => {
+    play: async ({ canvas }) => {
       await expect(canvas.getByRole('button', { name: /save/i })).toBeVisible();
-      await userEvent.click(canvas.getByRole('button', { name: /save/i }));
     },

Based on learnings: “Test real behavior, not just syntax patterns.”

Also applies to: 809-812

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@code/lib/cli-storybook/src/ai/prompt.ts` around lines 777 - 780, The story’s
play handler for the InsideCard examples clicks the "save" button but never
asserts the resulting behavior; update the play functions that use
canvas.getByRole('button', { name: /save/i }) and userEvent.click to include a
post-interaction assertion that verifies the expected outcome (for example, a
"saved" confirmation appears, the button becomes disabled, or some UI text
changes), or if there is no observable effect to assert, remove the
userEvent.click call entirely; apply this change for the play blocks shown (the
one using canvas.getByRole('button', { name: /save/i }) at the snippet and the
similar occurrence around lines 809-812) so each play either validates behavior
or does not perform the click.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@code/lib/cli-storybook/src/ai/prompt.ts`:
- Around line 777-780: The story’s play handler for the InsideCard examples
clicks the "save" button but never asserts the resulting behavior; update the
play functions that use canvas.getByRole('button', { name: /save/i }) and
userEvent.click to include a post-interaction assertion that verifies the
expected outcome (for example, a "saved" confirmation appears, the button
becomes disabled, or some UI text changes), or if there is no observable effect
to assert, remove the userEvent.click call entirely; apply this change for the
play blocks shown (the one using canvas.getByRole('button', { name: /save/i })
at the snippet and the similar occurrence around lines 809-812) so each play
either validates behavior or does not perform the click.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 6caea4f5-7303-4cf8-a584-67c691aa26a6

📥 Commits

Reviewing files that changed from the base of the PR and between 8ed4332 and 47b3d60.

📒 Files selected for processing (1)

• code/lib/cli-storybook/src/ai/prompt.ts

[yannbf]

Nice! Can you add the project language (js/ts) to the metadata banner at the top of the prompt and conditionally mention typescript stuff as well?

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@code/lib/cli-storybook/src/ai/prompt.ts`:
- Around line 780-783: The play function contains a click-only interaction (play
async ({ canvas, userEvent }) => { ...
userEvent.click(canvas.getByRole('button', { name: /save/i })) }) with no
post-click assertion; update the play to include a post-condition assertion
after userEvent.click (for example assert that a success message appears, the
save button becomes disabled, a form value changes, or a specific element is
visible/contains expected text) OR remove the click entirely; apply the same
change to the other similar play helper that uses canvas.getByRole('button', {
name: /save/i }) and userEvent.click to ensure each example asserts real
behavior rather than only performing a click.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d26dbb4e-a1bb-44d9-9e08-8f3032f18a38

📥 Commits

Reviewing files that changed from the base of the PR and between 47b3d60 and ed2f5dd.

📒 Files selected for processing (1)

• code/lib/cli-storybook/src/ai/prompt.ts

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Avoid click-only interactions in example play functions.

These clicks have no post-click assertion, which teaches a weaker pattern than the surrounding guidance. Add a post-condition assertion or remove the click.

Based on learnings, "Test real behavior, not just syntax patterns".

Also applies to: 812-815

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@code/lib/cli-storybook/src/ai/prompt.ts` around lines 780 - 783, The play
function contains a click-only interaction (play async ({ canvas, userEvent })
=> { ... userEvent.click(canvas.getByRole('button', { name: /save/i })) }) with
no post-click assertion; update the play to include a post-condition assertion
after userEvent.click (for example assert that a success message appears, the
save button becomes disabled, a form value changes, or a specific element is
visible/contains expected text) OR remove the click entirely; apply the same
change to the other similar play helper that uses canvas.getByRole('button', {
name: /save/i }) and userEvent.click to ensure each example asserts real
behavior rather than only performing a click.

[kasperpeulen]

Superseded by #34602, which ports these same changes (end-state paragraph, Args vs render subsection, Step 7 CssCheck story) directly into the new code/lib/cli-storybook/src/ai/prompts/pattern-copy-play.ts as part of the "eval prompts from the CLI" refactor. See the commit titled 'CLI: Port pattern-copy-play prompt improvements from #34596' on that branch.

Closing; the eval grade-check companion is #34595, and the core telemetry companion is #34600.