feat: new astro site - #8
Open
LinKCoding wants to merge 36 commits into
Open
LinKCoding wants to merge 36 commits into
LinKCoding wants to merge 36 commits into
Conversation
…s show up before components
LinKCoding
commented
Sep 16, 2026
| "clean-builds": "nx run-many --target=clean --all", | ||
| "clear-modules": "yarn clean-builds && rm -rf node_modules", | ||
| "deploy": "rm -rf ./dist/docs && mv ./dist/storybook/styleguide ./dist/docs && cp -r ./dist/static/* ./dist/docs && gh-pages -b gh-pages -d dist", | ||
| "deploy": "rm -rf ./dist/docs && mv ./dist/storybook/styleguide ./dist/docs && cp -R ./dist/static/. ./dist/docs && gh-pages -t -b gh-pages -d dist", |
Contributor
Author
There was a problem hiding this comment.
Why the deploy script changed
- cp -r ./dist/static/* ./dist/docs && gh-pages -b gh-pages -d dist
+ cp -R ./dist/static/. ./dist/docs && gh-pages -t -b gh-pages -d dist
Both edits exist to get .nojekyll onto the gh-pages branch — it has to clear two dotfile-hostile steps:
1. * is a shell glob and skips dotfiles; dist/static/. copies contents including them.
2. gh-pages defaults to dotfiles: false, so -t is needed to publish it.
Without it: Pages runs Jekyll (build_type: legacy), Jekyll omits _-prefixed dirs, and Astro puts all CSS/JS in _astro/ — so the site deploys green and serves unstyled HTML with no error anywhere. Storybook has no _ dirs, which is why this only starts mattering now.
LinKCoding
marked this pull request as ready for review
September 17, 2026 20:41
LinKCoding
requested review from
aresnik11 and
dreamwasp
and
a lite review from Copilot
September 17, 2026 20:41
There was a problem hiding this comment.
🟡 Changes recommended
The documentation contains invalid package names and links, broken Storybook embeds, and the deployment command does not publish the Astro build output.
Get a fresh assessment by requesting another Copilot review.
Pull request overview
Adds an Astro + Starlight documentation site for Gamut, with new information architecture, embedded Storybook references, theming, and migrated guidance.
Changes:
- Adds the
@skillsoft/gamut-docspackage and documentation content. - Adds Storybook/Figma embed components and custom Starlight styling.
- Updates deployment scripts, package metadata, and Storybook copy.
File summaries
| File | Description |
|---|---|
packages/gamut-docs/* |
New Astro/Starlight site configuration and package setup. |
packages/gamut-docs/src/components/* |
Storybook and Figma embed components. |
packages/gamut-docs/src/content/docs/* |
New getting-started, guide, foundation, concept, and component documentation. |
packages/styleguide/src/lib/Meta/Contributing.mdx |
Updated JIRA board link. |
packages/styleguide/src/lib/About.mdx |
Updated Storybook branding and repository copy. |
package.json |
Added docs scripts and changed deployment packaging. |
yarn.lock |
Added workspace dependency resolutions. |
.yarnrc.yml |
Allows @skillsoft/* packages through the age gate. |
.gitignore |
Ignores Astro build artifacts. |
dist/static/.nojekyll |
Adds GitHub Pages configuration. |
dist/static/CNAME |
Removes the previous CNAME file. |
dist/static/storybook/index.html |
Removes the previous stub page. |
docs/adr/0001-documentation-site-information-architecture.md |
Documents the site information architecture. |
docs/adr/0002-documentation-site-packaging-and-url-topology.md |
Documents deployment packaging and URL topology. |
Review details
- Files reviewed: 160/165 changed files
- Comments generated: 13
- Review effort level: Lite
💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| "clean-builds": "nx run-many --target=clean --all", | ||
| "clear-modules": "yarn clean-builds && rm -rf node_modules", | ||
| "deploy": "rm -rf ./dist/docs && mv ./dist/storybook/styleguide ./dist/docs && cp -r ./dist/static/* ./dist/docs && gh-pages -b gh-pages -d dist", | ||
| "deploy": "rm -rf ./dist/docs && mv ./dist/storybook/styleguide ./dist/docs && cp -R ./dist/static/. ./dist/docs && gh-pages -t -b gh-pages -d dist", |
Comment on lines
+23
to
+24
| const storybookOrigin = 'https://gamut.codecademy.com'; | ||
| const src = `${storybookOrigin}/iframe.html?id=${id}&viewMode=story`; |
|
|
||
| - Always pass `defaultValues` — it's required for reliable behavior, particularly resets. | ||
| - Every key in `validationRules` must have a matching key in `defaultValues`. | ||
| - `validation="onChange"` (the default is `"onChange"` via `useConnectedForm`) disables the submit button until every required field is valid; other [react-hook-form modes](https://react-hook-form.com/docs/useform#mode) validate at different times. |
|
|
||
| - [Text](/components/typography/text/) | ||
|
|
||
| Most other typography concerns (scale, weight, family) are tokens, not components — see [Foundations](/foundations/) and [Typography](/guides/writing-ux-copy/) guidance. |
Comment on lines
+66
to
+68
| id="foundations-system-responsiveproperties--media-queries" | ||
| height="10rem" | ||
| /> |
| Gamut components read theme values for color, spacing, and typography, | ||
| so this page already matches the rest of a Gamut app. | ||
| </Text> | ||
| <Card shadow="soft" p={24}> |
| ## Add the packages | ||
|
|
||
| ```bash | ||
| yarn add @skillsoft/gamut-kit @emotion/react @emotion/styled |
| Use shell (`sh`) syntax highlighting, skip the prompt symbol (`$`), and put one command per block unless several are directly related: | ||
|
|
||
| ```bash | ||
| yarn add @skillsoft/gamut-kit |
Comment on lines
+8
to
+10
| This site is organized around what you're trying to do, not around Gamut's internal component taxonomy. Knowing the four sections below will get you to an answer faster than browsing will. | ||
|
|
||
| ## The four sections |
| 1. **Header** — title, status, links to Figma and source. | ||
| 2. **Usage** — when to reach for this component, including a "When NOT to use" list that names the alternative. | ||
| 3. **Anatomy** — a labeled diagram of the component's parts (skipped for non-visual utilities). | ||
| 4. **Patterns** — goal-first recipes that need real wiring (state, callbacks, composition), skipped for components with no state to wire up. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Overview
Adds a new Gamut documentation website built with Astro + Starlight, which becomes the "front door" for design-system docs while Storybook remains the component API reference.
packages/gamut-docspackage (@codecademy/gamut-docs) — Astro 7 +@astrojs/starlight, with@astrojs/reactso live Gamut components render in pages, andstarlight-sidebar-topicsso each top-level section gets its own sidebar instead of one stacked list.docs/adr/0001-documentation-site-information-architecture.md:getting-started,guides,foundations,components,concepts. Components are grouped by function (Actions, Containers, Inputs & forms, Navigation, Feedback, Status, Overlays, Data display, Typography, Media & assets, Utilities) rather than by Atomic Design tier.StoryEmbed.astroiframes live Storybook canvases rather than re-authoring variants/props content, so Storybook stays the single source of truth for reference material.customCss(src/styles/gamut-core-theme.css) to match brand typography and color.packages/starlighttopackages/gamut-docsso directory, Nx project, and npm package names all agree. Updatedproject.json(name,sourceRoot, threecwdoptions), root scriptsbuild-docs-site/start:docs, two.gitignorepaths, theeditLinkbase URL, and theyarn.lockworkspace resolution.editLinkand GitHub social link fromCodecademy/gamuttoCodecademy/skillsoft-gamut.docs/adr/0002-documentation-site-packaging-and-url-topology.md): removeddist/static/CNAMEand the emptydist/static/storybook/index.htmlstub, addeddist/static/.nojekyll, and fixed thedeployscript tocp -R ./dist/static/.andgh-pages -tso dotfiles actually reach the published branch (Jekyll would otherwise strip Astro's_astro/output).packages/styleguide(About.mdx,Meta/Contributing.mdx,Molecules/Popover/Popover.mdx).PR Checklist
Testing Instructions
Don't make me tap the sign.
yarn start:docs(ornx run gamut-docs:dev) and openhttp://localhost:3333— confirm the Starlight site boots and the homepage renders.yarn start:storybook, visitlocalhost:6006StoryEmbediframe renders a live Storybook canvas and the "Open full story in Storybook →" link opens that story.PR Links and Envs
N/A