typography + meta (#2975)

* create foundations + layout stories

* start foundations

* start retooling componentheader

* component header tweak

* start restructure of header components

* TOC + Theme working, need DataTable + code background color

* working on color mode - need to fix text color

* revert test

* Theme page sorted, need to fix ColorMode

* colormode sorted

* colormode sorted

* start type fix + what to do about blocks

* LayoutGrid + content Container

* LayoutGrid done

* start flexbox, need to look into sandbox stuff

* gridbox + flexbox are good, just need to tweak

* tweaks to headers

* lots of style tweaks + deduplications

* fix typograpth, need to fix color mode switches

* start on system stories

* unify shared elements

* add variance + fix tables

* more tweaks to status

* design tweaks

* add hub

* more tweaks

* rename DataTable

* clean up of default

* typography + meta stories

* add anchor story

* start text + hiddentext

* text done

* started snippet changes

* fixed code snippets

* meta and sorted done?"

* renamed + sorting

* more kenny edits

* more kenny edits + other new tab for links

* the last of it

.vscode/stories.code-snippets

@@ -1,86 +1,137 @@
 {
-  "Component Story": {
-    "prefix": "component-story",
+  "Component Doc": {
+    "prefix": "component-doc",
     "body": [
-      "import { $1 } from '@codecademy/$2';",
-      "import title from '@codecademy/macros/lib/title.macro';",
-      "import { Canvas, Meta, Story } from '@storybook/addon-docs/blocks';",
-      "import { PropsTable } from '@codecademy/storybook-addon-variance';",
+      "import { Canvas, Controls, Meta } from '@storybook/blocks';",
+      "",
+      "import { ComponentHeader } from '~styleguide/blocks';",
+      "",
+      "import * as $1Stories from './$1.stories';",
+      "",
+      "export const parameters = {",
+      "subtitle: `Template component`,",
+      "design: {",
+      "type: 'figma',",
+      "url: 'https: //www.figma.com/file/XXX',",
+      " },",
+      "status: 'current',",
+      "source: {",
+      "repo: '$2',",
+      "// this is easy to find by right clicking on the file in VSCode and clicking 'Copy Remote File Url From...' and the selecting 'main' or amending the url path below like so: https://github.com/Codecademy/gamut/blob/main/packages/${2}/src/file/location",
+      "githubLink:",
+      "'https: //github.com/Codecademy/gamut/blob/main/packages/gamut/src/Logo',",
+      " },",
+      "};",
+      "<Meta of={$1Stories}/>",
+      "",
+      "<ComponentHeader {...parameters} />",
+      "",
+      "## Usage",
+      "",
+      "Use $1 to [what it should be used for]",
+      "",
+      "### Best practices:",
+      "",
+      "- [recommendation / best practice for implementation]",
+      "- [recommendation / best practice for implementation]",
+      "",
+      "When NOT to use",
+      "",
+      "- [use case]- for [describe the use case], use the [similar component] component.",
+      "- [use case]- for [describe the use case], use the [similar component] component",
+      "",
+      "## Anatomy",
+      "",
+      "[Insert image exported from Figma]",
+      "",
+      "1. [Element name]",
+      "- [description including available options and ux writing if relevant]",
       "",
-      "<Meta",
-      "  title={title}",
-      "  component={$1}",
-      "  parameters={{",
-      "    subtitle: '$3',",
-      "    source: '$2',",
-      "    status: 'current' | 'updating' | 'deprecated' | 'static'$4 ,",
-      "    design: {",
-      "      type: 'figma',",
-      "      url: 'https://www.figma.com/file/$5',",
-      "    }",
-      "  }}",
-      "  args={{}}",
-      "/>",
+      "## Variants",
       "",
-      "`$1` component summary goes here",
+      "### [Variant 1 name]",
       "",
-      "## Design Principles",
+      "Use the [variant 1 name] to [what it should be used for]",
       "",
-      "Design Principles summary",
+      "<Canvas of={$1Stories.Default} />",
       "",
-      "## Usage Guidelines",
+      "## Playground",
       "",
-      "Usage summary",
+      "If you are using a story named 'Default', you can forgo the `of` prop.",
       "",
-      "## Code Playground",
+      "<Canvas sourceState='shown' of={$1Stories.Default} />",
       "",
-      "<Canvas>",
-      "  <Story name=\"$1\">",
-      "    {(args) => <$1 {...args} />}",
-      "  </Story>",
-      "</Canvas>",
+      "<Controls />",
       "",
-      "<PropsTable story=\"$1\"/>"
+      "## Accessibility considerations",
+      "",
+      "- [Accessibility guidance]",
+      "",
+      "## UX writing",
+      "",
+      "- [content]",
+      " - [guidance]",
+      " - [guidance]"
     ],
-    "description": "Default Component Story Structure."
+    "description": "Default Component Doc Structure."
   },
   "Table of Contents Story": {
     "prefix": "toc-story",
     "body": [
-      "import title from '@codecademy/macros/lib/title.macro';",
-      "import { Meta } from '@storybook/addon-docs/blocks';",
+      "import { Meta } from '@storybook/blocks';",
+      "import { AboutHeader, TableOfContents } from '~styleguide/blocks';",
+      "",
+      "export const parameters = {",
+      "  id: '$1',",
+      "  title: '$1/About',",
+      "  subtitle: '$2',",
+      "  }",
       "",
-      "import { TableOfContents } from '~styleguide/blocks';",
+      "<Meta title='$1/About' />",
       "",
-      "<Meta",
-      "  title={title}",
-      "  parameters={{",
-      "    subtitle: '$3',",
-      "  }}",
-      "/>",
+      "<AboutHeader {...parameters} />",
       "",
-      "<TableOfContents />"
+      "Foundations make up the smallest scale design values that comprise a design system. Sometimes referred to elsewhere as "tokens", they are the abstract units that comprise and stitch together our atoms, molecules, and organisms.",
+      "",
+      "<TableOfContents",
+      " links={[",
+      "   {",
+      "     id: '$1/Category',",
+      "     subtitle: 'Short description',",
+      "     title: 'Category',",
+      "   }",
+      " ]}",
+      "/>"
     ],
     "description": "TOC Story Structure."
   },
-  "Canvas Block": {
-    "prefix": "canvas-block",
-    "body": [
-      "<Canvas>",
-      "  <Story name=\"$1\" args={{}}>",
-      "    {(args) => <$2 {...args} />}",
-      "  </Story>",
-      "</Canvas>"
-    ],
-    "description": "A single story block wrapped in a canvas"
-  },
-  "Story Block": {
-    "prefix": "story-block",
+  "Component Story": {
+    "prefix": "component-story",
     "body": [
-      "  <Story name=\"$1\" args={{}}>",
-      "    {(args) => <$2 {...args} />}",
-      "  </Story>"
+      "import { $1 } from '@codecademy/gamut';",
+      "import type { Meta, StoryObj } from '@storybook/react';",
+      "",
+      "const meta: Meta<typeof $1> = {",
+      " component: $1,",
+      " args: {},",
+      "};",
+      "",
+      "export default meta;",
+      "type Story = StoryObj<typeof $1>;",
+      "",
+      "export const Default: Story = {",
+      " args: {",
+      "   children: 'Test'",
+      " },",
+      "};",
+      "",
+      "export const Secondary: Story = {",
+      " args: {",
+      "   children: 'Test again',",
+      "   variant: 'secondary'",
+      " }",
+      "};"
     ],
-    "description": "A single story block without a canvas"
+    "description": "Default TSX story structure."
   }
 }

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

@@ -0,0 +1,9 @@
+import { Alert } from '@codecademy/gamut';
+
+export const Callout: React.FC<{ text: string }> = ({ text }) => {
+  return (
+    <Alert type="subtle" placement="inline">
+      {text}
+    </Alert>
+  );
+};

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

@@ -24,7 +24,9 @@ export const Link: React.FC<LinkProps> = ({ ref, id, variant, ...props }) => {
   if (variant === 'area') {
     return <Anchor {...props} onClick={onClick} variant="interface" />;
   }
-  return <Anchor {...props} onClick={onClick} variant={variant} />;
+  return (
+    <Anchor {...props} onClick={onClick} target="_blank" variant={variant} />
+  );
 };
 
 export const LinkTo = Link;

packages/styleguide/.storybook/components/Headers/ComponentHeader.tsx

@@ -5,7 +5,6 @@ import {
   InfoTip,
   Text,
 } from '@codecademy/gamut';
-import { Background } from '@codecademy/gamut-styles';
 import { Figma } from '@storybook/addon-designs/blocks';
 import { Title } from '@storybook/blocks';
 import * as React from 'react';

packages/styleguide/.storybook/components/index.tsx

@@ -1,6 +1,7 @@
 export * from './ImageWrapper';
 export * from './TokenTable';
 export * from './Headers';
+export * from './Elements/Callout';
 export * from './Elements/Markdown';
 export * from './Scales/ColorScale';
 export * from './Navigation/TableOfContents';

packages/styleguide/.storybook/preview.ts

@@ -7,13 +7,28 @@ import { DocsContainer } from './components/Elements/DocsContainer';
 
 const preview: Preview = {
   parameters: {
+    backgrounds: {
+      disable: true,
+    },
     docs: {
       container: DocsContainer,
       theme: theme,
       toc: { headingSelector: 'h1, h2, h3' },
     },
-    backgrounds: {
-      disable: true,
+    options: {
+      storySort: {
+        method: 'configure',
+        includeNames: true,
+        order: [
+          'Meta',
+          ['About', 'Best Practices', 'Contributing', 'FAQs', 'Stories'],
+          'Foundations',
+          'Layouts',
+          'Typography',
+          'Atoms',
+          '*',
+        ],
+      },
     },
     viewport: {
       defaultViewport: 'responsive',

packages/styleguide/src/lib/Layouts/About.mdx

@@ -9,7 +9,7 @@ export const parameters = {
     'Layouts are basic building blocks to help you construct layouts on the page via configuration',
 };
 
-<Meta title="Layouts" />
+<Meta title="Layouts/About" />
 
 <AboutHeader {...parameters} />
 
@@ -21,6 +21,7 @@ Pure sizing and padding containers. These position our elements on pages in stan
       id: 'Layouts/Boxes/About',
       subtitle: 'Flexible container component with all system props available.',
       title: 'Boxes',
+      status: 'current',
     },
     {
       id: 'Layouts/ContentContainer',
@@ -35,5 +36,6 @@ Pure sizing and padding containers. These position our elements on pages in stan
       status: 'current',
       title: 'LayoutGrid',
     },
-  ]}
+
+]}
 />

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

@@ -0,0 +1,40 @@
+import { Meta } from '@storybook/blocks';
+
+import { AboutHeader, TableOfContents } from '~styleguide/blocks';
+
+export const parameters = {
+  id: 'Meta',
+  title: 'Meta',
+  subtitle:
+    'Documentation and associated links explaining our in-progress approach to a design system.',
+};
+
+<Meta title="Meta/About" />
+
+<AboutHeader {...parameters} />
+
+<TableOfContents
+  links={[
+    {
+      id: 'Meta/Best Practices',
+      subtitle: 'Current best practices for using the Gamut Design System',
+      title: 'Best Practices',
+      status: 'current',
+    },
+    {
+      id: 'Meta/Contributing',
+      subtitle: `Thanks so much for being interested in contributing to Gamut! We love working with Codecademy employees across all our teams.`,
+      title: 'Contributing',
+    },
+    {
+      id: 'Meta/FAQs',
+      subtitle: `Please let us know if there are questions you'd like answered here!`,
+      title: 'FAQ',
+    },
+    {
+      id: 'Meta/Stories',
+      subtitle: `We're still building these opinions out, so don't expect all stories to adhere just yet!`,
+      title: 'Stories',
+    },
+  ]}
+/>