@codecademy/styleguide 79.1.0 → 79.1.1-alpha.0165b9.0

package/.storybook/preview.ts

@@ -45,15 +45,33 @@ const preview: Preview = {
           'Meta',
           [
             'About',
-            'Best Practices',
+            'Brand',
+            'Best practices',
             'Contributing',
+            'Deep Controls add-on',
             'ESLint rules',
             'FAQs',
-            'Stories',
-            'Brand',
             'Installation',
-            'Usage Guide',
+            'Stories',
+            'Usage guide',
             'MCP',
+            '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',
+              ],
+            ],
           ],
           'Foundations',
           'Layouts',

package/CHANGELOG.md

@@ -3,6 +3,10 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+### [79.1.1-alpha.0165b9.0](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@79.1.0...@codecademy/styleguide@79.1.1-alpha.0165b9.0) (2026-02-11)
+
+**Note:** Version bump only for package @codecademy/styleguide
+
 ## [79.1.0](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@79.0.0...@codecademy/styleguide@79.1.0) (2026-02-09)
 
 ### Features

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@codecademy/styleguide",
   "description": "Styleguide & Component library for codecademy.com",
-  "version": "79.1.0",
+  "version": "79.1.1-alpha.0165b9.0",
   "author": "Codecademy Engineering",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
   "repository": "git@github.com:Codecademy/gamut.git",
-  "gitHead": "d7c3a3fce650a3746f208c8e59aef7a5e49e9ec7"
+  "gitHead": "36a5b43d98d0c4bc396b0abaa56bcfb52b757904"
 }

package/src/lib/Meta/About.mdx

@@ -6,16 +6,16 @@ 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 mcpAboutParameters } from './MCP/About.mdx';
-import { parameters as storiesParameters } from './Stories.mdx';
-import { parameters as usageGuideParameters } from './Usage Guide.mdx';
+import { parameters as usageGuideParameters } from './Usage guide.mdx';
 
 export const parameters = {
   id: 'Meta',
@@ -35,7 +35,7 @@ export const parameters = {
     deepControlsParameters,
     eslintRulesParameters,
     faqsParameters,
-    storiesParameters,
+    gamutWritingGuideParameters,
     brandParameters,
     installationParameters,
     usageGuideParameters,

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/About.mdx

@@ -0,0 +1,43 @@
+import { Meta } from '@storybook/blocks';
+
+import {
+  AboutHeader,
+  addParentPath,
+  LinkTo,
+  TableOfContents,
+} from '~styleguide/blocks';
+
+import { parameters as documentationInCodeParameters } from './Documentation in code.mdx';
+import { parameters as formattingParameters } from './Formatting.mdx';
+import { parameters as generalPrinciplesParameters } from './General principles.mdx';
+import { parameters as languageAndGrammarParameters } from './Language and grammar.mdx';
+import { parameters as linkingParameters } from './Linking.mdx';
+import { parameters as referencingCodeParameters } from './Referencing code.mdx';
+import { parameters as storiesParameters } from './Stories/About.mdx';
+
+export const parameters = {
+  id: 'Meta/Gamut writing guide',
+  title: 'Gamut writing guide',
+  subtitle:
+    'Guidelines and standards for creating consistent, clear, and effective documentation.',
+};
+
+<Meta title="Meta/Gamut writing guide/About" />
+
+<AboutHeader {...parameters} />
+
+Welcome to the Gamut writing guide! Thanks for taking the time to learn about our documentation standards. This guide helps keep our documentation clear, consistent, and useful across the Gamut design system.
+
+The <LinkTo id="Meta/Gamut writing guide/General principles">General principles</LinkTo> is a great place to get an overview of our documentation philosophy and best practices. For specific topics like formatting, code documentation, or writing Storybook stories, check out the other pages below.
+
+<TableOfContents
+  links={addParentPath(parameters.id, [
+    generalPrinciplesParameters,
+    documentationInCodeParameters,
+    formattingParameters,
+    languageAndGrammarParameters,
+    linkingParameters,
+    referencingCodeParameters,
+    storiesParameters,
+  ])}
+/>

package/src/lib/Meta/Gamut writing guide/Documentation in code.mdx

@@ -0,0 +1,134 @@
+import { Meta } from '@storybook/blocks';
+
+import { ComponentHeader } from '~styleguide/blocks';
+
+export const parameters = {
+  title: 'Documentation in code',
+  subtitle: `Guidelines for documenting code in Gamut component files`,
+  status: 'current',
+};
+
+<Meta title="Meta/Gamut writing guide/Documentation in code" />
+
+<ComponentHeader {...parameters} />
+
+Good documentation starts in the code itself. By documenting components, props, and functions directly in source files, we create a single source of truth that stays synchronized with the implementation and surfaces automatically in developer tools and Storybook.
+
+## Naming conventions
+
+Clear, descriptive names reduce the need for comments and make code self-documenting. Choose names that reveal intent and follow established patterns.
+
+### Variables and constants
+
+- Use `camelCase` for variables: `userName`, `isLoading`, `itemCount`
+- Use descriptive names that reveal purpose: `filteredResults` not `arr`
+- Boolean variables should use `is`, `has`, `should`, or `can` prefixes: `isVisible`, `hasError`, `shouldRender`
+- Use `SCREAMING_SNAKE_CASE` for true constants: `MAX_RETRY_COUNT`, `DEFAULT_TIMEOUT`
+- Avoid single-letter names except for short loops or mathematical operations
+- Use plural names for arrays and collections: `users`, `menuItems`
+
+### Functions and methods
+
+- Use `camelCase` for function names: `getUserData`, `calculateTotal`, `handleClick`
+- Start with verbs that describe the action: `get`, `set`, `fetch`, `handle`, `render`, `calculate`
+- Event handlers should use `handle` prefix: `handleSubmit`, `handleClickOutside`
+- Boolean-returning functions should ask a question: `isValidEmail`, `canAccessResource`, `hasPermission`
+- Keep names concise but descriptive: `fetchUserProfile` not `getUserProfileDataFromAPI`
+
+### Components
+
+- Use `PascalCase` for component names: `Button`, `UserProfile`, `NavigationMenu`
+- Name folders to match the component: `Button`, `UserProfile`
+  - Subsequently, name files within the folder to match the component: `Button.tsx`, `UserProfile.tsx`
+- Use descriptive names that indicate purpose: `SkipToContent`, `RadialProgress`, `Toggle`
+- Avoid generic names like `Component`, `Container`, `Wrapper` without context
+
+## Code comments
+
+Comments should explain _why_ code exists, not _what_ it does. Well-named variables and functions handle the "what." Reserve comments for non-obvious decisions, complex logic, and important context.
+
+### When to comment
+
+- **Complex logic**: Explain algorithms or non-obvious implementations
+
+  ```tsx
+  // Use binary search for O(log n) performance on sorted arrays
+  const index = binarySearch(sortedArray, target);
+  ```
+
+- **Business logic**: Document requirements or constraints
+
+  ```tsx
+  // Per WCAG 2.2, focus must return to trigger element on close
+  previousFocusRef.current?.focus();
+  ```
+
+- **Workarounds**: Explain temporary fixes or browser-specific code
+
+  ```tsx
+  // Safari doesn't support :focus-visible, fallback to :focus
+  // TODO: Remove when Safari 15+ is minimum supported version
+  ```
+
+- **Non-obvious decisions**: Clarify choices that might seem strange
+  ```tsx
+  // Delay state update to avoid race condition with async validation
+  setTimeout(() => setIsValid(true), 0);
+  ```
+
+### When NOT to comment
+
+- **Self-explanatory code**: Good names eliminate the need
+
+  ```tsx
+  // ❌ Bad: Comment restates the code
+  // Set loading to true
+  setIsLoading(true);
+
+  // ✅ Good: Code is self-documenting
+  setIsLoading(true);
+  ```
+
+- **Commented-out code**: Delete it; Git tracks history
+  ```tsx
+  // ❌ Bad: Dead code clutters the file
+  // const oldImplementation = () => { ... };
+  ```
+
+### Comment style
+
+- Use `//` for single-line comments, add a space after the `//` before commenting
+- Use `/** */` for JSDoc comments on exports (functions, types, components)
+- Write complete sentences with proper punctuation
+- Keep comments up-to-date when code changes
+
+## API reference
+
+Well-documented APIs make components easier to use and understand. Clear prop descriptions and type information help developers implement components correctly without needing to read the source code.
+
+### Props documentation:
+
+Add [JSDoc](https://jsdoc.app/) comments to the props to provide additional clarity for what these props do — these comments is used by TypeScript when hovering over a prop, additional it also shows up in the props table of a component's story in Storybook.
+
+```tsx
+export type ButtonProps = {
+  /**
+   * The visual style variant of the button.
+   */
+  variant: 'primary' | 'secondary';
+
+  /**
+   * Whether the button is disabled.
+   */
+  disabled?: boolean;
+};
+```
+
+### Guidelines:
+
+- Full sentence descriptions
+- Start boolean descriptions with "Whether"
+- Document required vs. optional props
+- Include type information
+- Use discretion for whether a comment is needed or not
+  - If unsure, include a comment

package/src/lib/Meta/Gamut writing guide/Formatting.mdx

@@ -0,0 +1,69 @@
+import { Meta } from '@storybook/blocks';
+
+import { AboutHeader } from '~styleguide/blocks';
+
+export const parameters = {
+  id: 'Formatting',
+  title: 'Formatting',
+  subtitle: 'Standards for formatting text and content in documentation',
+  status: 'static',
+};
+
+<Meta title="Meta/Gamut writing guide/Formatting" />
+
+<AboutHeader {...parameters} />
+
+Consistent formatting makes documentation easier to scan, understand, and implement. These standards ensure our content is predictable and professional across all Gamut components.
+
+## Numbers
+
+- Use numerals for all numbers
+- Use commas for thousands: 1,000
+
+## Units of Measurement
+
+- Use standard units: px, rem, em, %
+- Include space between number and unit in prose: "16 pixels"
+- No space in code: `16px`, `2rem`
+
+## Lists
+
+Lists help break down complex information into digestible pieces. Use them to organize features, steps, or related concepts.
+
+### Bulleted lists:
+
+- Use for unordered items
+- Use parallel structure
+- End with periods if items are complete sentences
+- No periods if items are fragments
+
+### Numbered lists:
+
+- Use for sequential steps or prioritized items
+- Start each item with a capital letter
+
+## Code Blocks
+
+- Use triple backticks (` ``` `) with language identifier (e.g., `tsx`, `javascript`, `css`)
+- Include comments for complex examples
+- Keep examples concise and focused
+
+Example:
+
+````
+```tsx
+<TextButton onClick={handleClick}> Click me </TextButton>
+```
+````
+
+## Headings Hierarchy
+
+- Start with second-level headings (`<h2>` in HTML, `##` in Markdown). The first level heading is automatically set by the title parameter.
+- Don't skip heading levels. This ensures a logical reading order.
+
+## Whitespace
+
+- Use blank lines to separate sections
+- Don't use multiple consecutive blank lines
+- Indent code consistently (2 spaces for TypeScript/TSX)
+  - When using tabs, set them to 2 spaces

package/src/lib/Meta/Gamut writing guide/General principles.mdx

@@ -0,0 +1,46 @@
+import { Meta } from '@storybook/blocks';
+
+import { AboutHeader } from '~styleguide/blocks';
+
+export const parameters = {
+  id: 'General principles',
+  title: 'General principles',
+  subtitle: 'Core principles for writing effective documentation',
+  status: 'static',
+};
+
+<Meta title="Meta/Gamut writing guide/General principles" />
+
+<AboutHeader {...parameters} />
+
+Good documentation does more than describe — it helps people succeed. These principles guide how we write about Gamut components, with a focus on clarity, accessibility, and usefulness. Whether documenting a new component or updating existing content, prioritize being clear about what something does, honest about its limitations, and helpful in showing how to use it effectively. We want to remove barriers and make it easier for designers and developers to do great work. Like our design system itself, this guide is a living document — it will continue to evolve as we add new features and learn from our users.
+
+## Voice and tone
+
+- Friendly and conversational: Write as if explaining to a colleague
+- Prefer "we" when a pronoun is needed
+  - "You" is acceptable when necessary, e.g., "Use your best judgement"
+- Encouraging without overpromising: Be supportive but realistic
+- Global audience awareness: Avoid idioms, slang, and culturally-specific references
+
+## Inclusivity
+
+- Use inclusive language that makes all contributors feel welcome
+- Define terms when first introduced
+- Consider contributors of varying experience levels and roles (designers and developers)
+
+## Transparency
+
+- Clearly indicate component status:
+  - `current`: Stable, recommended for use
+  - `updating`: In progress, API may change
+  - `deprecated`: Still supported but slated for deletion — do not use for new work
+  - `static`: Reference material, no active development
+- Link to source code and design files (GitHub, Figma)
+
+## Consistency
+
+- Use a single term for the same concept, including how it's referred to between the heading, body copy, and code examples.
+- Do not use the same term for 2 different concepts.
+- Maintain consistent component naming across packages
+- Follow established patterns from existing components

package/src/lib/Meta/Gamut writing guide/Language and grammar.mdx

@@ -0,0 +1,54 @@
+import { Meta } from '@storybook/blocks';
+
+import { AboutHeader } from '~styleguide/blocks';
+
+export const parameters = {
+  id: 'Language and grammar',
+  title: 'Language and grammar',
+  subtitle: 'Guidelines for language usage and grammar in documentation',
+  status: 'static',
+};
+
+<Meta title="Meta/Gamut writing guide/Language and grammar" />
+
+<AboutHeader {...parameters} />
+
+## Voice
+
+Use active voice rather than passive voice — it makes clear who should do what and eliminates ambiguity about responsibilities. Passive voice obscures who handles what and makes documentation harder to follow. E.g. "The component renders..." not "The component is rendered by..."
+
+Use imperative mood for instructions: "Add the component" not "You should add the component"
+
+## Tense
+
+Use present tense for current functionality — it's the simplest and most direct form of a verb, making writing more clearer. The more conditional or future tense is used, the harder the audience has to work to understand the meaning. E.g. "The `StrokeButton` component accepts a `variant` prop."
+
+- Use future tense sparingly, only for confirmed features
+- Avoid past tense except in changelogs or historical context
+
+## Pronouns
+
+With active voice and imperative mood, we can often forgo pronouns entirely. However, if a pronoun is still necessary, consider these rules:
+
+- Prefer "we" when a pronoun is needed
+  - "You" is acceptable when necessary, e.g., "Use your best judgement"
+- Avoid "I/my/me" entirely
+
+## Articles
+
+- Use articles (a, an, the) for clarity
+- Omit articles in lists when appropriate for brevity
+
+## Abbreviations and Acronyms
+
+- Spell out on first use: "Web Content Accessibility Guidelines (WCAG)"
+- Use abbreviations for common terms in the domain of web design and development:
+  - HTML, CSS, API, UI, UX, etc.
+- Avoid uncommon abbreviations without definition
+
+## Capitalization
+
+- Sentence case for all headings, buttons, and UI text
+- PascalCase for component names: `MyComponent`, `ButtonGroup`
+- camelCase for props and variables: `onClick`, `backgroundColor`
+- Capitalize proper nouns: Codecademy, Storybook, Figma, GitHub

package/src/lib/Meta/Gamut writing guide/Linking.mdx

@@ -0,0 +1,60 @@
+import { Meta } from '@storybook/blocks';
+
+import { AboutHeader, Callout } from '~styleguide/blocks';
+
+export const parameters = {
+  id: 'Linking',
+  title: 'Linking',
+  subtitle: 'Best practices for linking within documentation',
+  status: 'static',
+};
+
+<Meta title="Meta/Gamut writing guide/Linking" />
+
+<AboutHeader {...parameters} />
+
+Use links to help users navigate between related components and resources. This guide covers linking within Storybook, to external sites, and writing clear link text.
+
+## Internal Links
+
+Use the `LinkTo` component from ‘~styleguide/blocks' and set the id prop as the story’s id value.
+
+```tsx
+import { LinkTo } from '~styleguide/blocks';
+<LinkTo id="Meta/Stories">Stories</LinkTo>
+<LinkTo id="Atoms/Animations/About">Animation</LinkTo>
+```
+
+### Guidelines:
+
+- Link text describes the destination, not the action: "See the [Stories page](#)" not "[See the Stories page](#)"
+- Use descriptive link text that makes sense out of context: "[Stories page](#)" not "[Click here](#)"
+- Link component names to their documentation
+- Verify that the link works correctly
+- 2-3 words minimum for easy clicking
+- Unique link text when multiple links on page
+- Meaningful and descriptive: conveys destination
+- Action-oriented when appropriate: "View the component"
+
+## External Links
+
+When linking to external resources like official documentation or tools, use the following guidelines.
+
+### Markdown Links:
+
+Use Markdown for external links. The examples below will open in a new tab:
+
+```markdown
+[GitHub Repository](https://github.com/Codecademy/gamut)
+[React Documentation](https://react.dev)
+```
+
+### Anchor Component:
+
+For more control over the link, use the `Anchor` component. The example below will open in the current tab:
+
+```tsx
+<Anchor href="https://github.com/Codecademy/gamut">Gamut Repository</Anchor>
+```
+
+<Callout text='To open external links in new tabs, use `target="_blank" rel="noreferrer"` together for security. However, avoid forcing this behavior unless necessary — users can choose to open links in new tabs themselves.' />

package/src/lib/Meta/Gamut writing guide/Referencing code.mdx

@@ -0,0 +1,86 @@
+import { Meta } from '@storybook/blocks';
+
+import { AboutHeader } from '~styleguide/blocks';
+
+export const parameters = {
+  id: 'Refencing code',
+  title: 'Refencing code',
+  subtitle: 'Guidelines for referencing code and UI Elements',
+  status: 'static',
+};
+
+<Meta title="Meta/Gamut writing guide/Referencing code" />
+
+<AboutHeader {...parameters} />
+
+This guide covers how to reference code elements, UI components, file paths, and commands consistently throughout documentation. Following these conventions ensures clarity and maintains a professional, accessible tone across all Gamut documentation.
+
+## Code in Text
+
+- Use backticks for inline code: `onClick`, `flex-direction`, `Box`, `StrokeButton`, `variant`, backgroundColor`, etc.
+- File and package names: `Button.tsx`, `package.json`, `@codecademy/gamut`
+  - When linking to them, use permalinks instead
+- Values assigned for props or variables: `true`, `15px`, `null`
+- "The `Box` component" (first mention) → "the component" (subsequent mentions)
+- When plural, the component should stay singular and the “component” is the pluralized, e.g
+  - ✅ “These `Box` components are…”
+  - ❌ “These `Boxes` are…”
+
+## Code samples
+
+Code samples help developers understand how to implement components and patterns. Use them to demonstrate real-world usage, not just syntax.
+
+### Format:
+
+```tsx
+import { Button } from '@codecademy/gamut';
+export const Example: React.FC = () => (
+  <Button variant="primary">Click me</Button>
+);
+```
+
+### Guidelines:
+
+- Include necessary imports
+- Use realistic, working examples
+- Add comments for complex logic
+- Keep examples focused on one concept
+- Use TypeScript types
+
+## Command-Line syntax
+
+When documenting commands, use consistent formatting to make them easy to copy and execute. Commands should be ready to run without modification.
+
+### Format:
+
+```bash
+yarn add @codecademy/gamut-kit
+```
+
+### Guidelines:
+
+- Use shell (`sh`) syntax highlighting for commands
+- Don't include command prompt symbols ($, #)
+- Show one command per block unless related
+
+## File Paths
+
+- Use backticks for file paths: `packages/gamut/src/Button/index.tsx`
+- Use relative paths when contextual (e.g., `./types.ts`)
+- Use paths from workspace root when further clarity is needed (e.g., `packages/gamut/src/Button/index.tsx`)
+- Use "in" for code locations: "in the `componentName.mdx` file"
+
+## UI element references
+
+When instructing users to interact with the interface, clearly identify what the UI elements are, where to find them, and how to interact with them.
+
+### Format:
+
+- Bold for UI labels: **Next**, **Back**, **Close**
+- Describe location: "Click the **Theme Switcher** (paintbrush icon)"
+- Use sentence case: "the **Show code** button"
+- Prefer words that aren't specific to input devices
+  - Use "click" as a device agnostic verb
+- Avoid directional language:
+  - ✅ "the following/adjacent form" or "in the previous section"
+  - ❌ "the form on the right" or "in the section above"

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} />