primer/css
1
1
Fork 0
mirror of https://github.com/primer/css.git synced 2024-12-01 04:21:12 +03:00
Code Issues Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/release-12.1.1' into fix-storybook

Browse Source
This commit is contained in:
Shawn Allen 2019-03-06 15:57:03 -08:00
commit 52464bcfed
84 changed files with 3054 additions and 3609 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
lib/add-bundle-meta.js
View File

@ -1,38 +0,0 @@
const {existsSync} = require('fs')
const {dirname, join, resolve} = require('path')
const cache = {}
module.exports = function addBundleMeta(options = {}) {
const {namespace = 'data', log = noop} = options
return (files, metal, done) => {
const root = metal.source()
for (const [path, file] of Object.entries(files)) {
const bundle = getBundleRelativeTo(path, root)
log(`[meta] ${path} bundle: "${bundle}"`)
file[namespace].bundle = bundle
}
done()
}
}
function getBundleRelativeTo(file, root) {
let dir = join(root, dirname(file))
if (dir in cache) {
return cache[dir]
}
while (dir !== root) {
const indexPath = join(dir, 'index.scss')
if (existsSync(indexPath)) {
return (cache[dir] = getPathName(indexPath.substr(root.length + 1)))
}
dir = resolve(dir, '..')
}
return false
}
function getPathName(path) {
return dirname(path).replace(/\//g, '-')
}
function noop() {}

16
lib/add-source.js
View File

@ -1,16 +0,0 @@
const each = require('./each')
module.exports = function addSource(options = {}) {
const {namespace = 'data'} = options
for (const key of ['branch', 'repository']) {
if (!options[key]) {
throw new Error(`addSource() plugin requires options.${key} (got ${JSON.stringify(options[key])})`)
}
}
const {branch, repository} = options
return each((file, source) => {
if (file[namespace]) {
file[namespace].source = `${repository}/tree/${branch}/modules/${source}`
}
})
}

11
lib/config.js
View File

@ -1,12 +1,9 @@
/* eslint-disable no-console */
const sync = require('./sync')
const {NODE_ENV, NOW_URL} = process.env
module.exports = (nextConfig = {}) => {
const {assetPrefix = NOW_URL || ''} = nextConfig
let configured = false
return Object.assign({}, nextConfig, {
assetPrefix,
pageExtensions: ['js', 'jsx', 'md', 'mdx'],
@ -26,13 +23,6 @@ module.exports = (nextConfig = {}) => {
)
}
const {dev} = options
// only attempt to sync locally and in CI
if (dev && !configured) {
sync({watch: !NODE_ENV})
}
config.module.rules.push({
test: /\.svg$/,
use: '@svgr/webpack'
@ -43,7 +33,6 @@ module.exports = (nextConfig = {}) => {
use: [options.defaultLoaders.babel, require.resolve('./mdx-loader')]
})
configured = true
if (typeof nextConfig.webpack === 'function') {
return nextConfig.webpack(config, options)
}

8
lib/each.js
View File

@ -1,8 +0,0 @@
module.exports = function each(fn) {
return (files, metal, done) => {
for (const path of Object.keys(files)) {
fn(files[path], path, metal)
}
done()
}
}

10
lib/filter-by.js
View File

@ -1,10 +0,0 @@
module.exports = function filterBy(fn) {
return (files, metal, done) => {
for (const [key, file] of Object.entries(files)) {
if (!fn(file, key, metal)) {
delete files[key]
}
}
done()
}
}

65
lib/ignore.js
View File

@ -1,65 +0,0 @@
const {join} = require('path')
const {existsSync, readFileSync, removeSync, writeFileSync} = require('fs')
module.exports = function gitIgnore(options = {}) {
const {header, log = noop} = options
if (!header) {
throw new Error(`getIgnore(): the "header" is required (got: ${JSON.stringify(header)})`)
}
const set = new Set()
return (files, metal, done) => {
const ignoreFile = join(metal.destination(), '.gitignore')
// first, get the list of previously ignored files and remove them (sync)
const ignored = getIgnored(ignoreFile, header, log)
for (const file of ignored) {
if (existsSync(file)) {
removeSync(file)
}
}
for (const file of Object.keys(files)) {
set.add(file)
}
setIgnored(ignoreFile, Array.from(set), header, log)
done()
}
}
function readLines(file, log = noop) {
let content
try {
content = readFileSync(file, 'utf8')
} catch (error) {
log(`ignore file ${file} does not exist!`)
return []
}
return content
.trim()
.split('\n')
.map(line => line.trim())
}
function getIgnored(file, header, log = noop) {
const lines = readLines(file)
const headerIndex = lines.indexOf(header)
if (headerIndex === -1) {
log(`ignore file ${file} does not contain the automatically generated header`)
return []
}
return lines.slice(headerIndex + 1).filter(line => line)
}
function setIgnored(file, files, header, log) {
const lines = readLines(file, log)
const headerIndex = lines.indexOf(header)
if (headerIndex === -1) {
lines.push(header)
} else {
lines.splice(headerIndex + 1)
}
lines.push(...files)
writeFileSync(file, `${lines.sort().join('\n')}\n`, 'utf8')
}
function noop() {}

31
lib/parse-doc-comments.js
View File

@ -1,31 +0,0 @@
const each = require('./each')
const START = /<!-- *%docs *\n/
const SPLIT = /\n *-->/
const END = /<!-- *%enddocs *-->/
module.exports = function parseDocComments({log = noop}) {
return each((file, path) => {
const str = String(file.contents)
let parts = str.split(START)
if (parts.length > 1) {
// metadata should either be in frontmatter _or_ %docs comment;
// it's too tricky to reconcile them here
if (str.indexOf('---') === 0) {
log('unable to parse doc comments from', path, '(existing frontmatter)')
return
}
// take the part between the start and end
const middle = parts[1].split(END)[0]
// split *that* on the split "marker"
parts = middle.split(SPLIT)
// the part before that is the "frontmatter"
// and everything after that is the actual docs
const [meta, docs] = parts
file.contents = Buffer.from(`---\n${meta}\n---\n${docs}`)
}
})
}
function noop() {}

22
lib/rename.js
View File

@ -1,22 +0,0 @@
module.exports = function rename(fn, options = {}) {
const {log = noop} = options
return (files, metal, done) => {
for (const [key, file] of Object.entries(files)) {
const dest = fn(file, key, files, metal)
if (dest === true) {
log(`[rename] keep: ${key}`)
} else if (dest && dest !== key) {
log(`[rename] ${key} -> ${dest}`)
file.path = dest
files[dest] = file
delete files[key]
} else if (dest === false) {
log(`[rename] delete ${key}`)
delete files[key]
}
}
done()
}
}
function noop() {}

74
lib/sync.js
View File

@ -1,74 +0,0 @@
const Metalsmith = require('metalsmith')
const filter = require('metalsmith-filter')
const frontmatter = require('metalsmith-matters')
const watch = require('metalsmith-watch')
const {repository} = require('../package.json')
const addBundleMeta = require('./add-bundle-meta')
const addSource = require('./add-source')
const filterBy = require('./filter-by')
const parseDocComments = require('./parse-doc-comments')
const rename = require('./rename')
const writeMeta = require('./write-meta')
const gitIgnore = require('./ignore')
module.exports = function sync(options = {}) {
// eslint-disable-next-line no-console
const {log = console.warn} = options
const metaOptions = options.meta || {namespace: 'data', log}
const ns = metaOptions.namespace
// this is what we'll resolve our Promise with later
let files
const metal = Metalsmith(process.cwd())
.source('src')
.destination('pages/css')
.clean(false)
.frontmatter(false)
// ignore anything containing "node_modules" in its path
.ignore(path => path.includes('node_modules'))
// only match files that look like docs
.use(filter(['**/*.md']))
// convert <!-- %docs -->...<!-- %enddocs --> blocks into frontmatter
.use(parseDocComments({log}))
// parse frontmatter into "data" key of each file
.use(frontmatter(metaOptions))
// only match files that have a "path" key in their frontmatter
.use(filterBy(file => file[ns].path))
// write the source frontmatter key to the relative source path
.use(
addSource({
branch: 'master',
repository,
log
})
)
// add the "bundle" metadata so that we can redirect to those pages
.use(addBundleMeta({namespace: ns}))
// rename files with their "path" frontmatter key
.use(rename(file => (file[ns] ? `${file[ns].path}.md` : true)), {log})
.use((_files, metal, done) => {
files = _files
done()
})
// write frontmatter back out to the file
.use(writeMeta(metaOptions))
// keep .gitignore up-to-date with the list of generated files
.use(
gitIgnore({
header: '# DO NOT EDIT: automatically generated by ignore.js'
})
)
if (options.watch) {
metal.use(watch(typeof options.watch === 'object' ? options.watch : {}))
}
return new Promise((resolve, reject) => {
metal.build(error => {
error ? reject(error) : resolve(files)
})
})
}

11
lib/write-meta.js
View File

@ -1,11 +0,0 @@
const matter = require('gray-matter')
const each = require('./each')
module.exports = function writeMeta({namespace = 'data'}) {
return each(file => {
const data = file[namespace]
if (data) {
file.contents = matter.stringify(String(file.contents), data)
}
})
}

8
package.json
View File

@ -1,6 +1,6 @@
{
"name": "@primer/css",
"version": "12.1.0",
"version": "12.1.1",
"description": "Primer is the CSS framework that powers GitHub's front-end design. primer 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.",
"homepage": "https://primer.style/css",
"author": "GitHub, Inc.",
@ -39,12 +39,10 @@
"dev": "next dev",
"start-storybook": "start-storybook -p 8001",
"build-storybook": "build-storybook -o .storybuild",
"sync": "script/sync",
"test": "npm-run-all -s test-urls test-migrate",
"test-all-modules": "ava --verbose tests/test-*.js",
"test-urls": "npm run sync && node docs-test/urls.js",
"test-migrate": "script/test-migrate",
"watch": "script/sync --watch"
"test-urls": "node docs-test/urls.js",
"test-migrate": "script/test-migrate"
},
"devDependencies": {
"@githubprimer/octicons-react": "^8.1.3",

42
pages/css/.gitignore vendored
View File

@ -1,42 +0,0 @@
# DO NOT EDIT: automatically generated by ignore.js
components/alerts.md
components/avatars.md
components/blankslate.md
components/box.md
components/branch-name.md
components/breadcrumb.md
components/buttons.md
components/forms.md
components/labels.md
components/markdown.md
components/marketing-buttons.md
components/navigation.md
components/pagination.md
components/popover.md
components/progress.md
components/subhead.md
components/tooltips.md
components/truncate.md
objects/grid.md
objects/layout.md
objects/table-object.md
support/breakpoints.md
support/index.md
support/marketing-variables.md
support/spacing.md
support/typography.md
utilities/animations.md
utilities/borders.md
utilities/box-shadow.md
utilities/details.md
utilities/flexbox.md
utilities/layout.md
utilities/margin.md
utilities/marketing-borders.md
utilities/marketing-filters.md
utilities/marketing-layout.md
utilities/marketing-margin.md
utilities/marketing-padding.md
utilities/marketing-type.md
utilities/padding.md
utilities/typography.md

107
pages/css/components/alerts.md Normal file
View File

@ -0,0 +1,107 @@
---
title: Alerts
path: components/alerts
status: Stable
source: 'https://github.com/primer/css/tree/master/src/alerts'
bundle: alerts
---
Flash messages, or alerts, inform users of successful or pending actions. Use them sparingly. Don't show more than one at a time.
## Default
Flash messages start off looking decently neutral—they're just light blue rounded rectangles.
```html
<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.
```html
<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.*
```html
<div class="flash-messages">
<div class="flash">
Flash message goes here.
</div>
</div>
```
## Variations
Add `.flash-warn`, `.flash-error`, or `.flash-success` to the flash message to make it yellow, red, or green, respectively.
```html
<div class="flash flash-warn">
Flash message goes here.
</div>
```
```html
<div class="flash flash-error">
Flash message goes here.
</div>
```
```html
<div class="flash flash-success">
Flash message goes here.
</div>
```
## With icon
Add an icon to the left of the flash message to give it some funky fresh attention.
```erb
<div class="flash">
<%= octicon "alert" %>
Flash message with an icon goes here.
</div>
```
## With dismiss
Add a JavaScript enabled (via Crema) dismiss (close) icon on the right of any flash message.
```erb
<div class="flash">
<button class="flash-close js-flash-close" type="button"><%= octicon "x", :"aria-label" => "Close" %></button>
Dismissable flash message goes here.
</div>
```
## With action button
A flash message with an action button.
```html
<div class="flash">
<button type="submit" class="btn btn-sm primary flash-action">Complete action</button>
Flash message with action here.
</div>
```
## Full width flash
A flash message that is full width and removes border and border radius.
```html
<div class="flash flash-full">
<div class="container">
Full width flash message.
</div>
</div>
```

157
pages/css/components/avatars.md Normal file
View File

@ -0,0 +1,157 @@
---
title: Avatars
path: components/avatars
status: Stable
source: 'https://github.com/primer/css/tree/master/src/avatars'
bundle: avatars
---
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.
{:toc}
## Basic example
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.
```html
<img class="avatar" alt="jonrohan" src="https://github.com/jonrohan.png?v=3&s=144" width="72" height="72">
```
### Small avatars
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.
```html
<img class="avatar avatar-small" alt="jonrohan" src="https://github.com/jonrohan.png?v=3&s=64" width="32" height="32">
```
### Parent-child avatars
When you need a larger parent avatar, and a smaller child one, overlaid slightly, use the parent-child classes.
```html
<div class="avatar-parent-child float-left">
<img class="avatar" alt="jonrohan" src="https://github.com/jonrohan.png?v=3&s=96" width="48" height="48">
<img class="avatar avatar-child" alt="josh" src="https://github.com/josh.png?v=3&s=40" width="20" height="20">
</div>
```
### Avatar stack
Stacked avatars can be used to show multiple collaborators or participants when there is limited space available. When you hover over the stack, the avatars will reveal themselves.
```html
<div class="AvatarStack AvatarStack--three-plus">
<div class="AvatarStack-body tooltipped tooltipped-se tooltipped-align-left-1" aria-label="octocat, octocat, and octocat">
<img class="avatar" height="20" alt="@octocat" src="https://user-images.githubusercontent.com/334891/29999089-2837c968-9009-11e7-92c1-6a7540a594d5.png" width="20">
<img class="avatar" height="20" alt="@octocat" src="https://user-images.githubusercontent.com/334891/29999089-2837c968-9009-11e7-92c1-6a7540a594d5.png" width="20">
<img class="avatar" height="20" alt="@octocat" src="https://user-images.githubusercontent.com/334891/29999089-2837c968-9009-11e7-92c1-6a7540a594d5.png" width="20">
</div>
</div>
```
Based on the number of avatars in the stack, add these modifier classes:
- `AvatarStack--two` for 2 avatars.
- `AvatarStack--three-plus` for 3 or more avatars.
If you have more than three avatars, add a div with the classes `avatar avatar-more` as the third avatar in the stack, as such:
```html
<div class="AvatarStack AvatarStack--three-plus">
<div class="AvatarStack-body tooltipped tooltipped-se tooltipped-align-left-1" aria-label="octocat, octocat, octocat, octocat, and octocat">
<img class="avatar" height="20" alt="@octocat" src="https://user-images.githubusercontent.com/334891/29999089-2837c968-9009-11e7-92c1-6a7540a594d5.png" width="20">
<img class="avatar" height="20" alt="@octocat" src="https://user-images.githubusercontent.com/334891/29999089-2837c968-9009-11e7-92c1-6a7540a594d5.png" width="20">
<div class="avatar avatar-more"></div>
<img class="avatar" height="20" alt="@octocat" src="https://user-images.githubusercontent.com/334891/29999089-2837c968-9009-11e7-92c1-6a7540a594d5.png" width="20">
<img class="avatar" height="20" alt="@octocat" src="https://user-images.githubusercontent.com/334891/29999089-2837c968-9009-11e7-92c1-6a7540a594d5.png" width="20">
<img class="avatar" height="20" alt="@octocat" src="https://user-images.githubusercontent.com/334891/29999089-2837c968-9009-11e7-92c1-6a7540a594d5.png" width="20">
</div>
</div>
```
You can also link individual avatars. To do this shift the `avatar` class over to the anchor:
```html
<div class="AvatarStack AvatarStack--two">
<div class="AvatarStack-body tooltipped tooltipped-se tooltipped-align-left-1" aria-label="octocat and octocat">
<a href="#" class="avatar">
<img height="20" alt="@octocat" src="https://user-images.githubusercontent.com/334891/29999089-2837c968-9009-11e7-92c1-6a7540a594d5.png" width="20">
</a>
<a href="#" class="avatar">
<img height="20" alt="@octocat" src="https://user-images.githubusercontent.com/334891/29999089-2837c968-9009-11e7-92c1-6a7540a594d5.png" width="20">
</a>
</div>
</div>
```
Use `AvatarStack--right` to right-align the avatar stack. Remember to switch the alignment of tooltips when making this change.
```html
<div class="AvatarStack AvatarStack--three-plus AvatarStack--right">
<div class="AvatarStack-body tooltipped tooltipped-sw tooltipped-align-right-1" aria-label="octocat, octocat, and octocat">
<img class="avatar" height="20" alt="@octocat" src="https://user-images.githubusercontent.com/334891/29999089-2837c968-9009-11e7-92c1-6a7540a594d5.png" width="20">
<img class="avatar" height="20" alt="@octocat" src="https://user-images.githubusercontent.com/334891/29999089-2837c968-9009-11e7-92c1-6a7540a594d5.png" width="20">
<img class="avatar" height="20" alt="@octocat" src="https://user-images.githubusercontent.com/334891/29999089-2837c968-9009-11e7-92c1-6a7540a594d5.png" width="20">
</div>
</div>
```
## Circle Badge
`.CircleBadge` allows for the display of badge-like icons or logos. They are used mostly with Octicons or partner integration icons.
`.CircleBadge` should have an `aria-label`, `title` (for a link), or an `alt` (for child `img` elements) attribute specified if there is no text-based alternative to describe it. If there is a text-based alternative or the icon has no semantic value, `aria-hidden="true"` or an empty `alt` attribute may be used.
### Small
```erb
<a class="CircleBadge CircleBadge--small float-left mr-2" href="#small" title="Travis CI">
<img src="https://github.com/travis-ci.png" class="CircleBadge-icon" alt="">
</a>
<a class="CircleBadge CircleBadge--small bg-yellow" title="Zap this!" href="#small">
<%= octicon "zap", :class => "CircleBadge-icon text-white" %>
</a>
```
### Medium
```html
<div class="CircleBadge CircleBadge--medium bg-gray-dark">
<img src="https://github.com/travis-ci.png" alt="Travis CI" class="CircleBadge-icon">
</div>
```
### Large
```html
<div class="CircleBadge CircleBadge--large">
<img src="https://github.com/travis-ci.png" alt="Travis CI" class="CircleBadge-icon">
</div>
```
### Dashed connection
For specific cases where two badges or more need to be shown as related or connected (such as integrations or specific product workflows), a `DashedConnection` class was created. Use utility classes to ensure badges are spaced correctly.
```erb
<div class="DashedConnection">
<ul class="d-flex list-style-none flex-justify-between" aria-label="A sample GitHub workflow">
<li class="CircleBadge CircleBadge--small" aria-label="GitHub">
<%= octicon "mark-github", :class => "width-full height-full" %>
</li>
<li class="CircleBadge CircleBadge--small" aria-label="Slack">
<img src="https://github.com/slackhq.png" alt="" class="CircleBadge-icon">
</li>
<li class="CircleBadge CircleBadge--small" aria-label="Travis CI">
<img src="https://github.com/travis-ci.png" alt="" class="CircleBadge-icon">
</li>
</ul>
</div>
```

94
pages/css/components/blankslate.md Normal file
View File

@ -0,0 +1,94 @@
---
title: Blankslate
path: components/blankslate
status: Stable
source: 'https://github.com/primer/css/tree/master/src/blankslate'
bundle: blankslate
---
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.
#### Basic example
Wrap some content in the outer `.blankslate` wrapper to give it the blankslate appearance.
```html
<div class="blankslate">
<h3>This is a blank slate</h3>
<p>Use it to provide information when no dynamic content exists.</p>
</div>
```
#### With Octicons
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.
```erb
<div class="blankslate">
<%= octicon "git-commit", :height => 32, :class => "blankslate-icon" %>
<%= octicon "tag", :height => 32, :class => "blankslate-icon" %>
<%= octicon "git-branch", :height => 32, :class => "blankslate-icon" %>
<h3>This is a blank slate</h3>
<p>Use it to provide information when no dynamic content exists.</p>
</div>
```
#### Variations
Add an additional optional class to the `.blankslate` to change its appearance.
##### Narrow
Narrows the blankslate container to not occupy the entire available width.
```html
<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>
```
##### Capped
Removes the `border-radius` on the top corners.
```html
<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>
```
##### Spacious
Significantly increases the vertical padding.
```html
<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>
```
##### Large
Increases the size of the text in the blankslate
```html
<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>
```
##### No background
Removes the `background-color` and `border`.
```html
<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>
```

553
pages/css/components/box.md Normal file
View File

@ -0,0 +1,553 @@
---
title: Box
path: components/box
status_issue: 'https://github.com/github/design-systems/issues/198'
status: Stable
source: 'https://github.com/primer/css/tree/master/src/box'
bundle: box
---
The `.Box` component can be used for something as simple as a rounded corner box, or more complex lists and forms. It includes optional modifiers for padding density and color themes.
{:toc}
## Box
A `.Box` is a container with a a white background, a light gray border, and rounded corners. By default there are no additional styles such as padding, these can be added as needed with utility classes. Other styles and layouts can be achieved with box elements and modifiers shown in the documentation below.
```html
<div class="Box">
This is a box.
</div>
```
## Box elements
Box elements include `Box-header`, `Box-body`, and `Box-footer`. These elements include borders and consistent padding. Optionally, you can include use `Box-title` which applies a bold font-weight the heading.
```html
<div class="Box">
<div class="Box-header">
<h3 class="Box-title">
Box title
</h3>
</div>
<div class="Box-body">
Box body
</div>
<div class="Box-footer">
Box footer
</div>
</div>
```
### Box row
Use `Box-row` to add rows with borders and maintain the same padding. Box rows have a lighter border to give contrast between the header and footer.
**Note:** Box rows have some reliance on markup structure in order to target the first and last rows, therefore using an unordered list is recommended. See [box row markup structure](#box-row-markup-structure) for more information.
```html
<div class="Box">
<ul>
<li class="Box-row">
Box row one
</li>
<li class="Box-row">
Box row two
</li>
<li class="Box-row">
Box row three
</li>
<li class="Box-row">
Box row four
</li>
</ul>
</div>
```
Rows can be used with or without `Box-header`, `Box-footer`, or `Box-body`.
```html
<div class="Box">
<div class="Box-header">
Box header
</div>
<div class="Box-body">
<strong>Box body</strong>
</div>
<ul>
<li class="Box-row">
Box row one
</li>
<li class="Box-row">
Box row two
</li>
<li class="Box-row">
Box row three
</li>
<li class="Box-row">
Box row four
</li>
</ul>
<div class="Box-footer">
Box footer
</div>
</div>
```
### Box row markup structure
Box rows have some reliance on markup structure in order to target the first and last rows. Box rows are given a top border that is lighter in color than other box elements so the first row is targeted to apply a darker border color. An inner border-radius is applied to the first and last rows that that row corners don't poke outside the `Box`, this can be particularly noticeable when using a highlight on box rows.
Using an unordered list is recommended in order to target the first and last rows, however, if you need to use a `<div>` for your rows, you may want to place your rows inside a parent `<div>` so that the first and last rows are styled appropriately.
```html
<div class="Box">
<div class="Box-header">
Box header
</div>
<!-- This wrapping div ensures the first and last rows can be targeted for styling. -->
<div>
<div class="Box-row">Box row using a div</div>
<div class="Box-row">Box row using a div</div>
</div>
</div>
```
## Box padding density
You can changed the padding density of the box component.
Use `Box--condensed` to apply a more condensed line-height and reduce the padding on the Y axis.
```html
<div class="Box Box--condensed">
<div class="Box-header">
<h3 class="Box-title">
Box title
</h3>
</div>
<div class="Box-body">
Box body
</div>
<ul>
<li class="Box-row">
Box row one
</li>
<li class="Box-row">
Box row two
</li>
</ul>
<div class="Box-footer">
Box footer
</div>
</div>
```
Use `Box--spacious` to increase padding and increase the title font size.
You may want to increase the overall font size to work with the larger padding, in this example the default body font size is increased to 16px using the `f4` typography utility.
```html
<div class="Box Box--spacious f4">
<div class="Box-header">
<h3 class="Box-title">
Box title
</h3>
</div>
<div class="Box-body">
Box body
</div>
<ul>
<li class="Box-row">
Box row one
</li>
<li class="Box-row">
Box row two
</li>
</ul>
<div class="Box-footer">
Box footer
</div>
</div>
```
## Blue box theme
Use `Box--blue` to style the box borders and box header in blue.
```html
<div class="Box Box--blue">
<div class="Box-header">
Box header
</div>
<ul>
<li class="Box-row">
Box row one
</li>
<li class="Box-row">
Box row two
</li>
</ul>
<div class="Box-footer">
Box footer
</div>
</div>
```
## Blue box header theme
Use `Box-header--blue` to add to change the header border and background to blue.
```html
<div class="Box">
<div class="Box-header Box-header--blue">
<h3 class="Box-title">Box with blue header</h3>
</div>
<div class="Box-body">
Box body
</div>
</div>
```
## Box danger theme
Use `Box--danger` to apply a red border to the outside of the box. This theme is helpful for communicating destructive actions.
**Note:** `Box-danger` only works with either `Box-row`'s or `Box-body`.
```html
<div class="Box Box--danger">
<div class="Box-row">
Row one
</div>
<div class="Box-row">
Row two
</div>
</div>
```
`Box-danger` is often paired with a red heading. See the [subhead](./subhead) docs for more information.
```html
<div class="Subhead border-bottom-0">
<h2 class="Subhead-heading Subhead-heading--danger">Danger zone</h2>
</div>
<div class="Box Box--danger">
<div class="Box-body">
Box body
</div>
</div>
```
## Row themes
You can change the background color for individual rows, or change the color on hover or navigation focus.
```html
<div class="Box">
<div class="Box-row Box-row--gray">
.Box-row--gray
</div>
<div class="Box-row Box-row--hover-gray">
.Box-row--hover-gray
</div>
<div class="Box-row Box-row--yellow">
.Box-row--yellow
</div>
<div class="Box-row Box-row--hover-blue">
.Box-row--hover-blue
</div>
<div class="Box-row Box-row--blue">
.Box-row--blue
</div>
</div>
```
Use `Box-row--focus-gray` or `Box-row--focus-blue` when using along-side `navigation-focus` if you want to highlight rows when using keyboard commands.
```html
<div class="Box">
<div class="Box-row Box-row--focus-gray navigation-focus">
.Box-row--focus-gray and .navigation-focus
</div>
<div class="Box-row Box-row--focus-gray">
.Box-row--focus-gray
</div>
<div class="Box-row Box-row--focus-blue navigation-focus">
.Box-row--focus-blue and .navigation-focus
</div>
<div class="Box-row Box-row--focus-blue">
.Box-row--focus-blue
</div>
</div>
```
### Box row unread
Use `.Box-row-unread` to apply a blue vertical line highlight for indicating a row contains unread items.
```html
<div class="Box">
<div class="Box-row">
Box row
</div>
<div class="Box-row Box-row--unread">
Box row unread
</div>
<div class="Box-row">
Box row
</div>
</div>
```
### Box row link
Use .`Box-row-link` when you want a link to appear dark gray and blue on hover on desktop, and remain a blue link on mobile. This is useful to indicate links on mobile without having hover styles.
```html
<div class="Box">
<div class="Box-row">
<a class="Box-row-link" href="#box-row-link">Box row link</a>
</div>
</div>
```
## Dashed border
Use the `border-dashed` utility to apply a dashed border to a box.
```html
<div class="Box border-dashed p-2">
A box with a dashed border
</div>
```
## Boxes with flash alerts
Use `flash-full` for flash alert inside a box to remove the rounded corners. Place the flash alert above the `Box-body` and underneath the `Box-header`.
Flash alerts come in three different colors and can be used with icons and buttons, see the [alert documentation](./alerts) for more information.
```erb
<div class="Box">
<div class="Box-header">
Box header
</div>
<div class="flash flash-full">
<button class="flash-close js-flash-close"><%= octicon "x" %></button>
Flash message with close button.
</div>
<div class="flash flash-full flash-success">
<%= octicon("check") %> Flash success with an icon.
</div>
<div class="flash flash-full flash-warn">
<%= octicon("alert") %> Flash warning with an icon.
</div>
<div class="flash flash-full flash-error">
Flash error inside a Box.
</div>
<div class="Box-body">
Box body
</div>
</div>
```
## Boxes with icons
Use `Box-btn-octicon` with `btn-octicon` when you want the icon to maintain the same padding as other box elements. This selector offsets margin to ensure it lines up on the left and right sides of the box so you may need to add padding neighboring elements.
```erb
<div class="Box">
<div class="Box-body">
<span class="pr-2">Box body</span>
<button href="#" class="Box-btn-octicon btn-octicon"><%= octicon "pencil" %></button>
</div>
</div>
```
It's common to want to float icons to the far left or right and stop the `Box-title`from wrapping underneath. To do this you'll need to create a media object with utilities. Add `clearfix` to the surrounding div (this could be the header, body, or rows), add `overflow-hidden` to the title (or other text element), and float the icons as desired.
```erb
<div class="Box">
<div class="Box-header clearfix">
<button href="#" class="Box-btn-octicon btn-octicon float-right"><%= octicon "x" %></button>
<h3 class="Box-title overflow-hidden pr-3">A very long title that wraps onto multiple lines without overlapping or wrapping underneath the icon to it's right</h3>
</div>
<div class="Box-body">
Box body
</div>
</div>
```
```erb
<div class="Box">
<div class="Box-row clearfix">
<button href="#" class="Box-btn-octicon btn-octicon float-left"><%= octicon "check" %></button>
<p class="overflow-hidden pl-3">A very long paragraph that wraps onto multiple lines without overlapping or wrapping underneath the icon to it's left</p>
</div>
</div>
```
## Box headers with counters
Use a counter with a background that works against the contrast of the box header. The default counter colors do not stand out well against the header background so we suggest using one of the following styles:
Use `Counter--gray` for a counter with a gray background and dark gray text.
```html
<div class="Box">
<div class="Box-header">
<h3 class="Box-title">
Box title
<span class="Counter Counter--gray">12</span>
</h3>
</div>
<div class="Box-body">
Box body
</div>
</div>
```
Use `Counter--gray-dark` for a counter with a dark gray background and white text.
```html
<div class="Box">
<div class="Box-header">
<h3 class="Box-title">
Box title
<span class="Counter Counter--gray-dark">12</span>
</h3>
</div>
<div class="Box-body">
Box body
</div>
</div>
```
## Form elements and buttons in boxes
To achieve different layouts when adding buttons or form elements to boxes we suggest you use utilities to achieve the layout you want. Here's some common examples:
Use [flexbox utilities](/css/utilities/flexbox) to center align items, and avoid using floats by using `flex-auto` to have the text fill the remaining space so that the button rests on the far right.
```html
<div class="Box Box--condensed">
<div class="Box-header d-flex flex-items-center">
<h3 class="Box-title overflow-hidden flex-auto">
Box title
</h3>
<button class="btn btn-primary btn-sm">
Button
</button>
</div>
<div class="Box-body">
Box body
</div>
</div>
```
A similar approach can be used for buttons with multiple lines of text within a row.
```html
<div class="Box">
<div class="Box-row d-flex flex-items-center">
<div class="flex-auto">
<strong>Row title</strong>
<div class="text-small text-gray-light">
Description
</div>
</div>
<button type="button" class="btn btn-primary" name="button">View</button>
</div>
<div class="Box-row d-flex flex-items-center">
<div class="flex-auto">
<strong>Row title</strong>
<div class="text-small text-gray-light">
Description
</div>
</div>
<button type="button" class="btn btn-primary" name="button">View</button>
</div>
<div class="Box-row d-flex flex-items-center">
<div class="flex-auto">
<strong>Row title</strong>
<div class="text-small text-gray-light">
Description
</div>
</div>
<button type="button" class="btn btn-primary" name="button">View</button>
</div>
</div>
```
Using flexbox along with form, button, and link styles, you can create more complex box headers for things like bulk actions and sorting.
```html
<div class="Box">
<div class="Box-header d-flex flex-items-center">
<form class="flex-auto">
<label>
<input class="mr-1" type="checkbox">
Check it
</label>
</form>
<button class="btn-link select-menu-button muted-link">
Select menu
</button>
</div>
<div class="Box-body">
Box body
</div>
</div>
```
You can put forms in boxes. Often form submission buttons are aligned to the bottom right of the form which you can do with `text-right` instead of using floats.
```html
<div class="Box">
<div class="Box-header">
<h3 class="Box-title">
Example form title
</h3>
</div>
<form>
<div class="Box-body">
<dl class="form-group">
<dt><label>Example label</label></dt>
<dd><input class="form-control" type="text"></dd>
</dl>
<div class="form-checkbox">
<label>
<input type="checkbox" checked="checked">
Yes please
</label>
</div>
</div>
<div class="Box-footer text-right">
<button class="btn btn-secondary mr-1">
Cancel
</button>
<button class="btn btn-primary">
Submit
</button>
</div>
</form>
</div>
```
When a box is all by itself centered on a page you can use [column widths](/css/objects/grid) to control the width of the box. If needed, break the mold a little and use [typography utilities](/css/utilities/typography) instead of the built in box title styles.
```html
<div class="Box Box--spacious col-6 mx-auto text-center">
<form>
<div class="Box-body">
<h3 class="f1-light">
Example form
</h3>
<dl class="form-group mb-4">
<dt><label>Example label</label></dt>
<dd><input class="form-control" type="text"></dd>
</dl>
<button class="btn btn-primary btn-block">
Submit
</button>
</div>
</form>
</div>
```
Box patterns can also be made with, and modified with [border utilities](/css/utilities/borders).

28
pages/css/components/branch-name.md Normal file
View File

@ -0,0 +1,28 @@
---
title: Branch name
path: components/branch-name
status: Stable
source: 'https://github.com/primer/css/tree/master/src/branch-name'
bundle: branch-name
---
Branch names can be a link name or not:
```html title="Branch name"
<span class="branch-name">a_new_feature_branch</span>
```
```html title="Branch name with link"
<a href="#url" class="branch-name">a_new_feature_branch</a>
```
You may also include an octicon before the branch name text:
```erb title="Branch name with icon"
<span class="branch-name">
<%= octicon("git-branch", width:16, height:16) %>
a_new_feature_branch
</span>
```

27
pages/css/components/breadcrumb.md Normal file
View File

@ -0,0 +1,27 @@
---
title: Breadcrumbs
path: components/breadcrumb
status: Stable
source: 'https://github.com/primer/css/tree/master/src/breadcrumb'
bundle: breadcrumb
---
Breadcrumbs are used to show taxonomical context on pages that are many levels deep in a site’s hierarchy. Breadcrumbs show and link to parent, grandparent, and sometimes great-grandparent pages. Breadcrumbs are most appropriate on pages that:
- Are many levels deep on a site
- Do not have a section-level navigation
- May need the ability to quickly go back to the previous (parent) page
#### Usage
```html title="Breadcrumb"
<nav aria-label="Breadcrumb">
<ol>
<li class="breadcrumb-item text-small"><a href="https://github.com/business">Business</a></li>
<li class="breadcrumb-item text-small"><a href="https://github.com/business/customers">Customers</a></li>
<li class="breadcrumb-item breadcrumb-item-selected text-small text-gray" aria-current="page">MailChimp</li>
</ol>
</nav>
```

233
pages/css/components/buttons.md Normal file
View File

@ -0,0 +1,233 @@
---
title: Buttons
path: components/buttons
status: Stable
source: 'https://github.com/primer/css/tree/master/src/buttons'
bundle: buttons
---
Buttons are used for **actions**, like in forms, while textual hyperlinks are used for **destinations**, or moving from one page to another.
{:toc}
## Default button
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**.
```html
<button class="btn" type="button">Button button</button>
<a class="btn" href="#url" role="button">Link button</a>
```
You can find them in two sizes: the default `.btn` and the smaller `.btn-sm`.
```html
<button class="btn" type="button">Button</button>
<button class="btn btn-sm" type="button">Small button</button>
```
## Primary 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`.
```html
<button class="btn btn-primary" type="button">Primary button</button>
<button class="btn btn-sm btn-primary" type="button">Small primary button</button>
```
## Danger 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`.
```html
<button class="btn btn-danger" type="button">Danger button</button>
<button class="btn btn-sm btn-danger" type="button">Small danger button</button>
```
## Outline button
Outline buttons downplay an action as they appear like boxy links. Just add `.btn-outline` and go.
```html
<button class="btn btn-outline" type="button">Outline button</button>
<button class="btn btn-sm btn-outline" type="button">Outline button</button>
```
## Large button
Use `.btn-large` to increase the padding and border radius of a button. This is useful for prominent calls to action in hero sections.
[Type scale utilities](https://styleguide.github.com/primer/utilities/typography/#type-scale-utilities) can be used to alter the font-size if needed. Padding is applied in em's so that it scales proportionally with the font-size.
```html
<p>
<a class="btn btn-large btn-purple" href="#url" role="button">Large link button</a>
<button class="btn btn-large" type="button">Large button button</button>
</p>
```
Use `.btn-large` with a type scale utility to transform the text to a bigger size.
```html
<p class="f3">
<a class="btn btn-large btn-purple" href="#url" role="button">Large link button</a>
<button class="btn btn-large btn-outline-blue" type="button">Large button button</button>
</p>
```
## Disabled state
Disable `<button>` elements with the boolean `disabled` attribute and `<a>` elements with the `.disabled` class.
```html
<button class="btn" type="button" disabled>Disabled button</button>
<a class="btn disabled" href="#url" role="button">Disabled button</a>
```
Similar styles are applied to primary, danger, and outline buttons:
```html
<button class="btn btn-primary" type="button" disabled>Disabled button</button>
<a class="btn btn-primary disabled" href="#url" role="button">Disabled button</a>
```
```html
<button class="btn btn-danger" type="button" disabled>Disabled button</button>
<a class="btn btn-danger disabled" href="#url" role="button">Disabled button</a>
```
```html
<button class="btn btn-outline" type="button" disabled>Disabled button</button>
<a class="btn btn-outline disabled" href="#url" role="button">Disabled button</a>
```
## Block button
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.
```html
<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>
```
## Link button
Create a button that looks like a link with `.btn-link`. Rather than using an `<a>` to trigger JS, this style on a `<button>` should be used for better accessibility.
**The `.btn-link` class is not designed to be used with `.btn`; the overlapping styles are not compatible.**
```html
<p><button class="btn-link" type="button">Link button</button></p>
```
## Button with counts
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.**
```erb
<div class="clearfix">
<a class="btn btn-sm btn-with-count" href="#url" role="button">
<%= octicon "eye" %>
Watch
</a>
<a class="social-count" href="#url">6</a>
</div>
```
You can also use the [counter](./labels#counters) component within buttons:
```html
<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>
```
## Button groups
Have a hankering for a series of buttons that are attached to one another? Wrap them in a `.BtnGroup` and the buttons will be rounded and spaced automatically.
```html
<div class="BtnGroup mr-2">
<button class="btn BtnGroup-item" type="button">Button</button>
<button class="btn BtnGroup-item" type="button">Button</button>
<button class="btn BtnGroup-item" type="button">Button</button>
</div>
<div class="BtnGroup mr-2">
<button class="btn BtnGroup-item btn-outline" type="button">Button</button>
<button class="btn BtnGroup-item btn-outline" type="button">Button</button>
<button class="btn BtnGroup-item btn-outline" type="button">Button</button>
</div>
<div class="BtnGroup">
<button class="btn BtnGroup-item btn-sm" type="button">Button</button>
<button class="btn BtnGroup-item btn-sm" type="button">Button</button>
<button class="btn BtnGroup-item btn-sm" type="button">Button</button>
</div>
```
Add `.BtnGroup-parent` to parent elements, like `<form>`s or `<details>`s, within `.BtnGroup`s for proper spacing and rounded corners.
```html
<div class="BtnGroup">
<button class="btn BtnGroup-item" type="button">Button</button>
<form class="BtnGroup-parent">
<button class="btn BtnGroup-item" type="button">Button in a form</button>
</form>
<button class="btn BtnGroup-item" type="button">Button</button>
<button class="btn BtnGroup-item" type="button">Button</button>
</div>
```
## Hidden text button
Use `.hidden-text-expander` to indicate and toggle hidden text.
```html
<span class="hidden-text-expander">
<button type="button" class="ellipsis-expander" aria-expanded="false">&hellip;</button>
</span>
```
You can also make the expander appear inline by adding `.inline`.
## Using button styles with the details summary element
You can add `.btn` and `.btn-*` classes to any
[`<summary>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary)
element so that it gains the appearance of a button, and
selected/active styles when the parent
[`<details>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details)
element is open.
```html
<details>
<summary class="btn btn-block btn-primary">Toggle the content</summary>
<p class="mt-2">
This content will be toggled.
</p>
</details>
```

306
pages/css/components/forms.md Normal file
View File

@ -0,0 +1,306 @@
---
title: Forms
path: components/forms
status: Stable
source: 'https://github.com/primer/css/tree/master/src/forms'
bundle: forms
---
Style individual form controls and utilize common layouts.
{:toc}
Overview:
- We reset several elements' default styles for cross browser consistency and easier manipulation later. This includes `<fieldset>`s, WebKit validation bubbles, and most textual `<input>`s.
- Specific types of textual `<input>`s are styled automatically, but `.form-control` is available should you need it.
- Always declare a `type` on your `<button>`s.
- Form layouts rely on form groups.
#### Kitchen sink
All our inputs and buttons side-by-side for easy testing of sizing and alignment with one another.
```html
<p>
<button class="btn" type="button">Button</button>
<button class="btn select-menu-button" type="button" aria-expanded="false" aria-haspopup="true">
Select menu
</button>
<input class="form-control" type="text" placeholder="Standard input" aria-label="Repository description">
<input class="form-control input-monospace" type="text" placeholder="Monospace input" aria-label="SHA">
<select class="form-select" aria-label="Important decision">
<option>Select</option>
<option value="option 2">Option 2</option>
</select>
</p>
<p>
<button class="btn btn-sm" type="button">Small button</button>
<button class="btn btn-sm select-menu-button" type="button" aria-expanded="false" aria-haspopup="true">
Select menu
</button>
<input class="form-control input-sm" type="text" placeholder="Small input" aria-label="Repository description">
<select class="form-select select-sm" aria-label="Important decision">
<option>Select</option>
<option value="option 1">Option 1</option>
</select>
</p>
```
#### Example form
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.
```html
<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>
```
#### Form contrast
Textual form controls have a white background by default. You can change this to a light gray with `.input-contrast`.
```html
<form>
<input class="form-control" type="text" placeholder="Default input" aria-label="Default input">
<input class="form-control input-contrast" type="text" placeholder="Input with contrast" aria-label="Input with contrast">
</form>
```
#### Sizing
Make inputs smaller, larger, or full-width with an additional class.
##### Small
```html
<form>
<input class="form-control input-sm" type="text" placeholder="Small input" aria-label="Small input">
</form>
```
##### Large
```html
<form>
<input class="form-control input-lg" type="text" placeholder="Large input" aria-label="Large input">
</form>
```
##### Block
```html
<form>
<input class="form-control input-block" type="text" placeholder="Full-width input" aria-label="Full-width input">
</form>
```
##### Hide webkit's contact info autofill icon
Webkit sometimes gets confused and tries to add an icon/dropdown to autofill contact information on fields that may not be appropriate (such as input for number of users). Use this class to override the display of this icon.
```html
<form>
<input class="form-control input-hide-webkit-autofill" placeholder="Hide Webkit's contact autofill on this input" type="text" aria-label="Hide Webkit's contact autofill on this input">
</form>
```
#### Selects
Primer adds light `height` and `vertical-align` styles to `<select>`s for all browsers to render them consistently with textual inputs.
```html
<form>
<select class="form-select" aria-label="Preference">
<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>
```
##### Small
Use the `.select-sm` class to resize both default and custom `<select>`s to match the size of [our small buttons](./buttons#default-buttons).
```html
<select class="form-select select-sm" aria-label="Preference">
<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" aria-label="Preference">
<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 groups
```html
<form>
<dl class="form-group">
<dt><label for="example-text">Example Text</label></dt>
<dd><input class="form-control" type="text" value="Example Value" id="example-text"></dd>
</dl>
<dl class="form-group">
<dt><label for="example-select">Example Select</label></dt>
<dd>
<select class="form-select" id="example-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 for="example-textarea">Example Textarea</label></dt>
<dd>
<textarea class="form-control" id="example-textarea"></textarea>
</dd>
</dl>
</form>
```
#### Form group validation
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`.
```html
<form>
<dl class="form-group errored">
<dt><label for="example-text-errored">Example Text</label></dt>
<dd><input class="form-control" type="text" value="Example Value" id="example-text-errored" aria-describedby="form-error-text"></dd>
<dd class="error" id="form-error-text">This example input has an error.</dd>
</dl>
<br>
<dl class="form-group warn">
<dt><label for="example-text-warn">Example Text</label></dt>
<dd><input class="form-control" type="text" value="Example Value" id="example-text-warn" aria-describedby="form-warning-text"></dd>
<dd class="warning" id="form-warning-text">This example input has a warning.</dd>
</dl>
</form>
```
#### Checkboxes and radios
Utilities to spice up the alignment and styling of checkbox and radio controls.
```html
<form>
<div class="form-checkbox">
<label>
<input type="checkbox" checked="checked" aria-describedby="help-text-for-checkbox">
Available for hire
</label>
<p class="note" id="help-text-for-checkbox">
This will do insanely <strong>awesome</strong> and <strong>amazing</strong> things!
</p>
</div>
</form>
```
You may also add emphasis to the label:
```html
<form>
<div class="form-checkbox">
<label>
<input type="checkbox" checked="checked">
<em class="highlight">Available for hire</em>
</label>
</div>
</form>
```
##### Show / hide content based on a checkbox or radio button state
Content that is hidden by default should only be done so if it is non-essential for the context of the surrounding content. Be sure to use the `aria-live="polite"` attribute on the parent label for added content to be announced when displayed.
```html
<form>
<div class="form-checkbox">
<label>
<input type="radio" name="hireme">
Not available for hire
</label>
</div>
<div class="form-checkbox">
<label aria-live="polite">
<input type="radio" class="form-checkbox-details-trigger" name="hireme">
Available for hire
<span class="form-checkbox-details text-normal">
<span class="d-block mb-1">Available hours per week</span>
<input type="text" name="" class="form-control input-contrast" size="3">
<span class="text-small text-gray pl-2">hours per week</span>
</span>
</label>
</div>
</form>
```
#### Input group
Attached an input and button to one another.
```erb
<form>
<div class="input-group">
<input class="form-control" type="text" placeholder="Username" aria-label="Username">
<span class="input-group-button">
<button class="btn" type="button" aria-label="Copy to clipboard">
<%= octicon "clippy" %>
</button>
</span>
</div>
</form>
```
#### Form actions
Align buttons to the right—via `float: right` on the buttons—in forms with `.form-actions`. The floats are automatically cleared for you.
```html
<div class="form-actions">
<button type="submit" class="btn btn-primary">Save changes</button>
<button type="button" class="btn">Cancel</button>
</div>
```

142
pages/css/components/labels.md Normal file
View File

@ -0,0 +1,142 @@
---
title: Labels
path: components/labels
status_issue: 'https://github.com/github/design-systems/issues/332'
status: Stable
source: 'https://github.com/primer/css/tree/master/src/labels'
bundle: labels
---
Labels add metatdata or indicate status of items and navigational elements. Three different types of labels are available: [Labels](#default-label-styles) for adding metadata, [States](#states) for indicating status, and [Counters](#counters) for showing the count for a number of items.
{:toc}
## Labels
The base label component styles the text, adds padding and rounded corners, and an inset box shadow. Labels come in various themes which apply colors and different border styles.
GitHub also programmatically generates and applies a background color for labels on items such as issues and pull requests. Users are able to select any background color and the text color will adjust to work with light and dark background colors.
The base `Label` style does not apply a background color, here's an example using the `bg-blue` utility to apply a blue background:
```html title="Label"
<span title="Label: default label" class="Label bg-blue">default label</span>
```
**Note:** Be sure to include a title attribute on labels, it's helpful for people using screen-readers to differentiate a label from other text. I.e. without the title attribute, the following example would read as _"New select component design"_, rather than identifying `design` as a label.
```html title="Label without title"
<!-- Don't do this -->
<a href="#url">New select component</a><span class="Label bg-blue ml-1">design</span>
```
### Label themes
Labels come in a few different themes. Use a theme that helps communicate the content of the label, and ensure it's used consistently.
Use `Label--gray` to create a label with a light gray background and gray text. This label is neutral in color and can be used in contexts where all you need to communicate is metadata, or whe you want a label to feel less prominent compared with labels with stronger colors.
```html title="Label theme gray"
<span title="Label: gray label" class="Label Label--gray">gray label</span>
```
Use `Label--gray-darker` to create a label with a dark-gray background color. This label is also neutral in color, however, since it's background is darker it can stand out more compared to `Label--gray`.
```html title="Label theme dark gray"
<span title="Label: dark gray label" class="Label Label--gray-darker">dark gray label</span>
```
Use `Label--orange` to communicate "warning". The orange background color is very close to red, so avoid using next to labels with a red background color since most people will find it hard to tell the difference.
```html title="Label theme orange"
<span title="Label: orange label" class="Label Label--orange">orange label</span>
```
Use `Label--outline` to create a label with gray text, a gray border, and a transparent background. The outline reduces the contrast of this label in combination with filled labels. Use this in contexts where you need it to stand out less than other labels and communicate a neutral message.
```html title="Label outline"
<span title="Label: outline label" class="Label Label--outline">outlined label</span>
```
Use `Label--outline-green` in combination with `Label--outline` to communicate a positive message.
```html title="Label outline green"
<span title="Label: green outline label" class="Label Label--outline Label--outline-green">green outlined label</span>
```
## States
Use state labels to inform users of an items status. States are large labels with bolded text. The default state has a gray background.
```html title="State"
<span class="State">Default</span>
```
### State themes
States come in a few variations that apply different colors. Use the state that best communicates the status or function.
```erb title="State themes"
<span title="Status: open" class="State State--green"><%= octicon "git-pull-request" %> Open</span>
<span title="Status: closed" class="State State--red"><%= octicon "git-pull-request" %> Closed</span>
<span title="Status: merged" class="State State--purple"><%= octicon "git-merge" %> Merged</span>
```
**Note:** Similar to [labels](#labels), you should include the title attribute on states to differentiate them from other content.
### Small states
Use `State--small` for a state label with reduced padding a smaller font size. This is useful in denser areas of content.
```erb title="Small states"
<span title="Status: open" class="State State--green State--small"><%= octicon "issue-opened" %> Open</span>
<span title="Status: closed" class="State State--red State--small"><%= octicon "issue-closed" %> Closed</span>
```
## Counters
Use the `Counter` component to add a count to navigational elements and buttons. Counters come in 3 variations: the default `Counter` with a light gray background, `Counter--gray` with a dark-gray background and inverse white text, and `Counter--gray-light` with a light-gray background and dark gray text. When a counter is empty, it's visibility will be hidden.
```html title="Counter"
<span class="Counter">16</span>
<span class="Counter Counter--gray">32</span>
<span class="Counter Counter--gray-light">64</span>
```
Use the `Counter` in navigation to indicate the number of items without the user having to click through or count the items, such as open issues in a GitHub repo. See more options in [navigation](./navigation).
```html title="Counter in tabs"
<div class="tabnav">
<nav class="tabnav-tabs" aria-label="Foo bar">
<a href="#url" class="tabnav-tab selected" aria-current="page">Foo tab <span class="Counter">23</a>
<a href="#url" class="tabnav-tab">Bar tab</a>
</nav>
</div>
```
Counters can also be used in `Box` headers to indicate the number of items in a list. See more on the [box component](./box).
```html title="Counter in Box headers"
<div class="Box">
<div class="Box-header">
<h3 class="Box-title">
Box title
<span class="Counter Counter--gray">3</span>
</h3>
</div>
<ul>
<li class="Box-row">
Box row one
</li>
<li class="Box-row">
Box row two
</li>
<li class="Box-row">
Box row three
</li>
</ul>
</div>
```

174
pages/css/components/markdown.md Normal file
View File

@ -0,0 +1,174 @@
---
title: Markdown
path: components/markdown
status: Stable
source: 'https://github.com/primer/css/tree/master/src/markdown'
bundle: markdown
---
Text can be **bold**, _italic_, or ~~strikethrough~~. [Links](https://github.com) should be blue with no underlines (unless hovered over).
There should be whitespace between paragraphs. There should be whitespace between paragraphs. There should be whitespace between paragraphs. There should be whitespace between paragraphs.
There should be whitespace between paragraphs. There should be whitespace between paragraphs. There should be whitespace between paragraphs. There should be whitespace between paragraphs.
> There should be no margin above this first sentence.
>
> Blockquotes should be a lighter gray with a gray border along the left side.
>
> There should be no margin below this final sentence.
# Header 1
This is a normal paragraph following a header. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.
## Header 2
> This is a blockquote following a header. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.
### Header 3
```
This is a code block following a header.
```
#### Header 4
* This is an unordered list following a header.
* This is an unordered list following a header.
* This is an unordered list following a header.
##### Header 5
1. This is an ordered list following a header.
2. This is an ordered list following a header.
3. This is an ordered list following a header.
###### Header 6
| What | Follows |
|-----------|-----------------|
| A table | A header |
| A table | A header |
| A table | A header |
----------------
There's a horizontal rule above and below this.
----------------
Here is an unordered list:
* Salt-n-Pepa
* Bel Biv DeVoe
* Kid 'N Play
And an ordered list:
1. Michael Jackson
2. Michael Bolton
3. Michael Bublé
And an unordered task list:
- [x] Create a sample markdown document
- [x] Add task lists to it
- [ ] Take a vacation
And a "mixed" task list:
- [ ] Steal underpants
- ?
- [ ] Profit!
And a nested list:
* Jackson 5
* Michael
* Tito
* Jackie
* Marlon
* Jermaine
* TMNT
* Leonardo
* Michelangelo
* Donatello
* Raphael
Definition lists can be used with HTML syntax. Definition terms are bold and italic.
<dl>
<dt>Name</dt>
<dd>Godzilla</dd>
<dt>Born</dt>
<dd>1952</dd>
<dt>Birthplace</dt>
<dd>Japan</dd>
<dt>Color</dt>
<dd>Green</dd>
</dl>
----------------
Tables should have bold headings and alternating shaded rows.
| Artist | Album | Year |
|-------------------|-----------------|------|
| Michael Jackson | Thriller | 1982 |
| Prince | Purple Rain | 1984 |
| Beastie Boys | License to Ill | 1986 |
If a table is too wide, it should condense down and/or scroll horizontally.
| Artist | Album | Year | Label | Awards | Songs |
|-------------------|-----------------|------|-------------|----------|-----------|
| Michael Jackson | Thriller | 1982 | Epic Records | Grammy Award for Album of the Year, American Music Award for Favorite Pop/Rock Album, American Music Award for Favorite Soul/R&B Album, Brit Award for Best Selling Album, Grammy Award for Best Engineered Album, Non-Classical | Wanna Be Startin' Somethin', Baby Be Mine, The Girl Is Mine, Thriller, Beat It, Billie Jean, Human Nature, P.Y.T. (Pretty Young Thing), The Lady in My Life |
| Prince | Purple Rain | 1984 | Warner Brothers Records | Grammy Award for Best Score Soundtrack for Visual Media, American Music Award for Favorite Pop/Rock Album, American Music Award for Favorite Soul/R&B Album, Brit Award for Best Soundtrack/Cast Recording, Grammy Award for Best Rock Performance by a Duo or Group with Vocal | Let's Go Crazy, Take Me With U, The Beautiful Ones, Computer Blue, Darling Nikki, When Doves Cry, I Would Die 4 U, Baby I'm a Star, Purple Rain |
| Beastie Boys | License to Ill | 1986 | Mercury Records | noawardsbutthistablecelliswide | Rhymin & Stealin, The New Style, She's Crafty, Posse in Effect, Slow Ride, Girls, (You Gotta) Fight for Your Right, No Sleep Till Brooklyn, Paul Revere, Hold It Now, Hit It, Brass Monkey, Slow and Low, Time to Get Ill |
----------------
Code snippets like `var foo = "bar";` can be shown inline.
Also, `this should vertically align` ~~`with this`~~ ~~and this~~.
Code can also be shown in a block element.
```
var foo = "bar";
```
Code can also use syntax highlighting.
```javascript
var foo = "bar";
```
```
Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this.
```
```javascript
var foo = "The same thing is true for code with syntax highlighting. A single line of code should horizontally scroll if it is really long.";
```
Inline code inside table cells should still be distinguishable.
| Language | Code |
|-------------|--------------------|
| Javascript | `var foo = "bar";` |
| Ruby | `foo = "bar"` |
----------------
Small images should be shown at their actual size.
![](http://placekitten.com/g/300/200/)
Large images should always scale down and fit in the content container.
![](http://placekitten.com/g/1200/800/)
```
This is the final element on the page and there should be no margin below this.
```

39
pages/css/components/marketing-buttons.md Normal file
View File

@ -0,0 +1,39 @@
---
title: Marketing Buttons
path: components/marketing-buttons
status: New Release
source: 'https://github.com/primer/css/tree/master/src/marketing/buttons'
bundle: marketing-buttons
---
Marketing buttons come in different colors and sizes, and are also available in a blue outlined version.
## Colors and outlined
Marketing buttons can be solid blue, outlined blue, solid green, or transparent.
The solid blue and solid green buttons have more visual emphasis than the blue outlined button, therefore they should be used sparingly and only for call to actions that need emphasis.
```html
<button class="btn-mktg mr-2" type="button">Learn more</button>
<button class="btn-mktg btn-outline-mktg mr-2" type="button">Learn more</button>
<button class="btn-mktg btn-primary-mktg mr-2" type="button">Sign up</button>
<div class="bg-gray-dark">
<button class="btn-mktg btn-transparent m-2" type="button">Learn more</button>
</div>
```
## Sizes
Available in two sizes, marketing buttons have a default size and a large size.
```html
<button class="btn-mktg mr-2" type="button">Learn more</button>
<button class="btn-mktg btn-outline-mktg mr-2" type="button">Learn more</button>
<button class="btn-mktg btn-primary-mktg mr-2" type="button">Sign up</button>
<button class="btn-mktg btn-large-mktg mr-2" type="button">Learn more</button>
<button class="btn-mktg btn-outline-mktg btn-large-mktg mr-2" type="button">Learn more</button>
<button class="btn-mktg btn-primary-mktg btn-large-mktg mr-2" type="button">Sign up</button>
```

321
pages/css/components/navigation.md Normal file
View File

@ -0,0 +1,321 @@
---
title: Navigation
path: components/navigation
status: Stable
source: 'https://github.com/primer/css/tree/master/src/navigation'
bundle: navigation
---
Primer comes with several navigation components. Some were designed with singular purposes, while others were design to be more flexible and appear quite frequently.
{:toc}
## Menu
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`.
```html title="Menu"
<nav class="menu" aria-label="Person settings">
<a class="menu-item selected" href="#url" aria-current="page">Account</a>
<a class="menu-item" href="#url">Profile</a>
<a class="menu-item" href="#url">Emails</a>
<a class="menu-item" href="#url">Notifications</a>
</nav>
```
There are a few subcomponents and add-ons that work well with the menu, including avatars, counters, and Octicons.
```erb title="Menu with octicons, avatars and counters"
<nav class="menu" aria-label="Person settings">
<a class="menu-item selected" href="#url" aria-current="page">
<%= octicon "tools" %>
Account
</a>
<a class="menu-item" href="#url">
<%= octicon "person" %>
Profile
</a>
<a class="menu-item" href="#url">
<%= octicon "mail" %>
Emails
</a>
<a class="menu-item" href="#url">
<%= octicon "radio-tower" %>
<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.
```html title="Menu with heading"
<nav class="menu" aria-labelledby="menu-heading">
<span class="menu-heading" id="menu-heading">Menu heading</span>
<a class="menu-item selected" href="#url" aria-current="page">Account</a>
<a class="menu-item" href="#url">Profile</a>
<a class="menu-item" href="#url">Emails</a>
<a class="menu-item" href="#url">Notifications</a>
</nav>
```
## Underline nav
Use `.UnderlineNav` to style navigation with a minimal underlined selected state, typically used for navigation placed at the top of the page. This component comes with variations to accommodate icons, containers and other content.
```html title="UnderlineNav"
<nav class="UnderlineNav">
<div class="UnderlineNav-body">
<a href="#url" role="tab" title="Item 1" class="UnderlineNav-item selected">Item 1</a>
<a href="#url" role="tab" title="Item 2" class="UnderlineNav-item">Item 2</a>
<a href="#url" role="tab" title="Item 3" class="UnderlineNav-item">Item 3</a>
<a href="#url" role="tab" title="Item 4" class="UnderlineNav-item">Item 4</a>
</div>
</nav>
```
Use `.UnderlineNav-actions` to place another element, such as a button, to the opposite side of the navigation items.
```html title="UnderlineNav-actions"
<nav class="UnderlineNav" aria-label="Foo bar">
<div class="UnderlineNav-body">
<a href="#url" class="UnderlineNav-item selected">Item 1</a>
<a href="#url" class="UnderlineNav-item">Item 2</a>
<a href="#url" class="UnderlineNav-item">Item 3</a>
<a href="#url" class="UnderlineNav-item">Item 4</a>
</div>
<div class="UnderlineNav-actions">
<a class="btn">Button</a>
</div>
</nav>
```
Use `.UnderlineNav--right` to right align the navigation.
```html title="UnderlineNav--right"
<nav class="UnderlineNav UnderlineNav--right">
<div class="UnderlineNav-body">
<a href="#url" role="tab" title="Item 1" class="UnderlineNav-item selected">Item 1</a>
<a href="#url" role="tab" title="Item 2" class="UnderlineNav-item">Item 2</a>
<a href="#url" role="tab" title="Item 3" class="UnderlineNav-item">Item 3</a>
<a href="#url" role="tab" title="Item 4" class="UnderlineNav-item">Item 4</a>
</div>
</nav>
```
`.UnderlineNav--right` also works with when used with `.UnderlineNav-actions`.
```html title="UnderlineNav--right with actions"
<nav class="UnderlineNav UnderlineNav--right" aria-label="Foo bar">
<div class="UnderlineNav-actions">
<a class="btn">Button</a>
</div>
<div class="UnderlineNav-body">
<a href="#url" class="UnderlineNav-item selected">Item 1</a>
<a href="#url" class="UnderlineNav-item">Item 2</a>
<a href="#url" class="UnderlineNav-item">Item 3</a>
<a href="#url" class="UnderlineNav-item">Item 4</a>
</div>
</nav>
```
<!-- Update wording here -->
`.Counters` and `.octicons` can be used with navigation items. Use `.UnderlineNav-octicon` to add color and hover styles.
```erb title="UnderlineNav with Counter"
<nav class="UnderlineNav" aria-label="Foo bar">
<div class="UnderlineNav-body">
<a href="#url" class="UnderlineNav-item selected">
<%= octicon "tools", :class => "UnderlineNav-octicon" %>
Item 1
</a>
<a href="#url" class="UnderlineNav-item">
<%= octicon "tools", :class => "UnderlineNav-octicon" %>
Item 2
<span class="Counter">10</span>
</a>
<a href="#url" class="UnderlineNav-item">
<%= octicon "tools", :class => "UnderlineNav-octicon" %>
Item 3
</a>
<a href="#url" class="UnderlineNav-item">
<%= octicon "tools", :class => "UnderlineNav-octicon" %>
Item 4
</a>
</div>
</nav>
```
Use `.UnderlineNav--full` in combination with container styles and `.UnderlineNav-container` to make navigation fill the width of the container.
```html title="UnderlineNav--full"
<nav class="UnderlineNav UnderlineNav--full" aria-label="Foo bar">
<div class="container-lg UnderlineNav-container">
<div class="UnderlineNav-body">
<a href="#url" class="UnderlineNav-item selected">Item 1</a>
<a href="#url" class="UnderlineNav-item">Item 2
<span class="Counter">10</span>
</a>
<a href="#url" class="UnderlineNav-item">Item 3</a>
<a href="#url" class="UnderlineNav-item">Item 4</a>
</div>
<div class="UnderlineNav-actions">
<a class="btn">Button</a>
</div>
</div>
</nav>
```
## Tabnav
When you need to toggle between different views, consider using a tabnav. It'll give you a left-aligned horizontal row of... tabs!
```html title="tabnav"
<div class="tabnav">
<nav class="tabnav-tabs" aria-label="Foo bar">
<a href="#url" class="tabnav-tab selected" aria-current="page">Foo tab</a>
<a href="#url" class="tabnav-tab">Bar tab</a>
</nav>
</div>
```
Use `.float-right` to align additional elements in the `.tabnav`:
```html title="tabnav with buttons"
<div class="tabnav">
<a class="btn btn-sm float-right" href="#url" role="button">Button</a>
<nav class="tabnav-tabs" aria-label="Foo bar">
<a href="#url" class="tabnav-tab selected" aria-current="page">Foo Tab</a>
<a href="#url" class="tabnav-tab">Bar Tab</a>
</nav>
</div>
```
Additional bits of text and links can be styled for optimal placement with `.tabnav-extra`:
```html title="tabnav-extra"
<div class="tabnav">
<div class="tabnav-extra float-right">
Tabnav widget text here.
</div>
<nav class="tabnav-tabs" aria-label="Foo bar">
<a href="#url" class="tabnav-tab selected" aria-current="page">Foo Tab</a>
<a href="#url" class="tabnav-tab">Bar Tab</a>
</nav>
</div>
```
```html title="tabnav with everything"
<div class="tabnav">
<div class="float-right">
<a class="tabnav-extra" href="#url">
Tabnav extra link
</a>
<a class="tabnav-extra" href="#url">
Tabnav extra link
</a>
</div>
<nav class="tabnav-tabs" aria-label="Foo bar">
<a href="#url" class="tabnav-tab selected" aria-current="page">Foo Tab</a>
<a href="#url" class="tabnav-tab">Bar Tab</a>
</nav>
</div>
```
## Filter list
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.
```html title="filter-list"
<ul class="filter-list">
<li>
<a href="#url" class="filter-item selected" aria-current="page">
<span class="count" title="results">21</span>
First filter
</a>
</li>
<li>
<a href="#url" class="filter-item">
<span class="count" title="results">3</span>
Second filter
</a>
</li>
<li>
<a href="#url" class="filter-item">
Third filter
</a>
</li>
</ul>
```
## Sub navigation
`.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.
```html title="subnav"
<nav class="subnav" aria-label="Respository">
<a href="#url" class="subnav-item selected" aria-current="page">Item 1</a>
<a href="#url" class="subnav-item">Item 2</a>
<a href="#url" class="subnav-item">Item 3</a>
</nav>
```
You can have `subnav-search` in the subnav bar.
```erb title="subnav-search"
<div class="subnav">
<nav class="subnav-links" aria-label="Repository">
<a href="#url" class="subnav-item selected" aria-current="page">Item 1</a>
<a href="#url" class="subnav-item">Item 2</a>
<a href="#url" class="subnav-item">Item 3</a>
</nav>
<div class="subnav-search float-left">
<input type="search" name="name" class="form-control subnav-search-input" value="" aria-label="Search site">
<%= octicon "search", :class => "subnav-search-icon" %>
</div>
</div>
```
You can also use a `subnav-search-context` to display search help in a select menu.
```erb title="subnav-search-context"
<div class="subnav">
<nav class="subnav-links">
<a href="#url" class="subnav-item selected">Item 1</a>
<a href="#url" class="subnav-item">Item 2</a>
<a href="#url" class="subnav-item">Item 3</a>
</nav>
<div class="float-left ml-3 select-menu js-menu-container js-select-menu subnav-search-context">
<button type="button" name="button" class="btn select-menu-button js-menu-target" aria-expanded="false" aria-haspopup="true">Filters </button>
<div class="select-menu-modal-holder js-menu-content js-navigation-container" aria-hidden="true">
<div class="select-menu-modal">
<div class="select-menu-list">
<a href="#url" class="select-menu-item js-navigation-item">
<div class="select-menu-item-text">
Search filter 1
</div>
</a>
<a href="#url" class="select-menu-item js-navigation-item">
<div class="select-menu-item-text">
Search filter 2
</div>
</a>
<a href="#url" class="select-menu-item js-navigation-item">
<div class="select-menu-item-text">
Search filter 3
</div>
</a>
</div>
</div>
</div>
</div>
<div class="subnav-search float-left">
<input type="search" name="name" class="form-control subnav-search-input" value="" aria-label="Search site">
<%= octicon "search", :class => "subnav-search-icon" %>
</div>
</div>
```

54
pages/css/components/pagination.md Normal file
View File

@ -0,0 +1,54 @@
---
title: Pagination
path: components/pagination
status: New Release
source: 'https://github.com/primer/css/tree/master/src/pagination'
bundle: 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).
{:toc}
## Previous/next pagination
You can make a very simple pagination container with just the Previous and Next buttons. Add the class `disabled` to the `Previous` button if there isn't a preceding page, or to the `Next` button if there isn't a succeeding page.
```html
<nav class="paginate-container" aria-label="Pagination">
<div class="pagination">
<span class="previous_page disabled">Previous</span>
<a class="next_page" rel="next" href="#url" aria-label="Next Page">Next</a>
</div>
</nav>
```
## 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 class `disabled` to the Previous button if you're on the first page. Apply the class `current` 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 the `paginate-container` element.
- Add `aria-current="true"` to the current page marker.
- Add `aria-label="Page X"` to each anchor link.
```html
<nav class="paginate-container" aria-label="Pagination">
<div class="pagination">
<span class="previous_page disabled">Previous</span>
<em class="current selected" aria-current="true">1</em>
<a href="#url" aria-label="Page 2">2</a>
<a href="#url" aria-label="Page 3">3</a>
<span class="gap">…</span>
<a href="#url" aria-label="Page 8">8</a>
<a href="#url" aria-label="Page 9">9</a>
<a href="#url" aria-label="Page 10">10</a>
<a class="next_page" rel="next" href="#url" aria-label="Next Page">Next</a>
</div>
</nav>
```

241
pages/css/components/popover.md Normal file
View File

@ -0,0 +1,241 @@
---
title: Popover
path: components/popover
status: Experimental
source: 'https://github.com/primer/css/tree/master/src/popover'
bundle: popover
---
Popovers are used to bring attention to specific user interface elements, typically to suggest an action or to guide users through a new experience.
{:toc}
A popover consist of:
- The block element, `.Popover`, which simply positions its content absolutely atop other body content.
- The child element, `.Popover-message`, which contains the markup for the intended messaging and the visual "caret."
In the examples below, `Popover-message`, in particular, uses a handful of utility classes to style it appropriately. And these are intended to demonstrate the default, go-to presentation for the popover's message. By default, the message's caret is centered on the top edge of the message.
The `Popover-message` element also supports several modifiers, most of which position the caret differently:
- [`.Popover-message--top`](#default-top-center) (default): Places the caret on the top edge of the message, horizontally centered.
- [`.Popover-message--bottom`](#bottom) Places the caret on the bottom edge of the message, horizontally centered.
- [`.Popover-message--right`](#right): Places the caret on the right edge of the message, vertically centered.
- [`.Popover-message--left`](#left): Places the caret on the left edge of the message, vertically centered.
Each of these modifiers also support a syntax for adjusting the positioning the caret to the right, left, top, or bottom of its respective edge. That syntax looks like:
- [`.Popover-message--bottom-left`](#bottom-left)
- [`.Popover-message--bottom-right`](#bottom-right)
- [`.Popover-message--left-bottom`](#left-bottom)
- [`.Popover-message--left-top`](#left-top)
- [`.Popover-message--right-bottom`](#right-bottom)
- [`.Popover-message--right-top`](#right-top)
- [`.Popover-message--top-left`](#top-left)
- [`.Popover-message--top-right`](#top-right)
Lastly, there is an added [`.Popover-message--large`](#large) modifier, which assumes a slightly wider popover message on screens wider than 544px.
### Notes
The samples below include optional markup, like:
- An outermost container that establishes stacking context (e.g. `position-relative`).
- A choice piece of user interface (a button, in this case) to relate the popover to.
- Use of the `Details` and `js-details` family of class names, which interact with JavaScript to demonstrate dismissal of the popover by clicking the nested "Got it!" button.
### Basic example
Defaults to caret oriented top-center.
```html title="Default (top-center)"
<div class="position-relative text-center">
<button class="btn btn-primary">UI</button>
<div class="Popover right-0 left-0">
<div class="Popover-message text-left p-4 mt-2 mx-auto Box box-shadow-large">
<h4 class="mb-2">Popover heading</h4>
<p>Message about this particular piece of UI.</p>
<button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
</div>
</div>
</div>
```
### Large example
```html title="Large"
<div class="position-relative text-center">
<button class="btn btn-primary">UI</button>
<div class="Popover right-0 left-0">
<div class="Popover-message Popover-message--large text-left p-4 mt-2 Box box-shadow-large">
<h4 class="mb-2">Popover heading</h4>
<p>Message about this particular piece of UI.</p>
<button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
</div>
</div>
</div>
```
### Bottom
```html title="Bottom"
<div class="position-relative text-center">
<div class="Popover position-relative">
<div class="Popover-message Popover-message--bottom p-4 mx-auto mb-2 text-left Box box-shadow-large">
<h4 class="mb-2">Popover heading</h4>
<p>Message about this particular piece of UI.</p>
<button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
</div>
</div>
<button class="btn btn-primary">UI</button>
</div>
```
### Bottom-right
```html title="Bottom-right"
<div class="position-relative text-right">
<div class="Popover position-relative">
<div class="Popover-message Popover-message--bottom-right p-4 mb-2 text-left Box box-shadow-large">
<h4 class="mb-2">Popover heading</h4>
<p>Message about this particular piece of UI.</p>
<button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
</div>
</div>
<button class="btn btn-primary">UI</button>
</div>
```
### Bottom-left
```html title="Bottom-left"
<div class="Popover position-relative">
<div class="Popover-message Popover-message--bottom-left p-4 mb-2 Box box-shadow-large">
<h4 class="mb-2">Popover heading</h4>
<p>Message about this particular piece of UI.</p>
<button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
</div>
</div>
<button class="btn btn-primary">UI</button>
```
### Left
```html title="Left"
<div class="d-flex flex-justify-center flex-items-center">
<button class="btn btn-primary">UI</button>
<div class="Popover position-relative">
<div class="Popover-message Popover-message--left p-4 ml-2 Box box-shadow-large">
<h4 class="mb-2">Popover heading</h4>
<p>Message about this particular piece of UI.</p>
<button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
</div>
</div>
</div>
```
### Left-bottom
```html title="Left-bottom"
<div class="d-flex flex-justify-center flex-items-end">
<button class="btn btn-primary">UI</button>
<div class="Popover position-relative">
<div class="Popover-message Popover-message--left-bottom p-4 ml-2 Box box-shadow-large">
<h4 class="mb-2">Popover heading</h4>
<p>Message about this particular piece of UI.</p>
<button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
</div>
</div>
</div>
```
### Left-top
```html title="Left-top"
<div class="d-flex flex-justify-center flex-items-start">
<button class="btn btn-primary">UI</button>
<div class="Popover position-relative">
<div class="Popover-message Popover-message--left-top p-4 ml-2 Box box-shadow-large">
<h4 class="mb-2">Popover heading</h4>
<p>Message about this particular piece of UI.</p>
<button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
</div>
</div>
</div>
```
### Right
```html title="Right"
<div class="d-flex flex-justify-center flex-items-center">
<div class="Popover position-relative">
<div class="Popover-message Popover-message--right p-4 mr-2 Box box-shadow-large">
<h4 class="mb-2">Popover heading</h4>
<p>Message about this particular piece of UI.</p>
<button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
</div>
</div>
<button class="btn btn-primary">UI</button>
</div>
```
### Right-bottom
```html title="Right-bottom"
<div class="d-flex flex-justify-center flex-items-end">
<div class="Popover position-relative">
<div class="Popover-message Popover-message--right-bottom p-4 mr-2 Box box-shadow-large">
<h4 class="mb-2">Popover heading</h4>
<p>Message about this particular piece of UI.</p>
<button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
</div>
</div>
<button class="btn btn-primary">UI</button>
</div>
```
### Right-top
```html title="Right-top"
<div class="d-flex flex-justify-center flex-items-start">
<div class="Popover position-relative">
<div class="Popover-message Popover-message--right-top p-4 mr-2 Box box-shadow-large">
<h4 class="mb-2">Popover heading</h4>
<p>Message about this particular piece of UI.</p>
<button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
</div>
</div>
<button class="btn btn-primary">UI</button>
</div>
```
### Top-left
```html title="Top-left"
<div class="position-relative">
<button class="btn btn-primary">UI</button>
<div class="Popover">
<div class="Popover-message Popover-message--top-left p-4 mt-2 Box box-shadow-large">
<h4 class="mb-2">Popover heading</h4>
<p>Message about this particular piece of UI.</p>
<button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
</div>
</div>
</div>
```
### Top-right
```html title="Top-right"
<div class="position-relative text-right">
<button class="btn btn-primary">UI</button>
<div class="Popover right-0">
<div class="Popover-message Popover-message--top-right text-left p-4 mt-2 Box box-shadow-large">
<h4 class="mb-2">Popover heading</h4>
<p>Message about this particular piece of UI.</p>
<button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
</div>
</div>
</div>
```

57
pages/css/components/progress.md Normal file
View File

@ -0,0 +1,57 @@
---
title: Progress
path: components/progress
status: New Release
source: 'https://github.com/primer/css/tree/master/src/progress'
bundle: progress
---
Use Progress components to visualize task completion.
## Default Progress
```html
<span class="Progress">
<span class="Progress-value bg-green" style="width: 50%;"></span>
</span>
```
## Large Progress
```html
<span class="Progress Progress--large">
<span class="Progress-value bg-green" style="width: 50%;"></span>
</span>
```
## Small Progress
```html
<span class="Progress Progress--small">
<span class="Progress-value bg-green" style="width: 50%;"></span>
</span>
```
## Progress with tooltip
```html
<div class="tooltipped tooltipped-n" aria-label="78 done / 6 in progress / 2 to do">
<span class="Progress">
<span class="Progress-value bg-green" style="width: 50%;"></span>
</span>
</div>
```
## Progress with multiple values
```html
<div class="tooltipped tooltipped-n" aria-label="78 done / 6 in progress / 2 to do">
<span class="Progress">
<span class="Progress-value bg-green" style="width: 50%;"></span>
<span class="Progress-value bg-purple" style="width: 25%;"></span>
<span class="Progress-value bg-red" style="width: 5%;"></span>
</span>
</div>
```

80
pages/css/components/subhead.md Normal file
View File

@ -0,0 +1,80 @@
---
title: Subhead
path: components/subhead
status: Stable
status_issue: 'https://github.com/github/design-systems/issues/101'
source: 'https://github.com/primer/css/tree/master/src/subhead'
bundle: subhead
---
The basic Subhead consists of a `.Subhead` container, which has a light gray bottom border. Use `.Subhead-heading` for the heading itself. It's an `<h2>` sized heading with normal font-weight.
Use a heading element whenever possible as they can be used as navigation for assistive technologies, and avoid skipping levels.
```html title="Subhead"
<div class="Subhead">
<div class="Subhead-heading">Plain subhead</div>
</div>
```
To add a top margin to the Subhead, use `.Subhead--spacious`. This is useful for separating sections on a settings page.
```html title="Spacious Subhead"
<div class="Subhead Subhead--spacious">
<div class="Subhead-heading">Spacious subhead</div>
</div>
```
You can add a one line description to the subhead with `.Subhead-description`.
```html title="Subhead with description"
<div class="Subhead">
<div class="Subhead-heading">Subhead with description</div>
<div class="Subhead-description">The subhead is a subdued header style with a light bottom border.</div>
</div>
```
For longer descriptions, it is recommended that you use a paragraph below the Subhead.
```html title="Subhead with longer description"
<div class="Subhead">
<div class="Subhead-heading">Plain subhead</div>
</div>
<p>
This is a longer description that is sitting below the Subheader. It's much longer than a description that could sit comfortably in the Subhead. It might even have <strong>bold</strong> text. <a href="#">Click to learn more.</a>
</p>
```
You can add a button or something to the right of `.Subhead-heading` with the `.Subhead-actions` element.
```html title="Subhead with actions"
<div class="Subhead">
<div class="Subhead-heading">Subhead with button</div>
<div class="Subhead-actions"><a href="#url" class="btn btn-sm btn-primary" role="button">Action</a></div>
</div>
<div class="Subhead Subhead--spacious">
<div class="Subhead-heading">Subhead with link</div>
<div class="Subhead-actions"><a href="#url">Learn more</a></div>
</div>
```
Use all the elements together to create a Subhead with actions and a description.
```html title="Subhead with actions and description"
<div class="Subhead">
<div class="Subhead-heading">Subhead with actions and description</div>
<div class="Subhead-actions"><a href="#url" class="btn btn-sm btn-primary" role="button">Action</a></div>
<div class="Subhead-description">The subhead is a subdued header style with a light bottom border.</div>
</div>
```
Use the `.Subhead-heading--danger` modifier to make the text bold and red. This is useful for warning users.
```html title="Subhead danger"
<div class="Subhead">
<div class="Subhead-heading Subhead-heading--danger">Danger zone</div>
</div>
```

113
pages/css/components/tooltips.md Normal file
View File

@ -0,0 +1,113 @@
---
title: Tooltips
path: components/tooltips
status: Stable
source: 'https://github.com/primer/css/tree/master/src/tooltips'
bundle: tooltips
---
Add tooltips built entirely in CSS to nearly any element.
{:toc}
## 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?
**Attention**: 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, or consider using `title` for supplemental information.
**Note:** 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:
- `.tooltipped-n`
- `.tooltipped-ne`
- `.tooltipped-e`
- `.tooltipped-se`
- `.tooltipped-s`
- `.tooltipped-sw`
- `.tooltipped-w`
- `.tooltipped-nw`
```html
<span class="tooltipped tooltipped-n border p-2 mb-2 mr-2 float-left" aria-label="This is the tooltip on the North side.">
Tooltip North
</span>
<span class="tooltipped tooltipped-ne border p-2 mb-2 mr-2 float-left" aria-label="This is the tooltip on the North East side.">
Tooltip North East
</span>
<span class="tooltipped tooltipped-e border p-2 mb-2 mr-2 float-left" aria-label="This is the tooltip on the East side.">
Tooltip East
</span>
<span class="tooltipped tooltipped-se border p-2 mb-2 mr-2 float-left" aria-label="This is the tooltip on the South East side.">
Tooltip South East
</span>
<span class="tooltipped tooltipped-s border p-2 mb-2 mr-2 float-left" aria-label="This is the tooltip on the South side.">
Tooltip South
</span>
<span class="tooltipped tooltipped-sw border p-2 mb-2 mr-2 float-left" aria-label="This is the tooltip on the South West side.">
Tooltip South West
</span>
<span class="tooltipped tooltipped-w border p-2 mb-2 mr-2 float-left" aria-label="This is the tooltip on the West side.">
Tooltip West
</span>
<span class="tooltipped tooltipped-nw border p-2 mb-2 mr-2 float-left" aria-label="This is the tooltip on the North West side.">
Tooltip North West
</span>
```
## Tooltip alignment
Align tooltips to the left or right of an element, combined with a directional class to specify north or south.
```html
<span class="tooltipped tooltipped-ne tooltipped-align-left-1 border p-2 mb-2 mr-2 float-left" aria-label="Tooltipped NE and aligned left.">
Tooltip North East align left 1
</span>
<span class="tooltipped tooltipped-ne tooltipped-align-left-2 border p-2 mb-2 mr-2 float-left" aria-label="Tooltipped NE and aligned left.">
Tooltip North East align left 2
</span>
<span class="tooltipped tooltipped-se tooltipped-align-left-1 border p-2 mb-2 mr-2 float-left" aria-label="Tooltipped SW and aigned left.">
Tooltip South East align left 1
</span>
<span class="tooltipped tooltipped-se tooltipped-align-left-2 border p-2 mb-2 mr-2 float-left" aria-label="Tooltipped SW and aigned left.">
Tooltip South East align left 2
</span>
<span class="tooltipped tooltipped-nw tooltipped-align-right-1 border p-2 mb-2 mr-2 float-left" aria-label="Tooltipped NW and aligned right.">
Tooltip North West align right 1
</span>
<span class="tooltipped tooltipped-nw tooltipped-align-right-2 border p-2 mb-2 mr-2 float-left" aria-label="Tooltipped NW and aligned right.">
Tooltip North West align right 2
</span>
<span class="tooltipped tooltipped-sw tooltipped-align-right-1 border p-2 mb-2 mr-2 float-left" aria-label="Tooltipped SE and aligned right.">
Tooltip South West align right 1
</span>
<span class="tooltipped tooltipped-sw tooltipped-align-right-2 border p-2 mb-2 mr-2 float-left" aria-label="Tooltipped SE and aligned right.">
Tooltip South West align right 2
</span>
```
## 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`.
```html
<span class="tooltipped tooltipped-multiline tooltipped-n border p-2" aria-label="This is the tooltip with multiple lines. This is the tooltip with multiple lines.">
Tooltip with multiple lines
</span>
```
## Tooltips 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 modifier class you can use to override this. `.tooltipped-no-delay`
```html
<span class="tooltipped tooltipped-n tooltipped-no-delay border p-2" aria-label="This is the tooltip on the no delay side.">
Tooltip no delay
</span>
```

24
pages/css/components/truncate.md Normal file
View File

@ -0,0 +1,24 @@
---
title: Truncate
path: components/truncate
status: Stable
source: 'https://github.com/primer/css/tree/master/src/truncate'
bundle: truncate
---
`.css-truncate` will shorten text with an ellipsis. The maximum width of the truncated text can be changed by overriding the max-width of `.css-truncate-target`. Unless the full text is so long that it affects performace, always add `title` to the truncated element so the full text can still be seen.
```html title="Truncate"
<span class="branch-ref css-truncate css-truncate-target" title="really-long-branch-name">
really-long-branch-name
</span>
```
You can reveal the entire string on hover with the addition of `.expandable`.
```html title="Truncate Expandable"
<span class="css-truncate expandable">
<span class="branch-ref css-truncate-target">this-is-a-really-long-branch-name</span>
</span>
```

5
src/layout/docs/grid.md → pages/css/objects/grid.md
View File

@ -2,8 +2,9 @@
title: Grid
path: objects/grid
status: Stable
status_issue: https://github.com/github/design-systems/issues/88
source: https://github.com/primer/css/blob/master/modules/primer-layout/lib/grid.scss
status_issue: 'https://github.com/github/design-systems/issues/88'
source: 'https://github.com/primer/css/tree/master/src/layout/grid.scss'
bundle: layout
---
The grid is 12 columns and percentage-based. The number of columns a container spans can be adjusted across breakpoints for responsive layouts. The grid system works with a variety of layout utilities to achieve different results.

92
pages/css/objects/layout.md Normal file
View File

@ -0,0 +1,92 @@
---
title: Layout
path: objects/layout
status: Deprecated
status_issue: 'https://github.com/github/design-systems/issues/59'
source: 'https://github.com/primer/css/tree/master/src/layout'
bundle: layout
---
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`.
#### Container
Center your page's contents with a `.container`.
```html title="Container"
<div class="container border">
Container
</div>
```
The container applies `width: 980px;` and uses horizontal `margin`s to center it.
#### Grid
##### How it works
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:
- Add a `.container` to encapsulate everything and provide ample horizontal gutter space.
- Create your outer row to clear the floated columns with `<div class="columns">`.
- Add your columns with individual `<div class="column">`s.
- Add your fractional width classes to set the width of the columns (e.g., `.one-fourth`).
##### Demo
In practice, your columns will look like the example below.
```html title="Grid columns"
<div class="container">
<div class="columns mb-1">
<div class="one-fifth column block-blue p-3 border">
.one-fifth
</div>
<div class="four-fifths column block-blue p-3 border">
.four-fifths
</div>
</div>
<div class="columns mb-1">
<div class="one-fourth column block-blue p-3 border">
.one-fourth
</div>
<div class="three-fourths column block-blue p-3 border">
.three-fourths
</div>
</div>
<div class="columns mb-1">
<div class="one-third column block-blue p-3 border">
.one-third
</div>
<div class="two-thirds column block-blue p-3 border">
.two-thirds
</div>
</div>
<div class="columns">
<div class="one-half column block-blue p-3 border">
.one-half
</div>
<div class="one-half column block-blue p-3 border">
.one-half
</div>
</div>
</div>
```
##### Centered
Columns can be centered by adding `.centered` to the `.column` class.
```html title="Grid centered"
<div class="columns">
<div class="one-half column centered block-blue border p-3">
.one-half
</div>
</div>
```

24
pages/css/objects/table-object.md Normal file
View File

@ -0,0 +1,24 @@
---
title: Table object
path: objects/table-object
status: Stable
source: 'https://github.com/primer/css/tree/master/src/table-object'
bundle: table-object
---
The table object 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.
```html title="Table object"
<div class="TableObject">
<div class="TableObject-item TableObject-item--primary">
<input class="input-block form-control" type="text" placeholder="Long elastic input form" aria-label="Long elastic input form">
</div>
<div class="TableObject-item">
<button class="btn ml-2" type="button">Button</button>
</div>
</div>
```

2
src/support/docs/breakpoints.md → pages/css/support/breakpoints.md
View File

@ -2,6 +2,8 @@
title: Breakpoints
path: support/breakpoints
status: Stable
source: 'https://github.com/primer/css/blob/master/src/support/variables/layout.scss'
bundle: support
---
{:toc}

19
pages/css/support/index.md Normal file
View File

@ -0,0 +1,19 @@
---
title: Support
path: support/index
source: 'https://github.com/primer/css/tree/master/src/support'
bundle: support
---
Primer is built on systems that form the foundation of our styles, and inform the way we write and organize our CSS. Building upon systems helps us make styles consistent and interoperable with each other, and assists us with visual hierarchy and vertical rhythm.
We use Sass variables to keep color, typography, spacing, and other foundations of our system consistent. Occasionally we use Sass mixins to apply multiple CSS properties, they are a convenient solution for frequently-used verbose patterns.
We've documented variables, mixins, and the systems they are built on for the following:
- [Breakpoints](/css/support/breakpoints)
- [Colors](/css/support/color-system)
- [Spacing](/css/support/spacing)
- [Typography](/css/support/typography)

25
pages/css/support/marketing-variables.md Normal file
View File

@ -0,0 +1,25 @@
---
title: Marketing support
path: support/marketing-variables
status: Stable
source: 'https://github.com/primer/css/tree/master/src/marketing/support'
bundle: marketing-support
---
### Extended spacing scale
This module extends the `primer-core` spacing scale for marketing site needs. These are useful for achieving bigger vertical spacing between sections on marketing sites.
Starting where the `primer-core` spacing scale ends at spacer 6, the marketing scale first steps up with `8px` for spacer 7 then steps in increments of `16px` from spacer 8 up to 12.
| Scale | Value |
|-------|-------|
| 7 | 48 |
| 8 | 64 |
| 9 | 80 |
| 10 | 96 |
| 11 | 112 |
| 12 | 128 |
See [primer-marketing-support](https://npm.im/primer-marketing-support) for the extended spacing scale used for marketing needs and the related y-axis spacing utilities for [margin](/css/utilities/marketing-margin) and [padding](/css/utilities/marketing-padding).

3
src/support/docs/spacing.md → pages/css/support/spacing.md
View File

@ -2,7 +2,8 @@
title: Spacing
path: support/spacing
status: Stable
source: https://github.com/primer/css/blob/master/modules/primer-support/lib/variables/layout.scss
source: 'https://github.com/primer/css/blob/master/src/support/variables/layout.scss'
bundle: support
---
{:toc}

5
src/support/docs/typography.md → pages/css/support/typography.md
View File

@ -2,8 +2,9 @@
title: Typography
path: support/typography
status: Stable
status_issue: https://github.com/github/design-systems/issues/329
source: https://github.com/primer/css/blob/master/modules/primer-support/lib/variables/typography.scss
status_issue: 'https://github.com/github/design-systems/issues/329'
source: 'https://github.com/primer/css/blob/master/src/support/variables/typography.scss'
bundle: support
---
{:toc}

2
src/utilities/docs/animations.md → pages/css/utilities/animations.md
View File

@ -3,6 +3,8 @@ title: Animations
path: utilities/animations
example_layout: toggle
status: Stable
source: 'https://github.com/primer/css/blob/master/src/utilities/animations.scss'
bundle: utilities
---
Animations are reusable animation classes that you can use to emphasize an element. All of these animations will animate if you toggle their visibility using the "Toggle" button.

4
src/utilities/docs/borders.md → pages/css/utilities/borders.md
View File

@ -2,7 +2,9 @@
title: Borders
path: utilities/borders
status: Stable
status_issue: https://github.com/github/design-systems/issues/72
status_issue: 'https://github.com/github/design-systems/issues/72'
source: 'https://github.com/primer/css/tree/master/src/utilities/borders.scss'
bundle: utilities
---
Utilities for borders, border radius, and box shadows.

4
src/utilities/docs/box-shadow.md → pages/css/utilities/box-shadow.md
View File

@ -2,7 +2,9 @@
title: Box shadow
path: utilities/box-shadow
status: Stable
status_issue: https://github.com/github/design-systems/issues/269
status_issue: 'https://github.com/github/design-systems/issues/269'
source: 'https://github.com/primer/css/tree/master/src/utilities/box-shadow.scss'
bundle: utilities
---
Box shadows are used to make content appear elevated. They are typically applied to containers of content that users need to pay attention to or content that appears on top of (overlapping) other elements on the page (like a pop-over or modal).

2
src/utilities/docs/details.md → pages/css/utilities/details.md
View File

@ -2,6 +2,8 @@
title: Details
path: utilities/details
status: Stable
source: 'https://github.com/primer/css/blob/master/src/utilities/details.scss'
bundle: utilities
---
Details classes are created to enhance the native behaviors of `<details>`.

4
src/utilities/docs/flexbox.md → pages/css/utilities/flexbox.md
View File

@ -2,7 +2,9 @@
title: Flexbox
path: utilities/flexbox
status: Stable
status_issue: https://github.com/github/design-systems/issues/157
status_issue: 'https://github.com/github/design-systems/issues/157'
source: 'https://github.com/primer/css/blob/master/src/utilities/flexbox.scss'
bundle: utilities
---
Flex utilities can be used to apply `flexbox` behaviors to elements by using utility classes.

2
src/utilities/docs/layout.md → pages/css/utilities/layout.md
View File

@ -2,6 +2,8 @@
title: Layout
path: utilities/layout
status: Stable
source: 'https://github.com/primer/css/blob/master/src/utilities/layout.scss'
bundle: utilities
---
Change the document layout with display, float, alignment, and other utilities.

2
src/utilities/docs/margin.md → pages/css/utilities/margin.md
View File

@ -2,6 +2,8 @@
title: Margin
path: utilities/margin
status: Stable
source: 'https://github.com/primer/css/blob/master/src/utilities/margin.scss'
bundle: utilities
---
Margin utilities are based on a global [spacing scale](/css/support/spacing) which helps keep horizontal and vertical spacing consistent. These utilities help us reduce the amount of custom CSS that share the same properties, and allows to achieve many different page layouts using the same styles.

2
src/marketing/utilities/docs/borders.md → pages/css/utilities/marketing-borders.md
View File

@ -3,6 +3,8 @@ title: Marketing Borders
sort_title: Borders Marketing
path: utilities/marketing-borders
status: Stable
source: 'https://github.com/primer/css/blob/master/src/marketing/utilities/borders.scss'
bundle: marketing-utilities
---
The following border utilities are meant to used in addition to those within primer-core.

4
src/marketing/utilities/docs/filters.md → pages/css/utilities/marketing-filters.md
View File

@ -2,7 +2,9 @@
title: Marketing Filters
path: utilities/marketing-filters
status: Stable
status_issue: https://github.com/github/design-systems/issues/302
status_issue: 'https://github.com/github/design-systems/issues/302'
source: 'https://github.com/primer/css/blob/master/src/marketing/utilities/filters.scss'
bundle: marketing-utilities
---
Filter utility classes can be applied to divs or images to apply visual effects.

2
src/marketing/utilities/docs/layout.md → pages/css/utilities/marketing-layout.md
View File

@ -3,6 +3,8 @@ title: Marketing Layout
sort_title: Layout Marketing
path: utilities/marketing-layout
status: Stable
source: 'https://github.com/primer/css/blob/master/src/marketing/utilities/layout.scss'
bundle: marketing-utilities
---
Marketing layout utilities build on top of [primer-core utilities](/css/utilities/layout#position), adding the option of responsive positioning.

4
src/marketing/utilities/docs/margin.md → pages/css/utilities/marketing-margin.md
View File

@ -3,7 +3,9 @@ title: Marketing Margin
sort_title: Margin Marketing
path: utilities/marketing-margin
status: Stable
status_issue: https://github.com/github/design-systems/issues/378
status_issue: 'https://github.com/github/design-systems/issues/378'
source: 'https://github.com/primer/css/blob/master/src/marketing/utilities/margin.scss'
bundle: marketing-utilities
---
Marketing margin utilities extend [core margin utilities](/css/support/spacing) across the y-axis only. The [marketing scale](/css/support/marketing-variables#extended-spacing-scale) starts from spacer 7 up to 12, and steps first by `8px` for spacer 7 and continues in increments of `16px` for spacer 8 to 12.

4
src/marketing/utilities/docs/padding.md → pages/css/utilities/marketing-padding.md
View File

@ -3,7 +3,9 @@ title: Marketing Padding
sort_title: Padding Marketing
path: utilities/marketing-padding
status: Stable
status_issue: https://github.com/github/design-systems/issues/378
status_issue: 'https://github.com/github/design-systems/issues/378'
source: 'https://github.com/primer/css/tree/master/src/marketing/utilities/padding.scss'
bundle: marketing-utilities
---
Marketing padding utilities extend [core margin utilities](/css/utilities/margin) across the x and y axis. The [marketing scale](/css/support/marketing-variables#extended-spacing-scale) starts from spacer 7 up to 12, and steps first by `8px` for spacer 7 and continues in increments of `16px` for spacer 8 to 12.

42
pages/css/utilities/marketing-type.md Normal file
View File

@ -0,0 +1,42 @@
---
title: Marketing Typography
path: utilities/marketing-type
status: New Release
source: 'https://github.com/primer/css/tree/master/src/marketing/type'
bundle: marketing-type
---
The typography for our marketing pages differs slightly from what is in Primer's core--it is responsive, on a slightly different scale, and headlines are in a different font (Roboto).
## Heading Utilities
Use `.h000-mktg` – `.h6-mktg` to change an element's font, size, and weight on marketing pages.
```html title="Heading Utilities"
<p class="h000-mktg">Heading 000</p>
<p class="h00-mktg">Heading 00</p>
<p class="h0-mktg">Heading 0</p>
<p class="h1-mktg">Heading 1</p>
<p class="h2-mktg">Heading 2</p>
<p class="h3-mktg">Heading 3</p>
<p class="h4-mktg">Heading 4</p>
<p class="h5-mktg">Heading 5</p>
<p class="h6-mktg">Heading 6</p>
```
## Typographic Utilities
These utilities are meant to be used in addition to Primer's core utilities.
```html title="Typographic Utilities"
<p class="lead-mktg text-gray">I'm a lead paragraph. Bacon ipsum dolor amet tri-tip chicken kielbasa, cow swine beef corned beef ground round prosciutto hamburger porchetta sausage alcatra tail.</p>
<p class="pullquote">I'm a pullquote. Someone said these words in real life, and now they're on the internet</p>
```

2
src/utilities/docs/padding.md → pages/css/utilities/padding.md
View File

@ -2,6 +2,8 @@
title: Padding
path: utilities/padding
status: Stable
source: 'https://github.com/primer/css/tree/master/src/utilities/padding.scss'
bundle: utilities
---
Padding utilities are based on a global [spacing scale](/css/support/spacing) which helps keep horizontal and vertical spacing consistent. These utilities help us reduce the amount of custom CSS that could share the same properties, and allows to achieve many different page layouts using the same styles.

2
src/utilities/docs/typography.md → pages/css/utilities/typography.md
View File

@ -2,6 +2,8 @@
title: Typography
path: utilities/typography
status: Stable
source: 'https://github.com/primer/css/tree/master/src/utilities/typography.scss'
bundle: utilities
---
Type utilities are designed to work in combination with line-height utilities so as to result in more sensible numbers wherever possible. These also exist as [variables](/css/support/typography#typography-variables) that you can use in components or custom CSS.

21
script/sync
View File

@ -1,21 +0,0 @@
#!/usr/bin/env node
const sync = require('../lib/sync')
const args = process.argv.slice(2)
const options = {
debug: !args.includes('--quiet'),
watch: args.includes('--watch')
}
sync(options)
.then(files => {
const built = Object.keys(files)
console.warn(`built ${built.length} files:`)
for (const file of built) {
console.warn(`- ${file}`)
}
})
.catch(error => {
console.error(error)
process.exitCode = 1
})

120
src/alerts/README.md
View File

@ -1,20 +1,8 @@
# Primer Alerts
[![npm version](https://img.shields.io/npm/v/primer-alerts.svg)](https://www.npmjs.org/package/primer-alerts)
[![Build Status](https://travis-ci.org/primer/css.svg?branch=master)](https://travis-ci.org/primer/primer)
> Flash messages, or alerts, inform users of successful or pending actions. Use them sparingly. Don’t show more than one at a time.
This repository is a module of the full [primer][primer] repository.
## Install
This repository is distributed with [npm][npm]. After [installing npm][install-npm], you can install `primer-alerts` with this command.
```
$ npm install --save primer-alerts
```
## Usage
The source files included are written in [Sass][sass] (`scss`) You can simply point your sass `include-path` at your `node_modules` directory and import it like this.
@ -35,118 +23,14 @@ $ npm run build
## Documentation
<!-- %docs
title: Alerts
path: components/alerts
status: Stable
-->
Flash messages, or alerts, inform users of successful or pending actions. Use them sparingly. Don't show more than one at a time.
## Default
Flash messages start off looking decently neutral—they're just light blue rounded rectangles.
```html
<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.
```html
<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.*
```html
<div class="flash-messages">
<div class="flash">
Flash message goes here.
</div>
</div>
```
## Variations
Add `.flash-warn`, `.flash-error`, or `.flash-success` to the flash message to make it yellow, red, or green, respectively.
```html
<div class="flash flash-warn">
Flash message goes here.
</div>
```
```html
<div class="flash flash-error">
Flash message goes here.
</div>
```
```html
<div class="flash flash-success">
Flash message goes here.
</div>
```
## With icon
Add an icon to the left of the flash message to give it some funky fresh attention.
```erb
<div class="flash">
<%= octicon "alert" %>
Flash message with an icon goes here.
</div>
```
## With dismiss
Add a JavaScript enabled (via Crema) dismiss (close) icon on the right of any flash message.
```erb
<div class="flash">
<button class="flash-close js-flash-close" type="button"><%= octicon "x", :"aria-label" => "Close" %></button>
Dismissable flash message goes here.
</div>
```
## With action button
A flash message with an action button.
```html
<div class="flash">
<button type="submit" class="btn btn-sm primary flash-action">Complete action</button>
Flash message with action here.
</div>
```
## Full width flash
A flash message that is full width and removes border and border radius.
```html
<div class="flash flash-full">
<div class="container">
Full width flash message.
</div>
</div>
```
<!-- %enddocs -->
Find further documentation at [primer.style/css/components/alerts](https://primer.style/css/components/alerts).
## License
[MIT](./LICENSE) &copy; [GitHub](https://github.com/)
[primer]: https://github.com/primer/css
[docs]: http://primer.github.io/
[docs]: https://primer.style/css
[npm]: https://www.npmjs.com/
[install-npm]: https://docs.npmjs.com/getting-started/installing-node
[sass]: http://sass-lang.com/

169
src/avatars/README.md
View File

@ -1,20 +1,9 @@
# Primer Avatars
[![npm version](https://img.shields.io/npm/v/primer-avatars.svg)](https://www.npmjs.org/package/primer-avatars)
[![Build Status](https://travis-ci.org/primer/css.svg?branch=master)](https://travis-ci.org/primer/primer)
> 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.
This repository is a module of the full [primer][primer] repository.
## Install
This repository is distributed with [npm][npm]. After [installing npm][install-npm], you can install `primer-avatars` with this command.
```
$ npm install --save primer-avatars
```
## Usage
The source files included are written in [Sass][sass] (`scss`) You can simply point your sass `include-path` at your `node_modules` directory and import it like this.
@ -35,168 +24,14 @@ $ npm run build
## Documentation
<!-- %docs
title: Avatars
path: components/avatars
status: Stable
-->
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.
{:toc}
## Basic example
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.
```html
<img class="avatar" alt="jonrohan" src="https://github.com/jonrohan.png?v=3&s=144" width="72" height="72">
```
### Small avatars
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.
```html
<img class="avatar avatar-small" alt="jonrohan" src="https://github.com/jonrohan.png?v=3&s=64" width="32" height="32">
```
### Parent-child avatars
When you need a larger parent avatar, and a smaller child one, overlaid slightly, use the parent-child classes.
```html
<div class="avatar-parent-child float-left">
<img class="avatar" alt="jonrohan" src="https://github.com/jonrohan.png?v=3&s=96" width="48" height="48">
<img class="avatar avatar-child" alt="josh" src="https://github.com/josh.png?v=3&s=40" width="20" height="20">
</div>
```
### Avatar stack
Stacked avatars can be used to show multiple collaborators or participants when there is limited space available. When you hover over the stack, the avatars will reveal themselves.
```html
<div class="AvatarStack AvatarStack--three-plus">
<div class="AvatarStack-body tooltipped tooltipped-se tooltipped-align-left-1" aria-label="octocat, octocat, and octocat">
<img class="avatar" height="20" alt="@octocat" src="https://user-images.githubusercontent.com/334891/29999089-2837c968-9009-11e7-92c1-6a7540a594d5.png" width="20">
<img class="avatar" height="20" alt="@octocat" src="https://user-images.githubusercontent.com/334891/29999089-2837c968-9009-11e7-92c1-6a7540a594d5.png" width="20">
<img class="avatar" height="20" alt="@octocat" src="https://user-images.githubusercontent.com/334891/29999089-2837c968-9009-11e7-92c1-6a7540a594d5.png" width="20">
</div>
</div>
```
Based on the number of avatars in the stack, add these modifier classes:
- `AvatarStack--two` for 2 avatars.
- `AvatarStack--three-plus` for 3 or more avatars.
If you have more than three avatars, add a div with the classes `avatar avatar-more` as the third avatar in the stack, as such:
```html
<div class="AvatarStack AvatarStack--three-plus">
<div class="AvatarStack-body tooltipped tooltipped-se tooltipped-align-left-1" aria-label="octocat, octocat, octocat, octocat, and octocat">
<img class="avatar" height="20" alt="@octocat" src="https://user-images.githubusercontent.com/334891/29999089-2837c968-9009-11e7-92c1-6a7540a594d5.png" width="20">
<img class="avatar" height="20" alt="@octocat" src="https://user-images.githubusercontent.com/334891/29999089-2837c968-9009-11e7-92c1-6a7540a594d5.png" width="20">
<div class="avatar avatar-more"></div>
<img class="avatar" height="20" alt="@octocat" src="https://user-images.githubusercontent.com/334891/29999089-2837c968-9009-11e7-92c1-6a7540a594d5.png" width="20">
<img class="avatar" height="20" alt="@octocat" src="https://user-images.githubusercontent.com/334891/29999089-2837c968-9009-11e7-92c1-6a7540a594d5.png" width="20">
<img class="avatar" height="20" alt="@octocat" src="https://user-images.githubusercontent.com/334891/29999089-2837c968-9009-11e7-92c1-6a7540a594d5.png" width="20">
</div>
</div>
```
You can also link individual avatars. To do this shift the `avatar` class over to the anchor:
```html
<div class="AvatarStack AvatarStack--two">
<div class="AvatarStack-body tooltipped tooltipped-se tooltipped-align-left-1" aria-label="octocat and octocat">
<a href="#" class="avatar">
<img height="20" alt="@octocat" src="https://user-images.githubusercontent.com/334891/29999089-2837c968-9009-11e7-92c1-6a7540a594d5.png" width="20">
</a>
<a href="#" class="avatar">
<img height="20" alt="@octocat" src="https://user-images.githubusercontent.com/334891/29999089-2837c968-9009-11e7-92c1-6a7540a594d5.png" width="20">
</a>
</div>
</div>
```
Use `AvatarStack--right` to right-align the avatar stack. Remember to switch the alignment of tooltips when making this change.
```html
<div class="AvatarStack AvatarStack--three-plus AvatarStack--right">
<div class="AvatarStack-body tooltipped tooltipped-sw tooltipped-align-right-1" aria-label="octocat, octocat, and octocat">
<img class="avatar" height="20" alt="@octocat" src="https://user-images.githubusercontent.com/334891/29999089-2837c968-9009-11e7-92c1-6a7540a594d5.png" width="20">
<img class="avatar" height="20" alt="@octocat" src="https://user-images.githubusercontent.com/334891/29999089-2837c968-9009-11e7-92c1-6a7540a594d5.png" width="20">
<img class="avatar" height="20" alt="@octocat" src="https://user-images.githubusercontent.com/334891/29999089-2837c968-9009-11e7-92c1-6a7540a594d5.png" width="20">
</div>
</div>
```
## Circle Badge
`.CircleBadge` allows for the display of badge-like icons or logos. They are used mostly with Octicons or partner integration icons.
`.CircleBadge` should have an `aria-label`, `title` (for a link), or an `alt` (for child `img` elements) attribute specified if there is no text-based alternative to describe it. If there is a text-based alternative or the icon has no semantic value, `aria-hidden="true"` or an empty `alt` attribute may be used.
### Small
```erb
<a class="CircleBadge CircleBadge--small float-left mr-2" href="#small" title="Travis CI">
<img src="https://github.com/travis-ci.png" class="CircleBadge-icon" alt="">
</a>
<a class="CircleBadge CircleBadge--small bg-yellow" title="Zap this!" href="#small">
<%= octicon "zap", :class => "CircleBadge-icon text-white" %>
</a>
```
### Medium
```html
<div class="CircleBadge CircleBadge--medium bg-gray-dark">
<img src="https://github.com/travis-ci.png" alt="Travis CI" class="CircleBadge-icon">
</div>
```
### Large
```html
<div class="CircleBadge CircleBadge--large">
<img src="https://github.com/travis-ci.png" alt="Travis CI" class="CircleBadge-icon">
</div>
```
### Dashed connection
For specific cases where two badges or more need to be shown as related or connected (such as integrations or specific product workflows), a `DashedConnection` class was created. Use utility classes to ensure badges are spaced correctly.
```erb
<div class="DashedConnection">
<ul class="d-flex list-style-none flex-justify-between" aria-label="A sample GitHub workflow">
<li class="CircleBadge CircleBadge--small" aria-label="GitHub">
<%= octicon "mark-github", :class => "width-full height-full" %>
</li>
<li class="CircleBadge CircleBadge--small" aria-label="Slack">
<img src="https://github.com/slackhq.png" alt="" class="CircleBadge-icon">
</li>
<li class="CircleBadge CircleBadge--small" aria-label="Travis CI">
<img src="https://github.com/travis-ci.png" alt="" class="CircleBadge-icon">
</li>
</ul>
</div>
```
<!-- %enddocs -->
Find further documentation at [primer.style/css/components/avatars](https://primer.style/css/components/avatars).
## License
[MIT](./LICENSE) &copy; [GitHub](https://github.com/)
[primer]: https://github.com/primer/css
[docs]: http://primer.github.io/
[docs]: https://primer.style/css
[npm]: https://www.npmjs.com/
[install-npm]: https://docs.npmjs.com/getting-started/installing-node
[sass]: http://sass-lang.com/

14
src/base/README.md
View File

@ -1,20 +1,8 @@
# Primer Base
[![npm version](https://img.shields.io/npm/v/primer-base.svg)](https://www.npmjs.org/package/primer-base)
[![Build Status](https://travis-ci.org/primer/css.svg?branch=master)](https://travis-ci.org/primer/primer)
> GitHub's CSS to reset the browsers default styles. Built on top of normalize.css
This repository is a module of the full [primer][primer] repository. And is built off of [normalize.css](https://github.com/necolas/normalize.css/)
## Install
This repository is distributed with [npm][npm]. After [installing npm][install-npm], you can install `primer-base` with this command.
```
$ npm install --save primer-base
```
## Usage
The source files included are written in [Sass][sass] (`scss`) You can simply point your sass `include-path` at your `node_modules` directory and import it like this.
@ -42,7 +30,7 @@ You can read more about base in the [docs][docs].
[MIT](./LICENSE) &copy; [GitHub](https://github.com/)
[primer]: https://github.com/primer/css
[docs]: http://primer.github.io/
[docs]: https://primer.style/css
[npm]: https://www.npmjs.com/
[install-npm]: https://docs.npmjs.com/getting-started/installing-node
[sass]: http://sass-lang.com/

106
src/blankslate/README.md
View File

@ -1,20 +1,9 @@
# Primer Blankslate
[![npm version](https://img.shields.io/npm/v/primer-blankslate.svg)](https://www.npmjs.org/package/primer-blankslate)
[![Build Status](https://travis-ci.org/primer/css.svg?branch=master)](https://travis-ci.org/primer/primer)
> 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.
This repository is a module of the full [primer][primer] repository.
## Install
This repository is distributed with [npm][npm]. After [installing npm][install-npm], you can install `primer-blankslate` with this command.
```
$ npm install --save primer-blankslate
```
## Usage
The source files included are written in [Sass][sass] (`scss`) You can simply point your sass `include-path` at your `node_modules` directory and import it like this.
@ -35,105 +24,14 @@ $ npm run build
## Documentation
<!-- %docs
title: Blankslate
path: components/blankslate
status: Stable
-->
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.
#### Basic example
Wrap some content in the outer `.blankslate` wrapper to give it the blankslate appearance.
```html
<div class="blankslate">
<h3>This is a blank slate</h3>
<p>Use it to provide information when no dynamic content exists.</p>
</div>
```
#### With Octicons
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.
```erb
<div class="blankslate">
<%= octicon "git-commit", :height => 32, :class => "blankslate-icon" %>
<%= octicon "tag", :height => 32, :class => "blankslate-icon" %>
<%= octicon "git-branch", :height => 32, :class => "blankslate-icon" %>
<h3>This is a blank slate</h3>
<p>Use it to provide information when no dynamic content exists.</p>
</div>
```
#### Variations
Add an additional optional class to the `.blankslate` to change its appearance.
##### Narrow
Narrows the blankslate container to not occupy the entire available width.
```html
<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>
```
##### Capped
Removes the `border-radius` on the top corners.
```html
<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>
```
##### Spacious
Significantly increases the vertical padding.
```html
<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>
```
##### Large
Increases the size of the text in the blankslate
```html
<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>
```
##### No background
Removes the `background-color` and `border`.
```html
<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>
```
<!-- %enddocs -->
Find further documentation at [primer.style/css/components/blankslate](https://primer.style/css/components/blankslate).
## License
[MIT](./LICENSE) &copy; [GitHub](https://github.com/)
[primer]: https://github.com/primer/css
[docs]: http://primer.github.io/
[docs]: https://primer.style/css
[npm]: https://www.npmjs.com/
[install-npm]: https://docs.npmjs.com/getting-started/installing-node
[sass]: http://sass-lang.com/

565
src/box/README.md
View File

@ -1,20 +1,9 @@
# Primer box
[![npm version](https://img.shields.io/npm/v/primer-box.svg)](https://www.npmjs.org/package/primer-box)
[![Build Status](https://travis-ci.org/primer/css.svg?branch=master)](https://travis-ci.org/primer/primer)
> Box is a module for creating rounded-corner boxes with a white background and gray borders. Box has optional element styles for headers, lists, and footers.
This repository is a module of the full [primer][primer] repository.
## Install
This repository is distributed with [npm][npm]. After [installing npm][install-npm], you can install `primer-box` with this command.
```
$ npm install --save primer-box
```
## Usage
The source files included are written in [Sass][sass] (`scss`) You can simply point your sass `include-path` at your `node_modules` directory and import it like this.
@ -35,564 +24,14 @@ $ npm run build
## Documentation
<!-- %docs
title: Box
path: components/box
status_issue: https://github.com/github/design-systems/issues/198
status: Stable
-->
The `.Box` component can be used for something as simple as a rounded corner box, or more complex lists and forms. It includes optional modifiers for padding density and color themes.
{:toc}
## Box
A `.Box` is a container with a a white background, a light gray border, and rounded corners. By default there are no additional styles such as padding, these can be added as needed with utility classes. Other styles and layouts can be achieved with box elements and modifiers shown in the documentation below.
```html
<div class="Box">
This is a box.
</div>
```
## Box elements
Box elements include `Box-header`, `Box-body`, and `Box-footer`. These elements include borders and consistent padding. Optionally, you can include use `Box-title` which applies a bold font-weight the heading.
```html
<div class="Box">
<div class="Box-header">
<h3 class="Box-title">
Box title
</h3>
</div>
<div class="Box-body">
Box body
</div>
<div class="Box-footer">
Box footer
</div>
</div>
```
### Box row
Use `Box-row` to add rows with borders and maintain the same padding. Box rows have a lighter border to give contrast between the header and footer.
**Note:** Box rows have some reliance on markup structure in order to target the first and last rows, therefore using an unordered list is recommended. See [box row markup structure](#box-row-markup-structure) for more information.
```html
<div class="Box">
<ul>
<li class="Box-row">
Box row one
</li>
<li class="Box-row">
Box row two
</li>
<li class="Box-row">
Box row three
</li>
<li class="Box-row">
Box row four
</li>
</ul>
</div>
```
Rows can be used with or without `Box-header`, `Box-footer`, or `Box-body`.
```html
<div class="Box">
<div class="Box-header">
Box header
</div>
<div class="Box-body">
<strong>Box body</strong>
</div>
<ul>
<li class="Box-row">
Box row one
</li>
<li class="Box-row">
Box row two
</li>
<li class="Box-row">
Box row three
</li>
<li class="Box-row">
Box row four
</li>
</ul>
<div class="Box-footer">
Box footer
</div>
</div>
```
### Box row markup structure
Box rows have some reliance on markup structure in order to target the first and last rows. Box rows are given a top border that is lighter in color than other box elements so the first row is targeted to apply a darker border color. An inner border-radius is applied to the first and last rows that that row corners don't poke outside the `Box`, this can be particularly noticeable when using a highlight on box rows.
Using an unordered list is recommended in order to target the first and last rows, however, if you need to use a `<div>` for your rows, you may want to place your rows inside a parent `<div>` so that the first and last rows are styled appropriately.
```html
<div class="Box">
<div class="Box-header">
Box header
</div>
<!-- This wrapping div ensures the first and last rows can be targeted for styling. -->
<div>
<div class="Box-row">Box row using a div</div>
<div class="Box-row">Box row using a div</div>
</div>
</div>
```
## Box padding density
You can changed the padding density of the box component.
Use `Box--condensed` to apply a more condensed line-height and reduce the padding on the Y axis.
```html
<div class="Box Box--condensed">
<div class="Box-header">
<h3 class="Box-title">
Box title
</h3>
</div>
<div class="Box-body">
Box body
</div>
<ul>
<li class="Box-row">
Box row one
</li>
<li class="Box-row">
Box row two
</li>
</ul>
<div class="Box-footer">
Box footer
</div>
</div>
```
Use `Box--spacious` to increase padding and increase the title font size.
You may want to increase the overall font size to work with the larger padding, in this example the default body font size is increased to 16px using the `f4` typography utility.
```html
<div class="Box Box--spacious f4">
<div class="Box-header">
<h3 class="Box-title">
Box title
</h3>
</div>
<div class="Box-body">
Box body
</div>
<ul>
<li class="Box-row">
Box row one
</li>
<li class="Box-row">
Box row two
</li>
</ul>
<div class="Box-footer">
Box footer
</div>
</div>
```
## Blue box theme
Use `Box--blue` to style the box borders and box header in blue.
```html
<div class="Box Box--blue">
<div class="Box-header">
Box header
</div>
<ul>
<li class="Box-row">
Box row one
</li>
<li class="Box-row">
Box row two
</li>
</ul>
<div class="Box-footer">
Box footer
</div>
</div>
```
## Blue box header theme
Use `Box-header--blue` to add to change the header border and background to blue.
```html
<div class="Box">
<div class="Box-header Box-header--blue">
<h3 class="Box-title">Box with blue header</h3>
</div>
<div class="Box-body">
Box body
</div>
</div>
```
## Box danger theme
Use `Box--danger` to apply a red border to the outside of the box. This theme is helpful for communicating destructive actions.
**Note:** `Box-danger` only works with either `Box-row`'s or `Box-body`.
```html
<div class="Box Box--danger">
<div class="Box-row">
Row one
</div>
<div class="Box-row">
Row two
</div>
</div>
```
`Box-danger` is often paired with a red heading. See the [subhead](./subhead) docs for more information.
```html
<div class="Subhead border-bottom-0">
<h2 class="Subhead-heading Subhead-heading--danger">Danger zone</h2>
</div>
<div class="Box Box--danger">
<div class="Box-body">
Box body
</div>
</div>
```
## Row themes
You can change the background color for individual rows, or change the color on hover or navigation focus.
```html
<div class="Box">
<div class="Box-row Box-row--gray">
.Box-row--gray
</div>
<div class="Box-row Box-row--hover-gray">
.Box-row--hover-gray
</div>
<div class="Box-row Box-row--yellow">
.Box-row--yellow
</div>
<div class="Box-row Box-row--hover-blue">
.Box-row--hover-blue
</div>
<div class="Box-row Box-row--blue">
.Box-row--blue
</div>
</div>
```
Use `Box-row--focus-gray` or `Box-row--focus-blue` when using along-side `navigation-focus` if you want to highlight rows when using keyboard commands.
```html
<div class="Box">
<div class="Box-row Box-row--focus-gray navigation-focus">
.Box-row--focus-gray and .navigation-focus
</div>
<div class="Box-row Box-row--focus-gray">
.Box-row--focus-gray
</div>
<div class="Box-row Box-row--focus-blue navigation-focus">
.Box-row--focus-blue and .navigation-focus
</div>
<div class="Box-row Box-row--focus-blue">
.Box-row--focus-blue
</div>
</div>
```
### Box row unread
Use `.Box-row-unread` to apply a blue vertical line highlight for indicating a row contains unread items.
```html
<div class="Box">
<div class="Box-row">
Box row
</div>
<div class="Box-row Box-row--unread">
Box row unread
</div>
<div class="Box-row">
Box row
</div>
</div>
```
### Box row link
Use .`Box-row-link` when you want a link to appear dark gray and blue on hover on desktop, and remain a blue link on mobile. This is useful to indicate links on mobile without having hover styles.
```html
<div class="Box">
<div class="Box-row">
<a class="Box-row-link" href="#box-row-link">Box row link</a>
</div>
</div>
```
## Dashed border
Use the `border-dashed` utility to apply a dashed border to a box.
```html
<div class="Box border-dashed p-2">
A box with a dashed border
</div>
```
## Boxes with flash alerts
Use `flash-full` for flash alert inside a box to remove the rounded corners. Place the flash alert above the `Box-body` and underneath the `Box-header`.
Flash alerts come in three different colors and can be used with icons and buttons, see the [alert documentation](./alerts) for more information.
```erb
<div class="Box">
<div class="Box-header">
Box header
</div>
<div class="flash flash-full">
<button class="flash-close js-flash-close"><%= octicon "x" %></button>
Flash message with close button.
</div>
<div class="flash flash-full flash-success">
<%= octicon("check") %> Flash success with an icon.
</div>
<div class="flash flash-full flash-warn">
<%= octicon("alert") %> Flash warning with an icon.
</div>
<div class="flash flash-full flash-error">
Flash error inside a Box.
</div>
<div class="Box-body">
Box body
</div>
</div>
```
## Boxes with icons
Use `Box-btn-octicon` with `btn-octicon` when you want the icon to maintain the same padding as other box elements. This selector offsets margin to ensure it lines up on the left and right sides of the box so you may need to add padding neighboring elements.
```erb
<div class="Box">
<div class="Box-body">
<span class="pr-2">Box body</span>
<button href="#" class="Box-btn-octicon btn-octicon"><%= octicon "pencil" %></button>
</div>
</div>
```
It's common to want to float icons to the far left or right and stop the `Box-title`from wrapping underneath. To do this you'll need to create a media object with utilities. Add `clearfix` to the surrounding div (this could be the header, body, or rows), add `overflow-hidden` to the title (or other text element), and float the icons as desired.
```erb
<div class="Box">
<div class="Box-header clearfix">
<button href="#" class="Box-btn-octicon btn-octicon float-right"><%= octicon "x" %></button>
<h3 class="Box-title overflow-hidden pr-3">A very long title that wraps onto multiple lines without overlapping or wrapping underneath the icon to it's right</h3>
</div>
<div class="Box-body">
Box body
</div>
</div>
```
```erb
<div class="Box">
<div class="Box-row clearfix">
<button href="#" class="Box-btn-octicon btn-octicon float-left"><%= octicon "check" %></button>
<p class="overflow-hidden pl-3">A very long paragraph that wraps onto multiple lines without overlapping or wrapping underneath the icon to it's left</p>
</div>
</div>
```
## Box headers with counters
Use a counter with a background that works against the contrast of the box header. The default counter colors do not stand out well against the header background so we suggest using one of the following styles:
Use `Counter--gray` for a counter with a gray background and dark gray text.
```html
<div class="Box">
<div class="Box-header">
<h3 class="Box-title">
Box title
<span class="Counter Counter--gray">12</span>
</h3>
</div>
<div class="Box-body">
Box body
</div>
</div>
```
Use `Counter--gray-dark` for a counter with a dark gray background and white text.
```html
<div class="Box">
<div class="Box-header">
<h3 class="Box-title">
Box title
<span class="Counter Counter--gray-dark">12</span>
</h3>
</div>
<div class="Box-body">
Box body
</div>
</div>
```
## Form elements and buttons in boxes
To achieve different layouts when adding buttons or form elements to boxes we suggest you use utilities to achieve the layout you want. Here's some common examples:
Use [flexbox utilities](/css/utilities/flexbox) to center align items, and avoid using floats by using `flex-auto` to have the text fill the remaining space so that the button rests on the far right.
```html
<div class="Box Box--condensed">
<div class="Box-header d-flex flex-items-center">
<h3 class="Box-title overflow-hidden flex-auto">
Box title
</h3>
<button class="btn btn-primary btn-sm">
Button
</button>
</div>
<div class="Box-body">
Box body
</div>
</div>
```
A similar approach can be used for buttons with multiple lines of text within a row.
```html
<div class="Box">
<div class="Box-row d-flex flex-items-center">
<div class="flex-auto">
<strong>Row title</strong>
<div class="text-small text-gray-light">
Description
</div>
</div>
<button type="button" class="btn btn-primary" name="button">View</button>
</div>
<div class="Box-row d-flex flex-items-center">
<div class="flex-auto">
<strong>Row title</strong>
<div class="text-small text-gray-light">
Description
</div>
</div>
<button type="button" class="btn btn-primary" name="button">View</button>
</div>
<div class="Box-row d-flex flex-items-center">
<div class="flex-auto">
<strong>Row title</strong>
<div class="text-small text-gray-light">
Description
</div>
</div>
<button type="button" class="btn btn-primary" name="button">View</button>
</div>
</div>
```
Using flexbox along with form, button, and link styles, you can create more complex box headers for things like bulk actions and sorting.
```html
<div class="Box">
<div class="Box-header d-flex flex-items-center">
<form class="flex-auto">
<label>
<input class="mr-1" type="checkbox">
Check it
</label>
</form>
<button class="btn-link select-menu-button muted-link">
Select menu
</button>
</div>
<div class="Box-body">
Box body
</div>
</div>
```
You can put forms in boxes. Often form submission buttons are aligned to the bottom right of the form which you can do with `text-right` instead of using floats.
```html
<div class="Box">
<div class="Box-header">
<h3 class="Box-title">
Example form title
</h3>
</div>
<form>
<div class="Box-body">
<dl class="form-group">
<dt><label>Example label</label></dt>
<dd><input class="form-control" type="text"></dd>
</dl>
<div class="form-checkbox">
<label>
<input type="checkbox" checked="checked">
Yes please
</label>
</div>
</div>
<div class="Box-footer text-right">
<button class="btn btn-secondary mr-1">
Cancel
</button>
<button class="btn btn-primary">
Submit
</button>
</div>
</form>
</div>
```
When a box is all by itself centered on a page you can use [column widths](/css/objects/grid) to control the width of the box. If needed, break the mold a little and use [typography utilities](/css/utilities/typography) instead of the built in box title styles.
```html
<div class="Box Box--spacious col-6 mx-auto text-center">
<form>
<div class="Box-body">
<h3 class="f1-light">
Example form
</h3>
<dl class="form-group mb-4">
<dt><label>Example label</label></dt>
<dd><input class="form-control" type="text"></dd>
</dl>
<button class="btn btn-primary btn-block">
Submit
</button>
</div>
</form>
</div>
```
Box patterns can also be made with, and modified with [border utilities](/css/utilities/borders).
<!-- %enddocs -->
Find further documentation at [primer.style/css/components/box](https://primer.style/css/components/box).
## License
[MIT](./LICENSE) &copy; [GitHub](https://github.com/)
[primer]: https://github.com/primer/css
[docs]: http://primer.github.io/
[docs]: https://primer.style/css
[npm]: https://www.npmjs.com/
[install-npm]: https://docs.npmjs.com/getting-started/installing-node
[sass]: http://sass-lang.com/

40
src/branch-name/README.md
View File

@ -1,20 +1,9 @@
# Primer / Branch Name
[![npm version](https://img.shields.io/npm/v/primer-branch-name.svg)](https://www.npmjs.org/package/primer-branch-name)
[![Build Status](https://travis-ci.org/primer/css.svg?branch=master)](https://travis-ci.org/primer/primer)
> A nice, consistent way to display branch names.
This repository is a module of the full [primer][primer] repository.
## Install
This repository is distributed with [npm]. After [installing npm][install-npm], you can install `primer-branch-name` with this command.
```
$ npm install --save primer-branch-name
```
## Usage
The source files included are written in [Sass][sass] (SCSS) You can simply point your sass `include-path` at your `node_modules` directory and import it like this.
@ -35,39 +24,14 @@ $ npm run build
## Documentation
<!-- %docs
title: Branch name
path: components/branch-name
status: Stable
-->
Branch names can be a link name or not:
```html title="Branch name"
<span class="branch-name">a_new_feature_branch</span>
```
```html title="Branch name with link"
<a href="#url" class="branch-name">a_new_feature_branch</a>
```
You may also include an octicon before the branch name text:
```erb title="Branch name with icon"
<span class="branch-name">
<%= octicon("git-branch", width:16, height:16) %>
a_new_feature_branch
</span>
```
<!-- %enddocs -->
Find further documentation at [primer.style/css/components/branch-name](https://primer.style/css/components/branch-name).
## License
[MIT](./LICENSE) &copy; [GitHub](https://github.com/)
[primer]: https://github.com/primer/css
[docs]: http://primer.github.io/
[docs]: https://primer.style/css
[npm]: https://www.npmjs.com/
[install-npm]: https://docs.npmjs.com/getting-started/installing-node
[sass]: http://sass-lang.com/

31
src/breadcrumb/README.md
View File

@ -1,39 +1,12 @@
# Primer Breadcrumb Navigation
[![npm version](https://img.shields.io/npm/v/primer-breadcrumb.svg)](https://www.npmjs.org/package/primer-breadcrumb)
[![Build Status](https://travis-ci.org/primer/css.svg?branch=master)](https://travis-ci.org/primer/primer)
> Breadcrumb navigation for GitHub's pages with parents / grandparents.
This repository is a module of the full [primer][primer] repository.
## Documentation
<!-- %docs
title: Breadcrumbs
path: components/breadcrumb
status: Stable
-->
Breadcrumbs are used to show taxonomical context on pages that are many levels deep in a site’s hierarchy. Breadcrumbs show and link to parent, grandparent, and sometimes great-grandparent pages. Breadcrumbs are most appropriate on pages that:
- Are many levels deep on a site
- Do not have a section-level navigation
- May need the ability to quickly go back to the previous (parent) page
#### Usage
```html title="Breadcrumb"
<nav aria-label="Breadcrumb">
<ol>
<li class="breadcrumb-item text-small"><a href="https://github.com/business">Business</a></li>
<li class="breadcrumb-item text-small"><a href="https://github.com/business/customers">Customers</a></li>
<li class="breadcrumb-item breadcrumb-item-selected text-small text-gray" aria-current="page">MailChimp</li>
</ol>
</nav>
```
<!-- %enddocs -->
Find further documentation at [primer.style/css/components/breadcrumb](https://primer.style/css/components/breadcrumb).
## License
@ -42,7 +15,7 @@ MIT &copy; [GitHub](https://github.com/)
[primer]: https://github.com/primer/css
[primer-support]: https://github.com/primer/css-support
[support]: https://github.com/primer/css-support
[docs]: http://primer.github.io/
[docs]: https://primer.style/css
[npm]: https://www.npmjs.com/
[install-npm]: https://docs.npmjs.com/getting-started/installing-node
[sass]: http://sass-lang.com/

245
src/buttons/README.md
View File

@ -1,20 +1,9 @@
# Primer Buttons
[![npm version](https://img.shields.io/npm/v/primer-buttons.svg)](https://www.npmjs.org/package/primer-buttons)
[![Build Status](https://travis-ci.org/primer/css.svg?branch=master)](https://travis-ci.org/primer/primer)
> Buttons are used for actions, like in forms, while textual hyperlinks are used for destinations, or moving from one page to another.
This repository is a module of the full [primer][primer] repository.
## Install
This repository is distributed with [npm][npm]. After [installing npm][install-npm], you can install `primer-buttons` with this command.
```
$ npm install --save primer-buttons
```
## Usage
The source files included are written in [Sass][sass] (`scss`) You can simply point your sass `include-path` at your `node_modules` directory and import it like this.
@ -35,244 +24,14 @@ $ npm run build
## Documentation
<!-- %docs
title: Buttons
path: components/buttons
status: Stable
-->
Buttons are used for **actions**, like in forms, while textual hyperlinks are used for **destinations**, or moving from one page to another.
{:toc}
## Default button
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**.
```html
<button class="btn" type="button">Button button</button>
<a class="btn" href="#url" role="button">Link button</a>
```
You can find them in two sizes: the default `.btn` and the smaller `.btn-sm`.
```html
<button class="btn" type="button">Button</button>
<button class="btn btn-sm" type="button">Small button</button>
```
## Primary 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`.
```html
<button class="btn btn-primary" type="button">Primary button</button>
<button class="btn btn-sm btn-primary" type="button">Small primary button</button>
```
## Danger 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`.
```html
<button class="btn btn-danger" type="button">Danger button</button>
<button class="btn btn-sm btn-danger" type="button">Small danger button</button>
```
## Outline button
Outline buttons downplay an action as they appear like boxy links. Just add `.btn-outline` and go.
```html
<button class="btn btn-outline" type="button">Outline button</button>
<button class="btn btn-sm btn-outline" type="button">Outline button</button>
```
## Large button
Use `.btn-large` to increase the padding and border radius of a button. This is useful for prominent calls to action in hero sections.
[Type scale utilities](https://styleguide.github.com/primer/utilities/typography/#type-scale-utilities) can be used to alter the font-size if needed. Padding is applied in em's so that it scales proportionally with the font-size.
```html
<p>
<a class="btn btn-large btn-purple" href="#url" role="button">Large link button</a>
<button class="btn btn-large" type="button">Large button button</button>
</p>
```
Use `.btn-large` with a type scale utility to transform the text to a bigger size.
```html
<p class="f3">
<a class="btn btn-large btn-purple" href="#url" role="button">Large link button</a>
<button class="btn btn-large btn-outline-blue" type="button">Large button button</button>
</p>
```
## Disabled state
Disable `<button>` elements with the boolean `disabled` attribute and `<a>` elements with the `.disabled` class.
```html
<button class="btn" type="button" disabled>Disabled button</button>
<a class="btn disabled" href="#url" role="button">Disabled button</a>
```
Similar styles are applied to primary, danger, and outline buttons:
```html
<button class="btn btn-primary" type="button" disabled>Disabled button</button>
<a class="btn btn-primary disabled" href="#url" role="button">Disabled button</a>
```
```html
<button class="btn btn-danger" type="button" disabled>Disabled button</button>
<a class="btn btn-danger disabled" href="#url" role="button">Disabled button</a>
```
```html
<button class="btn btn-outline" type="button" disabled>Disabled button</button>
<a class="btn btn-outline disabled" href="#url" role="button">Disabled button</a>
```
## Block button
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.
```html
<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>
```
## Link button
Create a button that looks like a link with `.btn-link`. Rather than using an `<a>` to trigger JS, this style on a `<button>` should be used for better accessibility.
**The `.btn-link` class is not designed to be used with `.btn`; the overlapping styles are not compatible.**
```html
<p><button class="btn-link" type="button">Link button</button></p>
```
## Button with counts
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.**
```erb
<div class="clearfix">
<a class="btn btn-sm btn-with-count" href="#url" role="button">
<%= octicon "eye" %>
Watch
</a>
<a class="social-count" href="#url">6</a>
</div>
```
You can also use the [counter](./labels#counters) component within buttons:
```html
<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>
```
## Button groups
Have a hankering for a series of buttons that are attached to one another? Wrap them in a `.BtnGroup` and the buttons will be rounded and spaced automatically.
```html
<div class="BtnGroup mr-2">
<button class="btn BtnGroup-item" type="button">Button</button>
<button class="btn BtnGroup-item" type="button">Button</button>
<button class="btn BtnGroup-item" type="button">Button</button>
</div>
<div class="BtnGroup mr-2">
<button class="btn BtnGroup-item btn-outline" type="button">Button</button>
<button class="btn BtnGroup-item btn-outline" type="button">Button</button>
<button class="btn BtnGroup-item btn-outline" type="button">Button</button>
</div>
<div class="BtnGroup">
<button class="btn BtnGroup-item btn-sm" type="button">Button</button>
<button class="btn BtnGroup-item btn-sm" type="button">Button</button>
<button class="btn BtnGroup-item btn-sm" type="button">Button</button>
</div>
```
Add `.BtnGroup-parent` to parent elements, like `<form>`s or `<details>`s, within `.BtnGroup`s for proper spacing and rounded corners.
```html
<div class="BtnGroup">
<button class="btn BtnGroup-item" type="button">Button</button>
<form class="BtnGroup-parent">
<button class="btn BtnGroup-item" type="button">Button in a form</button>
</form>
<button class="btn BtnGroup-item" type="button">Button</button>
<button class="btn BtnGroup-item" type="button">Button</button>
</div>
```
## Hidden text button
Use `.hidden-text-expander` to indicate and toggle hidden text.
```html
<span class="hidden-text-expander">
<button type="button" class="ellipsis-expander" aria-expanded="false">&hellip;</button>
</span>
```
You can also make the expander appear inline by adding `.inline`.
## Using button styles with the details summary element
You can add `.btn` and `.btn-*` classes to any
[`<summary>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary)
element so that it gains the appearance of a button, and
selected/active styles when the parent
[`<details>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details)
element is open.
```html
<details>
<summary class="btn btn-block btn-primary">Toggle the content</summary>
<p class="mt-2">
This content will be toggled.
</p>
</details>
```
<!-- %enddocs -->
Find further documentation at [primer.style/css/components/buttons](https://primer.style/css/components/buttons).
## License
[MIT](./LICENSE) &copy; [GitHub](https://github.com/)
[primer]: https://github.com/primer/css
[docs]: http://primer.github.io/
[docs]: https://primer.style/css
[npm]: https://www.npmjs.com/
[install-npm]: https://docs.npmjs.com/getting-started/installing-node
[sass]: http://sass-lang.com/

13
src/core/README.md
View File

@ -1,20 +1,9 @@
# Primer Core
[![npm version](https://img.shields.io/npm/v/primer-core.svg)](https://www.npmjs.org/package/primer-core)
[![Build Status](https://travis-ci.org/primer/css.svg?branch=master)](https://travis-ci.org/primer/primer)
> Primer core is one of 3 meta-packages that belong to the Primer framework. Primer core contains packages that are shared between GitHub product and marketing websites.
This repository is a compilation of [several CSS packages](https://github.com/primer/css). You can break it down into smaller sections using npm.
## Install
This repository is distributed with [npm][npm]. After [installing npm][install-npm], you can install `primer` with this command. **You must have npm >=3.0 installed to be able to satisfy the dependency paths**
```
$ npm install --save primer-core
```
## Usage
The source files included are written in [Sass][sass] (`scss`) You can simply point your sass `include-path` at your `node_modules` directory and import it like this.
@ -42,7 +31,7 @@ You can read more about primer in the [docs][docs].
[MIT](./LICENSE) &copy; [GitHub](https://github.com/)
[primer]: https://github.com/primer/css
[docs]: http://primer.github.io/
[docs]: https://primer.style/css
[npm]: https://www.npmjs.com/
[install-npm]: https://docs.npmjs.com/getting-started/installing-node
[sass]: http://sass-lang.com/

318
src/forms/README.md
View File

@ -1,20 +1,9 @@
# Primer Forms
[![npm version](https://img.shields.io/npm/v/primer-forms.svg)](https://www.npmjs.org/package/primer-forms)
[![Build Status](https://travis-ci.org/primer/css.svg?branch=master)](https://travis-ci.org/primer/primer)
> Style individual form controls and utilize common layouts.
This repository is a module of the full [primer][primer] repository.
## Install
This repository is distributed with [npm][npm]. After [installing npm][install-npm], you can install `primer-forms` with this command.
```
$ npm install --save primer-forms
```
## Usage
The source files included are written in [Sass][sass] (`scss`) You can simply point your sass `include-path` at your `node_modules` directory and import it like this.
@ -35,317 +24,14 @@ $ npm run build
## Documentation
<!-- %docs
title: Forms
path: components/forms
status: Stable
-->
Style individual form controls and utilize common layouts.
{:toc}
Overview:
- We reset several elements' default styles for cross browser consistency and easier manipulation later. This includes `<fieldset>`s, WebKit validation bubbles, and most textual `<input>`s.
- Specific types of textual `<input>`s are styled automatically, but `.form-control` is available should you need it.
- Always declare a `type` on your `<button>`s.
- Form layouts rely on form groups.
#### Kitchen sink
All our inputs and buttons side-by-side for easy testing of sizing and alignment with one another.
```html
<p>
<button class="btn" type="button">Button</button>
<button class="btn select-menu-button" type="button" aria-expanded="false" aria-haspopup="true">
Select menu
</button>
<input class="form-control" type="text" placeholder="Standard input" aria-label="Repository description">
<input class="form-control input-monospace" type="text" placeholder="Monospace input" aria-label="SHA">
<select class="form-select" aria-label="Important decision">
<option>Select</option>
<option value="option 2">Option 2</option>
</select>
</p>
<p>
<button class="btn btn-sm" type="button">Small button</button>
<button class="btn btn-sm select-menu-button" type="button" aria-expanded="false" aria-haspopup="true">
Select menu
</button>
<input class="form-control input-sm" type="text" placeholder="Small input" aria-label="Repository description">
<select class="form-select select-sm" aria-label="Important decision">
<option>Select</option>
<option value="option 1">Option 1</option>
</select>
</p>
```
#### Example form
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.
```html
<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>
```
#### Form contrast
Textual form controls have a white background by default. You can change this to a light gray with `.input-contrast`.
```html
<form>
<input class="form-control" type="text" placeholder="Default input" aria-label="Default input">
<input class="form-control input-contrast" type="text" placeholder="Input with contrast" aria-label="Input with contrast">
</form>
```
#### Sizing
Make inputs smaller, larger, or full-width with an additional class.
##### Small
```html
<form>
<input class="form-control input-sm" type="text" placeholder="Small input" aria-label="Small input">
</form>
```
##### Large
```html
<form>
<input class="form-control input-lg" type="text" placeholder="Large input" aria-label="Large input">
</form>
```
##### Block
```html
<form>
<input class="form-control input-block" type="text" placeholder="Full-width input" aria-label="Full-width input">
</form>
```
##### Hide webkit's contact info autofill icon
Webkit sometimes gets confused and tries to add an icon/dropdown to autofill contact information on fields that may not be appropriate (such as input for number of users). Use this class to override the display of this icon.
```html
<form>
<input class="form-control input-hide-webkit-autofill" placeholder="Hide Webkit's contact autofill on this input" type="text" aria-label="Hide Webkit's contact autofill on this input">
</form>
```
#### Selects
Primer adds light `height` and `vertical-align` styles to `<select>`s for all browsers to render them consistently with textual inputs.
```html
<form>
<select class="form-select" aria-label="Preference">
<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>
```
##### Small
Use the `.select-sm` class to resize both default and custom `<select>`s to match the size of [our small buttons](./buttons#default-buttons).
```html
<select class="form-select select-sm" aria-label="Preference">
<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" aria-label="Preference">
<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 groups
```html
<form>
<dl class="form-group">
<dt><label for="example-text">Example Text</label></dt>
<dd><input class="form-control" type="text" value="Example Value" id="example-text"></dd>
</dl>
<dl class="form-group">
<dt><label for="example-select">Example Select</label></dt>
<dd>
<select class="form-select" id="example-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 for="example-textarea">Example Textarea</label></dt>
<dd>
<textarea class="form-control" id="example-textarea"></textarea>
</dd>
</dl>
</form>
```
#### Form group validation
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`.
```html
<form>
<dl class="form-group errored">
<dt><label for="example-text-errored">Example Text</label></dt>
<dd><input class="form-control" type="text" value="Example Value" id="example-text-errored" aria-describedby="form-error-text"></dd>
<dd class="error" id="form-error-text">This example input has an error.</dd>
</dl>
<br>
<dl class="form-group warn">
<dt><label for="example-text-warn">Example Text</label></dt>
<dd><input class="form-control" type="text" value="Example Value" id="example-text-warn" aria-describedby="form-warning-text"></dd>
<dd class="warning" id="form-warning-text">This example input has a warning.</dd>
</dl>
</form>
```
#### Checkboxes and radios
Utilities to spice up the alignment and styling of checkbox and radio controls.
```html
<form>
<div class="form-checkbox">
<label>
<input type="checkbox" checked="checked" aria-describedby="help-text-for-checkbox">
Available for hire
</label>
<p class="note" id="help-text-for-checkbox">
This will do insanely <strong>awesome</strong> and <strong>amazing</strong> things!
</p>
</div>
</form>
```
You may also add emphasis to the label:
```html
<form>
<div class="form-checkbox">
<label>
<input type="checkbox" checked="checked">
<em class="highlight">Available for hire</em>
</label>
</div>
</form>
```
##### Show / hide content based on a checkbox or radio button state
Content that is hidden by default should only be done so if it is non-essential for the context of the surrounding content. Be sure to use the `aria-live="polite"` attribute on the parent label for added content to be announced when displayed.
```html
<form>
<div class="form-checkbox">
<label>
<input type="radio" name="hireme">
Not available for hire
</label>
</div>
<div class="form-checkbox">
<label aria-live="polite">
<input type="radio" class="form-checkbox-details-trigger" name="hireme">
Available for hire
<span class="form-checkbox-details text-normal">
<span class="d-block mb-1">Available hours per week</span>
<input type="text" name="" class="form-control input-contrast" size="3">
<span class="text-small text-gray pl-2">hours per week</span>
</span>
</label>
</div>
</form>
```
#### Input group
Attached an input and button to one another.
```erb
<form>
<div class="input-group">
<input class="form-control" type="text" placeholder="Username" aria-label="Username">
<span class="input-group-button">
<button class="btn" type="button" aria-label="Copy to clipboard">
<%= octicon "clippy" %>
</button>
</span>
</div>
</form>
```
#### Form actions
Align buttons to the right—via `float: right` on the buttons—in forms with `.form-actions`. The floats are automatically cleared for you.
```html
<div class="form-actions">
<button type="submit" class="btn btn-primary">Save changes</button>
<button type="button" class="btn">Cancel</button>
</div>
```
<!-- %enddocs -->
Find further documentation at [primer.style/css/components/forms](https://primer.style/css/components/forms).
## License
[MIT](./LICENSE) &copy; [GitHub](https://github.com/)
[primer]: https://github.com/primer/css
[docs]: http://primer.github.io/
[docs]: https://primer.style/css
[npm]: https://www.npmjs.com/
[install-npm]: https://docs.npmjs.com/getting-started/installing-node
[sass]: http://sass-lang.com/

154
src/labels/README.md
View File

@ -1,20 +1,9 @@
# Primer Labels
[![npm version](https://img.shields.io/npm/v/primer-labels.svg)](https://www.npmjs.org/package/primer-labels)
[![Build Status](https://travis-ci.org/primer/css.svg?branch=master)](https://travis-ci.org/primer/primer)
> Labels add metadata or indicate status of items and navigational elements.
This repository is a module of the full [primer][primer] repository.
## Install
This repository is distributed with [npm][npm]. After [installing npm][install-npm], you can install `primer-labels` with this command.
```
$ npm install --save primer-labels
```
## Usage
The source files included are written in [Sass][sass] (`scss`) You can simply point your sass `include-path` at your `node_modules` directory and import it like this.
@ -35,153 +24,14 @@ $ npm run build
## Documentation
<!-- %docs
title: Labels
path: components/labels
status_issue: https://github.com/github/design-systems/issues/332
status: Stable
-->
Labels add metatdata or indicate status of items and navigational elements. Three different types of labels are available: [Labels](#default-label-styles) for adding metadata, [States](#states) for indicating status, and [Counters](#counters) for showing the count for a number of items.
{:toc}
## Labels
The base label component styles the text, adds padding and rounded corners, and an inset box shadow. Labels come in various themes which apply colors and different border styles.
GitHub also programmatically generates and applies a background color for labels on items such as issues and pull requests. Users are able to select any background color and the text color will adjust to work with light and dark background colors.
The base `Label` style does not apply a background color, here's an example using the `bg-blue` utility to apply a blue background:
```html title="Label"
<span title="Label: default label" class="Label bg-blue">default label</span>
```
**Note:** Be sure to include a title attribute on labels, it's helpful for people using screen-readers to differentiate a label from other text. I.e. without the title attribute, the following example would read as _"New select component design"_, rather than identifying `design` as a label.
```html title="Label without title"
<!-- Don't do this -->
<a href="#url">New select component</a><span class="Label bg-blue ml-1">design</span>
```
### Label themes
Labels come in a few different themes. Use a theme that helps communicate the content of the label, and ensure it's used consistently.
Use `Label--gray` to create a label with a light gray background and gray text. This label is neutral in color and can be used in contexts where all you need to communicate is metadata, or whe you want a label to feel less prominent compared with labels with stronger colors.
```html title="Label theme gray"
<span title="Label: gray label" class="Label Label--gray">gray label</span>
```
Use `Label--gray-darker` to create a label with a dark-gray background color. This label is also neutral in color, however, since it's background is darker it can stand out more compared to `Label--gray`.
```html title="Label theme dark gray"
<span title="Label: dark gray label" class="Label Label--gray-darker">dark gray label</span>
```
Use `Label--orange` to communicate "warning". The orange background color is very close to red, so avoid using next to labels with a red background color since most people will find it hard to tell the difference.
```html title="Label theme orange"
<span title="Label: orange label" class="Label Label--orange">orange label</span>
```
Use `Label--outline` to create a label with gray text, a gray border, and a transparent background. The outline reduces the contrast of this label in combination with filled labels. Use this in contexts where you need it to stand out less than other labels and communicate a neutral message.
```html title="Label outline"
<span title="Label: outline label" class="Label Label--outline">outlined label</span>
```
Use `Label--outline-green` in combination with `Label--outline` to communicate a positive message.
```html title="Label outline green"
<span title="Label: green outline label" class="Label Label--outline Label--outline-green">green outlined label</span>
```
## States
Use state labels to inform users of an items status. States are large labels with bolded text. The default state has a gray background.
```html title="State"
<span class="State">Default</span>
```
### State themes
States come in a few variations that apply different colors. Use the state that best communicates the status or function.
```erb title="State themes"
<span title="Status: open" class="State State--green"><%= octicon "git-pull-request" %> Open</span>
<span title="Status: closed" class="State State--red"><%= octicon "git-pull-request" %> Closed</span>
<span title="Status: merged" class="State State--purple"><%= octicon "git-merge" %> Merged</span>
```
**Note:** Similar to [labels](#labels), you should include the title attribute on states to differentiate them from other content.
### Small states
Use `State--small` for a state label with reduced padding a smaller font size. This is useful in denser areas of content.
```erb title="Small states"
<span title="Status: open" class="State State--green State--small"><%= octicon "issue-opened" %> Open</span>
<span title="Status: closed" class="State State--red State--small"><%= octicon "issue-closed" %> Closed</span>
```
## Counters
Use the `Counter` component to add a count to navigational elements and buttons. Counters come in 3 variations: the default `Counter` with a light gray background, `Counter--gray` with a dark-gray background and inverse white text, and `Counter--gray-light` with a light-gray background and dark gray text. When a counter is empty, it's visibility will be hidden.
```html title="Counter"
<span class="Counter">16</span>
<span class="Counter Counter--gray">32</span>
<span class="Counter Counter--gray-light">64</span>
```
Use the `Counter` in navigation to indicate the number of items without the user having to click through or count the items, such as open issues in a GitHub repo. See more options in [navigation](./navigation).
```html title="Counter in tabs"
<div class="tabnav">
<nav class="tabnav-tabs" aria-label="Foo bar">
<a href="#url" class="tabnav-tab selected" aria-current="page">Foo tab <span class="Counter">23</a>
<a href="#url" class="tabnav-tab">Bar tab</a>
</nav>
</div>
```
Counters can also be used in `Box` headers to indicate the number of items in a list. See more on the [box component](./box).
```html title="Counter in Box headers"
<div class="Box">
<div class="Box-header">
<h3 class="Box-title">
Box title
<span class="Counter Counter--gray">3</span>
</h3>
</div>
<ul>
<li class="Box-row">
Box row one
</li>
<li class="Box-row">
Box row two
</li>
<li class="Box-row">
Box row three
</li>
</ul>
</div>
```
<!-- %enddocs -->
Find further documentation at [primer.style/css/components/labels](https://primer.style/css/components/labels).
## License
[MIT](./LICENSE) &copy; [GitHub](https://github.com/)
[primer]: https://github.com/primer/css
[docs]: http://primer.github.io/
[docs]: https://primer.style/css
[npm]: https://www.npmjs.com/
[install-npm]: https://docs.npmjs.com/getting-started/installing-node
[sass]: http://sass-lang.com/

104
src/layout/README.md
View File

@ -1,20 +1,9 @@
# Primer Layout
[![npm version](https://img.shields.io/npm/v/primer-layout.svg)](https://www.npmjs.org/package/primer-layout)
[![Build Status](https://travis-ci.org/primer/css.svg?branch=master)](https://travis-ci.org/primer/primer)
> 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.
This repository is a module of the full [primer][primer] repository.
## Install
This repository is distributed with [npm][npm]. After [installing npm][install-npm], you can install `primer-layout` with this command.
```
$ npm install --save primer-layout
```
## Usage
The source files included are written in [Sass][sass] (`scss`) You can simply point your sass `include-path` at your `node_modules` directory and import it like this.
@ -35,103 +24,14 @@ $ npm run build
## Documentation
<!-- %docs
title: Layout
path: objects/layout
status: Deprecated
status_issue: https://github.com/github/design-systems/issues/59
-->
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`.
#### Container
Center your page's contents with a `.container`.
```html title="Container"
<div class="container border">
Container
</div>
```
The container applies `width: 980px;` and uses horizontal `margin`s to center it.
#### Grid
##### How it works
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:
- Add a `.container` to encapsulate everything and provide ample horizontal gutter space.
- Create your outer row to clear the floated columns with `<div class="columns">`.
- Add your columns with individual `<div class="column">`s.
- Add your fractional width classes to set the width of the columns (e.g., `.one-fourth`).
##### Demo
In practice, your columns will look like the example below.
```html title="Grid columns"
<div class="container">
<div class="columns mb-1">
<div class="one-fifth column block-blue p-3 border">
.one-fifth
</div>
<div class="four-fifths column block-blue p-3 border">
.four-fifths
</div>
</div>
<div class="columns mb-1">
<div class="one-fourth column block-blue p-3 border">
.one-fourth
</div>
<div class="three-fourths column block-blue p-3 border">
.three-fourths
</div>
</div>
<div class="columns mb-1">
<div class="one-third column block-blue p-3 border">
.one-third
</div>
<div class="two-thirds column block-blue p-3 border">
.two-thirds
</div>
</div>
<div class="columns">
<div class="one-half column block-blue p-3 border">
.one-half
</div>
<div class="one-half column block-blue p-3 border">
.one-half
</div>
</div>
</div>
```
##### Centered
Columns can be centered by adding `.centered` to the `.column` class.
```html title="Grid centered"
<div class="columns">
<div class="one-half column centered block-blue border p-3">
.one-half
</div>
</div>
```
<!-- %enddocs -->
Find further documentation at [primer.style/css/objects/layout](https://primer.style/css/objects/layout).
## License
[MIT](./LICENSE) &copy; [GitHub](https://github.com/)
[primer]: https://github.com/primer/css
[docs]: http://primer.github.io/
[docs]: https://primer.style/css
[npm]: https://www.npmjs.com/
[install-npm]: https://docs.npmjs.com/getting-started/installing-node
[sass]: http://sass-lang.com/

186
src/markdown/README.md
View File

@ -1,20 +1,9 @@
# Primer Markdown
[![npm version](https://img.shields.io/npm/v/primer-markdown.svg)](https://www.npmjs.org/package/primer-markdown)
[![Build Status](https://travis-ci.org/primer/css.svg?branch=master)](https://travis-ci.org/primer/primer)
> Stylesheets for rendering GitHub Flavored Markdown and syntax highlighted code snippets.
This repository is a module of the full [primer][primer] repository.
## Install
This repository is distributed with [npm][npm]. After [installing npm][install-npm], you can install `primer-markdown` with this command.
```
$ npm install --save primer-markdown
```
## Usage
The source files included are written in [Sass][sass] (`scss`) You can simply point your sass `include-path` at your `node_modules` directory and import it like this.
@ -35,185 +24,14 @@ $ npm run build
## Documentation
<!-- %docs
title: Markdown
path: components/markdown
status: Stable
-->
Text can be **bold**, _italic_, or ~~strikethrough~~. [Links](https://github.com) should be blue with no underlines (unless hovered over).
There should be whitespace between paragraphs. There should be whitespace between paragraphs. There should be whitespace between paragraphs. There should be whitespace between paragraphs.
There should be whitespace between paragraphs. There should be whitespace between paragraphs. There should be whitespace between paragraphs. There should be whitespace between paragraphs.
> There should be no margin above this first sentence.
>
> Blockquotes should be a lighter gray with a gray border along the left side.
>
> There should be no margin below this final sentence.
# Header 1
This is a normal paragraph following a header. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.
## Header 2
> This is a blockquote following a header. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.
### Header 3
```
This is a code block following a header.
```
#### Header 4
* This is an unordered list following a header.
* This is an unordered list following a header.
* This is an unordered list following a header.
##### Header 5
1. This is an ordered list following a header.
2. This is an ordered list following a header.
3. This is an ordered list following a header.
###### Header 6
| What | Follows |
|-----------|-----------------|
| A table | A header |
| A table | A header |
| A table | A header |
----------------
There's a horizontal rule above and below this.
----------------
Here is an unordered list:
* Salt-n-Pepa
* Bel Biv DeVoe
* Kid 'N Play
And an ordered list:
1. Michael Jackson
2. Michael Bolton
3. Michael Bublé
And an unordered task list:
- [x] Create a sample markdown document
- [x] Add task lists to it
- [ ] Take a vacation
And a "mixed" task list:
- [ ] Steal underpants
- ?
- [ ] Profit!
And a nested list:
* Jackson 5
* Michael
* Tito
* Jackie
* Marlon
* Jermaine
* TMNT
* Leonardo
* Michelangelo
* Donatello
* Raphael
Definition lists can be used with HTML syntax. Definition terms are bold and italic.
<dl>
<dt>Name</dt>
<dd>Godzilla</dd>
<dt>Born</dt>
<dd>1952</dd>
<dt>Birthplace</dt>
<dd>Japan</dd>
<dt>Color</dt>
<dd>Green</dd>
</dl>
----------------
Tables should have bold headings and alternating shaded rows.
| Artist | Album | Year |
|-------------------|-----------------|------|
| Michael Jackson | Thriller | 1982 |
| Prince | Purple Rain | 1984 |
| Beastie Boys | License to Ill | 1986 |
If a table is too wide, it should condense down and/or scroll horizontally.
| Artist | Album | Year | Label | Awards | Songs |
|-------------------|-----------------|------|-------------|----------|-----------|
| Michael Jackson | Thriller | 1982 | Epic Records | Grammy Award for Album of the Year, American Music Award for Favorite Pop/Rock Album, American Music Award for Favorite Soul/R&B Album, Brit Award for Best Selling Album, Grammy Award for Best Engineered Album, Non-Classical | Wanna Be Startin' Somethin', Baby Be Mine, The Girl Is Mine, Thriller, Beat It, Billie Jean, Human Nature, P.Y.T. (Pretty Young Thing), The Lady in My Life |
| Prince | Purple Rain | 1984 | Warner Brothers Records | Grammy Award for Best Score Soundtrack for Visual Media, American Music Award for Favorite Pop/Rock Album, American Music Award for Favorite Soul/R&B Album, Brit Award for Best Soundtrack/Cast Recording, Grammy Award for Best Rock Performance by a Duo or Group with Vocal | Let's Go Crazy, Take Me With U, The Beautiful Ones, Computer Blue, Darling Nikki, When Doves Cry, I Would Die 4 U, Baby I'm a Star, Purple Rain |
| Beastie Boys | License to Ill | 1986 | Mercury Records | noawardsbutthistablecelliswide | Rhymin & Stealin, The New Style, She's Crafty, Posse in Effect, Slow Ride, Girls, (You Gotta) Fight for Your Right, No Sleep Till Brooklyn, Paul Revere, Hold It Now, Hit It, Brass Monkey, Slow and Low, Time to Get Ill |
----------------
Code snippets like `var foo = "bar";` can be shown inline.
Also, `this should vertically align` ~~`with this`~~ ~~and this~~.
Code can also be shown in a block element.
```
var foo = "bar";
```
Code can also use syntax highlighting.
```javascript
var foo = "bar";
```
```
Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this.
```
```javascript
var foo = "The same thing is true for code with syntax highlighting. A single line of code should horizontally scroll if it is really long.";
```
Inline code inside table cells should still be distinguishable.
| Language | Code |
|-------------|--------------------|
| Javascript | `var foo = "bar";` |
| Ruby | `foo = "bar"` |
----------------
Small images should be shown at their actual size.
![](http://placekitten.com/g/300/200/)
Large images should always scale down and fit in the content container.
![](http://placekitten.com/g/1200/800/)
```
This is the final element on the page and there should be no margin below this.
```
<!-- %enddocs -->
Find further documentation at [primer.style/css/components/markdown](https://primer.style/css/components/markdown).
## License
[MIT](./LICENSE) &copy; [GitHub](https://github.com/)
[primer]: https://github.com/primer/css
[docs]: http://primer.github.io/
[docs]: https://primer.style/css
[npm]: https://www.npmjs.com/
[install-npm]: https://docs.npmjs.com/getting-started/installing-node
[sass]: http://sass-lang.com/

13
src/marketing/README.md
View File

@ -1,20 +1,9 @@
# Primer marketing
[![npm version](https://img.shields.io/npm/v/primer-marketing.svg)](https://www.npmjs.org/package/primer-marketing)
[![Build Status](https://travis-ci.org/primer/css.svg?branch=master)](https://travis-ci.org/primer/primer)
> Primer marketing is one of 3 meta-packages that belong to the Primer framework. Primer marketing contains packages that are used on GitHub marketing websites.
This repository is a compilation of [several CSS packages](https://github.com/primer/css). You can break it down into smaller sections using npm.
## Install
This repository is distributed with [npm][npm]. After [installing npm][install-npm], you can install `primer` with this command. **You must have npm >=3.0 installed to be able to satisfy the dependency paths**
```
$ npm install --save primer-marketing
```
## Usage
The source files included are written in [Sass][sass] (`scss`) You can simply point your sass `include-path` at your `node_modules` directory and import it like this.
@ -42,7 +31,7 @@ You can read more about primer in the [docs][docs].
[MIT](./LICENSE) &copy; [GitHub](https://github.com/)
[primer]: https://github.com/primer/css
[docs]: http://primer.github.io/
[docs]: https://primer.style/css
[npm]: https://www.npmjs.com/
[install-npm]: https://docs.npmjs.com/getting-started/installing-node
[sass]: http://sass-lang.com/

51
src/marketing/buttons/README.md
View File

@ -1,59 +1,12 @@
# Primer Marketing CSS Buttons
[![npm version](https://img.shields.io/npm/v/primer-marketing-buttons.svg)](https://www.npmjs.org/package/primer-marketing-buttons)
[![Build Status](https://travis-ci.org/primer/css.svg?branch=master)](https://travis-ci.org/primer/primer)
> Buttons are used for actions, like in forms, while textual hyperlinks are used for destinations, or moving from one page to another.
This repository is a module of the full [primer][primer] repository.
## Documentation
<!-- %docs
title: Marketing Buttons
path: components/marketing-buttons
status: New Release
-->
Marketing buttons come in different colors and sizes, and are also available in a blue outlined version.
## Colors and outlined
Marketing buttons can be solid blue, outlined blue, solid green, or transparent.
The solid blue and solid green buttons have more visual emphasis than the blue outlined button, therefore they should be used sparingly and only for call to actions that need emphasis.
```html
<button class="btn-mktg mr-2" type="button">Learn more</button>
<button class="btn-mktg btn-outline-mktg mr-2" type="button">Learn more</button>
<button class="btn-mktg btn-primary-mktg mr-2" type="button">Sign up</button>
<div class="bg-gray-dark">
<button class="btn-mktg btn-transparent m-2" type="button">Learn more</button>
</div>
```
## Sizes
Available in two sizes, marketing buttons have a default size and a large size.
```html
<button class="btn-mktg mr-2" type="button">Learn more</button>
<button class="btn-mktg btn-outline-mktg mr-2" type="button">Learn more</button>
<button class="btn-mktg btn-primary-mktg mr-2" type="button">Sign up</button>
<button class="btn-mktg btn-large-mktg mr-2" type="button">Learn more</button>
<button class="btn-mktg btn-outline-mktg btn-large-mktg mr-2" type="button">Learn more</button>
<button class="btn-mktg btn-primary-mktg btn-large-mktg mr-2" type="button">Sign up</button>
```
<!-- %enddocs -->
## Install
This repository is distributed with [npm][npm]. After [installing npm][install-npm], you can install `primer-marketing-buttons` with this command.
```
$ npm install --save primer-marketing-buttons
```
Find further documentation at [primer.style/css/utilities/marketing-buttons](https://primer.style/css/utilities/marketing-buttons).
## Usage
@ -80,7 +33,7 @@ MIT &copy; [GitHub](https://github.com/)
[primer]: https://github.com/primer/css
[primer-support]: https://github.com/primer/css-support
[support]: https://github.com/primer/css-support
[docs]: http://primer.github.io/
[docs]: https://primer.style/css
[npm]: https://www.npmjs.com/
[install-npm]: https://docs.npmjs.com/getting-started/installing-node
[sass]: http://sass-lang.com/

37
src/marketing/support/README.md
View File

@ -1,22 +1,11 @@
# Primer Marketing Support
[![npm version](https://img.shields.io/npm/v/primer-marketing-support.svg)](https://www.npmjs.org/package/primer-marketing-support)
[![Build Status](https://travis-ci.org/primer/css.svg?branch=master)](https://travis-ci.org/primer/primer)
> Support files are Sass variables, mixins, and functions that we import into different bases for use across components, objects, and utilities. Sharing these common properties across GitHub sites helps us to keep our styles more consistent.
>
> Most of the time to include these you'll only need to add `@import "./primer-marketing-support";` to the top of your bundle. If you want only a specific partial you can import them separately.
This repository is a module of the full [primer][primer] repository.
## Install
This repository is distributed with [npm][npm]. After [installing npm][install-npm], you can install `support` with this command.
```
$ npm install --save support
```
## Usage
The source files included are written in [Sass][sass] (`scss`) You can simply point your sass `include-path` at your `node_modules` directory and import it like this.
@ -29,36 +18,14 @@ You can also import specific portions of the module by importing those partials
## Documentation
<!-- %docs
title: Marketing support
path: support/marketing-variables
status: Stable
-->
### Extended spacing scale
This module extends the `primer-core` spacing scale for marketing site needs. These are useful for achieving bigger vertical spacing between sections on marketing sites.
Starting where the `primer-core` spacing scale ends at spacer 6, the marketing scale first steps up with `8px` for spacer 7 then steps in increments of `16px` from spacer 8 up to 12.
| Scale | Value |
|-------|-------|
| 7 | 48 |
| 8 | 64 |
| 9 | 80 |
| 10 | 96 |
| 11 | 112 |
| 12 | 128 |
See [primer-marketing-support](https://npm.im/primer-marketing-support) for the extended spacing scale used for marketing needs and the related y-axis spacing utilities for [margin](/css/utilities/marketing-margin) and [padding](/css/utilities/marketing-padding).
<!-- %enddocs -->
Find further documentation at [primer.style/css/support/marketing-variables](https://primer.style/css/support/marketing-variables).
## License
MIT &copy; [GitHub](https://github.com/)
[primer]: https://github.com/primer/css
[docs]: http://primer.github.io/
[docs]: https://primer.style/css
[npm]: https://www.npmjs.com/
[install-npm]: https://docs.npmjs.com/getting-started/installing-node
[sass]: http://sass-lang.com/

4
src/marketing/support/variables.scss
View File

@ -5,14 +5,14 @@ $marketing-font-path: "/primer-marketing-support/fonts/" !default;
font-family: Inter;
font-style: normal;
font-weight: $font-weight-normal;
src: local("Inter"), local("Inter-Regular"), url("#{$marketing-font-path}Inter-UI-Regular.woff") format("woff");
src: local("Inter"), local("Inter-Regular"), url("#{$marketing-font-path}Inter-Regular.woff") format("woff");
}
@font-face {
font-family: Inter;
font-style: normal;
font-weight: $font-weight-semibold;
src: local("Inter Medium"), local("Inter-Medium"), url("#{$marketing-font-path}Inter-UI-Medium.woff") format("woff");
src: local("Inter Medium"), local("Inter-Medium"), url("#{$marketing-font-path}Inter-Medium.woff") format("woff");
}
$font-mktg: Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol" !default;

54
src/marketing/type/README.md
View File

@ -1,62 +1,12 @@
# Primer Marketing CSS Typography
[![npm version](https://img.shields.io/npm/v/primer-marketing-type.svg)](https://www.npmjs.org/package/primer-marketing-type)
[![Build Status](https://travis-ci.org/primer/css.svg?branch=master)](https://travis-ci.org/primer/primer)
> Flash messages, or alerts, inform users of successful or pending actions. Use them sparingly. Don’t show more than one at a time.
This repository is a module of the full [primer][primer] repository.
## Documentation
<!-- %docs
title: Marketing Typography
path: utilities/marketing-type
status: New Release
-->
The typography for our marketing pages differs slightly from what is in Primer's core--it is responsive, on a slightly different scale, and headlines are in a different font (Roboto).
## Heading Utilities
Use `.h000-mktg` – `.h6-mktg` to change an element's font, size, and weight on marketing pages.
```html title="Heading Utilities"
<p class="h000-mktg">Heading 000</p>
<p class="h00-mktg">Heading 00</p>
<p class="h0-mktg">Heading 0</p>
<p class="h1-mktg">Heading 1</p>
<p class="h2-mktg">Heading 2</p>
<p class="h3-mktg">Heading 3</p>
<p class="h4-mktg">Heading 4</p>
<p class="h5-mktg">Heading 5</p>
<p class="h6-mktg">Heading 6</p>
```
## Typographic Utilities
These utilities are meant to be used in addition to Primer's core utilities.
```html title="Typographic Utilities"
<p class="lead-mktg text-gray">I'm a lead paragraph. Bacon ipsum dolor amet tri-tip chicken kielbasa, cow swine beef corned beef ground round prosciutto hamburger porchetta sausage alcatra tail.</p>
<p class="pullquote">I'm a pullquote. Someone said these words in real life, and now they're on the internet</p>
```
<!-- %enddocs -->
## Install
This repository is distributed with [npm][npm]. After [installing npm][install-npm], you can install `primer-marketing-typography` with this command.
```
$ npm install --save primer-marketing-typography
```
Find further documentation at [primer.style/css/utilities/marketing-type](https://primer.style/css/utilities/marketing-type).
## Usage
@ -83,7 +33,7 @@ MIT &copy; [GitHub](https://github.com/)
[primer]: https://github.com/primer/css
[primer-support]: https://github.com/primer/css-support
[support]: https://github.com/primer/css-support
[docs]: http://primer.github.io/
[docs]: https://primer.style/css
[npm]: https://www.npmjs.com/
[install-npm]: https://docs.npmjs.com/getting-started/installing-node
[sass]: http://sass-lang.com/

15
src/marketing/utilities/README.md
View File

@ -1,18 +1,7 @@
# Primer Marketing CSS Utilities
[![npm version](https://img.shields.io/npm/v/primer-marketing-utilities.svg)](https://www.npmjs.org/package/primer-marketing-utilities)
[![Build Status](https://travis-ci.org/primer/css.svg?branch=master)](https://travis-ci.org/primer/primer)
This repository is a module of the full [primer-marketing-css][primer-marketing-css] repository.
## Install
This repository is distributed with [npm][npm]. After [installing npm][install-npm], you can install `primer-marketing-utilities` with this command.
```
$ npm install --save primer-marketing-utilities
```
## Usage
The source files included are written in [Sass][sass] (`scss`) You can simply point your sass `include-path` at your `node_modules` directory and import it like this.
@ -33,14 +22,14 @@ $ npm run build
## Documentation
You can read more about utilities in the [docs folder](./docs/).
Find further documentation at [primer.style/css/utilities](https://primer.style/css/utilities).
## License
[MIT](./LICENSE) &copy; [GitHub](https://github.com/)
[primer]: https://github.com/primer/css
[docs]: http://primer.github.io/
[docs]: https://primer.style/css
[npm]: https://www.npmjs.com/
[install-npm]: https://docs.npmjs.com/getting-started/installing-node
[sass]: http://sass-lang.com/

333
src/navigation/README.md
View File

@ -1,20 +1,9 @@
# Primer Navigation
[![npm version](https://img.shields.io/npm/v/primer-navigation.svg)](https://www.npmjs.org/package/primer-navigation)
[![Build Status](https://travis-ci.org/primer/css.svg?branch=master)](https://travis-ci.org/primer/primer)
> Primer comes with several navigation components. Some were designed with singular purposes, while others were design to be more flexible and appear quite frequently.
This repository is a module of the full [primer][primer] repository.
## Install
This repository is distributed with [npm][npm]. After [installing npm][install-npm], you can install `primer-navigation` with this command.
```
$ npm install --save primer-navigation
```
## Usage
The source files included are written in [Sass][sass] (`scss`) You can simply point your sass `include-path` at your `node_modules` directory and import it like this.
@ -35,332 +24,14 @@ $ npm run build
## Documentation
<!-- %docs
title: Navigation
path: components/navigation
status: Stable
-->
Primer comes with several navigation components. Some were designed with singular purposes, while others were design to be more flexible and appear quite frequently.
{:toc}
## Menu
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`.
```html title="Menu"
<nav class="menu" aria-label="Person settings">
<a class="menu-item selected" href="#url" aria-current="page">Account</a>
<a class="menu-item" href="#url">Profile</a>
<a class="menu-item" href="#url">Emails</a>
<a class="menu-item" href="#url">Notifications</a>
</nav>
```
There are a few subcomponents and add-ons that work well with the menu, including avatars, counters, and Octicons.
```erb title="Menu with octicons, avatars and counters"
<nav class="menu" aria-label="Person settings">
<a class="menu-item selected" href="#url" aria-current="page">
<%= octicon "tools" %>
Account
</a>
<a class="menu-item" href="#url">
<%= octicon "person" %>
Profile
</a>
<a class="menu-item" href="#url">
<%= octicon "mail" %>
Emails
</a>
<a class="menu-item" href="#url">
<%= octicon "radio-tower" %>
<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.
```html title="Menu with heading"
<nav class="menu" aria-labelledby="menu-heading">
<span class="menu-heading" id="menu-heading">Menu heading</span>
<a class="menu-item selected" href="#url" aria-current="page">Account</a>
<a class="menu-item" href="#url">Profile</a>
<a class="menu-item" href="#url">Emails</a>
<a class="menu-item" href="#url">Notifications</a>
</nav>
```
## Underline nav
Use `.UnderlineNav` to style navigation with a minimal underlined selected state, typically used for navigation placed at the top of the page. This component comes with variations to accommodate icons, containers and other content.
```html title="UnderlineNav"
<nav class="UnderlineNav">
<div class="UnderlineNav-body">
<a href="#url" role="tab" title="Item 1" class="UnderlineNav-item selected">Item 1</a>
<a href="#url" role="tab" title="Item 2" class="UnderlineNav-item">Item 2</a>
<a href="#url" role="tab" title="Item 3" class="UnderlineNav-item">Item 3</a>
<a href="#url" role="tab" title="Item 4" class="UnderlineNav-item">Item 4</a>
</div>
</nav>
```
Use `.UnderlineNav-actions` to place another element, such as a button, to the opposite side of the navigation items.
```html title="UnderlineNav-actions"
<nav class="UnderlineNav" aria-label="Foo bar">
<div class="UnderlineNav-body">
<a href="#url" class="UnderlineNav-item selected">Item 1</a>
<a href="#url" class="UnderlineNav-item">Item 2</a>
<a href="#url" class="UnderlineNav-item">Item 3</a>
<a href="#url" class="UnderlineNav-item">Item 4</a>
</div>
<div class="UnderlineNav-actions">
<a class="btn">Button</a>
</div>
</nav>
```
Use `.UnderlineNav--right` to right align the navigation.
```html title="UnderlineNav--right"
<nav class="UnderlineNav UnderlineNav--right">
<div class="UnderlineNav-body">
<a href="#url" role="tab" title="Item 1" class="UnderlineNav-item selected">Item 1</a>
<a href="#url" role="tab" title="Item 2" class="UnderlineNav-item">Item 2</a>
<a href="#url" role="tab" title="Item 3" class="UnderlineNav-item">Item 3</a>
<a href="#url" role="tab" title="Item 4" class="UnderlineNav-item">Item 4</a>
</div>
</nav>
```
`.UnderlineNav--right` also works with when used with `.UnderlineNav-actions`.
```html title="UnderlineNav--right with actions"
<nav class="UnderlineNav UnderlineNav--right" aria-label="Foo bar">
<div class="UnderlineNav-actions">
<a class="btn">Button</a>
</div>
<div class="UnderlineNav-body">
<a href="#url" class="UnderlineNav-item selected">Item 1</a>
<a href="#url" class="UnderlineNav-item">Item 2</a>
<a href="#url" class="UnderlineNav-item">Item 3</a>
<a href="#url" class="UnderlineNav-item">Item 4</a>
</div>
</nav>
```
<!-- Update wording here -->
`.Counters` and `.octicons` can be used with navigation items. Use `.UnderlineNav-octicon` to add color and hover styles.
```erb title="UnderlineNav with Counter"
<nav class="UnderlineNav" aria-label="Foo bar">
<div class="UnderlineNav-body">
<a href="#url" class="UnderlineNav-item selected">
<%= octicon "tools", :class => "UnderlineNav-octicon" %>
Item 1
</a>
<a href="#url" class="UnderlineNav-item">
<%= octicon "tools", :class => "UnderlineNav-octicon" %>
Item 2
<span class="Counter">10</span>
</a>
<a href="#url" class="UnderlineNav-item">
<%= octicon "tools", :class => "UnderlineNav-octicon" %>
Item 3
</a>
<a href="#url" class="UnderlineNav-item">
<%= octicon "tools", :class => "UnderlineNav-octicon" %>
Item 4
</a>
</div>
</nav>
```
Use `.UnderlineNav--full` in combination with container styles and `.UnderlineNav-container` to make navigation fill the width of the container.
```html title="UnderlineNav--full"
<nav class="UnderlineNav UnderlineNav--full" aria-label="Foo bar">
<div class="container-lg UnderlineNav-container">
<div class="UnderlineNav-body">
<a href="#url" class="UnderlineNav-item selected">Item 1</a>
<a href="#url" class="UnderlineNav-item">Item 2
<span class="Counter">10</span>
</a>
<a href="#url" class="UnderlineNav-item">Item 3</a>
<a href="#url" class="UnderlineNav-item">Item 4</a>
</div>
<div class="UnderlineNav-actions">
<a class="btn">Button</a>
</div>
</div>
</nav>
```
## Tabnav
When you need to toggle between different views, consider using a tabnav. It'll given you a left-aligned horizontal row of... tabs!
```html title="tabnav"
<div class="tabnav">
<nav class="tabnav-tabs" aria-label="Foo bar">
<a href="#url" class="tabnav-tab selected" aria-current="page">Foo tab</a>
<a href="#url" class="tabnav-tab">Bar tab</a>
</nav>
</div>
```
Use `.float-right` to align additional elements in the `.tabnav`:
```html title="tabnav with buttons"
<div class="tabnav">
<a class="btn btn-sm float-right" href="#url" role="button">Button</a>
<nav class="tabnav-tabs" aria-label="Foo bar">
<a href="#url" class="tabnav-tab selected" aria-current="page">Foo Tab</a>
<a href="#url" class="tabnav-tab">Bar Tab</a>
</nav>
</div>
```
Additional bits of text and links can be styled for optimal placement with `.tabnav-extra`:
```html title="tabnav-extra"
<div class="tabnav">
<div class="tabnav-extra float-right">
Tabnav widget text here.
</div>
<nav class="tabnav-tabs" aria-label="Foo bar">
<a href="#url" class="tabnav-tab selected" aria-current="page">Foo Tab</a>
<a href="#url" class="tabnav-tab">Bar Tab</a>
</nav>
</div>
```
```html title="tabnav with everything"
<div class="tabnav">
<div class="float-right">
<a class="tabnav-extra" href="#url">
Tabnav extra link
</a>
<a class="tabnav-extra" href="#url">
Tabnav extra link
</a>
</div>
<nav class="tabnav-tabs" aria-label="Foo bar">
<a href="#url" class="tabnav-tab selected" aria-current="page">Foo Tab</a>
<a href="#url" class="tabnav-tab">Bar Tab</a>
</nav>
</div>
```
## Filter list
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.
```html title="filter-list"
<ul class="filter-list">
<li>
<a href="#url" class="filter-item selected" aria-current="page">
<span class="count" title="results">21</span>
First filter
</a>
</li>
<li>
<a href="#url" class="filter-item">
<span class="count" title="results">3</span>
Second filter
</a>
</li>
<li>
<a href="#url" class="filter-item">
Third filter
</a>
</li>
</ul>
```
## Sub navigation
`.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.
```html title="subnav"
<nav class="subnav" aria-label="Respository">
<a href="#url" class="subnav-item selected" aria-current="page">Item 1</a>
<a href="#url" class="subnav-item">Item 2</a>
<a href="#url" class="subnav-item">Item 3</a>
</nav>
```
You can have `subnav-search` in the subnav bar.
```erb title="subnav-search"
<div class="subnav">
<nav class="subnav-links" aria-label="Repository">
<a href="#url" class="subnav-item selected" aria-current="page">Item 1</a>
<a href="#url" class="subnav-item">Item 2</a>
<a href="#url" class="subnav-item">Item 3</a>
</nav>
<div class="subnav-search float-left">
<input type="search" name="name" class="form-control subnav-search-input" value="" aria-label="Search site">
<%= octicon "search", :class => "subnav-search-icon" %>
</div>
</div>
```
You can also use a `subnav-search-context` to display search help in a select menu.
```erb title="subnav-search-context"
<div class="subnav">
<nav class="subnav-links">
<a href="#url" class="subnav-item selected">Item 1</a>
<a href="#url" class="subnav-item">Item 2</a>
<a href="#url" class="subnav-item">Item 3</a>
</nav>
<div class="float-left ml-3 select-menu js-menu-container js-select-menu subnav-search-context">
<button type="button" name="button" class="btn select-menu-button js-menu-target" aria-expanded="false" aria-haspopup="true">Filters </button>
<div class="select-menu-modal-holder js-menu-content js-navigation-container" aria-hidden="true">
<div class="select-menu-modal">
<div class="select-menu-list">
<a href="#url" class="select-menu-item js-navigation-item">
<div class="select-menu-item-text">
Search filter 1
</div>
</a>
<a href="#url" class="select-menu-item js-navigation-item">
<div class="select-menu-item-text">
Search filter 2
</div>
</a>
<a href="#url" class="select-menu-item js-navigation-item">
<div class="select-menu-item-text">
Search filter 3
</div>
</a>
</div>
</div>
</div>
</div>
<div class="subnav-search float-left">
<input type="search" name="name" class="form-control subnav-search-input" value="" aria-label="Search site">
<%= octicon "search", :class => "subnav-search-icon" %>
</div>
</div>
```
<!-- %enddocs -->
Find further documentation at [primer.style/css/components/navigation](https://primer.style/css/components/navigation).
## License
[MIT](./LICENSE) &copy; [GitHub](https://github.com/)
[primer]: https://github.com/primer/css
[docs]: http://primer.github.io/
[docs]: https://primer.style/css
[npm]: https://www.npmjs.com/
[install-npm]: https://docs.npmjs.com/getting-started/installing-node
[sass]: http://sass-lang.com/

64
src/pagination/README.md
View File

@ -1,20 +1,9 @@
# Primer Pagination
[![npm version](https://img.shields.io/npm/v/primer-pagination.svg)](https://www.npmjs.org/package/primer-pagination)
[![Build Status](https://travis-ci.org/primer/css.svg?branch=master)](https://travis-ci.org/primer/primer)
> Pagination component for applying button styles to a connected set of links that go to related pages
This repository is a module of the full [primer][primer] repository.
## Install
This repository is distributed with [npm]. After [installing npm][install-npm], you can install `primer-pagination` with this command.
```
$ npm install --save primer-pagination
```
## Usage
The source files included are written in [Sass][sass] (SCSS) You can simply point your sass `include-path` at your `node_modules` directory and import it like this.
@ -35,55 +24,4 @@ $ npm run build
## Documentation
<!-- %docs
title: Pagination
path: components/pagination
status: New Release
-->
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).
{:toc}
## Previous/next pagination
You can make a very simple pagination container with just the Previous and Next buttons. Add the class `disabled` to the `Previous` button if there isn't a preceding page, or to the `Next` button if there isn't a succeeding page.
```html
<nav class="paginate-container" aria-label="Pagination">
<div class="pagination">
<span class="previous_page disabled">Previous</span>
<a class="next_page" rel="next" href="#url" aria-label="Next Page">Next</a>
</div>
</nav>
```
## 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 class `disabled` to the Previous button if you're on the first page. Apply the class `current` 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 the `paginate-container` element.
- Add `aria-current="true"` to the current page marker.
- Add `aria-label="Page X"` to each anchor link.
```html
<nav class="paginate-container" aria-label="Pagination">
<div class="pagination">
<span class="previous_page disabled">Previous</span>
<em class="current selected" aria-current="true">1</em>
<a href="#url" aria-label="Page 2">2</a>
<a href="#url" aria-label="Page 3">3</a>
<span class="gap">…</span>
<a href="#url" aria-label="Page 8">8</a>
<a href="#url" aria-label="Page 9">9</a>
<a href="#url" aria-label="Page 10">10</a>
<a class="next_page" rel="next" href="#url" aria-label="Next Page">Next</a>
</div>
</nav>
```
<!-- %enddocs -->
Find further documentation at [primer.style/css/components/pagination](https://primer.style/css/components/pagination).

252
src/popover/README.md
View File

@ -1,20 +1,9 @@
# Primer Popover
[![npm version](https://img.shields.io/npm/v/primer-popover.svg)](https://www.npmjs.org/package/primer-popover)
[![Build Status](https://travis-ci.org/primer/css.svg?branch=master)](https://travis-ci.org/primer/primer)
> Popover for suggesting, guiding, and bringing attention to specific UI elements on a page.
This repository is a module of the full [primer][primer] repository.
## Install
This repository is distributed with [npm]. After [installing npm][install-npm], you can install `primer-popover` with this command.
```
$ npm install --save primer-popover
```
## Usage
The source files included are written in [Sass][sass] (SCSS) You can simply point your sass `include-path` at your `node_modules` directory and import it like this.
@ -35,252 +24,15 @@ $ npm run build
## Documentation
<!-- %docs
title: Popover
path: components/popover
status: Experimental
-->
Find further documentation at [primer.style/css/components/popover](https://primer.style/css/components/popover).
Popovers are used to bring attention to specific user interface elements, typically to suggest an action or to guide users through a new experience.
{:toc}
A popover consist of:
- The block element, `.Popover`, which simply positions its content absolutely atop other body content.
- The child element, `.Popover-message`, which contains the markup for the intended messaging and the visual "caret."
In the examples below, `Popover-message`, in particular, uses a handful of utility classes to style it appropriately. And these are intended to demonstrate the default, go-to presentation for the popover's message. By default, the message's caret is centered on the top edge of the message.
The `Popover-message` element also supports several modifiers, most of which position the caret differently:
- [`.Popover-message--top`](#default-top-center) (default): Places the caret on the top edge of the message, horizontally centered.
- [`.Popover-message--bottom`](#bottom) Places the caret on the bottom edge of the message, horizontally centered.
- [`.Popover-message--right`](#right): Places the caret on the right edge of the message, vertically centered.
- [`.Popover-message--left`](#left): Places the caret on the left edge of the message, vertically centered.
Each of these modifiers also support a syntax for adjusting the positioning the caret to the right, left, top, or bottom of its respective edge. That syntax looks like:
- [`.Popover-message--bottom-left`](#bottom-left)
- [`.Popover-message--bottom-right`](#bottom-right)
- [`.Popover-message--left-bottom`](#left-bottom)
- [`.Popover-message--left-top`](#left-top)
- [`.Popover-message--right-bottom`](#right-bottom)
- [`.Popover-message--right-top`](#right-top)
- [`.Popover-message--top-left`](#top-left)
- [`.Popover-message--top-right`](#top-right)
Lastly, there is an added [`.Popover-message--large`](#large) modifier, which assumes a slightly wider popover message on screens wider than 544px.
### Notes
The samples below include optional markup, like:
- An outermost container that establishes stacking context (e.g. `position-relative`).
- A choice piece of user interface (a button, in this case) to relate the popover to.
- Use of the `Details` and `js-details` family of class names, which interact with JavaScript to demonstrate dismissal of the popover by clicking the nested "Got it!" button.
### Basic example
Defaults to caret oriented top-center.
```html title="Default (top-center)"
<div class="position-relative text-center">
<button class="btn btn-primary">UI</button>
<div class="Popover right-0 left-0">
<div class="Popover-message text-left p-4 mt-2 mx-auto Box box-shadow-large">
<h4 class="mb-2">Popover heading</h4>
<p>Message about this particular piece of UI.</p>
<button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
</div>
</div>
</div>
```
### Large example
```html title="Large"
<div class="position-relative text-center">
<button class="btn btn-primary">UI</button>
<div class="Popover right-0 left-0">
<div class="Popover-message Popover-message--large text-left p-4 mt-2 Box box-shadow-large">
<h4 class="mb-2">Popover heading</h4>
<p>Message about this particular piece of UI.</p>
<button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
</div>
</div>
</div>
```
### Bottom
```html title="Bottom"
<div class="position-relative text-center">
<div class="Popover position-relative">
<div class="Popover-message Popover-message--bottom p-4 mx-auto mb-2 text-left Box box-shadow-large">
<h4 class="mb-2">Popover heading</h4>
<p>Message about this particular piece of UI.</p>
<button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
</div>
</div>
<button class="btn btn-primary">UI</button>
</div>
```
### Bottom-right
```html title="Bottom-right"
<div class="position-relative text-right">
<div class="Popover position-relative">
<div class="Popover-message Popover-message--bottom-right p-4 mb-2 text-left Box box-shadow-large">
<h4 class="mb-2">Popover heading</h4>
<p>Message about this particular piece of UI.</p>
<button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
</div>
</div>
<button class="btn btn-primary">UI</button>
</div>
```
### Bottom-left
```html title="Bottom-left"
<div class="Popover position-relative">
<div class="Popover-message Popover-message--bottom-left p-4 mb-2 Box box-shadow-large">
<h4 class="mb-2">Popover heading</h4>
<p>Message about this particular piece of UI.</p>
<button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
</div>
</div>
<button class="btn btn-primary">UI</button>
```
### Left
```html title="Left"
<div class="d-flex flex-justify-center flex-items-center">
<button class="btn btn-primary">UI</button>
<div class="Popover position-relative">
<div class="Popover-message Popover-message--left p-4 ml-2 Box box-shadow-large">
<h4 class="mb-2">Popover heading</h4>
<p>Message about this particular piece of UI.</p>
<button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
</div>
</div>
</div>
```
### Left-bottom
```html title="Left-bottom"
<div class="d-flex flex-justify-center flex-items-end">
<button class="btn btn-primary">UI</button>
<div class="Popover position-relative">
<div class="Popover-message Popover-message--left-bottom p-4 ml-2 Box box-shadow-large">
<h4 class="mb-2">Popover heading</h4>
<p>Message about this particular piece of UI.</p>
<button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
</div>
</div>
</div>
```
### Left-top
```html title="Left-top"
<div class="d-flex flex-justify-center flex-items-start">
<button class="btn btn-primary">UI</button>
<div class="Popover position-relative">
<div class="Popover-message Popover-message--left-top p-4 ml-2 Box box-shadow-large">
<h4 class="mb-2">Popover heading</h4>
<p>Message about this particular piece of UI.</p>
<button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
</div>
</div>
</div>
```
### Right
```html title="Right"
<div class="d-flex flex-justify-center flex-items-center">
<div class="Popover position-relative">
<div class="Popover-message Popover-message--right p-4 mr-2 Box box-shadow-large">
<h4 class="mb-2">Popover heading</h4>
<p>Message about this particular piece of UI.</p>
<button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
</div>
</div>
<button class="btn btn-primary">UI</button>
</div>
```
### Right-bottom
```html title="Right-bottom"
<div class="d-flex flex-justify-center flex-items-end">
<div class="Popover position-relative">
<div class="Popover-message Popover-message--right-bottom p-4 mr-2 Box box-shadow-large">
<h4 class="mb-2">Popover heading</h4>
<p>Message about this particular piece of UI.</p>
<button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
</div>
</div>
<button class="btn btn-primary">UI</button>
</div>
```
### Right-top
```html title="Right-top"
<div class="d-flex flex-justify-center flex-items-start">
<div class="Popover position-relative">
<div class="Popover-message Popover-message--right-top p-4 mr-2 Box box-shadow-large">
<h4 class="mb-2">Popover heading</h4>
<p>Message about this particular piece of UI.</p>
<button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
</div>
</div>
<button class="btn btn-primary">UI</button>
</div>
```
### Top-left
```html title="Top-left"
<div class="position-relative">
<button class="btn btn-primary">UI</button>
<div class="Popover">
<div class="Popover-message Popover-message--top-left p-4 mt-2 Box box-shadow-large">
<h4 class="mb-2">Popover heading</h4>
<p>Message about this particular piece of UI.</p>
<button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
</div>
</div>
</div>
```
### Top-right
```html title="Top-right"
<div class="position-relative text-right">
<button class="btn btn-primary">UI</button>
<div class="Popover right-0">
<div class="Popover-message Popover-message--top-right text-left p-4 mt-2 Box box-shadow-large">
<h4 class="mb-2">Popover heading</h4>
<p>Message about this particular piece of UI.</p>
<button type="submit" class="btn btn-outline mt-2 text-bold">Got it!</button>
</div>
</div>
</div>
```
<!-- %enddocs -->
## License
[MIT](./LICENSE) &copy; [GitHub](https://github.com/)
[primer]: https://github.com/primer/css
[docs]: http://primer.github.io/
[docs]: https://primer.style/css
[npm]: https://www.npmjs.com/
[install-npm]: https://docs.npmjs.com/getting-started/installing-node
[sass]: http://sass-lang.com/

13
src/product/README.md
View File

@ -1,20 +1,9 @@
# Primer product
[![npm version](https://img.shields.io/npm/v/primer-product.svg)](https://www.npmjs.org/package/primer-product)
[![Build Status](https://travis-ci.org/primer/css.svg?branch=master)](https://travis-ci.org/primer/primer)
> Primer product is one of 3 meta-packages that belong to the Primer framework. Primer product contains packages that are used on GitHub product websites.
This repository is a compilation of [several CSS packages](https://github.com/primer/css). You can break it down into smaller sections using npm.
## Install
This repository is distributed with [npm][npm]. After [installing npm][install-npm], you can install `primer` with this command. **You must have npm >=3.0 installed to be able to satisfy the dependency paths**
```
$ npm install --save primer-product
```
## Usage
The source files included are written in [Sass][sass] (`scss`) You can simply point your sass `include-path` at your `node_modules` directory and import it like this.
@ -42,7 +31,7 @@ You can read more about primer in the [docs][docs].
[MIT](./LICENSE) &copy; [GitHub](https://github.com/)
[primer]: https://github.com/primer/css
[docs]: http://primer.github.io/
[docs]: https://primer.style/css
[npm]: https://www.npmjs.com/
[install-npm]: https://docs.npmjs.com/getting-started/installing-node
[sass]: http://sass-lang.com/

68
src/progress/README.md
View File

@ -1,20 +1,9 @@
# Primer / Progress
[![npm version](https://img.shields.io/npm/v/primer-progress.svg)](https://www.npmjs.org/package/primer-progress)
[![Build Status](https://travis-ci.org/primer/css.svg?branch=master)](https://travis-ci.org/primer/primer)
> Use Progress components to visualize task completion
This repository is a module of the full [primer][primer] repository.
## Install
This repository is distributed with [npm]. After [installing npm][install-npm], you can install `primer-progress` with this command.
```
$ npm install --save primer-progress
```
## Usage
The source files included are written in [Sass][sass] (SCSS) You can simply point your sass `include-path` at your `node_modules` directory and import it like this.
@ -34,68 +23,15 @@ $ npm run build
```
## Documentation
<!-- %docs
title: Progress
path: components/progress
status: New Release
-->
Find further documentation at [primer.style/css/components/progress](https://primer.style/css/components/progress).
Use Progress components to visualize task completion.
## Default Progress
```html
<span class="Progress">
<span class="Progress-value bg-green" style="width: 50%;"></span>
</span>
```
## Large Progress
```html
<span class="Progress Progress--large">
<span class="Progress-value bg-green" style="width: 50%;"></span>
</span>
```
## Small Progress
```html
<span class="Progress Progress--small">
<span class="Progress-value bg-green" style="width: 50%;"></span>
</span>
```
## Progress with tooltip
```html
<div class="tooltipped tooltipped-n" aria-label="78 done / 6 in progress / 2 to do">
<span class="Progress">
<span class="Progress-value bg-green" style="width: 50%;"></span>
</span>
</div>
```
## Progress with multiple values
```html
<div class="tooltipped tooltipped-n" aria-label="78 done / 6 in progress / 2 to do">
<span class="Progress">
<span class="Progress-value bg-green" style="width: 50%;"></span>
<span class="Progress-value bg-purple" style="width: 25%;"></span>
<span class="Progress-value bg-red" style="width: 5%;"></span>
</span>
</div>
```
<!-- %enddocs -->
## License
[MIT](./LICENSE) &copy; [GitHub](https://github.com/)
[primer]: https://github.com/primer/css
[docs]: http://primer.github.io/
[docs]: https://primer.style/css
[npm]: https://www.npmjs.com/
[install-npm]: https://docs.npmjs.com/getting-started/installing-node
[sass]: http://sass-lang.com/

90
src/subhead/README.md
View File

@ -1,19 +1,9 @@
# Primer / Subhead
[![npm version](https://img.shields.io/npm/v/primer-subhead.svg)](https://www.npmjs.org/package/primer-subhead)
[![Build Status](https://travis-ci.org/primer/css.svg?branch=master)](https://travis-ci.org/primer/primer)
> The Subhead is a simple header with a bottom border. It&#39;s designed to be used on settings and configuration pages.
This repository is a module of the full [primer][primer] repository.
## Install
This repository is distributed with [npm]. After [installing npm][install-npm], you can install `primer-subhead` with this command.
```
$ npm install --save primer-subhead
```
## Usage
@ -35,91 +25,15 @@ $ npm run build
## Documentation
<!-- %docs
title: Subhead
path: components/subhead
status: Stable
status_issue: https://github.com/github/design-systems/issues/101
-->
Find further documentation at [primer.style/css/components/subhead](https://primer.style/css/components/subhead).
The basic Subhead consists of a `.Subhead` container, which has a light gray bottom border. Use `.Subhead-heading` for the heading itself. It's an `<h2>` sized heading with normal font-weight.
Use a heading element whenever possible as they can be used as navigation for assistive technologies, and avoid skipping levels.
```html title="Subhead"
<div class="Subhead">
<div class="Subhead-heading">Plain subhead</div>
</div>
```
To add a top margin to the Subhead, use `.Subhead--spacious`. This is useful for separating sections on a settings page.
```html title="Spacious Subhead"
<div class="Subhead Subhead--spacious">
<div class="Subhead-heading">Spacious subhead</div>
</div>
```
You can add a one line description to the subhead with `.Subhead-description`.
```html title="Subhead with description"
<div class="Subhead">
<div class="Subhead-heading">Subhead with description</div>
<div class="Subhead-description">The subhead is a subdued header style with a light bottom border.</div>
</div>
```
For longer descriptions, it is recommended that you use a paragraph below the Subhead.
```html title="Subhead with longer description"
<div class="Subhead">
<div class="Subhead-heading">Plain subhead</div>
</div>
<p>
This is a longer description that is sitting below the Subheader. It's much longer than a description that could sit comfortably in the Subhead. It might even have <strong>bold</strong> text. <a href="#">Click to learn more.</a>
</p>
```
You can add a button or something to the right of `.Subhead-heading` with the `.Subhead-actions` element.
```html title="Subhead with actions"
<div class="Subhead">
<div class="Subhead-heading">Subhead with button</div>
<div class="Subhead-actions"><a href="#url" class="btn btn-sm btn-primary" role="button">Action</a></div>
</div>
<div class="Subhead Subhead--spacious">
<div class="Subhead-heading">Subhead with link</div>
<div class="Subhead-actions"><a href="#url">Learn more</a></div>
</div>
```
Use all the elements together to create a Subhead with actions and a description.
```html title="Subhead with actions and description"
<div class="Subhead">
<div class="Subhead-heading">Subhead with actions and description</div>
<div class="Subhead-actions"><a href="#url" class="btn btn-sm btn-primary" role="button">Action</a></div>
<div class="Subhead-description">The subhead is a subdued header style with a light bottom border.</div>
</div>
```
Use the `.Subhead-heading--danger` modifier to make the text bold and red. This is useful for warning users.
```html title="Subhead danger"
<div class="Subhead">
<div class="Subhead-heading Subhead-heading--danger">Danger zone</div>
</div>
```
<!-- %enddocs -->
## License
[MIT](./LICENSE) &copy; [GitHub](https://github.com/)
[primer]: https://github.com/primer/css
[docs]: http://primer.github.io/
[docs]: https://primer.style/css
[npm]: https://www.npmjs.com/
[install-npm]: https://docs.npmjs.com/getting-started/installing-node
[sass]: http://sass-lang.com/

31
src/support/README.md
View File

@ -1,22 +1,11 @@
# Primer Support
[![npm version](https://img.shields.io/npm/v/primer-support.svg)](https://www.npmjs.org/package/primer-support)
[![Build Status](https://travis-ci.org/primer/css.svg?branch=master)](https://travis-ci.org/primer/primer)
> Support files are Sass variables, mixins, and functions that we import into different bases for use across components, objects, and utilities. Sharing these common properties across GitHub sites helps us to keep our styles more consistent.
>
> Most of the time to include these you'll only need to add `@import "support/support";` to the top of your bundle. If you want only a specific partial you can import them separately.
This repository is a module of the full [primer][primer] repository.
## Install
This repository is distributed with [npm][npm]. After [installing npm][install-npm], you can install `primer-support` with this command.
```
$ npm install --save primer-support
```
## Usage
The source files included are written in [Sass][sass] (`scss`) You can simply point your sass `include-path` at your `node_modules` directory and import it like this.
@ -29,30 +18,14 @@ You can also import specific portions of the module by importing those partials
## Documentation
<!-- %docs
title: Support
path: support/index
-->
Primer is built on systems that form the foundation of our styles, and inform the way we write and organize our CSS. Building upon systems helps us make styles consistent and interoperable with each other, and assists us with visual hierarchy and vertical rhythm.
We use Sass variables to keep color, typography, spacing, and other foundations of our system consistent. Occasionally we use Sass mixins to apply multiple CSS properties, they are a convenient solution for frequently-used verbose patterns.
We've documented variables, mixins, and the systems they are built on for the following:
- [Breakpoints](/css/support/breakpoints)
- [Colors](/css/support/color-system)
- [Spacing](/css/support/spacing)
- [Typography](/css/support/typography)
<!-- %enddocs -->
Find further documentation at [primer.style/css/support](https://primer.style/css/support).
## License
[MIT](./LICENSE) &copy; [GitHub](https://github.com/)
[primer]: https://github.com/primer/css
[docs]: http://primer.github.io/
[docs]: https://primer.style/css/support
[npm]: https://www.npmjs.com/
[install-npm]: https://docs.npmjs.com/getting-started/installing-node
[sass]: http://sass-lang.com/

35
src/table-object/README.md
View File

@ -1,20 +1,9 @@
# Primer table object
[![npm version](https://img.shields.io/npm/v/primer-table-object.svg)](https://www.npmjs.org/package/primer-table-object)
[![Build Status](https://travis-ci.org/primer/css.svg?branch=master)](https://travis-ci.org/primer/primer)
> Table object 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.
This repository is a module of the full [primer][primer] repository.
## Install
This repository is distributed with [npm][npm]. After [installing npm][install-npm], you can install `primer-table-object` with this command.
```
$ npm install --save primer-table-object
```
## Usage
The source files included are written in [Sass][sass] (`scss`) You can simply point your sass `include-path` at your `node_modules` directory and import it like this.
@ -35,35 +24,15 @@ $ npm run build
## Documentation
<!-- %docs
title: Table object
path: objects/table-object
status: Stable
-->
Find further documentation at [primer.style/css/objects/table-object](https://primer.style/css/objects/table-object).
The table object 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.
```html title="Table object"
<div class="TableObject">
<div class="TableObject-item TableObject-item--primary">
<input class="input-block form-control" type="text" placeholder="Long elastic input form" aria-label="Long elastic input form">
</div>
<div class="TableObject-item">
<button class="btn ml-2" type="button">Button</button>
</div>
</div>
```
<!-- %enddocs -->
## License
[MIT](./LICENSE) &copy; [GitHub](https://github.com/)
[primer]: https://github.com/primer/css
[docs]: http://primer.github.io/
[docs]: https://primer.style/css
[npm]: https://www.npmjs.com/
[install-npm]: https://docs.npmjs.com/getting-started/installing-node
[sass]: http://sass-lang.com/

124
src/tooltips/README.md
View File

@ -1,20 +1,9 @@
# Primer Tooltips
[![npm version](https://img.shields.io/npm/v/primer-tooltips.svg)](https://www.npmjs.org/package/primer-tooltips)
[![Build Status](https://travis-ci.org/primer/css.svg?branch=master)](https://travis-ci.org/primer/primer)
> Add tooltips built entirely in CSS to nearly any element. Just add a few classes and an aria-label attribute.
This repository is a module of the full [primer][primer] repository.
## Install
This repository is distributed with [npm][npm]. After [installing npm][install-npm], you can install `primer-tooltips` with this command.
```
$ npm install --save primer-tooltips
```
## Usage
The source files included are written in [Sass][sass] (`scss`) You can simply point your sass `include-path` at your `node_modules` directory and import it like this.
@ -35,124 +24,15 @@ $ npm run build
## Documentation
<!-- %docs
title: Tooltips
path: components/tooltips
status: Stable
-->
Find further documentation at [primer.style/css/components/tooltips](https://primer.style/css/components/tooltips).
Add tooltips built entirely in CSS to nearly any element.
{:toc}
## 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?
**Attention**: 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, or consider using `title` for supplemental information.
**Note:** 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:
- `.tooltipped-n`
- `.tooltipped-ne`
- `.tooltipped-e`
- `.tooltipped-se`
- `.tooltipped-s`
- `.tooltipped-sw`
- `.tooltipped-w`
- `.tooltipped-nw`
```html
<span class="tooltipped tooltipped-n border p-2 mb-2 mr-2 float-left" aria-label="This is the tooltip on the North side.">
Tooltip North
</span>
<span class="tooltipped tooltipped-ne border p-2 mb-2 mr-2 float-left" aria-label="This is the tooltip on the North East side.">
Tooltip North East
</span>
<span class="tooltipped tooltipped-e border p-2 mb-2 mr-2 float-left" aria-label="This is the tooltip on the East side.">
Tooltip East
</span>
<span class="tooltipped tooltipped-se border p-2 mb-2 mr-2 float-left" aria-label="This is the tooltip on the South East side.">
Tooltip South East
</span>
<span class="tooltipped tooltipped-s border p-2 mb-2 mr-2 float-left" aria-label="This is the tooltip on the South side.">
Tooltip South
</span>
<span class="tooltipped tooltipped-sw border p-2 mb-2 mr-2 float-left" aria-label="This is the tooltip on the South West side.">
Tooltip South West
</span>
<span class="tooltipped tooltipped-w border p-2 mb-2 mr-2 float-left" aria-label="This is the tooltip on the West side.">
Tooltip West
</span>
<span class="tooltipped tooltipped-nw border p-2 mb-2 mr-2 float-left" aria-label="This is the tooltip on the North West side.">
Tooltip North West
</span>
```
## Tooltip alignment
Align tooltips to the left or right of an element, combined with a directional class to specify north or south.
```html
<span class="tooltipped tooltipped-ne tooltipped-align-left-1 border p-2 mb-2 mr-2 float-left" aria-label="Tooltipped NE and aligned left.">
Tooltip North East align left 1
</span>
<span class="tooltipped tooltipped-ne tooltipped-align-left-2 border p-2 mb-2 mr-2 float-left" aria-label="Tooltipped NE and aligned left.">
Tooltip North East align left 2
</span>
<span class="tooltipped tooltipped-se tooltipped-align-left-1 border p-2 mb-2 mr-2 float-left" aria-label="Tooltipped SW and aigned left.">
Tooltip South East align left 1
</span>
<span class="tooltipped tooltipped-se tooltipped-align-left-2 border p-2 mb-2 mr-2 float-left" aria-label="Tooltipped SW and aigned left.">
Tooltip South East align left 2
</span>
<span class="tooltipped tooltipped-nw tooltipped-align-right-1 border p-2 mb-2 mr-2 float-left" aria-label="Tooltipped NW and aligned right.">
Tooltip North West align right 1
</span>
<span class="tooltipped tooltipped-nw tooltipped-align-right-2 border p-2 mb-2 mr-2 float-left" aria-label="Tooltipped NW and aligned right.">
Tooltip North West align right 2
</span>
<span class="tooltipped tooltipped-sw tooltipped-align-right-1 border p-2 mb-2 mr-2 float-left" aria-label="Tooltipped SE and aligned right.">
Tooltip South West align right 1
</span>
<span class="tooltipped tooltipped-sw tooltipped-align-right-2 border p-2 mb-2 mr-2 float-left" aria-label="Tooltipped SE and aligned right.">
Tooltip South West align right 2
</span>
```
## 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`.
```html
<span class="tooltipped tooltipped-multiline tooltipped-n border p-2" aria-label="This is the tooltip with multiple lines. This is the tooltip with multiple lines.">
Tooltip with multiple lines
</span>
```
## Tooltips 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 modifier class you can use to override this. `.tooltipped-no-delay`
```html
<span class="tooltipped tooltipped-n tooltipped-no-delay border p-2" aria-label="This is the tooltip on the no delay side.">
Tooltip no delay
</span>
```
<!-- %enddocs -->
## License
[MIT](./LICENSE) &copy; [GitHub](https://github.com/)
[primer]: https://github.com/primer/css
[docs]: http://primer.github.io/
[docs]: https://primer.style/css
[npm]: https://www.npmjs.com/
[install-npm]: https://docs.npmjs.com/getting-started/installing-node
[sass]: http://sass-lang.com/

35
src/truncate/README.md
View File

@ -1,20 +1,9 @@
# Primer Truncate
[![npm version](https://img.shields.io/npm/v/primer-truncate.svg)](https://www.npmjs.org/package/primer-truncate)
[![Build Status](https://travis-ci.org/primer/css.svg?branch=master)](https://travis-ci.org/primer/primer)
> .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.
This repository is a module of the full [primer][primer] repository.
## Install
This repository is distributed with [npm][npm]. After [installing npm][install-npm], you can install `primer-truncate` with this command.
```
$ npm install --save primer-truncate
```
## Usage
The source files included are written in [Sass][sass] (`scss`) You can simply point your sass `include-path` at your `node_modules` directory and import it like this.
@ -35,35 +24,15 @@ $ npm run build
## Documentation
<!-- %docs
title: Truncate
path: components/truncate
status: Stable
-->
Find further documentation at [primer.style/css/components/truncate](https://primer.style/css/components/truncate).
`.css-truncate` will shorten text with an ellipsis. The maximum width of the truncated text can be changed by overriding the max-width of `.css-truncate-target`. Unless the full text is so long that it affects performace, always add `title` to the truncated element so the full text can still be seen.
```html title="Truncate"
<span class="branch-ref css-truncate css-truncate-target" title="really-long-branch-name">
really-long-branch-name
</span>
```
You can reveal the entire string on hover with the addition of `.expandable`.
```html title="Truncate Expandable"
<span class="css-truncate expandable">
<span class="branch-ref css-truncate-target">this-is-a-really-long-branch-name</span>
</span>
```
<!-- %enddocs -->
## License
[MIT](./LICENSE) &copy; [GitHub](https://github.com/)
[primer]: https://github.com/primer/css
[docs]: http://primer.github.io/
[docs]: https://primer.style/css
[npm]: https://www.npmjs.com/
[install-npm]: https://docs.npmjs.com/getting-started/installing-node
[sass]: http://sass-lang.com/

15
src/utilities/README.md
View File

@ -1,20 +1,9 @@
# Primer Utilities
[![npm version](https://img.shields.io/npm/v/primer-utilities.svg)](https://www.npmjs.org/package/primer-utilities)
[![Build Status](https://travis-ci.org/primer/css.svg?branch=master)](https://travis-ci.org/primer/primer)
> There are a handful of utilities in Primer for quick behaviors, floats, colors, alignment, and more.
This repository is a module of the full [primer][primer] repository.
## Install
This repository is distributed with [npm][npm]. After [installing npm][install-npm], you can install `primer-utilities` with this command.
```
$ npm install --save primer-utilities
```
## Usage
The source files included are written in [Sass][sass] (`scss`) You can simply point your sass `include-path` at your `node_modules` directory and import it like this.
@ -35,14 +24,14 @@ $ npm run build
## Documentation
You can read more about utilities in the [docs folder](./docs/).
Find further documentation at [primer.style/css/utilities](https://primer.style/css/utilities).
## License
[MIT](./LICENSE) &copy; [GitHub](https://github.com/)
[primer]: https://github.com/primer/css
[docs]: http://primer.github.io/
[docs]: https://primer.style/css
[npm]: https://www.npmjs.com/
[install-npm]: https://docs.npmjs.com/getting-started/installing-node
[sass]: http://sass-lang.com/