[Primitives v8] UI color docs (#720)

* graphics galore

* more docs

* clean up headings

* lint

* cleanup

* ready for review!!!!

* lint

* undo sb embed changes

* address feedback

* add alt text

* fix heading

* add new css utilities

* grammar

* lint

* add more clarity

content/foundations/color/accessibility.mdx

@@ -0,0 +1,72 @@
+---
+title: Accessibility
+description:
+  Primer color tokens are designed to be accessible by default. This guide provides more context around how to ensure new patterns meet GitHub's standards.
+---
+
+import {Box, Heading} from '@primer/react'
+
+## Guidelines
+
+### Assure adequate color contrast
+
+Color contrast between text and its background must meet [required WCAG standards](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html).
+
+The contrast requirements are:
+
+- 4.5:1 for normal text
+- 3:1 for large text (>24px)
+- 3:1 for UI elements and graphics
+- No contrast requirement for decorative and disabled elements
+
+Use an [online contrast checker](https://webaim.org/resources/contrastchecker/) or a [Figma plugin](/guides/accessibility/tools#contrast-plugin) to test your contrast.
+
+### Don't rely on color alone
+
+<Box
+  mb={3}
+  display="flex"
+  alignItems="flex-start"
+  alignItems="center"
+  flexDirection={['column', 'column', 'column', 'column', 'row']}
+  sx={{gap: 3}}
+>
+  <Box as="p" mt="0">
+    <Heading sx={{mt: 0, mb: 3, fontSize: 2}} as="h4">
+      Show state with more than color
+    </Heading>
+    Color vision deficiency is different for different people. To make sure everyone can understand and use your UI you should
+    show state with more than a change in color. For example by using icons or changing the content.
+  </Box>
+  <img
+    width="456"
+    alt="Example icon that uses a distinct shape in addition to color to indicate an error."
+    src="https://user-images.githubusercontent.com/813754/187186864-8a825434-978b-4e21-bac2-9c1235d75e2c.png"
+  />
+</Box>
+
+<Box
+  mb={3}
+  display="flex"
+  alignItems="flex-start"
+  alignItems="start"
+  flexDirection={['column', 'column', 'column', 'column', 'row']}
+  sx={{gap: 3}}
+>
+  <Box as="p" mt="0">
+    <Heading sx={{mt: 0, mb: 3, fontSize: 2}} as="h4">
+      Connect labels to graphs with lines or patterns
+    </Heading>
+    For charts and graphs you can position the labels on top or close to each section. You can also use patterns to distinguish
+    different parts.
+  </Box>
+  <img
+    width="456"
+    alt="Two graphs. One is a line graph and one is a pie graph. The line graph is demonstrating using unique shapes for each comparison line's plot symbol. The pie chart is demonstrating how each slice's label can use a line to point to its corresponding slide."
+    src="https://user-images.githubusercontent.com/813754/187186931-84bcc541-7cea-45f2-a686-21c5428e0620.png"
+  />
+</Box>
+
+### Additional guidance
+
+Reference [Color considerations](https://primer.style/guides/accessibility/color-considerations) for additional information about how color relates to compliance, and other focused documentation topics.

content/foundations/color/base-scales.mdx

@@ -0,0 +1,17 @@
+---
+title: Base scales
+description:
+  Primer base color scales makeup the foundation for all UI color considerations.
+---
+
+## All color scales
+
+<Note>Base color values should only be used to construct functional and component/pattern design tokens, never used directly in code</Note>
+
+Use the theme menu to see how the base scales change per theme.
+
+<StorybookEmbed
+  baseUrl="https://primer.style/primitives/storybook"
+  stories={[{id: 'color-base-scales--all-scales'}]}
+  height="940"
+/>

content/foundations/color/index.mdx

@@ -0,0 +1,10 @@
+---
+title: Color
+description: Color is a fundamental part of Primer's visual language. In this guide you will learn about the principles,
+  patterns, and abstractions that make up Primer’s color system.
+---
+
+import IndexLayout from '~/src/layouts/index-layout'
+export default IndexLayout
+
+<ChildPages path="Foundations/Color" />

content/foundations/color/overview.mdx

@@ -0,0 +1,168 @@
+---
+title: UI color system
+description:
+  Color is a fundamental part of Primer's visual language. In this guide you will learn about the principles,
+  patterns, and abstractions that make up Primer’s color system.
+---
+
+import {Box} from '@primer/react'
+
+## Overview
+
+<img width="960" alt="Comparative display of GitHub interface elements in light and dark modes. The light mode shows a browser window with a light background, green contribution graph, and standard browser controls. The dark mode presents the same design with a dark background, enhancing the visibility of green contribution graph and browser controls." src="https://github.com/primer/primitives/assets/18661030/615e3e06-9289-4adc-ab85-2213fae96e8c" style="margin-bottom: 1rem;" />
+
+GitHub's UI offers two color modes, `light` and `dark`. Primer supports both color modes across nine [themes](../../foundations/primitives/getting-started#theming). Every pattern in Primer is built to work across all color modes out of the box.
+
+### Color modes in Figma
+
+When designing product interfaces in Figma, we recommend using **light mode** or **dark mode** as the Primer Web Figma library provides components and tokens in those two modes.
+You can learn more about using design tokens in Figma in our [Figma guidelines](../../guides/figma/getting-started#styles-and-variables).
+
+### Color design tokens
+
+Primer delivers colors in the form of [design tokens](../../foundations/primitives/getting-started). Design tokens are a layer of abstraction that allows for better maintainability, consistency and theming. Within Primer, design tokens are represented as CSS variables for code and Figma variables for design. For a full reference table of all available design tokens, see the [color CSS variables](../../foundations/primitives/color) page.
+
+As an example of how color tokens work, when `bgColor-default` is referenced for a background color, the value of that token will automatically change depending on the color mode.
+
+<img
+  width="960"
+  alt="GitHub Wiki page theming comparison. On the left, a light theme featuring a card with a welcome message, a green 'Create the first page' button, and annotated with 'fgColor-default' for foreground and 'bgColor-default' for background colors. On the right, the same card is shown in dark mode with the text and button colors adjusted for contrast, also annotated with color roles."
+  src="https://github.com/primer/react/assets/18661030/21726ed0-2175-44a3-a821-af002778c0b3"
+/>
+
+### Design token categories
+
+Primer design tokens are categorized into three groups:
+
+- Base
+- Functional
+- Component/pattern
+
+To read more about the naming convention, see the [design token naming guidelines](../../foundations/primitives/token-names) page.
+
+<img
+  width="960"
+  alt="Color design guide for GitHub interface elements showing a transition from a base color, a magenta (#bf3989) to a functional color name 'color-scale-pink-5', and then to 'borderColor-sponsors-emphasis'. Below the base color, a color scale from 0 to 9 shows varying shades of pink. Two button examples demonstrate the practical application of the colors: one in a light theme with 'Sponsor' text and heart icon and another in a dark theme with the same elements."
+  src="https://github.com/primer/primitives/assets/18661030/10dd4c91-5faa-464c-ab07-9e26afd54e5f"
+  style="margin-bottom: 1rem;"
+/>
+
+**Base** color tokens are the lowest level tokens and map directly to a raw value. They are <strong>only</strong> to be used as a reference for functional and component/pattern tokens. Base color tokens don't respect color modes and should never be used directly in code or design.
+
+Example: `color-scale-pink-5`
+
+**Functional** color tokens represent global UI patterns such as text, borders, shadows, and backgrounds. These are the most commonly used design tokens throughout all of Primer and GitHub UI. Functional color tokens reference base color tokens under the hood, and respect color modes.
+
+Example: `borderColor-sponsors-emphasis`
+
+<img
+  width="960"
+  alt="GitHub interface component patterns displaying color coding for UI elements. On the left, a red border box indicates 'borderColor-danger-emphasis' changing to 'control-borderColor-danger'. On the right, a blue border box signifies 'borderColor-accent-emphasis' transitioning to 'focus-outlineColor'. Examples include text input fields for an email address with error messages and toggle switches in both light and dark themes."
+  src="https://github.com/primer/primitives/assets/18661030/4b91c346-24c4-4926-911d-de9d27c851d3"
+  style="margin-bottom: 1rem; margin-top: 1rem;"
+/>
+
+**Component/pattern** tokens are used for values that are more specific or unique than functional tokens. These tokens are limited and functional tokens are preferred. Component/pattern color tokens may reference both base and functional tokens under the hood, and respect color modes.
+
+Example: `focus-outlineColor`
+
+## Neutral colors
+
+Shades of gray used for text, borders, backgrounds, and shadows.
+
+### Foreground
+
+Foreground tokens use the `fgColor` property and are used for text and icons.
+
+<img
+  width="960"
+  alt="GitHub pull request interface demonstrating foreground color roles in light and dark themes. Both themes highlight text 'Guidelines #798' in 'fgColor-default', the 'Draft' label in 'fgColor-onEmphasis', and a clickable username in 'fgColor-link'. The light theme uses 'fgColor-muted' for auxiliary text, mirrored in the dark theme for contrast optimization."
+  src="https://github.com/primer/react/assets/18661030/b8f72aab-98eb-4b7a-a5fa-fd8d63e9b8cd"
+/>
+
+### Background
+
+Background tokens use the `bgColor` property and are used for backgrounds and fills.
+
+<img
+  width="960"
+  alt="GitHub's navigation menu in light and dark themes, annotated to indicate background color roles. In light mode, the menu has 'bgColor-inset' for the avatar circle, 'bgColor-emphasis' for the 'Pull requests' button, 'overlay-bgColor' for hover effects, 'bgColor-muted' for inactive menu items, and 'bgColor-default' for the overall background. The dark mode mirrors this scheme with appropriate colors for visibility."
+  src="https://github.com/primer/react/assets/18661030/477efd99-16a0-42f7-8bd4-68c05bb5376a"
+/>
+
+### Border
+
+Border tokens use the `borderColor` property and are used for borders and dividers.
+
+<img
+  width="960"
+  alt="GitHub interface dropdown menu with border color annotations in light and dark themes. In light mode, the dropdown is outlined with 'borderColor-default', while menu options are separated by 'borderColor-muted'. In dark mode, the same color roles apply with adjusted shades for contrast."
+  src="https://github.com/primer/react/assets/18661030/6e916437-0bcd-4dd0-9e88-f014f27d1fd0"
+/>
+
+### Shadow
+
+Shadow tokens use the `shadow` property and are used for shadows and elevation.
+
+<img width="960" alt="GitHub interface design elements annotated with shadow styles: 'shadow-floating-small', 'shadow-resting-xsmall', and 'shadow-inset', displayed on light and dark mode backgrounds." src="https://github.com/primer/primitives/assets/18661030/246b3dc1-42b4-4125-aaf1-f936bc29c995" />
+
+## Semantic colors
+
+Semantic colors are typically used to communicate status, action, or emphasis. Each semantic color is tied to a [role](#color-roles) with a specific meaning. Color tokens are available for foreground, background, and border. Background and border colors have both a `muted` and `emphasis` option.
+
+<img
+  width="960"
+  alt="Overview of GitHub UI color roles in light and dark themes. Each theme displays labeled color swatches for: 'accent-emphasis' in blue, 'accent-muted' in light blue, 'success-emphasis' in green, 'success-muted' in light green, 'danger-emphasis' in red, 'danger-muted' in light red, 'warning-emphasis' in yellow, 'warning-muted' in light yellow, 'done-emphasis' in purple, 'done-muted' in light purple, 'sponsor-emphasis' in magenta, and 'sponsor-muted' in light magenta."
+  src="https://github.com/primer/primitives/assets/18661030/165ceeae-9933-473a-976f-655c918be1c2"
+/>
+
+### Muted
+
+Muted background and border colors are often combined to draw attention to a specific piece of content with a subtle emphasis.
+
+<img
+  width="960"
+  alt="GitHub interface elements showing a warning message and a user comment in both light and dark modes. The warning message has a yellow background with a caution icon and is dismissible with a close button. The user comment by 'monalisa' features a speech bubble with a light blue background in light mode and a dark blue background in dark mode, both with muted borders."
+  src="https://github.com/primer/react/assets/18661030/df33b03c-ef06-4dc6-9d85-f6dd9cd3f3f0"
+/>
+
+### Emphasis
+
+Emphasis background colors provide a stronger emphasis for UI elements and are always combined with `fgColor-onEmphasis` tokens for text and icons.
+
+<img
+  width="960"
+  alt="GitHub interface showcasing button styles with emphasis colors in light and dark modes. The 'Primary' button is green, the 'Danger' button is red with a trash icon, the 'Queued' button is brown with a clock icon, and the 'Beta' button is outlined in green. Annotations indicate 'borderColor-{role}-emphasis' and 'bgColor-{role}-emphasis' for each button style."
+  src="https://github.com/primer/react/assets/18661030/3e4ec1f8-cbc5-4ebf-9816-7f247474b9c6"
+/>
+
+### Semantic foreground
+
+Foreground semantic colors provide contrast against `muted` and default background colors and should be used for text and icons.
+
+<img
+  width="960"
+  alt="GitHub interface elements displaying in light and dark themes with foreground color roles. Tags include 'Sponsor' with a heart icon, 'Verified' with a checkmark, and language tags 'css' and 'ruby'. The colors of text and icons are adjusted according to the theme for optimal contrast, annotated with 'fgColor-{role}'."
+  src="https://github.com/primer/react/assets/18661030/7fcd6efb-ec86-4460-98aa-e3e5be062bec"
+/>
+
+## Color roles
+
+| Color roles                                                                       | Usage                                                               |
+| :-------------------------------------------------------------------------------- | :------------------------------------------------------------------ |
+| <Box sx={{display: 'inline-flex', alignContent: 'center', gap: '4px', verticalAlign: 'middle'}}><Box sx={{backgroundColor: 'accent.emphasis', height: '24px', width: '24px', borderRadius: 1}}></Box> `accent`</Box> | Links, selected, active, and focus states, and neutral information |
+| <Box sx={{display: 'inline-flex', alignContent: 'center', gap: '4px', verticalAlign: 'middle'}}><Box sx={{backgroundColor: 'success.emphasis', height: '24px', width: '24px', borderRadius: 1}}></Box> `success`</Box>     | Primary buttons, positive messaging and successful states                                |
+| <Box sx={{display: 'inline-flex', alignContent: 'center', gap: '4px', verticalAlign: 'middle'}}><Box sx={{backgroundColor: 'attention.emphasis', height: '24px', width: '24px', borderRadius: 1}}></Box> `attention`</Box> | Warning states, active processes such as queued PRs and tests in progress   |
+| <Box sx={{display: 'inline-flex', alignContent: 'center', gap: '4px', verticalAlign: 'middle'}}><Box sx={{backgroundColor: 'danger.emphasis', height: '24px', width: '24px', borderRadius: 1}}></Box> `danger`</Box>       | Danger buttons and error states |
+| <Box sx={{display: 'inline-flex', alignContent: 'center', gap: '4px', verticalAlign: 'middle'}}><Box sx={{backgroundColor: 'open.emphasis', height: '24px', width: '24px', borderRadius: 1}}></Box> `open`</Box>           | Open tasks, PRs or workflows           |
+| <Box sx={{display: 'inline-flex', alignContent: 'center', gap: '4px', verticalAlign: 'middle'}}><Box sx={{backgroundColor: 'closed.emphasis', height: '24px', width: '24px', borderRadius: 1}}></Box> `closed`</Box>       | Closed tasks, PRs or workflows         |
+| <Box sx={{display: 'inline-flex', alignContent: 'center', gap: '4px', verticalAlign: 'middle'}}><Box sx={{backgroundColor: 'done.emphasis', height: '24px', width: '24px', borderRadius: 1}}></Box> `done`</Box>           | Completed tasks, PRs or workflows      |
+| <Box sx={{display: 'inline-flex', alignContent: 'center', gap: '4px', verticalAlign: 'middle'}}><Box sx={{backgroundColor: 'sponsors.emphasis', height: '24px', width: '24px', borderRadius: 1}}></Box> `sponsors`</Box>           | Text and icons related to GitHub Sponsors      |
+
+
+## Developers
+
+Colors are available in the form of CSS variables and CSS utility classes that can be used across all frameworks including React and Rails. Check out the references below for more information.
+
+- [Color CSS variables](../../foundations/primitives/color)
+- [Color CSS utility classes](../../foundations/css-utilities/colors)

content/foundations/css-utilities/colors.mdx

@@ -14,7 +14,7 @@ These utilities should only be used where color is not provided by a component.
 
 Use text color utilities to set text to a specific color. Color contrast must pass a minimum WCAG accessibility rating of [level AA](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html). This ensures that viewers who cannot see the full color spectrum are able to read the text. To customize outside of the suggested combinations below, we recommend using this [color contrast testing tool](https://colorable.jxnblk.com/). For more information, read our [accessibility standards](/guides/accessibility).
 
-<StorybookEmbed framework="css" stories={[{id: 'utilities-color--text'}]} height="410" />
+<StorybookEmbed framework="css" stories={[{id: 'utilities-color--new-text'}, {id: 'utilities-color--text'}]} height="410" />
 
 You can set the color inheritance on an element by using the `color-fg-inherit` class.
 
@@ -24,10 +24,10 @@ You can set the color inheritance on an element by using the `color-fg-inherit`
 
 Background colors are most commonly used for filling large blocks of content or areas with a color. When selecting a background color, make sure the foreground color contrast passes a minimum WCAG accessibility rating of [level AA](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html). Meeting these standards ensures that content is accessible by everyone, regardless of disability or user device. You can [check your color combination with this demo site](https://colorable.jxnblk.com/). For more information, read our [accessibility standards](/guides/accessibility).
 
-<StorybookEmbed framework="css" stories={[{id: 'utilities-color--background'}]} height="1250" />
+<StorybookEmbed framework="css" stories={[{id: 'utilities-color--new-background'}, {id: 'utilities-color--background'}]} height="1250" />
 
 ## Border
 
 Override default border colors with the following utilities.
 
-<StorybookEmbed framework="css" stories={[{id: 'utilities-color--border'}]} height="1170" />
+<StorybookEmbed framework="css" stories={[{id: 'utilities-color--new-border'}, {id: 'utilities-color--border'}]} height="1170" />

content/foundations/primitives/color.mdx

@@ -13,31 +13,31 @@ description:
 <StorybookEmbed
   baseUrl="https://primer.style/primitives/storybook/"
   stories={[{id: 'color-functional-tables--foreground'}]}
-  height="640"
+  height="760"
 />
 
 ### Background
 
 <StorybookEmbed
   baseUrl="https://primer.style/primitives/storybook/"
   stories={[{id: 'color-functional-tables--background'}]}
-  height="330"
+  height="1280"
 />
 
 ### Border
 
 <StorybookEmbed
   baseUrl="https://primer.style/primitives/storybook/"
   stories={[{id: 'color-functional-tables--border'}]}
-  height="640"
+  height="1200"
 />
 
 ### Shadow
 
 <StorybookEmbed
   baseUrl="https://primer.style/primitives/storybook/"
   stories={[{id: 'color-functional-tables--shadow'}]}
-  height="220"
+  height="460"
 />
 
 ## Pattern