Merge pull request #1111 from primer/VanAnderson/update-docs-for-func…

…tional-vars Update docs to use functional color variables
primer · Mar 9, 2021 · 057a489 · 057a489 · vercel · Mar 9, 2021
2 parents f38e8c3 + 360e359
commit 057a489
Show file tree

Hide file tree

Showing 20 changed files with 236 additions and 189 deletions.
diff --git a/.changeset/fair-feet-know.md b/.changeset/fair-feet-know.md
@@ -0,0 +1,5 @@
+---
+"@primer/components": patch
+---
+
+Update color variable used in ProgressBar (`state.success` → `bg.successInverse`)
diff --git a/docs/content/BorderBox.md b/docs/content/BorderBox.md
@@ -2,8 +2,7 @@
 title: BorderBox
 ---
 
-
-BorderBox is a Box component with a border. When no `borderColor` is present, the component defaults to a gray border.
+BorderBox is a Box component with a border. When no `borderColor` is present, the component defaults to a primary border.
 
 ## Default example
 
@@ -19,10 +18,10 @@ BorderBox components get `COMMON`, `LAYOUT`, `BORDER`, and `FLEX` system props.
 
 ## Component props
 
-| Prop name | Type | Default | Description |
-| :- | :- | :-: | :- |
-| borderWidth | String | '1px' | Sets the border, use theme values or provide your own. |
-| borderStyle | String | 'solid' | Sets the border style, use theme values or provide your own. |
-| borderColor | String | 'gray.2' (from theme) | Sets the border color, use theme values or provide your own. |
-| borderRadius | String or Number| 2 (from theme)| Sets the border radius, use theme values or provide your own. |
-| boxShadow | String | | Sets box shadow, use theme values or provide your own. |
+| Prop name    | Type             |            Default            | Description                                                   |
+| :----------- | :--------------- | :---------------------------: | :------------------------------------------------------------ |
+| borderWidth  | String           |             '1px'             | Sets the border, use theme values or provide your own.        |
+| borderStyle  | String           |            'solid'            | Sets the border style, use theme values or provide your own.  |
+| borderColor  | String           | 'border.primary' (from theme) | Sets the border color, use theme values or provide your own.  |
+| borderRadius | String or Number |        2 (from theme)         | Sets the border radius, use theme values or provide your own. |
+| boxShadow    | String           |                               | Sets box shadow, use theme values or provide your own.        |
diff --git a/docs/content/Box.md b/docs/content/Box.md
@@ -2,17 +2,26 @@
 title: Box
 ---
 
-
-The Box component serves as a wrapper component for most layout related needs. Use Box to set values such as `display`,  `width`, `height`, and more. See the LAYOUT section of our [System Props](/system-props) documentation for the full list of available props. In practice, this component is used frequently as a wrapper around other components to achieve Box Model related styling.
+The Box component serves as a wrapper component for most layout related needs. Use Box to set values such as `display`, `width`, `height`, and more. See the LAYOUT section of our [System Props](/system-props) documentation for the full list of available props. In practice, this component is used frequently as a wrapper around other components to achieve Box Model related styling.
 
 ## Default example
 
 ```jsx live live
 <Box>
- Box can be used to create both <Box as="span" bg="green.1">inline</Box> and
- <Box bg="blue.1">block-level elements,</Box>
- <Box bg="purple.1" width={[1, 1, 1/2]}>elements with fixed or responsive width and height,</Box>
- <Box bg="yellow.0" p={4} mt={2}>and more!</Box>
+  Box can be used to create both{' '}
+  <Box as="span" color="text.inverse" bg="bg.successInverse">
+    inline
+  </Box>{' '}
+  and
+  <Box color="text.inverse" bg="bg.dangerInverse">
+    block-level elements,
+  </Box>
+  <Box color="text.inverse" bg="bg.warningInverse" width={[1, 1, 1 / 2]}>
+    elements with fixed or responsive width and height,
+  </Box>
+  <Box color="text.inverse" bg="bg.infoInverse" p={4} mt={2}>
+    and more!
+  </Box>
 </Box>
 ```
 
@@ -22,6 +31,6 @@ Box components get the `COMMON`, `LAYOUT`, and `FLEX` categories of system props
 
 ## Component props
 
-| Prop name | Type | Default | Description |
-| :- | :- | :-: | :- |
-| as | String | `div` | sets the HTML tag for the component|
+| Prop name | Type   | Default | Description                         |
+| :-------- | :----- | :-----: | :---------------------------------- |
+| as        | String |  `div`  | sets the HTML tag for the component |
diff --git a/docs/content/BranchName.md b/docs/content/BranchName.md
@@ -2,8 +2,7 @@
 title: BranchName
 ---
 
-
-BranchName is a label-type component rendered as an `<a>` tag by default with monospace font and blue background.
+BranchName is a label-type component rendered as an `<a>` tag by default with monospace font.
 
 ## Default example
 
@@ -17,7 +16,7 @@ BranchName components get `COMMON` system props. Read our [System Props](/system
 
 ## Component props
 
-| Name | Type | Default | Description |
-| :- | :- | :-: | :- |
-| as | String | `<a>` | sets the HTML tag for the component |
-| href | String | | a URL to link the component to |
+| Name | Type   | Default | Description                         |
+| :--- | :----- | :-----: | :---------------------------------- |
+| as   | String |  `<a>`  | sets the HTML tag for the component |
+| href | String |         | a URL to link the component to      |
diff --git a/docs/content/CircleOcticon.md b/docs/content/CircleOcticon.md
@@ -2,13 +2,12 @@
 title: CircleOcticon
 ---
 
-
 CircleOcticon renders any Octicon with a circle background. CircleOcticons are most commonly used to represent the status of a pull request in the comment timeline.
 
 ## Default example
 
 ```jsx live
-  <CircleOcticon icon={CheckIcon} size={32} bg="green.5" color="white"/>
+<CircleOcticon icon={CheckIcon} size={32} bg="icon.success" color="text.inverse" />
 ```
 
 ## System props
@@ -17,7 +16,7 @@ CircleOcticon components get `COMMON` system props. Read our [System Props](/sys
 
 ## Component props
 
-| Name | Type | Default | Description |
-| :- | :- | :-: | :- |
-| icon | Octicon | | Octicon component used in the component |
-| size | Number | 32 | used to set the width and height of the component |
+| Name | Type    | Default | Description                                       |
+| :--- | :------ | :-----: | :------------------------------------------------ |
+| icon | Octicon |         | Octicon component used in the component           |
+| size | Number  |   32    | used to set the width and height of the component |
diff --git a/docs/content/Flex.md b/docs/content/Flex.md
@@ -4,20 +4,20 @@ title: Flex
 
 The `Flex` component behaves the same as the `Box` component except that it has `display: flex` set by default.
 
-*Previously, a `Flex.Item` component was used for flex item specific properties; `Box` now contains all those properties and should be used in its place.*
+_Previously, a `Flex.Item` component was used for flex item specific properties; `Box` now contains all those properties and should be used in its place._
 
 ## Default example
 
 ```jsx live
 <BorderBox width={300} height={300} borderRadius={0}>
   <Flex flexWrap="nowrap">
-    <Box p={3} bg="blue.5">
+    <Box p={3} color="text.inverse" bg="bg.infoInverse">
       Item 1
     </Box>
-    <Box p={3} bg="green.5">
+    <Box p={3} color="text.inverse" bg="bg.warningInverse">
       Item 2
     </Box>
-    <Box p={3} bg="yellow.5">
+    <Box p={3} color="text.inverse" bg="bg.dangerInverse">
       Item 3
     </Box>
   </Flex>

diff --git a/docs/content/Grid.md b/docs/content/Grid.md
@@ -8,8 +8,12 @@ Grid is a component that exposes grid system props. See the [CSS Tricks Complete
 
 ```jsx live
 <Grid gridTemplateColumns="repeat(2, auto)" gridGap={3}>
-    <Box p={3} bg="blue.2">1</Box>
-    <Box p={3} bg="yellow.2">2</Box>
+  <Box p={3} color="text.inverse" bg="bg.infoInverse">
+    1
+  </Box>
+  <Box p={3} color="text.inverse" bg="bg.warningInverse">
+    2
+  </Box>
 </Grid>
 ```
 

diff --git a/docs/content/Label.md b/docs/content/Label.md
@@ -7,11 +7,11 @@ The Label component is used to add contextual metadata to a design. Visually it
 ## Default example
 
 ```jsx live
-  <Label variant="small" outline borderColor="red.2" mr={2} color="red.4">small</Label>
+  <Label variant="small" outline borderColor="border.danger" mr={2} color="text.danger">small</Label>
   <Label variant="medium" mr={2}>medium (default)</Label>
   <Label variant="large" mr={2}>large</Label>
   <Label variant="xl">xl label</Label>
-  
+
   <Box mt={4}/>
   <Label variant="medium" bg="#A575FF" m={1}>good first issue</Label>
   <Label variant="medium" bg="#FF75C8" m={1}>🚂 deploy: train</Label>
@@ -26,9 +26,9 @@ Label components get `COMMON` system props. Read our [System Props](/system-prop
 
 ## Component props
 
-| Name | Type | Default | Description |
-| :- | :- | :-: | :- |
-| outline | Boolean | | Creates an outline style label |
-| variant | String | 'medium' | Can be one of `small`, `medium` (default), `large` or `xl` .
-| dropshadow | Boolean | | Adds a dropshadow to the label |
-| bg | String | 'gray.5' | Part of the `COMMON` system props, used to change the background of the label.
+| Name       | Type    |        Default         | Description                                                                    |
+| :--------- | :------ | :--------------------: | :----------------------------------------------------------------------------- |
+| outline    | Boolean |                        | Creates an outline style label                                                 |
+| variant    | String  |        'medium'        | Can be one of `small`, `medium` (default), `large` or `xl` .                   |
+| dropshadow | Boolean |                        | Adds a dropshadow to the label                                                 |
+| bg         | String  | 'label.primary.border' | Part of the `COMMON` system props, used to change the background of the label. |
diff --git a/docs/content/LabelGroup.md b/docs/content/LabelGroup.md
@@ -9,7 +9,7 @@ The LabelGroup component is used to add commonly used margins and wrapping for g
 ```jsx live
 <LabelGroup>
   <Label>Default label</Label>
-  <Label bg='red.4'>Label with red background</Label>
+  <Label color="prState.closed.text" bg="prState.closed.bg">Label with background indicating a closed PR state</Label>
   <Label outline>Default outline label</Label>
 </LabelGroup>
 ```

diff --git a/docs/content/Link.md b/docs/content/Link.md
@@ -2,7 +2,7 @@
 title: Link
 ---
 
-The Link component styles anchor tags with default blue styling and hover text decoration. `Link` is used for destinations, or moving from one page to another.
+The Link component styles anchor tags with default hyperlink color cues and hover text decoration. `Link` is used for destinations, or moving from one page to another.
 
 In special cases where you'd like a `<button>` styled like a `Link`, use `<Link as='button'>`. Make sure to provide a click handler with `onClick`.
 
@@ -22,10 +22,10 @@ Link components get `COMMON` and `TYPOGRAPHY` system props. Read our [System Pro
 
 ## Component props
 
-| Name      | Type    | Default | Description                                       |
-| :-------- | :------ | :-----: | :------------------------------------------------ |
-| href      | String  |         | URL to be used for the Link                       |
-| muted     | Boolean |  false  | Uses light gray for Link color, and blue on hover |
-| underline | Boolean |  false  | Adds underline to the Link                        |
-| as        | String  |   'a'   | Can be 'a', 'button', 'input', or 'summary'       |
-| hoverColor        | String  |    | Color used when hovering over link      |
+| Name       | Type    | Default | Description                                                                     |
+| :--------- | :------ | :-----: | :------------------------------------------------------------------------------ |
+| href       | String  |         | URL to be used for the Link                                                     |
+| muted      | Boolean |  false  | Uses a less prominent shade for Link color, and the default link shade on hover |
+| underline  | Boolean |  false  | Adds underline to the Link                                                      |
+| as         | String  |   'a'   | Can be 'a', 'button', 'input', or 'summary'                                     |
+| hoverColor | String  |         | Color used when hovering over link                                              |
diff --git a/docs/content/PointerBox.md b/docs/content/PointerBox.md
@@ -7,7 +7,7 @@ PointerBox is a [BorderBox](./BorderBox) component with a caret added to it.
 ## Default example
 
 ```jsx live
-<PointerBox m={4} p={2} minHeight={100} bg="green.1" borderColor="green.5">
+<PointerBox m={4} p={2} minHeight={100} bg="bg.success" borderColor="border.success">
   PointerBox
 </PointerBox>
 ```
@@ -18,26 +18,47 @@ function PointerBoxDemo(props) {
 
   return (
     <Box>
-      <Heading as="h3" fontSize={3}>Caret Position</Heading>
+      <Heading as="h3" fontSize={3}>
+        Caret Position
+      </Heading>
       <CaretSelector current={pos} onChange={setPos} />
       <Relative pt={4}>
-        <PointerBox m={4} p={2} minHeight={100} bg="green.1" borderColor="green.5" caret={pos}> Content </PointerBox>
+        <PointerBox m={4} p={2} minHeight={100} bg="bg.success" borderColor="border.success" caret={pos}>
+          {' '}
+          Content{' '}
+        </PointerBox>
       </Relative>
     </Box>
   )
 }
 
 function CaretSelector(props) {
   const choices = [
-    'top',         'bottom',      'left',         'right',
-    'left-bottom', 'left-top',    'right-bottom', 'right-top',
-    'top-left',    'bottom-left', 'top-right',    'bottom-right'
-  ].map((dir) => (
+    'top',
+    'bottom',
+    'left',
+    'right',
+    'left-bottom',
+    'left-top',
+    'right-bottom',
+    'right-top',
+    'top-left',
+    'bottom-left',
+    'top-right',
+    'bottom-right'
+  ].map(dir => (
     <label>
-      <input key={dir} type='radio' name='caret' value={dir}
-        checked={dir === props.current} onChange={() => props.onChange(dir)} /> {dir}
+      <input
+        key={dir}
+        type="radio"
+        name="caret"
+        value={dir}
+        checked={dir === props.current}
+        onChange={() => props.onChange(dir)}
+      />{' '}
+      {dir}
     </label>
-))
+  ))
 
   return (
     <Grid gridTemplateColumns="repeat(4, auto)" gridGap={3} my={2}>
@@ -55,6 +76,6 @@ PointerBox components get `COMMON`, `LAYOUT`, `BORDER`, and `FLEX` system props.
 
 ## Component props
 
-| Name | Type | Default | Description |
-| :- | :- | :-: | :- |
-| caret | String | bottom | Sets the location of the caret. The format is `[edge]-[position on edge]`. For example, `right-top` will position the caret on the top of the right edge of the box. Use `top`, `right`, `bottom`, or `left` to position a caret in the center of that edge. |
+| Name  | Type   | Default | Description                                                                                                                                                                                                                                                  |
+| :---- | :----- | :-----: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| caret | String | bottom  | Sets the location of the caret. The format is `[edge]-[position on edge]`. For example, `right-top` will position the caret on the top of the right edge of the box. Use `top`, `right`, `bottom`, or `left` to position a caret in the center of that edge. |
diff --git a/docs/content/Position.md b/docs/content/Position.md
@@ -10,30 +10,46 @@ The Position component is a wrapper component that gives the containing componen
 <Box p={2} mb={200}>
   <Heading mb={2}>Relative + Absolute</Heading>
   <Relative size={128} mx={128} my={6}>
-    <Box border={1} borderColor="gray.2" size="100%">
-      <Absolute left="100%" top={0} bg="red.1" p={1}>rt</Absolute>
-      <Absolute right="100%" top={0} bg="green.1" p={1}>lt</Absolute>
-      <Absolute left="100%" bottom={0} bg="blue.1" p={1}>rb</Absolute>
-      <Absolute right="100%" bottom={0} bg="purple.1" p={1}>lb</Absolute>
-      <Absolute left={0} top="100%" bg="orange.1" p={1}>bl</Absolute>
-      <Absolute right={0} top="100%" bg="yellow.3" p={1}>br</Absolute>
-      <Absolute left={0} bottom="100%" bg="red.1" p={1}>tl</Absolute>
-      <Absolute right={0} bottom="100%" bg="blue.1" p={1}>tr</Absolute>
-    </Box>
+    <BorderBox size="100%">
+      <Absolute left="100%" top={0} color="text.inverse" bg="bg.successInverse" p={1}>
+        rt
+      </Absolute>
+      <Absolute right="100%" top={0} color="text.inverse" bg="bg.successInverse" p={1}>
+        lt
+      </Absolute>
+      <Absolute left="100%" bottom={0} color="text.inverse" bg="bg.successInverse" p={1}>
+        rb
+      </Absolute>
+      <Absolute right="100%" bottom={0} color="text.inverse" bg="bg.successInverse" p={1}>
+        lb
+      </Absolute>
+      <Absolute left={0} top="100%" color="text.inverse" bg="bg.successInverse" p={1}>
+        bl
+      </Absolute>
+      <Absolute right={0} top="100%" color="text.inverse" bg="bg.successInverse" p={1}>
+        br
+      </Absolute>
+      <Absolute left={0} bottom="100%" color="text.inverse" bg="bg.successInverse" p={1}>
+        tl
+      </Absolute>
+      <Absolute right={0} bottom="100%" color="text.inverse" bg="bg.successInverse" p={1}>
+        tr
+      </Absolute>
+    </BorderBox>
   </Relative>
 
   <Heading my={2}>Sticky</Heading>
 
-  <BorderBox border={1} borderColor="green.5" height={500}>
-    <Sticky top={0} bg="green.2" p={6}>
+  <BorderBox border={1} borderColor="border.success" height={500}>
+    <Sticky top={0} bg="bg.success" p={6}>
       I'm sticky!
     </Sticky>
   </BorderBox>
 
   <Heading my={2}>Fixed</Heading>
   <p>(see the bottom right of the screen)</p>
 
-  <Fixed bottom={0} right={0} bg="red.2" p={2}>
+  <Fixed bottom={0} right={0} color="text.inverse" bg="bg.dangerInverse" p={2}>
     I'm fixed to the bottom right.
   </Fixed>
 </Box>