Audit the CSF migration for dropped props, and the docs pages it left behind

[spaceninja]

#2405 migrated 84 .stories.mdx files to CSF3 + .mdx with a purpose-written transformer. #2420 then found that thirty stories across thirteen files had silently lost their height prop and were rendering clipped to 100px — cards cut in half, text cut mid-sentence — and that one file had translated it to docs.story.height, which Storybook does not recognise, so it had no effect either.

#2420 fixed height because that is what the visible symptom pointed at. It explicitly did not check whether the transformer dropped other <Story> props, and that question is still open. This issue is for closing it, plus a second audit that working in the same files turned up.

Part 1: sweep every <Story> prop

Diff the <Story> attributes in the pre-#2405 MDX against what survived into CSF. The commit before #2405 is eb1bb81b; the migration landed in 96fd86e1.

Worth knowing that this defect class is invisible to CI. build-storybook passes, and the headless story sweep passes too, because something does render on those pages — just wrongly. Both defects #2405 shipped were caught by looking at the deploy preview, not by any check.

Candidate props to check for, beyond height:

• inline
• decorators
• parameters
• args / argTypes set on the story rather than the meta
• name mismatches that would change a story's ID and break existing links

Outcome is either "nothing else was dropped," which is worth recording so nobody wonders again, or a list of further fixes.

Part 2: audit docs.story.inline: false

Fourteen files currently disable inline rendering. #2420 established that this is not one decision, so it wants auditing story by story rather than a blanket removal — and each change alters rendering:

• Some disable it because of an html-to-react bug the comments cite. logo.stories.js is explicit about this. That reason is obsolete — Upgrade to Storybook 10 + Vite, and Twing 7 #2405 removed the library, and Storybook 10's HTML renderer inlines natively.
• Others do it so media queries resolve against the example's own viewport rather than the docs page. overview.stories.js says exactly this. That reason is still valid, and applies to anything demonstrating breakpoint behaviour — Deck's o-deck--3-column@m, Container, Ground Nav.

The fourteen:

src/objects/page/page.stories.js
src/objects/feature-group/feature-group.stories.js
src/objects/container/container.stories.js
src/objects/list/list.stories.js
src/objects/deck/deck.stories.js
src/objects/overview/overview.stories.js
src/objects/hype-group/hype-group.stories.js
src/components/cloud-cover/cloud-cover.stories.js
src/components/input/input.stories.js
src/components/logo/logo.stories.js
src/components/icon/icon.stories.js
src/components/sky-nav/sky-nav.stories.js
src/components/ground-nav/ground-nav.stories.js
src/vendor/wordpress/utilities.stories.js

(#2391 records this as twelve files; it is fourteen as of 0b1748c6.)

The token pages have the same drift problem — see #1143

This originally carried a third part, about the nine design token pages duplicating their table markup. That is already #1143, open since 2021 and filed when the Theo → Style Dictionary switch turned generated story files into hand-maintained ones. Removed from here rather than duplicated; #1143 is the better home and carries history this issue does not, including the JSX errors that blocked an earlier attempt.

The connection is worth recording on both, though: #2424 removed a width: 10% that all nine pages carried, which was breaking token names mid-word. It survived for years because there is nowhere to fix it once — sizes.mdx, motion.mdx and font.mdx each define their own generateTokenTable (motion's with a different signature), and the other six write the markup inline. So #1143 is not only a tidiness question; the duplication is what let a visible rendering defect persist.

Why this is not part of #2391 item 6

Item 6 removes Gulp — build tooling. None of the above is build tooling, and #2391 will close when item 6 lands, so these need a home that outlives it.

Related: #2391, #2405, #2420, #2424, #1143.

[spaceninja]

Note before anyone picks this up in an automated run: this is not a single-PR unit, and it collides with #2429.

Part 1 is discovery, not a fix. The <Story> prop sweep has unknown output — it may find nothing, or another thirty defects of the #2420 kind. Its deliverable is a report: every <Story> attribute in the pre-#2405 MDX (eb1bb81b) diffed against what survived into CSF (96fd86e1), with each difference classified as carried across, translated, or dropped. Fixes should follow as separate PRs once the list exists, because each one changes rendering and wants its own review.

Part 2 needs per-story design judgment. Whether docs.story.inline: false is still warranted depends on why each story set it — the html-to-react reason is obsolete, the "media queries should resolve against the example's own viewport" reason is still valid. That is a call per story, made by looking at what the example demonstrates, and each change alters rendering. It is not mechanical and should not be swept.

Do not run this in parallel with #2429. Both rewrite the same 84 story files. In parallel they will conflict on nearly every file, and the second to merge will need a redo rather than a rebase. #2429 is the more mechanical of the two, so running it first and rebasing this onto it is the lower-risk order.

The token page duplication that used to be Part 3 lives in #1143.

[spaceninja]

Scheduled as part of #2440, a worklist for an agent-driven run. That issue carries the batching and the shared ground rules; the decision for this issue is in the comment above.

[spaceninja]

Part 1 report: the <Story> prop sweep

Every <Story> attribute in the pre-migration MDX diffed against what is in the CSF files today. The result is close to clean: one genuinely dropped prop.

Diffed against current main (793f5441) rather than 96fd86e1, so that anything #2420 already repaired shows as fixed instead of being re-reported.

Coverage

MDX files at eb1bb81b	84
…containing <Story> tags	67
<Story> tags	249
CSF story exports on main today	249
MDX files with stories lacking a CSF counterpart	0
Attribute instances examined	309

Story-for-story it is 1:1 — no story was lost in the migration, and every one of the 67 files landed somewhere.

Attribute classification

Verdict	Count
Carried across	278
Translated	29
Dropped	2

Attribute usage in the old MDX was: name 249, args 139, parameters 98, argTypes 41, height 30, inline 1.

The 29 translations are all height → parameters.docs.story.iframeHeight, and every value matches — 400px stayed 400px, and so on for all 29. That is #2420's work, verified rather than assumed.

The two dropped props

1. button-swap → Default → inline={false} — genuine, still outstanding.

The only inline attribute in the entire pre-migration MDX, and it did not survive:

<Story
 name="Default"
 inline={false}
 args={{ … }}
>

src/components/button-swap/button-swap.stories.js has no inline setting at any level today, so that story now renders inline on its docs page instead of in an iframe. Storybook 10 spells it parameters: { docs: { story: { inline: false } } }.

Whether it should be restored is a Part 2 question rather than a Part 1 one — Button Swap ships markup but not the swapping script, so there may be no live behaviour that needs its own frame. Worth deciding deliberately rather than leaving it dropped by accident.

2. design/illustrations → "Responsive fallback image" → height="200px" — already decided, no action.

#2420 removed this one on purpose rather than translating it: that story never disabled inline rendering, so it has no iframe to size, and a valid-looking parameter that does nothing is worse than none. Recording it here so the sweep's numbers reconcile.

So: no new defects of the #2420 kind

The sweep's open question was whether another thirty defects were waiting. They are not. Beyond the one inline={false}, every attribute is accounted for.

---

Part 2 inventory: the inline: false list

Not making these calls — each one changes rendering and needs a look at what the example demonstrates. But here is the list to work from. Thirteen locations, twelve of them on the meta, so they apply to every story in the file:

File	Scope
components/cloud-cover/cloud-cover.stories.js	meta
components/ground-nav/ground-nav.stories.js	meta
components/input/input.stories.js	meta
components/logo/logo.stories.js	meta
components/sky-nav/sky-nav.stories.js	meta
objects/container/container.stories.js	meta
objects/deck/deck.stories.js	meta
objects/feature-group/feature-group.stories.js	meta
objects/hype-group/hype-group.stories.js	meta
objects/list/list.stories.js	meta
objects/overview/overview.stories.js	meta
objects/page/page.stories.js	meta
vendor/wordpress/utilities.stories.js	story: Alignment (paired with iframeHeight: '320px')

The meta-level ones are the ones to look at hardest: a single decision there covers a whole file's stories, so a file where only one story needed its own viewport is currently framing all of them.

components/icon/icon.stories.js also matches a grep for inline: false, but that is the Icon component's own inline arg, not the docs setting. Not part of this list.

---

A note on the harness

Two bugs in my own extraction, both caught before they reached this report, in the spirit of the warning in #2440:

• The first pass read the story's display name with /^\s*name: '…'/, which matched a name: nested inside args or inside a Twig template literal. Five stories came back as "NOT FOUND" that plainly exist.
• It then treated the argTypes, shorthand as absent because the regex required a colon, inventing three dropped props in calendar-date and dot-leader.

Both were false alarms of exactly the shape the issue is looking for, which is a good argument for hand-checking every hit before filing anything. The 250th <Story> "tag" was likewise the string <Story> inside a code comment.

Suggested follow-ups

• One small PR restoring or deliberately declining inline={false} on Button Swap's Default story.
• Part 2 as its own pass over the thirteen locations above, story by story.

[spaceninja]

Closing. Part 1 is answered, and Part 2 is being taken only as far as the cases with a documented obsolete reason.

Part 1: nothing else was dropped

That was the open question, and the answer is the good one. Full report in the comment above: 249 <Story> tags across 67 MDX files, 309 attribute instances, and a second pass over 286 nested parameters key paths — because the first pass compared attribute presence only, and #2420's defect lived in nested content.

Everything is accounted for under its original name or a known Storybook 6 → 10 rename (inlineStories → story.inline, iframeHeight → story.iframeHeight, transformSource → source.transform). Story-for-story it is 1:1 with the pre-migration MDX; no story or story ID was lost.

One genuine drop, now fixed: Button Swap's Default story lost inline={false} — the only inline attribute in the whole of the old MDX, which is presumably why nothing pointed at it. Restored in #2448.

So the transformer was clean apart from that one prop, and the height fixes in #2420 all check out: 29 translations, every value preserved.

Part 2: stopping at the documented cases

#2449 removed inline: false from logo and input. Both stale reasons turned out to trace to the same removed library — html-to-react, which Storybook 6 used to convert story HTML into React elements. Logo's comment named it; Input's described the symptom ("React syncs all their properties") without naming the cause, but property syncing between sibling elements only happens if a virtual-DOM differ is managing those nodes. html-to-react is gone from node_modules and the lockfile, and the Storybook 10 HTML renderer assigns innerHTML with no conversion step, so neither mechanism can apply.

Not pursuing the rest. Part 1 established that those settings were carried across faithfully from the original MDX, scope and all, so they predate #2405 and are not a regression. Anyone who wants to revisit them is making a fresh design call, not repairing migration damage.

For whoever that turns out to be, the state of the remaining eleven:

Recorded reason	Files	Reading
"media queries will behave as expected within embedded examples"	ground-nav, sky-nav, container, overview	Still valid — keep
(none)	cloud-cover, deck, feature-group, hype-group, list, page, utilities	Undecided

Two corrections to this issue's own accounting

• The list of fourteen is really thirteen. src/components/icon/icon.stories.js is on it, but its inline: false is the Icon component's own inline arg on the Basic and Muted stories. It has no docs.story.inline setting and never did.
• button-swap now belongs on the list, as of Restore the frame on Button Swap's Default story #2448 — deliberately, not pending review.

Part 3 lives in #1143, as this issue already recorded.