Primer
+The design system that powers GitHub
+ Install Primer 9.3.0 +diff --git a/CNAME b/CNAME new file mode 100644 index 0000000..00fed49 --- /dev/null +++ b/CNAME @@ -0,0 +1 @@ +primercss.io \ No newline at end of file diff --git a/apple-touch-icon.png b/apple-touch-icon.png new file mode 100644 index 0000000..845aabe Binary files /dev/null and b/apple-touch-icon.png differ diff --git a/archive/about/index.html b/archive/about/index.html new file mode 100644 index 0000000..63c5cea --- /dev/null +++ b/archive/about/index.html @@ -0,0 +1,84 @@ + + +
+ + + + + + + + +Learn more about this styleguide, particularly how it’s built and who maintains it.
+ +Primer is GitHub’s internal CSS framework. It includes basic global styling for utilities, objects, components, and our general guidelines for writing HTML and CSS. It’s been used internally at GitHub for years now.
+ +Primer is currently being overhauled. The upcoming version of Primer will add new styles and bring the existing styles up to date, improve the build process, and include new and improved documentation. New styles will be open-sourced in the Primer repo and on npm as we add them, and the new documentation site will be shared when it's complete, currently slated to happen in mid-to-late 2017.
+ +Maintained by the GitHub Design Systems team.
+ +Flash messages, or alerts, inform users of successful or pending actions. Use them sparingly. Don’t show more than one at a time.
+ +Flash messages start off looking decently neutral—they’re just light blue rounded rectangles.
+ +<div class="flash">
+ Flash message goes here.
+</div>
You can put multiple paragraphs of text in a flash message—the last paragraph’s bottom margin
will be automatically override.
This is a longer flash message in it's own paragraph. It ends up looking something like this. If we keep adding more text, it'll eventually wrap to a new line.
+And this is another paragraph.
+<div class="flash">
+ <p>This is a longer flash message in it's own paragraph. It ends up looking something like this. If we keep adding more text, it'll eventually wrap to a new line.</p>
+ <p>And this is another paragraph.</p>
+</div>
Should the need arise, you can quickly space out your flash message from surrounding content with a .flash-messages
wrapper. Note the extra top and bottom margin in the example below.
<div class="flash-messages">
+ <div class="flash">
+ Flash message goes here.
+ </div>
+</div>
Add .flash-warn
or .flash-error
to the flash message to make it yellow or red, respectively.
<div class="flash flash-warn">
+ Flash message goes here.
+</div>
<div class="flash flash-error">
+ Flash message goes here.
+</div>
Add an icon to the left of the flash message to give it some funky fresh attention. Just add .flash-with-icon
and your Octicon.
<div class="flash flash-with-icon">
+ <span class="octicon octicon-alert"></span>
+ Flash message with an icon goes here.
+</div>
Add a JavaScript enabled (via Crema) dismiss (close) icon on the right of any flash message.
+ +<div class="flash">
+ <span class="octicon octicon-x flash-close js-flash-close"></span>
+ Dismissable flash message goes here.
+</div>
Avatars are images that users can set as their profile picture. On GitHub, they’re always going to be rounded squares. They can be custom photos, uploaded by users, or generated as Identicons as a placeholder.
+ +Add .avatar
to any <img>
element to make it an avatar. This resets some key styles for alignment, address a Firefox image placeholder bug, and rounds the corners.
Be sure to set width
and height
attributes for maximum browser performance.
<img class="avatar" src="https://avatars3.githubusercontent.com/u/9919?v=3&s=144" width="72" height="72">
We occasionally use smaller avatars. Anything less than 48px
wide should include the .avatar-small
modifier class to reset the border-radius
to a more appropriate level.
<img class="avatar avatar-small" src="https://avatars3.githubusercontent.com/u/9919?v=3&s=64" width="32" height="32">
When you need a larger parent avatar, and a smaller child one, overlaid slightly, use the parent-child classes.
+ +<div class="avatar-parent-child left">
+ <img class="avatar" src="https://avatars3.githubusercontent.com/u/9919?v=3&s=96" width="48" height="48">
+ <img class="avatar avatar-child" src="https://avatars3.githubusercontent.com/u/9919?v=3&s=40" width="20" height="20">
+</div>
Blankslates are for when there is a lack of content within a page or section. Use them as placeholders to tell users why something isn’t there. Be sure to provide an action to add content as well.
+ +Wrap some content in the outer .blankslate
wrapper to give it the blankslate appearance.
Use it to provide information when no dynamic content exists.
+<div class="blankslate">
+ <h3>This is a blank slate</h3>
+ <p>Use it to provide information when no dynamic content exists.</p>
+</div>
When it helps the message, include (relevant) icons in your blank slate. Add .blankslate-icon
to any .mega-octicon
s as the first elements in the blankslate, like so.
Use it to provide information when no dynamic content exists.
+<div class="blankslate">
+ <span class="mega-octicon octicon-git-commit blankslate-icon"></span>
+ <span class="mega-octicon octicon-tag blankslate-icon"></span>
+ <span class="mega-octicon octicon-git-branch blankslate-icon"></span>
+ <h3>This is a blank slate</h3>
+ <p>Use it to provide information when no dynamic content exists.</p>
+</div>
Add an additional optional class to the .blankslate
to change its appearance.
Narrows the blankslate container to not occupy the entire available width.
+ +Use it to provide information when no dynamic content exists.
+<div class="blankslate blankslate-narrow">
+ <h3>This is a blank slate</h3>
+ <p>Use it to provide information when no dynamic content exists.</p>
+</div>
Removes the border-radius
on the top corners.
Use it to provide information when no dynamic content exists.
+<div class="blankslate blankslate-capped">
+ <h3>This is a blank slate</h3>
+ <p>Use it to provide information when no dynamic content exists.</p>
+</div>
Significantly increases the vertical padding.
+ +Use it to provide information when no dynamic content exists.
+<div class="blankslate blankslate-spacious">
+ <h3>This is a blank slate</h3>
+ <p>Use it to provide information when no dynamic content exists.</p>
+</div>
Increases the size of the text in the blankslate
+ +Use it to provide information when no dynamic content exists.
+<div class="blankslate blankslate-large">
+ <h3>This is a blank slate</h3>
+ <p>Use it to provide information when no dynamic content exists.</p>
+</div>
Removes the background-color
and border
.
Use it to provide information when no dynamic content exists.
+<div class="blankslate blankslate-clean-background">
+ <h3>This is a blank slate</h3>
+ <p>Use it to provide information when no dynamic content exists.</p>
+</div>
Buttons are used for actions, like in forms, while textual hyperlinks are used for destinations, or moving from one page to another.
+ +Use the standard—yet classy—.btn
for form actions and primary page actions. These are used extensively around the site.
When using a <button>
element, always specify a type
. When using a <a>
element, always add role="button"
for accessibility.
<button class="btn" type="button">Button button</button>
+<a class="btn" href="#" role="button">Link button</a>
You can find them in two sizes: the default .btn
and the smaller .btn-sm
.
<button class="btn" type="button">Button</button>
+<button class="btn btn-sm" type="button">Small button</button>
Primary buttons are green and are used to indicate the primary action on a page. When you need your buttons to stand out, use .btn.btn-primary
. You can use it with both button sizes—just add .btn-primary
.
<button class="btn btn-primary" type="button">Primary button</button>
+<button class="btn btn-sm btn-primary" type="button">Small primary button</button>
Danger buttons are red. They help reiterate that the intended action is important or potentially dangerous (e.g., deleting a repo or transferring ownership). Similar to the primary buttons, just add .btn-danger
.
<button class="btn btn-danger" type="button">Danger button</button>
+<button class="btn btn-sm btn-danger" type="button">Small danger button</button>
Outline buttons downplay an action as they appear like boxy links. Just add .btn-outline
and go.
<button class="btn btn-outline" type="button">Outline button</button>
+<button class="btn btn-sm btn-outline" type="button">Outline button</button>
Disable <button>
elements with the boolean disabled
attribute and <a>
elements with the .disabled
class.
<button class="btn" type="button" disabled>Disabled button</button>
+<a class="btn disabled" href="#" role="button">Disabled button</a>
Similar styles are applied to primary, danger, and outline buttons:
+ + +<button class="btn btn-primary" type="button" disabled>Disabled button</button>
+<a class="btn btn-primary disabled" href="#" role="button">Disabled button</a>
<button class="btn btn-danger" type="button" disabled>Disabled button</button>
+<a class="btn btn-danger disabled" href="#" role="button">Disabled button</a>
<button class="btn btn-outline" type="button" disabled>Disabled button</button>
+<a class="btn btn-outline disabled" href="#" role="button">Disabled button</a>
Make any button full-width by adding .btn-block
. It adds width: 100%;
, changes the display
from inline-block
to block
, and centers the button text.
<p><button class="btn btn-block" type="button">Block button</button></p>
+<p><button class="btn btn-sm btn-block" type="button">Small block button</button></p>
You can easily append a count to a small button. Add the .with-count
class to the .btn-sm
and then add the .social-count
after the button.
Be sure to clear the float added by the additional class.
+ +<div class="clearfix">
+ <a class="btn btn-sm btn-with-count" href="#" role="button">
+ <span class="octicon octicon-eye"></span>
+ Watch
+ </a>
+ <a class="social-count" href="#">6</a>
+</div>
You can also use the counter component within buttons:
+ +<button class="btn" type="button">
+ Button
+ <span class="counter">12</span>
+</button>
+
+<button class="btn btn-primary" type="button">
+ Button
+ <span class="counter">12</span>
+</button>
+
+<button class="btn btn-danger" type="button">
+ Button
+ <span class="counter">12</span>
+</button>
+
+<button class="btn btn-outline" type="button">
+ Button
+ <span class="counter">12</span>
+</button>
Have a hankering for a series of buttons that are attached to one another? Wrap them in a .btn-group
and the buttons will be rounded and spaced automatically.
<div class="btn-group">
+ <button class="btn" type="button">Button</button>
+ <button class="btn" type="button">Button</button>
+ <button class="btn" type="button">Button</button>
+</div>
+
+<div class="btn-group">
+ <button class="btn btn-outline" type="button">Button</button>
+ <button class="btn btn-outline" type="button">Button</button>
+ <button class="btn btn-outline" type="button">Button</button>
+</div>
+
+<div class="btn-group">
+ <button class="btn btn-sm" type="button">Button</button>
+ <button class="btn btn-sm" type="button">Button</button>
+ <button class="btn btn-sm" type="button">Button</button>
+</div>
Add .btn-group-form
to <form>
s within .btn-group
s for proper spacing and rounded corners.
<div class="btn-group">
+ <form class="btn-group-form">
+ <button class="btn" type="button">Button in a form</button>
+ </form>
+ <button class="btn" type="button">Button</button>
+ <button class="btn" type="button">Button</button>
+</div>
Use .hidden-text-expander
to indicate and toggle hidden text.
<span class="hidden-text-expander">
+ <button type="button" class="ellipsis-expander">…</button>
+</span>
You can also make the expander appear inline by adding .inline
.
The look and feel of our company and product relies on using a handful of specific colors that help convey meaning and purpose.
+ +Style individual form controls and utilize common layouts.
+ +<fieldset>
s, WebKit validation bubbles, and most textual <input>
s.<input>
s are styled automatically, but .form-control
is available should you need it.type
on your <button>
s.Form controls in Primer currently have no basic layout specified (this is by design). You’ll need to use <fieldset>
s, <div>
s, or other elements and styles to rearrange them.
<form>
+ <label for="name">Name</label>
+ <input class="form-control" type="text" id="name">
+
+ <label for="email">Email address</label>
+ <input class="form-control" type="email" id="email">
+
+ <label>
+ <input type="checkbox"> Remember me
+ </label>
+
+ <label>
+ <input type="radio" id="herp" name="herpderp" checked> Herp
+ </label>
+ <label>
+ <input type="radio" id="derp" name="herpderp"> Derp
+ </label>
+
+ <button class="btn" type="submit">Submit</button>
+</form>
Textual form controls have a white background by default. You can change this to a light gray with .input-contrast
.
<form>
+ <input class="form-control" type="text" placeholder="Default input">
+ <input class="form-control input-contrast" type="text" placeholder="Input with contrast">
+</form>
Make inputs smaller, larger, or full-width with an additional class.
+ +<form>
+ <input class="form-control input-sm" type="text" placeholder="Small input">
+</form>
<form>
+ <input class="form-control input-lg" type="text" placeholder="Large input">
+</form>
<form>
+ <input class="form-control input-block" type="text" placeholder="Full-width input">
+</form>
Primer adds light height
and vertical-align
styles to <select>
s for all browsers to render them consistently with textual inputs.
<form>
+ <select class="form-select">
+ <option>Choose an option</option>
+ <option>Git</option>
+ <option>Subversion</option>
+ <option>Social Coding</option>
+ <option>Beets</option>
+ <option>Bears</option>
+ <option>Battlestar Galactica</option>
+ </select>
+</form>
Use the .select-sm
class to resize both default and custom <select>
s to match the size of our small buttons.
<select class="form-select select-sm">
+ <option>Choose an option</option>
+ <option>Git</option>
+ <option>Subversion</option>
+ <option>Social Coding</option>
+ <option>Beets</option>
+ <option>Bears</option>
+ <option>Battlestar Galactica</option>
+</select>
+
+<select class="form-select select-sm">
+ <option>Choose an option</option>
+ <option>Git</option>
+ <option>Subversion</option>
+ <option>Social Coding</option>
+ <option>Beets</option>
+ <option>Bears</option>
+ <option>Battlestar Galactica</option>
+</select>
<form>
+ <dl class="form-group">
+ <dt><label>Example Text</label></dt>
+ <dd><input class="form-control" type="text" value="Example Value"></dd>
+ </dl>
+
+ <dl class="form-group">
+ <dt><label>Example Select</label></dt>
+ <dd>
+ <select class="form-select">
+ <option>Choose an option</option>
+ <option>Git</option>
+ <option>Subversion</option>
+ <option>Social Coding</option>
+ <option>Beets</option>
+ <option>Bears</option>
+ <option>Battlestar Galactica</option>
+ </select>
+ </dd>
+ </dl>
+
+ <dl class="form-group">
+ <dt><label>Example Textarea</label></dt>
+ <dd>
+ <textarea class="form-control"></textarea>
+ </dd>
+ </dl>
+</form>
Convey errors and warnings for form groups. Add the appropriate class—either .errored
or .warn
—to the <dl class="form-group">
to start. Then, house your error messaging in an additional <dd>
with either .error
or .warning
.
<form>
+ <dl class="form-group errored">
+ <dt><label>Example Text</label></dt>
+ <dd><input class="form-control" type="text" value="Example Value"></dd>
+ <dd class="error">This example input has an error.</dd>
+ </dl>
+ <br>
+ <dl class="form-group warn">
+ <dt><label>Example Text</label></dt>
+ <dd><input class="form-control" type="text" value="Example Value"></dd>
+ <dd class="warning">This example input has a warning.</dd>
+ </dl>
+</form>
Utilities to spice up the alignment and styling of checkbox and radio controls.
+ + +<form>
+ <div class="form-checkbox">
+ <label>
+ <input type="checkbox" checked="checked">
+ Available for hire
+ </label>
+ <p class="note">
+ This will do insanely <strong>awesome</strong> and <strong>amazing</strong> things!
+ </p>
+ </div>
+</form>
You may also add emphasis to the label:
+ + +<form>
+ <div class="form-checkbox">
+ <label>
+ <input type="checkbox" checked="checked">
+ <em class="highlight">Available for hire</em>
+ </label>
+ </div>
+</form>
Attached an input and button to one another.
+ + +<form>
+ <div class="input-group">
+ <input class="form-control" type="text" placeholder="Username">
+ <span class="input-group-button">
+ <button class="btn">
+ <span class="octicon octicon-clippy"></span>
+ </button>
+ </span>
+ </div>
+</form>
Align buttons to the right—via float: right
on the buttons—in forms with .form-actions
. The floats are automatically cleared for you.
<div class="form-actions">
+ <button type="button" class="btn btn-primary">Save changes</button>
+ <button type="button" class="btn">Cancel</button>
+</div>
Best practices and guidelines for writing HTML and CSS with approachable formatting, syntax, and more.
+ +<p>
tag. Never use multiple <br>
tags.<ul>
, <ol>
, or <dl>
. Never use a set of <div>
or <p>
.<label>
tag. Especially radio or checkbox elements.<!-- /.element -->
. This just adds to page load time. Plus, most editors have indentation guides and open-close tag highlighting.<br>
, <hr>
, <img>
, and <input>
.tabindex
manually—rely on the browser to set the order.Many attributes don’t require a value to be set, like disabled
or checked
, so don’t set them.
For more information, read the WhatWG section.
+ +Whenever possible, avoid superfluous parent elements when writing HTML. Many times this requires iteration and refactoring, but produces less HTML. For example:
+ + + +<label>
s. No need for for
attributes here—the wrapping automatically associates the two.type
. Use primary buttons for the type="submit"
button and regular buttons for type="button"
.float: right;
on each button.Make use of <thead>
, <tfoot>
, <tbody>
, and <th>
tags (and scope
attribute) when appropriate. (Note: <tfoot>
goes above <tbody>
for speed reasons. You want the browser to load the footer before a table full of data.)
:
in property declarations.{
in rule declarations.#000
unless using rgba()
in raw CSS (SCSS’ rgba()
function is overloaded to accept hex colors as a param, e.g., rgba(#000, .5)
).//
for comment blocks (instead of /* */
).margin: 0;
instead of margin: 0px;
.As a rule of thumb, avoid unnecessary nesting in SCSS. At most, aim for three levels. If you cannot help it, step back and rethink your overall strategy (either the specificity needed, or the layout of the nesting).
+ +Here are some good examples that apply the above guidelines:
+ + + +In general, a flat directory of files works best, but at GitHub we break things down by bundles (separate compiled CSS files) and sections (directories of related content).
+ +GitHub.com uses a handful of bundles. Here’s a simplified representation of our two desktop bundles (split to support IE9’s maximum selector limit per CSS file) and a dedicated mobile bundle for our separate mobile views.
+ + + +Previously we used Sprockets to require files in Primer and at GitHub. Nowadays, we use explicit lists of imports to control the cascade, specificity, and more.
+ + + +This is also how Primer’s styles are to be included, should you need them.
+ +Use px
for font-size
, because it offers absolute control over text. Additionally, unit-less line-height
is preferred because it does not inherit a percentage value of its parent element, but instead is based on a multiplier of the font-size
.
Never reference js-
prefixed class names from CSS files. js-
are used exclusively from JS files.
Use the is-
prefix for state rules that are shared between CSS and JS.
Elements that occur exactly once inside a page should use IDs, otherwise, use classes. When in doubt, use a class name.
+ +When styling a component, start with an element + class namespace (prefer class names over ids), prefer direct descendant selectors by default, and use as little specificity as possible. Here is a good example:
+ + + + + +#selector
) make sure that you have no more than one in your rule declaration. A rule like #header .search #quicksearch { ... }
is considered harmful..listings-layout.bigger
use rules like .listings-layout.listings-bigger
. Think about ack/grep
ing your code in the future.disabled
, mousedown
, danger
, hover
, selected
, and active
should always be namespaced by a class (button.selected
is a good example).Primer is the basecoat of GitHub, made by nerds just like you who share a passion for HTML and CSS.
+Available for use under the MIT license and built with open source projects like SCSS, Jekyll, Grunt, and more.
+Includes a small Gruntfile for compiling our SCSS, Autoprefixer for vendor prefixes, and Parker for CSS stats.
+Primer’s layout includes basic page containers and a single-tiered, fraction-based grid system. That sounds more complicated than it really is though—it’s just containers, rows, and columns.
+ +You can find all the below styles in _layout.scss
.
Center your page’s contents with a .container
.
The container applies width: 980px;
and uses horizontal margin
s to center it.
The grid is pretty standard—you create rows with .columns
and individual columns with a column class and fraction class. Here’s how it works:
.container
to encapsulate everything and provide ample horizontal gutter space.<div class="columns">
.<div class="column">
s..one-fourth
).In practice, your columns will look like the example below.
+ +<div class="container">
+ <div class="columns">
+ <div class="one-fifth column">
+ .one-fifth
+ </div>
+ <div class="four-fifths column">
+ .four-fifths
+ </div>
+ </div>
+
+ <div class="columns">
+ <div class="one-fourth column">
+ .one-fourth
+ </div>
+ <div class="three-fourths column">
+ .three-fourths
+ </div>
+ </div>
+
+ <div class="columns">
+ <div class="one-third column">
+ .one-third
+ </div>
+ <div class="two-thirds column">
+ .two-thirds
+ </div>
+ </div>
+
+ <div class="columns">
+ <div class="one-half column">
+ .one-half
+ </div>
+ <div class="one-half column">
+ .one-half
+ </div>
+ </div>
+</div>
Columns can be centered by adding .centered
to the .column
class.
<div class="columns">
+ <div class="one-half column centered">
+ .one-half
+ </div>
+</div>
Styles for rendering GitHub Flavored Markdown in any project.
+ +Coming soon!
+ +Primer comes with several navigation components. Some were designed with singular purposes, while others were design to be more flexible and appear quite frequently.
+ +The menu is a vertical list of navigational links. A menu’s width and placement must be set by you. If you like, just use our grid columns as a parent. Otherwise, apply a custom width
.
<nav class="menu">
+ <a class="menu-item selected" href="#">Account</a>
+ <a class="menu-item" href="#">Profile</a>
+ <a class="menu-item" href="#">Emails</a>
+ <a class="menu-item" href="#">Notifications</a>
+</nav>
There are a few subcomponents and add-ons that work well with the menu, including avatars, counters, and Octicons.
+ + +<nav class="menu">
+ <a class="menu-item selected" href="#">
+ <span class="octicon octicon-tools"></span>
+ Account
+ </a>
+ <a class="menu-item" href="#">
+ <span class="octicon octicon-person"></span>
+ Profile
+ </a>
+ <a class="menu-item" href="#">
+ <span class="octicon octicon-mail"></span>
+ Emails
+ </a>
+ <a class="menu-item" href="#">
+ <span class="octicon octicon-radio-tower"></span>
+ <span class="counter">3</span>
+ Notifications
+ </a>
+</nav>
You can also add optional headings to a menu. Feel free to use nearly any semantic element with the .menu-heading
class, including inline elements, headings, and more.
<nav class="menu">
+ <span class="menu-heading">Menu heading</span>
+ <a class="menu-item selected" href="#">Account</a>
+ <a class="menu-item" href="#">Profile</a>
+ <a class="menu-item" href="#">Emails</a>
+ <a class="menu-item" href="#">Notifications</a>
+</nav>
When you need to toggle between different views, consider using a tabnav. It’ll given you a left-aligned horizontal row of… tabs!
+ +<div class="tabnav">
+ <nav class="tabnav-tabs">
+ <a href="#" class="tabnav-tab selected">Foo tab</a>
+ <a href="#" class="tabnav-tab">Bar tab</a>
+ </nav>
+</div>
Use .right
to align additional elements in the .tabnav
:
<div class="tabnav">
+ <a class="btn btn-sm right" href="#">Button</a>
+ <nav class="tabnav-tabs">
+ <a href="#" class="tabnav-tab selected">Foo Tab</a>
+ <a href="#" class="tabnav-tab">Bar Tab</a>
+ </nav>
+</div>
Additional bits of text and links can be styled for optimal placement with .tabnav-extra
:
<div class="tabnav">
+ <div class="tabnav-extra right">
+ Tabnav widget text here.
+ </div>
+ <nav class="tabnav-tabs">
+ <a href="#" class="tabnav-tab selected">Foo Tab</a>
+ <a href="#" class="tabnav-tab">Bar Tab</a>
+ </nav>
+</div>
<div class="tabnav">
+ <div class="right">
+ <a class="tabnav-extra" href="#">
+ Tabnav extra link
+ </a>
+ <a class="tabnav-extra" href="#">
+ Tabnav extra link
+ </a>
+ </div>
+ <nav class="tabnav-tabs">
+ <a href="#" class="tabnav-tab selected">Foo Tab</a>
+ <a href="#" class="tabnav-tab">Bar Tab</a>
+ </nav>
+</div>
A vertical list of filters. Grey text on white background. Selecting a filter from the list will fill its background with blue and make the text white.
+ +<ul class="filter-list">
+ <li>
+ <a href="#" class="filter-item selected">
+ <span class="count">21</span>
+ First filter
+ </a>
+ </li>
+ <li>
+ <a href="#" class="filter-item">
+ <span class="count">3</span>
+ Second filter
+ </a>
+ </li>
+ <li>
+ <a href="#" class="filter-item">
+ Third filter
+ </a>
+ </li>
+</ul>
Coming soon…
+ +Scaffolding refers to the global resets and dependencies that Primer is built upon.
+ +Primer makes use of certain HTML elements and CSS properties that require the use of the HTML5 doctype. Include it at the beginning of all your pages.
+ + + +We reset box-sizing
to border-box
for every element in Primer. This allows us to more easily assign widths to elements that also have padding
and border
s.
For improved cross-browser rendering, we use Normalize.css to correct small inconsistencies across browsers and devices.
+ +States, or state indicators, inform users of the current status of a particular item. Included common states are Open, Closed, or Merged, each requiring it’s own modifier class.
+ +<span class="state state-open">Open</span>
+<span class="state state-proposed">Open</span>
+<span class="state state-reopened">Open</span>
<span class="state state-closed">Closed</span>
<span class="state state-merged">Merged</span>
Add tooltips built entirely in CSS to nearly any element. Just add a few classes and an aria-label
attribute.
In addition, you’ll want to specify a direction:
+ +.tooltipped-n
.tooltipped-ne
.tooltipped-e
.tooltipped-se
.tooltipped-s
.tooltipped-sw
.tooltipped-w
.tooltipped-nw
Tooltip classes will conflict with Octicon classes, and as such, must go on a parent element instead of the icon.
+ +<span class="tooltipped tooltipped-n border p-2 mb-2 mr-2 left" aria-label="This is the tooltip.">
+ Tooltip North
+</span>
+<span class="tooltipped tooltipped-ne border p-2 mb-2 mr-2 left" aria-label="This is the tooltip.">
+ Tooltip North East
+</span>
+<span class="tooltipped tooltipped-e border p-2 mb-2 mr-2 left" aria-label="This is the tooltip.">
+ Tooltip East
+</span>
+<span class="tooltipped tooltipped-se border p-2 mb-2 mr-2 left" aria-label="This is the tooltip.">
+ Tooltip South East
+</span>
+<span class="tooltipped tooltipped-s border p-2 mb-2 mr-2 left" aria-label="This is the tooltip.">
+ Tooltip South
+</span>
+<span class="tooltipped tooltipped-sw border p-2 mb-2 mr-2 left" aria-label="This is the tooltip.">
+ Tooltip South West
+</span>
+<span class="tooltipped tooltipped-w border p-2 mb-2 mr-2 left" aria-label="This is the tooltip.">
+ Tooltip West
+</span>
+<span class="tooltipped tooltipped-nw border p-2 mb-2 mr-2 left" aria-label="This is the tooltip.">
+ Tooltip North West
+</span>
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 modifier class you can use to override this. .tooltipped-no-delay
<span class="tooltipped tooltipped-n tooltipped-no-delay border p-2" aria-label="This is the tooltip.">
+ Tooltip no delay
+</span>
Headings, paragraphs, blockquotes, lists, and more have some global resets. It’s worth noting these aren’t the same as our Markdown styles.
+ +<h1>h1. Primer heading</h1>
+<h2>h2. Primer heading</h2>
+<h3>h3. Primer heading</h3>
+<h4>h4. Primer heading</h4>
+<h5>h5. Primer heading</h5>
+<h6>h6. Primer heading</h6>
Nullam quis risus eget urna mollis ornare vel eu leo. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Nullam id dolor id nibh ultricies vehicula.
+Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec ullamcorper nulla non metus auctor fringilla. Duis mollis, est non commodo luctus, nisi erat porttitor ligula, eget lacinia odio sem nec elit. Donec ullamcorper nulla non metus auctor fringilla.
+Maecenas sed diam eget risus varius blandit sit amet non magna. Donec id elit non mi porta gravida at eget metus. Duis mollis, est non commodo luctus, nisi erat porttitor ligula, eget lacinia odio sem nec elit.
<p>Nullam quis risus eget urna mollis ornare vel eu leo. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Nullam id dolor id nibh ultricies vehicula.</p>
+<p>Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec ullamcorper nulla non metus auctor fringilla. Duis mollis, est non commodo luctus, nisi erat porttitor ligula, eget lacinia odio sem nec elit. Donec ullamcorper nulla non metus auctor fringilla.</p>
+<p>Maecenas sed diam eget risus varius blandit sit amet non magna. Donec id elit non mi porta gravida at eget metus. Duis mollis, est non commodo luctus, nisi erat porttitor ligula, eget lacinia odio sem nec elit.</p>
Make a paragraph stand out by adding .lead
.
+ Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor. Duis mollis, est non commodo luctus. +
<p class="lead">
+ Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor. Duis mollis, est non commodo luctus.
+</p>
Styling for common inline HTML5 elements.
+ +You can use the mark tag to highlight text.
+This line of text is meant to be treated as deleted text.
This line of text is meant to be treated as no longer accurate.
This line of text is meant to be treated as an addition to the document.
+This line of text will render as underlined
+This line of text is meant to be treated as fine print.
+This line rendered as bold text.
+This line rendered as italicized text.
<p>You can use the mark tag to <mark>highlight</mark> text.</p>
+<p><del>This line of text is meant to be treated as deleted text.</del></p>
+<p><s>This line of text is meant to be treated as no longer accurate.</s></p>
+<p><ins>This line of text is meant to be treated as an addition to the document.</ins></p>
+<p><u>This line of text will render as underlined</u></p>
+<p><small>This line of text is meant to be treated as fine print.</small></p>
+<p><strong>This line rendered as bold text.</strong></p>
+<p><em>This line rendered as italicized text.</em></p>
Wrap <blockquote>
around any HTML as the quote. For straight quotes, we recommend a <p>
.
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante.
+
<blockquote>
+ <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante.</p>
+</blockquote>
A list of items in which the order does not explicitly matter.
+ +<ul>
+ <li>Lorem ipsum dolor sit amet</li>
+ <li>Nulla volutpat aliquam velit
+ <ul>
+ <li>Phasellus iaculis neque</li>
+ <li>Purus sodales ultricies</li>
+ <li>Vestibulum laoreet porttitor sem</li>
+ <li>Ac tristique libero volutpat at</li>
+ </ul>
+ </li>
+ <li>Faucibus porta lacus fringilla vel</li>
+ <li>Aenean sit amet erat nunc</li>
+ <li>Eget porttitor lorem</li>
+</ul>
A list of items in which the order does explicitly matter.
+ +<ol>
+ <li>Lorem ipsum dolor sit amet</li>
+ <li>Nulla volutpat aliquam velit
+ <ol>
+ <li>Phasellus iaculis neque</li>
+ <li>Purus sodales ultricies</li>
+ <li>Vestibulum laoreet porttitor sem</li>
+ <li>Ac tristique libero volutpat at</li>
+ </ol>
+ </li>
+ <li>Faucibus porta lacus fringilla vel</li>
+ <li>Aenean sit amet erat nunc</li>
+ <li>Eget porttitor lorem</li>
+</ol>
There are a handful of utilities in Primer for quick behaviors, floats, colors, alignment, and more.
+ +.css-truncate
will shorten text with an ellipsis. The maximum width of the truncated text can be changed by overriding the max-width of the .css-truncate-target.
<span class="branch-ref css-truncate css-truncate-target">
+ really-long-branch-name
+</span>
You can reveal the entire string on hover with the addition of .expandable
.
<span class="css-truncate expandable">
+ <span class="branch-ref css-truncate-target">this-is-a-really-long-branch-name</span>
+</span>
Add a number or unread indicator to navs and more with a counter.
+ +<span class="counter">9</span>
Quickly float something to the left or right, and clear them later.
+ +.left
+ .right
+<div class="clearfix">
+ <code class="left">.left</code>
+ <code class="right">.right</code>
+</div>
Easily center block level content if it’s not taking up the full width of the parent. Can be used on grid columns or any other elements.
+ + +<nav class="menu centered">
+ <a class="menu-item selected" href="#">Account</a>
+ <a class="menu-item" href="#">Profile</a>
+ <a class="menu-item" href="#">Emails</a>
+ <a class="menu-item" href="#">Notifications</a>
+</nav>
Change the text-align
on elements with a class.
Left aligned text.
+Right aligned text.
+Center aligned text.
<p class="text-left">Left aligned text.</p>
+<p class="text-right">Right aligned text.</p>
+<p class="text-center">Center aligned text.</p>
Fill in an element with background colors.
+ +<span class="d-inline-block p-3 bg-white">.bg-white</span>
+<span class="d-inline-block p-3 bg-gray-dark text-white">.bg-gray-dark</span>
+<span class="d-inline-block p-3 bg-blue">.bg-blue</span>
+<span class="d-inline-block p-3 bg-blue-light">.bg-blue-light</span>
+<span class="d-inline-block p-3 bg-gray">.bg-gray</span>
+<span class="d-inline-block p-3 bg-gray-light">.bg-gray-light</span>
+<span class="d-inline-block p-3 bg-green">.bg-green</span>
+<span class="d-inline-block p-3 bg-red">.bg-red</span>
Change the color
of elements with a class.
<span class="text-blue">.text-blue</span>
+<span class="text-red">.text-red</span>
+<span class="text-gray-light">.text-gray-light</span>
+<span class="text-gray">.text-gray</span>
+<span class="text-gray-dark">.text-gray-dark</span>
+<span class="text-green">.text-green</span>
+<span class="text-orange">.text-orange</span>
+<span class="text-purple">.text-purple</span>
+<span class="text-white bg-gray-dark">.text-white</span>
+<span class="text-inherit">.text-inherit</span>
The default link color is blue, but there are a couple of other options to use for deemphasized links. On :hover
all links will turn blue.
Here is some example text. And a .link-blue
+Here is some example text. And a .link-gray
+Here is some example text. And a .link-gray-dark
<p>Here is some example text. <a class="link-blue" href="#">And a .link-blue</a></p>
+<p>Here is some example text. <a class="link-gray" href="#">And a .link-gray</a></p>
+<p>Here is some example text. <a class="link-gray-dark" href="#">And a .link-gray-dark</a></p>
Flex table is a module for creating dynamically resizable elements that always sit on the same horizontal line (e.g., they never break to a new line). Using table styles in our CSS means it’s cross browser friendly back to at least IE9.
+ +Additional margin
or padding
may be required to properly space content.
<div class="flex-table">
+ <div class="flex-table-item flex-table-item-primary">
+ <input class="input-block" type="text" placeholder="Long flexible input form">
+ </div>
+ <div class="flex-table-item">
+ <button class="btn" type="button">Button</button>
+ </div>
+</div>
You have the option to set margin sizes from 0-5
. You also have the optional direction using t,r,b,l,x,y
.
<div class="d-inline-block border p-2 mr-0">.mr-0</div>
+<div class="d-inline-block border p-2 mr-1">.mr-1</div>
+<div class="d-inline-block border p-2 mr-2">.mr-2</div>
+<div class="d-inline-block border p-2 mr-3">.mr-3</div>
+<div class="d-inline-block border p-2 mr-4">.mr-4</div>
+<div class="d-inline-block border p-2 mr-5">.mr-5</div>
+<div class="d-inline-block border p-2 mx-2">.mx-5</div>
+<div class="d-inline-block border p-2 my-2">.my-5</div>
+<div class="d-inline-block border p-2 m-2">.m-2</div>
You have the option to set padding sizes from 0-5
. You also have the optional direction using t,b,x,y
.
<div class="d-inline-block border pt-0">.pt-0</div>
+<div class="d-inline-block border pt-1">.pt-1</div>
+<div class="d-inline-block border pt-2">.pt-2</div>
+<div class="d-inline-block border pt-3">.pt-3</div>
+<div class="d-inline-block border pt-4">.pt-4</div>
+<div class="d-inline-block border pt-5">.pt-5</div>
+<div class="d-inline-block border p-3">.p-3</div>
+<div class="d-inline-block border px-3">.px-3</div>
+<div class="d-inline-block border py-3">.py-3</div>
We include classes for setting positioning as well as setting the top-0, right-0, bottom-0, left-0
to zero. Your options for positioning are position-static, position-absolute, position-relative, position-fixed
.
<div class="p-3 border position-relative">
+ .position-relative
+ <div class="border position-absolute right-0 top-0 p-1">.position-absolute.right-0.top-0</div>
+</div>
You can set your display with these utilities.
+ +<span class="border text-center d-block p-2">.d-block</span>
+<span class="border text-center d-inline p-2">.d-inline</span>
+<span class="border text-center d-inline-block p-2">.d-inline-block</span>
+<span class="border text-center d-none p-2">.d-none</span>
With these border utilities you can set common borders.
+ +<div class="border p-3 mb-3">.border</div>
+<div class="border-top p-3 mb-3">.border-top</div>
+<div class="border-right p-3 mb-3">.border-right</div>
+<div class="border-bottom p-3 mb-3">.border-bottom</div>
+<div class="border-left p-3 mb-3">.border-left</div>
Add these classes with .border
and you’ll have some common border colors.
<div class="border p-3 mb-3 border-blue">.border-blue</div>
+<div class="border p-3 mb-3 border-gray-light">.border-gray-light</div>
+<div class="border p-3 mb-3 border-gray-dark">.border-gray-dark</div>
To remove a border from one side you can use -0
postfix.
<div class="border border-0 p-3 mb-3">.border-0</div>
+<div class="border border-top-0 p-3 mb-3">.border-top-0</div>
+<div class="border border-right-0 p-3 mb-3">.border-right-0</div>
+<div class="border border-bottom-0 p-3 mb-3">.border-bottom-0</div>
+<div class="border border-left-0 p-3 mb-3">.border-left-0</div>
Primer has underdone a lot of changes in the past 18 months. We've been consolidating and updating the CSS to make more resuable and flexible styles, we turned Primer CSS into a monorepo and improved our build process, and we've been building a new documentation website that we'll make public in fall, 2017. In the meantime, you can still view the old documentation website, or you can find up-to-date documentation for styles within the README.md
or docs
folder of each Primer module.
Primer CSS includes 23 packages that are grouped into 3 core meta-packages for easy install. Each package and meta-package is independently versioned and distributed via npm, so it's easy to include all or part of Primer within your own project.
+ + +Contains all modules in primer-core, primer-product, and primer-marketing packages.
+Contains modules that are shared between GitHub product and marketing websites: primer-base, primer-box, primer-buttons, primer-forms, primer-layout, primer-navigation, primer-support, primer-table-object, primer-tooltips, primer-truncate, primer-utilities.
+Contains modules that are used on GitHub product websites: primer-alerts, primer-avatars, primer-blankslate, primer-labels, primer-markdown, primer-support.
+Contains modules that are used on GitHub marketing websites: primer-breadcrumb, primer-cards, primer-marketing-support, primer-marketing-type, primer-marketing-utilities, primer-page-headers, primer-page-sections, primer-support, primer-tables.
+