docs: Add Gamut Style Guide under /Meta #3197

LinKCoding · 2025-10-27T18:28:49Z

Overview

Adds a style guide for documentation purposes

PR Checklist

Related to designs:
Related to JIRA ticket: GMT-157
I have run this code to verify it works
This PR includes unit tests for the code change
This PR includes testing instructions tests for the code change
The alpha package of this PR is passing end-to-end tests in all relevant Codecademy repositories

Testing Instructions

Don't make me tap the sign.

Go to story /?path=/docs/meta-style-guide-about--docs
Check that the links work
Go through the pages and check that guidelines make sense
...
Finish and do a celebratory dance

PR Links and Envs

N/A

nx-cloud · 2025-10-27T18:29:30Z

View your CI Pipeline Execution ↗ for commit bc10713

☁️ Nx Cloud last updated this comment at 2025-10-29 15:28:45 UTC

aresnik11

Some initial thoughts!

packages/styleguide/src/lib/Meta/Style Guide/Component Pages.mdx

packages/styleguide/src/lib/Meta/Style Guide/Computer Interfaces.mdx

packages/styleguide/src/lib/Meta/Style Guide/Component Pages.mdx

Co-authored-by: Amy Resnik <[email protected]>

…es.mdx Co-authored-by: Amy Resnik <[email protected]>

dreamwasp

lgtm, def want emily to take a look!

packages/styleguide/src/lib/Meta/Style Guide/Component Pages.mdx

packages/styleguide/src/lib/Meta/Style Guide/Computer Interfaces.mdx

packages/styleguide/src/lib/Meta/Style Guide/Formatting.mdx

codecademydev · 2025-10-29T15:29:12Z

📬 Published Alpha Packages:

@codecademy/[email protected]

github-actions · 2025-10-29T15:31:47Z

🚀 Styleguide deploy preview ready!

Preview URL: https://6902335e02bbceefc63474ba--gamut-preview.netlify.app
Deploy Logs: https://app.netlify.com/projects/gamut-preview/deploys/6902335e02bbceefc63474ba

sh0ji

Finally had a chance to get my thoughts down, and there are a lot of them but I'm generally very excited about this. Great job on it!

Two other, more meta questions:

Should this guide live in Storybook? If it's for people writing Gamut documentation, my inclination is that it should be part of a contribution guide rather than part of Gamut docs.
How do we want to this guide to relate to Codecademy styling and grammar? Should our guide be aware of it? In deference to it? The draft you've written doesn't currently seem to acknowledge it and even conflicts with it in a few places (I only noted one).

sh0ji · 2025-11-05T13:42:52Z

packages/styleguide/src/lib/Meta/Style Guide/About.mdx

+  id: 'Meta/Style Guide',
+  title: 'Style Guide',
+  subtitle:
+    'Guidelines and standards for creating consistent, clear, and effective documentation.',


I initially thought this guide was a general guide for writing documentation anywhere across Skillsoft because of the title and description. I think it's better off starting as a guide for writing documentation in Gamut. Even if we think it'll be more widely useful, it's best to start narrow and broaden based on user needs.

I might suggest something like this but I know @uxemilylee had other ideas.

Suggested change

id: 'Meta/Style Guide',

title: 'Style Guide',

subtitle:

'Guidelines and standards for creating consistent, clear, and effective documentation.',

id: 'Meta/Gamut Writing Guide',

title: 'Gamut Writing Guide',

subtitle:

'Guidelines for consistent, clear, and effective documentation in Gamut.',

I like these suggestions! "Gamut Documentation Writing Guide" would be the most specific to me, but I'm OK with "Gamut Writing Guide" and we could monitor just in case people misinterpret these as writing for specific components.

sh0ji · 2025-11-05T13:55:07Z

packages/styleguide/src/lib/Meta/Style Guide/General Principles.mdx

+## Voice and Tone
+
+- Friendly and conversational: Write as if explaining to a colleague
+- Direct and action-oriented: Use "you" to address readers


I much prefer "we" in any writing where the reader is learning from an expert because it quietly invites the reader to be the expert, whereas "you" creates a line between author and reader: "I the expert am telling you the novice what's what." Or more simply, "we" is inclusive, "you" creates separation.

My general advice here is to prefer "we" whenever possible because there will be times when "you" is the better choice. For instance, it wouldn't make sense to say "use our best judgment" if we're encouraging the reader to use their judgment, so "use your best judgment" would be fine. But those instances are surprisingly rare—we can usually use "we" for most things without much effort.

sh0ji · 2025-11-05T13:59:53Z

packages/styleguide/src/lib/Meta/Style Guide/General Principles.mdx

+- Clearly indicate component status:
+  - `current`: Stable, recommended for use
+  - `updating`: In progress, API may change
+  - `deprecated`: Do not use for new work


Small quibble: "deprecated" means still actively supported but an end is planned. I mention it because a lot of people think it means "no longer supported" in my experience.

Quick question, are these 4 component status labels considered "props"?

sh0ji · 2025-11-05T14:11:16Z

packages/styleguide/src/lib/Meta/Style Guide/General Principles.mdx

+<Meta title="Meta/Style Guide/General Principles" />
+
+<AboutHeader {...parameters} />
+


It'd be good to have an introductory paragraph to this page especially, but we also might want that for every separate page. This page's introduction should be philosophical and inspirational, helping to answer "why" for subsequent style opinions.

For instance: "Great documentation improves understanding. Not just for our readers but for us, the authors. The act of writing forces us to articulate our mental models clearly so that our readers can share in our framing and understanding." (don't use this, it's just off the dome)

I'm also very partial to the Vue writing guide opening paragraph:

Writing documentation is an exercise in empathy. We're not describing an objective reality - the source code already does that. Our job is to help shape the relationship between users and the Vue ecosystem. This ever-evolving guide provides some rules and recommendations on how to do that consistently within the Vue ecosystem.

Aside from the clarity of their perspective on the point of documentation, I like their inclusion of "this ever-evolving guide" since it makes it immediately clear that their guidance isn't final.

sh0ji · 2025-11-05T14:15:30Z

packages/styleguide/src/lib/Meta/Style Guide/Formatting.mdx

+
+## Numbers
+
+- Spell out numbers one through nine


This is in conflict with brand guidelines:

Use numerals for all number (5 not five). Exceptions can be made for common phrases (e.g. The one thing to remember is...)

There might be other examples of this. We should find and then reconcile all of them, either by sticking to the conflict and explaining why it needs to be different in our context, or deferring to the brand guide.

This was one the conflicts I noticed, and I suggest unifying this guideline to say use numerals for all numbers. => This helps with consistency for multiple people writing in systems, and there is some readability research that supports this for ease of reading on the web.

sh0ji · 2025-11-05T16:07:54Z

packages/styleguide/src/lib/Meta/Style Guide/Referencing Code.mdx

+
+- Use bash syntax highlighting
+- Don't include command prompt symbols ($, #)
+- Use yarn as the default package manager


Let's not include user space technology choices in our guidelines. If anything, we should recommend documentation writers be inclusive about the technology choices of our users.

# install with your package manager of choice npm install @codecademy/gamut-kit pnpm add @codecademy/gamut-kit yarn add @codecademy/gamut-kit

Or better yet, let the user choose their package manager globally and then just show commands for it.
For instance, this is what I did for the Norton Design System's getting started guide (source code).

sh0ji · 2025-11-05T16:41:09Z

packages/styleguide/src/lib/Meta/Style Guide/Referencing Code.mdx

+
+## File Paths
+
+- Use forward slashes: `packages/gamut/src/Button/index.tsx`


Why do we need to say this?

sh0ji · 2025-11-05T16:44:17Z

packages/styleguide/src/lib/Meta/Style Guide/Referencing Code.mdx

+- Use absolute paths from workspace root when clearer
+- Format as inline code: `/packages/styleguide/src`


I don't think you mean absolute paths here. /packages/styleguide/src doesn't exist on my computer, for instance. I keep my copy of the repo at $HOME/code/gamut, so the absolute path would be /Users/evan.yamanishi/code/gamut/packages/styleguide/src.

sh0ji · 2025-11-05T16:58:24Z

packages/styleguide/src/lib/Meta/Style Guide/Referencing Code.mdx

+## 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


Could we split this into a separate section on writing documentation in code? This page is about referencing code, but I think there's a lot of benefit of having consistent comments in our code, and we probably want a style guide for that.

sh0ji · 2025-11-05T21:38:29Z

packages/styleguide/src/lib/Meta/Style Guide/Stories.mdx

How would you feel about directing contributors to follow the component story format standard (CSF) or even the Storybook docs on writing stories in TypeScript? We could then have this page focus purely on Gamut style: the situations where we have an opinion about something that's flexible in CSF, or requirements that are unique to Gamut.

sh0ji · 2025-11-06T22:12:18Z

Another thought: a lot of this guidance would be very useful in an agent instructions/rules/skills file. I often have Cursor help me write docs, and it always seems to format things in ways I don't like, so I end up having to correct it. This guide would be a huge help with that.

For instance:

./.cursor/rules/documentation-style.mdc - for Cursor
./.github/instructions/documentation-style.instructions.md - for GitHub Copilot & VSCode
./CLAUDE.md - for Claude, which just allows for the one file
- I think Skills would be something like ./skills/documentation/{SKILL,STYLE}.md, where the SKILL.md "imports" the STYLE.md file, but I haven't used that yet.

uxemilylee · 2025-11-07T01:02:28Z

packages/styleguide/src/lib/Meta/Style Guide/Language and Grammer.mdx

+
+## Capitalization
+
+- Sentence case for all headings, buttons, and UI text


It looks like we need to make all the headings in the writing guidelines section conform to sentence case...

Also a couple of copy editing items:
Language and Grammer => Language and grammar
Refencing Code => Referencing code

uxemilylee · 2025-11-07T01:10:50Z

packages/styleguide/.storybook/preview.ts

          'Meta',
-          ['About', 'Best Practices', 'Contributing', 'FAQs', 'Stories'],
+          [
+            'About',


@LinKCoding What do you think of the order of the sections? Would we want descending order based on priority? It looks like it's alphabetical in the left nav, and there's a mismatch between the left nav and when I'm on the About page.

uxemilylee · 2025-11-07T01:25:12Z

packages/styleguide/src/lib/Meta/Style Guide/General Principles.mdx

+  - `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 (Figma, GitHub)


Very nitpick 😅: Could we switch the order to match:

Link to source code and design files (GitHub, Figma)

uxemilylee · 2025-11-07T01:28:14Z

packages/styleguide/src/lib/Meta/Style Guide/Language and Grammer.mdx

+
+- Use active voice: "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"


Lol thanks for using this phrase! "imperative mood"

uxemilylee · 2025-11-07T01:31:03Z

packages/styleguide/src/lib/Meta/Style Guide/Language and Grammer.mdx

+- Use "you" for the user
+- Avoid "we" unless referring to the Codecademy team
+- Avoid “I/my/me” entirely
+- Avoid "your/my" in button labels: prefer "Go to dashboard" over "Go to your dashboard"


Is this getting into the component-specific writing guidelines? Or are there parts of Storybook where contributors are writing buttons?

uxemilylee · 2025-11-07T07:18:39Z

packages/styleguide/src/lib/Meta/Style Guide/Language and Grammer.mdx

+- 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


Love the succinctness and clarity of the sections!

LinKCoding added 3 commits October 24, 2025 18:39

started foundation for style guide

a2ef92b

round out docs

be93a53

QA'd

6acf546

LinKCoding requested a review from a team as a code owner October 27, 2025 18:28

LinKCoding requested review from aresnik11 and jakemhiller October 27, 2025 18:28

formatted

41ac0da

aresnik11 reviewed Oct 28, 2025

View reviewed changes

packages/styleguide/src/lib/Meta/Style Guide/Component Pages.mdx Outdated Show resolved Hide resolved

LinKCoding and others added 4 commits October 29, 2025 09:43

Update packages/styleguide/src/lib/Meta/Style Guide/Component Pages.mdx

5637dea

Co-authored-by: Amy Resnik <[email protected]>

Update packages/styleguide/src/lib/Meta/Style Guide/Component Pages.mdx

60f0a66

Co-authored-by: Amy Resnik <[email protected]>

Update packages/styleguide/src/lib/Meta/Style Guide/Computer Interfac…

d094255

…es.mdx Co-authored-by: Amy Resnik <[email protected]>

Merge branch 'main' into kl-gmt-157

5a55840

dreamwasp reviewed Oct 29, 2025

View reviewed changes

packages/styleguide/src/lib/Meta/Style Guide/Component Pages.mdx Outdated Show resolved Hide resolved

packages/styleguide/src/lib/Meta/Style Guide/Computer Interfaces.mdx Show resolved Hide resolved

packages/styleguide/src/lib/Meta/Style Guide/Formatting.mdx Show resolved Hide resolved

LinKCoding added 2 commits October 29, 2025 11:14

apply Amy's and Cass's feedback

70901b8

renaming files

bc10713

sh0ji requested changes Nov 5, 2025

View reviewed changes

uxemilylee reviewed Nov 7, 2025

View reviewed changes

		<Meta title="Meta/Style Guide/General Principles" />

		<AboutHeader {...parameters} />


		## File Paths

		- Use forward slashes: `packages/gamut/src/Button/index.tsx`

		- Use absolute paths from workspace root when clearer
		- Format as inline code: `/packages/styleguide/src`


		## Capitalization

		- Sentence case for all headings, buttons, and UI text

docs: Add Gamut Style Guide under /Meta #3197

Are you sure you want to change the base?

docs: Add Gamut Style Guide under /Meta #3197

Uh oh!

Conversation

LinKCoding commented Oct 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

PR Checklist

Testing Instructions

PR Links and Envs

Uh oh!

nx-cloud bot commented Oct 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aresnik11 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dreamwasp left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecademydev commented Oct 29, 2025

Uh oh!

github-actions bot commented Oct 29, 2025

Uh oh!

sh0ji left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sh0ji Nov 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sh0ji Nov 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sh0ji commented Nov 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

uxemilylee Nov 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

uxemilylee Nov 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LinKCoding commented Oct 27, 2025 •

edited

Loading

nx-cloud bot commented Oct 27, 2025 •

edited

Loading

sh0ji left a comment •

edited

Loading

sh0ji Nov 5, 2025 •

edited

Loading

sh0ji Nov 5, 2025 •

edited

Loading

sh0ji commented Nov 6, 2025 •

edited

Loading

uxemilylee Nov 7, 2025 •

edited

Loading

uxemilylee Nov 7, 2025 •

edited

Loading