primer / design

Primer Design Guidelines

Primer Design System documentation

Documentation for all things Primer, including components, UI patterns, foundations, guides, and more.

Status

This repository is evolving as our documentation needs change. See our contribution guides here.

Project board (GitHub staff only)

Local development

1. Clone this repo, e.g. with:

   git clone https://github.com/primer/design

2. In the terminal, navigate (cd) to the repo directory

3. nvm use --default to use the correct node version.

4. yarn to install dependencies

5. yarn start to start the dev server

Deployment

We deploy this site using GitHub Pages. Every push to a branch other than main will deploy to a URL unique to the preview environment. Merges to main will automatically deploy the site to https://primer.style/.

FAQ

How do I add documentation for a new component or edit existing component documentation?

• Our component documentation files are found here, and guidelines for adding content can be found under the Documenting components section of the Contributing guidelines.
• For a more detailed walk-through, check out this tutorial video.

I need help getting started.

• Check out our getting started guides or ping us in Slack (GitHub staff only)

I noticed a bug in the documentation!

• Feel free to open a pull request or issue directly in this repository, or ping us in Slack (GitHub staff only)

design's Issues

Document Figma components

• how and where to access Primer components in Figma
• tips & tricks
• prototyping in Figma
• useful links (such as Figma docs, spectrum.chat, and helpful articles)
• how to get access to Figma

Add guidelines for showing timestamps ⏱

It's time ⏱ for another issue. I could't find any information regarding usage of timestamps and thought this could make a great addition to our docs in the future.

🔦 Some examples I've found:

• Activity: 12d
• Issues: 16 Apr 2021
• PR deleted branch: 7 months ago
• Profile repositories: Updated on 27 Sep 2021
• Explore: Updated on 26 Feb
• Codespaces: Last used about 1 month ago
• Notifications: on 5 Jan

🎉 What I expect in the docs:

• Are there components/libraries available similar to moment.js our team should rely on during implementation.
• At what time length do we go from a days/months to the full date. Do we always show the year than or only if past the current year?
• How much precision is allowed on a timestamp. Seconds, minutes, hours, days, months...
• Accessibility
• When written in a sentence vs standalone
• Will we support different formats: day/month/year or month/day/year

Related

• https://github.com/github/special-projects/issues/1007

Add a treatment for consistent appearance of content on focus

This issue arose from primer/react#2593.

The SplitPageLayout component uses a small form with an input and submit button to allow for adjusting the pane width without the need for pointer input. This form is visually hidden, meaning that in its current implementation that only screen reader users will be aware of its presence.

Controls such as this need to also be visually apparent on focus. While only the SplitPageLayout component has this need right now, I anticipate other components needing similar functionality—and therefore a consistent visual treatment—as our Primer accessibility work continues.

Currently there is no one set way to handle this kind of content. The closest examples I am aware of are our Skip to main content link and our dashboard favorites reordering functionality:

I am thinking that this is worth codifying as something that can be used as a subcomponent for other components, to help ensure a consistent, accessible experience that feels like it is a part of Primer. We'll likely want something along the lines of how our Dialog component looks.

Additional context

• Slack thread in #accessibility-internal
• Slack thread in #primer-design
• AppFrame work

Expand "Applying Typography" - Typography Guidelines

Just linking to components isn't super helpful. We should show components when giving examples on how to use typography. I'd like this to be replaced with a section on "Applying typography" with examples of it in practice, in components and chunks of UI. However I think that could be a lot of work and would be happy if you make an issue for that for now and we follow up with that at a later date.

Originally posted by @broccolini in #15

11.28.2018
'Applying Typography' section has been added. This can be expanded in future iterations to house visual usages. Possibly as sub-section called “In Use” or “Use Cases” or something

Site build

• support mdx
• support 3 levels of navigation, same as Components
• built with primer components
• match header style with primer.style and components

Banner Illustration updates (static)

Updates to be made

• Header Image
  • @jhuashao and I are pairing to update the header image/animation to be more inline with Primer Components and Primer CSS.
• Header font-weight
  • Currently set to 700. Should this be 600 as seen on Primer CSS or leave as is which is in line with Primer Components? (cc @broccolini)

Remove empty pages

Color & design tools

broken figma resources link

hello!

all the links to figma resources listed in: https://primer.style/design/tools/figma#Resources are broken (at least to me)

Broken link sample: https://www.figma.com/file/WARYmZzsypbLrC6CDyE29dRA/primer-navigation

are the figma links updated?

Add guidelines for loading patterns 🔄

Problem
There are currently no guidelines on how to use loading states throughout GitHub.

Considerations

• Toasts that load forever
• Forms that load for a long time
• Should buttons be allowed to have a spinner inside them
• How and when do we show a timeout
• Possible new skeleton loaders for fast loading content and reducing layout shifts
• How do we do all above in an accessible way.

Original Slack thread (Internal)

Clarify usage of flash alert

A current issue mentioned problems with the flash banner being semi-transparent in dark mode.

However I believe the issue arises from incorrect usage of the flash component due to the documentation missing content on the positioning.

I think the flash alert is not supposed to be floating above the page but should be part of the default layout flow.
This needs to be clarified in the guidelines.

Document spacing in Primer

Document how to use values and apply spacing.

Pull request: #103

Todo:

• Re-review the content to make sure it is still accurate
• Create images for examples (Figma)

Outdated links

Links to Figma ressources in the tools page are redirecting to Figma's File not found page.

Add guidelines for inputs requiring numbers 🔢

Our form guidelines already provides a lot of good information on how to provide validation in multiple scenarios however it's missing cases where the input it limited to just numbers.

Currently there are no examples of disabled states as well as no pattern for letting the user know why an item is disabled.

Considerations

• Similar to password validation a error message should appear upon submission if it fails validations
• Similar to password validation a hint message should appear below the field explaining what's expected. In this case only numbers.
• From an accessibility point of view is it acceptable to only allow entering numbers and is there other things we should consider to ensure it is perceived correctly by screen readers.
• Do we need additional styling for the up and down arrows in number inputs
• Are there other types of inputs that might need additional documentation

Links

• Original Slack thread (internal)

Add documentation on using Flash alerts in dialog components

I came across this usage of a Flash alert inside of a details-dialog that felt a bit off:

Should we add some documentation about whether or not Flash alerts should be used inside of dialog components? To me it feels a bit redundant since the dialog itself is sort of like an alert but I wasn't 100% sure if this is something we should discourage or not.

Move Accessibility guidelines to design guidelines

https://styleguide.github.com/primer/principles/accessibility/

• Until the site is public, keep them in the style guide.
• Check links are updated where needed
• Ensure examples are generalized for platforms

ActionList: Add guidelines for disabled items and how to hint why they are disabled

Our ActionList guidelines already provides a lot of good information on how to use it but I've spotted one use case that's missing.

Currently there are no examples of disabled states as well as no pattern for letting the user know why an item is disabled.

Action

• Add screenshots of disabled items
• Provide a pattern for hinting why something is disabled
• Ensure the above pattern works with screen readers (accessibility)

Examples of what designers have come up with in the past:

Codepen Troubleshooting

Currently the Codepen 2 Col Layout Template is experiencing roadblocks due to some SCSS and CSS difficulties.

I found out later that the link in the templates is only calling on primer's CSS, and doesn't contain complete styling: https://unpkg.com/primer/build/build.css

Even after trying to call it directly, codepen is still having trouble:
https://github.githubassets.com/assets/github-12f3b278e437ae91b8bc11dcaa8f135f.css

Currently the 2 Col Demo is being run on a Jekyll + Primer github pages site, but will need to be fully ported over after Responsive Navigation designs have been decided upon.

http://joshuashao.design/2ColPrimerTest/

Edit: Another reason porting this over into another environment was that it was helpful to see the underlying of the styling; unfortunately this isn't possible in codepen

ActionList: Needs better guidelines on not using single select items

I found this pattern where a single selection item is used together with a confirm button.

We should provide better guidelines and examples on what the best alternatives are to this.

Concern with this pattern
Check marks (single selection ActionList items) are meant for final actions as they don't provide the feeling of confirming your selection.

Things that come to my mind that could use clarification:

• If the above design pattern is acceptable I'm assuming it should have a Cancel button as well.
• In ActionList guidelines the SelectPanel screenshot could be improved by showing the Cancel and Confirm button and the example in React it links to should be adapted to include this as well.
• Is the pull request merge pattern a good alternative?
• Should single selections be allowed to have a confirm button? In this case I can see why a confirm button can be useful.
• For multiple selections we use checkboxes so I'm assuming here we would do the same and move to radio buttons if a confirmation is needed.
• In this case should a dialog be used instead to confirm this action? At what point should you pick a Dialog over an Overlay.

Banner illustration

This should feel like part of the family of primer.style illustrations used on primer.style and primer.style/components.

Though the illustration style is abstract, the components illustration hints at the idea of "components", and so the design guidelines illustration should hint at design, interaction, UX, and documentation.

Add Illustration Guidelines

Add the illustration guidelines from this PR: primer/primer.style#101

Live Editor - Typography Guidelines

I think we'd have to store and load those fonts ourselves, probably use @fontface to specifically target the fonts. This would be nice but not essential right now. Let's make an issue to follow up with this. Ideally we would have use the live editor too so that people can type and test how the font would look like on google fonts. Only thing I'm not sure about is copyright so that's worth checking.

Originally posted by @broccolini in #15

Live Editor for typography implemented into Design Guidelines, allowing users to test out different typefaces for different use cases

Update NUX blankslate info

The current ship of the new blankslate component will include replacing major empty states with pictogram-based blankslates. However, for new users, illustrations can provide a much more personalized experience and and introduce the user to the octocat as a symbol of GitHub.

We need to add design documentation for when to use these illustration blankslates. This can come after the new blankslate design is merged into both Primer CSS and Primer Design.

Initial thoughts and draft of the copy for this section can be found at the bottom of this Gist.

[Tracking] Button Usage/ Interaction Guidelines

Introduction

These button usage guidelines will guide designers and developers in implementing consistent buttons across GitHub products.

Currently, Primer CSS and Primer Components all house code and technical implementation instructions. These guidelines are meant to serve as a way to understand best practices and common usages.

Button Usage Guidelines Priority List

Must

• Include straight forward guidance on basic button design implementation
  • Default
  • Primary
  • Danger
  • Outline
• Have guidelines for spacing + placement + sizing of buttons

Should

• Have documentation of icon-only button usage and guidelines

Could

• Include examples, use-cases, and guidance on using Links in lieu of buttons in certain scenarios
• Have guidance on implementing buttons for dropdowns, navigation, and filtering
• Have color and typography guidelines for specified use-cases

Won't

• Delve into technical aspects of implementing buttons on GitHub products

Alert dialog guidelines

Problem

Now that we have the wonderful Dialog documentation out, we might want to expand the documentation around dialog when used for alerts, warnings, or destructive purposes.

As @edokoa pointed out here, this sort of dialog doesn't follow a clear set of patterns, therefore we end up with different variations often used for similar use cases.

Proposal

Add a new Dialog usage section (similar to the Button usage), or a subsection inside the Messaging guidelines. This documentation could cover:

• Alert/flash banner usage (including best practices of danger and warning variants, positioning, tone and voice, etc)
• Heading content, so we don't vary from "Are you sure...?" to "Doing this..."
• Guidelines to display output or consequences on important actions (where and how to them, tone and voice, etc)
• Consistency around buttons (when to require or not a confirmation input, using danger or secondary buttons, etc)

Slack thread reference (internal)

Path alias doesn't work

The Now "path alias" that I set up in primer/primer.style#100 isn't working. I can curl https://primer.style/design and it looks like there's content in the response, but Next is doing something funky and redirecting to /design/ on the client side, which causes the server to keel over.

@emplums, maybe we can pair on this next week? 😭

Typography Guidelines

Creating Typography Guidelines for Primer Design Guidelines.

Live Iterations can be found here:
https://primer-design-typography.now.sh/design/foundation/typography

Guidelines should document our take on link targets

GitHub links don't open in a new tab. Or at least that seems to be the norm across most of the website. Our UI Guidelines should document this pattern and detail if, by any special reason, we should ever allow target="_blank" to be used.

Tooltips design guidelines

Some issues with accessiblity we should write about in the tooltips design guidelines https://github.com/github/github/issues/120980

Filters & Clearing Filters

This came up in response to: https://github.com/github/github/pull/107687
(also https://github.com/github/github/issues/106809)

Problem & Goal

We don't have an easily repeatable pattern for clearing filters across the site, which leaves people to create a custom solution when needed. It may be worth coming up with a consistent pattern here.

I think it might be worth including Filters/Clear Filters patterns in the design guidelines to help inform future design decisions.

Screenshots

PRs and Issues

File Diffs - Clear File Filters (Old)

File Diffs - Clear File Filters (Updated)**

---

Thoughts & Q's

• how do we make it clear that filters have been selected if we're not using an input or any other indication that filters are being applied (like in the PRs/Issues pattern). For example, it's not that obvious that filters are applied the second image, the only difference is that the link changes to blue:

👇 no filters selected/applied 👇

👇 commit and file filters applied 👇

Image being squashed on Safari

image on this page https://primer.style/design/tools/figma is being squashed on safari; appears normal on chrome + firefox.

I'm running Safari Version 14.0.3 (16610.4.2) on macOS Big Sur 11.2 Beta (20D5029f)

but also tested on Safari Version 13.1.2 (15609.3.5.1.3) on macOS Catalina Version 10.15.6 (19G2021) and it's the same thing...

Add a license?

Could you add a license to this repo? thanks. :)

Add info about font usage in Figma

• SF https://developer.apple.com/fonts/
• mono http://osxdaily.com/2018/01/07/use-sf-mono-font-mac/

Broken Link on Accessibility Page

Page: https://primer.style/design/global/accessibility

In the Overview section, 508 Reference Guide - 1194.22 points to a link which returns a 404 page.

Broken links in interface guidelines

I was reading the Primer interface guidelines for icons and noticed that quite a few of the links are broken. For example, the Library section contains a link:

At Primer, we utilize the Octicons icon library.

Looking at the source for this link, it's obviously meant to point to https://primer.style/octicons/, which is the correct URL, but something on the site is prepending /design to the path, even though the link starts with a slash. This means the document links to https://primer.style/design/octicons/ instead, which is 404'ing.

This problem also exists for many other links on the same page, and possibly other pages in the guidelines.

Test issue

Testing issue triage

Add dialogs to Messaging section

I noticed that the Messaging section doesn't include anything about details-dialog elements that are frequently used to confirm actions or provide more information. Though we don't maintain details-dialog I still think it would make sense to provide usage guidelines for them as they are frequently used bits of our UI.

Example of a details-dialog being used to confirm actions:

It also seems anti-pattern to put a question in the header/title of the dialog - maybe we could provide some usage guidelines for that as well.

Global User Support Notice

Originally posted by @broccolini in https://github.com/_render_node/MDIzOlB1bGxSZXF1ZXN0UmV2aWV3VGhyZWFkMTQyNTMzOTYzOnYy/pull_request_review_threads/discussion

@broccolini's idea to create a global support notice for Design Guidelines

Rather than create redundant sections for User Support across articles, creating a global notice applicable to all other guideline articles that aid users in navigating help and support from the Primer Team.

Creating a reusable "support component" for us to use could be really helpful!

Add lint rule to ensure `<img>` is self closing

When <img> is does not have self closing slash like <img />, vercel deploys broke completely.

<img > is considered valid HTML as it is a void element, but for some reason <img > breaks vercel deploys.

Apparently <img> is not valid in XHTML or XML and needs to be <img /> so maybe XHTML or XML is being used under the hood somewhere? Not sure

We should investigate why this breaks and/or add a lint rule so we catch this at the linting stage and prevent future headaches.

Truncation page has been removed, but not from navigation menu

What

Docs for truncation has been removed, but we have a link to that page on website, that causes 404 error.

Expected Result

The truncation page is remove from Navigation menu and A11Y main page

Links w/ Octicons

Right now, it's not immediately clear how to style an Octicon when it's paired with a link.

Should the Octicon be wrapped within the link, and have the same color/hover states applied? Or should the link color/hover color behave independently of the icon it's paired with.

Examples:

primer/design Landing Page

When designing for the Figma docs page, I accidentally created something that looked like it could be iterated upon to become the landing page for primer/design. I noticed that the front page didn't have much guidance on where to go right now, so I thought I might take a shot at getting this started.

Currently the page looks like:

What I would like is for the page to have some actionable, custom React components that welcome the user and tell them where to get started:

I would love to build this, but would like some feedback about whether we are comfortable going this direction. If so, I can pair with Shawn or Emily to create the component and open up a PR.

Here's the Figma

cc/ @emilybrick @ashygee

Link to Primer Mobile Figma library is broken

I was browsing the docs and noticed the various links to Primer Mobile-related Figma resources are dead. Any idea where I can find working copies?

Add clearing guidelines for SelectPanel/SelectMenu with single/multi selections

Currently our components are lacking guidelines as well as functionality on how clearing selections in a SelectPanel or SelectMenu should work. This is especially a problem when you have multiple items selected and quickly want to clear those

Exploration by @asiermartinez

Consider

• Selects with multi selections
• Selects with a filter input

Links

Slack Thread (external)
SelectMenu
SelectPanel

Updated Github UI in the latest Primer figma designs

Hello!

Do you plan to update community shared Figma designs to reflect the latest changes in Github UI (which is experimental, I guess)? I'd like to use Primer for my personal project, and I'd like to use updated design.

Improve cancel button guidelines

Our saving docs is already doing a great job at providing guidelines but on when to use cancel button and when not.

One relevant bit on saving is:
When data is not automatically saved after the user makes changes, buttons are used to submit or cancel the changes.

This might imply we should always include a cancel button but that isn't correct. For example on a login page this won't be useful.

Considerations:

• Should a cancel button be used on intermediate form pages (not just modals)
• Cancelling can be useful when by accident changing the form
• Are there accessibility considerations here?

Original Slack thread (internal)

Add guidelines for writing documentation

Animated banner is not using correct colors

Looks like something went wrong between after effects and shipping the animation, the Primer blue's are all dulled and not rendering correctly. It's possible this is on the after effects export end, or may be something we can fix in code.

cc @ashygee

Add redirect for /design

We need to add a redirect for primer.style/design ➡️ primer.style/interface-guidelines

Typography Guidelines

Typography

These guidelines summarize how we use typography at Github, and serve as guardrails for designers to design freely with best practices in mind.
Good typography enhances the user’s experience by providing a well-structured vessel to hold a product’s content

Typefaces

At Github, our teams utilize system-fonts, which allow for optimized performance. This design decision takes advantage of:

• retina screens
• dynamic kerning
• additional font-weights
• improved readability
• Operating system-agnostic design

Segoe UI for Windows
San Francisco for macOS and iOS
Ubuntu for Ubuntu Linux (most commonly used in Linux distros)

Font Stack

font-family: -apple-system, BlinkMacSystemFont, "Segoe UI",
Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";

For more information on how Github uses typography for product design, check out Mark Otto’s article: Shipping System fonts to Github.com

Type Scale and Line-Height

Principles of Usage

Utilize components
Primer has many typographic solutions that have been created for developers and designers. Please refer to the docs to access them
List of helpful components:

• subheads
• Label
• etc.

Be aware of our usage of system-fonts:
Because Github font-stack defaults to system-fonts, it is important for designers to be aware of this fact when making design decisions. It’s recommended designers become familiar with typefaces themselves, and understand their nuances.

Please refer to the Typefaces section of this document to access our font-stack and resources.

Layouts and Typographic Guidance:
Line length:
Line length is important to consider when designing with body text in mind. Cases vary depending on the situation, but this serves as a general rule of thumb for developing products at Github
Type Consistency:
Don’t overuse different type sizes, weights, and styling. Try to keep this to a minimum in order to

etc.

Move Sketch docs from style guide

These should be mark as "in maintenance mode" with a link to Figma as our supported design tool.