docs: move EDS markdown fully into storybook (#1610)

- remove markdown files (.md)
- move to MDX files (equivalent but allows for JSX)
- remove legacy documentation
- apply storybook structure
- simplify README.md and rely on linking to Storybook
- redo doc.s ordering to put people on "Getting Started" first
- remove markdown wrapper and prism vendor lib

.eslintrc

@@ -111,5 +111,5 @@
       }
     }
   ],
-  "ignorePatterns": ["!.storybook", ".storybook/components/Docs/prism.js"]
+  "ignorePatterns": ["!.storybook"]
 }

.gitignore

@@ -31,7 +31,6 @@ yarn-error.log*
 
 /.vscode
 *.css.map
-!prism.css
 !DesignTokens.css
 !Utilities.css
 

.prettierignore

@@ -6,4 +6,3 @@ lib
 .prettierignore
 *.svg
 *.png
-prism.js

docs/GETTING_STARTED.md → .storybook/components/Docs/GettingStarted.stories.mdx

@@ -1,3 +1,5 @@
+<Meta title="Getting Started" />
+
 # Welcome to EDS
 
 EDS is a design system that provides foundations to create a consistent, accessible web experience across products.
@@ -12,11 +14,11 @@ EDS' components follow the [Atomic Design](https://bradfrost.com/blog/post/atomi
 
 The navigation consists of:
 
-- **Design Tokens** are the reusable CSS variables that can be themed in your application. They are grouped into tiers which describe the specificity of the tokens (with tier one values corresponding to basic definitions, and tier two corresponing to use cases referencing the tier one values, etc.)
 - **Documentation** are a collection of guidelines and explanations for all the written content on this site.
+- **Design Tokens** are the reusable CSS variables that can be themed in your application. They are grouped into tiers which describe the specificity of the tokens (with tier one values corresponding to basic definitions, and tier two corresponing to use cases referencing the tier one values, etc.)
 - **Components** are all the exported offerings of EDS, combined in one list. They consist of various atoms, molecules, and organisms that can be used in a product, along with relevant documentation, controls, and <kbd>tags</kbd> (describing the component type and status)
-- **Recipes** are product-specific compositions that use the design system components to structure, but are not shipped with the system. This is to allow for teams to meet their business needs without polluting or complicating the reusable component structure and styling. Read [Brad Frost's post on recipes](https://bradfrost.com/blog/post/design-system-components-recipes-and-snowflakes/) and [our internal documentation on how we use recipes in EDS](/?path=/docs/documentation-recipes--recipes).
 - **Pages** are UI prototypes that use the components and recipes to structure the majority of real product pages that will use these. While these are not shipped with the system, the layout using components and recipes can be copied over into the product to represent the majority of the UI.
+- **Recipes** are product-specific compositions that use the design system components to structure, but are not shipped with the system. This is to allow for teams to meet their business needs without polluting or complicating the reusable component structure and styling. Read [Brad Frost's post on recipes](https://bradfrost.com/blog/post/design-system-components-recipes-and-snowflakes/) and [our internal documentation on how we use recipes in EDS](/?path=/docs/documentation-recipes--recipes).
 
 ### Storybook Features
 

docs/CODE_GUIDELINES.md → .storybook/components/Docs/Guildelines/CodeGuidelines.stories.mdx

@@ -1,6 +1,8 @@
+<Meta title="Documentation/Guidelines/Code Guidelines" />
+
 # Code Guidelines
 
-EDS follows these principles and conventions for HTML, CSS, and JavaScript/TypeScript/React:
+EDS component code follows these principles and conventions for HTML, CSS, and JavaScript/TypeScript/React:
 
 - [HTML](#html)
 - [CSS](#css)
@@ -50,7 +52,7 @@ EDS follows these principles and conventions for HTML, CSS, and JavaScript/TypeS
 
 ### BEM syntax
 
-EDS follows [BEM](http://getbem.com/introduction/) syntax for component classnames. BEM stands for “Block Element Modifier”. Here's a breakdown of what that means:
+EDS follows [BEM](http://getbem.com/introduction/) syntax for component class names. BEM stands for “Block Element Modifier”. Here's a breakdown of what that means:
 
 - **Block** is the primary component block (e.g. `.button`)
 - **Element** is a child of the primary block (e.g. `.button__text`)
@@ -94,7 +96,7 @@ EDS uses [PostCSS Nested](https://github.com/postcss/postcss-nested) to provide
 
 #### Media queries
 
-```scss
+```css
 .primary-nav {
   /**
     * On larger displays, convert to a horizontal list
@@ -111,7 +113,7 @@ We use focus-visible for most focus states. This ensures that the focus state wi
 
 However, we currently support some browser versions that do not support the focus-visible CSS feature, so we also use a fallback block in conjunciton with focus-visible.
 
-```scss
+```css
 .button--primary {
   &:focus-visible {
     @mixin focus;
@@ -127,7 +129,7 @@ However, we currently support some browser versions that do not support the focu
 
 #### States and pseudo-selectors
 
-```scss
+```css
 .button--primary {
   background: var(--eds-theme-color-background-brand-primary-strong);
 
@@ -149,7 +151,7 @@ Use [parent selectors](https://sass-lang.com/documentation/style-rules/parent-se
 
 Use the following conventions:
 
-```scss
+```css
 .button {
   /* button code */
 }
@@ -181,7 +183,7 @@ There are some disabilities (ex: vestibular disorders) that cause users to becom
 
 Examples:
 
-```scss
+```css
 .dropdown-button__icon {
   transition: transform var(--eds-anim-move-medium) var(--eds-anim-ease);
 
@@ -265,7 +267,7 @@ Instead of:
 
 Use:
 
-```scss
+```css
 .primary-nav {
   flex-direction: column;
 
@@ -309,7 +311,7 @@ This is a "lightly" themed system, meaning that only a few variables (such as ke
 
 ### Design Tokens <a name="design-tokens"></a>
 
-Please refer to the [design tokens documentation](./TOKENS.md) to learn how to use design tokens in EDS.
+Please refer to the [design tokens documentation](./?path=/story/documentation-guidelines-tokens--page) to learn how to use design tokens in EDS.
 
 ---
 
@@ -545,6 +547,7 @@ By default, we err towards more centralized control over the component architect
 - Compound components should be re-exported from their parent component file for easier usage. For example, at the bottom of `Card.tsx`, add the lines:
 
 ```tsx
+// This demonstrates how bound subcomponents are attached
 Card.Header = CardHeader;
 Card.Footer = CardFooter;
 ```

docs/COMPONENTS.md → .storybook/components/Docs/Guildelines/Components.stories.mdx

@@ -1,3 +1,5 @@
+<Meta title="Documentation/Guidelines/Components" />
+
 # Working with EDS Components, Pages, and Recipes
 
 This codebase contains all the components, [recipes](https://bradfrost.com/blog/post/design-system-components-recipes-and-snowflakes/), and pages to successfully build the presentation view of product screens.
@@ -16,7 +18,7 @@ The top-level organization you can find in storybook is as follows:
 
 Using EDS components in your React application involves first installing the EDS package as a dependency:
 
-```sh
+```bash
 npm install @chanzuckerberg/eds
 # or
 yarn add @chanzuckerberg/eds
@@ -50,7 +52,7 @@ If you have questions or are experiencing any issues when working with EDS's com
 
 1. To create a component, run `yarn plop` in the command line.
 2. The command will ask, "What is your component name?" Add your component name (you can either type `PageHeader` or `page header` and it will automatically generate the proper casing).
-3. Edit component source code in accordance with [EDS's code guidelines](./CODE_GUIDELINES.md)
+3. Edit component source code in accordance with [EDS's code guidelines][code-guidelines]
 4. Create relevant stories for all component variants
 
 ### Component Beta status
@@ -107,7 +109,7 @@ Pages
 
 ## Working with recipes
 
-**[Recipes](https://bradfrost.com/blog/post/design-system-components-recipes-and-snowflakes/)** are mainly compositions of design system components that are to be consistently used across products, but aren’t agnostic enough to live in core component library. Like pages, recipes live in the `.storybook` directory of the project since they are not packaged up with the design system. Recipes should follow EDS [code conventions](./CODE_GUIDELINES.md) as closely as possible in order to make future use across projects as easy as possible.
+**[Recipes](https://bradfrost.com/blog/post/design-system-components-recipes-and-snowflakes/)** are mainly compositions of design system components that are to be consistently used across products, but aren’t agnostic enough to live in core component library. Like pages, recipes live in the `.storybook` directory of the project since they are not packaged up with the design system. Recipes should follow EDS [code conventions][code-guidelines] as closely as possible in order to make future use across projects as easy as possible.
 
 ### Using recipes
 
@@ -166,3 +168,5 @@ Recipes
 --Recipe Name
 ----Recipe Stories
 ```
+
+[code-guidelines]: ./?path=/story/documentation-guidelines-code-guidelines--page

docs/ICONS.md → .storybook/components/Docs/Guildelines/Icons.stories.mdx

@@ -1,3 +1,5 @@
+<Meta title="Documentation/Guidelines/Icons" />
+
 # Icons
 
 EDS provides utilitarian UI icons (e.g. magnifying glass, menu, triangles, carets, and so on). "Branded" or content-specific icons are not provided by EDS.
@@ -22,8 +24,12 @@ View the "Icon Grid" story in Storybook for a visualization of all available ico
 2. If necessary, remove the `fill` attribute on the `<path>` in the exported SVG file(s). In the very rare case that an icon needs colors defined in the icon (like the `status-` icons), only use tier 2 or tier 3 CSS variables for the color.
 3. In a new feature branch, locate `src/icons/spritemap` and add new icon contents (everything but the `<svg>` element) to the object.
 4. In Storybook, view the "Icon Grid" component to see the new component added to the available list of icons, which is now ready to use in EDS components.
-5. Submit PR in accordance with [workflow guidelines](./WORKFLOW.md) and release in order to make icon available to consuming applications
+5. Submit PR to [edu-design-system](https://github.com/chanzuckerberg/edu-design-system)
+
+For more information on contributing to EDS, please review our [contribution guidelines][contributing].
 
 ### Modifiying icons
 
-Modiying icons involves the same steps as adding an icon, only overriding an existing SVG icon definition with the new one. However, releasing modified icons needs to be handled with care as certain icon changes aren't particularly noticeable while others may constitute a breaking change to the library. Refer to the [EDS release guidelines](./WORKFLOW.md) to determine how best to roll out icon updates.
+Modifying icons involves the same steps as adding an icon, only overriding an existing SVG icon definition with the new one. However, releasing modified icons needs to be handled with care as certain icon changes aren't particularly noticeable while others may constitute a breaking change to the library. Refer to the [EDS contributing guidelines][contributing] to determine how best to roll out icon updates.
+
+[contributing]: https://github.com/chanzuckerberg/edu-design-system/blob/main/docs/CONTRIBUTING.md

docs/LAYOUT.md → .storybook/components/Docs/Guildelines/Layout.stories.mdx

@@ -1,3 +1,5 @@
+<Meta title="Documentation/Guidelines/Layout" />
+
 # Layout
 
 EDS provides several layout-specific components to accomplish specific design outcomes.

docs/THEMING.md → .storybook/components/Docs/Guildelines/Theming.stories.mdx

@@ -1,3 +1,5 @@
+<Meta title="Documentation/Theming" />
+
 # Theming overview
 
 "Theming", in the context of EDS, is the process of overriding the default styles of EDS components to match a different brand (or "theme"). The "Theming" directory in storybook demonstrates two examples of theming — a [wireframe theme](./?path=/story/pages-theming-wireframedemo--default) (an unbranded theme that can be used for prototyping a product before it has an official visual style) and an [along theme](./?path=/story/pages-theming-alongdemo--default) that replicates the visual style of the [Along product](https://app.along.org/).

docs/TOKENS.md → .storybook/components/Docs/Guildelines/Tokens.stories.mdx

@@ -1,3 +1,5 @@
+<Meta title="Documentation/Guidelines/Tokens" />
+
 # Design Tokens
 
 EDS is a [themeable design system](https://bradfrost.com/blog/post/creating-themeable-design-systems/) in order to support different brands, design language generations, and product families. [Design tokens](https://css-tricks.com/what-are-design-tokens/) are a core part of building a EDS theme. Design tokens define low-level design values and apply those values to UI applications in order to manage the brand's look and feel separately from structural component styles.
@@ -57,7 +59,7 @@ Tier 1 tokens define the brand’s design values. They can be thought of as a br
 
 ### Borders <a name="tier-1-borders"></a>
 
-- `border-width-` for border widths. Typically default to abbreviated t-shirt sizes (e.g. `sm`, `md`, `lg`, `xl`) in accordance with the [EDS code guidelines](./CODE_GUIDELINES.md).
+- `border-width-` for border widths. Typically default to abbreviated t-shirt sizes (e.g. `sm`, `md`, `lg`, `xl`) in accordance with the [EDS code guidelines](./?path=/story/documentation-guidelines-code-guidelines--page).
 - `border-radius-` for border radius values. Typically default to t-shirt sizes, although sometimes "pill" or "round" might also be present
 
 ### Breakpoints <a name="tier-1-breakpoints"></a>

docs/TYPOGRAPHY.md → .storybook/components/Docs/Guildelines/Typography.stories.mdx

@@ -1,6 +1,8 @@
+<Meta title="Documentation/Guidelines/Typography" />
+
 # Typography
 
-Typography in EDS follows [the same structure as design tokens](./TOKENS.md), with the exception that typography operates as a _cluster_ of typography-specific style properties rather than a single style property.
+Typography in EDS follows [the same structure as design tokens](./?path=/story/documentation-guidelines-tokens--page), with the exception that typography operates as a _cluster_ of typography-specific style properties rather than a single style property.
 
 ## Tier 1: Typography values