From b928a0bbbb1aa1a6e1eb844063a2985fe0bf8601 Mon Sep 17 00:00:00 2001 From: Emily Date: Mon, 4 Mar 2019 14:28:17 -0800 Subject: [PATCH] remove docs in readmes --- pages/css/.gitignore | 42 -- pages/css/components/alerts.md | 107 ++++ pages/css/components/avatars.md | 157 +++++ pages/css/components/blankslate.md | 94 +++ pages/css/components/box.md | 553 +++++++++++++++++ pages/css/components/branch-name.md | 28 + pages/css/components/breadcrumb.md | 27 + pages/css/components/buttons.md | 233 ++++++++ pages/css/components/forms.md | 306 ++++++++++ pages/css/components/labels.md | 142 +++++ pages/css/components/markdown.md | 174 ++++++ pages/css/components/marketing-buttons.md | 39 ++ pages/css/components/navigation.md | 321 ++++++++++ pages/css/components/pagination.md | 54 ++ pages/css/components/popover.md | 241 ++++++++ pages/css/components/progress.md | 57 ++ pages/css/components/subhead.md | 80 +++ pages/css/components/tooltips.md | 113 ++++ pages/css/components/truncate.md | 24 + .../layout/docs => pages/css/objects}/grid.md | 5 +- pages/css/objects/layout.md | 92 +++ pages/css/objects/table-object.md | 24 + .../docs => pages/css/support}/breakpoints.md | 2 + pages/css/support/index.md | 19 + pages/css/support/marketing-variables.md | 25 + .../docs => pages/css/support}/spacing.md | 3 +- .../docs => pages/css/support}/typography.md | 5 +- .../css/utilities}/animations.md | 2 + .../docs => pages/css/utilities}/borders.md | 4 +- .../css/utilities}/box-shadow.md | 4 +- .../docs => pages/css/utilities}/details.md | 2 + .../docs => pages/css/utilities}/flexbox.md | 4 +- .../docs => pages/css/utilities}/layout.md | 2 + .../docs => pages/css/utilities}/margin.md | 2 + .../css/utilities/marketing-borders.md | 3 + .../css/utilities/marketing-filters.md | 5 +- .../css/utilities/marketing-layout.md | 3 + .../css/utilities/marketing-margin.md | 5 +- .../css/utilities/marketing-padding.md | 5 +- pages/css/utilities/marketing-type.md | 42 ++ .../docs => pages/css/utilities}/padding.md | 2 + .../css/utilities}/typography.md | 2 + src/alerts/README.md | 108 +--- src/avatars/README.md | 158 +---- src/base/README.md | 2 +- src/blankslate/README.md | 95 +-- src/box/README.md | 554 +----------------- src/branch-name/README.md | 29 +- src/breadcrumb/README.md | 28 +- src/buttons/README.md | 234 +------- src/core/README.md | 2 +- src/forms/README.md | 307 +--------- src/labels/README.md | 143 +---- src/layout/README.md | 93 +-- src/markdown/README.md | 175 +----- src/marketing/README.md | 2 +- src/marketing/buttons/README.md | 40 +- src/marketing/support/README.md | 26 +- src/marketing/type/README.md | 43 +- src/marketing/utilities/README.md | 4 +- src/navigation/README.md | 322 +--------- src/pagination/README.md | 53 +- src/popover/README.md | 241 +------- src/product/README.md | 2 +- src/progress/README.md | 57 +- src/subhead/README.md | 80 +-- src/support/README.md | 20 +- src/table-object/README.md | 24 +- src/tooltips/README.md | 113 +--- src/truncate/README.md | 24 +- src/utilities/README.md | 4 +- 71 files changed, 3054 insertions(+), 2983 deletions(-) delete mode 100644 pages/css/.gitignore create mode 100644 pages/css/components/alerts.md create mode 100644 pages/css/components/avatars.md create mode 100644 pages/css/components/blankslate.md create mode 100644 pages/css/components/box.md create mode 100644 pages/css/components/branch-name.md create mode 100644 pages/css/components/breadcrumb.md create mode 100644 pages/css/components/buttons.md create mode 100644 pages/css/components/forms.md create mode 100644 pages/css/components/labels.md create mode 100644 pages/css/components/markdown.md create mode 100644 pages/css/components/marketing-buttons.md create mode 100644 pages/css/components/navigation.md create mode 100644 pages/css/components/pagination.md create mode 100644 pages/css/components/popover.md create mode 100644 pages/css/components/progress.md create mode 100644 pages/css/components/subhead.md create mode 100644 pages/css/components/tooltips.md create mode 100644 pages/css/components/truncate.md rename {src/layout/docs => pages/css/objects}/grid.md (98%) create mode 100644 pages/css/objects/layout.md create mode 100644 pages/css/objects/table-object.md rename {src/support/docs => pages/css/support}/breakpoints.md (97%) create mode 100644 pages/css/support/index.md create mode 100644 pages/css/support/marketing-variables.md rename {src/support/docs => pages/css/support}/spacing.md (95%) rename {src/support/docs => pages/css/support}/typography.md (94%) rename {src/utilities/docs => pages/css/utilities}/animations.md (95%) rename {src/utilities/docs => pages/css/utilities}/borders.md (95%) rename {src/utilities/docs => pages/css/utilities}/box-shadow.md (94%) rename {src/utilities/docs => pages/css/utilities}/details.md (88%) rename {src/utilities/docs => pages/css/utilities}/flexbox.md (99%) rename {src/utilities/docs => pages/css/utilities}/layout.md (99%) rename {src/utilities/docs => pages/css/utilities}/margin.md (97%) rename src/marketing/utilities/docs/borders.md => pages/css/utilities/marketing-borders.md (86%) rename src/marketing/utilities/docs/filters.md => pages/css/utilities/marketing-filters.md (72%) rename src/marketing/utilities/docs/layout.md => pages/css/utilities/marketing-layout.md (92%) rename src/marketing/utilities/docs/margin.md => pages/css/utilities/marketing-margin.md (87%) rename src/marketing/utilities/docs/padding.md => pages/css/utilities/marketing-padding.md (89%) create mode 100644 pages/css/utilities/marketing-type.md rename {src/utilities/docs => pages/css/utilities}/padding.md (97%) rename {src/utilities/docs => pages/css/utilities}/typography.md (98%) diff --git a/pages/css/.gitignore b/pages/css/.gitignore deleted file mode 100644 index 102f1998..00000000 --- a/pages/css/.gitignore +++ /dev/null @@ -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 diff --git a/pages/css/components/alerts.md b/pages/css/components/alerts.md new file mode 100644 index 00000000..e5782161 --- /dev/null +++ b/pages/css/components/alerts.md @@ -0,0 +1,107 @@ +--- +title: Alerts +path: components/alerts +status: Stable +source: 'https://github.com/primer/css/tree/master/modules/alerts/README.md' +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 +
+ Flash message goes here. +
+``` + +You can put multiple paragraphs of text in a flash message—the last paragraph's bottom `margin` will be automatically override. + +```html +
+

This is a longer flash message in it's own paragraph. It ends up looking something like this. If we keep adding more text, it'll eventually wrap to a new line.

+

And this is another paragraph.

+
+``` + +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 +
+
+ Flash message goes here. +
+
+``` + +## Variations + +Add `.flash-warn`, `.flash-error`, or `.flash-success` to the flash message to make it yellow, red, or green, respectively. + +```html +
+ Flash message goes here. +
+``` + +```html +
+ Flash message goes here. +
+``` + +```html +
+ Flash message goes here. +
+``` + +## With icon + +Add an icon to the left of the flash message to give it some funky fresh attention. + +```erb +
+ <%= octicon "alert" %> + Flash message with an icon goes here. +
+``` + +## With dismiss + +Add a JavaScript enabled (via Crema) dismiss (close) icon on the right of any flash message. + +```erb +
+ + Dismissable flash message goes here. +
+``` + +## With action button + +A flash message with an action button. + +```html +
+ + Flash message with action here. +
+``` + +## Full width flash + +A flash message that is full width and removes border and border radius. + +```html +
+
+ Full width flash message. +
+
+``` + diff --git a/pages/css/components/avatars.md b/pages/css/components/avatars.md new file mode 100644 index 00000000..63a8b070 --- /dev/null +++ b/pages/css/components/avatars.md @@ -0,0 +1,157 @@ +--- +title: Avatars +path: components/avatars +status: Stable +source: 'https://github.com/primer/css/tree/master/modules/avatars/README.md' +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 `` 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 +jonrohan +``` + +### 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 +jonrohan +``` + +### Parent-child avatars + +When you need a larger parent avatar, and a smaller child one, overlaid slightly, use the parent-child classes. + +```html +
+ jonrohan + josh +
+``` + +### 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 +
+
+ @octocat + @octocat + @octocat +
+
+``` + +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 +
+
+ @octocat + @octocat +
+ @octocat + @octocat + @octocat +
+
+``` + +You can also link individual avatars. To do this shift the `avatar` class over to the anchor: + +```html +
+
+ + @octocat + + + @octocat + +
+
+``` + +Use `AvatarStack--right` to right-align the avatar stack. Remember to switch the alignment of tooltips when making this change. + +```html +
+
+ @octocat + @octocat + @octocat +
+
+``` + +## 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 + + + + + <%= octicon "zap", :class => "CircleBadge-icon text-white" %> + +``` + +### Medium + +```html +
+ Travis CI +
+``` + +### Large + +```html +
+ Travis CI +
+``` + +### 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 +
+ +
+``` + diff --git a/pages/css/components/blankslate.md b/pages/css/components/blankslate.md new file mode 100644 index 00000000..bf8ba202 --- /dev/null +++ b/pages/css/components/blankslate.md @@ -0,0 +1,94 @@ +--- +title: Blankslate +path: components/blankslate +status: Stable +source: 'https://github.com/primer/css/tree/master/modules/blankslate/README.md' +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 +
+

This is a blank slate

+

Use it to provide information when no dynamic content exists.

+
+``` + +#### 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 +
+ <%= octicon "git-commit", :height => 32, :class => "blankslate-icon" %> + <%= octicon "tag", :height => 32, :class => "blankslate-icon" %> + <%= octicon "git-branch", :height => 32, :class => "blankslate-icon" %> +

This is a blank slate

+

Use it to provide information when no dynamic content exists.

+
+``` + +#### 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 +
+

This is a blank slate

+

Use it to provide information when no dynamic content exists.

+
+``` + +##### Capped + +Removes the `border-radius` on the top corners. + +```html +
+

This is a blank slate

+

Use it to provide information when no dynamic content exists.

+
+``` + +##### Spacious + +Significantly increases the vertical padding. + +```html +
+

This is a blank slate

+

Use it to provide information when no dynamic content exists.

+
+``` + +##### Large + +Increases the size of the text in the blankslate + +```html +
+

This is a blank slate

+

Use it to provide information when no dynamic content exists.

+
+``` + +##### No background + +Removes the `background-color` and `border`. + +```html +
+

This is a blank slate

+

Use it to provide information when no dynamic content exists.

+
+``` diff --git a/pages/css/components/box.md b/pages/css/components/box.md new file mode 100644 index 00000000..a41fbd43 --- /dev/null +++ b/pages/css/components/box.md @@ -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/modules/box/README.md' +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 +
+ This is a box. +
+``` + +## 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 +
+
+

+ Box title +

+
+
+ Box body +
+
+ Box footer +
+
+``` + +### 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 +
+ +
+``` + + +Rows can be used with or without `Box-header`, `Box-footer`, or `Box-body`. + +```html +
+
+ Box header +
+
+ Box body +
+ +
+ Box footer +
+
+``` + +### 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 `
` for your rows, you may want to place your rows inside a parent `
` so that the first and last rows are styled appropriately. + +```html +
+
+ Box header +
+ +
+
Box row using a div
+
Box row using a 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 +
+
+

+ Box title +

+
+
+ Box body +
+
    +
  • + Box row one +
    • +
  • + Box row two +
    • +
+
+ Box footer +
+
+``` + +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 +
+
+

+ Box title +

+
+
+ Box body +
+
    +
  • + Box row one +
    • +
  • + Box row two +
    • +
+
+ Box footer +
+
+``` + +## Blue box theme +Use `Box--blue` to style the box borders and box header in blue. + +```html +
+
+ Box header +
+
    +
  • + Box row one +
    • +
  • + Box row two +
    • +
+
+ Box footer +
+
+``` + +## Blue box header theme + +Use `Box-header--blue` to add to change the header border and background to blue. + +```html +
+
+

Box with blue header

+
+
+ Box body +
+
+``` + +## 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 +
+
+ Row one +
+
+ Row two +
+
+``` + +`Box-danger` is often paired with a red heading. See the [subhead](./subhead) docs for more information. + +```html +
+

Danger zone

+
+ +
+
+ Box body +
+
+``` + +## Row themes +You can change the background color for individual rows, or change the color on hover or navigation focus. + + +```html +
+
+ .Box-row--gray +
+
+ .Box-row--hover-gray +
+
+ .Box-row--yellow +
+
+ .Box-row--hover-blue +
+
+ .Box-row--blue +
+
+``` + +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 +
+
+ .Box-row--focus-gray and .navigation-focus +
+
+ .Box-row--focus-gray +
+
+ .Box-row--focus-blue and .navigation-focus +
+
+ .Box-row--focus-blue +
+
+``` + +### Box row unread +Use `.Box-row-unread` to apply a blue vertical line highlight for indicating a row contains unread items. + +```html +
+
+ Box row +
+
+ Box row unread +
+
+ Box row +
+
+``` + +### 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 +
+
+ Box row link +
+
+``` + +## Dashed border +Use the `border-dashed` utility to apply a dashed border to a box. + +```html +
+ A box with a dashed border +
+``` + +## 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 +
+
+ Box header +
+
+ + Flash message with close button. +
+
+ <%= octicon("check") %> Flash success with an icon. +
+
+ <%= octicon("alert") %> Flash warning with an icon. +
+
+ Flash error inside a Box. +
+
+ Box body +
+
+``` + +## 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 +
+
+ Box body + +
+
+``` + +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 +
+
+ +

A very long title that wraps onto multiple lines without overlapping or wrapping underneath the icon to it's right

+
+
+ Box body +
+
+``` + +```erb +
+
+ +

A very long paragraph that wraps onto multiple lines without overlapping or wrapping underneath the icon to it's left

+
+
+``` + +## 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 +
+
+

+ Box title + 12 +

+
+
+ Box body +
+
+``` + +Use `Counter--gray-dark` for a counter with a dark gray background and white text. + +```html +
+
+

+ Box title + 12 +

+
+
+ Box body +
+
+``` + +## 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 +
+
+

+ Box title +

+ +
+
+ Box body +
+
+``` + +A similar approach can be used for buttons with multiple lines of text within a row. + +```html +
+
+
+ Row title +
+ Description +
+
+ +
+
+
+ Row title +
+ Description +
+
+ +
+
+
+ Row title +
+ Description +
+
+ +
+
+``` +Using flexbox along with form, button, and link styles, you can create more complex box headers for things like bulk actions and sorting. + +```html +
+
+
+ +
+ +
+
+ Box body +
+
+``` + +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 +
+
+

+ Example form title +

+
+
+
+
+
+
+
+
+ +
+
+
+ + +
+
+
+``` + +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 +
+
+
+

+ Example form +

+
+
+
+
+ +
+
+
+``` + +Box patterns can also be made with, and modified with [border utilities](/css/utilities/borders). + diff --git a/pages/css/components/branch-name.md b/pages/css/components/branch-name.md new file mode 100644 index 00000000..a0003ce9 --- /dev/null +++ b/pages/css/components/branch-name.md @@ -0,0 +1,28 @@ +--- +title: Branch name +path: components/branch-name +status: Stable +source: 'https://github.com/primer/css/tree/master/modules/branch-name/README.md' +bundle: branch-name +--- + + +Branch names can be a link name or not: + +```html title="Branch name" +a_new_feature_branch +``` + +```html title="Branch name with link" +a_new_feature_branch +``` + +You may also include an octicon before the branch name text: + +```erb title="Branch name with icon" + + <%= octicon("git-branch", width:16, height:16) %> + a_new_feature_branch + +``` + diff --git a/pages/css/components/breadcrumb.md b/pages/css/components/breadcrumb.md new file mode 100644 index 00000000..9b4e0917 --- /dev/null +++ b/pages/css/components/breadcrumb.md @@ -0,0 +1,27 @@ +--- +title: Breadcrumbs +path: components/breadcrumb +status: Stable +source: 'https://github.com/primer/css/tree/master/modules/breadcrumb/README.md' +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" + +``` + diff --git a/pages/css/components/buttons.md b/pages/css/components/buttons.md new file mode 100644 index 00000000..7f313978 --- /dev/null +++ b/pages/css/components/buttons.md @@ -0,0 +1,233 @@ +--- +title: Buttons +path: components/buttons +status: Stable +source: 'https://github.com/primer/css/tree/master/modules/buttons/README.md' +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 ` +Link button +``` + +You can find them in two sizes: the default `.btn` and the smaller `.btn-sm`. + +```html + + +``` + +## 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 + + +``` + +## 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 + + +``` + +## Outline button + +Outline buttons downplay an action as they appear like boxy links. Just add `.btn-outline` and go. + +```html + + +``` + +## 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 +

+ Large link button + +

+ +``` + +Use `.btn-large` with a type scale utility to transform the text to a bigger size. + +```html +

+ Large link button + +

+``` + +## Disabled state + +Disable ` +Disabled button +``` + +Similar styles are applied to primary, danger, and outline buttons: + +```html + +Disabled button +``` + +```html + +Disabled button +``` + +```html + +Disabled button +``` + +## 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 +

+

+``` + +## Link button + +Create a button that looks like a link with `.btn-link`. Rather than using an `` to trigger JS, this style on a `

+``` + +## 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 +
+ + <%= octicon "eye" %> + Watch + + +
+``` + +You can also use the [counter](./labels#counters) component within buttons: + +```html + + + + + + + +``` + +## 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 +
+ + + +
+ +
+ + + +
+ +
+ + + +
+``` + +Add `.BtnGroup-parent` to parent elements, like `
`s or `
`s, within `.BtnGroup`s for proper spacing and rounded corners. + +```html +
+ + + + + + +
+``` + +## Hidden text button + +Use `.hidden-text-expander` to indicate and toggle hidden text. + +```html + + + +``` + +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 +[``](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 +[`
`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details) +element is open. + +```html +
+ Toggle the content +

+ This content will be toggled. +

+
+``` + diff --git a/pages/css/components/forms.md b/pages/css/components/forms.md new file mode 100644 index 00000000..6a3b3b0f --- /dev/null +++ b/pages/css/components/forms.md @@ -0,0 +1,306 @@ +--- +title: Forms +path: components/forms +status: Stable +source: 'https://github.com/primer/css/tree/master/modules/forms/README.md' +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 `
`s, WebKit validation bubbles, and most textual ``s. +- Specific types of textual ``s are styled automatically, but `.form-control` is available should you need it. +- Always declare a `type` on your ` + + + + +

+ +

+ + + + +

+``` + +#### Example form + +Form controls in Primer currently have no basic layout specified (this is by design). You'll need to use `
`s, `
`s, or other elements and styles to rearrange them. + +```html +
+ + + + + + + + + + + + +
+``` + +#### Form contrast + +Textual form controls have a white background by default. You can change this to a light gray with `.input-contrast`. + +```html +
+ + +
+``` + +#### Sizing + +Make inputs smaller, larger, or full-width with an additional class. + +##### Small + +```html +
+ +
+``` + +##### Large + +```html +
+ +
+``` + +##### Block + +```html +
+ +
+``` + +##### 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 +
+ +
+``` + +#### Selects + +Primer adds light `height` and `vertical-align` styles to ` + + + + + + + + + +``` + +##### Small + +Use the `.select-sm` class to resize both default and custom ` + + + + + + + + + + +``` + +#### Form groups + +```html +
+
+
+
+
+ +
+
+
+ +
+
+ +
+
+
+ +
+
+
+``` + +#### Form group validation + +Convey errors and warnings for form groups. Add the appropriate class—either `.errored` or `.warn`—to the `
` to start. Then, house your error messaging in an additional `
` with either `.error` or `.warning`. + +```html +
+
+
+
+
This example input has an error.
+
+
+
+
+
+
This example input has a warning.
+
+
+``` + +#### Checkboxes and radios + +Utilities to spice up the alignment and styling of checkbox and radio controls. + +```html +
+
+ +

+ This will do insanely awesome and amazing things! +

+
+
+``` + +You may also add emphasis to the label: + +```html +
+
+ +
+
+``` + +##### 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 +
+
+ +
+
+ +
+
+``` + +#### Input group + +Attached an input and button to one another. + +```erb +
+
+ + + + +
+
+``` + +#### 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 +
+ + +
+``` diff --git a/pages/css/components/labels.md b/pages/css/components/labels.md new file mode 100644 index 00000000..25c13f7b --- /dev/null +++ b/pages/css/components/labels.md @@ -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/modules/labels/README.md' +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" +default label +``` + +**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" + +New select componentdesign +``` + +### 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" +gray label +``` + +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" +dark gray label +``` + +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" +orange label +``` + +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" +outlined label +``` + +Use `Label--outline-green` in combination with `Label--outline` to communicate a positive message. + +```html title="Label outline green" +green outlined label +``` + + +## 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" +Default +``` + +### 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" +<%= octicon "git-pull-request" %> Open +<%= octicon "git-pull-request" %> Closed +<%= octicon "git-merge" %> Merged +``` + +**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" +<%= octicon "issue-opened" %> Open +<%= octicon "issue-closed" %> Closed +``` + +## 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" +16 +32 +64 +``` + +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" +
+ +
+``` + +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" +
+
+

+ Box title + 3 +

+
+
    +
  • + Box row one +
    • +
  • + Box row two +
    • +
  • + Box row three +
    • +
+
+``` + + diff --git a/pages/css/components/markdown.md b/pages/css/components/markdown.md new file mode 100644 index 00000000..104b05d8 --- /dev/null +++ b/pages/css/components/markdown.md @@ -0,0 +1,174 @@ +--- +title: Markdown +path: components/markdown +status: Stable +source: 'https://github.com/primer/css/tree/master/modules/markdown/README.md' +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. + +
+
Name
+
Godzilla
+
Born
+
1952
+
Birthplace
+
Japan
+
Color
+
Green
+
+ +---------------- + +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. +``` diff --git a/pages/css/components/marketing-buttons.md b/pages/css/components/marketing-buttons.md new file mode 100644 index 00000000..8d970319 --- /dev/null +++ b/pages/css/components/marketing-buttons.md @@ -0,0 +1,39 @@ +--- +title: Marketing Buttons +path: components/marketing-buttons +status: New Release +source: 'https://github.com/primer/css/tree/master/modules/marketing/buttons/README.md' +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 + + + +
+ +
+``` + +## Sizes + +Available in two sizes, marketing buttons have a default size and a large size. + +```html + + + + + + +``` + diff --git a/pages/css/components/navigation.md b/pages/css/components/navigation.md new file mode 100644 index 00000000..a668fd5c --- /dev/null +++ b/pages/css/components/navigation.md @@ -0,0 +1,321 @@ +--- +title: Navigation +path: components/navigation +status: Stable +source: 'https://github.com/primer/css/tree/master/modules/navigation/README.md' +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" + +``` + +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" + +``` + +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" + +``` + +## 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" + +``` + +Use `.UnderlineNav-actions` to place another element, such as a button, to the opposite side of the navigation items. + +```html title="UnderlineNav-actions" + +``` + +Use `.UnderlineNav--right` to right align the navigation. + +```html title="UnderlineNav--right" + +``` + +`.UnderlineNav--right` also works with when used with `.UnderlineNav-actions`. + +```html title="UnderlineNav--right with actions" + +``` + + +`.Counters` and `.octicons` can be used with navigation items. Use `.UnderlineNav-octicon` to add color and hover styles. + +```erb title="UnderlineNav with Counter" + +``` + +Use `.UnderlineNav--full` in combination with container styles and `.UnderlineNav-container` to make navigation fill the width of the container. + +```html title="UnderlineNav--full" + +``` + +## 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" +
+ +
+``` + +Use `.float-right` to align additional elements in the `.tabnav`: + +```html title="tabnav with buttons" +
+ Button + +
+``` + +Additional bits of text and links can be styled for optimal placement with `.tabnav-extra`: + +```html title="tabnav-extra" +
+
+ Tabnav widget text here. +
+ +
+``` + +```html title="tabnav with everything" +
+
+ + Tabnav extra link + + + Tabnav extra link + +
+ +
+``` + +## 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" + +``` + +## 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" + +``` + +You can have `subnav-search` in the subnav bar. + +```erb title="subnav-search" +
+ +
+ + <%= octicon "search", :class => "subnav-search-icon" %> +
+
+``` + + +You can also use a `subnav-search-context` to display search help in a select menu. + +```erb title="subnav-search-context" +
+ +
+ + +
+
+ + <%= octicon "search", :class => "subnav-search-icon" %> +
+
+``` + + diff --git a/pages/css/components/pagination.md b/pages/css/components/pagination.md new file mode 100644 index 00000000..8060b3ed --- /dev/null +++ b/pages/css/components/pagination.md @@ -0,0 +1,54 @@ +--- +title: Pagination +path: components/pagination +status: New Release +source: 'https://github.com/primer/css/tree/master/modules/pagination/README.md' +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 + +``` + +## 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 + +``` + diff --git a/pages/css/components/popover.md b/pages/css/components/popover.md new file mode 100644 index 00000000..9e49a01a --- /dev/null +++ b/pages/css/components/popover.md @@ -0,0 +1,241 @@ +--- +title: Popover +path: components/popover +status: Experimental +source: 'https://github.com/primer/css/tree/master/modules/popover/README.md' +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)" +
+ +
+
+

Popover heading

+

Message about this particular piece of UI.

+ +
+
+
+``` + +### Large example + +```html title="Large" +
+ +
+
+

Popover heading

+

Message about this particular piece of UI.

+ +
+
+
+``` + +### Bottom + +```html title="Bottom" +
+
+
+

Popover heading

+

Message about this particular piece of UI.

+ +
+
+ +
+``` + +### Bottom-right + +```html title="Bottom-right" +
+
+
+

Popover heading

+

Message about this particular piece of UI.

+ +
+
+ +
+``` + +### Bottom-left + +```html title="Bottom-left" +
+
+

Popover heading

+

Message about this particular piece of UI.

+ +
+
+ +``` + +### Left + +```html title="Left" +
+ +
+
+

Popover heading

+

Message about this particular piece of UI.

+ +
+
+
+``` + +### Left-bottom + +```html title="Left-bottom" +
+ +
+
+

Popover heading

+

Message about this particular piece of UI.

+ +
+
+
+``` + +### Left-top + +```html title="Left-top" +
+ +
+
+

Popover heading

+

Message about this particular piece of UI.

+ +
+
+
+``` + +### Right + +```html title="Right" +
+
+
+

Popover heading

+

Message about this particular piece of UI.

+ +
+
+ +
+``` + +### Right-bottom + +```html title="Right-bottom" +
+
+
+

Popover heading

+

Message about this particular piece of UI.

+ +
+
+ +
+``` + +### Right-top + +```html title="Right-top" +
+
+
+

Popover heading

+

Message about this particular piece of UI.

+ +
+
+ +
+``` + +### Top-left + +```html title="Top-left" +
+ +
+
+

Popover heading

+

Message about this particular piece of UI.

+ +
+
+
+``` + +### Top-right + +```html title="Top-right" +
+ +
+
+

Popover heading

+

Message about this particular piece of UI.

+ +
+
+
+``` + diff --git a/pages/css/components/progress.md b/pages/css/components/progress.md new file mode 100644 index 00000000..d3f5d2be --- /dev/null +++ b/pages/css/components/progress.md @@ -0,0 +1,57 @@ +--- +title: Progress +path: components/progress +status: New Release +source: 'https://github.com/primer/css/tree/master/modules/progress/README.md' +bundle: progress +--- + + +Use Progress components to visualize task completion. + +## Default Progress + +```html + + + +``` + +## Large Progress + +```html + + + +``` + +## Small Progress + +```html + + + +``` + +## Progress with tooltip + +```html +
+ + + +
+``` + +## Progress with multiple values + +```html +
+ + + + + +
+``` + diff --git a/pages/css/components/subhead.md b/pages/css/components/subhead.md new file mode 100644 index 00000000..8c179aba --- /dev/null +++ b/pages/css/components/subhead.md @@ -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/modules/subhead/README.md' +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 `

` 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" +
+
Plain subhead
+
+``` + +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" +
+
Spacious subhead
+
+``` + +You can add a one line description to the subhead with `.Subhead-description`. + +```html title="Subhead with description" +
+
Subhead with description
+
The subhead is a subdued header style with a light bottom border.
+
+``` + +For longer descriptions, it is recommended that you use a paragraph below the Subhead. + +```html title="Subhead with longer description" +
+
Plain subhead
+
+

+ 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 bold text. Click to learn more. +

+``` + +You can add a button or something to the right of `.Subhead-heading` with the `.Subhead-actions` element. + +```html title="Subhead with actions" +
+
Subhead with button
+
Action
+
+ +
+
Subhead with link
+
Learn more
+
+``` + +Use all the elements together to create a Subhead with actions and a description. + +```html title="Subhead with actions and description" +
+
Subhead with actions and description
+
Action
+
The subhead is a subdued header style with a light bottom border.
+
+``` + +Use the `.Subhead-heading--danger` modifier to make the text bold and red. This is useful for warning users. + +```html title="Subhead danger" +
+
Danger zone
+
+``` + diff --git a/pages/css/components/tooltips.md b/pages/css/components/tooltips.md new file mode 100644 index 00000000..13e3bf31 --- /dev/null +++ b/pages/css/components/tooltips.md @@ -0,0 +1,113 @@ +--- +title: Tooltips +path: components/tooltips +status: Stable +source: 'https://github.com/primer/css/tree/master/modules/tooltips/README.md' +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 + + Tooltip North + + + Tooltip North East + + + Tooltip East + + + Tooltip South East + + + Tooltip South + + + Tooltip South West + + + Tooltip West + + + Tooltip North West + +``` + +## Tooltip alignment +Align tooltips to the left or right of an element, combined with a directional class to specify north or south. + +```html + + Tooltip North East align left 1 + + + Tooltip North East align left 2 + + + Tooltip South East align left 1 + + + Tooltip South East align left 2 + + + Tooltip North West align right 1 + + + Tooltip North West align right 2 + + + Tooltip South West align right 1 + + + Tooltip South West align right 2 + +``` + +## 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 + + Tooltip with multiple lines + +``` + +## 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 + + Tooltip no delay + +``` + diff --git a/pages/css/components/truncate.md b/pages/css/components/truncate.md new file mode 100644 index 00000000..9034f759 --- /dev/null +++ b/pages/css/components/truncate.md @@ -0,0 +1,24 @@ +--- +title: Truncate +path: components/truncate +status: Stable +source: 'https://github.com/primer/css/tree/master/modules/truncate/README.md' +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" + + really-long-branch-name + +``` + +You can reveal the entire string on hover with the addition of `.expandable`. + +```html title="Truncate Expandable" + +``` diff --git a/src/layout/docs/grid.md b/pages/css/objects/grid.md similarity index 98% rename from src/layout/docs/grid.md rename to pages/css/objects/grid.md index a1767bd2..412d0f24 100644 --- a/src/layout/docs/grid.md +++ b/pages/css/objects/grid.md @@ -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/modules/layout/docs/grid.md' +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. diff --git a/pages/css/objects/layout.md b/pages/css/objects/layout.md new file mode 100644 index 00000000..0bbb9535 --- /dev/null +++ b/pages/css/objects/layout.md @@ -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/modules/layout/README.md' +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" +
+ Container +
+``` + +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 `
`. +- Add your columns with individual `
`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" +
+
+
+ .one-fifth +
+
+ .four-fifths +
+
+ +
+
+ .one-fourth +
+
+ .three-fourths +
+
+ +
+
+ .one-third +
+
+ .two-thirds +
+
+ +
+
+ .one-half +
+
+ .one-half +
+
+
+``` + +##### Centered + +Columns can be centered by adding `.centered` to the `.column` class. + +```html title="Grid centered" +
+
+ .one-half +
+
+``` diff --git a/pages/css/objects/table-object.md b/pages/css/objects/table-object.md new file mode 100644 index 00000000..ea81795d --- /dev/null +++ b/pages/css/objects/table-object.md @@ -0,0 +1,24 @@ +--- +title: Table object +path: objects/table-object +status: Stable +source: 'https://github.com/primer/css/tree/master/modules/table-object/README.md' +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" +
+
+ +
+
+ +
+
+``` + diff --git a/src/support/docs/breakpoints.md b/pages/css/support/breakpoints.md similarity index 97% rename from src/support/docs/breakpoints.md rename to pages/css/support/breakpoints.md index d2709b8c..219b0cec 100644 --- a/src/support/docs/breakpoints.md +++ b/pages/css/support/breakpoints.md @@ -2,6 +2,8 @@ title: Breakpoints path: support/breakpoints status: Stable +source: 'https://github.com/primer/css/tree/master/modules/support/docs/breakpoints.md' +bundle: support --- {:toc} diff --git a/pages/css/support/index.md b/pages/css/support/index.md new file mode 100644 index 00000000..5aab6267 --- /dev/null +++ b/pages/css/support/index.md @@ -0,0 +1,19 @@ +--- +title: Support +path: support/index +source: 'https://github.com/primer/css/tree/master/modules/support/README.md' +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) + diff --git a/pages/css/support/marketing-variables.md b/pages/css/support/marketing-variables.md new file mode 100644 index 00000000..52e9a35b --- /dev/null +++ b/pages/css/support/marketing-variables.md @@ -0,0 +1,25 @@ +--- +title: Marketing support +path: support/marketing-variables +status: Stable +source: 'https://github.com/primer/css/tree/master/modules/marketing/support/README.md' +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). + diff --git a/src/support/docs/spacing.md b/pages/css/support/spacing.md similarity index 95% rename from src/support/docs/spacing.md rename to pages/css/support/spacing.md index 9db41526..cab97108 100644 --- a/src/support/docs/spacing.md +++ b/pages/css/support/spacing.md @@ -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/tree/master/modules/support/docs/spacing.md' +bundle: support --- {:toc} diff --git a/src/support/docs/typography.md b/pages/css/support/typography.md similarity index 94% rename from src/support/docs/typography.md rename to pages/css/support/typography.md index 1577587e..728bf72d 100644 --- a/src/support/docs/typography.md +++ b/pages/css/support/typography.md @@ -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/tree/master/modules/support/docs/typography.md' +bundle: support --- {:toc} diff --git a/src/utilities/docs/animations.md b/pages/css/utilities/animations.md similarity index 95% rename from src/utilities/docs/animations.md rename to pages/css/utilities/animations.md index 55a819b0..97c1c184 100644 --- a/src/utilities/docs/animations.md +++ b/pages/css/utilities/animations.md @@ -3,6 +3,8 @@ title: Animations path: utilities/animations example_layout: toggle status: Stable +source: 'https://github.com/primer/css/tree/master/modules/utilities/docs/animations.md' +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. diff --git a/src/utilities/docs/borders.md b/pages/css/utilities/borders.md similarity index 95% rename from src/utilities/docs/borders.md rename to pages/css/utilities/borders.md index db09cfcc..18a38168 100644 --- a/src/utilities/docs/borders.md +++ b/pages/css/utilities/borders.md @@ -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/modules/utilities/docs/borders.md' +bundle: utilities --- Utilities for borders, border radius, and box shadows. diff --git a/src/utilities/docs/box-shadow.md b/pages/css/utilities/box-shadow.md similarity index 94% rename from src/utilities/docs/box-shadow.md rename to pages/css/utilities/box-shadow.md index a35c7e0d..3a66052e 100644 --- a/src/utilities/docs/box-shadow.md +++ b/pages/css/utilities/box-shadow.md @@ -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/modules/utilities/docs/box-shadow.md' +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). diff --git a/src/utilities/docs/details.md b/pages/css/utilities/details.md similarity index 88% rename from src/utilities/docs/details.md rename to pages/css/utilities/details.md index 18df582b..49bd8dbb 100644 --- a/src/utilities/docs/details.md +++ b/pages/css/utilities/details.md @@ -2,6 +2,8 @@ title: Details path: utilities/details status: Stable +source: 'https://github.com/primer/css/tree/master/modules/utilities/docs/details.md' +bundle: utilities --- Details classes are created to enhance the native behaviors of `
`. diff --git a/src/utilities/docs/flexbox.md b/pages/css/utilities/flexbox.md similarity index 99% rename from src/utilities/docs/flexbox.md rename to pages/css/utilities/flexbox.md index a6960657..d1f40b5a 100644 --- a/src/utilities/docs/flexbox.md +++ b/pages/css/utilities/flexbox.md @@ -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/tree/master/modules/utilities/docs/flexbox.md' +bundle: utilities --- Flex utilities can be used to apply `flexbox` behaviors to elements by using utility classes. diff --git a/src/utilities/docs/layout.md b/pages/css/utilities/layout.md similarity index 99% rename from src/utilities/docs/layout.md rename to pages/css/utilities/layout.md index 979004bd..78068206 100644 --- a/src/utilities/docs/layout.md +++ b/pages/css/utilities/layout.md @@ -2,6 +2,8 @@ title: Layout path: utilities/layout status: Stable +source: 'https://github.com/primer/css/tree/master/modules/utilities/docs/layout.md' +bundle: utilities --- Change the document layout with display, float, alignment, and other utilities. diff --git a/src/utilities/docs/margin.md b/pages/css/utilities/margin.md similarity index 97% rename from src/utilities/docs/margin.md rename to pages/css/utilities/margin.md index 085087a9..abc99930 100644 --- a/src/utilities/docs/margin.md +++ b/pages/css/utilities/margin.md @@ -2,6 +2,8 @@ title: Margin path: utilities/margin status: Stable +source: 'https://github.com/primer/css/tree/master/modules/utilities/docs/margin.md' +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. diff --git a/src/marketing/utilities/docs/borders.md b/pages/css/utilities/marketing-borders.md similarity index 86% rename from src/marketing/utilities/docs/borders.md rename to pages/css/utilities/marketing-borders.md index 862522e2..dfb4c041 100644 --- a/src/marketing/utilities/docs/borders.md +++ b/pages/css/utilities/marketing-borders.md @@ -3,6 +3,9 @@ title: Marketing Borders sort_title: Borders Marketing path: utilities/marketing-borders status: Stable +source: >- + https://github.com/primer/css/tree/master/modules/marketing/utilities/docs/borders.md +bundle: marketing-utilities --- The following border utilities are meant to used in addition to those within primer-core. diff --git a/src/marketing/utilities/docs/filters.md b/pages/css/utilities/marketing-filters.md similarity index 72% rename from src/marketing/utilities/docs/filters.md rename to pages/css/utilities/marketing-filters.md index 801fc6ed..c3b4e66e 100644 --- a/src/marketing/utilities/docs/filters.md +++ b/pages/css/utilities/marketing-filters.md @@ -2,7 +2,10 @@ 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/tree/master/modules/marketing/utilities/docs/filters.md +bundle: marketing-utilities --- Filter utility classes can be applied to divs or images to apply visual effects. diff --git a/src/marketing/utilities/docs/layout.md b/pages/css/utilities/marketing-layout.md similarity index 92% rename from src/marketing/utilities/docs/layout.md rename to pages/css/utilities/marketing-layout.md index 2e8eb492..3e3f6b13 100644 --- a/src/marketing/utilities/docs/layout.md +++ b/pages/css/utilities/marketing-layout.md @@ -3,6 +3,9 @@ title: Marketing Layout sort_title: Layout Marketing path: utilities/marketing-layout status: Stable +source: >- + https://github.com/primer/css/tree/master/modules/marketing/utilities/docs/layout.md +bundle: marketing-utilities --- Marketing layout utilities build on top of [primer-core utilities](/css/utilities/layout#position), adding the option of responsive positioning. diff --git a/src/marketing/utilities/docs/margin.md b/pages/css/utilities/marketing-margin.md similarity index 87% rename from src/marketing/utilities/docs/margin.md rename to pages/css/utilities/marketing-margin.md index 6743501b..9783d2b1 100644 --- a/src/marketing/utilities/docs/margin.md +++ b/pages/css/utilities/marketing-margin.md @@ -3,7 +3,10 @@ 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/tree/master/modules/marketing/utilities/docs/margin.md +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. diff --git a/src/marketing/utilities/docs/padding.md b/pages/css/utilities/marketing-padding.md similarity index 89% rename from src/marketing/utilities/docs/padding.md rename to pages/css/utilities/marketing-padding.md index a6da381e..f16f9567 100644 --- a/src/marketing/utilities/docs/padding.md +++ b/pages/css/utilities/marketing-padding.md @@ -3,7 +3,10 @@ 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/modules/marketing/utilities/docs/padding.md +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. diff --git a/pages/css/utilities/marketing-type.md b/pages/css/utilities/marketing-type.md new file mode 100644 index 00000000..86c64621 --- /dev/null +++ b/pages/css/utilities/marketing-type.md @@ -0,0 +1,42 @@ +--- +title: Marketing Typography +path: utilities/marketing-type +status: New Release +source: 'https://github.com/primer/css/tree/master/modules/marketing/type/README.md' +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" + +

Heading 000

+

Heading 00

+

Heading 0

+

Heading 1

+

Heading 2

+

Heading 3

+

Heading 4

+

Heading 5

+

Heading 6

+ +``` + +## Typographic Utilities + +These utilities are meant to be used in addition to Primer's core utilities. + +```html title="Typographic Utilities" + +

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.

+ +

I'm a pullquote. Someone said these words in real life, and now they're on the internet

+ +``` + diff --git a/src/utilities/docs/padding.md b/pages/css/utilities/padding.md similarity index 97% rename from src/utilities/docs/padding.md rename to pages/css/utilities/padding.md index 08523ebc..80610075 100644 --- a/src/utilities/docs/padding.md +++ b/pages/css/utilities/padding.md @@ -2,6 +2,8 @@ title: Padding path: utilities/padding status: Stable +source: 'https://github.com/primer/css/tree/master/modules/utilities/docs/padding.md' +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. diff --git a/src/utilities/docs/typography.md b/pages/css/utilities/typography.md similarity index 98% rename from src/utilities/docs/typography.md rename to pages/css/utilities/typography.md index f210ff58..90b05a4b 100644 --- a/src/utilities/docs/typography.md +++ b/pages/css/utilities/typography.md @@ -2,6 +2,8 @@ title: Typography path: utilities/typography status: Stable +source: 'https://github.com/primer/css/tree/master/modules/utilities/docs/typography.md' +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. diff --git a/src/alerts/README.md b/src/alerts/README.md index cfe682b9..23d4693f 100644 --- a/src/alerts/README.md +++ b/src/alerts/README.md @@ -35,118 +35,14 @@ $ npm run build ## Documentation - - -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 -
- Flash message goes here. -
-``` - -You can put multiple paragraphs of text in a flash message—the last paragraph's bottom `margin` will be automatically override. - -```html -
-

This is a longer flash message in it's own paragraph. It ends up looking something like this. If we keep adding more text, it'll eventually wrap to a new line.

-

And this is another paragraph.

-
-``` - -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 -
-
- Flash message goes here. -
-
-``` - -## Variations - -Add `.flash-warn`, `.flash-error`, or `.flash-success` to the flash message to make it yellow, red, or green, respectively. - -```html -
- Flash message goes here. -
-``` - -```html -
- Flash message goes here. -
-``` - -```html -
- Flash message goes here. -
-``` - -## With icon - -Add an icon to the left of the flash message to give it some funky fresh attention. - -```erb -
- <%= octicon "alert" %> - Flash message with an icon goes here. -
-``` - -## With dismiss - -Add a JavaScript enabled (via Crema) dismiss (close) icon on the right of any flash message. - -```erb -
- - Dismissable flash message goes here. -
-``` - -## With action button - -A flash message with an action button. - -```html -
- - Flash message with action here. -
-``` - -## Full width flash - -A flash message that is full width and removes border and border radius. - -```html -
-
- Full width flash message. -
-
-``` - - +Find further documentation at [primer.style/css/components/alerts](https://primer.style/css/components/alerts). ## License [MIT](./LICENSE) © [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/ diff --git a/src/avatars/README.md b/src/avatars/README.md index b6c6fe2d..19be0828 100644 --- a/src/avatars/README.md +++ b/src/avatars/README.md @@ -35,168 +35,14 @@ $ npm run build ## Documentation - - -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 `` 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 -jonrohan -``` - -### 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 -jonrohan -``` - -### Parent-child avatars - -When you need a larger parent avatar, and a smaller child one, overlaid slightly, use the parent-child classes. - -```html -
- jonrohan - josh -
-``` - -### 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 -
-
- @octocat - @octocat - @octocat -
-
-``` - -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 -
-
- @octocat - @octocat -
- @octocat - @octocat - @octocat -
-
-``` - -You can also link individual avatars. To do this shift the `avatar` class over to the anchor: - -```html -
-
- - @octocat - - - @octocat - -
-
-``` - -Use `AvatarStack--right` to right-align the avatar stack. Remember to switch the alignment of tooltips when making this change. - -```html -
-
- @octocat - @octocat - @octocat -
-
-``` - -## 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 - - - - - <%= octicon "zap", :class => "CircleBadge-icon text-white" %> - -``` - -### Medium - -```html -
- Travis CI -
-``` - -### Large - -```html -
- Travis CI -
-``` - -### 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 -
-
    -
  • - <%= octicon "mark-github", :class => "width-full height-full" %> -
    • - -
  • - -
    • - -
  • - -
    • -
-
-``` - - +Find further documentation at [primer.style/css/components/avatars](https://primer.style/css/components/avatars). ## License [MIT](./LICENSE) © [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/ diff --git a/src/base/README.md b/src/base/README.md index 2f060b3d..fd41bac5 100644 --- a/src/base/README.md +++ b/src/base/README.md @@ -42,7 +42,7 @@ You can read more about base in the [docs][docs]. [MIT](./LICENSE) © [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/ diff --git a/src/blankslate/README.md b/src/blankslate/README.md index 06a49773..790a3d6d 100644 --- a/src/blankslate/README.md +++ b/src/blankslate/README.md @@ -35,105 +35,14 @@ $ npm run build ## Documentation - - -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 -
-

This is a blank slate

-

Use it to provide information when no dynamic content exists.

-
-``` - -#### 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 -
- <%= octicon "git-commit", :height => 32, :class => "blankslate-icon" %> - <%= octicon "tag", :height => 32, :class => "blankslate-icon" %> - <%= octicon "git-branch", :height => 32, :class => "blankslate-icon" %> -

This is a blank slate

-

Use it to provide information when no dynamic content exists.

-
-``` - -#### 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 -
-

This is a blank slate

-

Use it to provide information when no dynamic content exists.

-
-``` - -##### Capped - -Removes the `border-radius` on the top corners. - -```html -
-

This is a blank slate

-

Use it to provide information when no dynamic content exists.

-
-``` - -##### Spacious - -Significantly increases the vertical padding. - -```html -
-

This is a blank slate

-

Use it to provide information when no dynamic content exists.

-
-``` - -##### Large - -Increases the size of the text in the blankslate - -```html -
-

This is a blank slate

-

Use it to provide information when no dynamic content exists.

-
-``` - -##### No background - -Removes the `background-color` and `border`. - -```html -
-

This is a blank slate

-

Use it to provide information when no dynamic content exists.

-
-``` - +Find further documentation at [primer.style/css/components/blankslate](https://primer.style/css/components/blankslate). ## License [MIT](./LICENSE) © [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/ diff --git a/src/box/README.md b/src/box/README.md index 02fd9dd0..8569f123 100644 --- a/src/box/README.md +++ b/src/box/README.md @@ -35,564 +35,14 @@ $ npm run build ## Documentation - - -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 -
- This is a box. -
-``` - -## 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 -
-
-

- Box title -

-
-
- Box body -
-
- Box footer -
-
-``` - -### 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 -
-
    -
  • - Box row one -
    • -
  • - Box row two -
    • -
  • - Box row three -
    • -
  • - Box row four -
    • -
-
-``` - - -Rows can be used with or without `Box-header`, `Box-footer`, or `Box-body`. - -```html -
-
- Box header -
-
- Box body -
-
    -
  • - Box row one -
    • -
  • - Box row two -
    • -
  • - Box row three -
    • -
  • - Box row four -
    • -
-
- Box footer -
-
-``` - -### 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 `
` for your rows, you may want to place your rows inside a parent `
` so that the first and last rows are styled appropriately. - -```html -
-
- Box header -
- -
-
Box row using a div
-
Box row using a 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 -
-
-

- Box title -

-
-
- Box body -
-
    -
  • - Box row one -
    • -
  • - Box row two -
    • -
-
- Box footer -
-
-``` - -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 -
-
-

- Box title -

-
-
- Box body -
-
    -
  • - Box row one -
    • -
  • - Box row two -
    • -
-
- Box footer -
-
-``` - -## Blue box theme -Use `Box--blue` to style the box borders and box header in blue. - -```html -
-
- Box header -
-
    -
  • - Box row one -
    • -
  • - Box row two -
    • -
-
- Box footer -
-
-``` - -## Blue box header theme - -Use `Box-header--blue` to add to change the header border and background to blue. - -```html -
-
-

Box with blue header

-
-
- Box body -
-
-``` - -## 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 -
-
- Row one -
-
- Row two -
-
-``` - -`Box-danger` is often paired with a red heading. See the [subhead](./subhead) docs for more information. - -```html -
-

Danger zone

-
- -
-
- Box body -
-
-``` - -## Row themes -You can change the background color for individual rows, or change the color on hover or navigation focus. - - -```html -
-
- .Box-row--gray -
-
- .Box-row--hover-gray -
-
- .Box-row--yellow -
-
- .Box-row--hover-blue -
-
- .Box-row--blue -
-
-``` - -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 -
-
- .Box-row--focus-gray and .navigation-focus -
-
- .Box-row--focus-gray -
-
- .Box-row--focus-blue and .navigation-focus -
-
- .Box-row--focus-blue -
-
-``` - -### Box row unread -Use `.Box-row-unread` to apply a blue vertical line highlight for indicating a row contains unread items. - -```html -
-
- Box row -
-
- Box row unread -
-
- Box row -
-
-``` - -### 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 -
-
- Box row link -
-
-``` - -## Dashed border -Use the `border-dashed` utility to apply a dashed border to a box. - -```html -
- A box with a dashed border -
-``` - -## 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 -
-
- Box header -
-
- - Flash message with close button. -
-
- <%= octicon("check") %> Flash success with an icon. -
-
- <%= octicon("alert") %> Flash warning with an icon. -
-
- Flash error inside a Box. -
-
- Box body -
-
-``` - -## 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 -
-
- Box body - -
-
-``` - -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 -
-
- -

A very long title that wraps onto multiple lines without overlapping or wrapping underneath the icon to it's right

-
-
- Box body -
-
-``` - -```erb -
-
- -

A very long paragraph that wraps onto multiple lines without overlapping or wrapping underneath the icon to it's left

-
-
-``` - -## 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 -
-
-

- Box title - 12 -

-
-
- Box body -
-
-``` - -Use `Counter--gray-dark` for a counter with a dark gray background and white text. - -```html -
-
-

- Box title - 12 -

-
-
- Box body -
-
-``` - -## 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 -
-
-

- Box title -

- -
-
- Box body -
-
-``` - -A similar approach can be used for buttons with multiple lines of text within a row. - -```html -
-
-
- Row title -
- Description -
-
- -
-
-
- Row title -
- Description -
-
- -
-
-
- Row title -
- Description -
-
- -
-
-``` -Using flexbox along with form, button, and link styles, you can create more complex box headers for things like bulk actions and sorting. - -```html -
-
-
- -
- -
-
- Box body -
-
-``` - -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 -
-
-

- Example form title -

-
-
-
-
-
-
-
-
- -
-
-
- - -
-
-
-``` - -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 -
-
-
-

- Example form -

-
-
-
-
- -
-
-
-``` - -Box patterns can also be made with, and modified with [border utilities](/css/utilities/borders). - - +Find further documentation at [primer.style/css/components/box](https://primer.style/css/components/box). ## License [MIT](./LICENSE) © [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/ diff --git a/src/branch-name/README.md b/src/branch-name/README.md index d26d5361..1c81af51 100644 --- a/src/branch-name/README.md +++ b/src/branch-name/README.md @@ -35,39 +35,14 @@ $ npm run build ## Documentation - - -Branch names can be a link name or not: - -```html title="Branch name" -a_new_feature_branch -``` - -```html title="Branch name with link" -a_new_feature_branch -``` - -You may also include an octicon before the branch name text: - -```erb title="Branch name with icon" - - <%= octicon("git-branch", width:16, height:16) %> - a_new_feature_branch - -``` - - +Find further documentation at [primer.style/css/components/branch-name](https://primer.style/css/components/branch-name). ## License [MIT](./LICENSE) © [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/ diff --git a/src/breadcrumb/README.md b/src/breadcrumb/README.md index 95df1f20..7f2ffc32 100644 --- a/src/breadcrumb/README.md +++ b/src/breadcrumb/README.md @@ -9,31 +9,7 @@ This repository is a module of the full [primer][primer] repository. ## Documentation - - -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" - -``` - - +Find further documentation at [primer.style/css/components/breadcrumb](https://primer.style/css/components/breadcrumb). ## License @@ -42,7 +18,7 @@ MIT © [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/ diff --git a/src/buttons/README.md b/src/buttons/README.md index 790e48b8..20a7cd12 100644 --- a/src/buttons/README.md +++ b/src/buttons/README.md @@ -35,244 +35,14 @@ $ npm run build ## Documentation - - -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 ` -Link button -``` - -You can find them in two sizes: the default `.btn` and the smaller `.btn-sm`. - -```html - - -``` - -## 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 - - -``` - -## 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 - - -``` - -## Outline button - -Outline buttons downplay an action as they appear like boxy links. Just add `.btn-outline` and go. - -```html - - -``` - -## 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 -

- Large link button - -

- -``` - -Use `.btn-large` with a type scale utility to transform the text to a bigger size. - -```html -

- Large link button - -

-``` - -## Disabled state - -Disable ` -Disabled button -``` - -Similar styles are applied to primary, danger, and outline buttons: - -```html - -Disabled button -``` - -```html - -Disabled button -``` - -```html - -Disabled button -``` - -## 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 -

-

-``` - -## Link button - -Create a button that looks like a link with `.btn-link`. Rather than using an `` to trigger JS, this style on a `

-``` - -## 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 -
- - <%= octicon "eye" %> - Watch - - -
-``` - -You can also use the [counter](./labels#counters) component within buttons: - -```html - - - - - - - -``` - -## 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 -
- - - -
- -
- - - -
- -
- - - -
-``` - -Add `.BtnGroup-parent` to parent elements, like `
`s or `
`s, within `.BtnGroup`s for proper spacing and rounded corners. - -```html -
- - - - - - -
-``` - -## Hidden text button - -Use `.hidden-text-expander` to indicate and toggle hidden text. - -```html - - - -``` - -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 -[``](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 -[`
`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details) -element is open. - -```html -
- Toggle the content -

- This content will be toggled. -

-
-``` - - +Find further documentation at [primer.style/css/components/buttons](https://primer.style/css/components/buttons). ## License [MIT](./LICENSE) © [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/ diff --git a/src/core/README.md b/src/core/README.md index c0c4b825..400e30c6 100644 --- a/src/core/README.md +++ b/src/core/README.md @@ -42,7 +42,7 @@ You can read more about primer in the [docs][docs]. [MIT](./LICENSE) © [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/ diff --git a/src/forms/README.md b/src/forms/README.md index 0da308d3..c6db5c6d 100644 --- a/src/forms/README.md +++ b/src/forms/README.md @@ -35,317 +35,14 @@ $ npm run build ## Documentation - - -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 `
`s, WebKit validation bubbles, and most textual ``s. -- Specific types of textual ``s are styled automatically, but `.form-control` is available should you need it. -- Always declare a `type` on your ` - - - - -

- -

- - - - -

-``` - -#### Example form - -Form controls in Primer currently have no basic layout specified (this is by design). You'll need to use `
`s, `
`s, or other elements and styles to rearrange them. - -```html -
- - - - - - - - - - - - -
-``` - -#### Form contrast - -Textual form controls have a white background by default. You can change this to a light gray with `.input-contrast`. - -```html -
- - -
-``` - -#### Sizing - -Make inputs smaller, larger, or full-width with an additional class. - -##### Small - -```html -
- -
-``` - -##### Large - -```html -
- -
-``` - -##### Block - -```html -
- -
-``` - -##### 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 -
- -
-``` - -#### Selects - -Primer adds light `height` and `vertical-align` styles to ` - - - - - - - - - -``` - -##### Small - -Use the `.select-sm` class to resize both default and custom ` - - - - - - - - - - -``` - -#### Form groups - -```html -
-
-
-
-
- -
-
-
- -
-
- -
-
-
- -
-
-
-``` - -#### Form group validation - -Convey errors and warnings for form groups. Add the appropriate class—either `.errored` or `.warn`—to the `
` to start. Then, house your error messaging in an additional `
` with either `.error` or `.warning`. - -```html -
-
-
-
-
This example input has an error.
-
-
-
-
-
-
This example input has a warning.
-
-
-``` - -#### Checkboxes and radios - -Utilities to spice up the alignment and styling of checkbox and radio controls. - -```html -
-
- -

- This will do insanely awesome and amazing things! -

-
-
-``` - -You may also add emphasis to the label: - -```html -
-
- -
-
-``` - -##### 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 -
-
- -
-
- -
-
-``` - -#### Input group - -Attached an input and button to one another. - -```erb -
-
- - - - -
-
-``` - -#### 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 -
- - -
-``` - +Find further documentation at [primer.style/css/components/forms](https://primer.style/css/components/forms). ## License [MIT](./LICENSE) © [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/ diff --git a/src/labels/README.md b/src/labels/README.md index d042cac7..fd7f3df2 100644 --- a/src/labels/README.md +++ b/src/labels/README.md @@ -35,153 +35,14 @@ $ npm run build ## Documentation - - -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" -default label -``` - -**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" - -New select componentdesign -``` - -### 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" -gray label -``` - -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" -dark gray label -``` - -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" -orange label -``` - -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" -outlined label -``` - -Use `Label--outline-green` in combination with `Label--outline` to communicate a positive message. - -```html title="Label outline green" -green outlined label -``` - - -## 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" -Default -``` - -### 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" -<%= octicon "git-pull-request" %> Open -<%= octicon "git-pull-request" %> Closed -<%= octicon "git-merge" %> Merged -``` - -**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" -<%= octicon "issue-opened" %> Open -<%= octicon "issue-closed" %> Closed -``` - -## 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" -16 -32 -64 -``` - -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" -
- -
-``` - -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" -
-
-

- Box title - 3 -

-
-
    -
  • - Box row one -
    • -
  • - Box row two -
    • -
  • - Box row three -
    • -
-
-``` - - - +Find further documentation at [primer.style/css/components/labels](https://primer.style/css/components/labels). ## License [MIT](./LICENSE) © [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/ diff --git a/src/layout/README.md b/src/layout/README.md index f31dff42..e763dd08 100644 --- a/src/layout/README.md +++ b/src/layout/README.md @@ -35,103 +35,14 @@ $ npm run build ## Documentation - - -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" -
- Container -
-``` - -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 `
`. -- Add your columns with individual `
`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" -
-
-
- .one-fifth -
-
- .four-fifths -
-
- -
-
- .one-fourth -
-
- .three-fourths -
-
- -
-
- .one-third -
-
- .two-thirds -
-
- -
-
- .one-half -
-
- .one-half -
-
-
-``` - -##### Centered - -Columns can be centered by adding `.centered` to the `.column` class. - -```html title="Grid centered" -
-
- .one-half -
-
-``` - +Find further documentation at [primer.style/css/objects/layout](https://primer.style/css/objects/layout). ## License [MIT](./LICENSE) © [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/ diff --git a/src/markdown/README.md b/src/markdown/README.md index 26bd4c5f..75b3ea53 100644 --- a/src/markdown/README.md +++ b/src/markdown/README.md @@ -35,185 +35,14 @@ $ npm run build ## Documentation - - -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. - -
-
Name
-
Godzilla
-
Born
-
1952
-
Birthplace
-
Japan
-
Color
-
Green
-
- ----------------- - -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. -``` - +Find further documentation at [primer.style/css/components/markdown](https://primer.style/css/components/markdown). ## License [MIT](./LICENSE) © [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/ diff --git a/src/marketing/README.md b/src/marketing/README.md index f0f2ba58..cbbe1a5a 100755 --- a/src/marketing/README.md +++ b/src/marketing/README.md @@ -42,7 +42,7 @@ You can read more about primer in the [docs][docs]. [MIT](./LICENSE) © [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/ diff --git a/src/marketing/buttons/README.md b/src/marketing/buttons/README.md index 5040e70a..a55ae6c4 100644 --- a/src/marketing/buttons/README.md +++ b/src/marketing/buttons/README.md @@ -9,43 +9,7 @@ This repository is a module of the full [primer][primer] repository. ## Documentation - - -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 - - - -
- -
-``` - -## Sizes - -Available in two sizes, marketing buttons have a default size and a large size. - -```html - - - - - - -``` - - +Find further documentation at [primer.style/css/utilities/marketing-buttons](https://primer.style/css/utilities/marketing-buttons). ## Install @@ -80,7 +44,7 @@ MIT © [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/ diff --git a/src/marketing/support/README.md b/src/marketing/support/README.md index 01fdee66..13e8c2ae 100644 --- a/src/marketing/support/README.md +++ b/src/marketing/support/README.md @@ -29,36 +29,14 @@ You can also import specific portions of the module by importing those partials ## Documentation - - -### 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). - - +Find further documentation at [primer.style/css/support/marketing-variables](https://primer.style/css/support/marketing-variables). ## License MIT © [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/ diff --git a/src/marketing/type/README.md b/src/marketing/type/README.md index d05ceb1e..401a4f57 100644 --- a/src/marketing/type/README.md +++ b/src/marketing/type/README.md @@ -9,46 +9,7 @@ This repository is a module of the full [primer][primer] repository. ## Documentation - - -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" - -

Heading 000

-

Heading 00

-

Heading 0

-

Heading 1

-

Heading 2

-

Heading 3

-

Heading 4

-

Heading 5

-

Heading 6

- -``` - -## Typographic Utilities - -These utilities are meant to be used in addition to Primer's core utilities. - -```html title="Typographic Utilities" - -

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.

- -

I'm a pullquote. Someone said these words in real life, and now they're on the internet

- -``` - - +Find further documentation at [primer.style/css/utilities/marketing-type](https://primer.style/css/utilities/marketing-type). ## Install @@ -83,7 +44,7 @@ MIT © [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/ diff --git a/src/marketing/utilities/README.md b/src/marketing/utilities/README.md index 4d9f5764..97a3370a 100644 --- a/src/marketing/utilities/README.md +++ b/src/marketing/utilities/README.md @@ -33,14 +33,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) © [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/ diff --git a/src/navigation/README.md b/src/navigation/README.md index b7f0de71..cb4f1385 100644 --- a/src/navigation/README.md +++ b/src/navigation/README.md @@ -35,332 +35,14 @@ $ npm run build ## Documentation - - -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" - -``` - -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" - -``` - -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" - -``` - -## 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" - -``` - -Use `.UnderlineNav-actions` to place another element, such as a button, to the opposite side of the navigation items. - -```html title="UnderlineNav-actions" - -``` - -Use `.UnderlineNav--right` to right align the navigation. - -```html title="UnderlineNav--right" - -``` - -`.UnderlineNav--right` also works with when used with `.UnderlineNav-actions`. - -```html title="UnderlineNav--right with actions" - -``` - - -`.Counters` and `.octicons` can be used with navigation items. Use `.UnderlineNav-octicon` to add color and hover styles. - -```erb title="UnderlineNav with Counter" - -``` - -Use `.UnderlineNav--full` in combination with container styles and `.UnderlineNav-container` to make navigation fill the width of the container. - -```html title="UnderlineNav--full" - -``` - -## 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" -
- -
-``` - -Use `.float-right` to align additional elements in the `.tabnav`: - -```html title="tabnav with buttons" -
- Button - -
-``` - -Additional bits of text and links can be styled for optimal placement with `.tabnav-extra`: - -```html title="tabnav-extra" -
-
- Tabnav widget text here. -
- -
-``` - -```html title="tabnav with everything" -
-
- - Tabnav extra link - - - Tabnav extra link - -
- -
-``` - -## 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" - -``` - -## 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" - -``` - -You can have `subnav-search` in the subnav bar. - -```erb title="subnav-search" -
- -
- - <%= octicon "search", :class => "subnav-search-icon" %> -
-
-``` - - -You can also use a `subnav-search-context` to display search help in a select menu. - -```erb title="subnav-search-context" -
- -
- - -
-
- - <%= octicon "search", :class => "subnav-search-icon" %> -
-
-``` - - - +Find further documentation at [primer.style/css/components/navigation](https://primer.style/css/components/navigation). ## License [MIT](./LICENSE) © [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/ diff --git a/src/pagination/README.md b/src/pagination/README.md index ef5f465b..b0a88af9 100644 --- a/src/pagination/README.md +++ b/src/pagination/README.md @@ -35,55 +35,4 @@ $ npm run build ## Documentation - - -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 - -``` - -## 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 - -``` - - +Find further documentation at [primer.style/css/components/pagination](https://primer.style/css/components/pagination). diff --git a/src/popover/README.md b/src/popover/README.md index da92dbff..124541ab 100644 --- a/src/popover/README.md +++ b/src/popover/README.md @@ -35,252 +35,15 @@ $ npm run build ## Documentation - +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)" -
- -
-
-

Popover heading

-

Message about this particular piece of UI.

- -
-
-
-``` - -### Large example - -```html title="Large" -
- -
-
-

Popover heading

-

Message about this particular piece of UI.

- -
-
-
-``` - -### Bottom - -```html title="Bottom" -
-
-
-

Popover heading

-

Message about this particular piece of UI.

- -
-
- -
-``` - -### Bottom-right - -```html title="Bottom-right" -
-
-
-

Popover heading

-

Message about this particular piece of UI.

- -
-
- -
-``` - -### Bottom-left - -```html title="Bottom-left" -
-
-

Popover heading

-

Message about this particular piece of UI.

- -
-
- -``` - -### Left - -```html title="Left" -
- -
-
-

Popover heading

-

Message about this particular piece of UI.

- -
-
-
-``` - -### Left-bottom - -```html title="Left-bottom" -
- -
-
-

Popover heading

-

Message about this particular piece of UI.

- -
-
-
-``` - -### Left-top - -```html title="Left-top" -
- -
-
-

Popover heading

-

Message about this particular piece of UI.

- -
-
-
-``` - -### Right - -```html title="Right" -
-
-
-

Popover heading

-

Message about this particular piece of UI.

- -
-
- -
-``` - -### Right-bottom - -```html title="Right-bottom" -
-
-
-

Popover heading

-

Message about this particular piece of UI.

- -
-
- -
-``` - -### Right-top - -```html title="Right-top" -
-
-
-

Popover heading

-

Message about this particular piece of UI.

- -
-
- -
-``` - -### Top-left - -```html title="Top-left" -
- -
-
-

Popover heading

-

Message about this particular piece of UI.

- -
-
-
-``` - -### Top-right - -```html title="Top-right" -
- -
-
-

Popover heading

-

Message about this particular piece of UI.

- -
-
-
-``` - - ## License [MIT](./LICENSE) © [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/ diff --git a/src/product/README.md b/src/product/README.md index 204718bd..38135077 100644 --- a/src/product/README.md +++ b/src/product/README.md @@ -42,7 +42,7 @@ You can read more about primer in the [docs][docs]. [MIT](./LICENSE) © [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/ diff --git a/src/progress/README.md b/src/progress/README.md index 92b471ef..1912ec64 100644 --- a/src/progress/README.md +++ b/src/progress/README.md @@ -34,68 +34,15 @@ $ npm run build ``` ## Documentation - +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 - - - -``` - -## Large Progress - -```html - - - -``` - -## Small Progress - -```html - - - -``` - -## Progress with tooltip - -```html -
- - - -
-``` - -## Progress with multiple values - -```html -
- - - - - -
-``` - - ## License [MIT](./LICENSE) © [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/ diff --git a/src/subhead/README.md b/src/subhead/README.md index 5b71b1b7..d7abc93d 100644 --- a/src/subhead/README.md +++ b/src/subhead/README.md @@ -35,91 +35,15 @@ $ npm run build ## Documentation - +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 `

` 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" -
-
Plain subhead
-
-``` - -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" -
-
Spacious subhead
-
-``` - -You can add a one line description to the subhead with `.Subhead-description`. - -```html title="Subhead with description" -
-
Subhead with description
-
The subhead is a subdued header style with a light bottom border.
-
-``` - -For longer descriptions, it is recommended that you use a paragraph below the Subhead. - -```html title="Subhead with longer description" -
-
Plain subhead
-
-

- 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 bold text. Click to learn more. -

-``` - -You can add a button or something to the right of `.Subhead-heading` with the `.Subhead-actions` element. - -```html title="Subhead with actions" -
-
Subhead with button
-
Action
-
- -
-
Subhead with link
-
Learn more
-
-``` - -Use all the elements together to create a Subhead with actions and a description. - -```html title="Subhead with actions and description" -
-
Subhead with actions and description
-
Action
-
The subhead is a subdued header style with a light bottom border.
-
-``` - -Use the `.Subhead-heading--danger` modifier to make the text bold and red. This is useful for warning users. - -```html title="Subhead danger" -
-
Danger zone
-
-``` - - ## License [MIT](./LICENSE) © [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/ diff --git a/src/support/README.md b/src/support/README.md index ef8d9d03..a2d58f7f 100644 --- a/src/support/README.md +++ b/src/support/README.md @@ -29,30 +29,14 @@ You can also import specific portions of the module by importing those partials ## Documentation - - -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) - - +Find further documentation at [primer.style/css/support](https://primer.style/css/support). ## License [MIT](./LICENSE) © [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/ diff --git a/src/table-object/README.md b/src/table-object/README.md index 4e390faa..d65e6839 100644 --- a/src/table-object/README.md +++ b/src/table-object/README.md @@ -35,35 +35,15 @@ $ npm run build ## Documentation - +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" -
-
- -
-
- -
-
-``` - - ## License [MIT](./LICENSE) © [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/ diff --git a/src/tooltips/README.md b/src/tooltips/README.md index cb76229c..e66ffd2e 100644 --- a/src/tooltips/README.md +++ b/src/tooltips/README.md @@ -35,124 +35,15 @@ $ npm run build ## Documentation - +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 - - Tooltip North - - - Tooltip North East - - - Tooltip East - - - Tooltip South East - - - Tooltip South - - - Tooltip South West - - - Tooltip West - - - Tooltip North West - -``` - -## Tooltip alignment -Align tooltips to the left or right of an element, combined with a directional class to specify north or south. - -```html - - Tooltip North East align left 1 - - - Tooltip North East align left 2 - - - Tooltip South East align left 1 - - - Tooltip South East align left 2 - - - Tooltip North West align right 1 - - - Tooltip North West align right 2 - - - Tooltip South West align right 1 - - - Tooltip South West align right 2 - -``` - -## 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 - - Tooltip with multiple lines - -``` - -## 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 - - Tooltip no delay - -``` - - ## License [MIT](./LICENSE) © [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/ diff --git a/src/truncate/README.md b/src/truncate/README.md index 67e44f22..f97d63e2 100644 --- a/src/truncate/README.md +++ b/src/truncate/README.md @@ -35,35 +35,15 @@ $ npm run build ## Documentation - +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" - - really-long-branch-name - -``` - -You can reveal the entire string on hover with the addition of `.expandable`. - -```html title="Truncate Expandable" - -``` - ## License [MIT](./LICENSE) © [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/ diff --git a/src/utilities/README.md b/src/utilities/README.md index 7e6c72ab..5f7b1085 100644 --- a/src/utilities/README.md +++ b/src/utilities/README.md @@ -35,14 +35,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) © [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/