@codecademy/styleguide 79.2.4-alpha.38d1e4.0 → 79.2.4-alpha.9ce37a.0

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

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

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

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

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

@@ -1,49 +0,0 @@
-import { Meta } from '@storybook/blocks';
-
-import { AboutHeader, LinkTo } from '~styleguide/blocks';
-
-export const parameters = {
-  id: 'About pages',
-  title: 'About pages',
-  subtitle: 'How to create table of contents pages for component folders',
-  status: 'static',
-};
-
-<Meta title="Meta/Gamut writing guide/Stories/About pages" />
-
-<AboutHeader {...parameters} />
-
-An `About.mdx` file serves as a landing page for folders containing multiple related components or stories. Write a clear overview explaining what the folder contains and how components relate. Organize components logically by importance or usage frequency, use descriptive subtitles, and keep it concise—these are entry points, not detailed documentation.
-
-## When to create an About page
-
-Create an `About.mdx` file when multiple stories are presented in a folder. For example, the <LinkTo id="Atoms/Icons/About">Icons</LinkTo> folder contains an `About.mdx` file with a table of contents that links to more specific information about the icons — in this case, <LinkTo id="Atoms/Icons/Mini">Mini icons</LinkTo> and <LinkTo id="Atoms/Icons/Regular">Regular icons</LinkTo>.
-
-## Basic structure
-
-Inside the `About.mdx` file, use the `toc-story` snippet to generate a template. Import the `parameters` object from the respective component's `<ComponentName>.mdx` file and pass it to the `<TableOfContents />` component.
-
-```tsx
-import { parameters as componentNameParameters } from './ComponentName.mdx';
-import { parameters as anotherComponentParameters } from './AnotherComponent.mdx';
-
-
-export const parameters = {
-  id: 'ParentDir/FolderName',
-  title: 'FolderName',
-  subtitle: 'Overview of the components in this folder.',
-};
-
-...
-
-<TableOfContents links={addParentPath(parameters.id, [componentNameParameters, anotherComponentParameters]))} />
-```
-
-## The addParentPath function
-
-The `addParentPath()` function is used to ensure that the links in the table of contents have the correct IDs, which are derived from the parent path and the component's ID or title.
-
-This function takes two arguments:
-
-1. The parent path (`parameters.id`) - defines the folder hierarchy
-2. An array of parameter objects from child components/pages

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

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

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

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