diff --git a/packages/styleguide/.storybook/preview.ts b/packages/styleguide/.storybook/preview.ts
index bccda059ff0..cb2b4da7c64 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',
+ 'Gamut Writing Guide',
+ ],
'Foundations',
'Layouts',
'Typography',
diff --git a/packages/styleguide/src/lib/Meta/About.mdx b/packages/styleguide/src/lib/Meta/About.mdx
index 77487f9b7a3..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 storiesParameters } from './Stories.mdx';
import { parameters as usageGuideParameters } from './Usage Guide.mdx';
export const parameters = {
@@ -32,7 +32,7 @@ export const parameters = {
contributingParameters,
deepControlsParameters,
faqsParameters,
- storiesParameters,
+ gamutWritingGuideParameters,
brandParameters,
installationParameters,
usageGuideParameters,
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..0de79da9e8f
--- /dev/null
+++ b/packages/styleguide/src/lib/Meta/Gamut Writing Guide/About.mdx
@@ -0,0 +1,36 @@
+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/Formatting.mdx b/packages/styleguide/src/lib/Meta/Gamut Writing Guide/Formatting.mdx
new file mode 100644
index 00000000000..d29b2538827
--- /dev/null
+++ b/packages/styleguide/src/lib/Meta/Gamut Writing Guide/Formatting.mdx
@@ -0,0 +1,71 @@
+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',
+};
+
+
+
+
+
+Consistent formatting makes documentation easier to scan, understand, and implement. These standards ensure our content is predictable and professional across all Gamut components.
+
+## Numbers
+
+- Use numerals for all numbers
+- Use commas for thousands: 1,000
+
+## Units of Measurement
+
+- Use standard units: px, rem, em, %
+- Include space between number and unit in prose: "16 pixels"
+- No space in code: `16px`, `2rem`
+
+## Lists
+
+Lists help break down complex information into digestible pieces. Use them to organize features, steps, or related concepts.
+
+### Bulleted lists:
+
+- Use for unordered items
+- Use parallel structure
+- End with periods if items are complete sentences
+- No periods if items are fragments
+
+### Numbered lists:
+
+- Use for sequential steps or prioritized items
+- Start each item with a capital letter
+
+## Code Blocks
+
+- Use triple backticks (` ``` `) with language identifier (e.g., `tsx`, `javascript`, `css`)
+- Include comments for complex examples
+- Keep examples concise and focused
+
+Example:
+
+````
+```tsx
+ Click me
+```
+````
+
+## 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
+
+## 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
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
new file mode 100644
index 00000000000..ccd792c8f31
--- /dev/null
+++ b/packages/styleguide/src/lib/Meta/Gamut Writing Guide/General Principles.mdx
@@ -0,0 +1,45 @@
+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',
+};
+
+
+
+
+
+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
+- Encouraging without overpromising: Be supportive but realistic
+- Global audience awareness: Avoid idioms, slang, and culturally-specific references
+
+## Inclusivity
+
+- Use inclusive language that makes all contributors feel welcome
+- Define terms when first introduced
+- Consider contributors of varying experience levels and roles (designers and developers)
+
+## Transparency
+
+- Clearly indicate component status:
+ - `current`: Stable, recommended for use
+ - `updating`: In progress, API may change
+ - `deprecated`: Do not use for new work
+ - `static`: Reference material, no active development
+- Link to source code and design files (GitHub, Figma)
+
+## Consistency
+
+- Use a single term for the same concept, including how it's referred to between the heading, body copy, and code examples.
+- Do not use the same term for 2 different concepts.
+- Maintain consistent component naming across packages
+- Follow established patterns from existing components
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 Grammer.mdx
new file mode 100644
index 00000000000..651cac304e8
--- /dev/null
+++ b/packages/styleguide/src/lib/Meta/Gamut Writing Guide/Language and Grammer.mdx
@@ -0,0 +1,53 @@
+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',
+};
+
+
+
+
+
+## Voice
+
+Use active voice rather than passive voice — it makes clear who should do what and eliminates ambiguity about responsibilities. Passive voice obscures who handles what and makes documentation harder to follow. E.g. "The component renders..." not "The component is rendered by..."
+
+- Use 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 — 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
+
+## Pronouns
+
+- Use "you" for the user
+- Avoid "we" unless referring to the Codecademy team
+- Avoid “I/my/me” entirely
+
+## Articles
+
+- Use articles (a, an, the) for clarity
+- Omit articles in lists when appropriate for brevity
+
+## Abbreviations and Acronyms
+
+- Spell out on first use: "Web Content Accessibility Guidelines (WCAG)"
+- Use abbreviations for common terms in the domain of web design and development:
+ - HTML, CSS, API, UI, UX, etc.
+- Avoid uncommon abbreviations without definition
+
+## Capitalization
+
+- Sentence case for all headings, buttons, and UI text
+- PascalCase for component names: `MyComponent`, `ButtonGroup`
+- camelCase for props and variables: `onClick`, `backgroundColor`
+- Capitalize proper nouns: Codecademy, Storybook, Figma, GitHub
diff --git a/packages/styleguide/src/lib/Meta/Gamut Writing Guide/Linking.mdx b/packages/styleguide/src/lib/Meta/Gamut Writing Guide/Linking.mdx
new file mode 100644
index 00000000000..e68d7003241
--- /dev/null
+++ b/packages/styleguide/src/lib/Meta/Gamut Writing Guide/Linking.mdx
@@ -0,0 +1,60 @@
+import { Meta } from '@storybook/blocks';
+
+import { AboutHeader, Callout } from '~styleguide/blocks';
+
+export const parameters = {
+ id: 'Linking',
+ title: 'Linking',
+ subtitle: 'Best practices for linking within documentation',
+ status: 'static',
+};
+
+
+
+
+
+Use links to help users navigate between related components and resources. This guide covers linking within Storybook, to external sites, and writing clear link text.
+
+## Internal Links
+
+Use the `LinkTo` component from ‘~styleguide/blocks' and set the id prop as the story’s id value.
+
+```tsx
+import { LinkTo } from '~styleguide/blocks';
+Stories
+Animation
+```
+
+### Guidelines:
+
+- Link text describes the destination, not the action: "See the [Stories page](#)" not "[See the Stories page](#)"
+- Use descriptive link text that makes sense out of context: "[Stories page](#)" not "[Click here](#)"
+- Link component names to their documentation
+- Verify that the link works correctly
+- 2-3 words minimum for easy clicking
+- Unique link text when multiple links on page
+- Meaningful and descriptive: conveys destination
+- Action-oriented when appropriate: "View the component"
+
+## External Links
+
+When linking to external resources like official documentation or tools, use the following guidelines.
+
+### Markdown Links:
+
+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
+```
+
+
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/Stories.mdx b/packages/styleguide/src/lib/Meta/Gamut Writing Guide/Stories.mdx
similarity index 76%
rename from packages/styleguide/src/lib/Meta/Stories.mdx
rename to packages/styleguide/src/lib/Meta/Gamut Writing Guide/Stories.mdx
index b7fda0c938d..29e2eb15acf 100644
--- a/packages/styleguide/src/lib/Meta/Stories.mdx
+++ b/packages/styleguide/src/lib/Meta/Gamut Writing Guide/Stories.mdx
@@ -9,10 +9,12 @@ export const parameters = {
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.
@@ -143,7 +145,7 @@ export const parameters = {
### Flagship story
-The Flagship story for a component should be intended to give the reader a broad overview of its high-level functionality. Its `Canvas` should automatically display the story's code by setting the prop sourceState="shown".
+The Flagship story for a component should be intended to give the reader a broad overview of its high-level functionality. Its `Canvas` should automatically display the story's code by setting the prop `sourceState="shown"`.
Try to include the major behaviors for the component that most readers would need to understand its uses.
@@ -170,11 +172,46 @@ A short description should go here, as well as any variant specific usage guidel
```
+### 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, import the `parameters` object from the respective component's `.mdx` file and pass it to the `` 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';
@@ -192,4 +229,4 @@ export const parameters = {
```
-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.
+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.