From a2ef92bf783e1f258648899d2d180a7c929cc8fe Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Fri, 24 Oct 2025 18:39:06 -0400 Subject: [PATCH 01/23] started foundation for style guide --- packages/styleguide/.storybook/preview.ts | 9 ++++- packages/styleguide/src/lib/Meta/About.mdx | 2 + .../src/lib/Meta/Style Guide/About.mdx | 38 +++++++++++++++++++ .../lib/Meta/Style Guide/Code Examples.mdx | 18 +++++++++ .../Meta/Style Guide/Computer Interfaces.mdx | 18 +++++++++ .../src/lib/Meta/Style Guide/Formatting.mdx | 18 +++++++++ .../Meta/Style Guide/General Principles.mdx | 18 +++++++++ .../Meta/Style Guide/Language and Grammer.mdx | 18 +++++++++ .../src/lib/Meta/Style Guide/Linking.mdx | 18 +++++++++ 9 files changed, 156 insertions(+), 1 deletion(-) create mode 100644 packages/styleguide/src/lib/Meta/Style Guide/About.mdx create mode 100644 packages/styleguide/src/lib/Meta/Style Guide/Code Examples.mdx create mode 100644 packages/styleguide/src/lib/Meta/Style Guide/Computer Interfaces.mdx create mode 100644 packages/styleguide/src/lib/Meta/Style Guide/Formatting.mdx create mode 100644 packages/styleguide/src/lib/Meta/Style Guide/General Principles.mdx create mode 100644 packages/styleguide/src/lib/Meta/Style Guide/Language and Grammer.mdx create mode 100644 packages/styleguide/src/lib/Meta/Style Guide/Linking.mdx diff --git a/packages/styleguide/.storybook/preview.ts b/packages/styleguide/.storybook/preview.ts index bccda059ff0..0e0c6cda038 100644 --- a/packages/styleguide/.storybook/preview.ts +++ b/packages/styleguide/.storybook/preview.ts @@ -23,7 +23,14 @@ const preview: Preview = { order: [ 'Gamut', 'Meta', - ['About', 'Best Practices', 'Contributing', 'FAQs', 'Stories'], + [ + 'About', + 'Best Practices', + 'Contributing', + 'FAQs', + 'Stories', + 'Style Guide', + ], 'Foundations', 'Layouts', 'Typography', diff --git a/packages/styleguide/src/lib/Meta/About.mdx b/packages/styleguide/src/lib/Meta/About.mdx index 5fadd6a3420..23da60eb30b 100644 --- a/packages/styleguide/src/lib/Meta/About.mdx +++ b/packages/styleguide/src/lib/Meta/About.mdx @@ -12,6 +12,7 @@ import { parameters as contributingParameters } from './Contributing.mdx'; import { parameters as faqsParameters } from './FAQs.mdx'; import { parameters as installationParameters } from './Installation.mdx'; import { parameters as storiesParameters } from './Stories.mdx'; +import { parameters as styleGuideParameters } from './Style Guide/About.mdx'; import { parameters as usageGuideParameters } from './Usage Guide.mdx'; export const parameters = { @@ -31,6 +32,7 @@ export const parameters = { contributingParameters, faqsParameters, storiesParameters, + styleGuideParameters, brandParameters, installationParameters, usageGuideParameters, diff --git a/packages/styleguide/src/lib/Meta/Style Guide/About.mdx b/packages/styleguide/src/lib/Meta/Style Guide/About.mdx new file mode 100644 index 00000000000..593283942a2 --- /dev/null +++ b/packages/styleguide/src/lib/Meta/Style Guide/About.mdx @@ -0,0 +1,38 @@ +import { Meta } from '@storybook/blocks'; + +import { + AboutHeader, + addParentPath, + TableOfContents, +} from '~styleguide/blocks'; + +import { parameters as codeExamplesParameters } from './Code Examples.mdx'; +import { parameters as componentPagesParameters } from './Component Pages.mdx'; +import { parameters as computerInterfacesParameters } from './Computer Interfaces.mdx'; +import { parameters as formattingParameters } from './Formatting.mdx'; +import { parameters as generalPrinciplesParameters } from './General Principles.mdx'; +import { parameters as languageAndGrammerParameters } from './Language and Grammer.mdx'; +import { parameters as linkingParameters } from './Linking.mdx'; + +export const parameters = { + id: 'Meta/Style Guide', + title: 'Style Guide', + subtitle: + 'Guidelines and standards for creating consistent, clear, and effective documentation.', +}; + + + + + + diff --git a/packages/styleguide/src/lib/Meta/Style Guide/Code Examples.mdx b/packages/styleguide/src/lib/Meta/Style Guide/Code Examples.mdx new file mode 100644 index 00000000000..b5c59de14bd --- /dev/null +++ b/packages/styleguide/src/lib/Meta/Style Guide/Code Examples.mdx @@ -0,0 +1,18 @@ +import { Meta } from '@storybook/blocks'; + +import { AboutHeader } from '~styleguide/blocks'; + +export const parameters = { + id: 'Code Examples', + title: 'Code Examples', + subtitle: 'Standards for writing and formatting code examples', + status: 'static', +}; + + + + + +# Code Examples + +Content coming soon. diff --git a/packages/styleguide/src/lib/Meta/Style Guide/Computer Interfaces.mdx b/packages/styleguide/src/lib/Meta/Style Guide/Computer Interfaces.mdx new file mode 100644 index 00000000000..ebdd46d7aa4 --- /dev/null +++ b/packages/styleguide/src/lib/Meta/Style Guide/Computer Interfaces.mdx @@ -0,0 +1,18 @@ +import { Meta } from '@storybook/blocks'; + +import { AboutHeader } from '~styleguide/blocks'; + +export const parameters = { + id: 'Computer Interfaces', + title: 'Computer Interfaces', + subtitle: 'Guidelines for documenting computer interfaces and UI elements', + status: 'static', +}; + + + + + +# Computer Interfaces + +Content coming soon. diff --git a/packages/styleguide/src/lib/Meta/Style Guide/Formatting.mdx b/packages/styleguide/src/lib/Meta/Style Guide/Formatting.mdx new file mode 100644 index 00000000000..5082014f802 --- /dev/null +++ b/packages/styleguide/src/lib/Meta/Style Guide/Formatting.mdx @@ -0,0 +1,18 @@ +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', +}; + + + + + +# Formatting + +Content coming soon. diff --git a/packages/styleguide/src/lib/Meta/Style Guide/General Principles.mdx b/packages/styleguide/src/lib/Meta/Style Guide/General Principles.mdx new file mode 100644 index 00000000000..c74f3ba72b2 --- /dev/null +++ b/packages/styleguide/src/lib/Meta/Style Guide/General Principles.mdx @@ -0,0 +1,18 @@ +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', +}; + + + + + +# General Principles + +Content coming soon. diff --git a/packages/styleguide/src/lib/Meta/Style Guide/Language and Grammer.mdx b/packages/styleguide/src/lib/Meta/Style Guide/Language and Grammer.mdx new file mode 100644 index 00000000000..cb8450afd3d --- /dev/null +++ b/packages/styleguide/src/lib/Meta/Style Guide/Language and Grammer.mdx @@ -0,0 +1,18 @@ +import { Meta } from '@storybook/blocks'; + +import { AboutHeader } from '~styleguide/blocks'; + +export const parameters = { + id: 'Language and Grammer', + title: 'Language and Grammer', + subtitle: 'Guidelines for language usage and grammar in documentation', + status: 'static', +}; + + + + + +# Language and Grammer + +Content coming soon. diff --git a/packages/styleguide/src/lib/Meta/Style Guide/Linking.mdx b/packages/styleguide/src/lib/Meta/Style Guide/Linking.mdx new file mode 100644 index 00000000000..f5081274c6f --- /dev/null +++ b/packages/styleguide/src/lib/Meta/Style Guide/Linking.mdx @@ -0,0 +1,18 @@ +import { Meta } from '@storybook/blocks'; + +import { AboutHeader } from '~styleguide/blocks'; + +export const parameters = { + id: 'Linking', + title: 'Linking', + subtitle: 'Best practices for linking within documentation', + status: 'static', +}; + + + + + +# Linking + +Content coming soon. From be93a53a52035c845b4c7808af5798634016f9c6 Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Mon, 27 Oct 2025 12:45:26 -0400 Subject: [PATCH 02/23] round out docs --- .../lib/Meta/Style Guide/Code Examples.mdx | 27 +++++- .../lib/Meta/Style Guide/Component Pages.mdx | 56 +++++++++++ .../Meta/Style Guide/Computer Interfaces.mdx | 94 ++++++++++++++++++- .../src/lib/Meta/Style Guide/Formatting.mdx | 51 +++++++++- .../Meta/Style Guide/General Principles.mdx | 31 +++++- .../Meta/Style Guide/Language and Grammer.mdx | 48 +++++++++- .../src/lib/Meta/Style Guide/Linking.mdx | 60 +++++++++++- 7 files changed, 355 insertions(+), 12 deletions(-) create mode 100644 packages/styleguide/src/lib/Meta/Style Guide/Component Pages.mdx diff --git a/packages/styleguide/src/lib/Meta/Style Guide/Code Examples.mdx b/packages/styleguide/src/lib/Meta/Style Guide/Code Examples.mdx index b5c59de14bd..2bac54551c8 100644 --- a/packages/styleguide/src/lib/Meta/Style Guide/Code Examples.mdx +++ b/packages/styleguide/src/lib/Meta/Style Guide/Code Examples.mdx @@ -13,6 +13,29 @@ export const parameters = { -# Code Examples +## Best Practices -Content coming soon. +- Use Gamut tokens +- Use Emotion’s styled function to provide one-off styling + - use Gamut-style’s css() and variant() helper functions +- Avoid using the inline styled={{}} prop + +## Example Structure + +```tsx +// ✅ Good example +import { Button } from '@codecademy/gamut'; + +export const Example: React.FC = () => ( + +); +``` + +## Comments in Code + +- Use `//` for single-line comments +- Keep comments concise +- Explain "why" not "what" +- Use comments to highlight important patterns diff --git a/packages/styleguide/src/lib/Meta/Style Guide/Component Pages.mdx b/packages/styleguide/src/lib/Meta/Style Guide/Component Pages.mdx new file mode 100644 index 00000000000..eba249bb280 --- /dev/null +++ b/packages/styleguide/src/lib/Meta/Style Guide/Component Pages.mdx @@ -0,0 +1,56 @@ +import { Meta } from '@storybook/blocks'; + +import { AboutHeader } from '~styleguide/blocks'; + +export const parameters = { + id: 'Component Pages', + title: 'Component Pages', + subtitle: 'Guidelines for documenting computer interfaces and UI elements', + status: 'static', +}; + + + + + +## Using a single MDX file + +For components that have pages that aren’t too long, use the component-doc shortcut to auto-populate a template to describe the component’s usage, best practices, variants, examples, etc. + +## Using a directory of MDX files + +We recommend using a directory when a component is complex — in this case, “complex” can mean many things: + +- that it has multiple variants, usages, behaviors (e.g. GridForm) +- it is made of different subcomponent (e.g. Menu) +- it serves as a base component for other components (e.g. Button) + +Directories must include an About page. The contents of the About.mdx file can be generated using the toc-story shortcut that generates a template — this template will prompt you to include the general idea of what the collective files entail and a Table of Contents linking to individual pages. + +## Rendered code examples + +Examples rendered via `` 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. + +``` +// ❌ Don’t abstract the logic into an InfoTipExample +export const Default: Story = { + render: (args) => , +}; +``` + +``` +// ✅ Provide the actual code +export const Default: Story = { + render: (args) => ( + + Some text that needs info + + + ) +}; + +``` diff --git a/packages/styleguide/src/lib/Meta/Style Guide/Computer Interfaces.mdx b/packages/styleguide/src/lib/Meta/Style Guide/Computer Interfaces.mdx index ebdd46d7aa4..3b1c86c7c53 100644 --- a/packages/styleguide/src/lib/Meta/Style Guide/Computer Interfaces.mdx +++ b/packages/styleguide/src/lib/Meta/Style Guide/Computer Interfaces.mdx @@ -13,6 +13,96 @@ export const parameters = { -# Computer Interfaces +## Code in Text -Content coming soon. +- Use backticks for inline code: `onClick`, `useState`, `Box` + +- Use backticks for: + + - Component names: `Button`, `FlexBox` + + - Props: `variant`, `backgroundColor` + +- File names: `Button.tsx`, `package.json` + +- Package names: `@codecademy/gamut` + +- CSS properties: `display`, `flex-direction` + +- Values: `true`, `false`, `null` + +## Code Samples + +###Format: + +```tsx +import { Button } from '@codecademy/gamut'; +export const Example: React.FC = () => ( + +); +``` + +### 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 + +### Format: + +```bash +yarn add @codecademy/gamut-kit +``` + +### Guidelines: + +- Use bash syntax highlighting +- Don't include command prompt symbols ($, #) +- Use yarn as the default package manager +- Show one command per block unless related + +## File Paths + +- Use forward slashes: `packages/gamut/src/Button/index.tsx` +- Use relative paths when contextual +- Use absolute paths from workspace root when clearer +- Format as inline code: `/packages/styleguide/src` + +## UI Element References + +### Format: + +- Bold for UI labels: `Next`, `Back`, `Close` +- Describe location: "Click the Theme Switcher (paintbrush icon)" +- Use sentence case: "the Show code button" + +## API Reference + +### Props documentation: + +```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, then include a comment diff --git a/packages/styleguide/src/lib/Meta/Style Guide/Formatting.mdx b/packages/styleguide/src/lib/Meta/Style Guide/Formatting.mdx index 5082014f802..1b4df68d20a 100644 --- a/packages/styleguide/src/lib/Meta/Style Guide/Formatting.mdx +++ b/packages/styleguide/src/lib/Meta/Style Guide/Formatting.mdx @@ -13,6 +13,53 @@ export const parameters = { -# Formatting +## Numbers -Content coming soon. +- Spell out numbers one through nine +- Use numerals for 10 and above +- Use numerals for technical values: "`4px` padding" +- 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 + +### 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: + +\`\`\`tsx +\ -); -``` - -## Comments in Code - -- Use `//` for single-line comments -- Keep comments concise -- Explain "why" not "what" -- Use comments to highlight important patterns diff --git a/packages/styleguide/src/lib/Meta/Style Guide/Component Pages.mdx b/packages/styleguide/src/lib/Meta/Style Guide/Component Pages.mdx index eba249bb280..0eb6303aafd 100644 --- a/packages/styleguide/src/lib/Meta/Style Guide/Component Pages.mdx +++ b/packages/styleguide/src/lib/Meta/Style Guide/Component Pages.mdx @@ -54,3 +54,11 @@ export const Default: Story = { }; ``` + + +## Comments in Code + +- Use `//` for single-line comments +- Keep comments concise +- Explain "why" not "what" +- Use comments to highlight important patterns diff --git a/packages/styleguide/src/lib/Meta/Style Guide/Computer Interfaces.mdx b/packages/styleguide/src/lib/Meta/Style Guide/Computer Interfaces.mdx index 3b1c86c7c53..d726a11e480 100644 --- a/packages/styleguide/src/lib/Meta/Style Guide/Computer Interfaces.mdx +++ b/packages/styleguide/src/lib/Meta/Style Guide/Computer Interfaces.mdx @@ -33,7 +33,7 @@ export const parameters = { ## Code Samples -###Format: +### Format: ```tsx import { Button } from '@codecademy/gamut'; @@ -76,9 +76,9 @@ yarn add @codecademy/gamut-kit ### Format: -- Bold for UI labels: `Next`, `Back`, `Close` -- Describe location: "Click the Theme Switcher (paintbrush icon)" -- Use sentence case: "the Show code button" +- Bold for UI labels: **Next**, **Back**, **Close** +- Describe location: "Click the **Theme Switcher** (paintbrush icon)" +- Use sentence case: "the **Show code** button" ## API Reference @@ -105,4 +105,4 @@ export type ButtonProps = { - Document required vs. optional props - Include type information - Use discretion for whether a comment is needed or not -- if unsure, then include a comment + - if unsure, then include a comment diff --git a/packages/styleguide/src/lib/Meta/Style Guide/Formatting.mdx b/packages/styleguide/src/lib/Meta/Style Guide/Formatting.mdx index 1b4df68d20a..2dc3bc5b6e4 100644 --- a/packages/styleguide/src/lib/Meta/Style Guide/Formatting.mdx +++ b/packages/styleguide/src/lib/Meta/Style Guide/Formatting.mdx @@ -24,7 +24,7 @@ export const parameters = { - Use standard units: px, rem, em, % - Include space between number and unit in prose: "16 pixels" -- No space in code: 16px, 2rem +- No space in code: `16px`, `2rem` ## Lists @@ -42,15 +42,18 @@ export const parameters = { ## Code Blocks -- Use triple backticks with language identifier: - -\`\`\`tsx -\ -); -``` - -### 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 - -### Format: - -```bash -yarn add @codecademy/gamut-kit -``` - -### Guidelines: - -- Use bash syntax highlighting -- Don't include command prompt symbols ($, #) -- Use yarn as the default package manager -- Show one command per block unless related - -## File Paths - -- Use forward slashes: `packages/gamut/src/Button/index.tsx` -- Use relative paths when contextual -- Use absolute paths from workspace root when clearer -- Format as inline code: `/packages/styleguide/src` - -## UI Element References - -### Format: - -- Bold for UI labels: **Next**, **Back**, **Close** -- Describe location: "Click the **Theme Switcher** (paintbrush icon)" -- Use sentence case: "the **Show code** button" - -## API Reference - -### Props documentation: - -```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, then include a comment diff --git a/packages/styleguide/src/lib/Meta/Style Guide/Formatting.mdx b/packages/styleguide/src/lib/Meta/Style Guide/Formatting.mdx index 2dc3bc5b6e4..cf12f3d9140 100644 --- a/packages/styleguide/src/lib/Meta/Style Guide/Formatting.mdx +++ b/packages/styleguide/src/lib/Meta/Style Guide/Formatting.mdx @@ -56,13 +56,14 @@ Example: ## Headings Hierarchy -- H1: Page title (used once and set in the parameters object, not used explicitly) +- H1: Page title (used once and set in the `parameters` object, not used explicitly) - H2: Major sections - H3: Subsections -- Maintain logical order; don't skip levels +- Maintain logical order — don't skip levels ## Whitespace - Use blank lines to separate sections - Don't use multiple consecutive blank lines - Indent code consistently (2 spaces for TypeScript/TSX) + - If you prefer tabbing, then it should be set as 2 spaces From bc10713e4a2fdd822bf3cd9e68b50bff555d2112 Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Wed, 29 Oct 2025 11:26:21 -0400 Subject: [PATCH 09/23] renaming files --- .../lib/Meta/Style Guide/Referencing Code.mdx | 103 ++++++++ .../src/lib/Meta/Style Guide/Stories.mdx | 230 ++++++++++++++++++ 2 files changed, 333 insertions(+) create mode 100644 packages/styleguide/src/lib/Meta/Style Guide/Referencing Code.mdx create mode 100644 packages/styleguide/src/lib/Meta/Style Guide/Stories.mdx diff --git a/packages/styleguide/src/lib/Meta/Style Guide/Referencing Code.mdx b/packages/styleguide/src/lib/Meta/Style Guide/Referencing Code.mdx new file mode 100644 index 00000000000..b83b207b216 --- /dev/null +++ b/packages/styleguide/src/lib/Meta/Style Guide/Referencing Code.mdx @@ -0,0 +1,103 @@ +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', +}; + + + + + +## Code in Text + +- Use backticks for inline code: `onClick`, `useState`, `Box` +- Use backticks for: + - Component names: `Button`, `FlexBox` + - Props: `variant`, `backgroundColor` +- File names: `Button.tsx`, `package.json` +- Package names: `@codecademy/gamut` +- CSS properties: `display`, `flex-direction` +- Values: `true`, `false`, `null` + +## Code samples + +### Format: + +```tsx +import { Button } from '@codecademy/gamut'; +export const Example: React.FC = () => ( + +); +``` + +### 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 + +### Format: + +```bash +yarn add @codecademy/gamut-kit +``` + +### Guidelines: + +- Use bash syntax highlighting +- Don't include command prompt symbols ($, #) +- Use yarn as the default package manager +- Show one command per block unless related + +## File Paths + +- Use forward slashes: `packages/gamut/src/Button/index.tsx` +- Use relative paths when contextual +- Use absolute paths from workspace root when clearer +- Format as inline code: `/packages/styleguide/src` + +## UI Element References + +### Format: + +- Bold for UI labels: **Next**, **Back**, **Close** +- Describe location: "Click the **Theme Switcher** (paintbrush icon)" +- Use sentence case: "the **Show code** button" + +## API Reference + +### 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 you're unsure, then include a comment diff --git a/packages/styleguide/src/lib/Meta/Style Guide/Stories.mdx b/packages/styleguide/src/lib/Meta/Style Guide/Stories.mdx new file mode 100644 index 00000000000..70f59f911c2 --- /dev/null +++ b/packages/styleguide/src/lib/Meta/Style Guide/Stories.mdx @@ -0,0 +1,230 @@ +import { Meta } from '@storybook/blocks'; + +import { AboutHeader, LinkTo } from '~styleguide/blocks'; + +export const parameters = { + id: 'Stories', + title: 'Stories', + subtitle: 'Guidelines and tooling for writing Storybook stories and docs.', + status: 'static', +}; + + + + + +## Quick start + +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'; + +const meta: Meta = { + component: ComponentName, + args: { + variant: 'default', + }, +}; + +export default meta; +type Story = StoryObj; + +export const Default: Story = { + args: { + children: jpeg, + }, +}; + +export const Secondary: Story = { + args: { + children: 'Pro Content', + variant: 'secondary', + }, +}; +``` + +```tsx +// For ComponentName.mdx, more details in the component-doc code snippet + +import { Canvas, Controls, Meta } from '@storybook/blocks'; + +import { ComponentHeader } from '~styleguide/blocks'; + +import * as ComponentStories from './ComponentName.stories'; + +export const parameters = { + title: 'Template component', + subtitle: `Template component description...`, + design: { + type: 'figma', + url: 'https://www.figma.com/file/XXX', + }, + status: 'current', + source: { + repo: 'gamut', + // this is easy to find by right clicking on the file in VSCode and clicking "Copy Remote File Url From..." and the selecting 'main' or amending the url path below like so: https://github.com/Codecademy/gamut/blob/main/packages/${package}/src/file/location + githubLink: + 'https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/ComponentName', + }, +}; + + + + + +## Usage + +Etc... +``` + +## Story structure + +In our opinion, a good component story page consists of: + +1. **General Information:** Each component should define some key information on the `` 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. +3. `source`: The source package of the component (e.g. `gamut` | `gamut-styles`) and a link to the corresponding code. +4. `status`: The health of the components API (e.g. `current` | `updating` | `deprecated` | `static`) +5. `design`: A link to the Figma file that is associated with the component. + +```tsx +import { Meta } from '@storybook/blocks'; + +import { ComponentHeader } from '~styleguide/blocks'; + +import * as AnchorStories from './Anchor.stories'; + +export const parameters = { + subtitle: `A clickable text element that navigates to another page, resource, or location on the same page.`, + design: { + type: 'figma', + url: 'https://www.figma.com/file/ReGfRNillGABAj5SlITalN/%F0%9F%93%90-Gamut?node-id=993-0', + }, + status: 'current', + source: { + repo: 'gamut', + githubLink: + 'https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/Anchor', + }, +}; + + + + + +``` + +### 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"`. + +Try to include the major behaviors for the component that most readers would need to understand its uses. + +```tsx +## Playground + +//If your flagship story is named Default, you don't need to specify it for the Playground + + + +``` + +### 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. + +```tsx +## Variant Anchors + +A short description should go here, as well as any variant specific usage guidelines. + + + +``` + +### Rendered code examples + +Examples rendered via `` 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. + +``` +// ❌ Don’t abstract the logic into an InfoTipExample +export const Default: Story = { + render: (args) => , +}; +``` + +``` +// ✅ Provide the actual code +export const Default: Story = { + render: (args) => ( + + Some text that needs info + + + ) +}; + +``` + +### Comments in code + +- Use `//` for single-line comments +- Keep comments concise +- Explain "why" not "what" +- Use comments to highlight important patterns + +### About pages + +An `About.mdx` file should be be included when multiple stories are presented in a folder. E.g. the Animation folder which contains an `About.mdx` file with a table of contents that link to specific components -- in this case, the ExpandInCollapseOut component and the Rotation component. + +Inside the `About.mdx` file, use the `toc-story` snippet to generate a template. Import the `parameters` object from the respective component's `.mdx` file and pass it to the `` 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.', +}; + +... + + +``` + +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. From 94530ee60f62adbdc5b854e9a48a5075542389c0 Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Tue, 11 Nov 2025 15:33:15 -0500 Subject: [PATCH 10/23] applied some feedback --- packages/styleguide/.storybook/preview.ts | 2 +- .../src/lib/Meta/Style Guide/About.mdx | 6 ++-- .../src/lib/Meta/Style Guide/Formatting.mdx | 10 +++--- .../Meta/Style Guide/General Principles.mdx | 6 ++-- .../Meta/Style Guide/Language and Grammer.mdx | 2 +- .../src/lib/Meta/Style Guide/Linking.mdx | 31 +++++++++++++------ .../lib/Meta/Style Guide/Referencing Code.mdx | 2 +- .../src/lib/Meta/Style Guide/Stories.mdx | 2 +- 8 files changed, 38 insertions(+), 23 deletions(-) diff --git a/packages/styleguide/.storybook/preview.ts b/packages/styleguide/.storybook/preview.ts index 0e0c6cda038..cb2b4da7c64 100644 --- a/packages/styleguide/.storybook/preview.ts +++ b/packages/styleguide/.storybook/preview.ts @@ -29,7 +29,7 @@ const preview: Preview = { 'Contributing', 'FAQs', 'Stories', - 'Style Guide', + 'Gamut Writing Guide', ], 'Foundations', 'Layouts', diff --git a/packages/styleguide/src/lib/Meta/Style Guide/About.mdx b/packages/styleguide/src/lib/Meta/Style Guide/About.mdx index addb56905fa..8cc8de81f78 100644 --- a/packages/styleguide/src/lib/Meta/Style Guide/About.mdx +++ b/packages/styleguide/src/lib/Meta/Style Guide/About.mdx @@ -14,13 +14,13 @@ import { parameters as referencingCodeParameters } from './Referencing Code.mdx' import { parameters as storiesParameters } from './Stories.mdx'; export const parameters = { - id: 'Meta/Style Guide', - title: 'Style Guide', + id: 'Meta/Gamut Writing Guide', + title: 'Gamut Writing Guide', subtitle: 'Guidelines and standards for creating consistent, clear, and effective documentation.', }; - + diff --git a/packages/styleguide/src/lib/Meta/Style Guide/Formatting.mdx b/packages/styleguide/src/lib/Meta/Style Guide/Formatting.mdx index cf12f3d9140..d29b2538827 100644 --- a/packages/styleguide/src/lib/Meta/Style Guide/Formatting.mdx +++ b/packages/styleguide/src/lib/Meta/Style Guide/Formatting.mdx @@ -9,15 +9,15 @@ export const parameters = { status: 'static', }; - + +Consistent formatting makes documentation easier to scan, understand, and implement. These standards ensure our content is predictable and professional across all Gamut components. + ## Numbers -- Spell out numbers one through nine -- Use numerals for 10 and above -- Use numerals for technical values: "`4px` padding" +- Use numerals for all numbers - Use commas for thousands: 1,000 ## Units of Measurement @@ -28,6 +28,8 @@ export const parameters = { ## 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 diff --git a/packages/styleguide/src/lib/Meta/Style Guide/General Principles.mdx b/packages/styleguide/src/lib/Meta/Style Guide/General Principles.mdx index 76c9dafbbb0..8c0465bab1b 100644 --- a/packages/styleguide/src/lib/Meta/Style Guide/General Principles.mdx +++ b/packages/styleguide/src/lib/Meta/Style Guide/General Principles.mdx @@ -9,11 +9,13 @@ export const parameters = { status: 'static', }; - + -## Voice and Tone +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 you're 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 - Direct and action-oriented: Use "you" to address readers diff --git a/packages/styleguide/src/lib/Meta/Style Guide/Language and Grammer.mdx b/packages/styleguide/src/lib/Meta/Style Guide/Language and Grammer.mdx index fa84e344873..a34eb3467b2 100644 --- a/packages/styleguide/src/lib/Meta/Style Guide/Language and Grammer.mdx +++ b/packages/styleguide/src/lib/Meta/Style Guide/Language and Grammer.mdx @@ -9,7 +9,7 @@ export const parameters = { status: 'static', }; - + diff --git a/packages/styleguide/src/lib/Meta/Style Guide/Linking.mdx b/packages/styleguide/src/lib/Meta/Style Guide/Linking.mdx index e993d2f9e60..2b3997da6d6 100644 --- a/packages/styleguide/src/lib/Meta/Style Guide/Linking.mdx +++ b/packages/styleguide/src/lib/Meta/Style Guide/Linking.mdx @@ -1,6 +1,6 @@ import { Meta } from '@storybook/blocks'; -import { AboutHeader } from '~styleguide/blocks'; +import { AboutHeader, Callout } from '~styleguide/blocks'; export const parameters = { id: 'Linking', @@ -9,10 +9,12 @@ export const parameters = { status: 'static', }; - + +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. @@ -25,26 +27,35 @@ import { LinkTo } from '~styleguide/blocks'; ### Guidelines: -- Use descriptive link text: "See the Stories page" not "Click here" -- Link text should make sense out of context +- 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 -- Check to see that the link works accordingly +- Verify that the link works correctly ## External Links +### Markdown Links: + +You can 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: +If you need more control over the link, you can use the Anchor component,the example below will open in the current tab: + ```tsx - - Gamut Repository - +Gamut Repository ``` + + ### URL Guidelines: - Use full URLs for external resources -- Open external links in new tabs: target="\_" -- Prefer HTTPS over HTTP - Link to official documentation when referencing tools ## MDX file parameters diff --git a/packages/styleguide/src/lib/Meta/Style Guide/Referencing Code.mdx b/packages/styleguide/src/lib/Meta/Style Guide/Referencing Code.mdx index b83b207b216..e21cf253768 100644 --- a/packages/styleguide/src/lib/Meta/Style Guide/Referencing Code.mdx +++ b/packages/styleguide/src/lib/Meta/Style Guide/Referencing Code.mdx @@ -9,7 +9,7 @@ export const parameters = { status: 'static', }; - + diff --git a/packages/styleguide/src/lib/Meta/Style Guide/Stories.mdx b/packages/styleguide/src/lib/Meta/Style Guide/Stories.mdx index 70f59f911c2..16c21e79f3b 100644 --- a/packages/styleguide/src/lib/Meta/Style Guide/Stories.mdx +++ b/packages/styleguide/src/lib/Meta/Style Guide/Stories.mdx @@ -9,7 +9,7 @@ export const parameters = { status: 'static', }; - + From 459414b21175c1c7b9e6932a0b810b4443172a7f Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Wed, 12 Nov 2025 09:07:55 -0500 Subject: [PATCH 11/23] more feedback --- .../Meta/Style Guide/General Principles.mdx | 8 ++--- .../Meta/Style Guide/Language and Grammer.mdx | 7 +++-- .../src/lib/Meta/Style Guide/Linking.mdx | 29 +++---------------- .../src/lib/Meta/Style Guide/Stories.mdx | 2 ++ 4 files changed, 13 insertions(+), 33 deletions(-) diff --git a/packages/styleguide/src/lib/Meta/Style Guide/General Principles.mdx b/packages/styleguide/src/lib/Meta/Style Guide/General Principles.mdx index 8c0465bab1b..f948a764cc4 100644 --- a/packages/styleguide/src/lib/Meta/Style Guide/General Principles.mdx +++ b/packages/styleguide/src/lib/Meta/Style Guide/General Principles.mdx @@ -25,8 +25,7 @@ Good documentation does more than describe — it helps people succeed. These pr ## Inclusivity - Use inclusive language that makes all contributors feel welcome -- Avoid jargon unless necessary — define terms when first introduced -- Write for accessibility — ensure screen readers can parse content +- Define terms when first introduced - Consider contributors of varying experience levels and roles (designers and developers) ## Transparency @@ -37,11 +36,10 @@ Good documentation does more than describe — it helps people succeed. These pr - `deprecated`: Do not use for new work - `static`: Reference material, no active development - Link to source code and design files (Figma, GitHub) -- Direct contributors to help channels (#gamut-team, Office Hours) ## Consistency -- Use the same terminology throughout documentation -- Match language between headings, body copy, and code examples +- 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 diff --git a/packages/styleguide/src/lib/Meta/Style Guide/Language and Grammer.mdx b/packages/styleguide/src/lib/Meta/Style Guide/Language and Grammer.mdx index a34eb3467b2..9df70ed7fa7 100644 --- a/packages/styleguide/src/lib/Meta/Style Guide/Language and Grammer.mdx +++ b/packages/styleguide/src/lib/Meta/Style Guide/Language and Grammer.mdx @@ -15,13 +15,15 @@ export const parameters = { ## Voice -- Use active voice: "The component renders..." not "The component is rendered by..." +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 second person ("you") when addressing the reader - Use imperative mood for instructions: "Add the component" not "You should add the component" ## Tense -- Use present tense for current functionality: "The Button accepts a variant prop" +Use present tense for current functionality — it's the simplest and most direct form of a verb, making writing more clearer. The more you use conditional or future tense, the harder your audience has to work to understand your 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 @@ -35,7 +37,6 @@ export const parameters = { ## Articles - Use articles (a, an, the) for clarity - - "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…” diff --git a/packages/styleguide/src/lib/Meta/Style Guide/Linking.mdx b/packages/styleguide/src/lib/Meta/Style Guide/Linking.mdx index 2b3997da6d6..289b4f2c5eb 100644 --- a/packages/styleguide/src/lib/Meta/Style Guide/Linking.mdx +++ b/packages/styleguide/src/lib/Meta/Style Guide/Linking.mdx @@ -34,6 +34,8 @@ import { LinkTo } from '~styleguide/blocks'; ## External Links +When linking to external resources like official documentation or tools, use the following guidelines. + ### Markdown Links: You can use Markdown for external links, the examples below will open in a new tab: @@ -45,37 +47,14 @@ You can use Markdown for external links, the examples below will open in a new t ### Anchor Component: -If you need more control over the link, you can use the Anchor component,the example below will open in the current tab: +If you need more control over the link, you can use the `Anchor` component,the example below will open in the current tab: ```tsx Gamut Repository ``` - - -### URL Guidelines: - -- Use full URLs for external resources -- Link to official documentation when referencing tools + -## MDX file parameters - -For a component's `.mdx` file, add the following to the `parameters` object. Use the `main` branch for the `githubLink`. - -```tsx -source: { - repo: 'gamut', - githubLink: 'https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/Button' -} -``` - -```tsx -design: { - type: 'figma', - url: 'https://www.figma.com/file/ReGfRNillGABAj5SlITalN/%F0%9F%93%90-Gamut?node-id=993-0' -} - -``` ## Link Text Guidelines diff --git a/packages/styleguide/src/lib/Meta/Style Guide/Stories.mdx b/packages/styleguide/src/lib/Meta/Style Guide/Stories.mdx index 16c21e79f3b..29e2eb15acf 100644 --- a/packages/styleguide/src/lib/Meta/Style Guide/Stories.mdx +++ b/packages/styleguide/src/lib/Meta/Style Guide/Stories.mdx @@ -13,6 +13,8 @@ export const 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 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. From fe22d3dce776fc99270c50521c8677a245b3dc82 Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Wed, 12 Nov 2025 17:28:55 -0500 Subject: [PATCH 12/23] more feedback --- packages/styleguide/src/lib/Meta/About.mdx | 4 +- .../About.mdx | 2 +- .../Formatting.mdx | 0 .../General Principles.mdx | 2 +- .../Language and Grammer.mdx | 16 +-- .../Linking.mdx | 12 +- .../Gamut Writing Guide/Referencing Code.mdx | 117 ++++++++++++++++++ .../Stories.mdx | 0 .../lib/Meta/Style Guide/Referencing Code.mdx | 103 --------------- 9 files changed, 128 insertions(+), 128 deletions(-) rename packages/styleguide/src/lib/Meta/{Style Guide => Gamut Writing Guide}/About.mdx (100%) rename packages/styleguide/src/lib/Meta/{Style Guide => Gamut Writing Guide}/Formatting.mdx (100%) rename packages/styleguide/src/lib/Meta/{Style Guide => Gamut Writing Guide}/General Principles.mdx (97%) rename packages/styleguide/src/lib/Meta/{Style Guide => Gamut Writing Guide}/Language and Grammer.mdx (71%) rename packages/styleguide/src/lib/Meta/{Style Guide => Gamut Writing Guide}/Linking.mdx (98%) create mode 100644 packages/styleguide/src/lib/Meta/Gamut Writing Guide/Referencing Code.mdx rename packages/styleguide/src/lib/Meta/{Style Guide => Gamut Writing Guide}/Stories.mdx (100%) delete mode 100644 packages/styleguide/src/lib/Meta/Style Guide/Referencing Code.mdx diff --git a/packages/styleguide/src/lib/Meta/About.mdx b/packages/styleguide/src/lib/Meta/About.mdx index 7ee044b9a3c..a067aeb2563 100644 --- a/packages/styleguide/src/lib/Meta/About.mdx +++ b/packages/styleguide/src/lib/Meta/About.mdx @@ -11,8 +11,8 @@ 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 faqsParameters } from './FAQs.mdx'; +import { parameters as gamutWritingGuideParameters } from './Gamut Writing Guide/About.mdx'; import { parameters as installationParameters } from './Installation.mdx'; -import { parameters as styleGuideParameters } from './Style Guide/About.mdx'; import { parameters as usageGuideParameters } from './Usage Guide.mdx'; export const parameters = { @@ -32,7 +32,7 @@ export const parameters = { contributingParameters, deepControlsParameters, faqsParameters, - styleGuideParameters, + gamutWritingGuideParameters, brandParameters, installationParameters, usageGuideParameters, diff --git a/packages/styleguide/src/lib/Meta/Style Guide/About.mdx b/packages/styleguide/src/lib/Meta/Gamut Writing Guide/About.mdx similarity index 100% rename from packages/styleguide/src/lib/Meta/Style Guide/About.mdx rename to packages/styleguide/src/lib/Meta/Gamut Writing Guide/About.mdx index 8cc8de81f78..0de79da9e8f 100644 --- a/packages/styleguide/src/lib/Meta/Style Guide/About.mdx +++ b/packages/styleguide/src/lib/Meta/Gamut Writing Guide/About.mdx @@ -26,9 +26,9 @@ export const parameters = { - - -## Link Text Guidelines - -- 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" diff --git a/packages/styleguide/src/lib/Meta/Gamut Writing Guide/Referencing Code.mdx b/packages/styleguide/src/lib/Meta/Gamut Writing Guide/Referencing Code.mdx new file mode 100644 index 00000000000..821f218d9c4 --- /dev/null +++ b/packages/styleguide/src/lib/Meta/Gamut Writing Guide/Referencing Code.mdx @@ -0,0 +1,117 @@ +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', +}; + + + + + +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` + - Unless you're linking to them, in which case use permalinks +- 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 = () => ( + +); +``` + +### 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 bash syntax highlighting +- 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" + +## 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 diff --git a/packages/styleguide/src/lib/Meta/Style Guide/Stories.mdx b/packages/styleguide/src/lib/Meta/Gamut Writing Guide/Stories.mdx similarity index 100% rename from packages/styleguide/src/lib/Meta/Style Guide/Stories.mdx rename to packages/styleguide/src/lib/Meta/Gamut Writing Guide/Stories.mdx diff --git a/packages/styleguide/src/lib/Meta/Style Guide/Referencing Code.mdx b/packages/styleguide/src/lib/Meta/Style Guide/Referencing Code.mdx deleted file mode 100644 index e21cf253768..00000000000 --- a/packages/styleguide/src/lib/Meta/Style Guide/Referencing Code.mdx +++ /dev/null @@ -1,103 +0,0 @@ -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', -}; - - - - - -## Code in Text - -- Use backticks for inline code: `onClick`, `useState`, `Box` -- Use backticks for: - - Component names: `Button`, `FlexBox` - - Props: `variant`, `backgroundColor` -- File names: `Button.tsx`, `package.json` -- Package names: `@codecademy/gamut` -- CSS properties: `display`, `flex-direction` -- Values: `true`, `false`, `null` - -## Code samples - -### Format: - -```tsx -import { Button } from '@codecademy/gamut'; -export const Example: React.FC = () => ( - -); -``` - -### 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 - -### Format: - -```bash -yarn add @codecademy/gamut-kit -``` - -### Guidelines: - -- Use bash syntax highlighting -- Don't include command prompt symbols ($, #) -- Use yarn as the default package manager -- Show one command per block unless related - -## File Paths - -- Use forward slashes: `packages/gamut/src/Button/index.tsx` -- Use relative paths when contextual -- Use absolute paths from workspace root when clearer -- Format as inline code: `/packages/styleguide/src` - -## UI Element References - -### Format: - -- Bold for UI labels: **Next**, **Back**, **Close** -- Describe location: "Click the **Theme Switcher** (paintbrush icon)" -- Use sentence case: "the **Show code** button" - -## API Reference - -### 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 you're unsure, then include a comment From 2d59049712464aea43b6da4e20823c05e2917d49 Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Thu, 13 Nov 2025 12:13:00 -0500 Subject: [PATCH 13/23] more feedback and re-org some pages --- packages/styleguide/.storybook/preview.ts | 7 +- packages/styleguide/src/lib/Meta/About.mdx | 8 +- ...{Best Practices.mdx => Best practices.mdx} | 0 ...ls Add-On.mdx => Deep Controls add-on.mdx} | 0 .../lib/Meta/Gamut Writing Guide/About.mdx | 36 --- .../lib/Meta/Gamut Writing Guide/Stories.mdx | 232 ------------------ .../lib/Meta/Gamut writing guide/About.mdx | 43 ++++ .../Documentation in code.mdx | 133 ++++++++++ .../Formatting.mdx | 2 +- .../General principles.mdx} | 6 +- .../Language and grammar.mdx} | 6 +- .../Linking.mdx | 2 +- .../Referencing code.mdx} | 37 +-- .../Stories/About pages.mdx | 56 +++++ .../Gamut writing guide/Stories/About.mdx | 58 +++++ .../Stories/Component MDX.mdx | 129 ++++++++++ .../Stories/Component story tsx.mdx | 77 ++++++ .../Meta/{Usage Guide.mdx => Usage guide.mdx} | 6 +- 18 files changed, 521 insertions(+), 317 deletions(-) rename packages/styleguide/src/lib/Meta/{Best Practices.mdx => Best practices.mdx} (100%) rename packages/styleguide/src/lib/Meta/{Deep Controls Add-On.mdx => Deep Controls add-on.mdx} (100%) delete mode 100644 packages/styleguide/src/lib/Meta/Gamut Writing Guide/About.mdx delete mode 100644 packages/styleguide/src/lib/Meta/Gamut Writing Guide/Stories.mdx create mode 100644 packages/styleguide/src/lib/Meta/Gamut writing guide/About.mdx create mode 100644 packages/styleguide/src/lib/Meta/Gamut writing guide/Documentation in code.mdx rename packages/styleguide/src/lib/Meta/{Gamut Writing Guide => Gamut writing guide}/Formatting.mdx (97%) rename packages/styleguide/src/lib/Meta/{Gamut Writing Guide/General Principles.mdx => Gamut writing guide/General principles.mdx} (94%) rename packages/styleguide/src/lib/Meta/{Gamut Writing Guide/Language and Grammer.mdx => Gamut writing guide/Language and grammar.mdx} (93%) rename packages/styleguide/src/lib/Meta/{Gamut Writing Guide => Gamut writing guide}/Linking.mdx (97%) rename packages/styleguide/src/lib/Meta/{Gamut Writing Guide/Referencing Code.mdx => Gamut writing guide/Referencing code.mdx} (73%) create mode 100644 packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/About pages.mdx create mode 100644 packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/About.mdx create mode 100644 packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component MDX.mdx create mode 100644 packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component story tsx.mdx rename packages/styleguide/src/lib/Meta/{Usage Guide.mdx => Usage guide.mdx} (98%) diff --git a/packages/styleguide/.storybook/preview.ts b/packages/styleguide/.storybook/preview.ts index cb2b4da7c64..99a4d6224cd 100644 --- a/packages/styleguide/.storybook/preview.ts +++ b/packages/styleguide/.storybook/preview.ts @@ -25,11 +25,16 @@ const preview: Preview = { 'Meta', [ 'About', + 'Brand', 'Best Practices', 'Contributing', + 'Deep Controls add-on', 'FAQs', + 'Installation', 'Stories', - 'Gamut Writing Guide', + 'Usage guide', + 'Gamut writing guide', + ['About', 'General principles', 'Documentation in code', 'Formatting', 'Language and grammar', 'Linking', 'Referencing code', 'Stories'], ], 'Foundations', 'Layouts', diff --git a/packages/styleguide/src/lib/Meta/About.mdx b/packages/styleguide/src/lib/Meta/About.mdx index a067aeb2563..695709eb9fa 100644 --- a/packages/styleguide/src/lib/Meta/About.mdx +++ b/packages/styleguide/src/lib/Meta/About.mdx @@ -6,14 +6,14 @@ 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 faqsParameters } from './FAQs.mdx'; -import { parameters as gamutWritingGuideParameters } from './Gamut Writing Guide/About.mdx'; +import { parameters as gamutWritingGuideParameters } from './Gamut writing guide/About.mdx'; import { parameters as installationParameters } from './Installation.mdx'; -import { parameters as usageGuideParameters } from './Usage Guide.mdx'; +import { parameters as usageGuideParameters } from './Usage guide.mdx'; export const parameters = { id: 'Meta', diff --git a/packages/styleguide/src/lib/Meta/Best Practices.mdx b/packages/styleguide/src/lib/Meta/Best practices.mdx similarity index 100% rename from packages/styleguide/src/lib/Meta/Best Practices.mdx rename to packages/styleguide/src/lib/Meta/Best practices.mdx diff --git a/packages/styleguide/src/lib/Meta/Deep Controls Add-On.mdx b/packages/styleguide/src/lib/Meta/Deep Controls add-on.mdx similarity index 100% rename from packages/styleguide/src/lib/Meta/Deep Controls Add-On.mdx rename to packages/styleguide/src/lib/Meta/Deep Controls add-on.mdx diff --git a/packages/styleguide/src/lib/Meta/Gamut Writing Guide/About.mdx b/packages/styleguide/src/lib/Meta/Gamut Writing Guide/About.mdx deleted file mode 100644 index 0de79da9e8f..00000000000 --- a/packages/styleguide/src/lib/Meta/Gamut Writing Guide/About.mdx +++ /dev/null @@ -1,36 +0,0 @@ -import { Meta } from '@storybook/blocks'; - -import { - AboutHeader, - addParentPath, - TableOfContents, -} from '~styleguide/blocks'; - -import { parameters as formattingParameters } from './Formatting.mdx'; -import { parameters as generalPrinciplesParameters } from './General Principles.mdx'; -import { parameters as languageAndGrammerParameters } from './Language and Grammer.mdx'; -import { parameters as linkingParameters } from './Linking.mdx'; -import { parameters as referencingCodeParameters } from './Referencing Code.mdx'; -import { parameters as storiesParameters } from './Stories.mdx'; - -export const parameters = { - id: 'Meta/Gamut Writing Guide', - title: 'Gamut Writing Guide', - subtitle: - 'Guidelines and standards for creating consistent, clear, and effective documentation.', -}; - - - - - - diff --git a/packages/styleguide/src/lib/Meta/Gamut Writing Guide/Stories.mdx b/packages/styleguide/src/lib/Meta/Gamut Writing Guide/Stories.mdx deleted file mode 100644 index 29e2eb15acf..00000000000 --- a/packages/styleguide/src/lib/Meta/Gamut Writing Guide/Stories.mdx +++ /dev/null @@ -1,232 +0,0 @@ -import { Meta } from '@storybook/blocks'; - -import { AboutHeader, LinkTo } from '~styleguide/blocks'; - -export const parameters = { - id: 'Stories', - title: 'Stories', - subtitle: 'Guidelines and tooling for writing Storybook stories and docs.', - status: 'static', -}; - - - - - -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 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'; - -const meta: Meta = { - component: ComponentName, - args: { - variant: 'default', - }, -}; - -export default meta; -type Story = StoryObj; - -export const Default: Story = { - args: { - children: jpeg, - }, -}; - -export const Secondary: Story = { - args: { - children: 'Pro Content', - variant: 'secondary', - }, -}; -``` - -```tsx -// For ComponentName.mdx, more details in the component-doc code snippet - -import { Canvas, Controls, Meta } from '@storybook/blocks'; - -import { ComponentHeader } from '~styleguide/blocks'; - -import * as ComponentStories from './ComponentName.stories'; - -export const parameters = { - title: 'Template component', - subtitle: `Template component description...`, - design: { - type: 'figma', - url: 'https://www.figma.com/file/XXX', - }, - status: 'current', - source: { - repo: 'gamut', - // this is easy to find by right clicking on the file in VSCode and clicking "Copy Remote File Url From..." and the selecting 'main' or amending the url path below like so: https://github.com/Codecademy/gamut/blob/main/packages/${package}/src/file/location - githubLink: - 'https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/ComponentName', - }, -}; - - - - - -## Usage - -Etc... -``` - -## Story structure - -In our opinion, a good component story page consists of: - -1. **General Information:** Each component should define some key information on the `` 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. -3. `source`: The source package of the component (e.g. `gamut` | `gamut-styles`) and a link to the corresponding code. -4. `status`: The health of the components API (e.g. `current` | `updating` | `deprecated` | `static`) -5. `design`: A link to the Figma file that is associated with the component. - -```tsx -import { Meta } from '@storybook/blocks'; - -import { ComponentHeader } from '~styleguide/blocks'; - -import * as AnchorStories from './Anchor.stories'; - -export const parameters = { - subtitle: `A clickable text element that navigates to another page, resource, or location on the same page.`, - design: { - type: 'figma', - url: 'https://www.figma.com/file/ReGfRNillGABAj5SlITalN/%F0%9F%93%90-Gamut?node-id=993-0', - }, - status: 'current', - source: { - repo: 'gamut', - githubLink: - 'https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/Anchor', - }, -}; - - - - - -``` - -### 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"`. - -Try to include the major behaviors for the component that most readers would need to understand its uses. - -```tsx -## Playground - -//If your flagship story is named Default, you don't need to specify it for the Playground - - - -``` - -### 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. - -```tsx -## Variant Anchors - -A short description should go here, as well as any variant specific usage guidelines. - - - -``` - -### Rendered code examples - -Examples rendered via `` 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. - -``` -// ❌ Don’t abstract the logic into an InfoTipExample -export const Default: Story = { - render: (args) => , -}; -``` - -``` -// ✅ Provide the actual code -export const Default: Story = { - render: (args) => ( - - Some text that needs info - - - ) -}; - -``` - -### Comments in code - -- Use `//` for single-line comments -- Keep comments concise -- Explain "why" not "what" -- Use comments to highlight important patterns - -### About pages - -An `About.mdx` file should be be included when multiple stories are presented in a folder. E.g. the Animation folder which contains an `About.mdx` file with a table of contents that link to specific components -- in this case, the ExpandInCollapseOut component and the Rotation component. - -Inside the `About.mdx` file, use the `toc-story` snippet to generate a template. Import the `parameters` object from the respective component's `.mdx` file and pass it to the `` 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.', -}; - -... - - -``` - -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. diff --git a/packages/styleguide/src/lib/Meta/Gamut writing guide/About.mdx b/packages/styleguide/src/lib/Meta/Gamut writing guide/About.mdx new file mode 100644 index 00000000000..4d138b12b2f --- /dev/null +++ b/packages/styleguide/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.', +}; + + + + + +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. + +If you're new here, start with General principles 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. + + diff --git a/packages/styleguide/src/lib/Meta/Gamut writing guide/Documentation in code.mdx b/packages/styleguide/src/lib/Meta/Gamut writing guide/Documentation in code.mdx new file mode 100644 index 00000000000..17a0f75b176 --- /dev/null +++ b/packages/styleguide/src/lib/Meta/Gamut writing guide/Documentation in code.mdx @@ -0,0 +1,133 @@ +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', +}; + + + + + +Good documentation starts in the code itself. By documenting components, props, and functions directly in your source files, you 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 files 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 diff --git a/packages/styleguide/src/lib/Meta/Gamut Writing Guide/Formatting.mdx b/packages/styleguide/src/lib/Meta/Gamut writing guide/Formatting.mdx similarity index 97% rename from packages/styleguide/src/lib/Meta/Gamut Writing Guide/Formatting.mdx rename to packages/styleguide/src/lib/Meta/Gamut writing guide/Formatting.mdx index d29b2538827..f67b891d2cc 100644 --- a/packages/styleguide/src/lib/Meta/Gamut Writing Guide/Formatting.mdx +++ b/packages/styleguide/src/lib/Meta/Gamut writing guide/Formatting.mdx @@ -9,7 +9,7 @@ export const parameters = { status: 'static', }; - + diff --git a/packages/styleguide/src/lib/Meta/Gamut Writing Guide/General Principles.mdx b/packages/styleguide/src/lib/Meta/Gamut writing guide/General principles.mdx similarity index 94% rename from packages/styleguide/src/lib/Meta/Gamut Writing Guide/General Principles.mdx rename to packages/styleguide/src/lib/Meta/Gamut writing guide/General principles.mdx index ccd792c8f31..8773d241f67 100644 --- a/packages/styleguide/src/lib/Meta/Gamut Writing Guide/General Principles.mdx +++ b/packages/styleguide/src/lib/Meta/Gamut writing guide/General principles.mdx @@ -3,13 +3,13 @@ import { Meta } from '@storybook/blocks'; import { AboutHeader } from '~styleguide/blocks'; export const parameters = { - id: 'General Principles', - title: 'General Principles', + id: 'General principles', + title: 'General principles', subtitle: 'Core principles for writing effective documentation', status: 'static', }; - + diff --git a/packages/styleguide/src/lib/Meta/Gamut Writing Guide/Language and Grammer.mdx b/packages/styleguide/src/lib/Meta/Gamut writing guide/Language and grammar.mdx similarity index 93% rename from packages/styleguide/src/lib/Meta/Gamut Writing Guide/Language and Grammer.mdx rename to packages/styleguide/src/lib/Meta/Gamut writing guide/Language and grammar.mdx index 651cac304e8..f49b068bf1a 100644 --- a/packages/styleguide/src/lib/Meta/Gamut Writing Guide/Language and Grammer.mdx +++ b/packages/styleguide/src/lib/Meta/Gamut writing guide/Language and grammar.mdx @@ -3,13 +3,13 @@ import { Meta } from '@storybook/blocks'; import { AboutHeader } from '~styleguide/blocks'; export const parameters = { - id: 'Language and Grammer', - title: 'Language and Grammer', + id: 'Language and grammar', + title: 'Language and grammar', subtitle: 'Guidelines for language usage and grammar in documentation', status: 'static', }; - + diff --git a/packages/styleguide/src/lib/Meta/Gamut Writing Guide/Linking.mdx b/packages/styleguide/src/lib/Meta/Gamut writing guide/Linking.mdx similarity index 97% rename from packages/styleguide/src/lib/Meta/Gamut Writing Guide/Linking.mdx rename to packages/styleguide/src/lib/Meta/Gamut writing guide/Linking.mdx index e68d7003241..b822165e659 100644 --- a/packages/styleguide/src/lib/Meta/Gamut Writing Guide/Linking.mdx +++ b/packages/styleguide/src/lib/Meta/Gamut writing guide/Linking.mdx @@ -9,7 +9,7 @@ export const parameters = { status: 'static', }; - + diff --git a/packages/styleguide/src/lib/Meta/Gamut Writing Guide/Referencing Code.mdx b/packages/styleguide/src/lib/Meta/Gamut writing guide/Referencing code.mdx similarity index 73% rename from packages/styleguide/src/lib/Meta/Gamut Writing Guide/Referencing Code.mdx rename to packages/styleguide/src/lib/Meta/Gamut writing guide/Referencing code.mdx index 821f218d9c4..30bdf11ae06 100644 --- a/packages/styleguide/src/lib/Meta/Gamut Writing Guide/Referencing Code.mdx +++ b/packages/styleguide/src/lib/Meta/Gamut writing guide/Referencing code.mdx @@ -3,13 +3,13 @@ import { Meta } from '@storybook/blocks'; import { AboutHeader } from '~styleguide/blocks'; export const parameters = { - id: 'Refencing Code', - title: 'Refencing Code', + id: 'Refencing code', + title: 'Refencing code', subtitle: 'Guidelines for referencing code and UI Elements', status: 'static', }; - + @@ -70,6 +70,7 @@ yarn add @codecademy/gamut-kit - 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. @@ -85,33 +86,3 @@ When instructing users to interact with the interface, clearly identify what the - ✅ "the following/adjacent form" or "in the previous section" - ❌ "the form on the right" or "in the section above" -## 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 diff --git a/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/About pages.mdx b/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/About pages.mdx new file mode 100644 index 00000000000..cc9ce894e2f --- /dev/null +++ b/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/About pages.mdx @@ -0,0 +1,56 @@ +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', +}; + + + + + +An `About.mdx` file serves as a landing page for folders containing multiple related components or stories. It provides a brief overview and organized table of contents to help users understand what the folder contains and navigate to specific components. Keep these pages concise with clear descriptions—they're 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 Animation folder contains an `About.mdx` file with a table of contents that links to specific components — in this case, the ExpandInCollapseOut component and the Rotation 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 `.mdx` file and pass it to the `` 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.', +}; + +... + + +``` + +## 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 + +## Best practices + +- **Write a clear overview**: Explain what the folder contains and how components relate to each other +- **Order logically**: Arrange components in the table of contents by importance or usage frequency +- **Keep it concise**: About pages should be brief entry points, not detailed documentation +- **Use descriptive subtitles**: Help users understand what they'll find before clicking through diff --git a/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/About.mdx b/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/About.mdx new file mode 100644 index 00000000000..458a2a983ed --- /dev/null +++ b/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/About.mdx @@ -0,0 +1,58 @@ +import { Meta } from '@storybook/blocks'; + +import { + AboutHeader, + addParentPath, + TableOfContents, +} from '~styleguide/blocks'; + +import { parameters as aboutPagesParameters } from './About pages.mdx'; +import { parameters as componentMdxParameters } from './Component MDX.mdx'; +import { parameters as componentStoryTsxParameters } from './Component story tsx.mdx'; + +export const parameters = { + id: 'Meta/Gamut writing guide/Stories', + title: 'Stories', + subtitle: 'Guidelines and tooling for writing Storybook stories and docs.', + status: 'static', +}; + + + + + +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 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. +- 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 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. + + +## Learn more + +Explore the pages below for detailed guidelines on each part of the story structure: + + diff --git a/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component MDX.mdx b/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component MDX.mdx new file mode 100644 index 00000000000..5dc6a2c43ac --- /dev/null +++ b/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component MDX.mdx @@ -0,0 +1,129 @@ +import { Meta } from '@storybook/blocks'; + +import { AboutHeader } from '~styleguide/blocks'; + +export const parameters = { + id: 'Component MDX', + title: 'Component MDX', + subtitle: 'How to write .mdx documentation files for Gamut components', + status: 'static', +}; + + + + + +The `.mdx` file provides the documentation structure and context for your component. It combines the interactive stories from the `.stories.tsx` file with written documentation, usage guidelines, and metadata. + +## Story structure + +In our opinion, a good component story page consists of: + +1. **General Information:** Each component should define some key information on the `` 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. + +## Basic structure + +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 + +import { Canvas, Controls, Meta } from '@storybook/blocks'; + +import { ComponentHeader } from '~styleguide/blocks'; + +import * as ComponentStories from './ComponentName.stories'; + +export const parameters = { + title: 'Template component', + subtitle: `Template component description...`, + design: { + type: 'figma', + url: 'https://www.figma.com/file/XXX', + }, + status: 'current', + source: { + repo: 'gamut', + // this is easy to find by right clicking on the file in VSCode and clicking "Copy Remote File Url From..." and the selecting 'main' or amending the url path below like so: https://github.com/Codecademy/gamut/blob/main/packages/${package}/src/file/location + githubLink: + 'https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/ComponentName', + }, +}; + + + + + +## Usage + +Etc... +``` + +## 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. +3. `source`: The source package of the component (e.g. `gamut` | `gamut-styles`) and a link to the corresponding code. +4. `status`: The health of the components API (e.g. `current` | `updating` | `deprecated` | `static`) +5. `design`: A link to the Figma file that is associated with the component. + +```tsx +import { Meta } from '@storybook/blocks'; + +import { ComponentHeader } from '~styleguide/blocks'; + +import * as AnchorStories from './Anchor.stories'; + +export const parameters = { + subtitle: `A clickable text element that navigates to another page, resource, or location on the same page.`, + design: { + type: 'figma', + url: 'https://www.figma.com/file/ReGfRNillGABAj5SlITalN/%F0%9F%93%90-Gamut?node-id=993-0', + }, + status: 'current', + source: { + repo: 'gamut', + githubLink: + 'https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/Anchor', + }, +}; + + + + + +``` + +## 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"`. + +Try to include the major behaviors for the component that most readers would need to understand its uses. + +```tsx +## Playground + +//If your flagship story is named Default, you don't need to specify it for the Playground + + + +``` + +## 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. + +```tsx +## Variant Anchors + +A short description should go here, as well as any variant specific usage guidelines. + + + +``` diff --git a/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component story tsx.mdx b/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component story tsx.mdx new file mode 100644 index 00000000000..e563ca526ec --- /dev/null +++ b/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component story tsx.mdx @@ -0,0 +1,77 @@ +import { Meta } from '@storybook/blocks'; + +import { AboutHeader } from '~styleguide/blocks'; + +export const parameters = { + id: 'Component story tsx', + title: 'Component story tsx', + subtitle: 'How to write .stories.tsx files for Gamut components', + status: 'static', +}; + + + + + +The `.stories.tsx` file defines the interactive examples and variations of your 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. + +## 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 = { + component: ComponentName, + args: { + variant: 'default', + }, +}; + +export default meta; +type Story = StoryObj; + +export const Default: Story = { + args: { + children: jpeg, + }, +}; + +export const Secondary: Story = { + args: { + children: 'Pro Content', + variant: 'secondary', + }, +}; +``` + +## Rendered code examples + +Examples rendered via `` 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) => , +}; +``` + +```tsx +// ✅ Provide the actual code +export const Default: Story = { + render: (args) => ( + + Some text that needs info + + + ), +}; +``` diff --git a/packages/styleguide/src/lib/Meta/Usage Guide.mdx b/packages/styleguide/src/lib/Meta/Usage guide.mdx similarity index 98% rename from packages/styleguide/src/lib/Meta/Usage Guide.mdx rename to packages/styleguide/src/lib/Meta/Usage guide.mdx index fd7d01107fa..434014bdd6d 100644 --- a/packages/styleguide/src/lib/Meta/Usage Guide.mdx +++ b/packages/styleguide/src/lib/Meta/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', }; - + From e657bb22c64be29933685c9931007faa190127ab Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Thu, 13 Nov 2025 12:51:47 -0500 Subject: [PATCH 14/23] re-orged Stories.mdx --- .../src/lib/Meta/Gamut writing guide/Stories/About.mdx | 9 ++++----- ...mponent story tsx.mdx => Component code examples.mdx} | 6 +++--- ...mponent MDX.mdx => Component story documentation.mdx} | 6 +++--- 3 files changed, 10 insertions(+), 11 deletions(-) rename packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/{Component story tsx.mdx => Component code examples.mdx} (94%) rename packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/{Component MDX.mdx => Component story documentation.mdx} (96%) diff --git a/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/About.mdx b/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/About.mdx index 458a2a983ed..20491b57c2f 100644 --- a/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/About.mdx +++ b/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/About.mdx @@ -7,8 +7,8 @@ import { } from '~styleguide/blocks'; import { parameters as aboutPagesParameters } from './About pages.mdx'; -import { parameters as componentMdxParameters } from './Component MDX.mdx'; -import { parameters as componentStoryTsxParameters } from './Component story tsx.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', @@ -44,15 +44,14 @@ When you make a new story theres a few things to keep in mind: 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. - ## Learn more Explore the pages below for detailed guidelines on each part of the story structure: diff --git a/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component story tsx.mdx b/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component code examples.mdx similarity index 94% rename from packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component story tsx.mdx rename to packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component code examples.mdx index e563ca526ec..7686393f6f3 100644 --- a/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component story tsx.mdx +++ b/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component code examples.mdx @@ -3,13 +3,13 @@ import { Meta } from '@storybook/blocks'; import { AboutHeader } from '~styleguide/blocks'; export const parameters = { - id: 'Component story tsx', - title: 'Component story tsx', + id: 'Component code examples', + title: 'Component code examples', subtitle: 'How to write .stories.tsx files for Gamut components', status: 'static', }; - + diff --git a/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component MDX.mdx b/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component story documentation.mdx similarity index 96% rename from packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component MDX.mdx rename to packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component story documentation.mdx index 5dc6a2c43ac..182e23c56a1 100644 --- a/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component MDX.mdx +++ b/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component story documentation.mdx @@ -3,13 +3,13 @@ import { Meta } from '@storybook/blocks'; import { AboutHeader } from '~styleguide/blocks'; export const parameters = { - id: 'Component MDX', - title: 'Component MDX', + id: 'Component story documentation', + title: 'Component story documentation', subtitle: 'How to write .mdx documentation files for Gamut components', status: 'static', }; - + From 13c5f17ffd6db8ba0f5aa08204e34d004b0608b4 Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Thu, 13 Nov 2025 13:18:02 -0500 Subject: [PATCH 15/23] more feedback --- .../src/lib/Meta/Gamut writing guide/Formatting.mdx | 6 ++---- .../src/lib/Meta/Gamut writing guide/Referencing code.mdx | 2 +- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/packages/styleguide/src/lib/Meta/Gamut writing guide/Formatting.mdx b/packages/styleguide/src/lib/Meta/Gamut writing guide/Formatting.mdx index f67b891d2cc..beac37294ee 100644 --- a/packages/styleguide/src/lib/Meta/Gamut writing guide/Formatting.mdx +++ b/packages/styleguide/src/lib/Meta/Gamut writing guide/Formatting.mdx @@ -58,10 +58,8 @@ Example: ## Headings Hierarchy -- H1: Page title (used once and set in the `parameters` object, not used explicitly) -- H2: Major sections -- H3: Subsections -- Maintain logical order — don't skip levels +- Start with second-level headings (`

` 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 diff --git a/packages/styleguide/src/lib/Meta/Gamut writing guide/Referencing code.mdx b/packages/styleguide/src/lib/Meta/Gamut writing guide/Referencing code.mdx index 30bdf11ae06..53febfc2785 100644 --- a/packages/styleguide/src/lib/Meta/Gamut writing guide/Referencing code.mdx +++ b/packages/styleguide/src/lib/Meta/Gamut writing guide/Referencing code.mdx @@ -59,7 +59,7 @@ yarn add @codecademy/gamut-kit ### Guidelines: -- Use bash syntax highlighting +- Use shell (`sh`) syntax highlighting for commands - Don't include command prompt symbols ($, #) - Show one command per block unless related From b6ce36472bfbd704c6a7aa995e69739bb34bcc48 Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Thu, 13 Nov 2025 13:40:47 -0500 Subject: [PATCH 16/23] formatted --- packages/styleguide/.storybook/preview.ts | 11 ++++++++++- .../lib/Meta/Gamut writing guide/Referencing code.mdx | 2 -- .../Stories/Component code examples.mdx | 2 ++ 3 files changed, 12 insertions(+), 3 deletions(-) diff --git a/packages/styleguide/.storybook/preview.ts b/packages/styleguide/.storybook/preview.ts index 99a4d6224cd..60199a33da9 100644 --- a/packages/styleguide/.storybook/preview.ts +++ b/packages/styleguide/.storybook/preview.ts @@ -34,7 +34,16 @@ const preview: Preview = { 'Stories', 'Usage guide', 'Gamut writing guide', - ['About', 'General principles', 'Documentation in code', 'Formatting', 'Language and grammar', 'Linking', 'Referencing code', 'Stories'], + [ + 'About', + 'General principles', + 'Documentation in code', + 'Formatting', + 'Language and grammar', + 'Linking', + 'Referencing code', + 'Stories', + ], ], 'Foundations', 'Layouts', diff --git a/packages/styleguide/src/lib/Meta/Gamut writing guide/Referencing code.mdx b/packages/styleguide/src/lib/Meta/Gamut writing guide/Referencing code.mdx index 53febfc2785..d7308825e25 100644 --- a/packages/styleguide/src/lib/Meta/Gamut writing guide/Referencing code.mdx +++ b/packages/styleguide/src/lib/Meta/Gamut writing guide/Referencing code.mdx @@ -70,7 +70,6 @@ yarn add @codecademy/gamut-kit - 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. @@ -85,4 +84,3 @@ When instructing users to interact with the interface, clearly identify what the - Avoid directional language: - ✅ "the following/adjacent form" or "in the previous section" - ❌ "the form on the right" or "in the section above" - diff --git a/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component code examples.mdx b/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component code examples.mdx index 7686393f6f3..06c49895d28 100644 --- a/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component code examples.mdx +++ b/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component code examples.mdx @@ -15,6 +15,8 @@ export const parameters = { The `.stories.tsx` file defines the interactive examples and variations of your 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 documentation, 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 reading these documents 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: From 14d8a28991e36566bbdebfffdae3029e53eead75 Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Thu, 13 Nov 2025 14:08:13 -0500 Subject: [PATCH 17/23] more feedback --- packages/styleguide/.storybook/preview.ts | 6 ++++++ .../src/lib/Meta/Gamut writing guide/Stories/About.mdx | 4 ++-- .../Gamut writing guide/Stories/Component code examples.mdx | 2 +- 3 files changed, 9 insertions(+), 3 deletions(-) diff --git a/packages/styleguide/.storybook/preview.ts b/packages/styleguide/.storybook/preview.ts index 60199a33da9..759850dbd82 100644 --- a/packages/styleguide/.storybook/preview.ts +++ b/packages/styleguide/.storybook/preview.ts @@ -43,6 +43,12 @@ const preview: Preview = { 'Linking', 'Referencing code', 'Stories', + [ + 'About', + 'About pages', + 'Component story documentation', + 'Component code examples', + ], ], ], 'Foundations', diff --git a/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/About.mdx b/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/About.mdx index 20491b57c2f..f38d634ed48 100644 --- a/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/About.mdx +++ b/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/About.mdx @@ -50,8 +50,8 @@ Explore the pages below for detailed guidelines on each part of the story struct diff --git a/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component code examples.mdx b/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component code examples.mdx index 06c49895d28..57dbcd64bf6 100644 --- a/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component code examples.mdx +++ b/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component code examples.mdx @@ -15,7 +15,7 @@ export const parameters = { The `.stories.tsx` file defines the interactive examples and variations of your 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 documentation, 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 reading these documents for more detailed information. +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 From fa9464dc8ef8945451c54ee02d999220d4c0fb87 Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Thu, 13 Nov 2025 14:23:27 -0500 Subject: [PATCH 18/23] more touch ups --- .../lib/Meta/Gamut writing guide/Stories/About pages.mdx | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/About pages.mdx b/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/About pages.mdx index cc9ce894e2f..e34f120d2c3 100644 --- a/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/About pages.mdx +++ b/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/About pages.mdx @@ -13,7 +13,7 @@ export const parameters = { -An `About.mdx` file serves as a landing page for folders containing multiple related components or stories. It provides a brief overview and organized table of contents to help users understand what the folder contains and navigate to specific components. Keep these pages concise with clear descriptions—they're entry points, not detailed documentation. +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 @@ -47,10 +47,3 @@ 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 - -## Best practices - -- **Write a clear overview**: Explain what the folder contains and how components relate to each other -- **Order logically**: Arrange components in the table of contents by importance or usage frequency -- **Keep it concise**: About pages should be brief entry points, not detailed documentation -- **Use descriptive subtitles**: Help users understand what they'll find before clicking through From b2b51d2198a34c92b3306bf94f18a102894155c6 Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Thu, 13 Nov 2025 14:50:49 -0500 Subject: [PATCH 19/23] more clean up --- .../src/lib/Meta/Gamut writing guide/Stories/About.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/About.mdx b/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/About.mdx index f38d634ed48..6c0c69bea0f 100644 --- a/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/About.mdx +++ b/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/About.mdx @@ -27,8 +27,8 @@ This guide covers how to write and organize Storybook stories for Gamut componen 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. +- `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 From 818c26d36d263bad9ecfaa43a8221d573ed0f8b8 Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Thu, 13 Nov 2025 16:01:26 -0500 Subject: [PATCH 20/23] one more sentence casing --- packages/styleguide/.storybook/preview.ts | 2 +- packages/styleguide/src/lib/Meta/Best practices.mdx | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/styleguide/.storybook/preview.ts b/packages/styleguide/.storybook/preview.ts index 759850dbd82..cc73d17d37d 100644 --- a/packages/styleguide/.storybook/preview.ts +++ b/packages/styleguide/.storybook/preview.ts @@ -26,7 +26,7 @@ const preview: Preview = { [ 'About', 'Brand', - 'Best Practices', + 'Best practices', 'Contributing', 'Deep Controls add-on', 'FAQs', diff --git a/packages/styleguide/src/lib/Meta/Best practices.mdx b/packages/styleguide/src/lib/Meta/Best practices.mdx index 01fba299992..c9a1e99b8e3 100644 --- a/packages/styleguide/src/lib/Meta/Best practices.mdx +++ b/packages/styleguide/src/lib/Meta/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', }; - + From 277ac2e3ed415a196b5a685baebb49a197ab9d1f Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Wed, 3 Dec 2025 13:26:08 -0500 Subject: [PATCH 21/23] address Cass's feedback --- .../src/lib/Meta/Gamut writing guide/Documentation in code.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/packages/styleguide/src/lib/Meta/Gamut writing guide/Documentation in code.mdx b/packages/styleguide/src/lib/Meta/Gamut writing guide/Documentation in code.mdx index 17a0f75b176..0591ce98d51 100644 --- a/packages/styleguide/src/lib/Meta/Gamut writing guide/Documentation in code.mdx +++ b/packages/styleguide/src/lib/Meta/Gamut writing guide/Documentation in code.mdx @@ -38,7 +38,8 @@ Clear, descriptive names reduce the need for comments and make code self-documen ### Components - Use `PascalCase` for component names: `Button`, `UserProfile`, `NavigationMenu` -- Name files to match the component: `Button.tsx`, `UserProfile.tsx` +- 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 From caa65a980a7c2ba88e683e25ebf0e3da1bef6ed0 Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Thu, 4 Dec 2025 11:11:07 -0500 Subject: [PATCH 22/23] updated writing guide docs according to feedback and edited sentences using 'you' pronouns --- .../src/lib/Meta/Gamut writing guide/About.mdx | 2 +- .../Gamut writing guide/Documentation in code.mdx | 2 +- .../src/lib/Meta/Gamut writing guide/Formatting.mdx | 2 +- .../Meta/Gamut writing guide/General principles.mdx | 7 ++++--- .../Gamut writing guide/Language and grammar.mdx | 13 +++++++------ .../src/lib/Meta/Gamut writing guide/Linking.mdx | 6 +++--- .../Meta/Gamut writing guide/Referencing code.mdx | 2 +- .../lib/Meta/Gamut writing guide/Stories/About.mdx | 8 ++++---- .../Stories/Component code examples.mdx | 2 +- .../Stories/Component story documentation.mdx | 2 +- 10 files changed, 24 insertions(+), 22 deletions(-) diff --git a/packages/styleguide/src/lib/Meta/Gamut writing guide/About.mdx b/packages/styleguide/src/lib/Meta/Gamut writing guide/About.mdx index 4d138b12b2f..e2ed5a347ba 100644 --- a/packages/styleguide/src/lib/Meta/Gamut writing guide/About.mdx +++ b/packages/styleguide/src/lib/Meta/Gamut writing guide/About.mdx @@ -28,7 +28,7 @@ export const 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. -If you're new here, start with General principles 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. +The General principles 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. -Good documentation starts in the code itself. By documenting components, props, and functions directly in your source files, you create a single source of truth that stays synchronized with the implementation and surfaces automatically in developer tools and Storybook. +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 diff --git a/packages/styleguide/src/lib/Meta/Gamut writing guide/Formatting.mdx b/packages/styleguide/src/lib/Meta/Gamut writing guide/Formatting.mdx index beac37294ee..458f0ae1ad6 100644 --- a/packages/styleguide/src/lib/Meta/Gamut writing guide/Formatting.mdx +++ b/packages/styleguide/src/lib/Meta/Gamut writing guide/Formatting.mdx @@ -66,4 +66,4 @@ Example: - Use blank lines to separate sections - Don't use multiple consecutive blank lines - Indent code consistently (2 spaces for TypeScript/TSX) - - If you prefer tabbing, then it should be set as 2 spaces + - When using tabs, set them to 2 spaces diff --git a/packages/styleguide/src/lib/Meta/Gamut writing guide/General principles.mdx b/packages/styleguide/src/lib/Meta/Gamut writing guide/General principles.mdx index 8773d241f67..95339f06863 100644 --- a/packages/styleguide/src/lib/Meta/Gamut writing guide/General principles.mdx +++ b/packages/styleguide/src/lib/Meta/Gamut writing guide/General principles.mdx @@ -13,12 +13,13 @@ export const 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 you're 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. +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 -- Direct and action-oriented: Use "you" to address readers +- 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 @@ -33,7 +34,7 @@ Good documentation does more than describe — it helps people succeed. These pr - Clearly indicate component status: - `current`: Stable, recommended for use - `updating`: In progress, API may change - - `deprecated`: Do not use for new work + - `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) diff --git a/packages/styleguide/src/lib/Meta/Gamut writing guide/Language and grammar.mdx b/packages/styleguide/src/lib/Meta/Gamut writing guide/Language and grammar.mdx index f49b068bf1a..f6da0a199b2 100644 --- a/packages/styleguide/src/lib/Meta/Gamut writing guide/Language and grammar.mdx +++ b/packages/styleguide/src/lib/Meta/Gamut writing guide/Language and grammar.mdx @@ -17,21 +17,22 @@ export const parameters = { 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 second person ("you") when addressing the reader -- Use imperative mood for instructions: "Add the component" not "You should add the component" +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 you use conditional or future tense, the harder your audience has to work to understand your meaning. E.g. "The `StrokeButton` component accepts a `variant` prop." +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 -- Use "you" for the user -- Avoid "we" unless referring to the Codecademy team -- Avoid “I/my/me” entirely +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 diff --git a/packages/styleguide/src/lib/Meta/Gamut writing guide/Linking.mdx b/packages/styleguide/src/lib/Meta/Gamut writing guide/Linking.mdx index b822165e659..070b6527b08 100644 --- a/packages/styleguide/src/lib/Meta/Gamut writing guide/Linking.mdx +++ b/packages/styleguide/src/lib/Meta/Gamut writing guide/Linking.mdx @@ -42,7 +42,7 @@ When linking to external resources like official documentation or tools, use the ### Markdown Links: -You can use Markdown for external links, the examples below will open in a new tab: +Use Markdown for external links. The examples below will open in a new tab: ```markdown [GitHub Repository](https://github.com/Codecademy/gamut) @@ -51,10 +51,10 @@ You can use Markdown for external links, the examples below will open in a new t ### Anchor Component: -If you need more control over the link, you can use the `Anchor` component,the example below will open in the current tab: +For more control over the link, use the `Anchor` component. The example below will open in the current tab: ```tsx Gamut Repository ``` - + diff --git a/packages/styleguide/src/lib/Meta/Gamut writing guide/Referencing code.mdx b/packages/styleguide/src/lib/Meta/Gamut writing guide/Referencing code.mdx index d7308825e25..5a5f9f34775 100644 --- a/packages/styleguide/src/lib/Meta/Gamut writing guide/Referencing code.mdx +++ b/packages/styleguide/src/lib/Meta/Gamut writing guide/Referencing code.mdx @@ -19,7 +19,7 @@ This guide covers how to reference code elements, UI components, file paths, and - Use backticks for inline code: `onClick`, `flex-direction`, `Box`, `StrokeButton`, `variant`, backgroundColor`, etc. - File and package names: `Button.tsx`, `package.json`, `@codecademy/gamut` - - Unless you're linking to them, in which case use permalinks + - 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 diff --git a/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/About.mdx b/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/About.mdx index 6c0c69bea0f..40343307fb6 100644 --- a/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/About.mdx +++ b/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/About.mdx @@ -25,7 +25,7 @@ This guide covers how to write and organize Storybook stories for Gamut componen ## Quick start -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. +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. @@ -33,7 +33,7 @@ We've provided a few helpful vscode snippets to help you get through boilerplate ## File structure and naming -When you make a new story theres a few things to keep in mind: +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. @@ -41,8 +41,8 @@ When you make a new story theres a few things to keep in mind: - Example: `General principles.mdx` - Component-related files should use kebab-case: `RadialProgress.mdx` -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. +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 diff --git a/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component code examples.mdx b/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component code examples.mdx index 57dbcd64bf6..51b7c5a244e 100644 --- a/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component code examples.mdx +++ b/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component code examples.mdx @@ -13,7 +13,7 @@ export const parameters = { -The `.stories.tsx` file defines the interactive examples and variations of your 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. +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. diff --git a/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component story documentation.mdx b/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component story documentation.mdx index 182e23c56a1..f9ea17f9a3d 100644 --- a/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component story documentation.mdx +++ b/packages/styleguide/src/lib/Meta/Gamut writing guide/Stories/Component story documentation.mdx @@ -13,7 +13,7 @@ export const parameters = { -The `.mdx` file provides the documentation structure and context for your component. It combines the interactive stories from the `.stories.tsx` file with written documentation, usage guidelines, and metadata. +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. ## Story structure From 91f472633ca2daf3ae54ba1e81db5f4bf2a2c5c4 Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Fri, 5 Dec 2025 14:22:09 -0500 Subject: [PATCH 23/23] fix import --- packages/styleguide/src/lib/Meta/About.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/styleguide/src/lib/Meta/About.mdx b/packages/styleguide/src/lib/Meta/About.mdx index 0d94ac33b11..7972a56527c 100644 --- a/packages/styleguide/src/lib/Meta/About.mdx +++ b/packages/styleguide/src/lib/Meta/About.mdx @@ -9,7 +9,7 @@ import { 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';