docs: fixes LinkTo and adds new docs to README

README.md

@@ -58,13 +58,13 @@ We provide a single package to manage the versions of a few core dependencies: `
 ## Local development
 
 1.  Run `yarn` in the root directory
-1.  Run `yarn build` to build all of the packages (certain packages like `gamut-icons` need to be built to function in storybook).
+2.  Run `yarn build` to build all of the packages (certain packages like `gamut-icons` need to be built to function in storybook).
 
 ### Running the storybook styleguide
 
-1.  Run `yarn start` to start the storybook server
-1.  Add new stories to `packages/styleguide/stories`
-1.  Stories are written using storybook's [Component Story Format](https://storybook.js.org/docs/formats/component-story-format/)
+1.  Run `yarn nx storybook styleguide` to start the storybook server
+2.  Add new stories to `packages/styleguide/src`
+3.  Stories are written using storybook's [Component Story Format](https://storybook.js.org/docs/formats/component-story-format/) and [MDX](https://storybook.js.org/docs/writing-docs/mdx#basic-example). Check out our Storybook's comprehensive guide on writing stories [here](https://storybook.js.org/docs/react/get-started/introduction).
 
 ### Publishing Modules
 

packages/styleguide/.storybook/components/Elements/Markdown.tsx

@@ -1,4 +1,4 @@
-import { Anchor, AnchorBase } from '@codecademy/gamut';
+import { Anchor } from '@codecademy/gamut';
 import { themed } from '@codecademy/gamut-styles';
 import styled from '@emotion/styled';
 import { linkTo } from '@storybook/addon-links';

packages/styleguide/src/lib/Atoms/Badge/Badge.mdx

@@ -38,8 +38,8 @@ Use `Badge`s to display read-only information like statuses, attributes, and oth
 
 ### When NOT to use:
 
-- **Interactivity**- when text is meant to be clickable, use the <LinkTo component="Atoms/Button">Button</LinkTo> or <LinkTo component="Typography/Anchor">Anchor</LinkTo> (link) components instead.
-- **Categorization**- for labeling or catgorizing content, use the <LinkTo component="Atoms/Tag">Tag</LinkTo> component instead.
+- **Interactivity**- when text is meant to be clickable, use the <LinkTo id="Atoms/Buttons">Button</LinkTo> or <LinkTo id="Typography/Anchor">Anchor</LinkTo> components instead.
+- **Categorization**- for labeling or catgorizing content, use the <LinkTo id="Atoms/Tag">Tag</LinkTo> component instead.
 
 ## Anatomy
 
@@ -92,24 +92,31 @@ Use the accent variant to draw attention to important details or statuses with a
 <Canvas of={BadgeStories.Accent} />
 
 ## Sizes
+
 We have two `size` options, which should be used according to their context.
 
 ### Default size
+
 Use `primary` when the `Badge` is a standalone entitity.
-<Canvas of={BadgeStories.DefaultSize} />
 
+<Canvas of={BadgeStories.DefaultSize} />
 
 ### Small size
-Use `sm` when the `Badge` is inline with other components such as <LinkTo kind='Typography/Text'>Text</LinkTo>.
+
+Use `sm` when the `Badge` is inline with other components such as <LinkTo id='Typography/Text'>Text</LinkTo>.
+
 <Canvas of={BadgeStories.SmallSize} />
 
 ## Leading icon
+
 Include the `icon` property when the icon reinforces the badge’s message and improves scannability. Since badges are inherently small, it's recommended to use Gamut's mini icons. Below are examples of using icons with the different `Badge` sizes.
 
 ### Default size with icon
+
 <Canvas of={BadgeStories.DefaultSizeWithIcon} />
 
 ### Small size with icon
+
 <Canvas of={BadgeStories.SmallSizeWithIcon} />
 
 ## Playground

packages/styleguide/src/lib/Atoms/Buttons/Button/Button.mdx

@@ -39,21 +39,26 @@ All but CTA button support a size of either `normal` (default) or `small`.
 
 - Avoid using a color mode outside of its context (no light buttons on navy backgrounds)
 
-
 ## Variants
+
 The examples below use `FillButton` to showcase the `primary` and `secondary` button variants.
+
 ### Primary
+
 <Canvas of={ButtonStories.Primary} />
 
 ### Secondary
+
 <Canvas of={ButtonStories.Secondary} />
 
 ## Inline icons
-Our <LinkTo id="atoms-buttons-fillbutton">FillButton </LinkTo>, <LinkTo id="atoms-buttons-strokebutton">StrokeButton </LinkTo>, and <LinkTo id="atoms-buttons-textbutton">TextButton </LinkTo> all support a single inline icon. You can align the icon to the left or right of the button text using the `iconPosition` prop. These icons should be from the mini set to be legible at a smaller size.
+
+Our <LinkTo id="Atoms/Buttons/FillButton">FillButton </LinkTo>, <LinkTo id="Atoms/Buttons/StrokeButton">StrokeButton </LinkTo>, and <LinkTo id="Atoms/Buttons/TextButton">TextButton</LinkTo> all support a single inline icon. You can align the icon to the left or right of the button text using the `iconPosition` prop. These icons should be from the mini set to be legible at a smaller size.
 
 <Canvas of={ButtonStories.InlineIcons} />
 
 ## Buttons in light and dark mode
+
 Below are examples of how buttons could look in their respective light and dark modes.
 
 ### Light mode
@@ -68,7 +73,7 @@ Below are examples of how buttons could look in their respective light and dark
 
 Writing words for a link or button? Above all else, make sure that the words alone make it clear where a button or link will take the user. Refer to the checklist below for guidance. For more tips and best practices, check out the full guide about <LinkTo id="ux-writing-component-guidelines-buttons-and-links--page">writing for buttons and links</LinkTo>.
 
-* Make sure it is clear where the link or button will take the user.
-* Use sentence case, capitalizing only proper nouns.
-* For buttons, start with an action-oriented verb (like “explore” or “view”).
-* For buttons, use 3 words or less (unless more words are necessary for clarity).
+- Make sure it is clear where the link or button will take the user.
+- Use sentence case, capitalizing only proper nouns.
+- For buttons, start with an action-oriented verb (like “explore” or “view”).
+- For buttons, use 3 words or less (unless more words are necessary for clarity).

packages/styleguide/src/lib/Atoms/Buttons/IconButton/IconButton.mdx

@@ -1,6 +1,6 @@
 import { Canvas, Controls, Meta } from '@storybook/blocks';
 
-import { ComponentHeader } from '~styleguide/blocks';
+import { ComponentHeader, LinkTo } from '~styleguide/blocks';
 
 import * as IconButtonStories from './IconButton.stories';
 
@@ -23,9 +23,13 @@ export const parameters = {
 <ComponentHeader {...parameters} />
 
 ## Usage
-Use for secondary or space-constrained actions with recognizable icons. Use regular icons for normal buttons and mini icons for small buttons. Icon-only buttons must include an aria-label, which will also appear in the tooltip on hover and focus.
+
+Use for secondary or space-constrained actions with recognizable icons. Use regular icons for normal buttons and mini icons for small buttons. Icon-only buttons must include a `tip` prop, which will also appear in the tooltip on hover and focus.
+
+For more detailed information on `IconButton` tooltips, take a look at the <LinkTo id='Molecules/Tips/ToolTip'>ToolTip</LinkTo> story.
 
 ## Playground
+
 <Canvas sourceState="shown" of={IconButtonStories.Default} />
 
 <Controls />

packages/styleguide/src/lib/Atoms/FormElements/About.mdx

@@ -20,45 +20,45 @@ Both of our Form organisms provide the following benefits:
 1. **Accessibility**: All our forms handle accessibility styling and behaviors, passing tests out-of-the-box.
 2. **Functionality**: Validation and submission logic is handled by the [react-hook-form](https://react-hook-form.com) library
 
-We recommend <LinkTo id='organisms-gridForm'>GridForm</LinkTo> if you have a form that sticks to a 12x12 visual grid with consistent vertical rhythm and grid spacing.
-
-For everything else, we recommend <LinkTo id='organisms-connectedForm'>ConnectedForm</LinkTo>.
+We recommend <LinkTo id='Organisms/GridForm'>GridForm</LinkTo> if you have a form that sticks to a 12x12 visual grid with consistent vertical rhythm and grid spacing.
 
+For everything else, we recommend <LinkTo id='Organisms/ConnectedForm'>ConnectedForm</LinkTo>.
 
 <TableOfContents
   links={[
     {
       id: 'Atoms/FormElements/Form',
-      subtitle: 'A customizable `<form />` element for wrapping other form elements.',
+      subtitle:
+        'A customizable `<form />` element for wrapping other form elements.',
       title: 'Form',
       status: 'current',
     },
     {
       id: 'Atoms/FormElements/FormGroup',
-      subtitle: 'A label and description wrapper for a form element that provides conditional styling.',
+      subtitle:
+        'A label and description wrapper for a form element that provides conditional styling.',
       title: 'FormGroup',
       status: 'current',
     },
     {
       id: 'Atoms/FormElements/FormGroupDescription',
-      subtitle: 'A description wrapper to format a longer description of a group of inputs.',
+      subtitle:
+        'A description wrapper to format a longer description of a group of inputs.',
       title: 'FormGroupDescription',
       status: 'current',
     },
     {
       id: 'Atoms/FormElements/FormGroupLabel',
-      subtitle: "A label element to be tied to a group of elements.",
+      subtitle: 'A label element to be tied to a group of elements.',
       title: 'FormGroupLabel',
       status: 'current',
     },
     {
       id: 'Atoms/FormElements/FormRequiredText',
-      subtitle: "A Text element that renders our required field explanation, should be included in all forms with required fields.",
+      subtitle:
+        'A Text element that renders our required field explanation, should be included in all forms with required fields.',
       title: 'FormRequiredText',
       status: 'current',
-    }
+    },
   ]}
 />
-
-
-

packages/styleguide/src/lib/Atoms/FormElements/Form/Form.mdx

@@ -5,12 +5,13 @@ import { ComponentHeader, LinkTo } from '~styleguide/blocks';
 import * as FormStories from './Form.stories';
 
 export const parameters = {
-  subtitle: 'A customizable `<form />` element for wrapping other form elements',
+  subtitle:
+    'A customizable `<form />` element for wrapping other form elements',
   status: 'current',
   source: {
     repo: 'gamut',
     githubLink:
-      'https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/Form/elements/Form.tsx'
+      'https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/Form/elements/Form.tsx',
   },
 };
 
@@ -20,14 +21,14 @@ export const parameters = {
 
 ## Usage
 
-This is `Form` atom is the base component for other forms like the organisms: <LinkTo kind='Atoms/GridForm'>GridForm</LinkTo> and <LinkTo kind='Atoms/ConnectedForm'>ConnectedForm</LinkTo>.
-
+This is `Form` atom is the base component for other forms like the organisms: <LinkTo id='Organisms/GridForm'>GridForm</LinkTo> and <LinkTo id='Organisms/ConnectedForm'>ConnectedForm</LinkTo>.
 
 ### Best practices:
-- You should not use this component directly, instead use <LinkTo kind='Atoms/GridForm'>GridForm</LinkTo> or <LinkTo kind='Atoms/ConnectedForm'>ConnectedForm</LinkTo> depending on your needs.
+
+- You should not use this component directly, instead use <LinkTo id='Organisms/GridForm'>GridForm</LinkTo> or <LinkTo id='Organisms/ConnectedForm'>ConnectedForm</LinkTo> depending on your needs.
 
 ## Playground
+
 <Canvas sourceState="shown" of={FormStories.Default} />
 
 <Controls />
-

packages/styleguide/src/lib/Atoms/FormElements/FormGroup/FormGroup.mdx

@@ -29,32 +29,43 @@ Use `FormGroup` to provide a label and description for a form element.
 It is best to provide `htmlFor` to both the FormGroup + inner form element to make it super accessible. If this is not provided, the FormLabel will default to `<div>`. If an `htmlFor` is provided, it will be a `<label>`.
 
 Below shows how adding an `htmlFor` to both the FormGroup and inner form element will make the FormLabel a `<label>`.
+
 <Canvas of={FormGroupStories.FormGroupHtmlFor} />
 
 This example below omits the `htmlFor` prop on the FormGroup and inner form element, which will make the FormLabel a `<div>`.
+
 <Canvas of={FormGroupStories.FormGroupDiv} />
 
 ### States
+
 #### Default state
+
 Here's a `FormGroup` without an error or validation:
+
 <Canvas of={FormGroupStories.DefaultState} />
 
 #### `error`
+
 When including an error message, the `FormGroup` should have an `error` prop with a string that describes the error. The inner element wrapped by the `FormGroup` should also have an `error` prop with a boolean to either display or hide the error message. The `error` prop will add a red border to the form element and display the error message below the form element.
 
 <Canvas of={FormGroupStories.Error} />
 
 #### `valid`
+
 Adding `valid` to a `FormGroup`'s inner element will add a green checkmark to the form element.
+
 <Canvas of={FormGroupStories.Valid} />
 
 ### Including InfoTip
-A field can include <LinkTo id="molecules-tips--infotip"> our existing `InfoTip`</LinkTo>
+
+A field can include <LinkTo id="Molecules/Tips/InfoTip"> our existing `InfoTip`</LinkTo>
 
 #### Low emphasis
+
 <Canvas of={FormGroupStories.LowEmphasisInfoTip} />
 
 #### High emphasis
+
 <Canvas of={FormGroupStories.HighEmphasisInfoTip} />
 
 ## Playground

packages/styleguide/src/lib/Atoms/FormElements/FormRequiredText/FormRequiredText.mdx

@@ -20,9 +20,10 @@ export const parameters = {
 
 ## Usage
 
-`FormRequiredText` should be included in all forms with required fields. Accepts all props of <LinkTo id="typography-text">our existing `Text`</LinkTo> component.
+`FormRequiredText` should be included in all forms with required fields. Accepts all props of <LinkTo id="Typography/Text">our existing `Text`</LinkTo> component.
 
 ## Playground
+
 <Canvas sourceState="shown" of={FormRequiredTextStories.Default} />
 
 <Controls />

packages/styleguide/src/lib/Foundations/Layout.mdx

@@ -113,7 +113,7 @@ This section would be 6 columns at the smallest screen size and 4 columns at any
 
 ## Spacing
 
-For spacing between components and sections use these as a guide. Each of these scales is a subset of our `spacing` sizes found on <LinkTo id="foundations-theme--spacing">our theme</LinkTo>. While you will have access to all of them in your code use these sets as a practical guide.
+For spacing between components and sections use these as a guide. Each of these scales is a subset of our `spacing` sizes found on <LinkTo id="Foundations/Theme">our theme</LinkTo>. While you will have access to all of them in your code use these sets as a practical guide.
 
 <TokenTable
   rows={[

packages/styleguide/src/lib/Layouts/Boxes/FlexBox/FlexBox.mdx

@@ -18,7 +18,7 @@ export const parameters = {
 
 <ComponentHeader {...parameters} />
 
-For flex layouts we've added a specific flex <code>FlexBox</code> component that extends <LinkTo kind="Layouts/Boxes/Box">Box</LinkTo> with extra props for common flex configurations.
+For flex layouts we've added a specific flex <code>FlexBox</code> component that extends <LinkTo id="Layouts/Boxes/Box">Box</LinkTo> with extra props for common flex configurations.
 
 ## Usage guidelines
 

packages/styleguide/src/lib/Layouts/Boxes/GridBox/GridBox.mdx

@@ -19,7 +19,7 @@ export const parameters = {
 <ComponentHeader {...parameters} />
 
 For Grid layouts we&apos;ve added a specific grid <code>GridBox</code>
-component that extends <LinkTo component="Box">Box</LinkTo> with added grid props.
+component that extends <LinkTo id="Layouts/Boxes/Box">Box</LinkTo> with added grid props.
 
 ## Four-column grid Example
 

packages/styleguide/src/lib/Molecules/AccordionButtonDeprecated/AccordionButtonDeprecated.mdx

@@ -1,6 +1,6 @@
 import { Canvas, Controls, Meta } from '@storybook/blocks';
 
-import { ComponentHeader, LinkTo } from '~styleguide/blocks';
+import { Callout, ComponentHeader } from '~styleguide/blocks';
 
 import * as AccordionButtonDeprecatedStories from './AccordionButtonDeprecated.stories';
 
@@ -10,20 +10,23 @@ Comes in a few standard size and color combinations.`,
   status: 'deprecated',
   source: {
     repo: 'gamut',
-    githubLink: 'https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/AccordionButtonDeprecated/index.tsx'
+    githubLink:
+      'https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/AccordionButtonDeprecated/index.tsx',
   },
 };
 
 <Meta of={AccordionButtonDeprecatedStories} />
 
 <ComponentHeader {...parameters} />
 
+<Callout text="This component is deprecated. For similar functionality, consider using the Disclosure component." />
+
 ## Usage
-**Note**: This component is deprecated. For similar functionality, consider using <LinkTo id="molecules-disclosure" >Disclosure</LinkTo> or a <LinkTo id="organisms-disclosure">List</LinkTo> component.
 
 Use AccordionButtonDeprecated in conjunction with the AccordionDeprecated component to create an accordion-style interface.
 
 ### Best practices:
+
 - Avoid unless necessary for legacy pages that rely on this component. Check with a designer to ensure that styling is consistent or if it could be upgraded to use an updated component.
 
 ## Variants
@@ -51,4 +54,3 @@ Yellow AccordionButtonDeprecated tops are used in the "Get a Hint" sections of t
 <Canvas sourceState="shown" of={AccordionButtonDeprecatedStories.Blue} />
 
 <Controls />
-

packages/styleguide/src/lib/Molecules/AccordionDeprecated/AccordionDeprecated.mdx

@@ -1,6 +1,6 @@
 import { Canvas, Controls, Meta } from '@storybook/blocks';
 
-import { ComponentHeader, LinkTo } from '~styleguide/blocks';
+import { Callout, ComponentHeader } from '~styleguide/blocks';
 
 import * as AccordionDeprecatedStories from './AccordionDeprecated.stories';
 
@@ -10,25 +10,29 @@ such as a "hint" section in the LE or a list of department jobs on a careers pag
   status: 'deprecated',
   source: {
     repo: 'gamut',
-    githubLink: 'https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/AccordionDeprecated/index.tsx'
+    githubLink:
+      'https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/AccordionDeprecated/index.tsx',
   },
 };
 
 <Meta of={AccordionDeprecatedStories} />
 
 <ComponentHeader {...parameters} />
 
+<Callout text="Note: This component is deprecated. For similar functionality, consider using Disclosure or a List component." />
+
 ## Usage
-**Note**: This component is deprecated. For similar functionality, consider using <LinkTo id="molecules-disclosure" >Disclosure</LinkTo> or a <LinkTo id="organisms-disclosure">List</LinkTo> component.
 
 Use in conjunction with the AccordionButtonDeprecated component to create an accordion-style interface.
 
 This Accordion component will fit to `100%` of the the height of their parent container. If you need a fixed height container, wrap the accordion in a `<div>`.
 
 ### Best practices:
+
 - Avoid unless necessary for legacy pages that rely on this component. Check with a designer to ensure that styling is consistent or if it could be upgraded to use an updated component.
 
 ### When NOT to use:
+
 - [Having a button that reveals additional information]- for creating a single "Accordion", similar to an HTML [details](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details) element, use the Disclosure component instead.
 - Creating a "Accordion" with many rows — akin to an FAQ that lists out questions and reveals an answer when clicked, use the List component with expandable rows.
 
@@ -40,10 +44,8 @@ If you'd like a "controlled" component equivalent, you can manually use the `Acc
 
 Most accordions should use an `AccordionButtonDeprecated`; other forms of buttons are acceptable for custom accordions.
 
-
 <Canvas of={AccordionDeprecatedStories.AccordionAreaDeprecatedExample} />
 
-
 ## Playground
 
 <Canvas sourceState="shown" of={AccordionDeprecatedStories.Default} />