Reading level for UI content
Aim for a seventh-grade or below reading level when creating UI content for GitHub. Write text that is straightforward, without trying to be creative with words.
content
37 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
GitHub voice characteristics
GitHub's voice is: clear but not cold, conversational but not jargon-y, inclusive but not disingenuous, and helpful but not overly-prescriptive. Tone is almost always informal and positive, with adjustments depending on channel, audience, and emotional state.
Humor in error messages and waiting states
Humor is not welcome in error messages, when waiting, or when something fails. Error messages should be understandable by humans.
Pull request abbreviation
Pull request should never be abbreviated. It is always lowercase unless it is starting a sentence.
Time format in content
When referring to times, use am and pm, and not any other variation such as a.m., A.M., or AM.
Emoji usage guidelines
Avoid using emojis, but when you do: use them only at the end of a sentence, use only well-recognized emojis, do not repeat emojis, and use emojis that will work well in both dark and light modes.
Error message principles
Error messages should be friendly and helpful, avoid jargon, and not blame the user. Be specific about what is required or went wrong. Do not apologize too much. Do not try to be funny or humorous in error messages.
Feedback message consistency
Feedback should be clear and reassuring, using the same terms used by the UI elements that triggered it. Do not try to be funny, and avoid jargon.
Form labels and titles capitalization
Use sentence case for form titles, labels, and fields. Do not include colons in form labels.
Labels and buttons capitalization and punctuation
All labels and button text should be in sentence case and not include punctuation. When a sentence or label starts with a number, the number is the first word and the rest should be lowercase.
Action labels verb usage
Action labels should start with an imperative verb that clearly indicates what to expect. Action labels can be shortened to only include an adjective and a noun.
Sign in vs log in
Use 'sign in' rather than 'log in'.
Link text guidelines
Link text should be meaningful and unique, with as few duplicated references as possible. The link itself or its programmatically determined context (such as aria labels or text within the same paragraph) should provide information about where the link will take you. Never say 'here' or 'click here' in link text.
Image link context
Set the context of an image link from the text within the same container, so users understand where the link leads.
Headings, labels, and buttons punctuation
Headings, labels, and buttons should not include punctuation. Exclamation marks are generally not appropriate in UI content.
References to page sections in text
When referring to unclickable page names and sections, write them as they appear in the interface in quotation marks.
References to clickable UI elements in text
When referring to button or link text that a user should click on, use bold text without quotation marks. Make sure all UI references match the capitalization in the interface. For mobile app experiences, use 'tap' instead of 'click'.
Folder references in text
When referring to a folder, use a code tag.
Pronoun usage in UI content
In most instances, address the user as 'you' and items owned by the user as 'your' or 'yours'. Exceptions exist for legal language such as when a user needs to agree to terms or confirm a destructive action.
Words to avoid in content
Do not say that something is 'easy', 'quick', or that the user 'just' needs to do something. Do not capitalize common terms; only proper nouns and product names should be capitalized. Do not use emoji in UI content or to replace words. Use 'and' instead of an ampersand or plus sign. Do not use exclamation marks to indicate excitement. Do not use greater than and less than symbols to indicate steps in a flow. Do not use semicolons.
Top 10 content rules summary
The most important content guidelines are: write in plain English without sounding like a robot; be brief and remove unnecessary words like adjectives and adverbs; use active voice; use sentence case and capitalize only when necessary; always capitalize GitHub correctly; avoid gendered language; do not use slang or culturally-specific references; do not use 'here' or 'click here' in calls to action; be thoughtful when introducing humor to the interface; and have someone else proofread your text.
Acronym usage
Use acronyms when they are more widely used than the spelled out term.
Octovisuals intended use and access
Octovisuals are GitHub's internal set of logos and visuals for brand and marketing usage. They are intended for internal use only and can only be accessed by GitHub staff.
Permitted GitHub logos available
Two permitted GitHub logos are available for use: the GitHub Logotype (horizontal logo) and the GitHub Logomark also called Invertocat (mark only). Both are available for download.
GitHub logo use best practices - do
GitHub logos may be used to link to GitHub, as a social button to link to GitHub profiles or projects, to inform others that a project integrates with GitHub, in blog posts or news articles about GitHub, and should be used less prominently than your own company or product name or logo.
GitHub logo use best practices - don't
Do not use the GitHub name or any GitHub logo in a way that suggests you are GitHub, your offering is by GitHub, or that GitHub is endorsing you. Do not use any GitHub logo as the icon for your business, offering, project, domain, social media account, or website. Do not modify the permitted GitHub logos including changing color, dimensions, or combining with other words or elements. Do not use GitHub trademarks, logos, or artwork without prior written permission.
GitHub trademark and copyright ownership
GITHUB, the GITHUB logo design, the INVERTOCAT logo design, OCTOCAT, and the OCTOCAT logo design are trademarks of GitHub, Inc., registered in the United States and other countries. The OCTOCAT design is the exclusive property of GitHub, Inc and has been federally registered with the United States Copyright Office. No adaptation or use of any kind of registered trademarks or copyrights is allowed without express written permission of GitHub, Inc.
GitHub shared components definition
GitHub shared components are application-specific components shared by GitHub feature teams but not in Primer. They are shared with other teams by developing them as React components within the ui/packages/ monorepo.
Recommendation to use Primer components first
Teams are encouraged to rely only on Primer components where possible, and not all patterns from shared components will be upstreamed to Primer.
Monorepo baseline configurations
The ui/packages/ monorepo provides a solid foundation with baseline configurations for linting, accessibility scanning using Axe, and Storybook previews.
Shared components documentation location
GitHub shared components are documented in a private Storybook instance at ui/packages/ Storybook, accessible only to GitHub staff.
Shared components ownership and Figma
Shared components are owned by feature teams and will not exist in the Primer Web Figma component library unless they have been upstreamed into Primer.
VSCode extension for sx to CSS migration
A VSCode extension is available (ian-sanders.sx-to-css) to assist with migrating React code to CSS Modules. The extension automatically handles converting JavaScript syntax to CSS, replacing Primer theme keywords with CSS variables, creating a module file, and more.
Primer React focuses on presentational components
Primer React components focus primarily on presentational components that help standardize common design patterns. They do not handle fetching and submitting data to or from APIs. If you need to handle data in a Primer Component, create a wrapper around the Primer Component to do so.
Pattern components vs helper components
Primer React components fall into two categories: Pattern components help repeat commonly used UI patterns and interactions to maintain brand and user experience, with examples including Button, Avatar, and Label. Helper components help users achieve common CSS patterns while maintaining control over values, with Box as an example.
Flexibility through the sx prop
Primer React provides styling flexibility through the sx prop, which enables small customizations to color and spacing using values from the theme. Users also have the option to override the theme with a theme of their own.
Design philosophy: assume people will break the rules
While Primer React aims to standardize design, the philosophy is to assume that people will break the rules and provide safe ways for them to do so.