docs(swc): convert 2nd-gen pattern and controller story JSDoc to per-unit MDX

[caseyisonit]

Description

Follow-up to PR #6349 (components). Move long-form documentation that previously lived as JSDoc comments above story exports in .stories.ts files into per-unit MDX files at each unit's root, for the remaining 2nd-gen genres: conversational AI patterns and the focusgroup navigation controller.

Scope (this PR): 11 patterns + 1 controller.

• Patterns (2nd-gen/packages/swc/patterns/conversational-ai/<name>/<name>.mdx):
  • system-message, suggestion-item, conversation-turn, message-sources, upload-artifact, user-message, suggestion-group, message-feedback, response-status, prompt-field, conversation-thread
• Controller (2nd-gen/packages/core/controllers/focusgroup-navigation-controller/focusgroup-navigation-controller.mdx):
  • Validates the controller branch of DocsFooter, which auto-omits <ApiTable /> (controllers expose a TypeScript class, not a custom element manifest) and renders a hand-authored ## API section instead.

This branch is based on caseyisonit/docs-to-mdx. Merge that PR first; this PR contains pattern + controller changes only.

Motivation and context

Same as PR #6349: story-level JSDoc was the only mechanism for long-form prose attached to each story, which forced documentation-only stories (tags: ['description-only']) and section-order parameters to influence rendering order. Per-unit MDX provides:

• A single, hand-authored source of truth per pattern/controller, with explicit <Canvas of={Story} /> references.
• Prose-only sections without fake stories: description-only stories are deleted; their prose lives in MDX as Canvas-less sections (e.g. the controller's Usage, API, Accessibility, Appendix prose).
• Exact reuse of the DocsHeader / DocsFooter blocks shipped in PR docs(swc): convert 2nd-gen component story JSDoc to per-component MDX #6349 — no new infrastructure.

Related issue(s)

• Follows PR docs(swc): convert 2nd-gen component story JSDoc to per-component MDX #6349 (SWC-2228); tracked internally under the same umbrella effort.
• SWC-2230

Screenshots (if appropriate)

Visual parity verified by spot-checking system-message, conversation-thread, and the focusgroup-navigation-controller Docs pages against the template-driven rendering.

Author's checklist

• I have read the CONTRIBUTING and PULL_REQUESTS documents.
• I have reviewed at the Accessibility Practices for this feature, see: Aria Practices
• I have added automated tests to cover my changes.
• I have included a well-written changeset if my change needs to be published.
• I have included updated documentation if my change required it.

Reviewer's checklist

• Includes a Github Issue with appropriate flag or Jira ticket number without a link
• Includes thoughtfully written changeset if changes suggested include patch, minor, or major features
• Automated tests cover all use cases and follow best practices for writing
• Validated on all supported browsers
• All VRTs are approved before the author can update Golden Hash

Manual review test cases

• Per-pattern Docs pages render via MDX

  1. Run yarn storybook in 2nd-gen/packages/swc/
  2. Open each of: /docs/patterns-conversational-ai-system-message--docs, patterns-conversational-ai-suggestion-item--docs, patterns-conversational-ai-conversation-turn--docs, patterns-conversational-ai-message-sources--docs, patterns-conversational-ai-upload-artifact--docs, patterns-conversational-ai-user-message--docs, patterns-conversational-ai-suggestion-group--docs, patterns-conversational-ai-message-feedback--docs, patterns-conversational-ai-response-status--docs, patterns-conversational-ai-prompt-field--docs, patterns-conversational-ai-conversation-thread--docs
  3. Expect: each page renders header (title, subtitle, description, overview), all applicable section headings (Anatomy, Options, States, Behaviors, Accessibility), and footer (Primary, Controls, Feedback link). No regressions versus the template-driven rendering.

• Controller Docs page omits <ApiTable />

  1. Open /docs/core-controllers-focus-group-navigation-controller--docs
  2. Expect: page renders with ## What it does, ## Basic usage, ## Behaviors, ## Accessibility, ## API (hand-authored table — no auto-generated ApiTable), ## Appendix, and <Primary /> / <Controls /> from the playground. Confirm the Behaviors stories render correctly (HorizontalToolbar, BothAxesLinear, VerticalMenu, SkipDisabledMenu, Grid, ProgrammaticFocus, TextPrefixFocus).

• No regressions in untagged stories

  1. Confirm conversation-thread's FullPattern story (no section tag) is not surfaced on the Docs page; it remains an opt-in story export.

Device review

• Did it pass in Desktop?
• Did it pass in (emulated) Mobile?
• Did it pass in (emulated) iPad?

Accessibility testing checklist

Required: Complete each applicable item and document your testing steps.

• Keyboard (required — document steps below)

  1. From the Docs page of any converted pattern or the controller, press Tab through the page.
  2. Expect: focus order moves through in-page anchor links (per section), then into interactive content inside each <Canvas> (form controls, prompt-field textarea, suggestion buttons, focus-group toolbar items, etc.).
  3. Confirm focus is visible at every stop and no focus traps exist inside <Canvas> regions.
  4. For the focusgroup-navigation-controller page, confirm the demo toolbars/menus/grids respond to Arrow keys, Home/End, and Page Up/Page Down per the documented behavior.

• Screen reader (required — document steps below)

  1. With VoiceOver (macOS) or NVDA (Windows), navigate each converted Docs page by heading.
  2. Expect: heading levels read in canonical order — h1 (title), h2 (sections), h3 (per-story titles in hideTitle=false sections like Options/Behaviors), h4/h5 (JSDoc-derived subsections).
  3. Confirm each rendered story Canvas exposes its component(s) with role, name, and state as defined in the unit's accessibility behavior. No new announcements are introduced by the MDX wrapper itself.

[changeset-bot]

⚠️ No Changeset found

Latest commit: d48d771

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

📚 Branch Preview Links

• Documentation Site (first-gen)
• Storybook (first-gen)
• Storybook (second-gen)

🔍 First Generation Visual Regression Test Results

When a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:

• Spectrum | Light | Medium | LTR
• Spectrum | Dark | Large | RTL
• Express | Light | Medium | LTR
• Express | Dark | Large | RTL
• Spectrum-two | Light | Medium | LTR
• Spectrum-two | Dark | Large | RTL
• High Contrast Mode | Medium | LTR

Deployed to Azure Blob Storage: pr-6351

If the changes are expected, update the current_golden_images_cache hash in the circleci config to accept the new images. Instructions are included in that file.
If the changes are unexpected, you can investigate the cause of the differences and update the code accordingly.

[rise-erpelding]

This one is looking pretty good also! Would love a response about the controller docs and a tiny change there before approving but otherwise, once we rebase with the previous PR, this should be good to go!

[rise-erpelding]

This should go away on its own once the .gitignore changes from the other branch are in!

[caseyisonit]

this should have been removed with the merge from main but ill make sure its gone before this merges.

[rise-erpelding]

Hey, is this doc set to only be visible in Storybook when run locally? I don't see it in the preview build, just local. Do we want to surface this to consumers at some point?

[caseyisonit]

yeah this is an internal doc. i think thats a larger discussion down the road about core and when and what we expose. for the scope of this work i didnt change any architecture.

[rise-erpelding]

Do we need <DocsFooter /> here? I'm seeing an extra, empty API section and I'm wondering if this component might be the reason why.

[caseyisonit]

ahh i just need to move the API header in to the conditional render so if its not a component footer then the table is left out.

[rise-erpelding]

I wonder if a follow-up ticket to refine these conv AI stories would be helpful here - now that we're using mdx, we have a bit more freedom in the way these components get documented, is there anything we would want to change?

Maybe it's not necessary though? Just a thought, maybe @aramos-adobe has thoughts here.

[caseyisonit]

yes i totally 100% agree with this, this feels like its own initiative and touches on the team sync convo we need to have about "what are patterns and how do we approach them structuraly"

[rise-erpelding]

We weren't supposed to have autodocs tagged on Playground stories, right? So we've trimmed that story from all the docs pages for Conv AI?

[caseyisonit]

Correct, the autodocs tag will trigger Storybook's internal mechanism that will use DocumentTemplate over the MDX, so we remove this so MDX wins. dev will make sure it's exposed in the sidebar.