@codecademy/styleguide 79.2.4-alpha.b2bca8.0 → 79.2.4-alpha.be71e3.0

package/src/lib/Meta/Gamut writing guide/Stories/About pages.mdx

@@ -0,0 +1,49 @@
+import { Meta } from '@storybook/blocks';
+
+import { AboutHeader, LinkTo } from '~styleguide/blocks';
+
+export const parameters = {
+  id: 'About pages',
+  title: 'About pages',
+  subtitle: 'How to create table of contents pages for component folders',
+  status: 'static',
+};
+
+<Meta title="Meta/Gamut writing guide/Stories/About pages" />
+
+<AboutHeader {...parameters} />
+
+An `About.mdx` file serves as a landing page for folders containing multiple related components or stories. Write a clear overview explaining what the folder contains and how components relate. Organize components logically by importance or usage frequency, use descriptive subtitles, and keep it concise—these are entry points, not detailed documentation.
+
+## When to create an About page
+
+Create an `About.mdx` file when multiple stories are presented in a folder. For example, the <LinkTo id="Atoms/Animations/About">Animation</LinkTo> folder contains an `About.mdx` file with a table of contents that links 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.
+
+## Basic structure
+
+Inside the `About.mdx` file, use the `toc-story` snippet to generate a template. 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
+
+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.
+
+This function takes two arguments:
+
+1. The parent path (`parameters.id`) - defines the folder hierarchy
+2. An array of parameter objects from child components/pages

package/src/lib/Meta/Gamut writing guide/Stories/About.mdx

@@ -0,0 +1,57 @@
+import { Meta } from '@storybook/blocks';
+
+import {
+  AboutHeader,
+  addParentPath,
+  TableOfContents,
+} from '~styleguide/blocks';
+
+import { parameters as aboutPagesParameters } from './About pages.mdx';
+import { parameters as componentCodeExamplesParameters } from './Component code examples.mdx';
+import { parameters as componentStoryDocumentationParameters } from './Component story documentation.mdx';
+
+export const parameters = {
+  id: 'Meta/Gamut writing guide/Stories',
+  title: 'Stories',
+  subtitle: 'Guidelines and tooling for writing Storybook stories and docs.',
+  status: 'static',
+};
+
+<Meta title="Meta/Gamut writing guide/Stories/About" />
+
+<AboutHeader {...parameters} />
+
+This guide covers how to write and organize Storybook stories for Gamut components. Use it when creating new component documentation or updating existing stories.
+
+## Quick start
+
+We've provided a few helpful vscode snippets to help get through boilerplate. To use these start to type these strings in the editor and pick the template and fill out the tab targets.
+
+- `component-story`: The default TSX story template for code examples.
+- `component-doc`: The default component documentation template for a component's MDX file.
+- `toc-story`: A simple template for a Table of Contents category page.
+
+## File structure and naming
+
+When making a new story, there are 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.
+- For non-component related file names with more than one word, use a space between the words and use sentence case.
+  - Example: `General principles.mdx`
+  - Component-related files should use kebab-case: `RadialProgress.mdx`
+
+First find the right folder for the story in `packages/styleguide/stories` (e.g. `Atoms` | `Molecules` | `Organisms`).
+After finding it, create a new folder with two new files `#{COMPONENT_NAME}.stories.tsx` and `#{COMPONENT_NAME}.mdx`. This folder can also contain examples or other associated utility files.
+
+## Learn more
+
+Explore the pages below for detailed guidelines on each part of the story structure:
+
+<TableOfContents
+  links={addParentPath(parameters.id, [
+    aboutPagesParameters,
+    componentStoryDocumentationParameters,
+    componentCodeExamplesParameters,
+  ])}
+/>

package/src/lib/Meta/Gamut writing guide/Stories/Component code examples.mdx

@@ -0,0 +1,79 @@
+import { Meta } from '@storybook/blocks';
+
+import { AboutHeader } from '~styleguide/blocks';
+
+export const parameters = {
+  id: 'Component code examples',
+  title: 'Component code examples',
+  subtitle: 'How to write .stories.tsx files for Gamut components',
+  status: 'static',
+};
+
+<Meta title="Meta/Gamut writing guide/Stories/Component code examples" />
+
+<AboutHeader {...parameters} />
+
+The `.stories.tsx` file defines the interactive examples and variations of the component. These stories power the Storybook UI and provide developers with working code examples. Use concrete, realistic values in self-contained stories that are easy to copy and paste. Each story should demonstrate one clear variation or behavior.
+
+Our guidelines stem from the Storybook, specifically the [Component Story Format (CSF)](https://storybook.js.org/docs/8/api/csf) and [Writing stories in TypeScript](https://storybook.js.org/docs/writing-stories/typescript) documentation. We recommend using these resources for more detailed information.
+
+## Basic structure
+
+Each component should have a `ComponentName.stories.tsx` file that can use the `component-story` snippet to generate a template that resembles the following:
+
+```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',
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ComponentName>;
+
+export const Default: Story = {
+  args: {
+    children: <img src="./cinna.jpg" alt="jpeg" />,
+  },
+};
+
+export const Secondary: Story = {
+  args: {
+    children: 'Pro Content',
+    variant: 'secondary',
+  },
+};
+```
+
+## Rendered code examples
+
+Examples rendered via `<Canvas of={componentName.example} />` are stored in the `componentName.stories.tsx` file.
+
+When providing an example, use concretely applicable values. Avoid naming things like foo or bar, instead be opt for values that could be used in a practical setting, e.g. if deciding on the name of a boolean variable, don't use isBar — instead, consider the setting the example could be used, isModalOpen.
+
+When a user clicks **Show Code**, Storybook tries to show the underlying code, but Storybook is not good with abstractions. Instead of opting to be DRY, each example should contain all the code to render and when a user clicks on **Show Code**, they should be able to copy the code provided and render in their own project.
+
+```tsx
+// ❌ Don't abstract the logic into an InfoTipExample
+export const Default: Story = {
+  render: (args) => <InfoTipExample {...args} />,
+};
+```
+
+```tsx
+// ✅ Provide the actual code
+export const Default: Story = {
+  render: (args) => (
+    <FlexBox center m={24} py={64}>
+      <Text mr={4}>Some text that needs info</Text>
+      <InfoTip {...args} />
+    </FlexBox>
+  ),
+};
+```

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

@@ -1,67 +1,32 @@
 import { Meta } from '@storybook/blocks';
 
-import { AboutHeader, LinkTo } from '~styleguide/blocks';
+import { AboutHeader } from '~styleguide/blocks';
 
 export const parameters = {
-  id: 'Stories',
-  title: 'Stories',
-  subtitle: 'Guidelines and tooling for writing Storybook stories and docs.',
+  id: 'Component story documentation',
+  title: 'Component story documentation',
+  subtitle: 'How to write .mdx documentation files for Gamut components',
   status: 'static',
 };
 
-<Meta title="Meta/Stories" />
+<Meta title="Meta/Gamut writing guide/Stories/Component story documentation" />
 
 <AboutHeader {...parameters} />
 
-## Quick start
+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.
 
-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.
-
-- `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.
-
-## 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';
+## Story structure
 
-const meta: Meta<typeof ComponentName> = {
-  component: ComponentName,
-  args: {
-    variant: 'default',
-  },
-};
+In our opinion, a good component story page consists of:
 
-export default meta;
-type Story = StoryObj<typeof ComponentName>;
+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.
 
-export const Default: Story = {
-  args: {
-    children: <img src="./cinna.jpg" alt="jpeg" />,
-  },
-};
+## Basic structure
 
-export const Secondary: Story = {
-  args: {
-    children: 'Pro Content',
-    variant: 'secondary',
-  },
-};
-```
+Each component should have a `ComponentName.mdx` file that can use the `component-doc` snippet to generate a template that resembles the following:
 
 ```tsx
 // For ComponentName.mdx, more details in the component-doc code snippet
@@ -97,16 +62,9 @@ export const parameters = {
 Etc...
 ```
 
-## Story structure
+## General information
 
-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
+Each component should define key metadata in the `parameters` object:
 
 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.
@@ -141,9 +99,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.
 
@@ -156,7 +114,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.
@@ -169,27 +127,3 @@ 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: 'current',
+  status: 'updating',
   source: {
     repo: 'gamut',
     githubLink: