diff --git a/CHANGELOG.md b/CHANGELOG.md index c2071607e5..c02526e8ed 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,39 @@ # @primer/css +## 21.0.7 + +### Patch Changes + +- [#2472](https://github.com/primer/css/pull/2472) [`3ee117e1`](https://github.com/primer/css/commit/3ee117e1bd67675a5bdc2739bbe4d05f4e297c30) Thanks [@simurai](https://github.com/simurai)! - Add `::selection` to `color-mode-theme()` mixin + +## 21.0.6 + +### Patch Changes + +- [#2470](https://github.com/primer/css/pull/2470) [`03e1a26c`](https://github.com/primer/css/commit/03e1a26c0d4fcc85450998f0f1f8120a1db48acc) Thanks [@langermank](https://github.com/langermank)! - Revert #2461 default selection color + +## 21.0.5 + +### Patch Changes + +- [#2468](https://github.com/primer/css/pull/2468) [`c6d5d1df`](https://github.com/primer/css/commit/c6d5d1dfd3eafe44197ddc262f605dc5373437ac) Thanks [@keithamus](https://github.com/keithamus)! - Fix bug with `color-mode` mixin not applying correctly due to `::selection` + +## 21.0.4 + +### Patch Changes + +- [#2466](https://github.com/primer/css/pull/2466) [`92047014`](https://github.com/primer/css/commit/9204701416b547255a1ebaeb2bd8a20056ffb8d4) Thanks [@langermank](https://github.com/langermank)! - Use `@primer/primitives` v8 colors with fallbacks + +## 21.0.3 + +### Patch Changes + +- [#2461](https://github.com/primer/css/pull/2461) [`abc89659`](https://github.com/primer/css/commit/abc8965913313bbb969db9e1148fb5add9327ec9) Thanks [@langermank](https://github.com/langermank)! - Add default `::selection` color + +- [#2410](https://github.com/primer/css/pull/2410) [`344224fc`](https://github.com/primer/css/commit/344224fccdef2f3a37ed931c512e400b47301ea2) Thanks [@dylanatsmith](https://github.com/dylanatsmith)! - Add width utility to limit line length for readability + +- [#2457](https://github.com/primer/css/pull/2457) [`352ed7b7`](https://github.com/primer/css/commit/352ed7b75585c686c996a5e7c2c29e20e41d0672) Thanks [@langermank](https://github.com/langermank)! - Add new PostCSS fallback config + ## 21.0.2 ### Patch Changes diff --git a/docs/.babelrc b/docs/.babelrc index 0f92253e91..f818248075 100644 --- a/docs/.babelrc +++ b/docs/.babelrc @@ -1,6 +1,14 @@ { + "sourceType": "unambiguous", "presets": [ - "babel-preset-gatsby", - "@babel/preset-react" + "@babel/preset-react", + [ + "@babel/preset-env", + { + "targets": { + "chrome": 100 + } + } + ] ] } diff --git a/docs/.eslintrc.json b/docs/.eslintrc.json index 9a7049fdd3..ee56e8262b 100644 --- a/docs/.eslintrc.json +++ b/docs/.eslintrc.json @@ -1,13 +1,17 @@ { "extends": [ "plugin:react/recommended", - "plugin:jsx-a11y/recommended" + "plugin:jsx-a11y/recommended", + "plugin:storybook/recommended" ], "rules": { "import/no-namespace": 0, - "no-unused-vars": ["error", { - "ignoreRestSiblings": true - }] + "no-unused-vars": [ + "error", + { + "ignoreRestSiblings": true + } + ] }, "settings": { "react": { diff --git a/docs/.storybook/main.js b/docs/.storybook/main.js index bbb2b0925a..f3d94c8810 100644 --- a/docs/.storybook/main.js +++ b/docs/.storybook/main.js @@ -1,17 +1,29 @@ -module.exports = { - stories: ['../src/**/*.stories.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'], +/** @type { import('@storybook/react-webpack5').StorybookConfig } */ +const config = { + stories: ['../stories/**/*.mdx', '../stories/**/*.stories.@(js|jsx|ts|tsx)'], addons: [ - '@storybook/addon-a11y', '@storybook/addon-links', '@storybook/addon-essentials', - '@storybook/preset-scss', - '@whitespace/storybook-addon-html', - 'storybook-addon-designs', - 'storybook-color-picker', - 'storybook-addon-variants/preset.js' + '@storybook/addon-interactions', + 'storybook-addon-pseudo-states', + '@storybook/addon-storysource', + '@geometricpanda/storybook-addon-badges', + { + name: '@storybook/addon-styling', + options: { + sass: { + implementation: require('sass'), + }, + }, + }, ], - framework: '@storybook/react', - core: { - builder: 'webpack5' - } + framework: { + name: '@storybook/react-webpack5', + options: {}, + }, + docs: { + autodocs: 'tag', + }, + staticDirs: ['../stories/static'], } +export default config diff --git a/docs/.storybook/manager.js b/docs/.storybook/manager.js new file mode 100644 index 0000000000..65340e9bc3 --- /dev/null +++ b/docs/.storybook/manager.js @@ -0,0 +1,6 @@ +import {addons} from '@storybook/manager-api' +import theme from './theme' + +addons.setConfig({ + theme: theme, +}) diff --git a/docs/.storybook/preview-head.html b/docs/.storybook/preview-head.html index da57830886..3ed18e9949 100644 --- a/docs/.storybook/preview-head.html +++ b/docs/.storybook/preview-head.html @@ -1,33 +1 @@ - + diff --git a/docs/.storybook/preview.css b/docs/.storybook/preview.css new file mode 100644 index 0000000000..de33cb81f0 --- /dev/null +++ b/docs/.storybook/preview.css @@ -0,0 +1,9 @@ +@import '@primer/primitives/tokens-next-private/css/base/size/size.css'; +@import '@primer/primitives/tokens-next-private/css/base/typography/typography.css'; +@import '@primer/primitives/tokens-next-private/css/functional/size/border.css'; +@import '@primer/primitives/tokens-next-private/css/functional/size/breakpoints.css'; +@import '@primer/primitives/tokens-next-private/css/functional/size/size-coarse.css'; +@import '@primer/primitives/tokens-next-private/css/functional/size/size-fine.css'; +@import '@primer/primitives/tokens-next-private/css/functional/size/size.css'; +@import '@primer/primitives/tokens-next-private/css/functional/size/viewport.css'; +@import '@primer/primitives/tokens-next-private/css/functional/typography/typography.css'; diff --git a/docs/.storybook/preview.js b/docs/.storybook/preview.js index fd79f60a29..3f2fcf7430 100644 --- a/docs/.storybook/preview.js +++ b/docs/.storybook/preview.js @@ -1,140 +1,54 @@ import '../../src/docs.scss' import '../../src/index.scss' import '../../src/base/index.scss' -import '../src/stories/helpers/storybook-styles.scss' -// temporary import until primitives moves to core bundle -// importing the index from /css didn't play nice with Storybook -import '@primer/primitives/tokens-next-private/css/base/size/size.css'; -import '@primer/primitives/tokens-next-private/css/base/typography/typography.css'; -import '@primer/primitives/tokens-next-private/css/functional/size/border.css'; -import '@primer/primitives/tokens-next-private/css/functional/size/breakpoints.css'; -import '@primer/primitives/tokens-next-private/css/functional/size/size-coarse.css'; -import '@primer/primitives/tokens-next-private/css/functional/size/size-fine.css'; -import '@primer/primitives/tokens-next-private/css/functional/size/size.css'; -import '@primer/primitives/tokens-next-private/css/functional/size/viewport.css'; -import '@primer/primitives/tokens-next-private/css/functional/typography/typography.css'; -import renderToHTML from '../src/stories/helpers/code-snippet-html-helper' +import './preview.css' +import './storybook.css' +import clsx from 'clsx' +import {BADGE, BadgesConfig} from '@geometricpanda/storybook-addon-badges' -const customViewports = { - minXS: { - name: 'XS (min)', - styles: { - width: '320px', - height: '100%' - } - }, - medXS: { - name: 'XS (med)', - styles: { - width: '375px', - height: '100%' - } - }, - maxXS: { - name: 'XS (max)', - styles: { - width: '543px', - height: '100%' - } - }, - minSM: { - name: 'SM (min)', - styles: { - width: '544px', - height: '100%' - } - }, - maxSM: { - name: 'SM (max)', - styles: { - width: '767px', - height: '100%' - } - }, - minMD: { - name: 'MD (min)', - styles: { - width: '768px', - height: '100%' - } - }, - maxMD: { - name: 'MD (max)', - styles: { - width: '1011px', - height: '100%' - } - }, - minLG: { - name: 'LG (min)', - styles: { - width: '1012px', - height: '100%' - } - }, - maxLG: { - name: 'LG (max)', - styles: { - width: '1279px', - height: '100%' - } - }, - minXL: { - name: 'XL (min)', - styles: { - width: '1280px', - height: '100%' - } - }, - medXL: { - name: 'XL (med)', - styles: { - width: '1440px', - height: '100%' - } - } -} - -export const parameters = { - actions: {argTypesRegex: '^on[A-Z].*'}, - docs: { - transformSource: (src, storyContext) => renderToHTML(storyContext.storyFn) - }, - controls: { - matchers: { - color: /(background|color)$/i, - date: /Date$/ +/** @type { import('@storybook/react').Preview } */ +const preview = { + parameters: { + actions: {argTypesRegex: '^on[A-Z].*'}, + controls: { + matchers: { + color: /(background|color)$/i, + date: /Date$/, + }, + }, + options: { + storySort: { + order: ['Introduction', 'GettingStarting', 'Contributing', 'Utilities'], + }, + }, + badgesConfig: { + [BADGE.DEPRECATED]: { + title: 'Deprecated', + tooltip: { + desc: 'Please use a Primer View Component instead', + links: [{title: 'See docs', href: 'https://primer.style/design/components'}], + }, + }, + [BADGE.OBSOLETE]: { + title: 'Outdated', + tooltip: { + desc: 'Information in this document may be outdated.', + }, + }, }, - expanded: true - }, - - layout: 'padded', - html: { - root: '#story' // target id for html tab (should be direct parent of for easy copy/paste) }, - viewport: {viewports: customViewports}, - options: { - storySort: (storyA, storyB) => { - if (storyA[1].title.includes('Examples')) { - // if both are stories, sort alphabetically - if (storyB[1].title.includes('Examples')) return -1 - // if only 1 is a story, push the examples story down - else return 1 - } - // sort as usual = alphabetical - return -1 - } - } } -const themes = [ - 'light', - 'light_colorblind', - 'light_high_contrast', - 'dark', - 'dark_dimmed', - 'dark_high_contrast', - 'dark_colorblind' +const primerThemes = [ + {value: 'light', left: '☀️', title: 'Light'}, + {value: 'light_colorblind', left: '☀️', title: 'Light Protanopia & Deuteranopia'}, + {value: 'light_tritanopia', left: '☀️', title: 'Light Tritanopia'}, + {value: 'light_high_contrast', left: '☀️', title: 'Light High Contrast'}, + {value: 'dark', left: '🌗', title: 'Dark'}, + {value: 'dark_dimmed', left: '🌗', title: 'Dark Dimmed'}, + {value: 'dark_colorblind', left: '🌗', title: 'Dark Protanopia & Deuteranopia'}, + {value: 'dark_tritanopia', left: '🌗', title: 'Dark Tritanopia'}, + {value: 'dark_high_contrast', left: '🌗', title: 'Dark High Contrast'}, ] export const globalTypes = { @@ -143,33 +57,58 @@ export const globalTypes = { description: 'Switch themes', defaultValue: 'light', toolbar: { - icon: 'circlehollow', - items: [...themes, 'all'], - showName: true - } - } + icon: 'contrast', + items: [...primerThemes, {value: 'all', left: '', title: 'All'}], + showName: true, + dynamicTitle: true, + }, + }, } export const decorators = [ (Story, context) => { + const {parameters} = context + const defaultStoryType = 'banner' + const storyType = parameters.storyType || defaultStoryType + document.body.setAttribute('data-color-mode', context.globals.theme.startsWith('light') ? 'light' : 'dark') + document.body.setAttribute( + 'data-light-theme', + context.globals.theme.startsWith('light') ? context.globals.theme : undefined, + ) + document.body.setAttribute( + 'data-dark-theme', + context.globals.theme.startsWith('dark') ? context.globals.theme : undefined, + ) return ( -
- {themes.map(theme => { - if (context.globals.theme === theme || context.globals.theme === 'all') { - return ( -
- + <> + {context.globals.theme === 'all' ? ( + primerThemes.map(({value: theme}) => ( +
+ + {context.globals.theme === 'all' &&

{theme}

} +
+ )) + ) : ( +
+ {/* {parameters.storyType === 'banner' && ( +
+ Note: For the most up to date component documentation and guidelines, please reference Primer's core + documentation site at primer.style.
- ) - } - })} -
+ )} */} + +
+ )} + ) - } + }, ] + +export default preview diff --git a/docs/.storybook/storybook.css b/docs/.storybook/storybook.css new file mode 100644 index 0000000000..508e16a502 --- /dev/null +++ b/docs/.storybook/storybook.css @@ -0,0 +1,60 @@ +.story-wrap { + font-family: var(--fontStack-system); + color: var(--fgColor-default); +} + +#storybook-preview-wrapper { + background-color: var(--bgColor-default) !important; + width: 100% !important; + height: 100% !important; +} + +.theme-wrap-grid { + display: grid; + grid-template-columns: repeat(4, minmax(var(--breakpoint-xsmall, 20rem), auto)); + grid-gap: 1px; + height: 100vh; +} + +.story-wrap-grid { + outline: 1px solid #d4d4d8; + padding-bottom: 40px; + position: relative; +} + +@media (max-width: calc(20rem * 4)) { + .theme-wrap-grid { + grid-template-columns: repeat(3, minmax(var(--breakpoint-xsmall, 20rem), auto)); + } +} + +@media (max-width: calc(20rem * 3)) { + .theme-wrap-grid { + grid-template-columns: repeat(2, minmax(var(--breakpoint-xsmall, 20rem), auto)); + } +} + +@media (max-width: calc(20rem * 2)) { + .theme-wrap-grid { + display: block; + } +} + +.theme-name { + position: absolute; + bottom: 0; + right: 0; + background-color: var(--bgColor-muted); + padding: var(--base-size-4) var(--base-size-8); + font: var(--text-caption-shorthand); + margin: 0; +} + +code { + padding: 0.2em 0.4em; + font-family: var(--fontStack-monospace); + font-size: var(--text-codeInline-size); + background-color: var(--bgColor-muted); + border-radius: var(--borderRadius-small); + font-weight: var(--base-text-weight-normal); +} diff --git a/docs/.storybook/theme.js b/docs/.storybook/theme.js new file mode 100644 index 0000000000..cf427d197c --- /dev/null +++ b/docs/.storybook/theme.js @@ -0,0 +1,13 @@ +import {create} from '@storybook/theming' +import packageJson from '../../package.json' + +export default create({ + brandTitle: ` +
+ + ${packageJson.name}@${packageJson.version} +
+ `, +}) diff --git a/docs/content/components/alerts.md b/docs/content/components/alerts.md deleted file mode 100644 index e2efe76b4e..0000000000 --- a/docs/content/components/alerts.md +++ /dev/null @@ -1,197 +0,0 @@ ---- -title: Alerts -path: components/alerts -status: Stable -source: 'https://github.com/primer/css/tree/main/src/alerts' -rails: 'https://primer.style/view-components/components/alpha/banner' -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 live -
- Flash message goes here. -
-``` - -You can put multiple paragraphs of text in a flash message—the last paragraph's bottom `margin` will be automatically overridden. - -```html live -
-

- 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 live -
-
- Flash message goes here. -
-
-``` - -## Colors - -Add `.flash-warn`, `.flash-error`, or `.flash-success` to the flash message to make it yellow, red, or green, respectively. - -```html live -
- Flash message goes here. -
- -
- Flash message goes here. -
- -
- Flash message goes here. -
- -
- Flash message goes here. -
-``` - -## With icon - -Add an icon to the left of the flash message to give it some funky fresh attention. - -```html live -
- - - Flash message with an icon -
- -
- - - Flash message with an icon -
- -
- - - Flash message with an icon -
- -
- - - Flash message with an icon -
-``` - -When using a `24px` icon, add a `.v-align-bottom` class and increase the font-size with `.f4` for a more balanced alignment. - -```html live -
- - - Flash message with a larger icon -
-``` - -## With dismiss - -Add a close icon on the right to allow users to dismiss a flash message. - -```html live -
- Dismissable flash message goes here. - -
- -
- Dismissable flash message goes here. - -
- -
- Dismissable flash message goes here. - -
- -
- Dismissable flash message goes here. - -
-``` - -## With action button - -A flash message with an action button. - -```html live -
- Flash message with action here. - -
- -
- Flash message with action here. - -
- -
- Flash message with action here. - -
- -
- - Flash message with action here. - -
-``` - -## Full width flash - -A flash message that is full width and removes border and border radius. - -```html live -
- Full width flash message. -
-``` - -## Flash banner - -A flash message that is fixed positioned at the top of the page. Use for more global events where the content of the page is unknown. - -```html live -
-
- Flash banner message. -
-
-``` diff --git a/docs/content/components/autocomplete.md b/docs/content/components/autocomplete.md deleted file mode 100644 index 3ef1b54a76..0000000000 --- a/docs/content/components/autocomplete.md +++ /dev/null @@ -1,450 +0,0 @@ ---- -title: Autocomplete -path: components/autocomplete -status: Stable -source: 'https://github.com/primer/css/tree/main/src/autocomplete' -bundle: autocomplete ---- - -A list of items used to show autocompleted results. Use the [``](https://github.com/github/auto-complete-element) element to add functionality. - -## Default (stacked label) - -```html live -
- - - -
    -
  • Option 1
    • -
  • Option 2
    • -
  • Option 3
    • -
- -
- - -``` - -## Inline label - -**Note**: On smaller screen sizes, the labels will be stacked. - -```html live -
- - - -
    -
  • Team 1 (works on Ruby architecture)
    • -
  • Team 2 (works on frontend JS architecture)
    • -
  • Team 3 (this team works on design systems)
    • -
- -
- - -``` - -## Embedded icon with visible label - -### Stacked label - -```html live -
- - -
- - -
-
    -
  • Option 1
    • -
  • Option 2
    • -
  • Option 3
    • -
- -
- - -``` - -### Inline label - -```html live -
- - -
- - -
-
    -
  • Option 1
    • -
  • Option 2
    • -
  • Option 3
    • -
- -
- - -``` - -## Embedded icon with hidden label - -```html live -
- - -
- - -
-
    -
  • Option 1
    • -
  • Option 2
    • -
  • Option 3
    • -
- -
- - -``` - -## Within form group - -```html live -
-
-
- - -
- - -
-
    -
  • Option 1
    • -
  • Option 2
    • -
  • Option 3
    • -
- -
-
-
- - -``` - -## Within input group - -When rendering `Autocomplete` with embedded icon within an [input group](https://primer.style/css/components/forms#input-group), add `.input-group-button--autocomplete-embedded-icon` to `.input-group-button`. - -### Stacked - -```html live -
-
- - -
- - -
-
    -
  • Option 1
    • -
  • Option 2
    • -
  • Option 3
    • -
- -
- - - -
- - -``` - -### Inline -```html live -
-
- - -
- - -
-
    -
  • Option 1
    • -
  • Option 2
    • -
  • Option 3
    • -
- -
- - - -
- - -``` - -## Container with `max-width` - -```html live -
-
-
-
-
- - -
- - -
-
    -
  • Option 1
    • -
  • Option 2
    • -
  • Option 3
    • -
- -
-
-
-
-
- - -``` - -## Additional content - -Autocomplete items can contain additional content, like an `.avatar`. Or use utility classes to customize the text style. - -```html live -
- -
    -
  • - - GitHub Inc. - @github -
    • -
  • - - Hubot - @hubot -
    • -
  • - - Monalisa Octocat - @octocat -
    • -
-
- - -``` - -## Suggester - -The `.suggester` component is meant for showing suggestions while typing in a larger text area. Use the [``](https://github.com/github/text-expander-element) element to add functionality. - -```html live -
- -
    -
  • - - - - - #924 Markdown tables are inaccessible -
    • -
  • - - - - - #980 Use actual book emoji in Flexbox docs -
    • -
  • - - - - - #979 Add `.radio-group` component -
    • -
  • - - - - - #925 Release 14.0.0 -
    • -
  • - - - - - #978 Add `.css-truncate-overflow` -
    • -
-
- - -``` diff --git a/docs/content/components/avatar-stack.md b/docs/content/components/avatar-stack.md deleted file mode 100644 index a9ac9a0b9d..0000000000 --- a/docs/content/components/avatar-stack.md +++ /dev/null @@ -1,152 +0,0 @@ ---- -title: AvatarStack -path: components/avatar-stack -status: Stable -source: 'https://github.com/primer/css/tree/main/src/avatars' -rails: 'https://primer.style/view-components/components/beta/avatarstack' -bundle: avatars ---- - -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 live -
-
- @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 live -
-
- @octocat - @octocat -
- @octocat - @octocat - @octocat -
-
-``` - -You can also link individual avatars. To do this shift the `avatar` class over to the anchor: - -```html live -
-
- - @octocat - - - @octocat - -
-
-``` - -Use `AvatarStack--right` to right-align the avatar stack. Remember to switch the alignment of tooltips when making this change. - -```html live -
-
- @octocat - @octocat - @octocat -
-
-``` diff --git a/docs/content/components/avatars.md b/docs/content/components/avatars.md deleted file mode 100644 index 298736fedd..0000000000 --- a/docs/content/components/avatars.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: Avatars -path: components/avatars -status: Stable -source: 'https://github.com/primer/css/tree/main/src/avatars' -rails: 'https://primer.style/view-components/components/beta/avatar' -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. - -## 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 live -jonrohan -``` - -### Small avatars - -We occasionally use smaller avatars. Anything less than `24px` wide should include the `.avatar-small` modifier class to reset the `border-radius` to a more appropriate level. - -```html live -jonrohan -``` - -### Avatar sizes - -Instead of using the `width` and `height` attribute, you can also use a class like `.avatar-[1-8]`. The sizes go from `16px` up to `64px`. Note: Avatar stacks are only supported for the `20px` avatar size. - -```html live -jonrohan -jonrohan -jonrohan -jonrohan -jonrohan -jonrohan -jonrohan -jonrohan -``` - -### Parent-child avatars - -When you need a larger parent avatar, and a smaller child one, overlaid slightly, use the parent-child classes. - -```html live -
- jonrohan - josh -
-``` - -## 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 - -```html live - - - - - - - -``` - -### Medium - -```html live -
- Travis CI -
-``` - -### Large - -```html live -
- 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. - -```html live -
-
    -
  • - - -
    • - -
  • - -
    • - -
  • - -
    • -
-
-``` diff --git a/docs/content/components/blankslate.md b/docs/content/components/blankslate.md deleted file mode 100644 index 516c435c5d..0000000000 --- a/docs/content/components/blankslate.md +++ /dev/null @@ -1,152 +0,0 @@ ---- -title: Blankslate -path: components/blankslate -status: Stable -source: 'https://github.com/primer/css/tree/main/src/blankslate' -rails: 'https://primer.style/view-components/components/beta/blankslate' -bundle: blankslate ---- - -Blankslates are for when there is a lack of content within a page or section. Use them as placeholders to tell users why something isn't there. Be sure to provide an action to add content as well. - -## Basic example - -Wrap some content in the outer `.blankslate` wrapper and add the `.blankslate-heading` class to headings to give it the blankslate appearance. - -```html live -
-

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 the `.blankslate-icon` class to give icons the proper styling. - -```html live -
- - -

This is a blank slate

-

Use it to provide information when no dynamic content exists.

-
-``` - -## With graphic, button and link - -Add a graphic, button and/or link to add additional information and provide users a way to add content to this page. Add the `.blankslate-image` class to the image, and the `.blankslate-action` to any button or link wrappers. - -```html live -
- -

You don’t seem to have any pull requests.

-

Pull requests help you discuss potential changes before they are merged into the base branch.

-
- -
-
- -
-
-``` - -## Variations - -Add an additional optional class to the `.blankslate` to change its appearance. - -### Narrow - -`.blankslate-narrow` narrows the blankslate container to not occupy the entire available width. - -```html live -
- -

You don’t seem to have any pull requests.

-

Pull requests help you discuss potential changes before they are merged into the base branch.

-
- -
-
- -
-
-``` - -### Large - -`.blankslate-large` increases the size of the text in the blankslate - -```html live -
- -

You don’t seem to have any pull requests.

-

Pull requests help you discuss potential changes before they are merged into the base branch.

-
- -
-
- -
-
-``` - -### Spacious - -`.blankslate-spacious` significantly increases the vertical padding. - -```html live -
- -

You don’t seem to have any pull requests.

-

Pull requests help you discuss potential changes before they are merged into the base branch.

-
- -
-
- -
-
-``` - -**Note**: It's possible to combine variations. Large and spacious (`blankslate blankslate-large blankslate-spacious`) is often used together. - -### Add border - -To add a border, wrap the blankslate component with the [Box component](/components/box). - -```html live -
-
- -

You don’t seem to have any pull requests.

-

Pull requests help you discuss potential changes before they are merged into the base branch.

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

You don’t seem to have any pull requests.

-

Pull requests help you discuss potential changes before they are merged into the base branch.

-
- -
-
- -
-
-
-``` diff --git a/docs/content/components/box-overlay.md b/docs/content/components/box-overlay.md deleted file mode 100644 index 57760f88b0..0000000000 --- a/docs/content/components/box-overlay.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Box overlay -path: components/box-overlay -status: Alpha -status_issue: 'https://github.com/github/design-systems/issues/374' -source: 'https://github.com/github/github/tree/master/app/assets/stylesheets/components/box-overlay.scss' -rails: 'https://primer.style/view-components/components/alpha/dialog' -symbols: [Box--overlay, Box-header, Box-overlay--narrow, Box-overlay--wide] -keywords: [box, overlay] ---- - -Use the `Box--overlay` with the `
` and [``](https://github.com/github/details-dialog), and add the `details-overlay-dark` utility if you wish to apply a dark transparent background. - -Box overlays come in three widths. The default `Box--overlay` is 440px wide, `Box-overlay--narrow` is 320px wide, and `Box-overlay--wide` is 640px wide. - -```html live - -
- Open dialog - -
- -

Box title

-
-
-
-

- The quick brown fox jumps over the lazy dog and feels as if he were in the seventh heaven of typography together with Hermann Zapf, the most famous artist of the... -

-
-
    -
  • - broccolini - @broccolini -
    • -
  • - jonrohan - @jonrohan -
    • -
  • - shawnbot - @shawnbot -
    • -
-
-
- -
- -
- - - - -``` - -[aria attributes]: https://www.w3.org/TR/html-aria/#allowed-aria-roles-states-and-properties diff --git a/docs/content/components/box.md b/docs/content/components/box.md deleted file mode 100644 index 8ab9eee4e0..0000000000 --- a/docs/content/components/box.md +++ /dev/null @@ -1,579 +0,0 @@ ---- -title: Box -path: components/box -status_issue: 'https://github.com/github/design-systems/issues/198' -status: Stable -source: 'https://github.com/primer/css/tree/main/src/box' -rails: 'https://primer.style/view-components/components/beta/borderbox' -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. - -## Box - -A `.Box` is a container with 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 live -
- 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 live -
-
-

- 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 live -
-
    -
  • - 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 live -
-
- 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 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 live -
-
- 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 live -
-
-

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

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

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

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 live -
-
- .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 live -
-
- .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 live -
-
- 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 live -
-
- Box row link -
-
-``` - -## Dashed border - -Use the `border-dashed` utility to apply a dashed border to a box. - -```html live -
- 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. - -```html live -
-
- Box header -
-
- - Flash message with close button. -
-
- - - Flash success with an icon. -
-
- - - 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. - -```html live -
-
- 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. - -```html live -
-
- -

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

-
-
- Box body -
-
-``` - -```html live -
-
- -

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

- Box title - 12 -

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

- 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](/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 live -
-
-

- Box title -

- -
-
- Box body -
-
-``` - -A similar approach can be used for buttons with multiple lines of text within a row. - -```html live -
-
-
- 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 live -
-
-
- -
- -
-
- 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 live -
-
-

- Example form title -

-
-
-
-
-
-
-
-
- -
-
-
- - -
-
-
-``` - -When a box is all by itself centered on a page you can use [column widths](/utilities/grid) to control the width of the box. If needed, break the mold a little and use [typography utilities](/utilities/typography) instead of the built in box title styles. - -```html live -
-
-
-

- Example form -

-
-
-
-
- -
-
-
-``` - -Box patterns can also be made with, and modified with [border utilities](/utilities/borders). diff --git a/docs/content/components/branch-name.md b/docs/content/components/branch-name.md deleted file mode 100644 index 438849537c..0000000000 --- a/docs/content/components/branch-name.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Branch name -path: components/branch-name -status: Stable -source: 'https://github.com/primer/css/tree/main/src/branch-name' -bundle: branch-name ---- - -Branch names can be a link name or not: - -```html live -a_new_feature_branch -``` - -```html live -a_new_feature_branch -``` - -You may also include an octicon before the branch name text: - -```html live - - - - a_new_feature_branch - -``` diff --git a/docs/content/components/breadcrumb.md b/docs/content/components/breadcrumb.md deleted file mode 100644 index 1471ef9e4d..0000000000 --- a/docs/content/components/breadcrumb.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Breadcrumbs -path: components/breadcrumb -status: Stable -source: 'https://github.com/primer/css/tree/main/src/breadcrumb' -rails: 'https://primer.style/view-components/components/beta/breadcrumbs' -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 - -All items must contain links, and the last item must be selected. - -#### Usage - -```html live - -``` diff --git a/docs/content/components/button-group.md b/docs/content/components/button-group.md deleted file mode 100644 index b20b680d25..0000000000 --- a/docs/content/components/button-group.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Button group -path: components/button-group -status: Stable -source: 'https://github.com/primer/css/tree/main/src/buttons' -rails: 'https://primer.style/view-components/components/beta/buttongroup' -bundle: buttons ---- - -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 live -
- - - -
- -
- - - -
-``` - -Use `BtnGroup-item btn btn-sm` for a smaller BtnGroup items. - -```html live -
- - - -
-``` - -Add `.BtnGroup-parent` to parent elements, like `
`s or `
`s, within `.BtnGroup`s for proper spacing and rounded corners. - -```html live -
- - - - - - -
-``` diff --git a/docs/content/components/buttons.md b/docs/content/components/buttons.md deleted file mode 100644 index fae34157ef..0000000000 --- a/docs/content/components/buttons.md +++ /dev/null @@ -1,257 +0,0 @@ ---- -title: Buttons -path: components/buttons -status: Stable -source: 'https://github.com/primer/css/tree/main/src/buttons' -rails: 'https://primer.style/view-components/components/beta/button' -bundle: buttons ---- - -Buttons are used for **actions**, like in forms, while textual hyperlinks are used for **destinations**, or moving from one page to another. - -```html live - -``` - -Note: When using a ` -``` - -## Button types - -### Default - -Use the standard — yet classy — `.btn` for form actions and general page actions. These are used extensively around the site. - -```html live - -``` - -### Primary - -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 live - -``` - -### Outline - -Outline buttons downplay an action as they appear like boxy links. Just add `.btn-outline` and go. - -```html live - -``` - -### Danger - -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 live - -``` - -## Button states - -### Selected - -Adding an `aria-selected="true"` attribute will keep the button in a selected state. Typically used for [`BtnGroups`](#button-groups). - -```html live -
- - - -
- -
- - - -
-``` - -### Disabled - -Disable ` - - - -``` - -## Button variations - -### Sizes - -Next to the default size there is also a `.btn-sm` (small) and `.btn-large` option. Use them to decrease or increase the button size. This is useful for fitting a button next to an input or turning a button into a prominent call to action in hero sections. - -[Type scale utilities](/support/typography#type-scale) 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 live - - - -``` - -Use `.btn-large` with a type scale utility to transform the text to a bigger size. - -```html live -
- - Large link 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 live - - -``` - -### Link button - -Create a button that looks like a link with `.btn-link`. Rather than using an `` to trigger JS, this style on a ` -``` - -### Invisible button - -When you want a link, but you want it padded and line heightened like a button best for "cancel" actions on forms. - -```html live - - -``` - -### Hidden text button - -Use `.hidden-text-expander` to indicate and toggle hidden text. - -```html live - - - -``` - -You can also make the expander appear inline by adding `.inline`. - -## Button with icons - -Icons can be added to any button. - -```html live - - - - - - - - - -``` - -### Icon-only button - -Icon-only buttons `.btn-octicon` turn blue on hover. Use `.btn-octicon-danger` to turn an icon red on hover. - -```html live - - - - - - - -``` - -### Close button - -When using the `octicon-x` icon for a close button, add `.close-button` to remove the default button styles. - -```html live - -``` - -## Button with counts - -You can easily append a count to a **small button**. Add the `.btn-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.** - -```html live -
- - - - Watch - - -
-``` - -You can also use the [counter](./labels#counters) component within buttons: - -```html live - - - - - - - -``` diff --git a/docs/content/components/counter.md b/docs/content/components/counter.md deleted file mode 100644 index 903cf8e074..0000000000 --- a/docs/content/components/counter.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Counter -path: components/counter -status: Stable -source: 'https://github.com/primer/css/tree/main/src/labels' -rails: 'https://primer.style/view-components/components/beta/counter' -bundle: labels ---- - -Use the `Counter` component to add a count to navigational elements and buttons. Counters come in 3 variations: - -1. the default `Counter`, -2. the `Counter--primary` with a stronger background color -3. and `Counter--secondary` with a more subtle text color. - -Note: When a counter is empty, its visibility will be hidden. - -```html live -1 -23 -456 -``` - -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 live -
- -
-``` - -You can also have icons and emojis in counters. Or use utilities for counters with different background colors. - -```html live -1.5K - - - - 10 - -👍 2 -22 -22 -22 -``` diff --git a/docs/content/components/dialog.md b/docs/content/components/dialog.md deleted file mode 100644 index 61e4e749ed..0000000000 --- a/docs/content/components/dialog.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: Dialog -path: components/dialog -status: Alpha -source: 'https://github.com/github/github/tree/master/app/assets/stylesheets/experiments/modal-dialog.scss' -bundle: dialog ---- - -Please note that the `
` element with `id="fake-container"` is not included in the component. - -```html live -
- - -
-``` - -[aria attributes]: https://www.w3.org/TR/html-aria/#allowed-aria-roles-states-and-properties diff --git a/docs/content/components/dropdown.md b/docs/content/components/dropdown.md deleted file mode 100644 index fe84559316..0000000000 --- a/docs/content/components/dropdown.md +++ /dev/null @@ -1,204 +0,0 @@ ---- -title: Dropdown -status: Beta -source: 'https://github.com/primer/css/tree/main/src/dropdown' -rails: 'https://primer.style/view-components/components/alpha/dropdown' ---- - -Dropdowns are lightweight context menus for housing navigation and actions. They're great for instances where you don't need the full power (and code) of the select menu. - -## Basic examples - -Dropdowns should be triggered by a ` - - - - -

- -

- - - - -

-``` - -## Example form - -Form controls in Primer CSS 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 live -
- - - - - - - - - - - - -
-``` - -## Inputs - -### Sizing - -Make inputs smaller, larger, or full-width with an additional class. - -#### Small - -```html live -
- -
-``` - -#### Large - -```html live -
- -
-``` - -#### Block - -```html live -
- -
-``` - -### Input group - -Attached an input and button to one another. - -```html live -
-
- - - - -
-
-``` - -## Customization - -### Form contrast - -Textual form controls have a white background by default. You can change this to a light gray with `.input-contrast`. - -```html live -
- - -
-``` - -### Disabled state - -Add the `disabled` attribute to make a `.form-control` appear disabled. - -```html live -
- -
-``` - -### 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 live -
- -
-``` - -## Selects - -Primer CSS adds light `height` and `vertical-align` styles to ` - - - - - - - - - -``` - -### Small - -Use the `.select-sm` class to resize both default and custom ` - - - - - - - - - - -``` - -## Form groups - -```html live -
-
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
- -
-
-
-``` - -## Form group validation (deprecated) - - - These form validation styles are deprecated. Please use the TextField ViewComponent instead or refer to the design guidelines. - - -Convey success, errors and warnings for form groups. For github.com consider using the [``](https://github.github.io/web-systems-documentation/#custom-elements-auto-check-md) element to perform server-side validation on an input. - -### Success - -If the input is **valid**, add the `.successed` class to the `
` element. Next add/update a success message to the `.note` element, as well as the `.success` class. - -```html live -
-
-
- -
-
- -
-

monalisa is available

-
-
-``` - -### Error - -If the input is **not valid**, add the `.errored` class to the `
` element. Next add/update an error message to the `.note` element, as well as the `.error` class. - -```html live -
-
-
- -
-
- -
-

monalisa is not available. monalisa-beep, monalisa-cyber, or monalisa87 are available.

-
-
- ``` - -### Warning - -If the input should show a **warning**, add the `.warn` class to the `
` element. Next add/update a warning message to the `.note` element, as well as the `.warning` class. - - ```html live -
-
-
- -
-
- -
-

36 of maximum 39 characters entered.

-
-
-``` - -### 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 live -
- - -
-``` - -## Checkboxes and radios - -Utilities to control alignment and styling of checkbox and radio controls. - -```html live -
-
- -

- This will do insanely awesome and amazing things! -

-
-
-``` - -You may also add emphasis to the label: - -```html live -
-
- -
-
-``` - -### Toggle content visibility 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 live -
-
- -
-
- -
-
-``` - -## Radio group - -Radio groups are tab like controls. Their blue border gives extra emphasis to what is selected. - -```html live -
-
- - - - - - -
-
-``` - -Adding `octicon` icons is also supported. To disable an option, use the `disabled` attribute. - -```html live -
-
- - - - - - -
-
-``` diff --git a/docs/content/components/header.md b/docs/content/components/header.md deleted file mode 100644 index a16a179fd7..0000000000 --- a/docs/content/components/header.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: Header -path: components/header -status: Stable -source: 'https://github.com/primer/css/tree/main/src/header' -bundle: header ---- - -Use the Header component to create a header that has all of its items aligned vertically with consistent horizontal spacing. - -## Header - -The `.Header` class is the wrapping class that aligns all the items properly and gives the header its dark background. Each direct child of the `.Header` component is expected to be a `.Header-item` component. The component utilizes flexbox CSS to align all these items properly and applies spacing scale margin. - -```html live -
-
- - - - GitHub - -
-
- -
-
- Menu -
-
- @octocat -
-
- -``` - -## Header-item - -All items directly under the `.Header` component should be a `.Header-item` component. Inside these components can be anything (text, forms, images...), and the `.Header-item` component will make sure these elements vertically align with each other. - -`.Header-item` elements have a built-in margin that will need to be overridden with the `mr-0` utility class for the last element in the container. We relied on the utility classes here instead of `:last-child` because the last child isn't always the item visible. On responsive pages, there's a mobile menu that gets presented to the user at smaller breakpoints. - -```html live -
- -
- Text item -
- - -
- -
- - -
- @octocat -
-
- -``` - - - -### Header-item--full - -The `.Header-item` element has a modifier class, `.Header-item--full`, that stretches it to fill the available space and push any remaining items to the right. - -```html live -
-
- Item 1 -
- - -
- Item 2 -
- -
- Item 3 -
- -
- -``` - -## Header-link - -Add the `.Header-link` class to any anchor tags in the header to give them consistent styling and hover opacity. This class makes the links white, bold and 70% fade on hover. - -```html live -
-
- About -
-
- Releases -
-
- Team -
-
-``` diff --git a/docs/content/components/index.md b/docs/content/components/index.md deleted file mode 100644 index 203ab6ddc7..0000000000 --- a/docs/content/components/index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Components -path: components/index ---- - -Components make it easier to mark up a set of elements that are commonly grouped together with similar visual styles. Their base styles are shared and variants are added with modifier classes, so usually components are comprised of multiple classes. Most importantly, components should be highly reusable across the site, rather than built for specific pages or features. To achieve this: - -* **Separate structure and skin:** This means to define repeating visual features (like background and border styles) as separate “skins” that you can mix-and-match with your various components to achieve a large amount of visual variety without much code. -* **Separate container and content:** Essentially, this means “rarely use location-dependent styles”. A component should look the same no matter where you put it. diff --git a/docs/content/components/labels.md b/docs/content/components/labels.md deleted file mode 100644 index 24645699d1..0000000000 --- a/docs/content/components/labels.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Labels -path: components/labels -status_issue: 'https://github.com/github/design-systems/issues/332' -status: Stable -source: 'https://github.com/primer/css/tree/main/src/labels' -rails: 'https://primer.style/view-components/components/beta/label' -bundle: labels ---- - -Labels add metadata or indicate status of items and navigational elements. - -## Labels - -The base label component styles the text, adds padding and rounded corners, and a border. Labels come in various themes which apply different colors. - -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 and only uses the default border: - -```html live -design -``` - -### Label contrast - -Use `Label--primary` to create a label with a stronger border. This label is also neutral in color, however, since its border is stronger it can stand out more compared to the default `Label`. - -Use `Label--secondary` to create a label with a subtler text color. This label is neutral in color and can be used in contexts where all you need to communicate is metadata, or where you want a label to feel less prominent compared with labels with stronger colors. - -```html live -Default -Primary -Secondary -``` - -### Colored labels - -Labels come in a few different functional classes. Use to communicate the content of the label, and ensure it's used consistently. - -- `Label--accent` -- `Label--success` -- `Label--attention` -- `Label--severe` -- `Label--danger` -- `Label--open` -- `Label--closed` -- `Label--done` -- `Label--sponsors` - -```html live -Accent -Success -Attention -Severe -Danger -Open -Closed -Done -Sponsors -``` - -### Label sizes - -If space allows, add the `Label--large` modifier to add a bit more padding to labels. - -```html live -Default -Large -``` - -### Inline labels - -Sometimes when adding a label the line-height can be increased. Or the parent element increases in height. If that is not desired, use the `Label--inline` modifier change to the `display` property to `inline`. The font-size also adapts. - -```html live -

- Lorem Ipsum is simply dummy text of the printing and typesetting industry. - Lorem Ipsum has been the industry's standard dummy text. -

-``` - -## Issue labels - -Issue labels are used for adding labels to issues and pull requests. They also come with emoji support. - -```html live -Primer -bug 🐛 -help wanted -🚂 deploy: train -``` - -If an issue label needs to be bigger, add the `.IssueLabel--big` modifier. - -```html live -Primer -bug 🐛 -help wanted -🚂 deploy: train -``` diff --git a/docs/content/components/layout.md b/docs/content/components/layout.md deleted file mode 100644 index 4bd3643f0b..0000000000 --- a/docs/content/components/layout.md +++ /dev/null @@ -1,267 +0,0 @@ ---- -title: Layout -path: components/layout -status: Alpha -source: 'https://github.com/primer/css/tree/main/src/layout/layout.scss' -rails: 'https://primer.style/view-components/components/alpha/layout' -bundle: layout ---- - - -Build responsive-friendly page layouts with 2 columns. - -Use with .container-xx classes to limit the overall layout structure size. - -## Elements - -- `Layout-main` -- `Layout-sidebar` -- `Layout-divider` -- `Layout-main-centered-md` -- `Layout-main-centered-lg` -- `Layout-main-centered-xl` - -Use `Layout-main-centered-xx` to wrap `container-xx` elements inside -`Layout-main` so the content remains centered on the screen regardless -of the sidebar position. - -## Default - -```html live -
-
- .Layout-main -
- -
- .Layout-sidebar -
-
-``` - -### Dividers - -Use `Layout--divided` in conjunction with a `Layout-divider` to show a divider between the main content and the sidebar. -Flowing as row: -- default: shows a `1px` line between main and sidebar -- `Layout-divider--flowRow-shallow`: shows a filled `8px` divider. -- `Layout-divider--flowRow-hidden`: hides the divider - - -```html live -
-
main content
-
-
divider shown
-
-
-
main content
-
-
divider hidden
-
-
-
main content
-
-
flowRow shallow divider
-
-
-
main content
-
-
flowRow hidden divider
-
-``` - -### Centered content - -```html live -
-
-
-
- centered md -
-
-
-
sidebar
-
-
-
-
-
- centered lg -
-
-
-
sidebar
-
-
-
-
-
- centered xl -
-
-
-
sidebar
-
-``` - -## Modifiers - -### Sidebar sizing - -- Default: [md: 256px, lg: 296px] -- `Layout--sidebar-narrow` [md: 240px, lg: 256px] -- `Layout--sidebar-wide` [md: 296px, lg: 320px, xl: 344px] - -```html live -
-
- Layout--sidebar-narrow -
- -
- sidebar -
-
-
-
- Layout--sidebar-wide -
- -
- sidebar -
-
-``` - -### Column gutter - -- Default: [md: 16px, lg: 24px] -- `Layout--gutter-none`: 0px -- `Layout--gutter-condensed` 16px -- `Layout--gutter-spacious` [md: 16px, lg: 32px, xl: 40px] - -```html live -
-
- Layout--gutter-none -
- -
- sidebar -
-
-
-
- Layout--gutter-condensed -
- -
- sidebar -
-
-
-
- Default -
- -
- sidebar -
-
-
-
- Layout--gutter-spacious -
- -
- sidebar -
-
-``` - -### Sidebar positioning - -- `Layout--sidebarPosition-start` (default): sidebar to the left -- `Layout--sidebarPosition-end`: sidebar to the right - -```html live -
-
main
-
sidebar
-
-
-
main
-
sidebar
-
-``` - -### Sidebar positioning as rows - -- `Layout--sidebarPosition-flowRow-start` (default): when stacked, render the sidebar first -- `Layout--sidebarPosition-flowRow-end`: when stacked, render the sidebar last -- `Layout--sidebarPosition-flowRow-none`: when stacked, hide the sidebar - -```html live -
-
main
-
sidebar
-
-
-
main
-
sidebar
-
-
-
main
-
sidebar
-
-``` - -### Layout stacking - -- Default: stacks when container is `sm`. -- `Layout--flowRow-until-md`: stacks when container is `md`. -- `Layout--flowRow-until-lg`: stacks when container is `lg`. - -```html live -
-
main
-
sidebar
-
-
-
main
-
sidebar
-
-``` - -### Nesting Layouts - -It is possible to nest `Layout` components to generate 3-column layouts. - -```html live -
-
-
-
main content
-
metadata sidebar
-
-
-
default sidebar
-
-
-
-
-
main content
-
metadata sidebar
-
-
-
default sidebar
-
-``` - -## Accessibility and keyboard navigation - -Keyboard navigation follows the markup order. Decide carefully how the -focus order should be be by deciding whether `Layout-main` or `Layout-sidebar` -comes first in code. The code order won’t affect the visual position. diff --git a/docs/content/components/links.md b/docs/content/components/links.md deleted file mode 100644 index d6eaa59da3..0000000000 --- a/docs/content/components/links.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: Links -path: components/links -status: Beta -source: 'https://github.com/primer/css/tree/main/src/links' -rails: 'https://primer.style/view-components/components/beta/link' -bundle: links ---- - -By default `` elements already use the right link color and apply an underline on hover. So in most cases the `.Link` class is not really needed. - -```html live -Some text with a link -Some text with a link -``` - -If you like to override the default link styles you can do so with the following link utilities. **Bear in mind that link styles are easier for more people to see and interact with when the changes in styles do not rely on color alone.** - -## Primary link - -Use `.Link--primary` to turn the link color to blue only on hover. - -```html live -

Some text with a Link--primary

-``` - -## Secondary link - -Use `.Link--secondary` for a more subtle link color that turns blue on hover. - -```html live -Some text with a Link--secondary -``` - -## Muted link - -Use `.Link--muted` also removes the underline on hover. Tip: You can also use the `.no-underline` utility to do the same for `.Link--primary`. - -```html live -

Some text with a Link--muted

-

Some text with a Link--primary no-underline

-``` - -## On hover link - -Use `.Link--onHover` to make any text color used with links to turn blue on hover. This is useful when you want only part of a link to turn blue on hover. - -```html live - - A link with a partial Link--onHover - -``` - -## Nested link - -The `.Link` class can be nested inside an `` element if only part of it should be styled like a link. - -```html live - - A nested Link - -``` - -## Link and color utilities - -Link classes in combination with [color utilities](../utilities/colors) lets you colorize information separately inside of a link but have all of the link turn into one color on hover. - -```html live - - - Hot - potato - -``` diff --git a/docs/content/components/loaders.md b/docs/content/components/loaders.md deleted file mode 100644 index 820558c189..0000000000 --- a/docs/content/components/loaders.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Loaders -path: components/loaders -status: Beta -source: 'https://github.com/primer/css/tree/main/src/loaders' -bundle: loaders ---- - -Loaders inform users that an action is still in progress and might take a while to complete. - -## Animated ellipsis - -Add an animated ellipsis at the end of text with ``. - -```html live -Loading -``` - -It can also be used in combination with other components. - -```html live -

Loading

-Loading
-Loading
- -``` diff --git a/docs/content/components/markdown.md b/docs/content/components/markdown.md deleted file mode 100644 index 475347eb34..0000000000 --- a/docs/content/components/markdown.md +++ /dev/null @@ -1,493 +0,0 @@ ---- -title: Markdown -path: components/markdown -status: Stable -source: 'https://github.com/primer/css/tree/main/src/markdown' -bundle: markdown ---- - - -```html live -
-

Text can be bold, italic, or strikethrough. Links 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. -
  2. This is an ordered list following a header.
    3. -
  3. This is an ordered list following a header.
    4. -
- -
Header 6
- - - - - - - - - - - - - - - - - - - - - - -
WhatFollows
A tableA header
A tableA header
A tableA 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. -
  2. Michael Bolton
    3. -
  3. Michael Bublé
    4. -
- -

And an unordered task list:

- -
    -
  • Create a sample markdown document
    • -
  • 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.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ArtistAlbumYear
David BowieScary Monsters1980
PrincePurple Rain1982
Beastie BoysLicense to Ill1986
Janet JacksonRhythm Nation 18141989
- -

If a table is too wide, it should condense down and/or scroll horizontally.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ArtistAlbumYearLabelSongs
David BowieScary Monsters1980RCA RecordsIt's No Game (No. 1), Up the Hill Backwards, Scary Monsters (And Super Creeps), Ashes to Ashes, Fashion, Teenage Wildlife, Scream Like a Baby, Kingdom Come, Because You're Young, It's No Game (No. 2)
PrincePurple Rain1982Warner Brothers RecordsLet'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 BoysLicense to Ill1986Def JamRhymin & Stealin, The New Style, She's Crafty, Posse in Effect, Slow Ride, Girls, Fight for Your Right, No Sleep till Brooklyn, Paul Revere, "Hold It Now, Hit It", Brass Monkey, Slow and Low, Time to Get Ill
Janet JacksonRhythm Nation 18141989A&MInterlude: Pledge, Rhythm Nation, Interlude: T.V., State of the World, Interlude: Race, The Knowledge, Interlude: Let's Dance, Miss You Much, Interlude: Come Back, Love Will Never Do (Without You), Livin' in a World (They Didn't Make), Alright, Interlude: Hey Baby, Escapade, Interlude: No Acid, Black Cat, Lonely, Come Back to Me, Someday Is Tonight, Interlude: Livin'...In Complete Darkness
- -
- -

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.

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

- - - - - - - - - - - - - - - - - - -
LanguageCode
JavasScriptvar foo = "bar";
Rubyfoo = "bar"
- -
- -

The samp HTML element is used to enclose inline text which represents sample (or quoted) output from a computer program. Here an example of an error message: File not found

- -
- -

Small images should be shown at their actual size.

- -

- -

Large images should always scale down and fit in the content container.

- -

- -

- Here's a simple footnote,1 and here's a longer one.2 -

- -
-

Footnotes

-
    -
  1. -

    This is the first footnote. ↩

    -
    2. -
  2. -

    Here's one with multiple paragraphs and code.

    -

    Indent paragraphs to include them in the footnote.

    -

    { my code }

    -

    Add as many paragraphs as you like. ↩

    -
    3. -
-
- - 
This is the final element on the page and there should be no margin below this.
-
-``` - - - - - diff --git a/docs/content/components/marketing-buttons.md b/docs/content/components/marketing-buttons.md deleted file mode 100644 index 6e09b376b3..0000000000 --- a/docs/content/components/marketing-buttons.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: Marketing buttons -path: components/marketing-buttons -status: Beta -source: 'https://github.com/primer/css/tree/main/src/marketing/buttons' -bundle: marketing-buttons ---- - -Marketing buttons come in a few different colors and sizes that can be produced by combining the base class `btn-mktg` with a set of modifier classes. - -## Button types - -Marketing buttons can be solid (default), outlined (`muted`), borderless (`subtle`), or green (`signup`, only used for signing up). - -```html live - - - - -``` - -## Sizes - -Marketing buttons can be set to three different sizes: - -- Small: `btn-small-mktg` -- Medium (default) -- Large: `btn-large-mktg` - -```html live - - - - -
- - - - -
- - - - -``` - -## Animated arrow symbol - -Marketing buttons can include an animated arrow symbol, by adding a class `arrow-target-mktg` and including the SVG symbol: - -```html live - - - - - - - -``` diff --git a/docs/content/components/marketing-links.md b/docs/content/components/marketing-links.md deleted file mode 100644 index 3832f9f6b9..0000000000 --- a/docs/content/components/marketing-links.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: Marketing links -path: components/marketing-links -status: Beta -source: 'https://github.com/primer/css/tree/main/src/marketing/links' -bundle: marketing-links ---- - -Marketing links can be produced by combining the base class `link-mktg` with a set of modifier classes to control the size and color. - - -## Link sizes - -The marketing link size is defined with utility classes and come in large (`.f3-mktg`) and small (`.f4-mktg`): - -```html live - - Call to action - - - - - - -``` - -```html live - - Call to action - - - - - - -``` - -## Link with emphasis - -Add class `link-emphasis-mktg` to the link, to give it a pale underline, that will fill up on hover. - -```html live - - Call to action - - - - - - -``` - - -## Link colors - -The link color is controlled with the [Primer color classes](/utilities/colors), while the symbol and underline styling will follow: - -```html live - - Call to action - - - - - - - - - Call to action - - - - - - -``` \ No newline at end of file diff --git a/docs/content/components/menu.md b/docs/content/components/menu.md deleted file mode 100644 index e3cddb7b7e..0000000000 --- a/docs/content/components/menu.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Menu -path: components/menu -status: Stable -source: 'https://github.com/primer/css/tree/main/src/navigation' -rails: 'https://primer.style/view-components/components/alpha/menu' -bundle: navigation ---- - -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 live title="Menu" - -``` - -There are a few subcomponents and add-ons that work well with the menu, including avatars, counters, and Octicons. - -```html live - -``` - -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 live title="Menu with heading" - -``` diff --git a/docs/content/components/navigation.md b/docs/content/components/navigation.md deleted file mode 100644 index c919cd1cf4..0000000000 --- a/docs/content/components/navigation.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Navigation -path: components/navigation -status: Stable -source: 'https://github.com/primer/css/tree/main/src/navigation' -bundle: navigation ---- - -Primer CSS comes with several navigation components. Some were designed with singular purposes, while others were design to be more flexible and appear quite frequently. - -- [Menu](./menu) -- [Underline nav](./underline-nav) -- [Side nav](./side-nav) -- [Tabnav](./tabnav) -- [Filter list](./filter-list) -- [Sub navigation](./subnav) diff --git a/docs/content/components/popover.md b/docs/content/components/popover.md deleted file mode 100644 index 95abd25a6b..0000000000 --- a/docs/content/components/popover.md +++ /dev/null @@ -1,241 +0,0 @@ ---- -title: Popover -path: components/popover -status: Alpha -source: 'https://github.com/primer/css/tree/main/src/popover' -storybook: 'https://primer.style/css/storybook/?path=/story/components-popover--playground' -rails: 'https://primer.style/view-components/components/beta/popover' -bundle: popover ---- - - -Popovers are used to bring attention to specific user interface elements, typically to suggest an action or to guide users through a new experience. - -| Class | Description | -| :- | :- | -| `Popover` | Block element, position absolute | -| `Popover-message` | Child element, content and 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. By default, the caret is shown on the top edge of the message, horizontally centered. To change the caret's position, use one of the following modifiers. - -### Variants - -| Class | Description | -| :- | :- | -| `Popover-message--bottom` | Caret bottom | -| `Popover-message--right` | Caret right | -| `Popover-message--left` | Caret left | -| `Popover-message--bottom-left` | Caret bottom left | -| `Popover-message--bottom-right` | Caret bottom right | -| `Popover-message--left-bottom` | Caret left bottom | -| `Popover-message--left-top` | Caret left top | -| `Popover-message--right-bottom` | Caret right bottom | -| `Popover-message--right-top` | Caret right top | -| `Popover-message--top-left` | Caret top left | -| `Popover-message--top-right` | Caret top right | -| `Popover-message--large` | Larger width 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. - -For screen sizes smaller than 767px, `Popover` will appear full-width and without a caret. - -## Basic example -Defaults to caret oriented top-center. - -```html live title="Default (top-center)" -
- -
-
-

Popover heading

-

Message about this particular piece of UI.

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

Popover heading

-

Message about this particular piece of UI.

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

Popover heading

-

Message about this particular piece of UI.

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

Popover heading

-

Message about this particular piece of UI.

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

Popover heading

-

Message about this particular piece of UI.

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

Popover heading

-

Message about this particular piece of UI.

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

Popover heading

-

Message about this particular piece of UI.

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

Popover heading

-

Message about this particular piece of UI.

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

Popover heading

-

Message about this particular piece of UI.

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

Popover heading

-

Message about this particular piece of UI.

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

Popover heading

-

Message about this particular piece of UI.

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

Popover heading

-

Message about this particular piece of UI.

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

Popover heading

-

Message about this particular piece of UI.

- -
-
-
-``` diff --git a/docs/content/components/progress.md b/docs/content/components/progress.md deleted file mode 100644 index 5df3f317cc..0000000000 --- a/docs/content/components/progress.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: Progress -path: components/progress -status: Beta -source: 'https://github.com/primer/css/tree/main/src/progress' -rails: 'https://primer.style/view-components/components/beta/progressbar' -bundle: progress ---- - -Use progress components to visualize task completion. The `Progress` class adds a background color and aligns its children horizontally with flexbox. The children (`Progress-item`) should be individually colored with [background utilities](/utilities/colors#background-colors) and sized with inline `width` styles in percentages. Overflow is hidden, so children that overflow will be clipped. - -```html live - - - -``` - -## Large progress - -Large progress bars are slightly taller than the default. - -```html live - - - -``` - -## Small progress - -Small progress bars are shorter than the default. - -```html live - - - -``` - -## Inline progress - -For inline progress indicators, use the `Progress` and `d-inline-flex` with an inline element such as `` and add a custom `width` style: - -```html live -4 of 16 - - - -``` - -## Accessibility - -In cases where it's not possible to describe the progress in text, provide an `aria-label` attribute that does so: - -```html live -
- - - -
-``` - -## Progress with multiple values - -To show the progress of tasks in multiple states (such as "done", "in progress", and "open"), add the `Progress-item` class and a distinct background color utility. Then give each one a percentage width proportional to the total number. Children are stacked from left to right, so if your widths add up to 100%, your bars will too. Note that items with very low percentage values might not be visible if they are smaller than `1px` in width. - -```html live -
- - - - - - -
-``` diff --git a/docs/content/components/select-menu-deprecated.md b/docs/content/components/select-menu-deprecated.md deleted file mode 100644 index b8d2565274..0000000000 --- a/docs/content/components/select-menu-deprecated.md +++ /dev/null @@ -1,880 +0,0 @@ ---- -title: Select menu (deprecated) -path: components/select-menu -status: Deprecated -source: 'https://github.com/github/github/blob/main/app/assets/stylesheets/components/select-menu.scss' -symbols: [active, close-button, css-truncate-target, description, description-inline, description-warning, disabled, filterable-empty, has-error, hidden-select-button-text, icon-only, indeterminate, is-loading, is-showing-new-item-form, label-select-menu, last-visible, menu-active, modal-backdrop, navigation-focus, octicon, octicon-check, octicon-dash, octicon-octoface, octicon-x, opaque, primary, select-menu, select-menu-action, select-menu-blankslate, select-menu-button, select-menu-button-gravatar, select-menu-button-large, select-menu-clear-item, select-menu-divider, select-menu-error, select-menu-filters, select-menu-header, select-menu-item, select-menu-item-gravatar, select-menu-item-heading, select-menu-item-icon, select-menu-item-parent, select-menu-item-template, select-menu-item-text, select-menu-list, select-menu-loading-overlay, select-menu-modal, select-menu-modal-holder, select-menu-modal-narrow, select-menu-modal-right, select-menu-new-item-form, select-menu-no-results, select-menu-tab, select-menu-tab-bucket, select-menu-tab-nav, select-menu-tabs, select-menu-text-filter, select-menu-title, selected, spinner] ---- - - - Please note that the `.select-menu` component is **deprecated**. Use the [`.SelectMenu`](select-menu) instead. - - -## Migration guide - -Here are a few tips on how to migrate an existing `.select-menu` to `.SelectMenu`. - -1. Use a `
` element to toggle the Select Menu. -2. Use a [``](https://github.com/github/details-menu-element) element to add JS behaviour. The older `.js-select-menu` is not compatible. -3. In case custom styling is needed, use [utility classes](https://primer.style/css/utilities) if possible. - -Below is a comparison between class names: - -`.select-menu` | `.SelectMenu` ---- | --- -`select-menu` | - -`select-menu-button` | - -`select-menu-modal-holder` | - -`select-menu-modal` | `SelectMenu` -`select-menu-modal-right` | `SelectMenu right-0` -- | `SelectMenu-modal` -`select-menu-loading-overlay` | `SelectMenu-loading` -`select-menu-item-icon` | `SelectMenu-icon` -`select-menu-header` | `SelectMenu-header` -`select-menu-title` | `SelectMenu-title` -`close-button` | `SelectMenu-closeButton` -`select-menu-filters` | - -`select-menu-text-filter` | `SelectMenu-filter` -- | `SelectMenu-input` -`select-menu-tabs` | `SelectMenu-tabs` -`select-menu-tab` | `SelectMenu-tab` -`select-menu-tab-nav` | - -`select-menu-list` | `SelectMenu-list` -`select-menu-item` | `SelectMenu-item` -`select-menu-item-text` | - -`select-menu-no-results` | `SelectMenu-message` -`select-menu-blankslate` | `SelectMenu-blankslate` -`selected` | `aria-checked="true"` - - ---- - -The select menu provides advanced support for navigation, filtering, and more. Any popover within a select menu can make use of JavaScript-enabled live filtering, selected states, tabbed lists, and keyboard navigation with a bit of markup. - -{:toc} - -## Basic example - -Select menus should be trigged by a ` -
-
-
- - <%= octicon("check", :class => "select-menu-item-icon") %> - Item 1 - - - <%= octicon("check", :class => "select-menu-item-icon") %> - Item 2 - - - <%= octicon("check", :class => "select-menu-item-icon") %> - Item 3 - -
-
-
-
-``` - -## Menu contents - -The contents of a select menu are easily customized with support for headers, footers, tabbed lists, and live filtering. - -### Headers - -Add a header to any select menu's popover to house a clear title and a dismiss button. - -```erb -
- -
-
-
- - Options -
-
- - <%= octicon("check", :class => "select-menu-item-icon") %> - Item 1 - - - <%= octicon("check", :class => "select-menu-item-icon") %> - Item 2 - - - <%= octicon("check", :class => "select-menu-item-icon") %> - Item 3 - -
-
-
-
-``` - -### List items - -The list of items is arguably the most important subcomponent within the menu. Build them out of anchors, buttons, or just about any [interactive content](http://w3c.github.io/html/dom.html#interactive-content). [List items are also customizable](#menu-list-items) with options for avatars, additional icons, and multiple lines of text. - -```erb -
- -
-
-
- - - <%= octicon("check", :class => "select-menu-item-icon") %> - Item 2 - - - <%= octicon("check", :class => "select-menu-item-icon") %> - Item 3 - -
-
-
-
-``` - -### Filter - -Enable live filtering of list items within a `.select-menu-list` with a search input. Only a handful of changes to your menu's markup are required: - -- Add the text input, housed in `.select-menu-filters`, before the `.select-menu-list`. -- Add two attributes, `data-filterable-for` and `data-filterable-type`, to the `.select-menu-list` to scope the filter to the list. - -There are no required changes for the `.select-menu-item`s. - -```erb -
- -
-
-
- - Options -
-
-
-
- -
-
-
- - - <%= octicon("check", :class => "select-menu-item-icon") %> -
- Test element -
- - - <%= octicon("check", :class => "select-menu-item-icon") %> -
- Filter to this -
- - - <%= octicon("check", :class => "select-menu-item-icon") %> -
- More content -
- - - <%= octicon("check", :class => "select-menu-item-icon") %> -
- Something else -
- - - <%= octicon("check", :class => "select-menu-item-icon") %> -
- One more thing -
- -
-
-
-
-
-``` - -### Tabs - -Sometimes you need two or more lists of items in your select menu, e.g. branches and tags. Select menu lists can be tabbed with the addition of the tab toggles at the top of the menu and a few changes to the `.select-menu-list`. - -```erb -
- -
-
-
- - Options -
-
-
-
- -
-
- - -
-
-
-
-``` - -### Filter and tabs - -Show a filter and tabs in a single select menu. - -```erb -
- -
-
-
- - Options -
-
-
-
- -
-
- -
-
- - -
-
-
-
-``` - -### Blankslate - -Sometimes a select menu needs to communicate a "blank slate" where there's no content in the menu's list. Usually these include a clear call to action to add said content to the list. Swap out the contents of a `.select-menu-list` with the `.select-menu-blankslate` and customize its contents as needed. - -```erb -
- -
-
-
- - Options -
-
-
- <%= octicon("check", :height => 32) %> -

Select menu blankslate

-

Some text here to describe why you're seeing a blankslate and how to go about fixing that up.

- -
-
-
-
-
-``` - -## Menu list items - -Select menu list items have a few options available to them for more complex information patterns. - -### Multi-line text - -Sometimes the contents of your select menu list require a heading and a description instead of just a string. Select menus come with some default styles for such situations with the addition of a few classes and wrapping ``s. - -```erb -
- - -
-
-
- - Notifications -
- -
-
-
-``` - -### With avatars - -Add avatars to a select menu to help indicate when a menu list item represents a user. - -```erb -
- -
-
-
- - Options -
-
- - <%= octicon("check", :class => "select-menu-item-icon") %> - - <%= avatar_for(current_user, 20, :alt => "") %> - - - probot - - - - <%= octicon("check", :class => "select-menu-item-icon") %> - - <%= avatar_for(current_user, 20, :alt => "") %> - - - probot - - - - <%= octicon("check", :class => "select-menu-item-icon") %> - - <%= avatar_for(current_user, 20, :alt => "") %> - - - probot - - -
-
-
-
-``` - -### With dismiss icon - -Indicate how to toggle the selected state on a select menu list item with the addition of a dismiss icon. - -```erb -
- -
-
-
- - Options -
-
- - - -
-
-
-
-``` - -## Menu alignment - -By default select menus are automatically aligned to the top left corner of an element, but you can also customize that with a few utilities or custom display. - -### Right aligned menus - -When select menus are right aligned, you can also right-align the select menu's popover with `.select-menu-modal-right`. - -```erb -
- -
-
-
- - Options -
-
- - <%= octicon("check", :class => "select-menu-item-icon") %> - Item 1 - - - <%= octicon("check", :class => "select-menu-item-icon") %> - Item 2 - - - <%= octicon("check", :class => "select-menu-item-icon") %> - Item 3 - -
-
-
-
-``` - -## Button options - -Customize the select menu's trigger button by changing the button modifier class, enabling stateful text, and more. - -### Style options - -Since select menus are powered by JavaScript behaviors, the specific display of your select menu button is up to you and your use case. - -```erb -
- - -
-
-
- - <%= octicon("check", :class => "select-menu-item-icon") %> - Item 1 - - - <%= octicon("check", :class => "select-menu-item-icon") %> - Item 2 - - - <%= octicon("check", :class => "select-menu-item-icon") %> - Item 3 - -
-
-
-
-``` - -```erb -
- - -
-
-
- - <%= octicon("check", :class => "select-menu-item-icon") %> - Item 1 - - - <%= octicon("check", :class => "select-menu-item-icon") %> - Item 2 - - - <%= octicon("check", :class => "select-menu-item-icon") %> - Item 3 - -
-
-
-
-``` - -```erb -
- - -
-
-
- - <%= octicon("check", :class => "select-menu-item-icon") %> - Item 1 - - - <%= octicon("check", :class => "select-menu-item-icon") %> - Item 2 - - - <%= octicon("check", :class => "select-menu-item-icon") %> - Item 3 - -
-
-
-
-``` - -```erb -
- - -
-
-
- - <%= octicon("check", :class => "select-menu-item-icon") %> - Item 1 - - - <%= octicon("check", :class => "select-menu-item-icon") %> - Item 2 - - - <%= octicon("check", :class => "select-menu-item-icon") %> - Item 3 - -
-
-
-
-``` - -### Stateful text - -Select menu buttons have the option of showing the current selection in the button itself. Wrap the string you intend to update with a `.js-select-button` and the select menu JavaScript will automatically update the contents of that element with the selected item's text. - -Open the select menu below and click different options to see it in action. - -```erb -
- -
-
-
- - Options -
-
- - <%= octicon("check", :class => "select-menu-item-icon") %> - main - - - <%= octicon("check", :class => "select-menu-item-icon") %> - feature-branch - - - <%= octicon("check", :class => "select-menu-item-icon") %> - refactor-component-name - -
-
-
-
-``` - -### Emphasized text - -You may want to include an emphasized label in the select menu. For example, you may want to include the word `Branch:` in front of the current branch on a repository **Code** page. To do this, within the button, wrap the string in an `` element. - -As shown below, emphasized text works well with the stateful text functionality mentioned above. - -```erb -
- -
-
-
- - Options -
-
- - <%= octicon("check", :class => "select-menu-item-icon") %> - main - - - <%= octicon("check", :class => "select-menu-item-icon") %> - feature-branch - - - <%= octicon("check", :class => "select-menu-item-icon") %> - refactor-component-name - -
-
-
-
-``` - -### Button avatars - -Add an avatar to the button, like, for example, in the context switcher in the signed in dashboard. - -```erb -
- -
-
-
- - Options -
-
- - <%= octicon("check", :class => "select-menu-item-icon") %> - - <%= avatar_for(current_user, 20, :"aria-label" => "") %> - - - probot - - - - <%= octicon("check", :class => "select-menu-item-icon") %> - - <%= avatar_for(current_user, 20, :"aria-label" => "") %> - - - probot - - - - <%= octicon("check", :class => "select-menu-item-icon") %> - - <%= avatar_for(current_user, 20, :"aria-label" => "") %> - - - probot - - -
-
-
-
-``` diff --git a/docs/content/components/select-menu.md b/docs/content/components/select-menu.md deleted file mode 100644 index d6abf0bf23..0000000000 --- a/docs/content/components/select-menu.md +++ /dev/null @@ -1,623 +0,0 @@ ---- -title: Select menu -status: Beta -source: 'https://github.com/primer/css/tree/main/src/select-menu' -bundle: select-menu ---- - - - Please note that this is a newer version and uses the `.SelectMenu` class instead of the deprecated select menu class. Check the migration guide to make sure your app is up to date. - - - -The `SelectMenu` component provides advanced support for navigation, filtering, and more. Any menu can make use of JavaScript-enabled live filtering, selected states, tabbed lists, and keyboard navigation with a bit of markup. - -## Basic example - -Use a `
` element to toggle the select menu. The `` element can be styled in many ways. In the example below it's a `.btn`. - -```html live -
- - Choose an item - -
-
-
- - - -
-
-
-
- -
-
-``` - -Add a `.SelectMenu-header` to house a clear title and a close button. Note that the close button is only shown on narrow screens (mobile). - -## Right aligned - -In case the select menu should be aligned to the right, use `SelectMenu right-0`. - -```html live -
-
- - Choose an item - -
-
-
- - - -
-
-
-
-
- -
-
-``` - -## Selected state - -If the `SelectMenu` should show a check icon for selected items, use the `SelectMenu-icon SelectMenu-icon--check` classes. It will make the check icon show when `aria-checked="true"` is set. - -```html live -
- - Choose an item - -
-
-
- - - - - -
-
-
-
- -
-
-``` - -## Borderless - -Use the `.SelectMenu-list--borderless` modifier to remove the borders between list items. Note: It's better to keep the borders if a list contains items with multiple lines of text. It will make it easier to see where the items start and end. - -```html live -
- - Choose an item - -
-
-
- - - -
-
-
-
- -
-
-``` - -## Header - -Add a `.SelectMenu-header` at the top to house a clear title and a close button. - -```html live -
- - Choose an item - -
-
-
-

Title

- -
-
- - - -
-
-
-
- -
-
-``` - -## List items - -The list of items is arguably the most important subcomponent within the menu. Build them out of anchors, buttons, or just about any [interactive content](http://w3c.github.io/html/dom.html#interactive-content). List items are also customizable with options for avatars, additional icons, and multiple lines of text. Use utility classes in case more custom styling is needed. - -```html live -
- - Choose an item - -
-
-
-

Title

- -
-
- - - - - - - -
-
-
-
- -
-
-``` - -## Divider - -The select menu's list can be divided into multiple parts by adding a `.SelectMenu-divider`. It can be a `
` with text/content. Or just an `
` to add a visual separator. - -```html live -
- - Choose an item - -
-
-
-

Title

- -
-
- - -
More options
- - -
- - -
-
-
-
- -
-
-``` - -Dividers are also supported when using the `.SelectMenu-list--borderless` modifier. - -```html live -
- - Choose an item - -
-
-
-

Title

- -
-
- - -
More options
- - -
- - -
-
-
-
- -
-
-``` - -## Footer - -Use a `.SelectMenu-footer` at the bottom for additional information. As a side effect it can greatly improve the scrolling performance because the list doesn't need to be repainted due to the rounded corners. - -```html live -
- - Choose an item - -
-
-
-

Title

- -
-
- - - - - -
-
Footer
-
-
-
- -
-
-``` - -## Filter - -If the list is expected to get long, consider adding a `.SelectMenu-filter` input. Be sure to also include the `.SelectMenu--hasFilter` modifier class. On mobile devices it will add a fixed height and anchor the select menu to the top of the screen. This makes sure the filter input stays at the same position while typing. - -```html live -
- - Choose an item - -
-
-
-

Title

- -
-
- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - -
-
Showing 25 of 25
-
-
-
- -
-
-``` - -## Tabs - -Sometimes you need two or more lists of items in your select menu, e.g. branches and tags. Select menu lists can be tabbed with the addition of `.SelectMenu-tabs` above the menu. - -```html live -
- - Choose an item - -
-
-
-

Title

- -
-
- -
- -
- - - - - -
- -
Showing 5 of 5
-
-
-
- -
-
-``` - -## Message - -A `SelectMenu-message` can be used to show different kind of messages to a user. Use utility classes to further style the message. - -```html live -
- - Choose an item - -
-
-
-

Title

- -
-
-
Message goes here
- - - -
-
-
-
- -
-
-``` - -## Loading - -When fetching large lists, consider showing a `.SelectMenu-loading` animation. - -```html live -
- - Choose an item - -
-
-
-

Title

- -
-
-
- - -
-
-
Loading...
-
-
-
- -
-
-``` - -## Disabled - -To disable a list item, use the `disabled` attribute for ` - - Item 3 - Item 4 (disabled) -
-
-
-
- -
-
-``` - -## Blankslate - -Sometimes a select menu needs to communicate a "blank slate" where there's no content in the menu's list. Usually these include a clear call to action to add said content to the list. Swap out the contents of a `.SelectMenu-list` with a `.SelectMenu-blankslate` and customize its contents as needed. - -```html live -
- - Choose an item - -
-
-
-

Title

- -
-
-
- - -

No repositories

-

We didn’t find any matching repositories that you can commit to.

- -
-
-
-
-
- -
-
-``` - -## github.com usage - -When adding the `.SelectMenu` component on github.com, use the [``](https://github.com/github/details-menu-element) element. It will magically make the `.SelectMenu` work. Here a basic example: - -```erb -
- - Choose - - - -
-
- My Select Menu - -
-
- Item 1 - Item 2 - Item 3 -
-
- -
-``` - -If loading content should be deferred, use the [``](https://github.com/github/details-menu-element) element: - -```erb - -
- - <%= octicon("octoface", class: "anim-pulse", :height => 32) %> - -
- -``` - -It will add a pulsing "octoface" icon while the content is loading. diff --git a/docs/content/components/side-nav.md b/docs/content/components/side-nav.md deleted file mode 100644 index fa26529cff..0000000000 --- a/docs/content/components/side-nav.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: SideNav -path: components/side-nav -status: Stable -source: 'https://github.com/primer/css/tree/main/src/navigation' -rails: 'https://primer.style/view-components/components/alpha/navlist' -bundle: navigation ---- - -The Side Nav is a vertical list of navigational links, typically used on the left side of a page. For maximum flexibility, **Side Nav elements have no default width or positioning**. We suggest using [column grid](../utilities/grid) classes or an inline `width` style for sizing, and [flexbox utilities](../utilities/flexbox) for positioning alongside content. - -- You can use a **border** if the parent element doesn't have it already. -- Add `aria-current="page"` to show a link as selected. Selected button elements in tab-like UIs should instead have `aria-selected="true"`. - -```html live - -``` - -Different kind of content can be added inside a Side Nav item. Use utility classes to further style them if needed. - -```html live - -``` - -The `.SideNav-subItem` is an alternative, more lightweight version without borders and more condensed. It can be used stand-alone. - -```html live - -``` - -Or also appear nested, as a sub navigation. Use margin/padding utility classes to add indentation. - -```html live - -``` diff --git a/docs/content/components/state.md b/docs/content/components/state.md deleted file mode 100644 index cfccf6bcfa..0000000000 --- a/docs/content/components/state.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: State -path: components/state -status: Stable -source: 'https://github.com/primer/css/tree/main/src/labels' -rails: 'https://primer.style/view-components/components/state' -bundle: labels ---- - -Use state labels to inform users of an item's status. States are large labels with bolded text. The default state has a gray background. States come in a few variations that apply different colors. Use the state that best communicates the status or function. - -- `State` -- `State State--draft` -- `State State--open` -- `State State--merged` -- `State State--closed` - -```html live -Draft - - - - - Open - - - - - - Merged - - - - - - Closed - -``` - -### Small states - -Use `State--small` for a state label with reduced padding a smaller font size. This is useful in denser areas of content. - -```html live -Default - - - - Open - - - - - Closed - -``` diff --git a/docs/content/components/subhead.md b/docs/content/components/subhead.md deleted file mode 100644 index 86d5ad88f6..0000000000 --- a/docs/content/components/subhead.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Subhead -path: components/subhead -status: Stable -status_issue: 'https://github.com/github/design-systems/issues/101' -source: 'https://github.com/primer/css/tree/main/src/subhead' -rails: 'https://primer.style/view-components/components/subhead' -bundle: subhead ---- - - -The basic Subhead consists of a `.Subhead` container, which has a light gray bottom border. Use `.Subhead-heading` for the heading itself. It is styled as 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 live 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 live title="Spacious Subhead" -
-

Spacious subhead

-
-``` - -You can add a one line description to the subhead with `.Subhead-description`. - -```html live 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 live 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 live 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 live title="Subhead with actions and description" -
-

Subhead with actions and description

-
The subhead is a subdued header style with a light bottom border.
-
Action
-
-``` - -Use the `.Subhead-heading--danger` modifier to make the text bold and red. This is useful for warning users. - -```html live title="Subhead danger" -
-

Danger zone

-
-``` diff --git a/docs/content/components/subnav.md b/docs/content/components/subnav.md deleted file mode 100644 index baa20a0014..0000000000 --- a/docs/content/components/subnav.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Sub navigation -path: components/subnav -status: Stable -source: 'https://github.com/primer/css/tree/main/src/navigation' -bundle: 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 live title="subnav" - -``` - -You can have `subnav-search` in the subnav bar. - -```html live -
- -
- - - -
-
-``` - -You can also use a `subnav-search-context` to display search help in a select menu. - -```html live -
- -
-
-
- -
-
- - - -
-
-``` diff --git a/docs/content/components/tabnav.md b/docs/content/components/tabnav.md deleted file mode 100644 index 41b7d62640..0000000000 --- a/docs/content/components/tabnav.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: Tabnav -path: components/tabnav -status: Stable -source: 'https://github.com/primer/css/tree/main/src/navigation' -rails: 'https://primer.style/view-components/components/alpha/tabnav' -bundle: navigation ---- - -When you need to toggle between different views, consider using a tabnav. It'll give you a left-aligned horizontal row of... tabs! - -```html live title="tabnav" -
- -
-``` - -Tabs can also contain icons and counters. - -```html live -
- -
-``` - -Use `.float-right` to align additional elements in the `.tabnav`: - -```html live title="tabnav with buttons" -
- Button - -
-``` - -Additional bits of text and links can be styled for optimal placement with `.tabnav-extra`: - -```html live title="tabnav-extra" -
-
Tabnav widget text here.
- -
-``` - -```html live title="tabnav with everything" -
-
- Tabnav extra link - Tabnav extra link -
- -
-``` diff --git a/docs/content/components/timeline.md b/docs/content/components/timeline.md deleted file mode 100644 index 41cd6798ec..0000000000 --- a/docs/content/components/timeline.md +++ /dev/null @@ -1,190 +0,0 @@ ---- -title: Timeline -path: components/timeline -status: Alpha -status_issue: 'https://github.com/github/design-systems/issues/101' -source: 'https://github.com/primer/css/tree/main/src/timeline' -rails: 'https://primer.style/view-components/components/timelineitem' -bundle: timeline ---- - -The `TimelineItem` component is used to display items on a vertical timeline, connected by `TimelineItem-badge` elements. - -```html live -
-
- - -
- -
- Monalisa created one - hot potato - Just now -
-
-``` - -## TimelineItem-badge - -The default TimelineItem-badge color is dark text on a light gray background. - -```html live - -
-
- - - -
-
- Default badge color -
-
-``` - -### Adding color to TimelineItem-badge - -To have color variants, use the [color utilities](/utilities/colors) on the badge. Be cautious with color choices. We typically use them in the timeline to give meaning to the event in context of the timeline. - -```html live - -
-
- - - -
-
- Red background used when closed events occur -
-
-
-
- - - -
-
- Green background when opened or passed events occur -
-
-
-
- - - -
-
- Purple background used when pull requests are merged -
-
-
-
- - - -
-
- Blue background to indicate new events below -
-
-``` - -## TimelineItem--condensed - -TimelineItem has a condensed variant that will reduce the vertical padding and remove the background from the badge item. These are most commonly used in commits. - -```html live -
-
- -
-
- This is the message of a condensed TimelineItem -
-
-
-
- -
-
- This is the message of a condensed TimelineItem -
-
-``` - -## TimelineItem-avatar - -Sometimes you want to give ownership to an event by displaying an [Avatar]() of the author. To do this, you'll need to wrap the TimelineItem in a `
` and give it space for the avatar. `ml-6 pl-3` This is `40px`, the size of the image, and `16px` space for the gutter. - -```html live -
-
-
- @octocat -
- -
- - -
- -
- Monalisa created one - hot potato - Just now -
-
-
-``` - -## TimelineItem-break - -To create a visual break in the timeline, use `TimelineItem-break`. This adds a horizontal bar across the timeline to show that something has disrupted it. Usually this happens when a close or merged event occurs. - -```html live -
-
- - - -
-
- Red background used when closed events occur -
-
-
-
-
- - - -
-
- Green background when opened or passed events occur -
-
-``` - -## Target TimelineItem - -```html live -
- - - - - -
- Monalisa created one - hot potato - Just now -
-
-``` diff --git a/docs/content/components/toasts.md b/docs/content/components/toasts.md deleted file mode 100644 index c93559dfa7..0000000000 --- a/docs/content/components/toasts.md +++ /dev/null @@ -1,227 +0,0 @@ ---- -title: Toasts -path: components/toasts -status: Alpha -status_issue: 'https://github.com/github/design-systems/issues/101' -source: '' -bundle: toasts ---- - -Toasts are used to show live, time-sensitive feedback to users. - -## Default - -To create a default toast, use `.Toast`. Always use the `info` icon for default messages. - -```html live -
-
- - - - - Toast message goes here -
-
-``` - -The Toast content is formattable. We recommend keeping your message under 140 characters. - -```html live -
-
- - - - - - Lorem ipsum dolor sit amet, consectetuer adipiscing elit. - Aenean commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et ma - -
-
-``` - -## Variations - -Use the success, warning, and error modifiers to communicate different states. - -Always use the `check` octicon for success states. - -```html live -
-
- - - - - Success message goes here. -
-
-``` - -Always use the `alert` octicon for warning states. - -```html live -
-
- - - - - Warning message goes here. -
-
-``` - -Always use the `stop` octicon for error states. - -```html live -
-
- - - - - Error message goes here -
-
-``` - -## Toast with dismiss - -Use `.Toast-dismissButton` to allow a user to explicitly dismiss a Toast. - -```html live -
-
- - - - - This toast is dismissable. - -
-
-``` - -## Toast with link - -Include a link to allow users to take actions within a Toast. - -```html live -
-
- - - - - Toast message goes hereAction. -
-
-``` - -## Toast animation in - -The `Toast--animateIn` and `Toast--animateOut` modifier classes can be used to animate the toast in and out from the bottom. - -```html live -
-
- - - - - Toast message goes here. -
-
-``` - -## Toast with loading animation - -Add the `Toast--spinner` modifier class on the `Toast-icon` `svg` to communicate a loading state. - -```html live -
-
- - - - Toast message goes here. -
-
-``` - -## Toast position - -Use the `position-fixed bottom-0 left-0` utility classes on a wrapper element to position Toasts at the **bottom left** of the viewport. - -```html live -
-
-
- - - - - Toast message goes here. -
-
-
-``` diff --git a/docs/content/components/tooltips.md b/docs/content/components/tooltips.md deleted file mode 100644 index 5fac24feaa..0000000000 --- a/docs/content/components/tooltips.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: Tooltips -path: components/tooltips -status: Deprecated -source: 'https://github.com/primer/css/tree/main/src/tooltips' -rails: 'https://primer.style/view-components/components/alpha/tooltip' -bundle: tooltips ---- - - - Please note that the `.tooltipped` component is **deprecated**. We recommend using the [Tooltip component](https://primer.style/view-components/components/alpha/tooltip) instead. - - -Add tooltips built entirely in CSS to appropriate elements. - -## 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? And check out [alternatives to Tooltips](https://primer.style/design/accessibility/tooltip-alternatives) to explore your options. - -### Attention - -- **Never** use tooltips on static elements. They should only be used on interactive elements, because users cannot tab-focus into static elements, which may make the content inaccessible for keyboard-only users and screen readers. -- 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 such as an icon-only button. -- 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: - -```html live -
- - - -
-
- - -
-
- - - -
-``` - -## Tooltip alignment -Align tooltips to the left or right of an element, combined with a directional class to specify north or south. Use a modifier of `1` or `2` to choose how much the tooltip's arrow is indented. - -```html live -
- - -
-
- - -
-
- - -
-
- - -
-``` - -## 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 live -
- -
-``` - -## Tooltips with 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 `.tooltipped-no-delay` modifier class you can use to override this. - -```html live -
- -
-``` diff --git a/docs/content/components/truncate.md b/docs/content/components/truncate.md deleted file mode 100644 index c3665463fd..0000000000 --- a/docs/content/components/truncate.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: Truncate -path: components/truncate -status: Alpha -source: 'https://github.com/primer/css/tree/main/src/truncate' -rails: 'https://primer.style/view-components/components/beta/truncate' -bundle: truncate ---- - -When text reaches lengths larger than existing container, shorten with ellipses. - -## Truncate - -Adding the `.Truncate` class and wrapping the inner text with `.Truncate-text` will truncate the text. `.Truncate-text` must be a direct descendant of `.Truncate`. - -```html live -
- - branch-name-that-is-really-long - -
-``` - -## Truncate multiple items - -You can add multiple `.Truncate-text` items in the same row and they will truncate evenly. If you want to make one of the items the primary text that doesn't truncate first, add the class `.Truncate-text--primary` class. - -```html live -
- - really-long-repository-owner-name - - / really-long-repository-name - - -
-``` - -`.Truncate-text--primary` doesn't need to be the last item in the list or only have one instance. Consider this breadcrumb example where we want to highlight the Repository name and the Issue title. The rest of the breadcrumb will truncate and leave the name and title untruncated until we run out of space. - -```html live -
-
    -
  1. primer
    2. -
  2. / css
    3. -
  3. / Issues
    4. -
  4. / #123 —
    5. -
  5. - Visual bug on primer.style found in lists -
    6. -
-
-``` - -## Expand on hover or focus - -When there are multiple items in a list, you can add the `.Truncate-text--expandable` class to the `.Truncate-text` items and they will grow when `:hover` or `:focus` state is applied to them. - -```html live -
- - really-long-repository-owner-name - really-long-repository-owner-name - really-long-repository-owner-name - really-long-repository-owner-name - -
-``` - -## Custom max widths - -It is recommended to use `max-width` as an inline style when you would like to have control over how far something can grow, even when there's enough space available. - -```html live -
-
- branch-name-that-is-really-long-branch-name-that-is-really-long-branch-name-that-is-really-long -
-
-
- branch-name-that-is-really-long-branch-name-that-is-really-long-branch-name-that-is-really-long -
-
-
- branch-name-that-is-really-long-branch-name-that-is-really-long-branch-name-that-is-really-long -
-
-``` diff --git a/docs/content/components/underline-nav.md b/docs/content/components/underline-nav.md deleted file mode 100644 index 6d89cb0f65..0000000000 --- a/docs/content/components/underline-nav.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: UnderlineNav -path: components/underline-nav -status: Stable -source: 'https://github.com/primer/css/tree/main/src/navigation' -rails: 'https://primer.style/view-components/components/alpha/underlinenav' -bundle: navigation ---- - -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. - -To add a selected state to an item, use: - -- `role="tab"` and `aria-selected="true"` if it's a button -- `aria-current="page"` if it's a link - -```html live title="UnderlineNav" - -``` - -Use `.UnderlineNav-actions` to place another element, such as a button, to the opposite side of the navigation items. - -```html live title="UnderlineNav-actions" - -``` - -Use `.UnderlineNav--right` to right align the navigation. - -```html live title="UnderlineNav--right" - -``` - -`.UnderlineNav--right` also works with when used with `.UnderlineNav-actions`. - -```html live title="UnderlineNav--right with actions" - -``` - - - -`.Counters` and `.octicons` can be used with navigation items. Use `.UnderlineNav-octicon` to add color and hover styles. - -```html live - -``` - -Use `.UnderlineNav--full` in combination with container styles and `.UnderlineNav-container` to make navigation fill the width of the container. - -```html live title="UnderlineNav--full" - -``` diff --git a/docs/content/getting-started/contributing.md b/docs/content/getting-started/contributing.md deleted file mode 100644 index 158d8123b6..0000000000 --- a/docs/content/getting-started/contributing.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: Contributing -description: Guidelines for contributing to GitHub's CSS ---- - -While this contributing guide is for GitHub employees, all contributions from the community are welcome. - -## Decision process for adding new styles - -### Components - -[Components](/components) are frequently used visual patterns we've abstracted into a set of convenient styles, that would be otherwise difficult to achieve with utilities. - -Decisions to add new components are made on a case-by-case basis, with help from the GitHub Design Systems team. Some questions that we use to guide these decisions include: - -- How often is this pattern used across the site? -- Could these styles be achieved with existing components and utilities? -- If your design is difficult to compose with current styles, does this highlight problems with existing components (such as overly-specific components, or missing utilities)? -- Is this a totally new pattern or should it be an extension of an existing component? -- How is this pattern being implemented currently - have you identified problems with it’s current implementation that can be improved with adding a new pattern? -- Is the desire for this new pattern a side-effect of lacking documentation or misunderstanding of use with current styles? -- Are there special factors that need to be considered as to why the this pattern needs it’s own styles? Such legal issues, usability issues, or branding and trademarks? -- Is this something that would be better handled by other front-end code rather than CSS? -- Every new addition of CSS means we ask our users to download a larger CSS file, and we increase the maintenance work of our CSS framework. Does the convenience of adding these new styles outweigh those costs? - -### Utilities - -Many of the same questions can be applied to utilities, however the purpose of these styles is different: - -[Utilities](/utilities) do one thing well and one thing only. These styles are immutable and therefore often use the `!important` tag. For this reason we aim not to change the properties of utilities very often. They often form the building blocks of our pages and when we introduce new ones we need to do so with care as we'll likely need to live with these styles for a long time. When assessing whether there is a need to add a new utility, consider these additional questions: - - How does this new utility fit within our existing set of utilities? If it is an addition to an existing set then it should follow the same naming convention. - - Is it for a property that would likely need to be changed at different breakpoints? If so it may need responsive options. - - If this style is part of a family of properties, do we need to consider adding the full set? Reasons for adding a full set could be that the other property values are often used, or that there would be a need to switch the property on and off (such as display or visibility). - - Does introducing this new utility cause any clashes or potential confusion with the use of existing utilities? If so, what steps can we take to avoid those issues. - - Does the utility have a connection with a set of variables? If so do the corresponding variables need to be updated? - -## Step-by-step instructions for adding new styles - -### Step 1: Open an issue - -It's usually better to open an issue before investing time in spiking out a new pattern. This gives the design systems team a heads up and allows other designers to share thoughts. Here's an outline of what's helpful to include in a new style issue: - -1. What the pattern is, and how it's being used on GitHub.com. Post screenshots and/or URLs whenever possible. If you need help identifying where the pattern is used, call that out in the issue. -2. Why you think a new pattern is needed (this should answer the relevant questions above). -3. If you intend to work on these new styles yourself, let us know what your timeline and next steps are. If you need help and this is a dependency for shipping another project, please make that clear here and what the timeline is. -4. Add the appropriate label(s): - - `Type: Enhancement` for new styles - - `Type: Bug Fix` for—you guessed it!—bug fixes - - `Type: Polish` for refactors of existing styles - - `Type: Breaking Change` for any change that [removes CSS selectors or SCSS variables](#removing-styles-and-variables) - -### Step 2: Design and build the new styles - -- You may want to explore the visual design for a new component before spiking it out in code. If so, continue in the issue and post your design mockups. Using our [CodePen template](https://codepen.io/team/GitHub/pen/xYLdZd) could also be a good option, it pulls in Primer CSS so you can explore options in isolation before jumping into production code. -- When you're ready, spike out a branch and build out your new component, object, or utilities according to the style guide principles, ensuring you follow our naming convention for each of the styles. -- Refactor parts of the product where you think those new styles could be used to test they work for each use case. This does not mean for every instance, but enough of the key use cases to be sure the styles are flexible enough. To avoid blowing out your initial pull request we recommend you do larger amounts of refactoring in an additional branch. -- When you're ready for review, add the `status: review needed` and the `design-systems` labels to your pull request. Follow the [ship checklist](#ship-checklist) for additional shipping steps. - -### Step 3: Follow up with refactoring - -New styles we add should be used in as many places as makes sense to in production. Often it takes time to refactor all instances to use the new styles in one pr, but you should ensure this is followed up on. - -- Add a tracking issue to the design systems repo with the label `type: refactor`. Add a task list with links to the code or pages that need updating. If you need help, request help in this issue. -- Follow up with as many refactoring pull requests as you can make time for. This is an important part of the process and helps us reduce CSS bloat. Think of it as the project isn't finished until the new styles are being used everywhere they should be in production. - -### Step 4: Feel awesome - -If you get to this step you've helped contribute to a style guide that many of your colleagues use on a daily basis, you've contributed to an open source project that's referenced and used by many others, and you've helped improve the usability and consistency of GitHub for our users. Thank you! - -[Please open an issue](#step-1-open-an-issue) if we can improve these guidelines and make following this process any easier. - - -## Documentation structure - -- Our documentation site for Primer CSS is built using [Doctocat](https://primer.style/doctocat) and deployed with [Vercel](https://vercel.com/). Our site is built from the `docs` folder and uses [MDX](https://mdxjs.com) to render markdown. - -- Documentation for Primer CSS modules should live in the corresponding `.md` or `.mdx` file for that module in the `/docs/content` folder. - -- There are separate folders in `/docs/content` for component, object, support, and utilities docs, as well as separate folders for more general documentation such as principles and tooling. - -- Documents in `docs/content/` automatically become pages with URLs based on their path relative to `content/`. For example, `docs/content/components/box.md` creates a `/components/box` page. - -- To add new documentation, locate the appropriate folder and create a new `.md` or `.mdx` file. Be sure to include the proper front matter (at minimum, title and status). For example: - -``` ---- -title: Alerts -status: Stable -source: 'https://github.com/primer/css/tree/main/src/alerts' ---- -``` - -### Table of contents - -A table of contents is automatically inserted at the top of every page published on [primer.style/css](https://primer.style/css). - -### Navigation - -For new components or doc pages, add the title and url to [nav.yml](https://github.com/primer/css/blob/main/docs/src/%40primer/gatsby-theme-doctocat/nav.yml). - -### Live code - -Check out Doctocat's [live code](https://primer.style/doctocat/usage/live-code) documentation for more information about creating live code examples. - -### Versioning - -Primer CSS follows [semantic versioning](http://semver.org/) conventions. This helps others know when a change is a patch, minor, or breaking change. - -To understand what choice to make, you'll need to understand semver and know if one of the changes shown is a major, minor, or patch. Semver is confusing at first, so we recommend reviewing [semver](http://semver.org/) and/or asking the team by [opening an issue](#step-1-open-an-issue). - -[semantic versioning]: https://semver.org -[script/test-deprecations.js]: https://github.com/primer/css/tree/main/script/test-deprecations.js -[deprecations.js]: https://github.com/primer/css/tree/main/deprecations.js diff --git a/docs/content/index.mdx b/docs/content/index.mdx deleted file mode 100644 index 2960ebd40c..0000000000 --- a/docs/content/index.mdx +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Primer CSS ---- - -import {HeroLayout} from '@primer/gatsby-theme-doctocat' -import {Grid, Box, Heading, Text, ButtonOutline, BorderBox} from '@primer/components' -import {Link} from 'gatsby' -import utilitiesImage from '../src/utilities-image.svg' -import componentsImage from '../src/components-image.svg' -import typographyImage from '../src/typography-image.png' -import colorImage from '../src/color-image.svg' -import spacingImage from '../src/spacing-image.svg' - -export default HeroLayout - -# Introduction - -Our goal is to create a system that enables us to build consistent user experiences with ease, yet with enough flexibility to support the broad spectrum of GitHub websites. This goal is embedded in our design and code decisions. Our approach to CSS is influenced by Object Oriented CSS principles, functional CSS, and BEM architecture. - -## Highly reusable, flexible styles - -Styles can be mixed and matched to achieve many different layouts, independent of their location. These styles fall into two categories: - - - {[ - { - name: 'Utilities', - description: 'Single purpose, immutable styles, that do one thing well.', - image: utilitiesImage - }, - {name: 'Components', description: 'Abstracted patterns for frequently used visual styles.', image: componentsImage} - ].map(({name, description, image}) => ( - - {name} - - {name} - -

{description}

- - ))} - - -## Systematically designed for GitHub - -Primer CSS is built upon systems that form the foundation of our styles such as spacing, typography, and color. This systematic approach helps ensure our styles are consistent and interoperable with each other. - - - {[ - { - name: 'Highly composable spacing scale', - description: - 'The base-8 spacing scale is highly composable and works with the density of GitHub’s content. Margin and padding spacers bring consistency to vertical and horizontal rhythm, while remaining flexible so you can tweak layouts to work for every context.', - image: spacingImage - }, - { - name: 'Customizable typography', - description: - 'Font size and line-height options work together to result in more sensible numbers. Font styles come in a range of weights and sizes so that we can style appropriately for content and readability. Type utilities allow us to change the visual styles while keeping markup semantic.', - image: typographyImage - }, - { - name: 'Meaningful color', - description: - 'The color system allows us to add meaningful signals to content and interactions. Color variables and utilities offer thematic styling options without being tied to structure. Text and background colors come in a range of accessible combinations to ensure we build inclusive interfaces.', - image: colorImage - } - ].map(({name, description, image}) => ( - - {name} - - - {name} - -

{description}

- - - ))} - - -## Structure - -Primer CSS is published to npm as `@primer/css`. Each of Primer CSS's "modules" lives in a subfolder under `src/` with an `index.scss` in it. Generally speaking, the styles are divided into three primary themes: - -- **Core** styles (in `core/`) are common dependencies, which include support variables, native element and typography styles, buttons, navigation, tooltips, etc. -- **Product** styles (in `product/`) are specific to github.com, and include components such as avatars, labels, markdown styles, popovers, and progress indicators. -- **Marketing** styles (in `marketing/`) are specific to GitHub marketing efforts, including international and event-focused sites as well as the more design-heavy feature pages on github.com. Marketing styles include new colors and button styles, and extend the core typography and whitespace scales. - - - - Use Primer CSS in your project - - - Pick and choose what you need. Install the entire Primer CSS bundle or import individual folders. - -
- - Installation instructions - - diff --git a/docs/content/marketing/index.md b/docs/content/marketing/index.md deleted file mode 100644 index 0d3b44dd48..0000000000 --- a/docs/content/marketing/index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Marketing -path: marketing/index ---- - -The marketing components and utilities are meant for marketing pages. Note that on github.com they are not available for product pages. diff --git a/docs/content/stickersheet/index.md b/docs/content/stickersheet/index.md deleted file mode 100644 index d6347aec46..0000000000 --- a/docs/content/stickersheet/index.md +++ /dev/null @@ -1,216 +0,0 @@ ---- -title: Sticker Sheet -path: stickersheet/ ---- - -### Light/Dark - -```html live - -
-
- - - - Icon - -
- -1.5K Counter - -
- -Label -Danger -Success -Info - -
- -IssueLabel -IssueLabel - -
- -Default - - - - Open - - - - - Closed - - - -
- - - -
- - - -
- - - -
- - - -
- - - -
- -
- -
- -
- - - -
- -
Flash alert
- -
- -
-
- - - - Header - -
-
- - -
-
- - - - - Icon - -
- -1.5K Counter - -
- -Label -Danger -Success -Info - -
- -IssueLabel -IssueLabel - -
- -Default - - - - Open - - - - - Closed - - - -
- - - -
- - - -
- - - -
- - - -
- - - -
- -
- -
- -
- - - -
- -
Flash alert
- -
- -
-
- - - - Header - -
-
- - - -
-
- - - - - - -``` diff --git a/docs/content/stickersheet/labels.md b/docs/content/stickersheet/labels.md deleted file mode 100644 index b603afe3bf..0000000000 --- a/docs/content/stickersheet/labels.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: Labels -path: stickersheet/labels -status: Deprecated -source: 'https://github.com/primer/css/tree/main/src/labels' -bundle: labels ---- - -```html live -

-The base label component styles the text, adds padding and rounded corners, and a border. Labels come in various themes which apply different colors. -

- -
Hello world
- -
Hello world
-
Hello world
-
Hello world
-
Hello world
-
Hello world
-
Hello world
- -
- -Gray -Default -Dark gray -Pending -Warning -Error -Success -Info - -
- -Gray -Default -Dark gray -Pending -Warning -Error -Success -Info - -
- -Primer - -🐻 Next - - -
- -Primer - -🐻 Next - -``` - -### States - -```html live -Default - - - - Open - - - - - Closed - - -
- -Default - - - - Open - - - - - Closed - -``` - -### Counters - -```html live -1 -23 -456 - -
- -
- -
- -
- -1.5K - - - - 10 - -👍 2 -22 -22 -22 - -
- -1 -23 -456 -1.5K -
-1 -23 -456 -1.5K -``` diff --git a/docs/content/stickersheet/sizes.md b/docs/content/stickersheet/sizes.md deleted file mode 100644 index 9baf677814..0000000000 --- a/docs/content/stickersheet/sizes.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: Sticker Sheet -path: stickersheet/sizes ---- - -### Sizes - -```html live - -16px - - - - - -
- -20px - -Label -IssueLabel -1.5K - - -
- -24px - -Label -IssueLabel -State - - -
- -28px - - - - - -
- -32px - - - - - -State - -
- -40px - -
- -
- -
- -48px - - -
Flash alert
- -
- -64px - -
-
- - - - Header - -
-
- -``` diff --git a/docs/content/support/index.md b/docs/content/support/index.md deleted file mode 100644 index 065f5863f9..0000000000 --- a/docs/content/support/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Support -path: support/index -source: 'https://github.com/primer/css/tree/main/src/support' -bundle: support ---- - - -Primer CSS 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](/support/breakpoints) -- [Spacing](/support/spacing) -- [Theming](/support/theming) -- [Typography](/support/typography) diff --git a/docs/content/support/spacing.md b/docs/content/support/spacing.md deleted file mode 100644 index ce888d98a0..0000000000 --- a/docs/content/support/spacing.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: Spacing -path: support/spacing -status: Stable -source: 'https://github.com/primer/css/blob/main/src/support/variables/layout.scss' -bundle: support ---- - -import {Text} from '@primer/components' - -## Spacing scale - -The spacing scale is a **base-8** scale. We chose a base-8 scale because eight is a highly composable number (it can be divided and multiplied many times and result in whole numbers), yet allows spacing dense enough for GitHub's UI. The scale's exception is that it begins at 4px to allow smaller padding and margin for denser parts of the site, from there on it steps up consistently in equal values of `8px`. - -| Variable | Scale | Value | -| ----------- | ----- | ----- | -| `$spacer-0` | 0 | 0 | -| `$spacer-1` | 1 | 4px | -| `$spacer-2` | 2 | 8px | -| `$spacer-3` | 3 | 16px | -| `$spacer-4` | 4 | 24px | -| `$spacer-5` | 5 | 32px | -| `$spacer-6` | 6 | 40px | - -These variables are encouraged to be used within components and custom CSS. The spacing scale is also used for [margin](/utilities/margin) and [padding](/utilities/padding) utilities. - -### Extended spacing scale - -These are primarily useful for achieving bigger vertical spacing between sections. This scale first steps up with `8px` for spacer 7, then steps in increments of `16px` from spacer 8 up to 12. - -| Variable | Scale | Value | -| ------------ |-------|-------| -| `$spacer-7` | 7 | 48px | -| `$spacer-8` | 8 | 64px | -| `$spacer-9` | 9 | 80px | -| `$spacer-10` | 10 | 96px | -| `$spacer-11` | 11 | 112px | -| `$spacer-12` | 12 | 128px | - -The extended spacing scale is used for [margin](/utilities/margin) and [padding](/utilities/padding) utilities along the Y-axis, as well as for single side spacing utilities (top, right, bottom, left). - -## Em-based spacing - -Ems are used for spacing within components such as buttons and form elements. We stick to common fractions for em values (and powers of 2 where possible) so that , in combination with typography and line-height, the total height lands on sensible numbers. - -We aim for whole numbers, however, GitHub's body font-size is 14px which is difficult to work with, so we sometimes can't achieve a whole number. Less desirable values are highlighted in red below. - -| Variable | Fraction | Y Padding (em) | Total height at 14px | Total height at 16px | -| -------------- | -------- | -------------- | -------------------------------- | -------------------- | -| `$em-spacer-1` | 1/16 | .0625 | 22.75 | 26 | -| `$em-spacer-2` | 1/8 | .125 | 24.5 | 28 | -| `$em-spacer-3` | 1/4 | .25 | 28 | 32 | -| `$em-spacer-4` | 3/8 | .375 | 31.5 | 36 | -| `$em-spacer-5` | 1/2 | .5 | 35 | 40 | -| `$em-spacer-6` | 3/4 | .75 | 42 | 48 | - -The variables listed above are preferred for use within components and custom CSS. To calculate values with other font-sizes or em values, we suggest using [Formula](https://jxnblk.github.io/formula/). diff --git a/docs/content/support/variables.mdx b/docs/content/support/variables.mdx deleted file mode 100644 index c2af8a2b37..0000000000 --- a/docs/content/support/variables.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Variables -path: support/variables -status: Stable ---- - -import {Variables, DeprecationIcon} from '../../src/variables' - - - -The tables below list all of the global SCSS variables defined in [the `support/variables` directory](https://github.com/primer/css/tree/main/src/support/variables). - -Variables with a are planned for [deprecation](../tools/deprecations) in a future version of `@primer/css`, and should be avoided. - - diff --git a/docs/content/tools/deprecations.md b/docs/content/tools/deprecations.md deleted file mode 100644 index 5204370d8b..0000000000 --- a/docs/content/tools/deprecations.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Deprecation data ---- - -As of version 12.7.0, we publish CSS selector and SCSS variable deprecation data (as of 14.0.0) with `@primer/css`. You can access the data via the [Node API](#node) or as [JSON](#json). - -To deprecate a class, variable, or mixin, add the element to the [deprecations.js](https://github.com/primer/css/blob/main/deprecations.js) file with it's replacement value. - -The replacement can be: - -* A `String` for a direct replacement. -* An `Array` for multiple replacement options. -* `null` to indicate there is no replacement. - -This could look something like this: - -```js -const deprecations = { - "deprecated-1": "replacement", - "deprecated-2": ["replacement-1", "replacement-2"], - "deprecated-3": null -} -``` - -## JSON - -The JSON data is available in the unpacked node module's `dist/deprecations.json`, and is an object with the following structure: - -```json -{ - "selectors" {...}, - "variables": {...}, - "mixins": {...} -} -``` - -* `selectors` is an object mapping CSS selectors to their replacements. If the replacement is an Array, then there's multiple options. If the replacement is null then there are no replacements. - - ```json - { - "selectors": { - "deprecated-class": "replacement-class" - } - } - ``` - -* `variables` is an object mapping SCSS variables to their replacement SCSS variable. - - ```json - { - "variables": { - "$deprecated-variable": "$replacement-variable" - } - } - ``` - -* `mixins` is an object mapping SCSS mixins to their replacement SCSS mixins. - - ```json - { - "mixins": { - "deprecated-mixin": "replacement-mixin" - } - } - ``` - - -## Node - -The Node API for selector deprecations is available at -`@primer/css/deprecations`. - -### Example: - -```js -const { - deprecatedSelectors, - deprecatedSassVariables, - deprecatedSassMixins -} = require('@primer/css/deprecations') - -``` diff --git a/docs/content/tools/index.md b/docs/content/tools/index.md deleted file mode 100644 index 4f806f80e9..0000000000 --- a/docs/content/tools/index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Tools -path: tools/index ---- - -Design and development tools for working with the GitHub CSS toolkit. diff --git a/docs/content/tools/testing.md b/docs/content/tools/testing.md deleted file mode 100644 index e5ed09dd14..0000000000 --- a/docs/content/tools/testing.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Testing resources -path: tools/testing ---- - -At GitHub we use a staging environment called review-lab for testing with production data. Deploying a branch to [review-lab](https://github.com/github/github/blob/master/docs/deployment.md#test-in-lab-environments) for testing is one of the best ways to test your work with real production data prior to an actual production deployment. - -To make testing on review-lab for extended periods of time easier, you can use the [Redirector](https://chrome.google.com/webstore/detail/redirector/pajiegeliagebegjdhebejdlknciafen) extension for Chrome to redirect all GitHub.com traffic to your review-lab deploy URL. - -## How to use it - -1. Install the [extension](https://chrome.google.com/webstore/detail/redirector/pajiegeliagebegjdhebejdlknciafen) -2. Open the extension options panel from the icon in Chrome -3. In the "From" field, enter: `https:\/\/github\.com\/?(.+)?` -4. In the "To" field, enter: `https://branchname.review-lab.github.com/$1` where `branchname` is the name of your branch. - -## Tips - -- You'll need to remove your rule or simply disable the extension when you want to stop redirecting to your branch. -- If you're trying to reach GitHub.com or your review-lab URL but are getting a "This page isn't working" message in your browser, that means your review-lab deploy has gone stale and needs to be redeployed. diff --git a/docs/content/utilities/animations.md b/docs/content/utilities/animations.md deleted file mode 100644 index e7864263e4..0000000000 --- a/docs/content/utilities/animations.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: Animations -path: utilities/animations -example_layout: toggle -status: Stable -source: 'https://github.com/primer/css/blob/main/src/utilities/animations.scss' -bundle: utilities ---- - -Animations are reusable animation classes that you can use to emphasize an element. All of these animations will animate if you toggle their visibility using the "Toggle" button. - - - -## Fade in - -The `.anim-fade-in` class is used to fade in an element on the page. This will run once when the element is revealed. - -```html live - - - - Hello from GitHub! - -``` - -## Fade out - -The `.anim-fade-out` class is used to fade out an element on the page. This will run once when the element is revealed. - -```html live - - - - Hello from GitHub! - -``` - -## Fade up - -The `.anim-fade-up` class is used to reveal an element on the page by sliding it up from below the fold. You should use this in a container with `overflow: hidden;` or on the bottom of the page. - -```html live -
- - - Hello from GitHub! -
-``` - -## Fade down - -The `.anim-fade-down` class is used to slide an element down hiding it. You should use this in a container with `overflow: hidden;` or on the bottom of the page. - -```html live -
- - - Hello from GitHub! -
-``` - -## Scale in - -The `.anim-scale-in` class will scale the element in. This is useful on menus when you want them to appear more friendly. - -```html live -
- - -
-``` - -## Grow x - -The `.anim-grow-x` class will grow an element width from 0-:100: real quick. - -```html live -
-``` - -## Pulse - -The `.anim-pulse` class will pulse an element infinitely. - -```html live - - -``` - -## Hover animation - -The `.anim-hover-grow` class will increase the scale of the element upon hover. - -```html live -
- - -
-``` - -## Rotation - -The `.anim-rotate` class will rotate the element indefinitely around the coordinate specified by `transform-origin`. Most elements have a default of `transform-origin: 50% 50%` and will rotate around the center. - -```html live - - -``` diff --git a/docs/content/utilities/borders.mdx b/docs/content/utilities/borders.mdx deleted file mode 100644 index fa1d4f6f4c..0000000000 --- a/docs/content/utilities/borders.mdx +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: Borders -path: utilities/borders -status: Stable -status_issue: 'https://github.com/github/design-systems/issues/72' -source: 'https://github.com/primer/css/tree/main/src/utilities/borders.scss' -bundle: utilities ---- - -Utilities for borders, and border radius. - -## Default border - -The default border utility applies a solid, 1px border, with a default gray color. - -```html live -
- .border -
-``` - -Borders can be applied to a specific edge or to the X and Y axes individually: - -```html live -
-
- .border-left -
-
- .border-top -
-
- .border-bottom -
-
- .border-right -
-
-
- .border-x -
-
- .border-y -
-``` - -Remove borders from all sides or a single side with `.border-0`, `.border-top-0`, `.border-right-0`, `.border-bottom-0`, `.border-left-0`. - -```html live -
- .border-top-0 -
-``` - -## Border style - -Use `border-dashed` to give an element a dashed border. - -```html live -
- .border-dashed -
-``` - -## Rounded corners - -Use the following utilities to add or remove rounded corners: `rounded-0` removes rounded corners, `rounded-1` applies a border radius of 4px, `rounded-2` applies a border radius of 6px, and `rounded-3` applies a border radius of 8px. `.circle` applies a border radius of 50%, which turns square elements into perfect circles. - -```html live -
- .rounded-0 -
-
- .rounded-1 -
-
- .rounded-2 -
-
- .rounded-3 -
-
- .circle -
-``` - -You can also add rounded corners to each edge (top, right, bottom, left) with the following utilities: - -```html live -
- .rounded-top-2 -
-
- .rounded-right-2 -
-
- .rounded-bottom-2 -
-
- .rounded-left-2 -
-``` - -## Responsive borders - -You can adjust border widths on all sides or each side individually with responsive border utilities: - -- `border-(sm|md|lg|xl)` adds borders on all sides at and above the breakpoint. The `border-(sm|md|lg|xl)` shorthand is also supported. -- `border-(sm|md|lg|xl)-0` removes borders from all sides at and above the breakpoint. -- `border-(sm|md|lg|xl)-(top|right|bottom|left)` adds a border on the given side at and above the breakpoint. -- `border-(sm|md|lg|xl)-(top|right|bottom|left)-0` the border from the given side at and above the breakpoint. - -```html live -
- .border-top - .border-sm-right - .border-md-bottom - .border-md-top-0 -
-``` - -## Border colors - -Border colors are documented on the [colors utilities page](../utilities/colors#border). diff --git a/docs/content/utilities/box-shadow.md b/docs/content/utilities/box-shadow.md deleted file mode 100644 index 3980f632a0..0000000000 --- a/docs/content/utilities/box-shadow.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: Box shadow -path: utilities/box-shadow -status: Stable -status_issue: 'https://github.com/github/design-systems/issues/269' -source: 'https://github.com/primer/css/tree/main/src/utilities/box-shadow.scss' -bundle: utilities ---- - -Box shadows are used to make content appear elevated. They are typically applied to containers of content that users need to pay attention to or content that appears on top of (overlapping) other elements on the page (like a pop-over or modal). - -## Small - -Small shadows are mainly used on things that need to appear slightly elevated, like pricing cards or UI elements containing important information. - -```html live -
- .color-shadow-small -
-``` - -These types of shadows are typically applied to elements with borders, such as the [Box component](/components/box). - -```html live -
-
-
-

Organization

-
-
-

- Taxidermy live-edge mixtape, keytar tumeric locavore meh selvage deep v letterpress vexillologist lo-fi tousled - church-key thundercats. Brooklyn bicycle rights tousled, marfa actually. -

-
-
- -
-
-
-``` - -## Medium - -Medium box shadows are more diffused and slightly larger than small box shadows. - -```html live -
- .color-shadow-medium -
-``` - -Medium box shadows are typically used on editorialized content that needs to appear elevated. Most of the time, the elements using this level of shadow will be clickable. - -```html live -
- -
-

Serverless architecture

-

- Build powerful, event-driven, serverless architectures with these open-source libraries and frameworks. -

-
    -
  • - - - 12 Repositories -
    • -
  • - - - 5 Languages -
    • -
- -
-``` - -## Large - -Large box shadows are very diffused and used sparingly in the product UI. - -```html live -
- .color-shadow-large -
-``` - -These shadows are used for marketing content, UI screenshots, and content that appears on top of other page elements. - -```html live -
- NASA is on GitHub -
-``` - -## Extra large - -Extra large box shadows are even more diffused. - -```html live -
- .color-shadow-extra-large -
-``` - -These shadows are used for marketing content and content that appears on top of other page elements. - -## Remove a box shadow - -Additionally there is a `box-shadow-none` class that removes `box-shadow`: - -```html live -
- .box-shadow-none -
-``` diff --git a/docs/content/utilities/colors.mdx b/docs/content/utilities/colors.mdx deleted file mode 100644 index a4cb414641..0000000000 --- a/docs/content/utilities/colors.mdx +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: Colors -description: 'Immutable, atomic CSS classes to rapidly build product' -status: Beta ---- - - - Please note Primer CSS v18 has changed the naming of these color classes. Check the migration guide to make sure your app is up to date. - - -Use color utilities to apply color to the background of elements, text, and borders. These utilities should only be used where color is not provided by a component. To learn more about how to apply color, read the [color documentation](https://primer.style/design/foundations/color) in the [interface guidelines](https://primer.style/design/). - -## Text - -Use text color utilities to set text to a specific color. Color contrast must pass a minimum WCAG accessibility rating of [level AA](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html). This ensures that viewers who cannot see the full color spectrum are able to read the text. To customize outside of the suggested combinations below, we recommend using this [color contrast testing tool](https://colorable.jxnblk.com/). For more information, read our [accessibility standards](../principles/accessibility). - -```html live -
.color-fg-default
-
.color-fg-muted
-
.color-fg-subtle
- -
.color-fg-accent
-
.color-fg-success
-
.color-fg-attention
-
.color-fg-severe
-
.color-fg-danger
-
.color-fg-open
-
.color-fg-closed
-
.color-fg-done
-
.color-fg-sponsors
- -
.color-fg-on-emphasis
-``` - -You can set the color inheritance on an element by using the `color-fg-inherit` class. - -```html live -
This text is green, including the link
-``` - -## Background - -Background colors are most commonly used for filling large blocks of content or areas with a color. When selecting a background color, make sure the foreground color contrast passes a minimum WCAG accessibility rating of [level AA](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html). Meeting these standards ensures that content is accessible by everyone, regardless of disability or user device. You can [check your color combination with this demo site](https://colorable.jxnblk.com/). For more information, read our [accessibility standards](../principles/accessibility). - -```html live -
.color-bg-default
-
.color-bg-overlay
-
.color-bg-inset
-
.color-bg-subtle
-
.color-bg-emphasis
- -
.color-bg-accent
-
.color-bg-accent-emphasis
- -
.color-bg-success
-
.color-bg-success-emphasis
- -
.color-bg-attention
-
.color-bg-attention-emphasis
- -
.color-bg-severe
-
.color-bg-severe-emphasis
- -
.color-bg-danger
-
.color-bg-danger-emphasis
- -
.color-bg-open
-
.color-bg-open-emphasis
- -
.color-bg-closed
-
.color-bg-closed-emphasis
- -
.color-bg-done
-
.color-bg-done-emphasis
- -
.color-bg-sponsors
-
.color-bg-sponsors-emphasis
- -
.color-bg-transparent
-``` - -## Border - -Override default border colors with the following utilities. - -```html live -
.color-border-default
-
.color-border-muted
-
.color-border-subtle
- -
.color-border-accent
-
.color-border-accent-emphasis
- -
.color-border-success
-
.color-border-success-emphasis
- -
.color-border-attention
-
.color-border-attention-emphasis
- -
.color-border-severe
-
.color-border-severe-emphasis
- -
.color-border-danger
-
.color-border-danger-emphasis
- -
.color-border-open
-
.color-border-open-emphasis
- -
.color-border-closed
-
.color-border-closed-emphasis
- -
.color-border-done
-
.color-border-done-emphasis
- -
.color-border-sponsors
-
.color-border-sponsors-emphasis
-``` - -## Link - -You can use the [Link](../components/links) component to change the link colors. diff --git a/docs/content/utilities/details.md b/docs/content/utilities/details.md deleted file mode 100644 index ba88444b0d..0000000000 --- a/docs/content/utilities/details.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: Details -path: utilities/details -status: Stable -source: 'https://github.com/primer/css/blob/main/src/utilities/details.scss' -bundle: utilities ---- - -Details classes are created to enhance the native behaviors of `
`. - -## Fullscreen click area - -Use `.details-overlay` to expand the click area of `` to cover the full screen, so user can click anywhere on a page to close `
`. - -```html live -
- More -
Hidden text
-
-``` - -## Darkened fullscreen click area - -Use `.details-overlay-dark` darken the click area overlay. Useful for modals. - -```html live -
- More -
- Hidden text -
-
-``` - -## Custom caret - -Use `.details-reset` to remove the default caret (that little triangle on the left). You then can add the `.dropdown-caret` on the right of the text. - -```html live -
- More -
Hidden text
-
-``` - -## 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 live -
- More -
Hidden text
-
- -
- More -
Hidden text
-
-``` diff --git a/docs/content/utilities/flexbox.md b/docs/content/utilities/flexbox.md deleted file mode 100644 index dc331eaf3a..0000000000 --- a/docs/content/utilities/flexbox.md +++ /dev/null @@ -1,786 +0,0 @@ ---- -title: Flexbox -path: utilities/flexbox -status: Stable -status_issue: 'https://github.com/github/design-systems/issues/157' -source: 'https://github.com/primer/css/blob/main/src/utilities/flexbox.scss' -bundle: utilities ---- - -Flex utilities can be used to apply `flexbox` behaviors to elements by using utility classes. - - - -## Required reading - -Before using these utilities, **you should be familiar with CSS3 Flexible Box spec**. If you are not, check out MDN's guide: - -📖 **[Using CSS Flexible Boxes](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Flexible_Box_Layout/Using_CSS_flexible_boxes)** - -## Flex container - -Use these classes to make an element lay out its content using the flexbox model. Each **direct** child of the flex container will become a flex item. - -### CSS - -```css -.d-flex { display: flex; } -.d-inline-flex { display: inline-flex; } -``` - -### Classes - -| Class | Description | -| --- | --- | -| `.d-flex` | The element behaves like a block and lays out its content using the flexbox model. | -| `.d-inline-flex` | The element behaves like an inline element and lays out its content using the flexbox model. | - -### Example using `.d-flex` - -```html live - -
-
flex item 1
-
flex item 2
-
flex item 3
-
-``` - -### Example using `.d-inline-flex` - -```html live - -
-
flex item 1
-
flex item 2
-
flex item 3
-
-``` - -## Flex direction - -Use these classes to define the orientation of the main axis (`row` or `column`). By default, flex items will display in a row. Use `.flex-column` to change the direction of the main axis to vertical. - -### CSS - -```css -.flex-row { flex-direction: row; } -.flex-row-reverse { flex-direction: row-reverse; } -.flex-column { flex-direction: column; } -.flex-column-reverse { flex-direction: column-reverse; } -``` - -### Classes - -| Class | Description | -| --- | --- | -| `.flex-row` | The main axis runs left to right (default). | -| `.flex-row-reverse` | The main axis runs right to left. | -| `.flex-column` | The main axis runs top to bottom. | -| `.flex-column-reverse` | The main axis runs bottom to top. | - -### Example using `.flex-column` - -```html live -
-
Item 1
-
Item 2
-
Item 3
-
-``` - -### Example using `.flex-column-reverse` - -This example uses the responsive variant `.flex-sm-column-reverse` to override `.flex-column` Learn more about responsive flexbox utilities **[here](#responsive-flex-utilities)**. Keep in mind that it won't affect screen readers or navigating with the keyboard and it's advised to keep the markup in a logical source order. - -```html live -
-
Item 1
-
Item 2
-
Item 3
-
-``` - -### Example using `.flex-row` - -This example uses the responsive variant `.flex-sm-row` to override `.flex-column` Learn more about responsive flexbox utilities **[here](#responsive-flex-utilities)**. - -```html live -
-
Item 1
-
Item 2
-
Item 3
-
-``` - -### Example using `.flex-row-reverse` - -This example uses the responsive variant `.flex-sm-row-reverse` to override `.flex-column` Learn more about responsive flexbox utilities **[here](#responsive-flex-utilities)**. Keep in mind that it won't affect screen readers or navigating with the keyboard and it's advised to keep the markup in a logical source order. - -```html live -
-
Item 1
-
Item 2
-
Item 3
-
-``` - -## Flex wrap - -You can choose whether flex items are forced into a single line or wrapped onto multiple lines. - -### CSS - -```css -.flex-wrap { flex-wrap: wrap; } -.flex-nowrap { flex-wrap: nowrap; } -.flex-wrap-reverse { flex-wrap: wrap-reverse; } -``` - -### Classes - -| Class | Description | -| --- | --- | -| `.flex-wrap` | Flex items will break onto multiple lines | -| `.flex-nowrap` | Flex items are laid out in a single line, even if they overflow (default) | -| `.flex-wrap-reverse` | Behaves the same as wrap but cross-start and cross-end are permuted. | - -### `flex-wrap` example - -```html live -
-
1
-
2
-
3
-
4
-
5
-
6
-
7
-
8
-
9
-
-``` - -### `flex-nowrap` example - -```html live -
-
1
-
2
-
3
-
4
-
5
-
6
-
7
-
8
-
9
-
-``` - -### `flex-wrap-reverse` example - -```html live -
-
1
-
2
-
3
-
4
-
5
-
6
-
7
-
8
-
9
-
-``` - -## Justify content - -Use these classes to distribute space between and around flex items along the **main axis** of the container. - -### CSS - -```css -.flex-justify-start { justify-content: flex-start; } -.flex-justify-end { justify-content: flex-end; } -.flex-justify-center { justify-content: center; } -.flex-justify-between { justify-content: space-between; } -.flex-justify-around { justify-content: space-around; } -``` - -### Classes - -| Class | Default behavior | -| --- | --- | -| `.flex-justify-start` | Justify all items to the left | -| `.flex-justify-end` | Justify all items to the right | -| `.flex-justify-center` | Justify items to the center of the container | -| `.flex-justify-between` | Distribute items evenly. First item is on the start line, last item is on the end line. | -| `.flex-justify-around` | Distribute items evenly with equal space around them | - -### flex-justify-start - -Use `.flex-justify-start` to align items to the start line. By default this will be on the left side of the container. If you are using `.flex-column`, the start line will be at the top of the container. - -```html live -
-
1
-
2
-
3
-
-``` - -### flex-justify-end - -Use `.flex-justify-end` to align items to the end line. By default this will be on the right side of the container. If you are using `.flex-column`, the end line will be at the bottom of the container. - -```html live -
-
1
-
2
-
3
-
-``` - -### flex-justify-center - -Use `.flex-justify-center` to align items in the middle of the container. - -```html live -
-
1
-
2
-
3
-
-``` - -### flex-justify-between - -Use `.flex-justify-between` to distribute items evenly in the container. The first items will be on the start line and the last item will be on the end line. - -```html live -
-
1
-
2
-
3
-
-``` - -### flex-justify-around - -Use `.flex-justify-around` to distribute items evenly, with an equal amount of space around them. Visually the spaces won't look equal, since each item has the same unit of space around it. For example, the first item only has one unit of space between it and the start line, but it has two units of space between it and the next item. - -```html live -
-
1
-
2
-
3
-
-``` - -## Align items - -Use these classes to align items on the **cross axis**. - -The cross axis runs perpendicular to the main axis. By default the main axis runs horizontally, so your items will align vertically on the cross axis. If you use [flex-column](#flex-direction) to make the main axis run vertically, your items will be aligned horizontally. - -### CSS - -```css -.flex-items-start { align-items: flex-start; } -.flex-items-end { align-items: flex-end; } -.flex-items-center { align-items: center; } -.flex-items-baseline { align-items: baseline; } -.flex-items-stretch { align-items: stretch; } -``` - -### Classes - -| Class | Behavior | -| --- | --- | -| `.flex-items-start` | Align items to the start of the cross axis | -| `.flex-items-end` | Align items to the end of the cross axis | -| `.flex-items-center` | Align items to the center of the cross axis | -| `.flex-items-baseline` | Align items along their baselines | -| `.flex-items-stretch` | Stretch items from start of cross axis to end of cross axis | - -### flex-items-start - -```html live -
-
1
-
2
-
3
-
4
-
-``` - -### flex-items-end - -```html live -
-
1
-
2
-
3
-
4
-
-``` - -### flex-items-center - -```html live -
-
1
-
2
-
3
-
4
-
-``` - -### flex-items-baseline - -With `.flex-items-baseline`, items will be aligned along their baselines even if they have different font sizes. - -```html live -
-
1
-
2
-
3
-
4
-
-``` - -### flex-items-stretch - -```html live -
-
1
-
2
-
3
-
4
-
-``` - -## Align content - -When the main axis wraps, this creates multiple main axis lines and adds extra space in the cross axis. Use these classes to align the lines of the main axis on the cross axis. - -### CSS - -```css -.flex-content-start { align-content: flex-start; } -.flex-content-end { align-content: flex-end; } -.flex-content-center { align-content: center; } -.flex-content-between { align-content: space-between; } -.flex-content-around { align-content: space-around; } -.flex-content-stretch { align-content: stretch; } -``` - -### Classes - -| Class | Description | -| --- | --- | -| `.flex-content-start` | Align content to the start of the cross axis | -| `.flex-content-end` | Align content to the end of the cross axis | -| `.flex-content-center` | Align content to the center of the cross axis | -| `.flex-content-between` | Distribute content evenly. First line is on the start of the cross axis, last line is on the end of the cross axis. | -| `.flex-content-around` | Stretch items from the start of the cross axis to the end of the cross axis. | -| `.flex-content-stretch` | Lines stretch to occupy available space. | - -### flex-content-start - -```html live -
-
1
-
2
-
3
-
4
-
5
-
6
-
7
-
8
-
9
-
10
-
11
-
12
-
-``` - -### flex-content-end - -```html live -
-
1
-
2
-
3
-
4
-
5
-
6
-
7
-
8
-
9
-
10
-
11
-
12
-
-``` - -### flex-content-center - -```html live -
-
1
-
2
-
3
-
4
-
5
-
6
-
7
-
8
-
9
-
10
-
11
-
12
-
-``` - -### flex-content-between - -```html live -
-
1
-
2
-
3
-
4
-
5
-
6
-
7
-
8
-
9
-
10
-
11
-
12
-
-``` - -### flex-content-around - -```html live -
-
1
-
2
-
3
-
4
-
5
-
6
-
7
-
8
-
9
-
10
-
11
-
12
-
-``` - -### flex-content-stretch - -```html live -
-
1
-
2
-
3
-
4
-
5
-
6
-
7
-
8
-
9
-
10
-
11
-
12
-
-``` - -## Flex - -Use this class to specify the ability of a flex item to alter its dimensions to fill available space. - -```css -.flex-1 { flex: 1; } -.flex-auto { flex: auto; } -.flex-grow-0 { flex-grow: 0; } -.flex-shrink-0 { flex-shrink: 0; } -``` - -| Class | Description | -| --- | --- | -| `.flex-1` | Fills available space | -| `.flex-auto` | Fills available space and auto-sizes based on the content | -| `.flex-grow-0` | Prevents growing of a flex item | -| `.flex-shrink-0` | Prevents shrinking of a flex item | - -### flex-1 - -Adding `.flex-1` makes the item grow in size to take up all the space that is available. - -```html live -
-
flex item
-
.flex-1
-
flex item
-
-``` - -Adding `.flex-1` to all flex items results in each item having the same size. - -```html live -
-
.flex-1
-
.flex-1
-
.flex-1
-
-``` - -### flex-auto - -Using `.flex-auto` fills the available space but also takes the size of the content into account. Type in the editor below to see the effect. - -```html live -
-
.flex-1
-
.flex-auto with a bit more text
-
.flex-1
-
-``` - -### flex-grow-0 - -Add `.flex-grow-0` to prevent an item from growing. This can be useful when used as a responsive variant. For example to stop growing when the viewport gets wider. - -```html live -
-
flex item
-
.flex-auto .flex-sm-grow-0
-
flex item
-
-``` - -### flex-shrink-0 - -Add `.flex-shrink-0` to prevent an item from shrinking. Note that for example text will not wrap and the flex items start to overflow if there is not enough space. - -```html live -
-
flex item
-
.flex-shrink-0
-
flex item
-
-``` - -## Align self - -Use these classes to adjust the alignment of an individual flex item on the cross axis. This overrides any `align-items` property applied to the flex container. - -### CSS - -```css -.flex-self-auto { align-self: auto; } -.flex-self-start { align-self: flex-start; } -.flex-self-end { align-self: flex-end; } -.flex-self-center { align-self: center; } -.flex-self-baseline { align-self: baseline; } -.flex-self-stretch { align-self: stretch; } -``` - -### Classes - -| Class | Description | -| --- | --- | -| `.flex-self-auto` | Inherit alignment from parent | -| `.flex-self-start` | Align to the start of the cross axis | -| `.flex-self-end` | Align to the end of the cross axis | -| `.flex-self-center` | Align to center of cross axis | -| `.flex-self-baseline` | Align baseline to the start of the cross axis | -| `.flex-self-stretch` | Stretch item from start of cross axis to end of cross axis. | - -### flex-self-auto - -```html live -
-
.flex-self-auto
-
 
-
 
-
-``` - -### flex-self-start - -```html live -
-
.flex-self-start
-
 
-
 
-
-``` - -### flex-self-end - -```html live -
-
.flex-self-end
-
 
-
 
-
-``` - -### flex-self-center - -```html live -
-
.flex-self-center
-
 
-
 
-
-``` - -### flex-self-baseline - -```html live -
-
.flex-self-baseline
-
item
-
item
-
-``` - -### flex-self-stretch - -```html live -
-
.flex-self-stretch
-
 
-
 
-
-``` - -## Order - -Use these classes to change the order of flex items. Keep in mind that it won't affect screen readers or navigating with the keyboard and it's advised to keep the markup in a logical source order. - -### CSS - -```css -.flex-order-1 { order: 1; } -.flex-order-2 { order: 2; } -.flex-order-none { order: inherit; } - -``` - -### Classes - -| Class | Description | -| --- | --- | -| `.flex-order-1` | Set order to be 1 | -| `.flex-order-2` | Set order to be 2 | -| `.flex-order-none` | Remove order (typically used with responsive variants) | - -### flex-order (1+2) - -```html live -
-
1. .flex-order-2
-
2.
-
3. .flex-order-1
-
-``` - -### flex-order-none - -Resize window to see the effect. - -```html live -
-
1. .flex-order-1 .flex-sm-order-none
-
2.
-
3.
-
-``` - -## Responsive flex utilities - -All flexbox utilities can be adjusted per [breakpoint](/utilities/grid#breakpoints) using the following formulas: - -- `d-[breakpoint]-[property]` for `display` -- `flex-[breakpoint]-[property]-[behavior]` for various flex properties - -Each responsive style is applied to the specified breakpoint and up. - -### Example classes - -```css -/* Example classes */ - -.d-sm-flex {} -.d-md-inline-flex {} - -.flex-lg-row {} -.flex-xl-column {} - -.flex-sm-wrap {} -.flex-lg-nowrap {} - -.flex-lg-self-start {} -``` - -### Example usage - -Mixing flex properties: - -```html live -
-
.flex-self-stretch
-
 
-
 
-
-``` - -## Example components - -The flex utilities can be used to create a number of components. Here are some examples. - -### Media object - -You can use flex utilities to make a simple media object, like this: - -```html live -
-
image
-

Body Bacon ipsum dolor sit amet chuck prosciutto landjaeger ham hock filet mignon shoulder hamburger pig venison.

-
-``` - -### Responsive media object - -Here is an example of a media object that is **vertically centered on large screens**, but converts to a stacked column layout on small screens. - -```html live -
-
- -
-
-

Body Bacon ipsum dolor sit amet chuck prosciutto landjaeger ham hock filet mignon shoulder hamburger pig venison.

-
-
- - -
-
-``` - -## Flexbox bugs - -This section lists flexbox bugs that affect [browsers we currently support](https://github.com/primer/css/blob/main/.browserslistrc). - -1. **Minimum content sizing of flex items not honored.** Some browsers don't respect flex item size. Instead of respecting the minimum content size, items shrink below their minimum size which can create some undesirable results, such as overflowing text. The workaround is to apply `flex-shrink: 0;` to the items using `d-flex`. This can be applied with the `flex-shrink-0` utility. For more information read [philipwalton/flexbugs](https://github.com/philipwalton/flexbugs#1-minimum-content-sizing-of-flex-items-not-honored). - -9. **Some elements can't be flex containers.** Specifically, ` -
- Mashed potatoes - Fries -
-
-``` - -### Fixed - -Use `.position-fixed` to position an element relative to the viewport. **Be careful when using fixed positioning. It is tricky to use and can lead to unwanted side effects.** - -_Note: This example is shown in an `