From 10733397ec8e1ac52e2456d12e3c78c0ffd4441f Mon Sep 17 00:00:00 2001
From: Josep Martins <josepmartins@github.com>
Date: Thu, 6 Oct 2022 16:37:05 +0200
Subject: [PATCH 1/2] Bump Doctocat to v4.2.0
---
content/components/action-bar.mdx | 96 ++++--------
content/components/action-list.mdx | 47 +-----
content/components/autocomplete.mdx | 61 +-------
content/components/dialog.mdx | 72 ++-------
content/components/relative-time.mdx | 27 ++--
content/components/segmented-control.mdx | 68 +--------
content/components/toggle-switch.mdx | 181 ++++++++++++++++-------
content/components/tokens.mdx | 34 +----
content/components/treeview.mdx | 11 +-
package.json | 2 +-
yarn.lock | 20 +--
11 files changed, 209 insertions(+), 410 deletions(-)
diff --git a/content/components/action-bar.mdx b/content/components/action-bar.mdx
index ab6751b..fecca9c 100644
--- a/content/components/action-bar.mdx
+++ b/content/components/action-bar.mdx
@@ -1,66 +1,10 @@
---
title: Action bar
status: Experimental
+description: An action bar contains a collection of horizontally aligned icon buttons.
---
-import {Box, Label, LabelGroup, Text} from '@primer/react'
-
-<Box sx={{fontSize: 3}} class="lead" as="p">
- An action bar contains a collection of horizontally aligned icon buttons.
-</Box>
-
-<!-- TODO: uncomment when available
-<LabelGroup>
- <Label
- as="a"
- href="https://primer.style/react/ActionBar"
- size="large"
- variant="secondary"
- sx={{textDecoration: 'none'}}
- >
- <img
- width="16"
- height="16"
- alt=""
- src="https://user-images.githubusercontent.com/293280/123878374-ce9d4d00-d8f3-11eb-8adf-1a160292ff53.png"
- style="vertical-align: middle; margin-right: 4px;"
- />
- React
- </Label>
- <Label
- as="a"
- href=""
- size="large"
- variant="secondary"
- sx={{textDecoration: 'none'}}
- >
- <img
- width="16"
- height="16"
- alt=""
- src="https://user-images.githubusercontent.com/293280/123878720-80d51480-d8f4-11eb-9b10-d02a1cb606f8.png"
- style="vertical-align: middle; margin-right: 4px;"
- />
- Figma
- </Label>
- <Label
- as="a"
- href="https://primer.style/view-components/components/alpha/actionbar"
- size="large"
- variant="secondary"
- sx={{textDecoration: 'none'}}
- >
- <img
- width="16"
- height="16"
- alt=""
- src="https://user-images.githubusercontent.com/18661030/171468311-184bfd70-128e-4bfc-b482-96d0de49d42a.png"
- style="vertical-align: middle; margin-right: 4px;"
- />
- Rails
- </Label>
-</LabelGroup>
--->
+import {Box, Text} from '@primer/react'
## Overview
@@ -68,7 +12,11 @@ Use an action bar to render multiple icon buttons in a row. Buttons can be split
## Anatomy
-<img width="960" alt="A diagram of an action bar with a few buttons, a divider and at the end a button that opens an overflow menu." src="https://user-images.githubusercontent.com/378023/193506131-be8bead4-d1ab-4c79-8ac1-054e75bac9be.png" />
+<img
+ width="960"
+ alt="A diagram of an action bar with a few buttons, a divider and at the end a button that opens an overflow menu."
+ src="https://user-images.githubusercontent.com/378023/193506131-be8bead4-d1ab-4c79-8ac1-054e75bac9be.png"
+/>
## Content
@@ -161,7 +109,9 @@ Buttons in action bars are solely used for triggering actions. Consider using a
role="presentation"
width="456"
/>
- <Caption>Buttons in action bars have a hover and pressed state, and a focused state when using a keyboard to navigate.</Caption>
+ <Caption>
+ Buttons in action bars have a hover and pressed state, and a focused state when using a keyboard to navigate.
+ </Caption>
</Do>
<Dont>
<img
@@ -243,7 +193,10 @@ Make sure to add extra spacing around the action bar.
role="presentation"
width="456"
/>
- <Caption>Avoid having the action bar touch something else. Even though the action bar buttons have no borders in their resting state, when hovering/pressing a button it will show a background color.</Caption>
+ <Caption>
+ Avoid having the action bar touch something else. Even though the action bar buttons have no borders in their
+ resting state, when hovering/pressing a button it will show a background color.
+ </Caption>
</Dont>
</DoDontContainer>
@@ -255,14 +208,14 @@ An action bar has an ARIA role of [`toolbar`](https://developer.mozilla.org/en-U
### Keyboard navigation
-| Key | description |
-| -- | -- |
-| `Tab` | Moves focus into and out of the action bar. Note that there should only be **one tab-stop** and pressing tab again should focus the next focusable element after the action bar. Also the first button is focused if the action bar is receiving focus for the first time after page load. Otherwise, the most recently focused button receives focus. |
-| `→` | Right arrow moves focus to the **next** button. If the last button has focus, focus loops back to the first button. |
-| `â†` | Left arrow moves focus to the **previous** button. If the first button has focus, focus moves to the last button. |
-| `Home` | Moves focus to the **first** button. |
-| `End` | Moves focus to the **last** button. |
-| `Enter` or `Space` | Triggers the button **action**. |
+| Key | description |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `Tab` | Moves focus into and out of the action bar. Note that there should only be **one tab-stop** and pressing tab again should focus the next focusable element after the action bar. Also the first button is focused if the action bar is receiving focus for the first time after page load. Otherwise, the most recently focused button receives focus. |
+| `→` | Right arrow moves focus to the **next** button. If the last button has focus, focus loops back to the first button. |
+| `â†` | Left arrow moves focus to the **previous** button. If the first button has focus, focus moves to the last button. |
+| `Home` | Moves focus to the **first** button. |
+| `End` | Moves focus to the **last** button. |
+| `Enter` or `Space` | Triggers the button **action**. |
<!-- TODO: Add video -->
@@ -277,7 +230,10 @@ An action bar has an ARIA role of [`toolbar`](https://developer.mozilla.org/en-U
sx={{gap: 3}}
>
<Text as="p" mt="0">
- Ensure action bar buttons have a large enough touch target size (44px by 44px). The buttons should respond to hovers, clicks, and taps anywhere in the touch target area, even if it isn't directly on the control. To avoid overlapping of touch targets, additional space between each button is needed (for example a 12px gap for medium sized buttons).
+ Ensure action bar buttons have a large enough touch target size (44px by 44px). The buttons should respond to
+ hovers, clicks, and taps anywhere in the touch target area, even if it isn't directly on the control. To avoid
+ overlapping of touch targets, additional space between each button is needed (for example a 12px gap for medium
+ sized buttons).
</Text>
<img
src="https://user-images.githubusercontent.com/378023/193507314-1f1cc55d-ca4e-4832-a6de-785546e079ca.png"
diff --git a/content/components/action-list.mdx b/content/components/action-list.mdx
index e184127..b557f4c 100644
--- a/content/components/action-list.mdx
+++ b/content/components/action-list.mdx
@@ -1,51 +1,14 @@
---
title: Action list
status: Alpha
----
-
-import {Box, Button, Heading, Label, LabelGroup, Link} from '@primer/react'
-
-<Box sx={{fontSize: 3}} class="lead" as="p">
+react: https://primer.style/react/ActionList
+figma: https://www.figma.com/file/GCvY3Qv8czRgZgvl1dG6lp/Primer-Web?node-id=1927%3A0
+description:
An action list is a vertical list of interactive actions or options. It’s composed of items presented in a consistent
single-column format, with room for icons, descriptions, side information, and other rich visuals.
-</Box>
+---
-<Box mb={4}>
- <LabelGroup>
- <Label
- as="a"
- href="https://primer.style/react/ActionList"
- size="large"
- variant="secondary"
- sx={{textDecoration: 'none'}}
- >
- <img
- width="16"
- height="16"
- alt=""
- src="https://user-images.githubusercontent.com/293280/123878374-ce9d4d00-d8f3-11eb-8adf-1a160292ff53.png"
- style="vertical-align: middle; margin-right: 4px;"
- />
- React
- </Label>
- <Label
- as="a"
- href="https://www.figma.com/file/GCvY3Qv8czRgZgvl1dG6lp/Primer-Web?node-id=1927%3A0"
- size="large"
- variant="secondary"
- sx={{textDecoration: 'none'}}
- >
- <img
- width="16"
- height="16"
- alt=""
- src="https://user-images.githubusercontent.com/293280/123878720-80d51480-d8f4-11eb-9b10-d02a1cb606f8.png"
- style="vertical-align: middle; margin-right: 4px;"
- />
- Figma
- </Label>
- </LabelGroup>
-</Box>
+import {Box, Button, Heading, Link} from '@primer/react'
<ImageContainer>
<img
diff --git a/content/components/autocomplete.mdx b/content/components/autocomplete.mdx
index de348c1..9288f7d 100644
--- a/content/components/autocomplete.mdx
+++ b/content/components/autocomplete.mdx
@@ -1,64 +1,13 @@
---
title: Autocomplete
status: Alpha
+description: Autocomplete allows users to quickly filter through a list of options and pick one or more values for a field.
+react: https://primer.style/react/Autocomplete
+rails: https://primer.style/view-components/components/beta/autocomplete
+figma: https://www.figma.com/file/GCvY3Qv8czRgZgvl1dG6lp/Primer-Web?node-id=1927%3A0
---
-import {LabelGroup, Label, Box} from '@primer/react'
-
-<Box sx={{fontSize: 3}} class="lead" as="p">
- Autocomplete allows users to quickly filter through a list of options and pick one or more values for a field.
-</Box>
-
-<LabelGroup>
- <Label
- as="a"
- href="https://primer.style/components/Autocomplete"
- size="large"
- variant="secondary"
- sx={{textDecoration: 'none'}}
- >
- <img
- width="16"
- height="16"
- alt=""
- src="https://user-images.githubusercontent.com/293280/123878374-ce9d4d00-d8f3-11eb-8adf-1a160292ff53.png"
- style="vertical-align: middle; margin-right: 4px;"
- />
- React
- </Label>
- <Label
- as="a"
- href="https://www.figma.com/file/GCvY3Qv8czRgZgvl1dG6lp/Primer-Web?node-id=1927%3A0"
- size="large"
- variant="secondary"
- sx={{textDecoration: 'none'}}
- >
- <img
- width="16"
- height="16"
- alt=""
- src="https://user-images.githubusercontent.com/293280/123878720-80d51480-d8f4-11eb-9b10-d02a1cb606f8.png"
- style="vertical-align: middle; margin-right: 4px;"
- />
- Figma
- </Label>
- <Label
- as="a"
- href="https://primer.style/view-components/components/beta/autocomplete"
- size="large"
- variant="secondary"
- sx={{textDecoration: 'none'}}
- >
- <img
- width="16"
- height="16"
- alt=""
- src="https://user-images.githubusercontent.com/18661030/171468311-184bfd70-128e-4bfc-b482-96d0de49d42a.png"
- style="vertical-align: middle; margin-right: 4px;"
- />
- Rails
- </Label>
-</LabelGroup>
+import {Box} from '@primer/react'
## Overview
diff --git a/content/components/dialog.mdx b/content/components/dialog.mdx
index 8548db5..6532de8 100644
--- a/content/components/dialog.mdx
+++ b/content/components/dialog.mdx
@@ -1,68 +1,15 @@
---
title: Dialog
status: Alpha
----
-
-import {Box, Heading, Label, LabelGroup, Link} from '@primer/react'
-import {Caption} from '@primer/gatsby-theme-doctocat'
-
-<Box sx={{fontSize: 3}} class="lead" as="p">
+description:
A Dialog is a floating surface used to display transient content such as confirmation actions, selection options, and
more.
-</Box>
+react: https://primer.style/react/Dialog
+rails: https://primer.style/view-components/components/alpha/dialog
+---
-<Box mb={4}>
- <LabelGroup>
- <Label
- as="a"
- href="https://primer.style/react/Dialog"
- size="large"
- variant="secondary"
- sx={{textDecoration: 'none'}}
- >
- <img
- width="16"
- height="16"
- alt=" "
- src="https://user-images.githubusercontent.com/293280/123878374-ce9d4d00-d8f3-11eb-8adf-1a160292ff53.png"
- style="vertical-align: middle; margin-right: 4px;"
- />
- React
- </Label>
- <Label
- as="a"
- href="https://primer.style/view-components/components/alpha/dialog"
- size="large"
- variant="secondary"
- sx={{textDecoration: 'none'}}
- >
- <img
- width="16"
- height="16"
- alt=""
- src="https://user-images.githubusercontent.com/18661030/171468311-184bfd70-128e-4bfc-b482-96d0de49d42a.png"
- style="vertical-align: middle; margin-right: 4px;"
- />
- Rails
- </Label>
- {/* <Label
- as="a"
- href="https://www.figma.com/file/GCvY3Qv8czRgZgvl1dG6lp/Primer-Web?node-id=1927%3A0"
- size="large"
- variant="secondary"
- sx={{textDecoration: 'none'}}
- >
- <img
- width="16"
- height="16"
- alt=" "
- src="https://user-images.githubusercontent.com/293280/123878720-80d51480-d8f4-11eb-9b10-d02a1cb606f8.png"
- style="vertical-align: middle; margin-right: 4px;"
- />
- Figma
- </Label> */}
- </LabelGroup>
-</Box>
+import {Box} from '@primer/react'
+import {Caption} from '@primer/gatsby-theme-doctocat'
## Overview
@@ -225,7 +172,7 @@ The edges of Dialog are free of text and heavy visuals to visually distinguish t
## Size
-Dialog offers a range of sizes from `small` to `xlarge`, with the default size set to `medium`.
+Dialog offers a range of sizes from `small` to `xlarge`, with the default size set to `medium`.
Each size defines a width and a maximum height. By default the dialog height will adjust to the body content. If the maximum height is reached, the body contents will scroll.
@@ -251,7 +198,10 @@ Medium is the default size for Dialog and should be used for most tasks such as
alt=""
src="https://user-images.githubusercontent.com/18661030/187552600-06dcbd81-90b5-45aa-81ce-89f8d9763508.png"
/>
-<Caption>Medium Dialogs have a width of 480px, and a max height of 320px. Medium portrait oriented Dialogs have a width of 480px, and a max height of 600px.</Caption>
+<Caption>
+ Medium Dialogs have a width of 480px, and a max height of 320px. Medium portrait oriented Dialogs have a width of
+ 480px, and a max height of 600px.
+</Caption>
### Large
diff --git a/content/components/relative-time.mdx b/content/components/relative-time.mdx
index 5416e25..b5621e6 100644
--- a/content/components/relative-time.mdx
+++ b/content/components/relative-time.mdx
@@ -1,13 +1,10 @@
---
title: Relative time
status: Experimental
+description: A relative time displays the time difference between the current time and the specified date-time.
---
-import {Box, Text} from '@primer/react'
-
-<Box sx={{fontSize: 3}} class="lead" as="p">
- A relative time displays the time difference between the current time and the specified date-time.
-</Box>
+import {Box} from '@primer/react'
## Content
@@ -23,12 +20,12 @@ If the date is in past months, the date time[^2] format `on D MMM` is used. If t
[^2]: Date time data is derived from the [Intl.DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat) API.
-| Time difference | Format | Examples |
-| --------------- | -------------------------------- | ------------------------------------------------------------------------------------------ |
-| < 1 minute | just now | `just now` |
+| Time difference | Format | Examples |
+| --------------- | -------------------------------- | ----------------------------------------------------------------------------------------- |
+| < 1 minute | just now | `just now` |
| < 1 month | X seconds/minutes/hours/days ago | `a minute ago`, `5 minutes ago`, `an hour ago`, `3 hours ago`, `yesterday`, `20 days ago` |
-| > 1 month | on D MMM | `on 18 Nov` |
-| Past year | on D MMM, YYYY | `on 26 Aug, 2021` |
+| > 1 month | on D MMM | `on 18 Nov` |
+| Past year | on D MMM, YYYY | `on 26 Aug, 2021` |
<p>
<img
@@ -46,12 +43,12 @@ If the future date is due to happen within the a month's time, the relative time
If the date is in the following months, the format `on D MMM` is used. If the date is in the next year or further, the format `on D MMM, YYYY` is used.
-| Time difference | Format | Examples |
-| --------------- | -------------------------------------- | ----------------------------------------------------------------------------------- |
-| < 1 minute | just now | `just now` |
+| Time difference | Format | Examples |
+| --------------- | ------------------------------------- | ----------------------------------------------------------------------------------- |
+| < 1 minute | just now | `just now` |
| < 1 month | in X seconds / minutes / hours / days | `in a minute`, `in 2 minutes`, `in an hour`, `in 7 hours`, `tomorrow`, `in 14 days` |
-| > 1 month | on D MMM | `on 18 Nov` |
-| Next year | on D MMM, YYYY | `on 26 Aug, 2021` |
+| > 1 month | on D MMM | `on 18 Nov` |
+| Next year | on D MMM, YYYY | `on 26 Aug, 2021` |
### Micro format
diff --git a/content/components/segmented-control.mdx b/content/components/segmented-control.mdx
index ce88f94..b84503a 100644
--- a/content/components/segmented-control.mdx
+++ b/content/components/segmented-control.mdx
@@ -1,70 +1,14 @@
---
title: Segmented control
----
-
-import {Box, Text, Label} from '@primer/react'
-
-<Box sx={{fontSize: 3}} class="lead" as="p">
+status: Alpha
+description:
A segmented control is used to pick one choice from a linear set of closely related choices, and immediately apply
that selection.
-</Box>
+react: https://primer.style/react/SegmentedControl
+figma: https://www.figma.com/file/GCvY3Qv8czRgZgvl1dG6lp/Primer-Web?node-id=16121%3A61220
+---
-<Box display="flex" alignItems="center" sx={{gap: 1}}>
- <Label
- as="a"
- href="https://primer.style/react/SegmentedControl"
- size="large"
- outline
- display="flex"
- variant="secondary"
- sx={{textDecoration: 'none'}}
- >
- <img
- width="20"
- height="20"
- role="presentation"
- src="https://user-images.githubusercontent.com/293280/123878374-ce9d4d00-d8f3-11eb-8adf-1a160292ff53.png"
- style="vertical-align: middle; margin-right: 4px;"
- />
- React
- </Label>
- {/*
- TODO: uncomment this when ViewComponents component is up
- <Label
- as="a"
- href="https://primer.style/view-components/components/segmented-control/"
- size="large"
- outline
- display="flex"
- variant="secondary"
- sx={{textDecoration: 'none'}}
- >
- <img
- width="20"
- role="presentation"
- src="https://user-images.githubusercontent.com/2313998/187994220-d892697d-8ffd-4e67-92ab-95c7e7223f56.png"
- style="vertical-align: middle; margin-right: 4px;"
- />
- ViewComponents
- </Label>
- */}
- <Label
- as="a"
- href="https://www.figma.com/file/GCvY3Qv8czRgZgvl1dG6lp/Primer-Web?node-id=16121%3A61220"
- size="large"
- variant="secondary"
- sx={{textDecoration: 'none'}}
- >
- <img
- width="16"
- height="16"
- role="presentation"
- src="https://user-images.githubusercontent.com/293280/123878720-80d51480-d8f4-11eb-9b10-d02a1cb606f8.png"
- style="vertical-align: middle; margin-right: 4px;"
- />
- Figma
- </Label>
-</Box>
+import {Box, Text} from '@primer/react'
## Anatomy
diff --git a/content/components/toggle-switch.mdx b/content/components/toggle-switch.mdx
index 202b09a..a6b37b2 100644
--- a/content/components/toggle-switch.mdx
+++ b/content/components/toggle-switch.mdx
@@ -1,9 +1,12 @@
---
title: Toggle switch
description: A toggle switch is used to immediately toggle a setting on or off.
+status: Alpha
+react: https://primer.style/react/ToggleSwitch
+rails: https://primer.style/view-components/components/alpha/toggleswitch
---
-import {Box, Text} from '@primer/react'
+import {Box} from '@primer/react'
## Anatomy
@@ -17,81 +20,138 @@ import {Box, Text} from '@primer/react'
### Label and description
-<Box mb={5} display="flex" alignItems="flex-start" flexDirection={["column", "column", "column", "column", "row"]} sx={{gap: 3}}>
- <div>
- <Box as="p" mt="0">Every toggle switch should have a label that says what is being turned on or off. Optionally, you may include a description about the setting that is being turned on or off.</Box>
- <Box as="p" mt="0">Labels should be succinct, and can describe an object or an action (for example: "Discussions" or "Automatically watch repositories"). Don't use phrases that describe the switch's state in your label.</Box>
- </div>
- <img
- width="456"
- role="presentation"
- src="https://user-images.githubusercontent.com/2313998/159587115-5ffcdefb-f5e9-4180-8dc3-5328b0440f7f.png"
- />
+<Box
+ mb={5}
+ display="flex"
+ alignItems="flex-start"
+ flexDirection={['column', 'column', 'column', 'column', 'row']}
+ sx={{gap: 3}}
+>
+ <div>
+ <Box as="p" mt="0">
+ Every toggle switch should have a label that says what is being turned on or off. Optionally, you may include a
+ description about the setting that is being turned on or off.
+ </Box>
+ <Box as="p" mt="0">
+ Labels should be succinct, and can describe an object or an action (for example: "Discussions" or "Automatically
+ watch repositories"). Don't use phrases that describe the switch's state in your label.
+ </Box>
+ </div>
+ <img
+ width="456"
+ role="presentation"
+ src="https://user-images.githubusercontent.com/2313998/159587115-5ffcdefb-f5e9-4180-8dc3-5328b0440f7f.png"
+ />
</Box>
<DoDontContainer>
<Do>
- <img role="presentation" src="https://user-images.githubusercontent.com/2313998/159587088-99e8fe4c-59a3-4452-836d-bd6f2297045a.png" />
+ <img
+ role="presentation"
+ src="https://user-images.githubusercontent.com/2313998/159587088-99e8fe4c-59a3-4452-836d-bd6f2297045a.png"
+ />
<Caption>Use succinct phrases with verbs or nouns</Caption>
</Do>
<Dont>
- <img role="presentation" src="https://user-images.githubusercontent.com/2313998/159587096-5f8a6913-df95-4ea0-9838-a366faf95e52.png" />
+ <img
+ role="presentation"
+ src="https://user-images.githubusercontent.com/2313998/159587096-5f8a6913-df95-4ea0-9838-a366faf95e52.png"
+ />
<Caption>Don't use phrases that describe the switch's state</Caption>
</Dont>
</DoDontContainer>
### Layout
-<Box mb={3} display="flex" alignItems="flex-start" flexDirection={["column", "column", "column", "column", "row"]} sx={{gap: 3}}>
- <div>
- <Box as="p" mt="0">By default, lay out a toggle switch horizontally justified with its label and optional description.</Box>
- <Box as="p" mt="0">You may use a vertical layout when a toggle switch is layed out inline with other content, or if a horizontal layout would put the switch too far from its label. If the vertical layout is left-aligned, the "on"/"off" text may be moved to the right of the switch.</Box>
- </div>
- <Box display="flex" flexDirection="column" sx={{gap: 2, flexGrow: 1, flexShrink: 0}}>
- <img
- width="456"
- role="presentation"
- src="https://user-images.githubusercontent.com/2313998/159587115-5ffcdefb-f5e9-4180-8dc3-5328b0440f7f.png"
- />
- <img
- width="456"
- role="presentation"
- src="https://user-images.githubusercontent.com/2313998/159587126-8d30ff26-33a8-4b84-87db-13dcfdff9dac.png"
- />
+<Box
+ mb={3}
+ display="flex"
+ alignItems="flex-start"
+ flexDirection={['column', 'column', 'column', 'column', 'row']}
+ sx={{gap: 3}}
+>
+ <div>
+ <Box as="p" mt="0">
+ By default, lay out a toggle switch horizontally justified with its label and optional description.
+ </Box>
+ <Box as="p" mt="0">
+ You may use a vertical layout when a toggle switch is layed out inline with other content, or if a horizontal
+ layout would put the switch too far from its label. If the vertical layout is left-aligned, the "on"/"off" text
+ may be moved to the right of the switch.
</Box>
+ </div>
+ <Box display="flex" flexDirection="column" sx={{gap: 2, flexGrow: 1, flexShrink: 0}}>
+ <img
+ width="456"
+ role="presentation"
+ src="https://user-images.githubusercontent.com/2313998/159587115-5ffcdefb-f5e9-4180-8dc3-5328b0440f7f.png"
+ />
+ <img
+ width="456"
+ role="presentation"
+ src="https://user-images.githubusercontent.com/2313998/159587126-8d30ff26-33a8-4b84-87db-13dcfdff9dac.png"
+ />
+ </Box>
</Box>
### Size
-<Box mb={3} display="flex" alignItems="flex-start" flexDirection={["column", "column", "column", "column", "row"]} sx={{gap: 3}}>
- <Box as="p" mt="0">A small variant is provided to maintain visual hierarchy, or for dense areas where the default size will not fit.</Box>
- <img
- width="456"
- role="presentation"
- src="https://user-images.githubusercontent.com/2313998/159587124-e7ef0a16-fd42-4614-be3e-80c985332ef7.png"
- />
+<Box
+ mb={3}
+ display="flex"
+ alignItems="flex-start"
+ flexDirection={['column', 'column', 'column', 'column', 'row']}
+ sx={{gap: 3}}
+>
+ <Box as="p" mt="0">
+ A small variant is provided to maintain visual hierarchy, or for dense areas where the default size will not fit.
+ </Box>
+ <img
+ width="456"
+ role="presentation"
+ src="https://user-images.githubusercontent.com/2313998/159587124-e7ef0a16-fd42-4614-be3e-80c985332ef7.png"
+ />
</Box>
### Loading
-<Box mb={3} display="flex" alignItems="flex-start" flexDirection={["column", "column", "column", "column", "row"]} sx={{gap: 3}}>
- <Box as="p" mt="0">When a toggle switch is waiting for something to load before toggling, a loading indicator should be displayed. The switch should not prematurely toggle from "on" to "off". Wait until loading is complete before showing a change.</Box>
- <img
- width="456"
- role="presentation"
- src="https://user-images.githubusercontent.com/2313998/159587116-aa07a847-a633-4515-82b3-20ebe2349914.png"
- />
+<Box
+ mb={3}
+ display="flex"
+ alignItems="flex-start"
+ flexDirection={['column', 'column', 'column', 'column', 'row']}
+ sx={{gap: 3}}
+>
+ <Box as="p" mt="0">
+ When a toggle switch is waiting for something to load before toggling, a loading indicator should be displayed. The
+ switch should not prematurely toggle from "on" to "off". Wait until loading is complete before showing a change.
+ </Box>
+ <img
+ width="456"
+ role="presentation"
+ src="https://user-images.githubusercontent.com/2313998/159587116-aa07a847-a633-4515-82b3-20ebe2349914.png"
+ />
</Box>
### Progressive disclosure
-<Box mb={3} display="flex" alignItems="flex-start" flexDirection={["column", "column", "column", "column", "row"]} sx={{gap: 3}}>
- <Box as="p" mt="0">The <a href="/ui-patterns/progressive-disclosure">progressive disclosure pattern</a> may be used to hide or show content based on whether a toggle switch is on. Content revealed on toggle switch activation should always come <em>after</em> the toggle switch.</Box>
- <img
- width="456"
- role="presentation"
- src="https://user-images.githubusercontent.com/2313998/159591632-f604ec1d-aca9-42f7-ad65-16f8811f192f.png"
- />
+<Box
+ mb={3}
+ display="flex"
+ alignItems="flex-start"
+ flexDirection={['column', 'column', 'column', 'column', 'row']}
+ sx={{gap: 3}}
+>
+ <Box as="p" mt="0">
+ The <a href="/ui-patterns/progressive-disclosure">progressive disclosure pattern</a> may be used to hide or show
+ content based on whether a toggle switch is on. Content revealed on toggle switch activation should always come{' '}
+ <em>after</em> the toggle switch.
+ </Box>
+ <img
+ width="456"
+ role="presentation"
+ src="https://user-images.githubusercontent.com/2313998/159591632-f604ec1d-aca9-42f7-ad65-16f8811f192f.png"
+ />
</Box>
## Accessibility
@@ -114,14 +174,19 @@ If you have a group of configuration options that can be disabled, use a button
-
<DoDontContainer>
<Do>
- <img role="presentation" src="https://user-images.githubusercontent.com/2313998/159587100-1a1af5b2-dd19-456a-a0ed-c2f9fa7f7c2e.png" />
+ <img
+ role="presentation"
+ src="https://user-images.githubusercontent.com/2313998/159587100-1a1af5b2-dd19-456a-a0ed-c2f9fa7f7c2e.png"
+ />
<Caption>Use a button to affect multiple related toggles</Caption>
</Do>
<Dont>
- <img role="presentation" src="https://user-images.githubusercontent.com/2313998/159587101-446548c2-41c3-45c1-b710-db3149e2ebe4.png" />
+ <img
+ role="presentation"
+ src="https://user-images.githubusercontent.com/2313998/159587101-446548c2-41c3-45c1-b710-db3149e2ebe4.png"
+ />
<Caption>Don't use a toggle switch to represent mixed values</Caption>
</Dont>
</DoDontContainer>
@@ -135,11 +200,17 @@ A toggle switch should never be used as a replacement for a checkbox. See [savin
<DoDontContainer>
<Do>
- <img role="presentation" src="https://user-images.githubusercontent.com/2313998/159587105-45d50974-eb76-46cd-a3fd-c1e0f605f3ef.png" />
+ <img
+ role="presentation"
+ src="https://user-images.githubusercontent.com/2313998/159587105-45d50974-eb76-46cd-a3fd-c1e0f605f3ef.png"
+ />
<Caption>Use a toggle switch like a button</Caption>
</Do>
<Dont>
- <img role="presentation" src="https://user-images.githubusercontent.com/2313998/159587113-6c8461f7-3d4d-4e6a-b3a5-c585c5143fba.png" />
+ <img
+ role="presentation"
+ src="https://user-images.githubusercontent.com/2313998/159587113-6c8461f7-3d4d-4e6a-b3a5-c585c5143fba.png"
+ />
<Caption>Don't use a toggle switch as a replacement for a checkbox</Caption>
</Dont>
</DoDontContainer>
diff --git a/content/components/tokens.mdx b/content/components/tokens.mdx
index 97923dd..523ff80 100644
--- a/content/components/tokens.mdx
+++ b/content/components/tokens.mdx
@@ -1,39 +1,11 @@
---
title: Tokens
status: Alpha
+react: https://primer.style/react/Token
+description: A token is a compact representation of an object, and is typically used to show a collection of related metadata.
---
-import {LabelGroup, Label, Box} from '@primer/react'
-
-<Box sx={{fontSize: 3}} class="lead" as="p">
- A token is a compact representation of an object, and is typically used to show a collection of related metadata.
-</Box>
-
-<LabelGroup display="block" mb={4}>
- <Label
- as="a"
- href="https://primer.style/components/Token"
- variant="xl"
- color="text.success"
- outline
- style="text-decoration: none; line-height: 20px;"
- >
- <img
- width="20"
- height="20"
- alt=" "
- src="https://user-images.githubusercontent.com/293280/123878374-ce9d4d00-d8f3-11eb-8adf-1a160292ff53.png"
- style="vertical-align: middle; margin-right: 4px;"
- />
- React
- </Label>
- {/* TODO: uncomment once React and Figma docs are live
- <Label as="a" href="https://www.figma.com/file/GCvY3Qv8czRgZgvl1dG6lp/Primer-Web?node-id=1927%3A0" variant="xl" outline style="text-decoration: none; line-height: 20px;">
- <img width="20" height="20" alt=" " src="https://user-images.githubusercontent.com/293280/123878720-80d51480-d8f4-11eb-9b10-d02a1cb606f8.png" style="vertical-align: middle; margin-right: 4px;" />
- Figma
- </Label>
- */}
-</LabelGroup>
+import {Box} from '@primer/react'
## Overview
diff --git a/content/components/treeview.mdx b/content/components/treeview.mdx
index 482f92b..5a6c016 100644
--- a/content/components/treeview.mdx
+++ b/content/components/treeview.mdx
@@ -1,16 +1,13 @@
---
title: Tree view
+status: Experimental
+description:
+ A tree view is a hierarchical list of items that may have a parent-child relationship where children can be toggled
+ into view by expanding or collapsing their parent item.
---
import {Box} from '@primer/react'
-<!-- TODO: remove alt attributes from presentational images before merging -->
-
-<Box sx={{fontSize: 3}} class="lead" as="p">
- A tree view is a hierarchical list of items that may have a parent-child relationship where children can be toggled
- into view by expanding or collapsing their parent item.
-</Box>
-
## Anatomy
<img
diff --git a/package.json b/package.json
index f9a14db..df7f2ff 100644
--- a/package.json
+++ b/package.json
@@ -11,7 +11,7 @@
},
"dependencies": {
"@github/prettier-config": "^0.0.4",
- "@primer/gatsby-theme-doctocat": "^4.0.0",
+ "@primer/gatsby-theme-doctocat": "^4.2.0",
"@primer/octicons-react": "^17.3.0",
"@primer/react": "^35.5.0",
"eslint": "^8.21.0",
diff --git a/yarn.lock b/yarn.lock
index d29bb55..1262c5e 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -1780,17 +1780,17 @@
resolved "https://registry.yarnpkg.com/@primer/component-metadata/-/component-metadata-0.4.1.tgz#86c4cda1bc6504cd5f9d523fac16c5e00556d881"
integrity sha512-iy5ZEeIRN6pFFG7px2ruuA726yVB/n4lsgM3msfdg9qJzfS9qE2JCqq2OuvQ+yXUTxb3JKROaDSH403kdpFR4Q==
-"@primer/gatsby-theme-doctocat@^4.0.0":
- version "4.0.0"
- resolved "https://registry.yarnpkg.com/@primer/gatsby-theme-doctocat/-/gatsby-theme-doctocat-4.0.0.tgz#29c916ce62f14f7e70c0e8c9195ff38d89467ffa"
- integrity sha512-V6+cANzIKbPh4KHl+WtGBnRzIRt9WWfI5o1iTOwfmoPz7NOpU63kHmvmhofdbS64Nnv/1urc+eI3NIBfO4XbVQ==
+"@primer/gatsby-theme-doctocat@^4.2.0":
+ version "4.2.0"
+ resolved "https://registry.yarnpkg.com/@primer/gatsby-theme-doctocat/-/gatsby-theme-doctocat-4.2.0.tgz#230f4f241e0035cd23e8da7e8ae5e48097aaf9d4"
+ integrity sha512-WgptcLQHZ565IQbp9WETRCVCiapnkk1HURyWk26XhAZfeDHNFoKKNgZRzW1wzZU/nkRuzw6jCgUduZG6wICpBw==
dependencies:
"@babel/preset-env" "^7.5.5"
"@babel/preset-react" "^7.0.0"
"@mdx-js/mdx" "^1.0.21"
"@mdx-js/react" "^1.0.21"
"@primer/component-metadata" "^0.4.0"
- "@primer/octicons-react" "^16.3.1"
+ "@primer/octicons-react" "^17.5.0"
"@primer/react" "^35.2.2"
"@styled-system/theme-get" "^5.0.12"
"@testing-library/jest-dom" "^5.16.2"
@@ -1837,16 +1837,16 @@
styled-system "^5.0.18"
worker-loader "^3.0.2"
-"@primer/octicons-react@^16.3.1":
- version "16.3.1"
- resolved "https://registry.yarnpkg.com/@primer/octicons-react/-/octicons-react-16.3.1.tgz#86982fe1001eee138d5ee46accbcdf62d51d11c5"
- integrity sha512-uzTs8/CvLiW1/47cgMRkIK9bKWpnw+UonCbgczXErwSSLqMDHfiiTpobW1trvRuoiMgLwsPo0l7kBBdKBnmq3g==
-
"@primer/octicons-react@^17.3.0":
version "17.4.0"
resolved "https://registry.yarnpkg.com/@primer/octicons-react/-/octicons-react-17.4.0.tgz#b4e838dab01e5dbdb229f4b9abfe424ae06f1fd2"
integrity sha512-3h+/5CqwvQ9lUzlY+g25v6KoM5eVq1/3OjNslphKqiw/fqLzNHWwkWQQx89MZyRVXtaPs0dcRdGb2pqKUXCRqQ==
+"@primer/octicons-react@^17.5.0":
+ version "17.6.0"
+ resolved "https://registry.yarnpkg.com/@primer/octicons-react/-/octicons-react-17.6.0.tgz#641c7ac1d78e4e97fa1afff72d02501b26b353b5"
+ integrity sha512-jn1fWag3eU6BvOltMS2MqLPNh39D45cpegsTO2Qhb8SlJoUsj/ZO1qbJgYd9ibvZo8evDyXx3syh4kDbxJQFsg==
+
"@primer/primitives@7.8.4":
version "7.8.4"
resolved "https://registry.yarnpkg.com/@primer/primitives/-/primitives-7.8.4.tgz#484486ee47050f18b2e82c33e9df247a5886c82a"
--
GitLab
From f2ea034a25988e2dd58853c1060bbf7a54153407 Mon Sep 17 00:00:00 2001
From: Josep Martins <josepmartins@github.com>
Date: Thu, 6 Oct 2022 18:42:17 +0200
Subject: [PATCH 2/2] Use description in layout
---
content/foundations/color.mdx | 60 +++--
content/foundations/content.mdx | 5 +-
content/foundations/introduction.mdx | 10 +-
content/foundations/typography.mdx | 6 +-
content/ui-patterns/button-usage.mdx | 13 +-
content/ui-patterns/empty-states.mdx | 5 +-
content/ui-patterns/feature-onboarding.mdx | 3 +-
content/ui-patterns/forms.mdx | 8 +-
content/ui-patterns/messaging.mdx | 3 +-
.../ui-patterns/progressive-disclosure.mdx | 3 +-
content/ui-patterns/saving.mdx | 227 ++++++++++++------
11 files changed, 211 insertions(+), 132 deletions(-)
diff --git a/content/foundations/color.mdx b/content/foundations/color.mdx
index aaad5ea..d445634 100644
--- a/content/foundations/color.mdx
+++ b/content/foundations/color.mdx
@@ -1,13 +1,11 @@
---
title: Color
----
-
-<Box sx={{fontSize: 3}} class="lead" as="p">
+description:
Color is a fundamental piece in the Primer visual language. In this guide you will learn about the principles,
patterns, and abstractions that make Primer’s color system.
-</Box>
+---
-import {Box, Button, Heading, Label, LabelGroup, Link} from '@primer/react'
+import {Box, Heading} from '@primer/react'
## Get started
@@ -17,7 +15,6 @@ import {Box, Button, Heading, Label, LabelGroup, Link} from '@primer/react'
src="https://user-images.githubusercontent.com/6951037/146927448-cb518377-114a-4ab8-a37e-1eeffc8732c7.png"
/>
-
GitHub's UI offers a variety of different color modes. Every pattern in Primer is built to work across all color modes out of the box.
When designing product interfaces in Figma, we recommend using light mode. This is best because the Primer Figma components are only available in light mode.
@@ -27,7 +24,7 @@ To preview your work in other modes, use the [Figma color mode plugin](https://w
Primer delivers colors in the form of [design tokens](https://primer.style/primitives/colors). Design tokens are a layer of abstraction that allows better maintainability, consistency and easy theming.
-For example use `bg-default` for the background of the page and `fg-default` for the text color. If the user changes to dark mode, the underlying color that those tokens reference change, but the token names stay the same.
+For example use `bg-default` for the background of the page and `fg-default` for the text color. If the user changes to dark mode, the underlying color that those tokens reference change, but the token names stay the same.
<img
width="960"
@@ -53,7 +50,6 @@ By using Primer's functional color system you make sure that your interface:
- gets all future themes updates "for free"
- uses [accessible color combination](#combining-colors) across themes
-
The functional system is structured into two groups of design tokens:
- **Foundations:** Foregrounds (text and icons), backgrounds, and borders that make up most of a product interface.
@@ -250,27 +246,40 @@ Not all colors pair well with each other. There are combinations of backgrounds
/>
## Accessibility
+
When designing with colors consider the following to make your UI visually accessible.
### Assure adequate color contrast
-Color contrast between text and its background must meet [required WCAG standards](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html).
+
+Color contrast between text and its background must meet [required WCAG standards](https://www.w3.org/WAI/WCAG21/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](https://primer.style/design/accessibility/tools#contrast-plugin) to test your contrast.
+Use an [online contrast checker](https://webaim.org/resources/contrastchecker/) or a [Figma plugin](https://primer.style/design/accessibility/tools#contrast-plugin) to test your contrast.
If you work with the [functional colors](#color-roles-recipes), this work has already been done for you. We checked all recommended combinations, so you are all set.
### 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
+ 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.
+ <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"
@@ -279,16 +288,25 @@ For example by using icons or changing the content.
/>
</Box>
-<Box mb={3} display="flex" alignItems="flex-start" alignItems="start" flexDirection={["column", "column", "column", "column", "row"]} sx={{gap: 3}}>
+<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.
+ <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"
+ 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>
diff --git a/content/foundations/content.mdx b/content/foundations/content.mdx
index 0834d3d..7dc63b0 100644
--- a/content/foundations/content.mdx
+++ b/content/foundations/content.mdx
@@ -1,12 +1,11 @@
---
title: Content
+description: These guidelines are specific to and focused on GitHub product interfaces.
---
-import {Box} from '@primer/react'
-import {Text} from '@primer/react'
import Code from '@primer/gatsby-theme-doctocat/src/components/code'
-These guidelines are specific to and focused on GitHub product interfaces. Your first port of call for general content guidelines should be [GitHub’s content guide](https://github.com/github/brand/blob/main/content.md) (link only accessible to GitHub staff), followed by the [Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/).
+Your first port of call for general content guidelines should be [GitHub’s content guide](https://github.com/github/brand/blob/main/content.md) (link only accessible to GitHub staff), followed by the [Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/).
## UI content principles
diff --git a/content/foundations/introduction.mdx b/content/foundations/introduction.mdx
index e1f054d..97265fc 100644
--- a/content/foundations/introduction.mdx
+++ b/content/foundations/introduction.mdx
@@ -1,14 +1,8 @@
---
title: Introduction
+description: Primer is built for GitHub by GitHub. Its guidelines are a collection of open source principles, standards, and recommendations for designing GitHub. As a design language, Primer provides common grammar and vocabulary to build cohesive, accessible, responsive, and efficient experiences.
---
-import {Box} from '@primer/react'
-
-
-<Box sx={{fontSize: 3}} class="lead" as="p">
- Primer is built for GitHub by GitHub. Its guidelines are a collection of open source principles, standards, and recommendations for designing GitHub. As a design language, Primer provides common grammar and vocabulary to build cohesive, accessible, responsive, and efficient experiences.
-</Box>
-
## A cohesive experience
GitHub has a global audience. Millions of people use GitHub every day for many different reasons, in many different ways. They all come from different backgrounds. We can’t infer their physical or cognitive abilities, or devices they use, or the internet connection they have. All of that needs to be taken into account before, during, and after the design process.
@@ -71,4 +65,4 @@ More details about the zen of GitHub can be found in [@kneath](https://github.co
- Favor focus over features
- Avoid administrative distraction
- Design for failure
-- Keep it logically awesome
\ No newline at end of file
+- Keep it logically awesome
diff --git a/content/foundations/typography.mdx b/content/foundations/typography.mdx
index 79529e8..73c7e11 100644
--- a/content/foundations/typography.mdx
+++ b/content/foundations/typography.mdx
@@ -1,5 +1,6 @@
---
title: Typography
+description: These guidelines summarize how we use typography at GitHub, and serve as guardrails for designers to design freely with best typographic practices in mind.
---
import segoeImage from '../../src/images/segoe.svg'
@@ -7,9 +8,6 @@ import sfImage from '../../src/images/sf.svg'
import sfMonoImage from '../../src/images/sfMono.svg'
import interImage from '../../src/images/interUI.svg'
import ubuntuImage from '../../src/images/ubuntu.svg'
-import {Box} from '@primer/react'
-
-These guidelines summarize how we use typography at GitHub, and serve as guardrails for designers to design freely with best typographic practices in mind.
## Typefaces
@@ -20,7 +18,7 @@ The first three typefaces listed below are the most commonly utilized system-fon
| Example | Description |
| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <img src={sfImage} alt="San Francisco" width="1000" /> | [San Francisco](https://developer.apple.com/fonts/) is a neo-grotesque sans-serif typeface designed by Apple to replace Helvetica Neue for OSX and iOS |
-| <img src={segoeImage} alt="Segoe" width="1000" /> | [Segoe UI](https://developer.microsoft.com/en-us/fabric#/resources) is a humanist sans-serif adopted by Microsoft as its default operating system font since Windows Vista |
+| <img src={segoeImage} alt="Segoe" width="1000" /> | [Segoe UI](https://developer.microsoft.com/en-us/fabric#/resources) is a humanist sans-serif adopted by Microsoft as its default operating system font since Windows Vista |
| <img src={ubuntuImage} alt="Ubuntu" width="1000" /> | [Ubuntu](https://design.ubuntu.com/font/) is an OpenType-based, humanist sans-serif typeface. It became the default system font for Ubuntu 10.10 and is commonly used on Linux distros |
| <img src={interImage} alt="Inter" width="1000" /> | [Inter UI](https://rsms.me/inter/) is a typeface designed by Rasmus Andersson specially for user interfaces. Inter UI is used in our products as a display face in select circumstances |
| <img src={sfMonoImage} alt="SF Mono" width="1000" /> | [SF Mono](https://developer.apple.com/fonts/) is a monospace typeface that is part of the San Francisco typeface family. SF Mono is monospaced across weights, so resetting SF Mono text into another font weight will not cause text to reflow |
diff --git a/content/ui-patterns/button-usage.mdx b/content/ui-patterns/button-usage.mdx
index 8a1d3ee..0779fd5 100644
--- a/content/ui-patterns/button-usage.mdx
+++ b/content/ui-patterns/button-usage.mdx
@@ -1,8 +1,9 @@
---
title: Button usage
+description: These guidelines summarize how GitHub implements buttons across our products.
---
-These guidelines summarize how GitHub implements buttons across our products. We have standardized buttons documented on [Primer CSS](https://primer.style/css/) and [Primer Components](https://primer.style/components), and these docs which serve as the source of truth for development implementation. This article serves to supplement our technical docs with proper guidance on design implementation.
+We have standardized buttons documented on [Primer CSS](https://primer.style/css/) and [Primer Components](https://primer.style/components), and these docs which serve as the source of truth for development implementation. This article serves to supplement our technical docs with proper guidance on design implementation.
## Types
@@ -50,11 +51,11 @@ In certain scenarios, buttons require supporting text to give the user more cont
## Sizes
-| Size | Usage |
-| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Medium | The default button size |
-| Small | Decrease button size when space is limited and the action is of lesser significance. |
-| Large | Increase button size to bring prominence to buttons that have major impact. Use large buttons sparingly, as layouts should generally have only one large button. |
+| Size | Usage |
+| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Medium | The default button size |
+| Small | Decrease button size when space is limited and the action is of lesser significance. |
+| Large | Increase button size to bring prominence to buttons that have major impact. Use large buttons sparingly, as layouts should generally have only one large button. |
## Alignments
diff --git a/content/ui-patterns/empty-states.mdx b/content/ui-patterns/empty-states.mdx
index f749de3..431a974 100644
--- a/content/ui-patterns/empty-states.mdx
+++ b/content/ui-patterns/empty-states.mdx
@@ -1,10 +1,9 @@
---
title: Empty states
+description: Empty states are used to fill spaces when no content has been added yet, or is temporarily empty due to the nature of the feature.
---
-import {Box, Text} from '@primer/react'
-
-Empty states are used to fill spaces when no content has been added yet, or is temporarily empty due to the nature of the feature. These guidelines demonstrate best practices for using the Blankslate component and designing empty states. If you're looking for guidelines on implementation, please refer to [Primer CSS](https://primer.style/css/components/blankslate).
+These guidelines demonstrate best practices for using the Blankslate component and designing empty states. If you're looking for guidelines on implementation, please refer to [Primer CSS](https://primer.style/css/components/blankslate).
## The Blankslate component
diff --git a/content/ui-patterns/feature-onboarding.mdx b/content/ui-patterns/feature-onboarding.mdx
index 55a4610..21ea846 100644
--- a/content/ui-patterns/feature-onboarding.mdx
+++ b/content/ui-patterns/feature-onboarding.mdx
@@ -1,11 +1,10 @@
---
title: Feature onboarding
+description: Onboarding is a virtual unboxing experience that helps users get started with a feature. This is a guide for designing onboarding for the product and does not include what to do for marketing pages, email announcements, social media, etc.
---
import {Box} from '@primer/react'
-Onboarding is a virtual unboxing experience that helps users get started with a feature. This is a guide for designing onboarding for the product and does not include what to do for marketing pages, email announcements, social media, etc.
-
Check out the feature onboarding Figma [sticker sheet](https://www.figma.com/file/FJtZyBeBfwDkByHPfDSN6k/Feature-onboarding?node-id=857%3A6).
When designing a feature onboarding flow, remember to:
diff --git a/content/ui-patterns/forms.mdx b/content/ui-patterns/forms.mdx
index dbae003..5d55cd2 100644
--- a/content/ui-patterns/forms.mdx
+++ b/content/ui-patterns/forms.mdx
@@ -1,13 +1,9 @@
---
title: Forms
+description: Primer's form design guidelines aim to minimize the effort and cognitive load required to complete a task that requires data input from the user. For example, creating a new repo configuring settings, and logging in.
---
-import {Box, Heading, Link} from '@primer/react'
-
-<Box sx={{fontSize: 3}} class="lead" as="p">
- Primer's form design guidelines aim to minimize the effort and cognitive load required to complete a task that
- requires data input from the user. For example: creating a new repo, configuring settings, and logging in.
-</Box>
+import {Box, Heading} from '@primer/react'
## Form control anatomy
diff --git a/content/ui-patterns/messaging.mdx b/content/ui-patterns/messaging.mdx
index 9203b4d..27d401c 100644
--- a/content/ui-patterns/messaging.mdx
+++ b/content/ui-patterns/messaging.mdx
@@ -1,11 +1,10 @@
---
title: Messaging
+description: Messaging components are used to provide important and relevant information to the user, including feedback, contextual information, product updates, and more.
---
import {Box} from '@primer/react'
-Messaging components are used to provide important and relevant information to the user, including feedback, contextual information, product updates, and more.
-
Primer includes three different messaging components:
- [Toasts](https://primer.style/css/components/toasts)
diff --git a/content/ui-patterns/progressive-disclosure.mdx b/content/ui-patterns/progressive-disclosure.mdx
index c4aae48..bdd8e64 100644
--- a/content/ui-patterns/progressive-disclosure.mdx
+++ b/content/ui-patterns/progressive-disclosure.mdx
@@ -1,11 +1,10 @@
---
title: Progressive disclosure
+description: These guidelines summarize how GitHub implements progressive disclosure—an interaction design pattern that hides/shows information—as well as guiding principles, best practices, and implementation support.
---
import {Box} from '@primer/react'
-These guidelines summarize how GitHub implements progressive disclosure—an interaction design pattern that hides/shows information—as well as guiding principles, best practices, and implementation support.
-
## Guiding principles
### Maintain context for users
diff --git a/content/ui-patterns/saving.mdx b/content/ui-patterns/saving.mdx
index 50a1d19..f71b519 100644
--- a/content/ui-patterns/saving.mdx
+++ b/content/ui-patterns/saving.mdx
@@ -1,13 +1,10 @@
---
title: Saving
+description: Save patterns help users store and update their content and configuration throughout GitHub. These changes should be represented in the UI accurately, quickly, and obviously. Their behavior should inspire confidence and trust.
---
import {Box, Text} from '@primer/react'
-<Box sx={{fontSize: 3}} class="lead" as="p">
- Save patterns help users store and update their content and configuration throughout GitHub. These changes should be represented in the UI accurately, quickly, and obviously. Their behavior should inspire confidence and trust.
-</Box>
-
## Explicit saving
When designing a form, start with an explicit saving pattern. Avoid mixing explicit and automatic save patterns on a single page with multiple forms, and never mix save patterns in a single form. For example: if I upload a profile photo in the "Public profile" form, that change should not be saved until I explicitly submit the whole form.
@@ -18,11 +15,17 @@ If there is an error saving the data, the user's data should be preserved in the
<DoDontContainer>
<Do>
- <img alt="A form broken into two sections where one section has a dropdown that automatically saves" src="https://user-images.githubusercontent.com/2313998/159594852-aa1223c7-201e-42ea-9109-649371709d22.png" />
+ <img
+ alt="A form broken into two sections where one section has a dropdown that automatically saves"
+ src="https://user-images.githubusercontent.com/2313998/159594852-aa1223c7-201e-42ea-9109-649371709d22.png"
+ />
<Caption>Separate auto-saving controls from an explicitly saved form</Caption>
</Do>
<Dont>
- <img alt="A form with a single section and it contains a dropdown that automatically saves" src="https://user-images.githubusercontent.com/2313998/159594854-8edb9736-bdd1-436c-a327-8525b6ddac0c.png" />
+ <img
+ alt="A form with a single section and it contains a dropdown that automatically saves"
+ src="https://user-images.githubusercontent.com/2313998/159594854-8edb9736-bdd1-436c-a327-8525b6ddac0c.png"
+ />
<Caption>Don't mix auto-saving controls and explicitly saved controls in the same form</Caption>
</Dont>
</DoDontContainer>
@@ -59,7 +62,6 @@ There are a few issues to bear in mind with autosaving declarative controls.
- Radio button groups: Screenreader users can't read the options without selecting them, which could accidentally apply a selection the user didn't want.
- Browser-native `<select>` dropdowns: Similarly to radio button groups, options could be selected when a user focuses the select and uses the arrow keys to read through each option.
-
### Calls to action
When data is not automatically saved after the user makes changes, buttons are used to submit or cancel the changes.
@@ -69,6 +71,7 @@ When data is not automatically saved after the user makes changes, buttons are u
All configuration flows should have calls to action that include an obvious active verb such as "Create", "Save", "Delete", or "Update" (for example, "Create" a new repository, "Add" an SSH key to your profile, "Save" security preferences, "Update" a repository's description, "Delete" an old email address).
When defining these calls to actions, make sure to:
+
1. Keep the text as succinct and clear as possible
2. Add the item’s name to the button text in cases where it may be unclear to the user what is being changed
@@ -91,27 +94,40 @@ When defining these calls to actions, make sure to:
For more guidance on button usage, see the [button interface guidelines](/ui-patterns/button-usage).
-<Box mb={3} display="flex" alignItems="flex-start" justifyContent="space-between" flexDirection={["column", "column", "column", "column", "row"]} sx={{gap: 3}}>
- <Box mb={3} display="flex" alignItems="center" flexDirection="column" mx="auto" sx={{gap: 2}}>
- <img
- width="456"
- src="https://user-images.githubusercontent.com/2313998/152432687-e119f44c-9325-4ae7-b277-e8559a4eb37b.png"
- />
- <Text as="p" mt="0" align="center" fontSize={1}>Controls all belong to one form</Text>
- <img
- width="456"
- alt="A small form in a dialog that has 'Cancel' and 'Save' buttons at the bottom right"
- src="https://user-images.githubusercontent.com/2313998/151623724-d59d5967-5484-4e81-a4c2-1109409956ee.png"
- />
- <Text as="p" mt="0" align="center" fontSize={1}>A form with a button to save and a button to cancel</Text>
- </Box>
- <Box mb={3} display="flex" alignItems="center" flexDirection="column" mx="auto" sx={{gap: 2}}>
- <img
- width="456"
- src="https://user-images.githubusercontent.com/2313998/152432688-e74f67b2-a777-4c5f-be45-37a43615e6ab.png"
- />
- <Text as="p" mt="0" align="center" fontSize={1}>Controls divided into multiple sections</Text>
- </Box>
+<Box
+ mb={3}
+ display="flex"
+ alignItems="flex-start"
+ justifyContent="space-between"
+ flexDirection={['column', 'column', 'column', 'column', 'row']}
+ sx={{gap: 3}}
+>
+ <Box mb={3} display="flex" alignItems="center" flexDirection="column" mx="auto" sx={{gap: 2}}>
+ <img
+ width="456"
+ src="https://user-images.githubusercontent.com/2313998/152432687-e119f44c-9325-4ae7-b277-e8559a4eb37b.png"
+ />
+ <Text as="p" mt="0" align="center" fontSize={1}>
+ Controls all belong to one form
+ </Text>
+ <img
+ width="456"
+ alt="A small form in a dialog that has 'Cancel' and 'Save' buttons at the bottom right"
+ src="https://user-images.githubusercontent.com/2313998/151623724-d59d5967-5484-4e81-a4c2-1109409956ee.png"
+ />
+ <Text as="p" mt="0" align="center" fontSize={1}>
+ A form with a button to save and a button to cancel
+ </Text>
+ </Box>
+ <Box mb={3} display="flex" alignItems="center" flexDirection="column" mx="auto" sx={{gap: 2}}>
+ <img
+ width="456"
+ src="https://user-images.githubusercontent.com/2313998/152432688-e74f67b2-a777-4c5f-be45-37a43615e6ab.png"
+ />
+ <Text as="p" mt="0" align="center" fontSize={1}>
+ Controls divided into multiple sections
+ </Text>
+ </Box>
</Box>
#### State
@@ -131,7 +147,7 @@ Do not disable or hide a form's save button even if the form is invalid or has n
#### Placement
-Place save buttons somewhere intuitive and easily accessible.
+Place save buttons somewhere intuitive and easily accessible.
- There should only be one save button on a page.
- Place save buttons somewhere intuitive and easily accessible. If all of the fields save automatically, do not include a save button. This makes it unclear when data is being saved. See the guidelines on [explicit saving](#explicit-saving) and [automatic saving](#automatic-saving) for more information.
@@ -139,11 +155,17 @@ Place save buttons somewhere intuitive and easily accessible.
<DoDontContainer>
<Do>
- <img alt="A form with one save button at the bottom" src="https://user-images.githubusercontent.com/2313998/151887934-cfcc5130-53a8-4f40-ba36-97148ead72c0.png" />
+ <img
+ alt="A form with one save button at the bottom"
+ src="https://user-images.githubusercontent.com/2313998/151887934-cfcc5130-53a8-4f40-ba36-97148ead72c0.png"
+ />
<Caption>Have one save button per form</Caption>
</Do>
<Dont>
- <img alt="A form with two sections. Each section has it's own save button." src="https://user-images.githubusercontent.com/2313998/151887938-1fa6b5d7-c5c1-4010-ab99-e5c37bff8c0a.png" />
+ <img
+ alt="A form with two sections. Each section has it's own save button."
+ src="https://user-images.githubusercontent.com/2313998/151887938-1fa6b5d7-c5c1-4010-ab99-e5c37bff8c0a.png"
+ />
<Caption>Don't have one save button per section of a form</Caption>
</Dont>
</DoDontContainer>
@@ -152,40 +174,65 @@ Place save buttons somewhere intuitive and easily accessible.
If there is a button to submit and a button to cancel, the cancel button should go to the **right** of the submit button.
-<Box mb={3} display="flex" alignItems="flex-start" flexDirection={["column", "column", "column", "column", "row"]} sx={{gap: 3}}>
- <img
- width="456"
- alt="A form with the controls and save button left aligned"
- src="https://user-images.githubusercontent.com/2313998/155623608-440c8f2c-dbb1-4b3c-a76e-7f01af63b3a8.png"
- />
- <Box as="p" mt="0">Default to placing the submit button at the bottom left of the form. Labels and inputs are left-aligned and run from top-to-bottom, so users would naturally move their eyes down and to the left.</Box>
+<Box
+ mb={3}
+ display="flex"
+ alignItems="flex-start"
+ flexDirection={['column', 'column', 'column', 'column', 'row']}
+ sx={{gap: 3}}
+>
+ <img
+ width="456"
+ alt="A form with the controls and save button left aligned"
+ src="https://user-images.githubusercontent.com/2313998/155623608-440c8f2c-dbb1-4b3c-a76e-7f01af63b3a8.png"
+ />
+ <Box as="p" mt="0">
+ Default to placing the submit button at the bottom left of the form. Labels and inputs are left-aligned and run from
+ top-to-bottom, so users would naturally move their eyes down and to the left.
+ </Box>
</Box>
##### Bottom-right (dialogs and comments)
If there is a button to submit and a button to cancel, the button to cancel should go to the **left** of the submit button.
-<Box mb={3} display="flex" alignItems="flex-start" flexDirection={["column", "column", "column", "column", "row"]} sx={{gap: 3}}>
- <img
- width="456"
- alt="A small form in a dialog that has 'Cancel' and 'Save' buttons at the bottom right"
- src="https://user-images.githubusercontent.com/2313998/151623724-d59d5967-5484-4e81-a4c2-1109409956ee.png"
- />
- <Box as="p" mt="0">If the save button is used in a dialog, place the button at the bottom right of the dialog. Right-aligned dialog buttons feel familiar because it's a common pattern across various platforms such as Windows, macOS, and Android.</Box>
+<Box
+ mb={3}
+ display="flex"
+ alignItems="flex-start"
+ flexDirection={['column', 'column', 'column', 'column', 'row']}
+ sx={{gap: 3}}
+>
+ <img
+ width="456"
+ alt="A small form in a dialog that has 'Cancel' and 'Save' buttons at the bottom right"
+ src="https://user-images.githubusercontent.com/2313998/151623724-d59d5967-5484-4e81-a4c2-1109409956ee.png"
+ />
+ <Box as="p" mt="0">
+ If the save button is used in a dialog, place the button at the bottom right of the dialog. Right-aligned dialog
+ buttons feel familiar because it's a common pattern across various platforms such as Windows, macOS, and Android.
+ </Box>
</Box>
-<Box mb={3} display="flex" alignItems="flex-start" flexDirection={["column", "column", "column", "column", "row"]} sx={{gap: 3}}>
- <img
- width="456"
- alt="A multi-line text input with 'Close with Comment' and 'Comment' buttons right-aligned below the input"
- src="https://user-images.githubusercontent.com/2313998/158623777-a4bb25ec-e1a0-4feb-bd56-e46a69c7f768.png"
- />
- <Box as="p" mt="0">
- If the button is used to send a message such as a comment on an issue, right-align the button below the text area. This is where GitHub has traditionally placed the <strong>Submit</strong> button for issues and pull requests, and it's common practice in other apps to place a <strong>Send</strong> button to the right.
- </Box>
+<Box
+ mb={3}
+ display="flex"
+ alignItems="flex-start"
+ flexDirection={['column', 'column', 'column', 'column', 'row']}
+ sx={{gap: 3}}
+>
+ <img
+ width="456"
+ alt="A multi-line text input with 'Close with Comment' and 'Comment' buttons right-aligned below the input"
+ src="https://user-images.githubusercontent.com/2313998/158623777-a4bb25ec-e1a0-4feb-bd56-e46a69c7f768.png"
+ />
+ <Box as="p" mt="0">
+ If the button is used to send a message such as a comment on an issue, right-align the button below the text area.
+ This is where GitHub has traditionally placed the <strong>Submit</strong> button for issues and pull requests, and
+ it's common practice in other apps to place a <strong>Send</strong> button to the right.
+ </Box>
</Box>
-
<!--
TODO:
Consider how we might define more patterns to keep the "Save" button easily accessible on long forms:
@@ -200,9 +247,9 @@ To simplify the interface, some content may be edited inline without taking the
An input used for inline editing should have a save button placed very close to visually connect the input with the button.
<img
- width="960"
- alt="Two images of a pull request header. The first image shows the title as read-only text. The second image shows a text input to edit the pull request title with 'Cancel' and 'Save' buttons below the input."
- src="https://user-images.githubusercontent.com/2313998/158624334-fcd4e268-d144-4420-98ed-819c51631e7e.png"
+ width="960"
+ alt="Two images of a pull request header. The first image shows the title as read-only text. The second image shows a text input to edit the pull request title with 'Cancel' and 'Save' buttons below the input."
+ src="https://user-images.githubusercontent.com/2313998/158624334-fcd4e268-d144-4420-98ed-819c51631e7e.png"
/>
##### Other
@@ -214,26 +261,38 @@ If you believe your submit button will not be intuitive or easily accessible usi
Automatic saving applies changes as they are made. Automatic saving should be used when the user expects instant feedback from the change they made.
<Box mb={3} display="flex" alignItems="center" flexDirection="column" mt={6} mx="auto" sx={{gap: 2, maxWidth: '450px'}}>
- <Box display="inline-block" overflow="hidden" borderWidth="1px" borderColor="border.default" borderStyle="solid" borderRadius="12px">
- <img
- width="456"
- src="https://user-images.githubusercontent.com/2313998/152013139-02eb5213-bb19-4c8d-8b19-01f1d73602d1.gif"
- alt="Opening the 'Watch' dropdown menu and changing. It saves automatically."
- />
- </Box>
- <Text as="p" mt="0" align="center" fontSize={1}>If a form field is saved automatically, it should be obvious whether or not it saved without using text or visual indicators. A visual indicator for whether or not a form field has been saved successfully could be mistaken as a validation status.</Text>
+ <Box
+ display="inline-block"
+ overflow="hidden"
+ borderWidth="1px"
+ borderColor="border.default"
+ borderStyle="solid"
+ borderRadius="12px"
+ >
+ <img
+ width="456"
+ src="https://user-images.githubusercontent.com/2313998/152013139-02eb5213-bb19-4c8d-8b19-01f1d73602d1.gif"
+ alt="Opening the 'Watch' dropdown menu and changing. It saves automatically."
+ />
+ </Box>
+ <Text as="p" mt="0" align="center" fontSize={1}>
+ If a form field is saved automatically, it should be obvious whether or not it saved without using text or visual
+ indicators. A visual indicator for whether or not a form field has been saved successfully could be mistaken as a
+ validation status.
+ </Text>
</Box>
### Imperative controls
To reduce UI and give instant feedback, you should use automatic saving (and not explicit saving) for imperative controls. These are:
+
- [Toggle switches](/components/toggle-switch). The toggle switch behaves like a light switch: the light just switches on and off without you having to confirm each time you flip the switch.
- [Segmented controls](/components/segmented-control). The segmented control behaves like tabs: the tab changes as soon as you select it, and you can only select one at a time.
- Single-select dropdowns that are not native `<select>` dropdowns or part of an explicitly saved form. Single-select dropdowns behave like a radio dial: the station starts playing as soon as you select it.
### Dropdown menu accessibility
-Semantic menus should only have a list of options to select from and should not have a save button in their dropdown. As soon as additional features (search inputs, filters, tabs, etc) are added, the component should be treated like a dialog with a button to submit and a button to cancel.
+Semantic menus should only have a list of options to select from and should not have a save button in their dropdown. As soon as additional features (search inputs, filters, tabs, etc) are added, the component should be treated like a dialog with a button to submit and a button to cancel.
## Feedback
@@ -242,7 +301,10 @@ If the change is not obvious within the user's viewport, provide feedback to let
- If the change occurred without a redirect or page refresh, you can use the [toast component](https://primer.style/design/ui-patterns/messaging#toasts).
- If the change occurred and the page refreshes or redirects, you can use a [flash banner component](https://primer.style/design/ui-patterns/messaging#flash-alerts).
-<Note variant="warning">If your design is being implemented in github.com, avoid using a toast for now. The toast components used on github.com have accessibility issues that need to be fixed.</Note>
+<Note variant="warning">
+ If your design is being implemented in github.com, avoid using a toast for now. The toast components used on
+ github.com have accessibility issues that need to be fixed.
+</Note>
## Error forgiveness
@@ -250,19 +312,34 @@ Before submitting a form with potentially destructive consequences (for example,
For risky changes, provide a way to undo those changes after saving.
-<Box display="flex" alignItems="center" flexDirection="column"mx="auto" sx={{gap: 1}}>
- <Box display="inline-block" overflow="hidden" borderWidth="1px" borderColor="border.default" borderStyle="solid" borderRadius="12px">
- <img width="960" src="https://user-images.githubusercontent.com/2313998/152434199-a067b037-baf8-4093-8796-b0bb58344223.png" />
- </Box>
- <Text as="p" mt="0" align="center" fontSize={1}>After merging a pull request, a button appears to revert the changes</Text>
+<Box display="flex" alignItems="center" flexDirection="column" mx="auto" sx={{gap: 1}}>
+ <Box
+ display="inline-block"
+ overflow="hidden"
+ borderWidth="1px"
+ borderColor="border.default"
+ borderStyle="solid"
+ borderRadius="12px"
+ >
+ <img
+ width="960"
+ src="https://user-images.githubusercontent.com/2313998/152434199-a067b037-baf8-4093-8796-b0bb58344223.png"
+ />
+ </Box>
+ <Text as="p" mt="0" align="center" fontSize={1}>
+ After merging a pull request, a button appears to revert the changes
+ </Text>
</Box>
## Redirecting
When creating new content like issues, discussions, or even larger entities such as repositories or organizations, you may redirect the user to the entity they just created at the end of the flow.
-In some cases, such as forking or using a template, you may need to hold the user at a waiting page while the entity is generated. In these cases, make the user feel confident that something is happening and that their configuration details will not be lost.
+In some cases, such as forking or using a template, you may need to hold the user at a waiting page while the entity is generated. In these cases, make the user feel confident that something is happening and that their configuration details will not be lost.
<Box overflow="hidden" borderWidth="1px" borderColor="border.default" borderStyle="solid" borderRadius="12px">
- <img src="https://user-images.githubusercontent.com/2313998/151446009-58bfb92f-00e1-4a15-a2a3-f1afb6fb4031.gif" alt="Screen recording of a user forking a repository" />
+ <img
+ src="https://user-images.githubusercontent.com/2313998/151446009-58bfb92f-00e1-4a15-a2a3-f1afb6fb4031.gif"
+ alt="Screen recording of a user forking a repository"
+ />
</Box>
--
GitLab