@codecademy/styleguide 79.2.4-alpha.38d1e4.0 → 79.2.4-alpha.9ce37a.0

package/.storybook/components/ImageWrapper.tsx

@@ -3,8 +3,9 @@ import * as React from 'react';
 import styled from '@emotion/styled';
 
 interface ImageWrapperProps {
-  src: string;
   alt: string;
+  height: number | string;
+  src: string;
 }
 
 const StyledImage = styled.img`
@@ -15,12 +16,13 @@ const StyledImage = styled.img`
 export const ImageWrapper: React.FC<ImageWrapperProps & BoxProps> = ({
   src,
   alt,
+  height = '216px',
   ...props
 }) => {
   return (
     <Box
       width={'100%'}
-      height="216px"
+      height={height}
       display="flex"
       justifyContent={'center'}
       alignItems="center"

package/.storybook/preview.ts

@@ -45,35 +45,15 @@ const preview: Preview = {
           'Meta',
           [
             'About',
-            'Brand',
-            'Best practices',
+            'Best Practices',
             'Contributing',
-            'Deep Controls add-on',
             'ESLint rules',
             'FAQs',
             'Logical and physical CSS properties',
             'Stories',
             'Brand',
             'Installation',
-            'Stories',
-            'Usage guide',
-            'Gamut writing guide',
-            [
-              'About',
-              'General principles',
-              'Documentation in code',
-              'Formatting',
-              'Language and grammar',
-              'Linking',
-              'Referencing code',
-              'Stories',
-              [
-                'About',
-                'About pages',
-                'Component story documentation',
-                'Component code examples',
-              ],
-            ],
+            'Usage Guide',
             'MCP',
           ],
           'Foundations',

package/CHANGELOG.md

@@ -3,7 +3,7 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-### [79.2.4-alpha.38d1e4.0](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@79.2.3...@codecademy/styleguide@79.2.4-alpha.38d1e4.0) (2026-03-20)
+### [79.2.4-alpha.9ce37a.0](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@79.2.3...@codecademy/styleguide@79.2.4-alpha.9ce37a.0) (2026-03-23)
 
 **Note:** Version bump only for package @codecademy/styleguide
 

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@codecademy/styleguide",
   "description": "Styleguide & Component library for codecademy.com",
-  "version": "79.2.4-alpha.38d1e4.0",
+  "version": "79.2.4-alpha.9ce37a.0",
   "author": "Codecademy Engineering",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
   "repository": "git@github.com:Codecademy/gamut.git",
-  "gitHead": "5b274531193b2e19e11c593da3eb3cb814a7ce7b"
+  "gitHead": "1d57457aa4e2a2d780bc1b006631a7e82e12e314"
 }

package/src/lib/Meta/About.mdx

@@ -6,17 +6,17 @@ import {
   TableOfContents,
 } from '~styleguide/blocks';
 
-import { parameters as bestPracticesParameters } from './Best practices.mdx';
+import { parameters as bestPracticesParameters } from './Best Practices.mdx';
 import { parameters as brandParameters } from './Brand.mdx';
 import { parameters as contributingParameters } from './Contributing.mdx';
-import { parameters as deepControlsParameters } from './Deep Controls add-on.mdx';
+import { parameters as deepControlsParameters } from './Deep Controls Add-On.mdx';
 import { parameters as eslintRulesParameters } from './ESLint rules.mdx';
 import { parameters as faqsParameters } from './FAQs.mdx';
-import { parameters as gamutWritingGuideParameters } from './Gamut writing guide/About.mdx';
 import { parameters as installationParameters } from './Installation.mdx';
 import { parameters as logicalPhysicalParameters } from './Logical and physical CSS properties.mdx';
 import { parameters as mcpAboutParameters } from './MCP/About.mdx';
-import { parameters as usageGuideParameters } from './Usage guide.mdx';
+import { parameters as storiesParameters } from './Stories.mdx';
+import { parameters as usageGuideParameters } from './Usage Guide.mdx';
 
 export const parameters = {
   id: 'Meta',
@@ -36,9 +36,9 @@ export const parameters = {
     deepControlsParameters,
     eslintRulesParameters,
     faqsParameters,
-    gamutWritingGuideParameters,
     installationParameters,
     logicalPhysicalParameters,
+    storiesParameters,
     brandParameters,
     usageGuideParameters,
     mcpAboutParameters,

package/src/lib/Meta/{Best practices.mdx → Best Practices.mdx }

@@ -3,13 +3,13 @@ import { Meta } from '@storybook/blocks';
 import { AboutHeader, Callout } from '~styleguide/blocks';
 
 export const parameters = {
-  id: 'Best practices',
-  title: 'Best practices',
+  id: 'Best Practices',
+  title: 'Best Practices',
   subtitle: 'Current best practices for using the Gamut Design System',
   status: 'current',
 };
 
-<Meta title="Meta/Best practices" />
+<Meta title="Meta/Best Practices" />
 
 <AboutHeader {...parameters} />
 

package/src/lib/Meta/{Gamut writing guide/Stories/Component story documentation.mdx → Stories.mdx}

@@ -1,32 +1,67 @@
 import { Meta } from '@storybook/blocks';
 
-import { AboutHeader } from '~styleguide/blocks';
+import { AboutHeader, LinkTo } from '~styleguide/blocks';
 
 export const parameters = {
-  id: 'Component story documentation',
-  title: 'Component story documentation',
-  subtitle: 'How to write .mdx documentation files for Gamut components',
+  id: 'Stories',
+  title: 'Stories',
+  subtitle: 'Guidelines and tooling for writing Storybook stories and docs.',
   status: 'static',
 };
 
-<Meta title="Meta/Gamut writing guide/Stories/Component story documentation" />
+<Meta title="Meta/Stories" />
 
 <AboutHeader {...parameters} />
 
-The `.mdx` file provides the documentation structure and context for the component. It combines the interactive stories from the `.stories.tsx` file with written documentation, usage guidelines, and metadata.
+## Quick start
 
-## Story structure
+We've provided a few helpful vscode snippets to help you get through boilerplate. To use these start to type these strings in your editor and pick the template and fill out the tab targets.
 
-In our opinion, a good component story page consists of:
+- `component-story`: The default TSX story template.
+- `component-doc`: The default component documentation template - each component should have a `.tsx` and `.mdx` file.
+- `toc-story`: A simple template for a Table of Contents category page.
 
-1. **General Information:** Each component should define some key information on the `<Meta />` component
-2. **Flagship Story + Props:** A single default story showing the default state of the component with a connected props table right below it.
-3. **Variation Stories:** Granular subsections that show the discrete varaitions of the component and describe their use cases
-4. **Usage instructions and Guidelines:** A section that describes how to use the component should and shouldn't be used, and any guidelines that should be followed.
+## File structure and naming
+
+When you make a new story theres a few things to keep in mind:
+
+- The folder structure is indicative of our flavor of atomic design.
+- The folder struture is identical to the storybook hierarchy generated.
+
+First find the right folder for your story in `packages/styleguide/stories` (e.g. `Atoms` | `Molecules` | `Organisms`).
+Once you've found it create a new folder with two new files `#{COMPONENT_NAME}.stories.tsx` and `#{COMPONENT_NAME}.mdx`. You can also store examples or other associated utility files in this folder.
+
+In your new files you can use the above snippets to set up your component add:
+
+```tsx
+// For ComponentName.stories.tsx
+
+import { ComponentName } from '@codecademy/gamut';
+import type { Meta, StoryObj } from '@storybook/react';
+
+const meta: Meta<typeof ComponentName> = {
+  component: ComponentName,
+  args: {
+    variant: 'default',
+  },
+};
 
-## Basic structure
+export default meta;
+type Story = StoryObj<typeof ComponentName>;
 
-Each component should have a `ComponentName.mdx` file that can use the `component-doc` snippet to generate a template that resembles the following:
+export const Default: Story = {
+  args: {
+    children: <img src="./cinna.jpg" alt="jpeg" />,
+  },
+};
+
+export const Secondary: Story = {
+  args: {
+    children: 'Pro Content',
+    variant: 'secondary',
+  },
+};
+```
 
 ```tsx
 // For ComponentName.mdx, more details in the component-doc code snippet
@@ -62,9 +97,16 @@ export const parameters = {
 Etc...
 ```
 
-## General information
+## Story structure
 
-Each component should define key metadata in the `parameters` object:
+In our opinion, a good component story page consists of:
+
+1. **General Information:** Each component should define some key information on the `<Meta />` component
+2. **Flagship Story + Props:** A single default story showing the default state of the component with a connected props table right below it.
+3. **Variation Stories:** Granular subsections that show the discrete varaitions of the component and describe their use cases
+4. **Usage instructions and Guidelines:** A section that describes how to use the component should and shouldn't be used, and any guidelines that should be followed.
+
+### General information
 
 1. `title`: The name of the component, this helps with linking to the story.
 2. `subtitle`: What the component does, and what the component would typically be used for.
@@ -99,9 +141,9 @@ export const parameters = {
 
 ```
 
-## Flagship story
+### Flagship story
 
-The Flagship story for a component should be intended to give the reader a broad overview of its high-level functionality. Its `Canvas` should automatically display the story's code by setting the prop `sourceState="shown"`.
+The Flagship story for a component should be intended to give the reader a broad overview of its high-level functionality. Its `Canvas` should automatically display the story's code by setting the prop sourceState="shown".
 
 Try to include the major behaviors for the component that most readers would need to understand its uses.
 
@@ -114,7 +156,7 @@ Try to include the major behaviors for the component that most readers would nee
 <Controls />
 ```
 
-## Granular stories
+### Granular stories
 
 Each subsequent story should elaborate on an important behavioral feature of the component.
 Try to show a single use of the behavior configurable with args.
@@ -127,3 +169,27 @@ A short description should go here, as well as any variant specific usage guidel
 <Canvas of={AnchorStories.Variant} />
 
 ```
+
+### About pages
+
+An `About.mdx` file should be be included when multiple stories are presented in a folder. E.g. the <LinkTo id="Atoms/Animations/About">Animation</LinkTo> folder which contains an `About.mdx` file with a table of contents that link to specific components -- in this case, the <LinkTo id="Atoms/Animations/ExpandInCollapseOut">ExpandInCollapseOut</LinkTo> component and the <LinkTo id="Atoms/Animations/Rotation">Rotation</LinkTo> component.
+
+Inside the `About.mdx` file, import the `parameters` object from the respective component's `<ComponentName>.mdx` file and pass it to the `<TableOfContents />` component.
+
+```tsx
+import { parameters as componentNameParameters } from './ComponentName.mdx';
+import { parameters as anotherComponentParameters } from './AnotherComponent.mdx';
+
+
+export const parameters = {
+  id: 'ParentDir/FolderName',
+  title: 'FolderName',
+  subtitle: 'Overview of the components in this folder.',
+};
+
+...
+
+<TableOfContents links={addParentPath(parameters.id, [componentNameParameters, anotherComponentParameters]))} />
+```
+
+The `addParentPath` function is used to ensure that the links in the table of contents have the correct IDs, which are derived from the parent path and the component's ID or title.

package/src/lib/Meta/{Usage guide.mdx → Usage Guide.mdx }

@@ -3,14 +3,14 @@ import { Meta } from '@storybook/blocks';
 import { AboutHeader, Callout, ImageWrapper, LinkTo } from '~styleguide/blocks';
 
 export const parameters = {
-  id: 'Usage guide',
-  title: 'Usage guide',
+  id: 'Usage Guide',
+  title: 'Usage Guide',
   subtitle:
     'Tips and tricks to using the Gamut Storybook as a user and developer.',
   status: 'static',
 };
 
-<Meta title="Meta/Usage guide" />
+<Meta title="Meta/Usage Guide" />
 
 <AboutHeader {...parameters} />
 

package/src/lib/Molecules/Tips/InfoTip/InfoTip.mdx

@@ -11,7 +11,7 @@ export const parameters = {
     type: 'figma',
     url: 'https://www.figma.com/file/ReGfRNillGABAj5SlITalN/branch/ayKNSg6QvZUjsgw0FFysW4/%F0%9F%93%90-Gamut?type=design&node-id=41538-55277&mode=design&t=fGkWf5GSl5cj5fQo-0',
   },
-  status: 'updating',
+  status: 'current',
   source: {
     repo: 'gamut',
     githubLink: