Add CSS documentation, deprecated section to components (#551)

* testing out a css component layout

* added css component layout

* fixed embed width

* fixed margin

* swapped Storybook example to default

* fixed tabs and added css ids and docs

* added box overlay and other docs

* fix linting error

* add box overlay example

* fixed merge conflict issues

content/components/branch-name.mdx

@@ -2,6 +2,7 @@
 title: Branch name
 description: Branch name is a label-type component rendered as an <a> tag by default that displays the name of a branch.
 reactId: branch_name
+cssId: branchname
 figmaId: branch_name
 ---
 

content/components/button.mdx

@@ -7,6 +7,7 @@ railsIds:
 - Primer::ButtonComponent
 figmaId: button
 rails: https://primer.style/view-components/components/beta/button
+cssId: button
 ---
 
 import {Box, Text} from '@primer/react'

content/components/header.mdx

@@ -3,6 +3,7 @@ title: Header
 description: Header is a navigation bar that has all of its items aligned vertically with consistent horizontal spacing.
 componentId: header
 reactId: header
+cssId: header
 ---
 
 import ComponentLayout from '~/src/layouts/component-layout'

content/components/label.mdx

@@ -4,6 +4,7 @@ description: Use the label component to add contextual metadata to a design.
 reactId: label
 railsIds:
 - Primer::Beta::Label
+cssId: issuelabel
 ---
 
 import ComponentLayout from '~/src/layouts/component-layout'

content/components/markdown.mdx

@@ -3,6 +3,7 @@ title: Markdown
 description: Use markdown to wrap markdown content.
 railsIds:
 - Primer::Beta::Markdown
+cssId: markdown
 ---
 
 import ComponentLayout from '~/src/layouts/component-layout'

content/components/pagination.mdx

@@ -4,6 +4,7 @@ description: Pagination is a horizontal set of links to navigate paginated conte
 reactId: pagination
 componentId: pagination
 figma: https://www.figma.com/file/GCvY3Qv8czRgZgvl1dG6lp/Primer-Web?node-id=20366-71286&t=kKGC85STU5bcL0zg-4
+cssId: pagination
 ---
 
 import ComponentLayout from '~/src/layouts/component-layout'

content/components/subnav.mdx

@@ -2,6 +2,7 @@
 title: Sub nav
 description: Use the sub nav component for navigation on a dashboard-type interface with another set of navigation components above it.
 reactId: sub_nav
+cssId: subnav
 ---
 
 import ComponentLayout from '~/src/layouts/component-layout'

content/components/toast.mdx

@@ -0,0 +1,42 @@
+---
+title: Toast
+description: Toasts are used to show live, time-sensitive feedback to users.
+cssId: toast
+---
+
+import ComponentLayout from '~/src/layouts/component-layout'
+import {Link, Text} from '@primer/react'
+import {Link as GatsbyLink} from 'gatsby'
+export default ComponentLayout
+
+## Usage
+
+Toasts are used to provide relevant feedback to the user, typically after they've taken an action. Primer includes styles for success, warning, error, loading, and default toasts. Some examples include:
+
+- Confirmation that an action was successfully taken
+- Communicating that an action is pending
+- Notifying the user if an action failed to complete
+- Providing general information
+
+Toasts are best used in context of the page they're referring to (rather than a global notification that can appear on any page) and should require minimal user interaction. Toasts are best used to display time-sensitive information. For global notices and messaging, see the [flash component](/components/flash).
+
+Toasts should be brief and not bog down the experience with superfluous copy. If multiple toasts appear on the page, they will stack naturally.
+
+<DoDontContainer>
+  <Do>
+    <img src="https://user-images.githubusercontent.com/586552/63106528-06de5100-bf51-11e9-8a5e-98583ed74874.png" />
+    <Caption>Use brief and direct communication.</Caption>
+  </Do>
+  <Dont>
+    <img src="https://user-images.githubusercontent.com/586552/63106527-06de5100-bf51-11e9-858c-72de6a5c728a.png" />
+    <Caption>Don't use wordy and redundant copy, and avoid exceeding 140 characters.</Caption>
+  </Dont>
+</DoDontContainer>
+
+## Accessibility
+
+Toasts are non-modal components and should contain `role=log`, which implies the element has `aria-live="polite"`. This notifies the user of the toast via Assistance Technologies without having to change focus to the toast. You can read more about `role=log` at [W3: Using `role=log` to identify sequential information updates](https://www.w3.org/WAI/WCAG21/Techniques/aria/ARIA23).
+
+Toasts are generally informative and should not receive focus when they appear. For that reason, we suggest you **avoid using interactive elements** in the component (aside from a dismiss action). Keep in mind that, even without an explicit dismiss action, the user can always hit `esc` to dismiss the toast. For more information on how interactive children affect web accessibility, [check out this issue](https://github.com/jackbsteinberg/std-toast/issues/29).
+
+

content/components/tooltip.mdx

@@ -5,6 +5,7 @@ reactId: tooltip
 railsIds:
 - Primer::Alpha::Tooltip
 - Primer::Tooltip
+cssId: tooltip
 ---
 
 import ComponentLayout from '~/src/layouts/component-layout'

content/deprecated-components/box-overlay.mdx

@@ -0,0 +1,21 @@
+---
+title: Box overlay
+description: Box overlay is used to create a floating box that appears on top of the page content.
+cssId: boxoverlay
+---
+
+import ComponentLayout from '~/src/layouts/component-layout'
+import {Link, Text} from '@primer/react'
+import {Link as GatsbyLink} from 'gatsby'
+export default ComponentLayout
+
+## Usage
+
+<Note variant="warning">
+  <Text sx={{display: 'block', fontWeight: 'bold', mb: 2}}>Usage for this component is not encouraged</Text>
+  <Text>Instead, please see <Link as={GatsbyLink} to="/components/dialog">dialog</Link>.</Text>
+</Note>
+
+Box overlay is only available as a [CSS component](/deprecated-components/box-overlay/css). Use box overlay with the `details` and `details-dialog`. The box overlay appears on top of the page content.
+
+Box overlays come in three widths, default (440px), narrow (320px), and wide (640px).

content/deprecated-components/index.mdx

@@ -0,0 +1,9 @@
+---
+title: Deprecated components
+description: Components that are no longer supported or encouraged for use. 
+---
+
+import IndexLayout from '~/src/layouts/index-layout'
+export default IndexLayout
+
+<ChildPages of="Deprecated components" />

content/deprecated-components/select-menu.mdx

@@ -0,0 +1,17 @@
+---
+title: Select menu
+description: Select menu provides advanced support for navigation, filtering, and more.
+cssId: selectmenu
+---
+
+import ComponentLayout from '~/src/layouts/component-layout'
+import {Link, Text} from '@primer/react'
+import {Link as GatsbyLink} from 'gatsby'
+export default ComponentLayout
+
+<Note variant="warning">
+  <Text sx={{display: 'block', fontWeight: 'bold', mb: 2}}>Usage for this component is not encouraged</Text>
+  <Text>Instead, please see <Link as={GatsbyLink} to="/components/action-menu">action menu</Link>.</Text>
+</Note>
+
+Select menu is only available right now as a [CSS component](/deprecated-components/select-menu/css). Select menu can make use of JavaScript-enabled live filtering, selected states, tabbed lists, and keyboard navigation with a bit of markup. To see all examples of this component, view it in the [Primer CSS storybook](https://primer.style/css/storybook/?path=/docs/deprecated-selectmenu--docs).

gatsby-node.esm.js

@@ -299,6 +299,7 @@ async function createComponentPages({actions, graphql}) {
             reactId
             figmaId
             railsIds
+            cssId
           }
         }
       }
@@ -314,6 +315,7 @@ async function createComponentPages({actions, graphql}) {
   const reactComponentLayout = path.resolve(__dirname, 'src/layouts/react-component-layout.tsx')
   const railsComponentLayout = path.resolve(__dirname, 'src/layouts/rails-component-layout.tsx')
   const figmaComponentLayout = path.resolve(__dirname, 'src/layouts/figma-component-layout.tsx')
+  const cssComponentLayout = path.resolve(__dirname, 'src/layouts/css-component-layout.tsx')
 
   for (const {slug, frontmatter} of data.allMdx.nodes) {
     if (frontmatter.reactId) {
@@ -370,6 +372,16 @@ async function createComponentPages({actions, graphql}) {
         },
       })
     }
+    if (frontmatter.cssId) {
+      actions.createPage({
+        path: `/${slug}/css`,
+        component: cssComponentLayout,
+        context: {
+          cssId: frontmatter.cssId,
+          parentPath: `/${slug}`,
+        },
+      })
+    }
   }
 }
 

src/@primer/gatsby-theme-doctocat/nav.yml

@@ -266,6 +266,8 @@
       url: /components/textarea
     - title: Timeline
       url: /components/timeline
+    - title: Toast
+      url: /components/toast
     - title: Toggle switch
       url: /components/toggle-switch
     - title: Token
@@ -280,6 +282,16 @@
       url: /components/underline-nav
     - title: Underline panels
       url: /components/underline-panels
+- title: Deprecated components
+  children:
+    - title: Box overlay
+      url: /deprecated-components/box-overlay
+    - title: Dropdown
+      url: /deprecated-components/dropdown
+    - title: Menu
+      url: /deprecated-components/menu
+    - title: Select menu
+      url: /deprecated-components/select-menu
 - title: GitHub staff
   url: /github-staff
   children:

src/components/component-page-nav.tsx

@@ -7,13 +7,15 @@ export function ComponentPageNav({
   includeReact,
   includeRails,
   includeFigma,
+  includeCSS,
   current,
 }: {
   basePath: string
   includeReact?: boolean
   includeRails?: boolean
   includeFigma?: boolean
-  current?: 'overview' | 'react' | 'rails' | 'figma'
+  includeCSS?: boolean
+  current?: 'overview' | 'react' | 'rails' | 'figma' | 'css'
 }) {
   return (
     <UnderlineNav>
@@ -35,6 +37,11 @@ export function ComponentPageNav({
           Figma
         </UnderlineNav.Link>
       ) : null}
+      {includeCSS ? (
+        <UnderlineNav.Link as={GatsbyLink} to={`${basePath}/css`} selected={current === 'css'}>
+          CSS
+        </UnderlineNav.Link>
+      ) : null}
     </UnderlineNav>
   )
 }

src/layouts/component-layout.tsx

@@ -7,7 +7,7 @@ import {BaseLayout} from '../components/base-layout'
 import {ComponentPageNav} from '../components/component-page-nav'
 
 export default function ComponentLayout({pageContext, children, path}) {
-  const {title, description, reactId, railsIds, figmaId} = pageContext.frontmatter
+  const {title, description, reactId, railsIds, figmaId, cssId} = pageContext.frontmatter
 
   return (
     <BaseLayout title={title} description={description}>
@@ -24,6 +24,7 @@ export default function ComponentLayout({pageContext, children, path}) {
             includeReact={reactId}
             includeRails={railsIds}
             includeFigma={figmaId}
+            includeCSS={cssId}
             current="overview"
           />
         </Box>

src/layouts/css-component-layout.tsx

@@ -0,0 +1,118 @@
+import SourceLink from '@primer/gatsby-theme-doctocat/src/components/source-link'
+import StorybookLink from '@primer/gatsby-theme-doctocat/src/components/storybook-link'
+import Code from '@primer/gatsby-theme-doctocat/src/components/code'
+import {HEADER_HEIGHT} from '@primer/gatsby-theme-doctocat/src/components/header'
+import {H2, H3} from '@primer/gatsby-theme-doctocat/src/components/heading'
+import {Note} from '@primer/gatsby-theme-doctocat'
+import {LinkExternalIcon} from '@primer/octicons-react'
+import {Box, Heading, Label, Link, Text} from '@primer/react'
+import {graphql, Link as GatsbyLink} from 'gatsby'
+import React from 'react'
+import {StorybookEmbed} from '../components/storybook-embed'
+import {BaseLayout} from '../components/base-layout'
+import {ComponentPageNav} from '../components/component-page-nav'
+
+export const query = graphql`
+  query CssComponentPageQuery($parentPath: String!) {
+    sitePage(path: {eq: $parentPath}) {
+      path
+      context {
+        frontmatter {
+          title
+          description
+          reactId
+          railsIds
+          figmaId
+          cssId
+        }
+      }
+    }
+  }
+`
+
+export default function CssComponentLayout({data}) {
+  console.log(data.sitePage)
+  const name = data.sitePage?.context.frontmatter.cssId || ''
+  const title = data.sitePage?.context.frontmatter.title || name
+  const description = data.sitePage?.context.frontmatter.description || ''
+  const stories = [{id: `deprecated-${name}--default`}]
+
+  return (
+    <BaseLayout title={title} description={description}>
+      <Box sx={{maxWidth: 1200, width: '100%', p: [4, 5, 6, 7], mx: 'auto'}}>
+        <Heading as="h1" sx={{fontSize: 7}}>{title}</Heading>
+        {description ? (
+          <Text as="p" sx={{fontSize: 3, m: 0, mb: 3, maxWidth: '60ch'}}>
+            {description}
+          </Text>
+        ) : null}
+        <Box sx={{mb: 4}}>
+          <ComponentPageNav
+            basePath={data.sitePage.path}
+            includeReact={data.sitePage.context.frontmatter.reactId}
+            includeRails={data.sitePage.context.frontmatter.railsIds}
+            includeFigma={data.sitePage.context.frontmatter.figmaId}
+            includeCSS={data.sitePage.context.frontmatter.cssId}
+            current="css"
+          />
+        </Box>
+        <Note variant="warning">
+          <Text sx={{display: 'block', fontWeight: 'bold', mb: 2}}>Primer CSS is no longer actively maintained</Text>
+          <Text>The <Link as={GatsbyLink} to="https://github.com/primer/css">CSS library</Link> is still available, but these components will not receive new features or major changes moving forward. We encourage you to use Primer React or View Components wherever possible.</Text>
+        </Note>
+        <Box sx={{display: 'flex', mt: 4, alignItems: 'start', gap: [null, 7, 8, 9]}}>
+          <Box sx={{width: '100%'}}>
+            {/* @ts-ignore */}
+            <Box
+              sx={{
+                display: 'flex',
+                flexDirection: ['column', null, null, null, 'row'],
+                justifyContent: 'space-between',
+                gap: 3,
+                mb: 4,
+              }}
+            >
+              <Box
+                as={'ul'}
+                sx={{
+                  display: 'flex',
+                  gap: 3,
+                  alignItems: 'center',
+                  m: 0,
+                  p: 0,
+                  paddingInline: 0,
+                  listStyle: 'none',
+                  fontSize: 1,
+                  '& > li': {
+                    display: 'flex',
+                  },
+                }}
+              >
+                <SourceLink href={`https://github.com/primer/css/blob/main/src/${name}`} />
+                {stories.length > 0 ? (
+                  <StorybookLink href={`https://primer.style/css/storybook/?path=/story/${stories[0].id}`} />
+                ) : null}
+              </Box>
+            </Box>
+
+            <H2>Examples</H2>
+            {stories.length > 0 ? (
+              <StorybookEmbed framework="css" height={300} stories={stories} />
+            ) : (
+              // If there are no stories, link to the component's page in the Primer CSS Storybook
+              <Link
+                sx={{display: 'inline-flex', gap: 1, alignItems: 'center'}}
+                href={`https://primer.style/css/${name}`}
+                target="_blank"
+                rel="noopener noreferrer"
+              >
+                <span>{name} examples</span>
+                <LinkExternalIcon />
+              </Link>
+            )}
+          </Box>
+        </Box>
+      </Box>
+    </BaseLayout>
+  )
+}

src/layouts/figma-component-layout.tsx

@@ -24,6 +24,7 @@ export const query = graphql`
           reactId
           figmaId
           railsIds
+          cssId
         }
       }
     }
@@ -93,6 +94,7 @@ export default function FigmaComponentLayout({data}) {
             includeReact={data.sitePage.context.frontmatter.reactId}
             includeRails={data.sitePage.context.frontmatter.railsIds}
             includeFigma={data.sitePage.context.frontmatter.figmaId}
+            includeCSS={data.sitePage.context.frontmatter.cssId}
             current="figma"
           />
         </Box>