typography + meta

.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/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/preview.ts

@@ -7,13 +7,20 @@ 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', 'Foundations', 'Layouts', 'Typography', 'Atoms', '*'],
+      },
     },
     viewport: {
       defaultViewport: 'responsive',

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

@@ -0,0 +1,39 @@
+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/BestPractices',
+      subtitle: 'Current best practices for using the Gamut Design System',
+      title: 'Best Practices',
+    },
+    {
+      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/FAQ',
+      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',
+    },
+  ]}
+/>

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

@@ -0,0 +1,16 @@
+import { Meta } from '@storybook/blocks';
+
+import { AboutHeader } from '~styleguide/blocks';
+
+export const parameters = {
+  id: 'Brand',
+  title: 'Brand',
+  subtitle: `Codecademy internal and branded components`,
+  status: 'static',
+};
+
+<Meta title="Meta/Brand" />
+
+<AboutHeader {...parameters} />
+
+The [Brand Library](https://brand-storybook.codecademy.com/) is a subset of assets, components, and themes intended for branded experiences and internal use. If you have any questions about Brand, feel free to reach out at #gamut-team on Slack.

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

@@ -0,0 +1,93 @@
+import { Meta } from '@storybook/blocks';
+
+import { AboutHeader, LinkTo } from '~styleguide/blocks';
+
+export const parameters = {
+  id: 'Contributing',
+  title: 'Contributing',
+  subtitle: `Thanks so much for being interested in contributing to Gamut!
+We love working with Codecademy employees across all our teams.`,
+  status: 'static',
+};
+
+<Meta title="Meta/Contributing" />
+
+<AboutHeader {...parameters} />
+
+## Prework
+
+We track planned work for Gamut components in the [Gamut Board](https://codecademy.atlassian.net/jira/software/projects/WEB/boards/1386) on JIRA.
+
+- If there's a ticket there you want to take on, send a Slack to #gamut-team or come to Gamut Office hours and lets talk about it!
+- If the work you'd like to do isn't captured in a JIRA ticket, talk to us and we can work with you to create that ticket.
+- If you would like to make a request for work to be done, please discuss with us on Slack or during Gamut Office Hours.
+- If you'd like to pitch a change to the design system, please attend Gamut Crit, come to Gamut Office Hours, or send a Slack message to #gamut-team.
+
+## Writing components
+
+### Component structure
+
+Create your component as an `index.tsx` file in a PascalCase-named folder within its package directory, such as `packages/gamut/src/ProgressBar/index.tsx`.
+Consider saving this recommended format as an editor snippet:
+
+```tsx
+import React from 'react';
+
+export type MyComponentProps = {
+  /* ... */
+};
+
+export const MyComponent: React.FC<MyComponentProps> = (
+  {
+    /* ... */
+  }
+) => {
+  // ...
+};
+```
+
+#### Props documentation
+
+With the exception of widespread, self-documenting props such as `onClick`, please include a sentence cased description of the prop's intent.
+React props on the component will be picked up by Storybook and added to the component's documentation story.
+We prefer these be full sentences.
+
+```ts
+/**
+ * Number of lines to limit the message to.
+ */
+limit: number;
+```
+
+- If your comment purely restartes the name and type of variable, please either elaborate on it or remove the comment altogether.
+- Consider starting comments for booleans with _"Whether "_.
+
+### Unit tests
+
+Your component should have unit tests in a `__tests__/MyComponent-test.tsx` file within its directory.
+Use Enzyme's `mount` to test it.
+
+We generally try to unit test all component logic, with the exception of class names in components that contain other logic.
+
+### Stories
+
+All components must have Storybook stories showing their use. See <LinkTo id='Meta/Stories'>Stories</LinkTo> for documentation.
+
+## Pull requests
+
+Please fill out the pull request template, including links to the corresponding Abstract design and JIRA ticket.
+
+> 😉 Protip: You can use a [Draft PR](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests#draft-pull-requests) to still run CI jobs.
+> That includes deploying a Netlify preview and publishing alpha package versions to npm.
+
+### Publishing updates
+
+If you know your PR has breaking changes in at least one downstream repository:
+
+1. Before merging it, create PRs in those downstream repositories using your PR's published alpha package versions
+2. Verify those PRs work as expected and get them signed off normally
+3. Merge your Gamut PR
+4. Wait until the new Gamut package is published, then update the downstream repository PRs to use it
+5. Merge and deploy those PRs as soon as possible
+
+If your PR contains breaking changes that might affect other users, please mention them in the `#frontend` Slack channel.