{"data":{"allMdx":{"nodes":[{"fileAbsolutePath":"/home/runner/work/design/design/content/index.mdx","frontmatter":{"title":"Interface guidelines"},"rawBody":"---\ntitle: Interface guidelines\n---\n\nimport {HeroLayout} from '@primer/gatsby-theme-doctocat'\nexport default HeroLayout\n\nPrimer's interface guidelines are a collection of principles, standards, and usage guidelines for designing GitHub\ninterfaces.\n\n#### [Guides](/guides)\n\nStandards, guidelines, and tools to getting started with Primer.\n\n#### [Foundations](/foundations)\n\nThe fundamental parts of the design system that underpin all GitHub interfaces, such as color and typography.\n\n#### [UI patterns](/ui-patterns)\n\nDesign guidelines covering common user workflows.\n\n#### [Components](/components)\n\nDesign and usage guidelines for individual Primer components.\n\n## Need help?\n\nIf you found a bug on this website, please [open a new issue](https://github.com/primer/issues/new) with as much detail as possible, including steps to replicate the bug, screenshots, links, and expected results.\n\nIf you need help using and designing with Primer, and you are GitHub staff, please visit the #primer Slack channel.\n","parent":{"relativeDirectory":"","name":"index"}},{"fileAbsolutePath":"/home/runner/work/design/design/content/components/action-bar.mdx","frontmatter":{"title":"Action bar"},"rawBody":"---\ntitle: Action bar\nstatus: Experimental\ndescription: Action bar contains a collection of horizontally aligned icon buttons.\nfigma: https://www.figma.com/file/GCvY3Qv8czRgZgvl1dG6lp/Primer-Web?node-id=17042%3A65285&t=SjYdIZSMZa38r2ZU-1\n---\n\nimport {Box, Text} from '@primer/react'\nimport ComponentLayout from '~/src/layouts/component-layout'\nexport default ComponentLayout\n\n## Usage\n\nUse an action bar to render multiple icon buttons in a row. Buttons can be split into groups by adding a divider. When there is not enough space, buttons that don't fit will be added to an overflow menu.\n\n## Anatomy\n\n\n\n## Content\n\n### Buttons\n\nAn action bar should only contain icon buttons with the `invisible` variant (no border/background).\n\n\n \n \n Use only invisible icon buttons in an action bar.\n \n \n \n Don't use other variants or components in an action bar.\n \n\n\n### Dividers\n\nDividers can be added to visually group related buttons.\n\n\n \n \n Use a divider between buttons.\n \n \n \n Don't use a divider at the beginning or end of the action bar.\n \n\n\n### Overflow menu\n\nWhen the buttons don't fit in the available space, an overflow button (\"kebab\" icon) is added at the end of the action bar signaling that there are more actions available. Clicking on the overflow button opens a menu with the remaining actions that didn't fit.\n\n\n\n#### Sorting\n\nButtons that don't fit are added to the top of the menu. Meaning that the last button in the action bar will also be the last button when inside the menu:\n\n\n\n#### Demo\n\n\nOverflow button appears when not enough space and resizing the action bar updates the overflow menu.\n\n## States\n\n### Button states\n\nButtons in action bars are solely used for triggering actions. Consider using a [segmented control](/components/segmented-control) when a button should have a selected state.\n\n\n \n \n \n Buttons in action bars have a hover and pressed state, and a focused state when using a keyboard to navigate.\n \n \n \n \n Don't add a selected state or any other information like a notification dot or a counter.\n \n\n\n### Tooltips\n\nWhen hovering over a button, a tooltip will appear that describes the action.\n\n\n \n \n Describe what action will be taken when clicking on the button.\n \n \n \n Don't use a tooltip in action bars to convey a current state.\n \n\n\n## Options\n\n### Size\n\nAction bars can have 3 different sizes:\n\n\n\n- Small (`28px`)\n- Medium (`32px`) (default)\n- Large (`40px`)\n\n## Layout\n\nAction bars can be used inline next to other content or also full width taking up the entire space.\n\n\n \n\n\n### Spacing\n\nMake sure to add extra spacing around the action bar.\n\n\n \n \n Extra padding of 8px is added when nesting an action bar in a box component.\n \n \n \n \n Avoid having the action bar touch something else. Even though the action bar buttons have no borders in their\n resting state, when hovering/pressing a button it will show a background color.\n \n \n\n\n## Accessibility\n\n### Role\n\nAn action bar has an ARIA role of [`toolbar`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/toolbar_role).\n\n### Keyboard navigation\n\n| Key | description |\n| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `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. |\n| `→` | Right arrow moves focus to the **next** button. If the last button has focus, focus loops back to the first button. |\n| `←` | Left arrow moves focus to the **previous** button. If the first button has focus, focus moves to the last button. |\n| `Home` | Moves focus to the **first** button. |\n| `End` | Moves focus to the **last** button. |\n| `Enter` or `Space` | Triggers the button **action**. |\n\n\n\n### Touch targets\n\n\n \n Ensure action bar buttons have a large enough touch target size (44px by 44px). The buttons should respond to\n hovers, clicks, and taps anywhere in the touch target area, even if it isn't directly on the control. To avoid\n overlapping of touch targets, additional space between each button is needed (for example a 12px gap for medium\n sized buttons).\n \n \n\n","parent":{"relativeDirectory":"components","name":"action-bar"}},{"fileAbsolutePath":"/home/runner/work/design/design/content/components/action-list.mdx","frontmatter":{"title":"Action list"},"rawBody":"---\ntitle: Action list\nreactId: action_list\nfigma: https://www.figma.com/file/GCvY3Qv8czRgZgvl1dG6lp/Primer-Web?node-id=1927%3A0\ndescription:\n Action list is a vertical list of interactive actions or options. It's composed of items presented in a consistent.\n single-column format, with room for icons, descriptions, side information, and other rich visuals.\n---\n\nimport {Box, Button, Heading, Link} from '@primer/react'\nimport ComponentLayout from '~/src/layouts/component-layout'\nexport default ComponentLayout\n\n\n \n\n\n## Overview\n\nAction lists can have many applications:\n\n- They’re the foundation of menus, selection panels, and other overlay components\n- They can be applied to page sidebars for showing individual actions, handling local navigation, and displaying metadata\n\nAction lists support section dividers and headers for grouping items, and individual item dividers for added clarity.\n\nAction lists use a mobile-friendly inset style. Their sizes are adapted on touch devices, and their single-column format should render consistently in any screen size.\n\nItems in an action list are generally interactive, and respond visually to `hover`, `active`, and `focus` states. Disabled and read-only items are also supported.\n\n## Anatomy\n\nAn action list can be composed of:\n\n- Action list items\n- Item dividers\n- Section headers (subtle or filled styles)\n- Section dividers (subtle or filled styles)\n\n\n\n\n\n## Options\n\n\n \n \n \n \n Sizes\n Action list items support three different sizes: small, medium, and large. The small size is the default and most common option. Medium sizes work well for relaxed local navigation, while large sizes can support items that need more breathing room.\n Sizes only grow vertically. This behavior keeps the content aligned among items, and retains horizontal space for density.\n On touch devices, the large size is used at all times to ensure usability when tapping.\n Be cautious when mixing different sizes in the same list to avoid inconsistency.\n \n \n \n \n Use leading visuals to represent system sections, features, or options.\n \n \n \n Use leading visuals in important menu items.\n \n \n \n Use leading visuals to represent content types.\n \n \n \n Leading visual\n Leading visuals are optional and appear at the start of an item. They can be octicons, avatars, and other custom visuals that fit a small area.\n When listing system sections, features, or options, use leading visuals to improve the items' scannability. In user-generated objects, they can help to indicate the item's content type and status.\n Depending on the context, displaying a leading visual may not be necessary. For example, a list of branches in a select panel may not need repeated icons if the surrounding UI provides enough hints about its content type.\n \n \n \n \n A right arrow as a trailing visual indicates there are more options to choose after selecting an item.\n \n \n \n Trailing text with custom styling to indicate diff change.\n \n \n \n Trailing visual and trailing text\n Trailing visual and trailing text can display auxiliary information. They're placed at the right of the item, and can denote status, keyboard shortcuts, or be used to set expectations about what the action does.\n Note these side visuals don't have dedicated interaction targets.\n \n\nUse an [`arrow-right`](https://primer.style/octicons/arrow-right-16) octicon in menus to indicate the action will open more options, such as in a nested context. Use a [`pencil`](https://primer.style/octicons/pencil-16) octicon to indicate the item is going to be edited after clicking it.\n\n\n Custom trailing elements are supported, such as counters, labels, and other custom visuals that may help identify the item.\n When using a trailing text for displaying keyboard shortcuts, always confirm the characters match with the user's operating system. For example, to indicate a bold action in a Markdown toolbar, use \"Ctrl+B\" on Linux and Windows, and \"⌘B\" on Mac. See reference for Mac keyboard glyphs.\n \n \n \n \n \n Trailing actions\n Trailing action buttons can be used to present a secondary interaction related to the contents of the main item, such as opening a menu or dialog. They may appear when an item is hovered, and can be keyboard focused individually.\n \n \n \n \n \n Item dividers\n Item dividers allow users to parse heavier amounts of information. They're placed between items and are useful in complex lists, particularly when descriptions or multi-line text is present.\n When considering whether to use item dividers, make sure they truly make the presented information easier to parse, instead of only increasing visual clutter.\n When using item dividers, increasing the action list item size may also help with legibility.\n \n \n \n \n \n Selection states\n \n\nAction list items can be selected. Single selections are represented with a [`check`](https://primer.style/octicons/check-16) octicon, while multiple selections are represented with a checkbox component. These selection visuals are always placed at the beginning of the item.\n\n\n When listing selectable items alongside non-selectable items in a menu, use dividers to differentiate between the item types.\n Don't mix different types of selections in the same list.\n \n \n \n \n \n Danger items\n An action list item can have a special \"danger\" style, to be used in cases that require extra attention from the user.\n For destructive or irremediable actions, show a confirmation dialog for extra friction. If the action is not destructive, present the user a way to undo the action instead of asking for confirmation. Never use a warning when you mean undo.\n Place danger items at the end of the list.\n \n\n\n## Application\n\n### In overlays\n\n\n
\n \n \"Action\n \n
\n
\n Action menu\n \n\nAction menus are used for disambiguation, navigation, or to display secondary options. They appear when users interact with buttons, actions, or other controls.\n\n[Primer React implementation](https://primer.style/react/ActionMenu)\n\n\n
\n
\n \n \"Action\n \n
\n
\n Action menu with selection\n \n\nActionMenu can be used for making a single selection among a small list of options. The list is usually predefined with system values, but in some cases it can include user-provided data when those are known not to grow into too many items.\n\n[Primer React implementation](https://primer.style/react/ActionMenu#with-selection)\n\n\n
\n
\n \n \"Select\n \n
\n
\n Select panel\n \n\nSelect panels allow manipulating long lists of options, with filtering and other advanced interactions. They can be used for single or multi-selection.\n\n[Primer React implementation](https://primer.style/react/SelectPanel)\n\n\n
\n\n","parent":{"relativeDirectory":"components","name":"action-list"}},{"fileAbsolutePath":"/home/runner/work/design/design/content/components/action-menu.mdx","frontmatter":{"title":"Action menu"},"rawBody":"---\ntitle: Action menu\nreactId: action_menu\nfigma: https://www.figma.com/file/GCvY3Qv8czRgZgvl1dG6lp/Primer-Web?node-id=17091%3A66640\ndescription: Action menu is composed of action list and overlay patterns used for quick actions and selections.\n---\n\nimport {Box, Button, Heading, Link} from '@primer/react'\nimport ComponentLayout from '~/src/layouts/component-layout'\nexport default ComponentLayout\n\n## Usage\n\nAction menu is used for actions, navigation, to display secondary options, or single/multi select lists. They appear when users interact with buttons, actions, or other controls.\n\n## Anatomy\n\n\n\n## Options\n\n\n\n The trigger button can be a standard or icon button. For single select menus that display the selection in the\n trigger, a label must be persist either internally or externally.\n\n\n\nMenus can contain simple actions and links, single select items, or multi select items.\n\n## Behavior\n\n### Opening\n\n\n
\n \n Open by clicking the trigger button with a mouse\n
\n
\n \n Open by focusing the trigger button and hitting return, space, or any arrow key\n
\n\n\n### Closing\n\n#### Default behavior\n\n\n
\n \n \n Close the menu by clicking on an item, clicking on the trigger, or clicking anywhere outside the menu.\n \n
\n
\n \n Close the menu by hitting enter on an item, or esc.\n
\n\n\n#### Single and multi select\n\n\n
\n \n Single select menu closes upon selection and may update the button label.\n
\n
\n \n Multi select menu closes upon selection and can be re-opened to select more options.\n
\n\n\n### Responsive\n\n\n \n \n

Narrow viewports

\n For narrow viewports, ActionMenu should remain anchored to its trigger and stay within the bounds of the viewport.\n \n\n\n## Best practices\n\n\n \n \n Use ActionMenu for quick actions.\n \n \n \n For complex interactions, use SelectPanel.\n \n\n\n\n \n \n Use ActionMenu for simple selection.\n \n \n \n \n Use SelectPanel for a filtered search.\n \n \n\n\n\n \n \n Use a button to open a menu.\n \n \n \n Don’t use a link to open a menu.\n \n\n\n## Accessibility\n\nSee [focus management](/guides/accessibility/focus-management) for more information.\n\n\n \n \n

Menu mnemonics

\n When a menu is open, hitting a letter key for the first letter in an item to be selected will move focus to that item. If\n two items have the same first letter, the first item in the list will be focused first, and hitting the letter key again\n will focus the next item.\n \n\n\n### Keyboard navigation\n\n#### Trigger button\n\n| Key | Description |\n| -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |\n| Enter | Opens the menu. |\n| Space | Opens the menu. |\n| ArrowDown | Opens the menu. |\n| ArrowUp | Opens the menu. |\n| ArrowLeft | Opens the menu. |\n| ArrowRight | Opens the menu. |\n\n#### Menu items\n\n| Key | Description |\n| -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |\n| ArrowUp | Cycle through items starting with current item to previous item |\n| ArrowDown | Cycle through items starting with current item to next item |\n| ArrowLeft | Cycle through items starting with current item to previous item |\n| ArrowRight | Cycle through items starting with current item to next item |\n| Home | Move focus to first item |\n| PageUp | Move focus to first item |\n| End | Move focus to last item |\n| PageDown | Move focus to last item |\n| Esc | Close menu |\n\n## Related components\n\n- [Action list](/components/action-list)\n- [Select panel](https://primer.style/react/SelectPanel)\n","parent":{"relativeDirectory":"components","name":"action-menu"}},{"fileAbsolutePath":"/home/runner/work/design/design/content/components/anchored-overlay.mdx","frontmatter":{"title":"Anchored overlay"},"rawBody":"---\ntitle: Anchored overlay\nreactId: anchored_overlay\nfigma: https://www.figma.com/file/GCvY3Qv8czRgZgvl1dG6lp/Primer-Web?node-id=15528%3A49147\ndescription: Anchored overlay opens an overlay relative to the anchor position.\n---\n\nimport {Box, Button, Heading} from '@primer/react'\nimport ComponentLayout from '~/src/layouts/component-layout'\nexport default ComponentLayout\n\n## Overview\n\nAnchored overlay provides an anchor that will open a floating overlay positioned relative to the anchor. The overlay can be opened and navigated using a keyboard or mouse.\n\nSee also [Overlay positioning](https://primer.style/react/Overlay#positioning)\n\n## Related components\n\n- [Overlay](https://primer.style/react/Overlay)\n\n## Accessibility\n\nThe anchored overlay menu will automatically receive a focus trap and focus zone. Use up/down keys to navigate between buttons.\n","parent":{"relativeDirectory":"components","name":"anchored-overlay"}},{"fileAbsolutePath":"/home/runner/work/design/design/content/components/autocomplete.mdx","frontmatter":{"title":"Autocomplete"},"rawBody":"---\ntitle: Autocomplete\ndescription: Autocomplete allows users to quickly filter through a list of options and pick one or more values for a field.\nreactId: autocomplete\nrails: https://primer.style/view-components/components/beta/autocomplete\nfigma: https://www.figma.com/file/GCvY3Qv8czRgZgvl1dG6lp/Primer-Web?node-id=1927%3A0\n---\n\nimport {Box} from '@primer/react'\nimport ComponentLayout from '~/src/layouts/component-layout'\nexport default ComponentLayout\n\n## Overview\n\nThe autocomplete component is an enhanced text input that makes it easier to choose one or more values from a long list of options. The list of options is displayed when a user focuses the input.\n\n## Anatomy\n\nAutocomplete is made up of a form input field, label, and overlay of menu options. The label is required but may be visually hidden. Optionally, a leading visual and/or clear button may be displayed.\n\n![autocomplete component diagram with an input label stating pick a branch, empty focused input field with a search icon and clear button, and an overlay menu listing search options](https://user-images.githubusercontent.com/18661030/170589956-7c0f2498-b55c-4013-8c99-ef5bc1844218.png)\n\n## Usage\n\n### Text input\n\n![two side by side autocomplete inputs, one showing a single select filled state, and another showing a multi select filled state with clearable tokens](https://user-images.githubusercontent.com/18661030/170590638-b7868803-6558-4df9-b462-20d00420b9f5.png)\n\nThe Autocomplete text input has all the same design functionality and properties as a regular text input including size options, width, leading visual, trailing action, and states. When a single item is selected from the menu, it will display in the input as regular text. If multiple items are selected, they will display as clearable tokens within the input.\n\n### Menu\n\n![two side by side autocomplete inputs focused with open menus. One shows a single select menu, the second shows a multi select menu with checkboxes](https://user-images.githubusercontent.com/18661030/170590641-42b27a3a-799a-4c1e-aaef-774990aed345.png)\n\nThe menu is a list of options for the field's value. It appears as a list in a non-modal dialog that the user may select one or more values from. The menu uses Overlay and ActionList designs for size, structure and interaction.\n\n#### Menu item rendering\n\nBy default, menu items are rendered as a single line of text. The list in the menu is rendered using the [Action List](/action-list) component, so menu items can be rendered with all of the same options as Action List items.\n\n\n \n \n If no options are available based on the search term, the menu will display a message that says \"No selectable\n options\". A concise, custom message may be used in place of the default.\n \n\n\n\n \n \n If a user is not limited to a pre-defined list of options, an additional item can be rendered in the menu to select\n the value that has been typed into the text input.\n \n\n\n\n \n \n A loading indicator should be displayed while the data for the list of options is being populated. The loading\n indicator helps the user understand that the list is not empty, it's just not done loading.\n \n\n\n## Sort and filter behavior\n\n### Sorting\n\nThe order of the items should be ordered in a way that makes it easy for a user to find a specific value. This could mean items may be ranked by how likely a user is to pick that option (for example, ordering labels by the number of times they've been used in that repository), or it could simply be in alphabetical order.\n\nIf multiple values can be selected, the default behavior is to move the selected items to the top of the list after the menu is closed. If this sorting logic is not helpful for your use case, you may override this behavior with a more appropriate sorting logic.\n\n### Filtering\n\nBy default, menu items are filtered based on whether or not they match the value of the text input. The default filter is case-insensitive.\n\nCustom filtering logic can be applied if the default filtering behavior does not make sense for your use case. However, it is strongly discouraged to disable filtering entirely.\n","parent":{"relativeDirectory":"components","name":"autocomplete"}},{"fileAbsolutePath":"/home/runner/work/design/design/content/components/avatar-pair.mdx","frontmatter":{"title":"Avatar pair"},"rawBody":"---\ntitle: Avatar pair\ndescription: Avatar pair is composed of two avatars, one larger one and a smaller one, overlaid slightly.\nreactId: avatar_pair\nfigma: https://www.figma.com/file/GCvY3Qv8czRgZgvl1dG6lp/Primer-Web?node-id=13007%3A40428\n---\n\nimport {Box, Text} from '@primer/react'\nimport ComponentLayout from '~/src/layouts/component-layout'\nexport default ComponentLayout\n\n## Usage\n\n\n\nUse AvatarPair to display two avatars when one is secondary to the other.\n\n## Options\n\nAvatar pair has two parent-child combinations: the parent as the circle and the child as the square, and vice-versa.\n\n\n
\n \n Parent as the circle avatar (human) and child as the square (entity).\n
\n
\n \n Parent as the square avatar (entity) and child as the circle (human).\n
\n\n\n## Related components\n\n- [Avatar](/components/avatar)\n- [Avatar stack](/components/avatar-stack)\n","parent":{"relativeDirectory":"components","name":"avatar-pair"}},{"fileAbsolutePath":"/home/runner/work/design/design/content/components/avatar-stack.mdx","frontmatter":{"title":"Avatar stack"},"rawBody":"---\ntitle: Avatar stack\ndescription: Avatar stack displays two or more avatars in an inline stack.\nreactId: avatar_stack\nfigma: https://www.figma.com/file/GCvY3Qv8czRgZgvl1dG6lp/Primer-Web?node-id=13007%3A40428\n---\n\nimport {Box, Text} from '@primer/react'\nimport ComponentLayout from '~/src/layouts/component-layout'\nexport default ComponentLayout\n\n\n\n## Usage\n\nStacked avatars can be used to show multiple collaborators or participants when there is limited space available. When you hover over the stack, the avatars will reveal themselves.\n\n### Best practices\n\n- Use AvatarStack when space is limited\n- Don’t use AvatarStack if there is adequate space to show 4 avatars or less.\n\n## Anatomy\n\nAvatar stack displays a minimum of 2 avatars and a maximum of 4 avatars.\nOnly the 20px avatar size is currently used in the avatar stack.\n\n## Options\n\n### Alignment\n\nThe default AvatarStack is left-aligned. You can [right-align](https://primer.style/react/AvatarStack#right-aligned) the component for layouts that are better suited for it.\n\n## Related components\n\n- [Avatar](/components/avatar)\n- [Avatar pair](/components/avatar-pair)\n","parent":{"relativeDirectory":"components","name":"avatar-stack"}},{"fileAbsolutePath":"/home/runner/work/design/design/content/components/avatar.mdx","frontmatter":{"title":"Avatar"},"rawBody":"---\ntitle: Avatar\ndescription: Avatar is an image that represents a user or organization.\nreactId: avatar\nfigma: https://www.figma.com/file/GCvY3Qv8czRgZgvl1dG6lp/Primer-Web?node-id=13007%3A40428\n---\n\nimport {Box, Text} from '@primer/react'\nimport ComponentLayout from '~/src/layouts/component-layout'\nexport default ComponentLayout\n\n\n\n## Usage\n\nUse avatars to represent users, organizations, bots, or teams. On GitHub, avatars are either rounded squares or circles.\n\n## Options\n\n### Size\n\nAvatars start at 16px and increment by base-4 until 32px. At 32px, the scale switches to base-8 up to 48px.\n64px is the largest size in this scale.\n\n\n\n### Shape\n\nAvatars appear as two different shapes, each with their own functional purpose.\n\n- **Circle avatars** represent individual people.\n- **Square avatars** represent non-human entities, such as bots, teams, or organizations\n\n## Related components\n\n- [Avatar pair](/components/avatar-pair)\n- [Avatar stack](/components/avatar-stack)\n","parent":{"relativeDirectory":"components","name":"avatar"}},{"fileAbsolutePath":"/home/runner/work/design/design/content/components/box.mdx","frontmatter":{"title":"Box"},"rawBody":"---\ntitle: Box\ndescription: Box is a basic wrapper component for most layout related needs.\nreactId: box\nrails: https://primer.style/view-components/components/box\n---\n\nimport {Box, Text} from '@primer/react'\nimport ComponentLayout from '~/src/layouts/component-layout'\nexport default ComponentLayout\n\n## Usage\n\nThe box component is considered a utility component, as it can be used for something as simple as a rounded corner box.\n\nBy default there are no additional styles, as these can be achieved using styled system props to enable custom theme-aware styling.\n","parent":{"relativeDirectory":"components","name":"box"}},{"fileAbsolutePath":"/home/runner/work/design/design/content/components/branch-name.mdx","frontmatter":{"title":"Branch name"},"rawBody":"---\ntitle: Branch name\ndescription: Branch name is a label-type component rendered as an tag by default that displays the name of a branch.\nreactId: branch_name\nfigma: https://www.figma.com/file/GCvY3Qv8czRgZgvl1dG6lp/Primer-Web?node-id=14855%3A46652\n---\n\nimport {Box, Text} from '@primer/react'\nimport ComponentLayout from '~/src/layouts/component-layout'\nexport default ComponentLayout\n\n\n\n## Usage\n\nUse this component to represent a branch name label and link to its tree.\n\n## Options\n\n### Icon\n\nInclude the branch icon when using the component in isolation and in places where users can’t easily determine whether the label represents a branch from the surrounding context.\n\n\n\n## As a link\n\nBranch name is rendered as a link by default. You can also represent the branch label in plain text.\n\n\n","parent":{"relativeDirectory":"components","name":"branch-name"}},{"fileAbsolutePath":"/home/runner/work/design/design/content/components/breadcrumbs.mdx","frontmatter":{"title":"Breadcrumbs"},"rawBody":"---\ntitle: Breadcrumbs\ndescription: Breadcrumbs display the current page or context within the site, allowing them to navigate different levels of the hierarchy.\nreactId: breadcrumbs\nrails: https://primer.style/view-components/components/beta/breadcrumbs\nfigma: https://www.figma.com/file/GCvY3Qv8czRgZgvl1dG6lp/Primer-Web?node-id=14985%3A47006\n---\n\nimport {Box, Text} from '@primer/react'\nimport ComponentLayout from '~/src/layouts/component-layout'\nexport default ComponentLayout\n\n\n\n## Usage\n\nBreadcrumbs are used to show taxonomical context on pages that are many levels deep in a site’s hierarchy. Breadcrumbs show and link to pages higher up in the ancestry.\n\nBreadcrumbs are most appropriate on pages that:\n\n- Are many levels deep on a site\n- Do not have a section-level navigation\n- May need the ability to quickly go back to the previous (parent) page\n- All items must contain links, with the last item as the user's current context\n\n## Anatomy\n\nBreadcrumbs are made of links (indicating parents), dividers, and the current page. The default breadcrumbs component can be modified to change the number of items within the chain.\n\n\n\nNote: The space between items is set to 0px as the divider has padding built into it.\n\n## Options\n\n### Breadcrumb length\n\nBy default the breadcrumbs component can show up to 10 items within the chain.\n\n\n","parent":{"relativeDirectory":"components","name":"breadcrumbs"}},{"fileAbsolutePath":"/home/runner/work/design/design/content/components/button-group.mdx","frontmatter":{"title":"Button group"},"rawBody":"---\ntitle: Button group\ndescription: Button group renders a series of buttons.\nreactId: button_group\nfigma: https://www.figma.com/file/GCvY3Qv8czRgZgvl1dG6lp/Primer-Web?node-id=20363%3A71038&t=GrA68FvIJRoUaVbl-1\nrails: https://primer.style/view-components/components/beta/buttongroup\n---\n\nimport {Box, Text} from '@primer/react'\nimport ComponentLayout from '~/src/layouts/component-layout'\nexport default ComponentLayout\n\n\n\n## Usage\n\nButtons can be grouped together as individual segments of related actions. \n\nEach segment in a button group is comprised from our default button component and can be visually represented with the same button types and states.\n\nGrouping buttons with a button group is better than rendering buttons close together for the following uses:\n\n- rendering a group of buttons next to one or more buttons\n- grouping multiple sets of buttons\n- saving horizontal space when rendering multiple closely-related buttons\n\n### Best practices\n\n- Use button groups to organize similar functionality. Don't group buttons just because they're close together.\n- For most use-cases, only default button types should be used in button groups. In rare cases, primary buttons can be included in button groups but there should only ever be one primary button (if any) in a button group.\n- Avoid grouping too many buttons together. It could be overwhelming to the user.\n- Do not use a button group to indicate a selection. Use a [segmented control](/components/segmented-control) instead.\n- Do not use a button group as a replacement for tab navigation. \n- Avoid mixing buttons with text labels with icon-only buttons. However, it is acceptable to group a text-labeled button with an icon-only button with a [down-pointing triangle](https://primer.style/design/foundations/icons/triangle-down-16) that opens a dropdown menu of actions related to the button.\n- Do not group an [invisible](/components/button#invisible) button with buttons of another variant.\n\n## Options\n\n### Size\n\nButton groups only support medium (default) and small button sizes.\n\n\n\n### Split buttons with a dropdown\n\nA button group can be shown as a split button with an action on the left and dropdown button with an additional list of actions.\n\n\n\n### Leading and trailing visuals\n\nSimilarly to buttons, button segments can optionally include an icon and/or a counter.\n\n\n\n## Accessibility\n\nA button group does not behave like a [toolbar](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/toolbar_role), so assistive technologies still interpret the buttons as unrelated. The grouping is purely visual.\n\n### Descriptive buttons\n\nLabeling buttons properly lets users know what will happen when they activate the control, lessens errors, and increases confidence.\n\nRead more about [descriptive buttons](/guides/accessibility/descriptive-buttons).\n\n## Related links\n\n- [Button](/components/button)\n\n- [Segmented control](/components/segmented-control)\n\n","parent":{"relativeDirectory":"components","name":"button-group"}},{"fileAbsolutePath":"/home/runner/work/design/design/content/components/button.mdx","frontmatter":{"title":"Button"},"rawBody":"---\ntitle: Button\ndescription: Button is used to initiate actions on a page or form.\nreactId: button\nfigma: https://www.figma.com/file/GCvY3Qv8czRgZgvl1dG6lp/Primer-Web?node-id=136%3A1805&t=Tj1PzACLUAihiXgm-1\nrails: https://primer.style/view-components/components/beta/button\n---\n\nimport {Box, Text} from '@primer/react'\nimport ComponentLayout from '~/src/layouts/component-layout'\nexport default ComponentLayout\n\n\n\n## Usage\n\nButtons allow users to initiate an action or command when clicked or tapped. The button's label or text description indicates the purpose of the action to the user. At GitHub, buttons are a fundamental building block of our products. Most of the time, we use the \"Default\" button type, but other types of buttons may be used to indicate something special about the button's hierarchy or functionality.\n\n## Anatomy\n\n\n\n## Options\n\n### Leading and trailing visuals\n\n\n \n \n

Trailing actions

\n Trailing actions such as dropdown carets are always locked to the end of a button, which is particularly obvious for full width scenarios. If a button is a call-to-action (Submit, Save, Do this™, etc), its contents (visuals and button label) appear center-aligned inside the button container. If a button is used for selecting items (Weeks ▾, Iteration ▾, Sort ▾, Select™ ▾, etc), its contents (visuals and button label) appear left-aligned inside the button container.\n\n \n\n\n\n \n \n

Leading visuals

\n Leading visuals provide additional context for a button label, such as a “search” icon next to the label for a search field submit. Leading visuals always apear locked to the button label, even if the button is full width.\n\n \n\n\n\n \n \n

Trailing visuals

\n Trailing visuals such as counters display additional information about the action or task at hand.\n Trailing visuals always apear locked to the button label, even if the button is full width.\n\n \n\n\n### Sizing and spacing\n\n\n \n \n

Medium (default)

\n Primer buttons are medium sized by default. \n Medium is suitable for most interfaces and is considered the preferred size.\n\n \n\n\n\n \n \n

Small

\n Small buttons may be used when space is limited and if the action is less significant.\n\n \n\n\n\n \n \n

Large

\n Large buttons increase the significance of an action and should be used sparingly. \n More often than not a medium sized button will be more appropriate.\n\n \n\n\n### Color\n\n\n \n \n

Primary

\n Primary buttons represent the highest priority action in a page. There should only ever be one primary button (if any) in a button group, and typically only one primary button should be present in page.\n\n \n\n\n\n \n \n

Secondary

\n Secondary buttons are the default button color scheme and are suitable for more interactions. They can be paired with a primary button to perform a secondary action, or used on their own.\n\n \n\n\n\n \n \n

Invisible

\n Invisible buttons have a transparent background with translucent hover and active states, making them useful for compound components like ActionList.\n\n \n\n\n\n \n \n

Danger

\n Danger buttons should be used sparingly to warn of a destructive action, typically resulting in the opening of a confirmation dialog.\n\n \n\n\n## Best practices\n\n### Primary and outline button usage\n\nLimit primary button usage. Only use one primary button on the page, whenever possible, to indicate its emphasis relative to other actions. Primary buttons have top priority in visual hierarchy, and using too many of them on a single view dilutes their effectiveness.\n\n\n### Button usage\n\n\n \n \n Keep button labels succinct with no line breaks.\n \n \n \n Buttons should never contain line breaks and lose their button shape.\n \n\n\n\n \n \n Use sentence case for labels.\n \n \n \n Don't use all-caps or other text formats.\n \n\n\n\n \n \n Show focus styles on keyboard :focus\n \n \n \n Don't remove default button :focus styles.\n \n\n\n\n \n \n Do place primary buttons at the end of a button group\n \n \n \n Don't place primary buttons at the start of a button group\n \n\n\n\n \n \n Use a primary button with a secondary button\n \n \n \n Don’t place multiple primary buttons together\n \n\n\n## Accessibility\n\n### Descriptive buttons\n\nLabeling buttons properly lets users know what will happen when they activate the control, lessens errors, and increases confidence.\n\nRead more about [descriptive buttons](/guides/accessibility/descriptive-buttons).\n","parent":{"relativeDirectory":"components","name":"button"}},{"fileAbsolutePath":"/home/runner/work/design/design/content/components/checkbox-group.mdx","frontmatter":{"title":"Checkbox group"},"rawBody":"---\ntitle: Checkbox group\ndescription: Checkbox group renders a set of checkboxes.\nreactId: checkbox_group\nfigma: https://www.figma.com/file/GCvY3Qv8czRgZgvl1dG6lp/Primer-Web?node-id=15341%3A47574\n---\n\nimport ComponentLayout from '~/src/layouts/component-layout'\nexport default ComponentLayout\n\n\n\n## Usage\n\nUse checkbox group to allow users to select multiple items from a list of individual items, or to mark one individual item as selected.\n\n### Best practices\n\n- Put checkboxes in a logical order\n- If users are only allowed to select a single option, consider using a [radio group](/components/radio-group) instead\n- Each checkbox's state should be independent from other checkboxes in the group. For example: checking one checkbox should not check or disable any other checkboxes\n\n## Anatomy\n\n\n\n**Label:** A title that labels the group of options and helps users understand the relationship between the options in the group.\n\n**Required indicator:** Indicates that a selection is required.\n\n**Caption:** May be used to provide additional context about the checkbox group when the label alone is not sufficient\n\n**Options:** A list of options represented using [checkboxes](/components/checkbox).\n\n**Validation message:** A message explaining why the selection failed validation. See the [form pattern documentation](../ui-patterns/forms#validation) for more information on form validation patterns.\n\n## Accessibility\n\nOnce a user checks an option from a checkbox group, the result should not be saved or applied until the user has explicitly submitted their input using a \"save\" or \"submit\" button. See the [saving pattern guidelines](../ui-patterns/saving) for more information.\nAlternative: you can use a [toggle switch](/components/toggle-switch) to immediately toggle something on and off as long as it's not in the context of a bigger form that applies other input values when submited\n\n## Related links\n\n- [Forms](../ui-patterns/forms)\n- [Form control](/components/form-control)\n- [Checkbox](/components/checkbox)\n- [Radio](/components/radio)\n- [Radio group](/components/radio-group)\n","parent":{"relativeDirectory":"components","name":"checkbox-group"}},{"fileAbsolutePath":"/home/runner/work/design/design/content/components/checkbox.mdx","frontmatter":{"title":"Checkbox"},"rawBody":"---\ntitle: Checkbox\ndescription: Checkbox is a form control for single and multiple selections.\nreactId: checkbox\nfigma: https://www.figma.com/file/GCvY3Qv8czRgZgvl1dG6lp/Primer-Web?node-id=15341%3A47574\n---\n\nimport ComponentLayout from '~/src/layouts/component-layout'\nexport default ComponentLayout\n\n## Usage\n\nUse checkboxes to allow users to select multiple items from a list of individual items, or to mark one individual item as selected.\n\n### States\n\nCheckboxes have static dimensions and three different states: rest (default), focus, and disabled.\n\n\n\n### Selected states\n\nCheckboxes are capable of showing two forms of selection: checked (left) or indeterminate (right).\n\n\nThe indeterminate state is colored in some browsers (e.g. Safari) and grey in others (e.g. Chrome).\n\n### Best practices\n\n- An individual checkbox should not have its own validation message or style. Instead, show a validation message on the [checkbox group](/components/checkbox-group). For more information, see the [Validation Message](../ui-patterns/forms#validation) section in the Forms documentation.\n- An individual checkbox button cannot be marked as required. Instead, make a selection required using the [checkbox group](/components/checkbox-group). For more information, see the [Required field indicator](../ui-patterns/forms/#required-field-indicator) in the Forms documentation.\n\n## Related links\n\n- [Forms](../ui-patterns/forms)\n- [Form control](/components/form-control)\n- [Checkbox group](/components/checkbox-group)\n- [Radio](/components/radio)\n- [Radio group](/components/radio-group)\n","parent":{"relativeDirectory":"components","name":"checkbox"}},{"fileAbsolutePath":"/home/runner/work/design/design/content/components/comment-box.mdx","frontmatter":{"title":"Comment box"},"rawBody":"---\ntitle: Comment box\nstatus: Experimental\nfigma: https://www.figma.com/file/GCvY3Qv8czRgZgvl1dG6lp/Primer-Web?node-id=17091%3A66640\ndescription: Comment box allows users to write and preview comments.\n---\n\nimport ComponentLayout from '~/src/layouts/component-layout'\nexport default ComponentLayout\n\n## Anatomy\n\n\n\n## Content\n\n### Heading (required)\n\nA heading is shown above the comment box to establish the context and inform users about the purpose of the textarea that follows. The default heading is \"Add a comment\".\n\n\n \n \n Use a different heading depending on the context.\n \n \n \n \n Don't use the term \"Write\". This may create confusion when navigating between the comment box's heading and the \"Write/Preview\" tab nav.\n \n \n\n\nIt's recommended to *always* show a heading to give users a permanent description of the comment box. In case the design doesn't have room for a heading, the `sr-only` class may be added to visually hide the heading.\n\n\n \n \n When the heading needs to be visually hidden, use the placholder text instead.\n \n \n \n Don't visually hide the heading and remove the placholder text.\n \n\n\n### Placeholder text (recommended)\n\nThe placeholder text is meant to give users addtional hints. Keep in mind that it will disappear as soon as users start typing. A placeholder text is not required, but can help suggest CommentBox features specific to a component implementation, such as slash commands. Having a placeholder text also helps with improving usablity and making sure users know where to start typing. The default placeholder text is \"Type your comment here...\".\n\n\n \n \n Use a different placeholder text depending on the context.\n \n \n \n Don't repeat the heading also as placeholder text.\n \n\n\n### Tab nav\n\nA tab nav is used to toggle between write and preview mode. In **write mode** the entered text is rendered as typed (plain text).\n\n\n\nWhen switching to **preview mode** the toolbar disappears and the text is rendered as HTML. Markdown formatting, autolinking and other features are supported as well.\n\n\n\n### Toolbar\n\nThe toolbar provides the comment box with shortcuts to...\n\n- format Markdown\n- @-mention users or reference issues and pull requests\n- insert saved replies\n- attach images and files\n\n\n\nAdditional toolbar items can be added based on context. They appear at the beginning of the toolbar separated with a divider.\n\n\n\n### Textarea\n\nA textarea is used to write the comment. While typing it will automatically resize to fit the content until a certain max height is reached. The textarea can also be manually resized by dragging the handle in the bottom right corner.\n\n\n\nThe default and minimum height is `100px`. For cases where users typically add a lot of content, like issues or pull request descriptions, the textarea can be configured to have an increased initial height:\n\n| Option | value |\n| ----------------- | ------- |\n| `small` (default) | `100px` |\n| `medium` | `300px` |\n| `large` | `500px` |\n\n## Messages\n\nA [flash alert](/ui-patterns/messaging#flash-alerts) is used to inform users about an event related to the comment box. Events include but are not limited to error or warning messages, uploading state or successful actions. The flash alert is shown undertneath the comment box.\n\n\n\n## Responsive behavior\n\nThe comment box's toolbar uses an [action bar](/components/action-bar) under the hood that is responsive by default. Toolbar items that don't fit in the available space are moved to an [overflow menu](/components/action-bar#overflow-menu).\n\n\n\nWhen the available space becomes narrow, the tab nav takes up full width and the toolbar moves to its own row underneath.\n\n\n\n## Example usage\n\nA typical use of the comment box is at the bottom of a timeline or inline when replying to existing comments. Most often there is a cancel and a submit button at the bottom right of the comment box. Pro tips can also be shown to eductate users and help feature discovery.\n\n\n\n## Accessibility\n\n### Keyboard navigation\n\n| Key | description |\n| ----- | -------------------------------------------------------------------------------------------------------------------- |\n| `Tab` | Moves focus between the different parts of the comment box. The order is as follows: 1. tab nav 2. toolbar 3. textarea. |\n\n\n\nNote that tab nav and toolbar ([action bar](/components/action-bar#keyboard-navigation)) have their own keyboard navigation.\n","parent":{"relativeDirectory":"components","name":"comment-box"}},{"fileAbsolutePath":"/home/runner/work/design/design/content/components/counter-label.mdx","frontmatter":{"title":"Counter label"},"rawBody":"---\ntitle: Counter label\ndescription: Counter label is a button with a numbered label accompanied by text.\nreactId: counter_label\nfigma: https://www.figma.com/file/GCvY3Qv8czRgZgvl1dG6lp/Primer-Web?node-id=14919%3A49961\nrails: https://primer.style/view-components/components/beta/counter\n---\n\nimport ComponentLayout from '~/src/layouts/component-layout'\nexport default ComponentLayout\n\n## Usage\n\nUse counter label to add a count to navigational elements and buttons.\n\n\n\n## Accessibility\n\nAlways use counter label with adjacent text that provides supplementary information regarding what the count is for. For instance, Counter should be accompanied with text such as issues or pull requests.\n","parent":{"relativeDirectory":"components","name":"counter-label"}},{"fileAbsolutePath":"/home/runner/work/design/design/content/components/data-table.mdx","frontmatter":{"title":"Data table"},"rawBody":"---\ntitle: Data table\nreactId: data_table\ndescription: Data table is a 2-dimensional data structure where each row is an item, and each column is a data point about the item.\n---\n\nimport ComponentLayout from '~/src/layouts/component-layout'\nexport default ComponentLayout\n\nimport {Box, Heading} from '@primer/react'\n\nThis component is not available in production yet\n\n## Anatomy\n\n\n\n### Table header\n\nThe table header shows contextual information about the table and render controls that affect the table.\n\n- **Title:** A concise label that describes the table and its contents\n- **Subtitle:** A brief description to adds more context for the table when the title alone is not enough\n- **Actions:** Controls that affect the entire table\n- **Filter:** An input used to filter table data to make it easier for the user to focus only on the rows relevant to their task. Even though the filter affects the entire table, it's not considered an \"action\".\n\n### Column headers\n\nA very short label that describes the data in the column.\n\nColumn headers are buttons that sort rows by the column data in ascending or descending order. Sort functionality may be disabled on a column-by-column basis.\n\nThe column that contains row actions does not have a visible column header.\n\n### Row headers\n\nA row header identifies the item being represented in the row. They are typically the first cell in the row, and are visually distinct from the other cells in the row.\n\n### Row actions\n\nActions that affect the item represented in the row.\n\n### Data cells\n\nThe data for each row that is described by its corresponding column header and optional row header.\n\n### Pagination footer\n\nThe pagination footer shows the user where they are in relation to the total number of rows and provides controls for navigating all rows.\n\n## Usage\n\n### When to use a data table\n\n- To navigate a lot of information at once and to make it easy to compare data points between rows or columns\n- If the data is easy to understand when all data points are displayed in a flat hierarchy\n\n### When to use something else\n\n#### Use a list or something else\n\n- When there are columns where the cells will usually be empty\n- If the data is easier to understand with grouping and hierarchy (sections, headings, subheadings, etc.)\n- When rows and columns are only a means of layout\n- For data with longform content such as paragraphs or long lists\n\n#### Use a data grid\n\n- If the primary purpose is to edit or otherwise interact with the cells (like a spreadsheet)\n- If rows or columns support some kind of user interaction\n\n### Best practices\n\n h4': { margin: 0 }}}>\n\n#### Order rows intuitively\n\n
\n\nData should be initially rendered in an intuitive order. For example, starting with the most recently created items.\n\nBy default, sort alphabetically by the first column's content. Rows will be re-ordered as the user updates the sort\nparameters\n\n
\n\n#### Minimize the number of columns\n\nIt's easier to scan many rows than it is to scan many columns. Consider swapping columns and rows when it's unlikely that there will ever be more rows than columns.\n\n#### Adapt column widths when necessary\n\nUse the column width options to appropriately size the columns depending on the content and the available horizontal space.\n\n#### Keep column headers short\n\nColumn headers are short labels used to define the kind of data that is shown in that column.\n\n#### Keep cell content concise\n\nCells should represent data in the shortest possible format. This makes the table easier to scan, and preserves horizontal space.\n\n#### Don't use a single column to show multiple pieces of data\n\nThe column header should accurately represent the data point rendered in the column's cells. It would also be unclear which data point is being used when sorting.\n\n#### Make numbers easier to compare\n\nRight-align numeric values and use the `tabular-num` [font variant](https://developer.mozilla.org/en-US/docs/Web/CSS/font-variant-numeric) when possible.\n\n#### Avoid wrapping or truncation of cell content as much as possible\n\n
\n\nIdeally, the cell content is very short and the column will be wide enough to accommodate its content. In cases where it's not possible to fit the content, you may wrap or truncate the content.\n\nCells that are likely to contain long strings may choose to wrap the content. This is the preferred way to accommodate long content because it doesn't hide the content.\n\nContent truncation is available as a last resort when column widths are set. The full content may be exposed in a tooltip.\n\n
\n\n#### By default, leave empty cells blank\n\nYou may show a message to explain an absence of data. Just don't use a character like “x” or “-”. It creates a weird experience for assistive technologies like screen readers.\n\n#### Use “skeleton” placeholders to indicate loading content\n\n
\n\nThe placeholder should match the real content as closely as possible.Use the following properties to adjust the size and alignment of the placeholder:\n\n- column width\n- alignment\n- whether or not there is a leading visual\n\nDon't worry about whether the text wraps. Ideally, the height of the cell will not change once the data is loaded. However, it wouldn't be possible to know how many lines of text the content wraps to.\n\n
\n\n#### Use pagination to accommodate tables with a large dataset\n\nBy paginating, the user can focus on segments of a large dataset without being overwhelmed. Pagination also helps with performance by reducing the amount of data to be downloaded and the amount of content that needs to be rendered.\n\n#### Don't put too many or too few rows per page\n\n
\n\nIf page length is too short, it would be annoying to browse the data in small segments. If page length is too long, users could get lost or overwhelmed.\n\nThe following factors influence what the ideal page length would be for your use-case:\n\n- Whether rows can be filtered\n- Number of columns\n- Visual complexity of the rendered cells\n- Amount of context needed when reviewing the data\n\nThese factors make it difficult to recommend an “ideal” page size for all use cases, but 20 rows is a good place to start.\n\n
\n\n#### Communicate when the table has no data to show\n\nShow a `Blankslate` component in place of the table\n\n#### Consider small screens\n\n
\n\nSome strategies for adapting the table for narrow viewports include:\n\n- Use the column width options\n- Remove less important columns\n- Scroll horizontally\n\n
\n\n\n\n### Do's and Don'ts\n\n\n \n \n \n Use a data table for data in a flat hierarchical structure\n \n \n \n \n \n Don't use a data table for information that has hierarchical relationships\n \n \n\n\n\n \n \n \n Restrict the data in a column to represent one type of data\n \n \n \n \n \n Don't group data in a column cell that isn't described by the column header\n \n \n\n\n\n \n \n \n Leave the cell blank {`(preferred)`} or show text that explains the absence\n \n \n \n \n \n Don't show a character, icon, or emoji to indicate a cell is empty\n \n \n\n\n\n \n \n \n Allow the title in the page header to act as a table title when appropriate\n \n \n \n \n \n Don't repeat or rephrase the title in the page header as the table title\n \n \n\n\n## Options\n\n### Column widths\n\n\n\n#### Grow (default)\n\nStretch to fill available space, and min width is the width of the widest cell in the column. This is the same behavior as a CSS grid column with the value `minmax(auto, 1fr)`\n\nMay have a min and max width constraint\n\n\n \n\n \n\n\n#### Shrink\n\nStretch to fill available space in the parent **or shrink** to fit in the available space in the parent\n\nMay have a min and max width constraint\n\n\n \n \n\n\n#### Auto\n\nThe column is the width of its widest cell. Not intended for use with columns whose content length varies a lot because a layout shift will occur when the content changes.\n\nMay have a min and max width constraint\n\n\n \n \n\n\n#### Explicit width\n\nWill be exactly that width and will not grow or shrink to fill the parent\n\n\n\n#### Action column\n\nThe action column would not accept a width. Its min-width would be the width of the actions.\n\n#### Filling available space\n\nIf all columns have width constraints set and the row doesn't fill the table container, the difference is added to the width of the last column.\n\n### Cells\n\n\n\n\n\n\n#### Density\n\nOptions:\n\n- **Condensed:** Optimize for showing more information in a smaller area.\n- **Normal (default):** Shows a lot of information in a small area, but provides enough whitespace that the cells won't risk visually running together.\n- **Spacious:** Optimizes readability for tables with visually busy cell content.\n\n\n\n\n\n\n\n\n\n\n\n#### Text alignment\n\n- **Left (default):** Matches natural reading direction of text in right-to-left writing systems.\n- **Right:** Optimizes for comparing column data that is easier to compare when it's right-aligned. Most commonly used for numeric data.\n\n\n\n\n\n\n\n\n\n\n\n#### Content fitting\n\n- Wrapping (default)\n- Single-line truncation\n- Multi-line truncation\n\n\n\n\n\n\n\n\n### Row actions cell options\n\n\n\n\n\n\n\n\n#### 1 action\n\nRow actions are placed in the last column, and they don't require a visible column header\n\n\n\n\n\n\n\n\n\n\n\n#### Multiple actions\n\nIf you have multiple actions for a row, start by pulling them into a dropdown menu.\n\n\n\n\n\n\n\n\n\n\n\n#### 1 primary action, other actions in an overflow\n\nIf one of the actions is heavily used, pull it out for easier access. Do not pull out more than 1 action.\n\n\n\n\n\n\n\n\n## Interactions\n\n### Sorting\n\n\n\n\n If a table is sortable, it must start with one column sorted on page load. Interacting with a column that is already\n sorted will toggle the sort between ascending and descending. If a column is not sorted yet, the first click sorts in\n ascending order.\n\n\n\n\n\n#### States\n\n\n\n\n
  • Unsorted (default)
    • \n
  • Ascending sort active
    • \n
  • Descending sort active
    • \n
  • Sort in progress
    • \n    \n\n\n    \n\n### Filtering\n\n\n\n\n\nA [filter input](/components/filter-input) is used to write a query and only show rows that\nmatch that query.\n\n\n\n\n\n\n## Accessibility\n\n### Labeling and describing the table\n\nThe table must have a title, and can optionally have a subtitle to describe more context. If you encounter a case where there is enough context that the table doesn’t need a visible label, you may hide it so it’s only accessible to assistive technologies.\n\n\n\n\n If you use the table header, the table's title and subtitle will automatically be associated with the table for\n assistive technologies.\n\n\n\n\n\n\n\n\n If your table's title exists somewhere else on the page (for example, in the PageHeader), then you must manually\n associate that contextual information with the table using ARIA.\n\n\n\n\n\n### Labeling actions\n\n\n\n\n\n The row header string will be prepended to the ARIA text of action buttons. For examples, Download {`{row header}`}“,\n “Actions:{`{row header}`}”\n\n\n\n\n\n\n\n\n To handle cases where the row header can be very long, we should give consumers the option to specify a shorter string\n to identify the rows. For example, if an issue title is used as the row header, we could use the issue number instead\n of the full issue title.\n\n\n\n\n\n\n## Related components and patterns\n\n- [ActionBar](/components/action-bar)\n- [Pagination (React implementatiopn)](https://primer.style/react/Pagination)\n","parent":{"relativeDirectory":"components","name":"data-table"}},{"fileAbsolutePath":"/home/runner/work/design/design/content/components/details.mdx","frontmatter":{"title":"Details"},"rawBody":"---\ntitle: Details\ndescription: Details is a styled component to enhance the native behaviors of the
    element.\nreactId: details\nrails: https://primer.style/view-components/components/beta/details\n---\n\nimport ComponentLayout from '~/src/layouts/component-layout'\nexport default ComponentLayout\n\nimport {Box, Text} from '@primer/react'\n\n## Usage\n\nThe details component can reveal additional information by using a button to toggle between hidden and visible. It includes a summary followed by the content that's hidden or visible.\n\nBy default, the information is hidden. When triggered, it expands and displays the information.\n","parent":{"relativeDirectory":"components","name":"details"}},{"fileAbsolutePath":"/home/runner/work/design/design/content/components/dialog.mdx","frontmatter":{"title":"Dialog"},"rawBody":"---\ntitle: Dialog\ndescription:\n Dialog is a floating surface used to display transient content such as confirmation actions, selection options, and\n more.\nreactId: dialog\nrails: https://primer.style/view-components/components/alpha/dialog\n---\n\nimport ComponentLayout from '~/src/layouts/component-layout'\nexport default ComponentLayout\n\nimport {Box} from '@primer/react'\nimport {Caption} from '@primer/gatsby-theme-doctocat'\n\nDialogs can streamline the interface by allowing extra content to be disclosed as needed. Dialogs create a new modality to the user, and can expedite the completion of individual tasks.\n\n## Anatomy\n\n\nAnatomy of a Dialog.\n\n### Header region\n\nThe **header** region provides context for the Dialog. By default, the region supports a title, description, and a close button. Titles and descriptions may wrap to multiple lines if necessary.\n\nThe title is required for all Dialogs, but may be visually hidden for custom scenarios such as a command palette. The close button is required and may **not** be visually hidden. The title has a default size along with a larger option for confirmation dialogs.\n\nThe header region provides a slot for custom content in place of the default title/description, though a title is still required and may be visually hidden. Secondary action icon buttons may be placed next to the close button.\n\n\n
    \n \n Header with the default title variant.\n
    \n
    \n \n Header with large title variant.\n
    \n    \n\n\n
    \n \n Header with custom variant and a secondary action button.\n
    \n
    \n \n Command palette with a visually hidden title.\n
    \n    \n\n### Subheader region\n\nThe subheader region is an optional space for interactive controls. Use it to display a search field, a filter menu, or a local navigation component.\n\n\n
    \n \n Header displaying a subheader with a search field.\n
    \n
    \n \n Header displaying a subheader with a local navigation.\n
    \n    \n\n### Body region\n\nThe body region is the main content of the dialog. It can contain any content that is relevant to the task at hand. The body region is scrollable if the content exceeds the height of the dialog.\n\n\n
    \n \n Body content will scroll vertically if the content exceeds the overall dialog height.\n
    \n
    \n \n The body may contain additional content such as banners and form controls.\n
    \n    \n\n### Footer region\n\nThe footer region may be used to show confirmation actions, navigation links, or specialized actions. Primary actions should be aligned to the right of the footer, and grouped by additional related actions. Secondary actions may be shown aligned to the left side.\n\nIf the content area has overflow scrolling, a divider should be added between the footer and content area. Otherwise, showing a divider is optional.\n\n\nUse buttons in a footer to let the user complete a task.\n\n\n
    \n \n Footer with small buttons aligned to the right.\n
    \n
    \n \n Footer with an auxiliary action aligned to the left.\n
    \n    \n\n### Backdrop\n\nDialog displays with a **backdrop**, which dims the rest of the page. The backdrop is visible when the dialog is centered on the page, or attached to a side as a sheet.\n\nBy default, clicking on the **backdrop** will dismiss the dialog. However, if the dialog contains a form that can have unsaved changes, the **backdrop** won't dismiss the dialog, regardless of the state of the form.\n\n### Spacing\n\nThe edges of dialog are free of text and heavy visuals to visually distinguish the dialog as an elevated surface, alongside its shadow. Content within the body and header should remain within the 16px safe area. However, inner components that have transparent or discrete backgrounds may bleed into the padding for visual alignment.\n\n\n\n 1. A search field in the Subheader region appears closer to the edges. While the search icon remains within the safe\n area.\n
    \n 2. Close button placed `8px` away from the edges. Note that the \"×\" glyph remains within the safe area.\n
    \n 3. Action list items in the Body region.\n
    \n 4. Footer buttons always appear inside the safe area.
    \n\n\n## Size\n\nDialog offers a range of sizes from `small` to `xlarge`, with the default size set to `medium`.\n\nEach 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.\n\nA dialog sizing is constrained by the viewport dimensions. Dialogs will not grow beyond the boundaries of the viewport.\n\nSmall viewports force dialogs to remain small. All dialogs need to work on viewports of at least `320px` of width, and `256px` of height.\n\n### Small\n\n\nSmall dialogs have a width of 320px, and a max height of 256px.\n\n### Medium (default)\n\nMedium is the default size for Dialog and should be used for most tasks such as completing a form or selecting an option from a list. The medium portrait size is suitable for longer lists of items that require more vertical space for the body.\n\n\n\n Medium dialogs have a width of 480px, and a max height of 320px. Medium portrait oriented Dialogs have a width of\n 480px, and a max height of 600px.\n\n\n### Large\n\nLarge dialogs are suitable for content that requires more horizontal space for the body compared to size medium, such as a comment box.\n\n\nLarge dialogs have a width of 640px, and a max height of 432px.\n\n### Extra large\n\nBefore using an extra large dialog, consider whether or not the content would be more appropriate for a new page.\n\n\nExtra large dialogs have a width of 960px, and a max height of 600px.\n\n## Usage\n\n### Keep content simple\n\nDialogs are meant to be interacted with in a single context. Avoid creating a whole page inside a dialog. Prefer single-column layouts that convey a clear goal from the moment the dialog is opened.\n\nHowever, dialogs are powerful tools when creating space for single-context interfaces. When designing a new feature to support a main interface, start by considering if the new feature can be created under a single context.\n\nIf the answer is yes, designing the feature inside a dialog provides an easy way to add responsive support, and avoid deeper navigations. If the answer is no, or if a side navigation is required for the feature, consider designing a new page.\n\n\n \n \n Prefer a single column layout.\n \n \n \n Avoid side navigation within a Dialog.\n \n\n\n### Dialogs should work well on any device\n\nDialogs must adjust their designs to fit in smaller viewports. Make sure the overlay contents work with all supported sizes and input methods.\n\n\n
    \n \n Center aligned dialog becomes fullscreen on narrow viewport.\n
    \n
    \n \n Center aligned dialog becomes a bottom sheet on narrow viewport.\n
    \n    \n\n## Regular-viewport placement\n\n### Centered\n\nBy default, dialog appears centered in the viewport, with a visible backdrop that dims the rest of the window for focus. Centered dialogs are surrounded by a safe area of `16px` between the frame and the viewport for all sizes.\n\n\nDialog centered within a desktop screen.\n\n### Side sheets\n\nSide sheets slide from the right or left edges of the viewport. **Left side sheets are reserved for global navigation drawers. Right side sheets are used for global actions, but can also be considered for quick previews in full-width pages, or configuration panels.**\n\nSide sheets take the entire height of the viewport, and should be used sparingly. Don't use side sheets to present create/edit forms, or flows that may contain a lot of information. For that, use a page instead.\n\n\nLeft aligned side sheet is reserved for global navigation only.\n\n\n\n Right aligned side sheet can be used for global actions, but may also be considered for quick previews or\n configuration panels.\n\n\n## Narrow-viewport placement\n\n### Bottom sheets\n\nA bottom sheet is a variant supported on narrow viewports made to facilitate reachability. dialogs that appear centered in large screens may adapt to appear as a bottom sheet on small screens.\n\nA bottom sheet always dims the rest of the screen for focus and takes up the full width of the viewport. Tapping on the backdrop dismisses the dialog.\n\nUse a bottom to indicate that the user is still in the context of the main page, and that the dialog is a secondary action.\n\n\nBottom sheet in portrait mode.\n\nIn landscape mode, a bottom sheet has a maximum width of `480px`, and is centered horizontally.\n\n\nBottom sheet in landscape mode.\n\n### Full-screen\n\nFull-screen dialogs may be used to present content that needs all the available space on narrow viewports, or to act as a new page without navigating away from the main page. Dialogs that have one or more input fields should always use the full-screen variant.\n\n\nFull-screen Dialog in portrait mode.\n\n## Accessibility\n\nDialog's title and close button are required to ensure an accessible experience for everyone. Further, keyboard and focus behavior must be considered.\n\n### Trigger elements and keyboard focus\n\nDialogs are initially hidden, and can be opened by an element with `role=\"button\"`, called a **trigger**. The role `button` allows the **trigger** to be a relatively complex element, such as an action list item.\n\nDialogs must be fully functional using the keyboard and assistive technology. Pressing `Esc` must dismiss a dialog, also returning focus to the **trigger** that opened it.\n\n\nClicking the backdrop or hitting the `Esc` key should dismiss the dialog.\n\nWhen a dialog is opened, the first interactive element (typically the close button) is focused. For a scenario like a command palette with an `` next to the close button, the `` will recieve focus first. Hitting `Tab` will cycle through all interactive elements within the dialog. To escape the focus trap, hitting the `Esc` key or clicking on the backdrop will close the dialog. While the dialog is open, page scrolling is disabled and becomes `inert`.\n\n\n
    \n \n Dialogs can be triggered by buttons with a mouse click or keypress.\n
    \n
    \n \n The first interactive item inside a dialog is focused when opened.\n
    \n    \n\n\nWhen a dialog is closed, focus is returned to the trigger button.\n","parent":{"relativeDirectory":"components","name":"dialog"}},{"fileAbsolutePath":"/home/runner/work/design/design/content/components/filter-input.mdx","frontmatter":{"title":"Filter input"},"rawBody":"---\ntitle: Filter input\nstatus: Experimental\ndescription: Filter input is an input that provides suggestions through qualifiers and highlights complex filter syntax.\nfigma: https://www.figma.com/file/GCvY3Qv8czRgZgvl1dG6lp/Primer-Web?node-id=1927%3A0\n---\n\nimport {Box, Text} from '@primer/react'\nimport ComponentLayout from '~/src/layouts/component-layout'\nexport default ComponentLayout\n\n\n This component is not available in production yet however multiple teams are currently contributing to this.\n\n\n## Overview\n\nAn input that provides suggestions through qualifiers and highlights complex filter syntax.\n\n## Anatomy\n\n\n\n## Content\n\n### Icon\n\nA filter input allows free form text searching as well as using qualifiers to narrow down your search.\nThe filter input always supports free form text search. This is why you should use the search icon as a leading visual. A filter icon could give the impression that free form text search isn't available.\n\n\n \n \n Use the search icon in a filter input.\n \n \n \n Don't use a filter icon in a filter input.\n \n\n\n### Submit\n\nThere are two ways this component can trigger submission of the input value.\n\n1. Auto update results as the value changes (recommended)\n2. Provide a search button next to the filter input\n\n\n \n \n Auto update results based on when the input value changes.\n \n \n \n Don't add an item to submit the current value.\n \n\n\n### Clear button\n\nThe clear button only appears when there is at least one character entered in the input. When the input is empty the clear button disappears again.\n\n\n \n \n Hide the clear button when the input is empty.\n \n \n \n Don't show the clear button when the input is empty.\n \n\n\nUse an icon instead of a link for clearing the input. This avoids confusion with the value of the input. Especially when the input has a long value that gets close to the clear button a link could be problematic.\n\n\n \n \n Use a circular clear button with an x icon to clear the input.\n \n \n \n Don't use a link for clearing as this could be confused with the text inside the input.\n \n\n\n### Avoid duplication\n\nWhen introducing custom qualifiers it's important to avoid repetitive icons or descriptions to increase readability and reduce noise for screen readers.\n\n\n \n \n \n An input with a value 'pinned:' suggesting 'Application', 'Form submissions', 'Performance', 'Feature requests',\n 'Large data sets' and 'Issues'. All items include a pin board icon and a `Pinned` description.\n \n \n \n \n Don't repeat icons or descriptions that add no additional value.\n \n\n\n### Sorting\n\nThere are two different states that should be considered when providing suggestions:\n\n1. **Default**: You've entered a matching qualifier and get default suggestions. For example: `author:`.\n2. **Narrow down**: You've entered a value after your qualifier to narrow down the suggestions. For example: `author:max`\n\n\n\nWe should always strive to provide as relevant results as possible when dealing with `user`, `organization`, `repository`, `issue`, `pull request` items. This can be done through a mix of considerations:\n\n1. Objects you've interacted with\n2. Organizations you're part of and it's members\n3. Repositories you're part of and it's members\n4. [Approximate string matching](https://en.wikipedia.org/wiki/Approximate_string_matching) (fuzzy)\n\nLet's take the `author:` as an example. While in the `default` state we aren't searching through the authors and want to provide a default list with users.\nIt's crucial we make the suggestions as relevant as possible therefore we rank them based on how often/recently you've interacted with them.\n\nOnce we start narrowing down those results by using `author:max` we enter the `narrow down` state and apply _approximate string matching_ on those suggestions. In this case we still rank users that I've recently interacted with or that are part of my organization/repositories higher.\n\nNot all our infrastructure supports this logic yet. If not available we fall back on alphabetical ordering.\n\nFor static items that only return a handful of suggestions we often can just order items through common sense:\n\n\n\n## Qualifiers\n\nThe filter input comes with a list of predefined qualifiers and prestyled suggestions. This ensures everyone aligns on the same qualifiers as well as on the styling of suggestions.\n\n\n\nEven though custom qualifiers can be added it's important to check if your new qualifier could fit in one of the predefined qualifiers below.\n\n| Icon | Qualifier | Origin | Suggestions | Format | Preview |\n| --------------------------------------------------------------------------------- | ----------------- | ------ | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |\n| [person](https://primer.style/octicons/person-16) | `assignee` | api | `avatar`, `username` and `Full Name` | `username` | [View](https://user-images.githubusercontent.com/980622/207335821-6dcb45dc-1b79-4270-8a78-825acadce8f0.png) |\n| [person](https://primer.style/octicons/person-16) | `author` | api | `avatar`, `username` and `Full Name` | `username` | [View](https://user-images.githubusercontent.com/980622/207335836-1f7766cd-acc6-41c5-921e-9764357d2589.png) |\n| [calendar](https://primer.style/octicons/calendar-16) | `created` | static | `Today`, `Yesterday`, `Last 7 days`, `Last 30 days`, `Oct 19, 2007`, `Before June 4, 2018`, `After June 4, 2018` | `@today`, `@today-1d`,`@today-1w`,`>@today-1m`, `>YYYY-MM-DD`, `YYYY-MM-DD`, `YYYY-MM-DD..YYYY-MM-DD` | [View](https://user-images.githubusercontent.com/980622/207335851-a5f464cc-2e70-4050-8e48-82f71c837389.png) |\n| [repo-forked](https://primer.style/octicons/repo-forked-16) | `fork` | static | `Yes`, `No` | `true`, `false` | [View](https://user-images.githubusercontent.com/980622/207335873-2f6e8519-c2cf-41fb-8560-572c2ee660e2.png) |\n| [apps](https://primer.style/octicons/apps-16) | `is` | static | `Action`, `Code`, `Command`, `Commit`... | `name` | [View](https://user-images.githubusercontent.com/980622/207335878-9877e103-c235-4e03-a306-12cbc4e77f35.png) |\n| [tag](https://primer.style/octicons/tag-16) | `label` | api | `Title`, `Description` and `color`. | `title` | [View](https://user-images.githubusercontent.com/980622/207335883-08f7a9ba-5529-4486-9c24-da8debf562b2.png) |\n| [code](https://primer.style/octicons/code-16) | `language` | static | `C`, `C##`, `C++`, `CoffeeScript`... | `language` | [View](https://user-images.githubusercontent.com/980622/207335891-e63e53e9-b30c-4636-91d2-b9eba239a223.png) |\n| [globe](https://primer.style/octicons/globe-16) | `location` | static | `Amsterdam, Netherlands`, `Bern, Switzerland`... | `\"Amsterdam, Netherlands\"` | [View](https://user-images.githubusercontent.com/980622/207335903-928f9bc7-4772-4166-8a83-8d62a60ff48f.png) |\n| [file-badge](https://primer.style/octicons/file-badge-16) | `license` | static | `BSD Zero Clause License`, `Academic Free License v3.0`... | `cc0-1.0` | [View](https://user-images.githubusercontent.com/980622/207335897-9311c884-0c66-4d10-81b0-a7111405444b.png) |\n| [mention](https://primer.style/octicons/mention-16) | `mentions` | api | `avatar`, `username` and `Full Name`. | `username` | [View](https://user-images.githubusercontent.com/980622/207335907-b58c2ae4-59bf-4594-abca-c85f838b1f3d.png) |\n| [organization](https://primer.style/octicons/organization-16) | `org` | api | `avatar`, `username` and `Full Name` | `username` | [View](https://user-images.githubusercontent.com/980622/207335912-324815e0-eed5-492d-ad69-e070e6d2ffb7.png) |\n| [repo](https://primer.style/octicons/repo-16) | `repo` | api | `avatar`, `username/repo-name` | `username/repo-name` | [View](https://user-images.githubusercontent.com/980622/207335923-f63517ed-eda2-4ed8-a434-7ff25a123d54.png) |\n| [file-directory](https://primer.style/octicons/file-directory-16) | `path` | api | `path` | `path` | [View](https://user-images.githubusercontent.com/980622/207335918-83e9b028-e7f5-48e1-99b0-b68ac7c12d85.png) |\n| [issue-draft](https://primer.style/octicons/issue-draft-16) | `state` (generic) | static | `open`, `merged`, `closed`, `draft` | `open` | [View](https://user-images.githubusercontent.com/980622/207335939-ec2d1c4c-e564-4509-93ca-a4ba05b5c167.png) |\n| [git-pull-request-draft](https://primer.style/octicons/git-pull-request-draft-16) | `state` (pr) | static | `open`, `merged`, `closed`, `draft` | `open` | [View](https://user-images.githubusercontent.com/980622/207335949-e65f3708-65eb-4087-a8f4-c657a0bcd5d6.png) |\n| [issue-draft](https://primer.style/octicons/issue-draft-16) | `state` (issue) | static | `open`, `closed`, `draft` | `open` | [View](https://user-images.githubusercontent.com/980622/207335944-80089848-ffc4-4fbc-8d6b-ed7b00d11fab.png) |\n| [comment-discussion](https://primer.style/octicons/comment-discussion-16) | `comments` | static | `More than 10`, `Less than 10`, `Between 10 and 100`, `100`, | `>100`, `10..100`, `100` | [View](https://user-images.githubusercontent.com/980622/207335844-4b89c9db-1add-4b39-951d-5bee28c2b2d6.png) |\n| [people](https://primer.style/octicons/people-16) | `followers` | static | `More than 10`, `Less than 10`, `Between 10 and 100`, `100` | `>100`, `10..100`, `100` | [View](https://user-images.githubusercontent.com/980622/207335866-81c6cfc6-e619-4624-8fbd-f09d92373b0a.png) |\n| [star](https://primer.style/octicons/star-16) | `stars` | static | `More than 10`, `Less than 10`, `Between 10 and 100`, `100` | `>100`, `10..100`, `100` | [View](https://user-images.githubusercontent.com/980622/207335933-795de5c6-8bb6-414a-bf83-4e34aaa08972.png) |\n| [calendar](https://primer.style/octicons/calendar-16) | `updated` | static | `Today`, `Yesterday`, `Last 7 days`, `Last 30 days`, `Oct 19, 2007`, `Before June 4, 2018`, `After June 4, 2018` | `@today`, `@today-1d`,`@today-1w`,`>@today-1m`, `>YYYY-MM-DD`, `YYYY-MM-DD`, `YYYY-MM-DD..YYYY-MM-DD` | [View](https://user-images.githubusercontent.com/980622/207335954-d669b842-5437-47d3-8589-a3ed67b834c4.png) |\n| [file-code](https://primer.style/octicons/file-code-16) | `extension` | static | `md, Markdown`, `json, JavaScript Object Notation`... | `md` | [View](https://user-images.githubusercontent.com/980622/207335860-7237c64b-f159-4c25-9591-0bbaae7dde51.png) |\n| [people](https://primer.style/octicons/people-16) | `team` | api | `avatars`, `name` and `total members` | `name` | [View](https://user-images.githubusercontent.com/980622/207593729-5f39a33f-277a-4329-bfc1-d75f63bba34e.png) |\n\n⚠️ This list will change a lot over the next month to accomodate different teams.\n\n### Generics\n\nThe `state:` qualifier has multiple variants to improve the experience for specific items:\n\n- `state`: For both pull requests and issues (no icons)\n- `state-pr`: For only pull requests (with icons)\n- `state-issue`: For only issues (with icons)\n\nTherefore it's important to use the correct qualifier as soon as you can determine if you're filtering to pull requests or issues.\n\n\n \n \n Use the `state-pr` variant when filtering pull requests.\n \n \n \n Don't use the `state` variant when filtering pull requests.\n \n\n\n### Highlighting\n\nIf invalid values are used we don't show highlighting.\n\nWhile this applies to all qualifiers we do understand that for the ones that depend on our api endpoints (`users`, `repositories`, `organisations`...) we can't always accurately match every result and therefore while not ideal we always highlight those. For example when not single signed-on to a organisation some repositories might not be returned.\nAlso consider that users might copy paste strings containing qualifiers. In this case you need to run through every qualifier to set the highlight if needed.\n\n\n \n \n Remove highlighting on values when they are invalid.\n\n \n \n \n Don't show highlighting on invalid values.\n \n\n\n### No matches\n\nWhen no matches are found we stop suggesting items through the popover and don't show anything.\nIn rare cases the user could be searching for `format:format` within the content of items they are filtering to and this will still allow them to do so.\n\n\n \n \n Stop suggesting if no matches are found.\n \n \n \n Don't show an empty state when no matches are found.\n \n\n\n### Values with spaces\n\nSome qualifiers like `location:` might have values which contain spaces. eg: 'Amsterdam, Netherlands'. In this case we encapsulate the value between straight quotes (not smart quotes).\n\nWithout this it would be hard for the parser to understand where the value ends.\n\n\n \n \n Use straight quotes around values with spaces.\n \n \n \n Don't use values with spaces without quotes.\n \n\n\n### Deprecate where possible\n\nThere are many qualifiers on our platform that could be unified or deleted. For example `type:` can now be replaced by `is:`.\nRemember that deprecating means that we stop suggesting those options to users but we still keep them available in the backend until we see usage declining to low volumes.\n\n\n \n \n Use a predefined qualifier where possible.\n \n \n \n Use a custom qualifier instead of a predefined one.\n\n \n\n\n### Formatting\n\nAlways list qualifiers in a readable way and don't include all their options by using descriptions.\nWe do this to ensure that qualifiers are easy to scan and have enough context.\n\n\n \n \n List qualifiers in a readable way and without their options.\n \n \n 400, 100...200'\"\n />\n Don't list qualifiers as their raw value with possible options.\n \n\n\n### Dynamic values\n\nSometimes static values can be limiting when filtering results. For example, let's say you want to get all items created in the past 7 days. Using a static value, you would have to create a range of dates manually, such as `2022-01-01..2023-01-07`. However, when you come back the next day (the 8th of January), you would have to update this range manually again to `2022-01-02..2023-01-08`. This is not very convenient. That's why dynamic values can be useful in these situations. Using the same example, if you use the dynamic value `@today-7d`, you will get all items created in the past 7 days. When you come back the next day, the range of dates will automatically update to reflect the current date, so you don't have to do it manually.\n\n| Value | Translation |\n| -------- | ---------------------------- |\n| `@today` | Current date (excludes time) |\n| `@me` | Current signed in user |\n\n⚠️ At the moment, we are conducting a review of dynamic values with multiple stakeholders, so changes may be made.\n\n## Options\n\n### Size\n\nFilter inputs can have 3 different sizes:\n\n\n\n- Small (`28px`)\n- Medium (`32px`) (default)\n- Large (`40px`)\n","parent":{"relativeDirectory":"components","name":"filter-input"}},{"fileAbsolutePath":"/home/runner/work/design/design/content/components/flash.mdx","frontmatter":{"title":"Flash"},"rawBody":"---\ntitle: Flash\ndescription: Flash alert informs users of successful or pending actions.\nreactId: flash\nfigma: https://www.figma.com/file/GCvY3Qv8czRgZgvl1dG6lp/Primer-Web?node-id=142%3A597&t=PFYau6cmDlujeJkx-1\nrails: https://primer.style/view-components/components/beta/flash\n---\n\nimport {Heading, Link} from '@primer/react'\nimport ComponentLayout from '~/src/layouts/component-layout'\nexport default ComponentLayout\n\n\n\n## Usage\n\nFlash alerts are used to display updates or alerts pertaining to any part of the system; this includes information regarding the user's account, the organization, the repo, and more.\n\nThese updates are typically not user-initiated but rather alerts that require the user's attention. Similarly to toasts, flash alerts can convey a warning, error, success, or a neutral message. If additional context is needed, provide a link for the user to learn more.\n\n### Best practices\n\n- Use flash alerts sparingly and only when necessary. Flash alerts can disrupt the user experience and should only be used when and where relevant.\n\n- Though flash alerts don't need to be as concise as a typical Toast message, they should **be direct and not exceed two to three sentences**. Don't use headings or multiple type sizes in flash alerts, rely on the default paragraph size instead.\n\n- Don't show more than one flash alert at a time. For more information, see this article on [alert fatigue](https://www.nngroup.com/videos/alert-fatigue-user-interfaces/).\n\n- They do not typically timeout on their own, but can include a dismiss action for messages that can be closed.\n\n## Options\n\n### Types\n\nThere are four types of flash banners, each with their own styles: Default, Warning, Danger, and Success.\n\n\n\n#### Full-width\n\nFull-width can be applied when attaching a banner to a container. It attaches only to the top of a container.\n\n\n\n#### Accessories and actions\n\nBanners contain options to add an icon, button, or dismiss button to the content of the alert.\n\n\n\n## Accessibility\n\nThe flash component should trigger notifications for users utilizing assistive technology. They should be considered as part of the overall messaging in the product and do not recieve focus (therefore, they do not _require_ a dismiss button).\n","parent":{"relativeDirectory":"components","name":"flash"}},{"fileAbsolutePath":"/home/runner/work/design/design/content/components/form-control.mdx","frontmatter":{"title":"Form control"},"rawBody":"---\ntitle: Form control\ndescription: Form control displays a labelled input and, optionally, associated validation text and/or hint text.\nreactId: form_control\nfigma: https://www.figma.com/file/GCvY3Qv8czRgZgvl1dG6lp/Primer-Web?node-id=142%3A595\n---\n\nimport ComponentLayout from '~/src/layouts/component-layout'\nexport default ComponentLayout\n\n## Usage\n\nUse form controls when requiring data input from the user. For example, creating a new repo configuring settings, and logging in.\n\nThis component is a helper component to keep layouts consistent and ensure the correct ARIA attributes are set. You can find some of Primer's form components listed in the [Related links](#related-links) section.\n\n## Anatomy\n\n![diagrams labeling the anatomy of a text field and a checkbox field](https://user-images.githubusercontent.com/2313998/171692166-43d45c4b-509a-4f68-9e8b-1577658b493e.png)\n\nForm controls allow users to provide data. At a minimum, they include an input and label. They may also include a caption and required field indicator.\n\nTo learn more about anatomy, input methods, forms structure, validation, and more, please refer to our [Forms guidance](/ui-patterns/forms).\n\n## Related links\n\n- [Forms](/ui-patterns/forms)\n- [Checkbox](/components/checkbox)\n- [Checkbox group](/components/checkbox-group)\n- [Radio](/components/radio)\n- [Radio group](/components/radio-group)\n- [Text input](/components/text-input)\n- [Textarea](/components/textarea)\n- [Select](/components/select)\n","parent":{"relativeDirectory":"components","name":"form-control"}},{"fileAbsolutePath":"/home/runner/work/design/design/content/components/heading.mdx","frontmatter":{"title":"Heading"},"rawBody":"---\ntitle: Heading\ndescription: Heading defines the hierarchical structure and importance of the content they contain.\nreactId: heading\nfigma: https://www.figma.com/file/GCvY3Qv8czRgZgvl1dG6lp/Primer-Web?node-id=21069%3A78764&t=0oSdmKQbjXp6hwuf-1\nrails: https://primer.style/view-components/components/beta/heading\n---\n\nimport ComponentLayout from '~/src/layouts/component-layout'\nexport default ComponentLayout\n\n\n\n## Usage\n\nHeadings are used to structure the content on the page, with each heading representing a different level of importance. It is recommended to use headings in a logical manner to create a clear hierarchy and improve accessibility.\n\n- Heading should be used to communicate page organization and hierarchy.\n- Use heading as the title of a section or sub section.\n- Do not use heading for styling alone. For simply styling text, use text with relevant styling.\n\nThe heading component will render an html h2 tag without any default styling.\n\n## Accessibility\n\nWhile sighted users rely on visual cues such as font size changes to determine what the heading is, assistive technology users rely on programatic cues that can be read out. When text on a page is visually implied to be a heading, ensure that it is coded as a heading. Additionally, visually implied heading level and coded heading level should be consistent. See [WCAG success criteria: 1.3.1: Info and Relationships](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html).\n\nHeadings allow assistive technology users to quickly navigate around a page. Navigation to text that is not meant to be a heading can be a confusing experience. [Learn more about best heading practices (WAI Headings)](https://www.w3.org/WAI/tutorials/page-structure/headings/).\n","parent":{"relativeDirectory":"components","name":"heading"}},{"fileAbsolutePath":"/home/runner/work/design/design/content/components/index.mdx","frontmatter":{"title":"Components"},"rawBody":"---\ntitle: Components\n---\n\n\n","parent":{"relativeDirectory":"components","name":"index"}},{"fileAbsolutePath":"/home/runner/work/design/design/content/components/link.mdx","frontmatter":{"title":"Link"},"rawBody":"---\ntitle: Link\ndescription: Links are used to apply styles to hyperlink text.\nreactId: link\nfigma: https://www.figma.com/file/GCvY3Qv8czRgZgvl1dG6lp/Primer-Web?node-id=20953%3A78940&t=wIvqJYawyRBUeGPt-1\n---\n\nimport {Box, Text} from '@primer/react'\nimport Code from '@primer/gatsby-theme-doctocat/src/components/code'\nimport ComponentLayout from '~/src/layouts/component-layout'\nexport default ComponentLayout\n\n## Usage\n\nLinks enable users to navigate between pages or resources in a seamless way. Links can be used within a body of text or as a standalone element.\n\nLinks navigate you to a new place or new content. **Do not** use links for triggering an action. Instead, use [buttons](/components/button), which are designed to activate a feature.\n\nLinks should be concise and not exceed more than a few words.\n\n## Anatomy\n\nThe link component can be displayed in default, muted, or blue colors. Links can be underlined, may include a leading visual or trailing visual, and can be either the default or small size. \n\n\n \n \n\n\n## Accessibility\n\nLinks play a key part in your experience on the web, but without proper consideration they can be frustrating to use, skipped over, or completely unnoticed.\n\nFor assistive technologies like screen readers, links and buttons are expected to function differently from each other. If a link is activated and does not do what was expected, that can be disorienting and frustrating.\n\nA common way a screen reader might navigate the page is by going through a list of all the links on the page. Without context, \"read more\" or \"click here\" links are not helpful.\n\nPeople who have low or colorblind vision may have trouble identifying links that just use color to distinguish them from plain text, this is why keeping the underline styling on links within body text is important for identification.\n\n### How to test links\n\n#### Functionality and purpose\n\nA link's function is to _navigate_ to a different page or new content. If instead a feature on the page is activated, use a `