## File: README.md

# Primer CSS
The CSS implementation of GitHub's Primer Design System

[](https://www.npmjs.com/package/@primer/css)
[](https://github.com/primer/css/actions/workflows/ci.yml)
[](https://github.com/primer/css/graphs/contributors)
[](https://github.com/primer/css/commits/main)
[](https://github.com/primer/css/blob/main/LICENSE)

> :warning: **This project is in KTLO mode!** Use existing utility classes from this project where needed. For more complete patterns that include styling and markup, please use [primer/react](https://github.com/primer/react) or, if necessary, [primer/view_components](https://github.com/primer/view_components).

## Documentation
Our documentation site lives at [primer.style/css](https://primer.style/css). You'll be able to find detailed documentation on getting started, all of the components, our theme, our principles, and more.

## Install
This repository is distributed with [npm]. After [installing npm][install-npm], you can install `@primer/css` with this command:

```sh
npm install --save @primer/css
```

## Usage
The included source files are written in [Sass] using SCSS syntax. Once installed, you can add your project's `node_modules` directory to your Sass [include paths](https://github.com/sass/node-sass#includepaths) (AKA [load paths](http://technology.customink.com/blog/2014/10/09/understanding-and-using-sass-load-paths/) in Ruby), then import it like this:

```scss
@import "@primer/css/index.scss";
```

You can import individual Primer modules directly from the `@primer/css` package:

```scss
@import "@primer/css/core/index.scss";
@import "@primer/css/product/index.scss";
@import "@primer/css/marketing/index.scss";
```

## Development
See [DEVELOP.md](DEVELOP.md) for development docs.

## Releasing (for GitHub staff)
You can find docs about our release process in [RELEASING.md](RELEASING.md).

## License

[MIT](./LICENSE) © [GitHub](https://github.com/)


[install-npm]: https://docs.npmjs.com/getting-started/installing-node
[npm]: https://www.npmjs.com/
[sass]: http://sass-lang.com/

---

## File: docs/stories/deprecated-components/Tooltip/Tooltip.mdx

import {Canvas, Meta, Story} from '@storybook/blocks'

import * as TooltipStories from './Tooltip.stories'

<Meta of={TooltipStories} />

# Tooltip

Please note that the `.tooltipped` component is **deprecated**. We recommend using the [Tooltip component](https://primer.style/view-components/components/alpha/tooltip) instead.

Add tooltips built entirely in CSS to appropriate elements.

## Implementation and accessibility

Tooltips as a UI pattern should be our last resort for conveying information because it is hidden by default and often with zero or little visual indicator of its existence.

Before adding a tooltip, please consider: Is this information essential and necessary\* Can the UI be made clearer? Can the information be shown on the page by default? And check out [alternatives to Tooltips](https://primer.style/design/accessibility/tooltip-alternatives) to explore your options.

### Attention

- **Never** use tooltips on static elements. They should only be used on interactive elements, because users cannot tab-focus into static elements, which may make the content inaccessible for keyboard-only users and screen readers.
- we use `aria-label` for tooltip contents, because it is crucial that they are accessible to screen reader users. However, `aria-label` **replaces** the text content of an element in screen readers, so only use `.tooltipped` on elements with no existing text content such as an icon-only button.
- Tooltip classes will conflict with Octicon styles, and as such, must be applied to the parent element instead of the icon.

## Tooltip direction

Specify the direction of a tooltip with north, south, east, and west directions:

<Canvas of={TooltipStories.Default} />

## Tooltip alignment

Align tooltips to the left or right of an element, combined with a directional class to specify north or south. Use a modifier of `1` or `2` to choose how much the tooltip's arrow is indented.

<Canvas of={TooltipStories.Alignment} />

## Tooltips with multiple lines

Use `.tooltipped-multiline` when you have long content. This style has some limitations: you cannot pre-format the text with newlines, and tooltips are limited to a max-width of `250px`.

<Canvas of={TooltipStories.MultiLine} />

## Tooltips with no delay

By default the tooltips have a slight delay before appearing. This is to keep multiple tooltips in the UI from being distracting. There is a `.tooltipped-no-delay` modifier class you can use to override this.

<Canvas of={TooltipStories.NoDelay} />

---

## File: docs/stories/deprecated-components/Toast/Toast.mdx

import {Canvas, Meta, Story} from '@storybook/blocks'

import * as ToastStories from './Toast.stories'

<Meta of={ToastStories} />

# Toast

Toasts are used to show live, time-sensitive feedback to users.

## Default

To create a default toast, use `.Toast`. Always use the `info` icon for default messages.

<Canvas of={ToastStories.Default} />

The Toast content is formattable. We recommend keeping your message under 140 characters.

## Variations

Use the success, warning, and error modifiers to communicate different states.

Always use the `check` octicon for success states.

<Canvas of={ToastStories.Success} />

Always use the `alert` octicon for warning states.

<Canvas of={ToastStories.Alert} />

Always use the `stop` octicon for error states.

<Canvas of={ToastStories.Error} />

## Toast with dismiss

Use `.Toast-dismissButton` to allow a user to explicitly dismiss a Toast.

<Canvas of={ToastStories.Dismiss} />

## Toast with link

Include a link to allow users to take actions within a Toast.

<Canvas of={ToastStories.WithLink} />

## Toast animation in

The `Toast--animateIn` and `Toast--animateOut` modifier classes can be used to animate the toast in and out from the bottom.

<Canvas of={ToastStories.AnimationIn} />

## Toast with loading animation

Add the `Toast--spinner` modifier class on the `Toast-icon` `svg` to communicate a loading state.

<Canvas of={ToastStories.Loading} />

## Toast position

Use the `position-fixed bottom-0 left-0` utility classes on a wrapper element to position Toasts at the **bottom left** of the viewport.

---

## File: docs/stories/deprecated-components/SubNav/SubNav.mdx

import {Canvas, Meta, Story} from '@storybook/blocks'

import * as SubNavStories from './SubNav.stories'

<Meta of={SubNavStories} />

# SubNav

`.subnav` is navigation that is typically used when on a dashboard type interface with another set of navigation above it. This helps distinguish navigation hierarchy.

<Canvas of={SubNavStories.Default} />

You can have `subnav-search` in the subnav bar.

<Canvas of={SubNavStories.Search} />

You can also use a `subnav-search-context` to display search help in a select menu.

<Canvas of={SubNavStories.SearchContext} />

---

## File: docs/stories/deprecated-components/SideNav/SideNav.mdx

import {Canvas, Meta, Story} from '@storybook/blocks'

import * as SideNavStories from './SideNav.stories'

<Meta of={SideNavStories} />

# SideNav

The Side Nav is a vertical list of navigational links, typically used on the left side of a page. For maximum flexibility, **Side Nav elements have no default width or positioning**. We suggest using [column grid](../utilities/grid) classes or an inline `width` style for sizing, and [flexbox utilities](../utilities/flexbox) for positioning alongside content.

- You can use a **border** if the parent element doesn't have it already.
- Add `aria-current="page"` to show a link as selected. Selected button elements in tab-like UIs should instead have `aria-selected="true"`.

<Canvas of={SideNavStories.Default} />

Different kind of content can be added inside a Side Nav item. Use utility classes to further style them if needed.

<Canvas of={SideNavStories.Options} />

The `.SideNav-subItem` is an alternative, more lightweight version without borders and more condensed. It can be used stand-alone.

<Canvas of={SideNavStories.SubItem} />

Or also appear nested, as a sub navigation. Use margin/padding utility classes to add indentation.

<Canvas of={SideNavStories.Nested} />

---

## File: docs/stories/deprecated-components/SelectMenu/SelectMenu.mdx

import {Canvas, Meta, Story} from '@storybook/blocks'

import * as SelectMenuStories from './SelectMenu.stories'

<Meta of={SelectMenuStories} />

# SelectMenu

Please note that this is a newer version and uses the `.SelectMenu` class instead of the [deprecated select menu](/css/components/select-menu-deprecated) class. Check the [migration guide](/css/components/select-menu-deprecated) to make sure your app is up to date.

The `SelectMenu` component provides advanced support for navigation, filtering, and more. Any menu can make use of JavaScript-enabled live filtering, selected states, tabbed lists, and keyboard navigation with a bit of markup.

## Basic example

Use a `` element to toggle the select menu. The `` element can be styled in many ways. In the example below it's a `.btn`.

<Canvas of={SelectMenuStories.Default} />

Add a `.SelectMenu-header` to house a clear title and a close button. Note that the close button is only shown on narrow screens (mobile).

## Right aligned

In case the select menu should be aligned to the right, use `SelectMenu right-0`.

<Canvas of={SelectMenuStories.RightAligned} />

## Selected state

If the `SelectMenu` should show a check icon for selected items, use the `SelectMenu-icon SelectMenu-icon--check` classes. It will make the check icon show when `aria-checked="true"` is set.

<Canvas of={SelectMenuStories.SelectedState} />

## Borderless

Use the `.SelectMenu-list--borderless` modifier to remove the borders between list items. Note: It's better to keep the borders if a list contains items with multiple lines of text. It will make it easier to see where the items start and end.

<Canvas of={SelectMenuStories.Borderless} />

## Header

Add a `.SelectMenu-header` at the top to house a clear title and a close button.

<Canvas of={SelectMenuStories.Header} />

## List items

The list of items is arguably the most important subcomponent within the menu. Build them out of anchors, buttons, or just about any [interactive content](http://w3c.github.io/html/dom.html#interactive-content). List items are also customizable with options for avatars, additional icons, and multiple lines of text. Use utility classes in case more custom styling is needed.

<Canvas of={SelectMenuStories.ListItems} />

## Divider

The select menu's list can be divided into multiple parts by adding a `.SelectMenu-divider`. It can be a `` with text/content. Or just an `<hr>` to add a visual separator.

Dividers are also supported when using the `.SelectMenu-list--borderless` modifier.

<Canvas of={SelectMenuStories.Divider} />

## Footer

Use a `.SelectMenu-footer` at the bottom for additional information. As a side effect it can greatly improve the scrolling performance because the list doesn't need to be repainted due to the rounded corners.

<Canvas of={SelectMenuStories.Footer} />

## Filter

If the list is expected to get long, consider adding a `.SelectMenu-filter` input. Be sure to also include the `.SelectMenu--hasFilter` modifier class. On mobile devices it will add a fixed height and anchor the select menu to the top of the screen. This makes sure the filter input stays at the same position while typing.

<Canvas of={SelectMenuStories.Filter} />

## Tabs

Sometimes you need two or more lists of items in your select menu, e.g. branches and tags. Select menu lists can be tabbed with the addition of `.SelectMenu-tabs` above the menu.

<Canvas of={SelectMenuStories.Tabs} />

## Message

A `SelectMenu-message` can be used to show different kind of messages to a user. Use utility classes to further style the message.

<Canvas of={SelectMenuStories.Message} />

## Loading

When fetching large lists, consider showing a `.SelectMenu-loading` animation.

<Canvas of={SelectMenuStories.Loading} />

## Disabled

To disable a list item, use the `disabled` attribute for ``s. For `<a>`s replace the `href` with an `aria-disabled="true"` attribute. Note: If not obvious, try to communicate to the user why an item is disabled.

<Canvas of={SelectMenuStories.Disabled} />

## Blankslate

Sometimes a select menu needs to communicate a "blank slate" where there's no content in the menu's list. Usually these include a clear call to action to add said content to the list. Swap out the contents of a `.SelectMenu-list` with a `.SelectMenu-blankslate` and customize its contents as needed.

<Canvas of={SelectMenuStories.BlankSlate} />

## github.com usage

When adding the `.SelectMenu` component on github.com, use the [``](https://github.com/github/details-menu-element) element. It will magically make the `.SelectMenu` work. Here a basic example:

```erb

  
    Choose
    
  
  
    
      <header class="SelectMenu-header">
        My Select Menu
        
          <%= octicon("x", "aria-label": "Close menu") %>
        
      </header>
      
        <a class="SelectMenu-item" href="" role="menuitem">Item 1</a>
        <a class="SelectMenu-item" href="" role="menuitem">Item 2</a>
        <a class="SelectMenu-item" href="" role="menuitem">Item 3</a>
      
    
  

```

If loading content should be deferred, use the [``](https://github.com/github/details-menu-element) element:

```erb

  
    
      <%= octicon("octoface", class: "anim-pulse", :height => 32) %>
    
  

```

It will add a pulsing "octoface" icon while the content is loading.

---

## File: docs/stories/deprecated-components/Pagination/Pagination.mdx

import {Canvas, Meta, Story} from '@storybook/blocks'

import * as PaginationStories from './Pagination.stories'

<Meta of={PaginationStories} />

# Pagination

Use the pagination component to apply button styles to a connected set of links that go to related pages (for example, previous, next, or page numbers).

## Previous/next pagination

You can make a very simple pagination container with just the Previous and Next buttons. Add the `aria-disabled="true"` attribute to the `Previous` button if there isn't a preceding page, or to the `Next` button if there isn't a succeeding page.

<Canvas of={PaginationStories.Default} />

## Numbered pagination

For pagination across multiple pages, make sure it's clear to the user where they are in a set of pages.

To do this, add anchor links to the `pagination` element. Previous and Next buttons should always be present. Add the `aria-disabled="true"` attribute to the Previous button if you're on the first page. Apply the `aria-current="page"` attribute to the current numbered page.

As always, make sure to include the appropriate `aria` attributes to make the element accessible.

- Add `aria-label="Pagination"` to the `paginate-container` element.
- Add `aria-label="Page X"` to each anchor link.

<Canvas of={PaginationStories.Numbered} />

---

## File: docs/stories/deprecated-components/Marketing/Marketing.mdx

import {Canvas, Meta, Story} from '@storybook/blocks'

import * as MarketingStories from './Marketing.stories'

<Meta of={MarketingStories} />

# Marketing links

Marketing links can be produced by combining the base class `link-mktg` with a set of modifier classes to control the size and color.

<Canvas of={MarketingStories.Link} />

## Link sizes

The marketing link size is defined with utility classes and come in large (`.f3-mktg`) and small (`.f4-mktg`):

## Link with emphasis

Add class `link-emphasis-mktg` to the link, to give it a pale underline, that will fill up on hover.

<Canvas of={MarketingStories.LinkEmphasis} />

## Link colors

The link color is controlled with the [Primer color classes](/utilities/colors), while the symbol and underline styling will follow:

<Canvas of={MarketingStories.LinkColors} />

---

## File: docs/stories/deprecated-components/Loaders/Loaders.mdx

import {Canvas, Meta, Story} from '@storybook/blocks'

import * as LoaderStories from './Loaders.stories'

<Meta of={LoaderStories} />

# Loaders

Loaders inform users that an action is still in progress and might take a while to complete.

Add an animated ellipsis at the end of text with ``.

<Canvas of={LoaderStories.Default} />

---

## File: docs/stories/deprecated-components/IssueLabel/IssueLabel.mdx

import {Canvas, Meta, Story} from '@storybook/blocks'

import * as IssueLabelStories from './IssueLabel.stories'

<Meta of={IssueLabelStories} />

# IssueLabel

Issue labels are used for adding labels to issues and pull requests. They also come with emoji support.

<Canvas of={IssueLabelStories.Default} />

If an issue label needs to be bigger, add the `.IssueLabel--big` modifier.

<Canvas of={IssueLabelStories.Big} />