Documentation audience and assumed knowledge
Primer documentation is primarily aimed at GitHub designers and engineers at various levels of experience. Readers are assumed to know basic design concepts like consistency and terms such as 'white space' or 'scale'. GitHub-specific terminology should be linked to a glossary or other documents. Terms readers may want to know more about should link to authoritative sources like MDN and W3C. In non-engineering docs, code examples can be used but programming language expertise should not be assumed.
Voice and tone guidelines for documentation
Write affirmatively using imperative mood for clear instructions. Keep sentences and paragraphs short. Use contractions and write conversationally without sounding robotic. Avoid sarcasm, irony, double negatives, and expressions like 'easy', 'simply', 'quick', or 'just'. Avoid idioms. Use active voice with imperative mood: 'Open Figma' not 'Figma can be opened'. Avoid possessive 'our' and do not address Primer as 'our design system'. Use 'we' to refer specifically to the Design Systems / Infrastructure team only.
Primer documentation principles
Primer documentation should be concise but friendly, avoiding unnecessary words while maintaining approachable tone. Documentation should be universally understood by assuming readers are members of the public or new to GitHub, avoiding internal phrases. Code examples should promote production-quality best practices and follow accessibility standards.
Grammar and US spelling requirements
Follow GitHub content guidelines using US spelling (e.g., 'Color palette' not 'Colour palette'). Use sentence case for titles ('Utility classes' not 'Utility Classes'). Capitalize only proper nouns and product names ('Open a pull request' not 'Open a Pull Request'). Avoid positional language like 'below' and use 'that follows' instead. Use contractions ('Don't' not 'Do not'). Exclamation points are acceptable in moderation.
Documentation images and examples requirements
All documentation examples should be of real github.com examples. Examples should include only the most important part of the UI and not attempt to show entire UI. Use meaningful copy in examples (e.g., 'New issue' instead of 'Button' as text inside a button). Use the Figma Doctocat content template for consistent images across Primer documentation.
Publishing checklist for documentation
Before publishing documentation: spellcheck text and UI text in images using an automated tool. Have someone else proofread the document and images. Test all links and indicate which links only work for GitHub staff. Verify no private or sensitive information is present. Verify all images include alt text. Always link to source when mentioning or referring to other styles and documentation.
Component documentation naming conventions
Use sentence case when referring to component names. Do not capitalize the component name in the middle of a sentence. When writing the component description, introduce the component directly without 'a' or 'an'. Example: 'Action menu is a component based on action list for creating a menu of actions that expands through a trigger button.'
Component documentation structure sections
Component documentation should include: Description (what the component is, concise without usage info), Usage (when to use, best practices, do/don't examples), Anatomy (elements that make up the component including typography, spacing, styles and sub components), Options (different sizes, typography, layout variations, spacing, applications), Interactions (specific behaviors, clickability, state-based interactions), Accessibility (keyboard navigation, touch targets, assistive technology guidelines, known issues with links to GitHub issues labeled with both 'accessibility' and 'component: name'), and Related components and patterns.
Minimum-viable component documentation approach
Minimum-viable documentation should be accurate, informative but concise, and visible. Minimum-viable description requires brief text describing the component, link to available implementations, and image if applicable. Minimum-viable usage guidance requires proper usage guides and visual examples such as image or gif. Add more documentation if readily available and doesn't require huge time investment, such as related components and accessibility guidelines.
Known accessibility issues documentation format
To document known accessibility issues in component documentation: import AccessibilityLink component at top of file with `import {AccessibilityLink} from '~/src/components/accessibility-link'`. Add section to markdown content under the Accessibility heading with markdown: `## Accessibility` and `### Known accessibility issues (GitHub staff only)` followed by `<AccessibilityLink label="ComponentName"/>`.
Primer Figma community access
Public access to shared Primer libraries and files is available from the Primer Figma Community page at https://www.figma.com/@primer. Access to the GitHub Figma organization is currently only available to members of the GitHub team.
Primer Figma team libraries available
GitHub uses Figma to distribute Primer through team libraries. Each library covers a different part of the system. Core asset libraries for Primer can be found in the Primer team's 'Core libraries (internal)' project or the primer community page. The core libraries include: Primer Primitives (internal and community versions) containing all color, type, and spacing styles used within Primer; Primer Web (internal and community versions) containing UI components for GitHub's web interfaces; Primer Mobile (internal only) containing UI components for GitHub's native mobile platforms; and Octicons, GitHub's custom icon library.
Primer Figma template libraries
Primer provides template libraries to jump-start the design process. Primer Interfaces contains templates for common views and UI patterns found within GitHub's web product. Primer Email contains templates used to design product emails for GitHub.
Primer definition and purpose
Primer is a design language built for GitHub by GitHub. It provides guidelines that are a collection of open source principles, standards, and recommendations for designing GitHub. As a design language, Primer provides common grammar and vocabulary to build cohesive, accessible, responsive, and efficient experiences.
Primer's goal for cohesive experience
Primer focuses on the user experience so people can benefit from using a platform that is cohesive, no matter where in the platform they are. Familiar patterns help people intuitively navigate to information and discover new features. If a page behaves and feels familiar, it allows people to focus on the task at hand, instead of requiring them to parse UI that looks completely new.
Primer's responsive design approach
Primer provides reusable patterns and components that can streamline the creation of responsive-friendly and accessible designs. Primer patterns and components aim towards accessible solutions that don't dilute efficient UI interactions. It focuses on responsive design that doesn't reduce desktop experiences into mobile-first solutions.
Design for efficiency principle
GitHub is a platform used for productivity. Primer aims to encourage flow, focus, and an experience that is fast and compact. By providing a cohesive, inclusive, and responsive design, Primer's goal is to remove as much friction as possible between the human and the software.
The Zen of GitHub aphorisms
The Zen of GitHub consists of 14 aphorisms: Responsive is better than fast, It's not fully shipped until it's fast, Anything added dilutes everything else, Practicality beats purity, Approachable is better than simple, Mind your words they are important, Speak like a human, Half measures are as bad as nothing at all, Encourage flow, Non-blocking is better than blocking, Favor focus over features, Avoid administrative distraction, Design for failure, Keep it logically awesome.
eslint-plugin-primer-react is experimental
eslint-plugin-primer-react is experimental. Issues should be reported in the primer/react repository on GitHub.
eslint-plugin-primer-react installation command
Install eslint-plugin-primer-react using npm with: npm install --save-dev eslint-plugin-primer-react. Alternatively, use yarn with: yarn add --dev eslint-plugin-primer-react. This requires ESLint and Primer React to already be installed.
ESLint configuration for Primer React recommended rules
To enable recommended Primer React ESLint rules, extend the configuration in your ESLint configuration file with plugin:primer-react/recommended. The configuration format is: {"extends": ["plugin:primer-react/recommended"]}.
Component status documentation location
Primer provides a component status guide that documents accessibility reviews and the component lifecycle status of each component. The guide references a separate component lifecycle documentation for detailed information on each status.
Component lifecycle guide reference
Primer maintains a component lifecycle guide that explains the meaning and requirements of each component status. This guide should be consulted to understand the status categories applied to components.
Status table availability
Primer provides a StatusTable component that displays the accessibility review status and component lifecycle status for all Primer components in a tabular format.
Primer CLI design system purpose
Primer is a design system for terminal-like implementations of GitHub, providing principles and design foundations for creating command-line experiences.