css Documentation

Primer is GitHub's design system. This is the CSS implementation

12,995 stars SCSS 1 file · ~4,209 tokens #css#design-system#design-systems#framework#meta#primer#primer-css#sass
RAW Doc

File: README.md

Primer CSS

The CSS implementation of GitHub's Primer Design System





: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 or, if necessary, primer/view_components.

Documentation

Our documentation site lives at 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, 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 (AKA 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 for development docs.

Releasing (for GitHub staff)

You can find docs about our release process in RELEASING.md.

License

MIT © GitHub

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

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

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

Tooltip

Please note that the .tooltipped component is deprecated. We recommend using the Tooltip component 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 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:

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.

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.

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.

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

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

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

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.

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.

Always use the alert octicon for warning states.

Always use the stop octicon for error states.

Toast with dismiss

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

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

Toast animation in

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

Toast with loading animation

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

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'

.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.

You can have subnav-search in the subnav bar.

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

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

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

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

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 classes or an inline width style for sizing, and flexbox utilities 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".

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

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

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

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

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

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

SelectMenu

Please note that this is a newer version and uses the .SelectMenu class instead of the deprecated select menu class. Check the migration guide 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.

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.

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.

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.

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

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. 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.

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.

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.

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.

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.

Message

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

Loading

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

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.

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.

github.com usage

When adding the .SelectMenu component on github.com, use the `` 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 `` 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'

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.

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.

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

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

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

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

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

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

The link color is controlled with the Primer color classes, while the symbol and underline styling will follow:

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

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

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

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 ``.

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

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

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

IssueLabel

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

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

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#css Browse css catalog → #design-system Browse design-system catalog → #design-systems Browse design-systems catalog → #framework Browse framework catalog → #meta Browse meta catalog → #primer Browse primer catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →