feat: add packages/.storybook (Vite, autodocs, no MDX)

[aresnik11]

feat: stand up packages/.storybook as the Storybook workspace (Vite, autodocs, no MDX)

A new Storybook config at packages/.storybook, copied from the styleguide's setup, that renders the existing component stories with autodocs and no hand-authored MDX. It's wired up as its own Nx project and becomes the Storybook that the repo's scripts and story tests use. The styleguide package and its stories stay in place — only its Nx storybook targets move to the new project. The new config currently reads stories from the styleguide package until we start moving them over.

Why

Part of the testing/docs revamp: the goal is a single Storybook that can eventually host stories from all packages, with docs coming from autodocs rather than MDX prose pages. This stands up that config in a new location as a copy and shifts the tooling (Nx targets, root scripts, story tests) onto it, so styleguide keeps working while we transition. styleguide stays for now and will be retired later. One deviation from the original plan: the config lives at the top level packages/.storybook (not gamut/.storybook) so it can pull stories across packages, not just gamut.

What's included

• project.json (new) — an Nx project named storybook with two targets: dev (@nx/storybook:storybook, port 6006) and build-storybook (@nx/storybook:build, output dist/storybook/styleguide).
• main.ts — react-vite framework, Emotion transform, and the package source aliases from styleguide, with paths adjusted for the new location. Stories are scoped to styleguide/src/lib (object form) and exclude .mdx. Addon set trimmed to addon-docs, addon-a11y, storybook-addon-deep-controls, addon-vitest — addon-links and addon-designs are dropped.
• preview.ts — ported decorators (withEmotion), globalTypes (colorMode / theme / logicalProps / direction), a11y: { test: 'error' }, docs.container (DocsContainer), a trimmed storySort.order, and tags: ['autodocs']. Trimmed of all MDX-only machinery (see below).
• components/ — reduced to just DocsContainer (used by docs.container) and ImageGallery (used by the Icons/Illustrations/Patterns gallery stories). The MDX-authoring doc blocks (Callout, Headers, TableOfContents, TokenTable, ColorScale, Markdown, etc.) are omitted — nothing but MDX pages used them.
• argTypes/, theming/, manager.ts, assets/ — copied as-is.
• Root wiring — start:storybook → nx run storybook:dev; build-storybook → nx run storybook:build-storybook (both now target the new project instead of styleguide). vitest.config.ts test:stories now reads packages/.storybook (Vite root moved to packages to match). packages/styleguide/project.json has its storybook and build-storybook Nx targets removed (lint stays).

preview.ts cleanup (MDX-only)

• WrappedPre — a source-block styling hack targeting a hardcoded, long-stale Emotion class hash; verified non-functional. Removed.
• mdxComponents and the docs.mdxComponents param (CodeOrSourceMdx, HeadersMdx) — MDX prose rendering. Removed.
• docs.toc — table of contents, meaningful only for long MDX pages. Removed.
• storySort.order — trimmed from the old MDX-page list (Meta / About / Contributing / FAQs / UX Writing / AI Tooling / …) down to the real component sections: Foundations, Layouts, Typography, Atoms, Molecules, Organisms, *.

Notes

• Stories still physically live in styleguide/src/lib; this config reads them from there. When stories co-locate into gamut later, add a { directory: '../gamut/src', … } entry to the stories array — no other config changes needed.
• Auto-title is computed relative to styleguide/src/lib, so the sidebar reads Atoms / Molecules / Organisms / etc. (An earlier wildcard glob produced a spurious "Styleguide/src/lib" tree; the scoped directory form fixes that.)
• The new Storybook runs on port 6006 (the port the styleguide Storybook used); there is no longer a second Storybook on 6008. The old packages/styleguide/.storybook config dir is now superseded but left in place — it's no longer launchable via Nx, and removing it is a follow-up.
• Nx gotcha: because the project lives in a dot-directory, the Nx daemon can serve a stale project graph after edits to packages/.storybook/project.json. If a storybook target isn't found, run yarn nx reset.

Testing instructions

1. yarn start (or yarn nx run storybook:dev) — serves on http://localhost:6006.
2. Confirm the sidebar shows Atoms / Molecules / Organisms / Foundations / Layouts / Typography (no "Styleguide" bucket), and that components render.
3. Open a component's Docs tab — confirm autodocs renders (one Docs page per component, no hand-written MDX).
4. Spot-check the gallery stories (Atoms → Icons / Illustrations / Patterns) — they use ImageGallery and should render.
5. yarn test:stories — the story suite runs against the new config and passes. (On a cold cache you may see a batch of "Failed to fetch dynamically imported module" errors; re-run — the warm cache is green.)

PR Checklist

• Related to designs:
• Related to JIRA ticket: GMT-1773
• Version plan added/updated (or not needed)
• I have run this code to verify it works
• This PR includes unit tests for the code change
• This PR includes testing instructions tests for the code change
• The alpha package of this PR is passing end-to-end tests in all relevant Codecademy repositories

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (main@d3bc05c). Learn more about missing BASE report.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #25   +/-   ##
=======================================
  Coverage        ?   91.40%           
=======================================
  Files           ?      408           
  Lines           ?     6903           
  Branches        ?     2220           
=======================================
  Hits            ?     6310           
  Misses          ?      584           
  Partials        ?        9           

Flag	Coverage Δ
pull-request	91.40% <ø> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

[pkg-pr-new]

Open in StackBlitz

@skillsoft/eslint-plugin-gamut

npm i https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/eslint-plugin-gamut@25

yarn add https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/eslint-plugin-gamut@25.tgz

@skillsoft/gamut

npm i https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut@25

yarn add https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut@25.tgz

@skillsoft/gamut-agent-tools

npm i https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-agent-tools@25

yarn add https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-agent-tools@25.tgz

@skillsoft/gamut-icons

npm i https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-icons@25

yarn add https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-icons@25.tgz

@skillsoft/gamut-illustrations

npm i https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-illustrations@25

yarn add https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-illustrations@25.tgz

@skillsoft/gamut-patterns

npm i https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-patterns@25

yarn add https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-patterns@25.tgz

@skillsoft/gamut-styles

npm i https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-styles@25

yarn add https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-styles@25.tgz

@skillsoft/gamut-tests

npm i https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-tests@25

yarn add https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-tests@25.tgz

@skillsoft/variance

npm i https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/variance@25

yarn add https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/variance@25.tgz

commit: 9ef7041

[dreamwasp]

wasn't able to test locally but looks solid!

[LinKCoding]

testing instructions are all passing and the spot check of docs look good!