docs: MVP-3 nest Core under new Reference sidebar root

[caseyisonit]

Description

Adopt the persona-first Storybook sidebar from the docs-overhaul v2 RFC (MVP-3). Core moves from a top-level sidebar entry to Reference > Core, making Reference a distinct top-level sibling to Get started, Components, Learn, and Contribute.

Motivation and context

Per the docs-overhaul v2 RFC, the sidebar should lead with persona ("who are you?") before topic ("what is it?"). Before this change, Core lived at the sidebar root alongside audience-shaped entries; after this change, Core is one of several Reference sub-pages — sitting next to placeholders for the future API reference (CEM-driven) and Design tokens pages populated in later phases.

No content moves; the change is titlePrefix + storySort only.

What changed

• .storybook/main.ts: the three directory: '../../core' story entries (mdx, stories, dev-only tests) now use titlePrefix: 'Reference/Core' instead of 'Core'.
• .storybook/preview.ts storySort: root-level Core entry removed; root-level Reference entry added after the generated Contribute block, containing Core (Overview / Controllers) plus placeholders for API reference and Design tokens.

What didn't change

• No component moves.
• No story renames.
• The `Contribute > Reference` generated entry (which references the `CONTRIBUTOR-DOCS/reference/` folder) is unrelated and continues to render as before — the two "Reference" paths are distinct (`Contribute/Reference` vs. top-level `Reference`).

Related issue(s)

• Part of the docs-overhaul v2 RFC MVP sequence (MVP-α, MVP-4, MVP-2, MVP-6a, MVP-6c, MVP-β already merged / in review; this is MVP-3).

Author's checklist

• I have read the CONTRIBUTING and PULL_REQUESTS documents.
• I have reviewed 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.

No changeset: this PR only reorders Storybook sidebar entries; nothing is published to npm.
No automated tests: Storybook sidebar config is validated by Storybook's build at CI time; a failing storySort or missing titlePrefix would surface as a build error in the Preview Documentation workflow.

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

• Sidebar renders with Reference as a top-level entry

  1. Check out this branch
  2. From `2nd-gen/packages/swc`, run `yarn storybook`
  3. Expect the left sidebar to show, in order: Get started → Components → Learn → Contribute → Reference
  4. Expand Reference; expect `Core` containing `Overview` and `Controllers`

• Core stories still resolve

  1. Click Reference > Core > Overview — expect the Core overview page to render
  2. Click Reference > Core > Controllers > Focus group navigation controller — expect the existing controller stories to render

• Production build preserves the same tree

  1. Run `yarn storybook:build` (or use the Preview Documentation workflow output on this PR)
  2. Verify the built Storybook's sidebar matches step 1, with Reference as a top-level entry

Device review

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

Accessibility testing checklist

Sidebar reorg only; no changes to focus order, keyboard handling, or screen reader output within components.

• Keyboard (required — document steps below)

  1. In the Storybook sidebar, press Tab through the top-level entries
  2. Expect focus to land on each top-level label in order (Get started → Components → Learn → Contribute → Reference) with a visible focus indicator
  3. Press Enter on Reference
  4. Expect the group to expand, focus remains on Reference

• Screen reader (required — document steps below)

  1. Navigate to the sidebar's top-level Reference item
  2. Expect the item to be announced with its name ("Reference") and expand/collapse state
  3. Expand Reference
  4. Expect child items "Core", "API reference", and "Design tokens" to be announced

🤖 Generated with Claude Code

[changeset-bot]

⚠️ No Changeset found

Latest commit: 4e912d5

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-6210

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.