diff --git a/.github/workflows/deploy_preview.yml b/.github/workflows/deploy_preview.yml index 1917b227..a35d7d3a 100644 --- a/.github/workflows/deploy_preview.yml +++ b/.github/workflows/deploy_preview.yml @@ -19,7 +19,7 @@ jobs: secrets: gh_token: ${{ secrets.GITHUB_TOKEN }} with: - node_version: 14 + node_version: 16 install: yarn && cd docs && yarn && cd .. build: yarn build:docs:preview output_dir: docs/public diff --git a/docs/.babelrc b/docs/.babelrc index 0f92253e..f8182480 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 9a7049fd..ee56e826 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 0479b1a2..f3d94c88 100644 --- a/docs/.storybook/main.js +++ b/docs/.storybook/main.js @@ -1,22 +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-links', + '@storybook/addon-essentials', + '@storybook/addon-interactions', + 'storybook-addon-pseudo-states', + '@storybook/addon-storysource', + '@geometricpanda/storybook-addon-badges', { - name: '@storybook/addon-essentials', + name: '@storybook/addon-styling', options: { - actions: false, - controls: false, - docs: true, - viewport: true, + sass: { + implementation: require('sass'), + }, }, }, - '@storybook/addon-a11y', - '@storybook/addon-links', - '@storybook/preset-scss', ], - framework: '@storybook/react', - core: { - builder: 'webpack5', + framework: { + name: '@storybook/react-webpack5', + options: {}, }, - staticDirs: ['../src/stories/static'], + 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 00000000..65340e9b --- /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 6f25036b..3ed18e99 100644 --- a/docs/.storybook/preview-head.html +++ b/docs/.storybook/preview-head.html @@ -1,32 +1 @@ - + diff --git a/docs/.storybook/preview.css b/docs/.storybook/preview.css new file mode 100644 index 00000000..de33cb81 --- /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 5dd6c5d2..3f2fcf74 100644 --- a/docs/.storybook/preview.js +++ b/docs/.storybook/preview.js @@ -1,138 +1,54 @@ import '../../src/docs.scss' import '../../src/index.scss' import '../../src/base/index.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 './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%', +/** @type { import('@storybook/react').Preview } */ +const preview = { + parameters: { + actions: {argTypesRegex: '^on[A-Z].*'}, + controls: { + matchers: { + color: /(background|color)$/i, + date: /Date$/, + }, }, - }, - medXS: { - name: 'XS (med)', - styles: { - width: '375px', - height: '100%', + options: { + storySort: { + order: ['Introduction', 'GettingStarting', 'Contributing', 'Utilities'], + }, }, - }, - 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%', + 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.', + }, + }, }, }, } -export const parameters = { - actions: {argTypesRegex: '^on[A-Z].*'}, - // docs: { - // transformSource: (src, storyContext) => renderToHTML(storyContext.storyFn), - // }, - controls: { - matchers: { - color: /(background|color)$/i, - date: /Date$/, - }, - 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 = { @@ -141,33 +57,58 @@ export const globalTypes = { description: 'Switch themes', defaultValue: 'light', toolbar: { - icon: 'circlehollow', - items: [...themes, 'all'], + 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 00000000..508e16a5 --- /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 00000000..cf427d19 --- /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 e2efe76b..00000000 --- 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 3ef1b54a..00000000 --- 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 a9ac9a0b..00000000 --- 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 298736fe..00000000 --- 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 516c435c..00000000 --- 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 57760f88..00000000 --- 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 8ab9eee4..00000000 --- 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 43884953..00000000 --- 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 1471ef9e..00000000 --- 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 b20b680d..00000000 --- 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 fae34157..00000000 --- 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 903cf8e0..00000000 --- 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 61e4e749..00000000 --- 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 fe845593..00000000 --- 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 a16a179f..00000000 --- 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 203ab6dd..00000000 --- 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 24645699..00000000 --- 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 4bd3643f..00000000 --- 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 d6eaa59d..00000000 --- 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 820558c1..00000000 --- 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 475347eb..00000000 --- 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 6e09b376..00000000 --- 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 3832f9f6..00000000 --- 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 e3cddb7b..00000000 --- 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 c919cd1c..00000000 --- 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/pagination.md b/docs/content/components/pagination.md deleted file mode 100644 index 6f552da5..00000000 --- a/docs/content/components/pagination.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Pagination -path: components/pagination -status: Beta -source: 'https://github.com/primer/css/tree/main/src/pagination' -bundle: pagination ---- - -Use the pagination component to apply button styles to a connected set of links that go to related pages (for example, previous, next, or page numbers). - -## Previous/next pagination - -You can make a very simple pagination container with just the Previous and Next buttons. Add the `aria-disabled="true"` attribute to the `Previous` button if there isn't a preceding page, or to the `Next` button if there isn't a succeeding page. - -```html live - -``` - -## Numbered pagination - -For pagination across multiple pages, make sure it's clear to the user where they are in a set of pages. - -To do this, add anchor links to the `pagination` element. Previous and Next buttons should always be present. Add the `aria-disabled="true"` attribute to the Previous button if you're on the first page. Apply the `aria-current="page"` attribute to the current numbered page. - -As always, make sure to include the appropriate `aria` attributes to make the element accessible. - -- Add `aria-label="Pagination"` to the `paginate-container` element. -- Add `aria-label="Page X"` to each anchor link. - -```html live - -``` diff --git a/docs/content/components/popover.md b/docs/content/components/popover.md deleted file mode 100644 index 95abd25a..00000000 --- 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 5df3f317..00000000 --- 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 b8d25652..00000000 --- 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 d6abf0bf..00000000 --- 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 fa26529c..00000000 --- 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 cfccf6bc..00000000 --- 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 86d5ad88..00000000 --- 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 baa20a00..00000000 --- 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 41b7d626..00000000 --- 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 41cd6798..00000000 --- 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 c93559df..00000000 --- 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 5fac24fe..00000000 --- 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 c3665463..00000000 --- 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 6d89cb0f..00000000 --- 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 158d8123..00000000 --- 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/getting-started/index.md b/docs/content/getting-started/index.md deleted file mode 100644 index 0e663cfb..00000000 --- a/docs/content/getting-started/index.md +++ /dev/null @@ -1,126 +0,0 @@ ---- -title: Getting started -path: getting-started/index ---- - -Primer CSS is [open-sourced on GitHub](https://github.com/primer/css) and [available on npm](https://www.npmjs.com/package/@primer/css). - -## Installing via npm - -We recommend installing Primer CSS with npm: `npm install --save @primer/css`. - -### Before you start - -Primer CSS requires npm version 3 or above. You can check which version you have by running `npm -v`. If you have a version that's older than 3.0, you can update it with `npm install npm@latest -g`. For more info, read the [npm install docs](https://docs.npmjs.com/getting-started/installing-node). - -### Initialize npm project - -Begin by initializing your project with a `package.json` file. You can read more on how to do this [in the npm documentation](https://docs.npmjs.com/getting-started/using-a-package.json#creating-a-packagejson). - -### Install Primer CSS - -Install the Primer CSS npm package modules by running `npm install @primer/css`. This will install all of the SCSS source files into the `node_modules/@primer/css` directory. - -```shell -npm install @primer/css --save -``` - -### Paths - -Here's what you need to know about how the files are structured in both git and in the published npm module: - -- In git, all of the SCSS source files live in the `src/` directory. -- When published, all of the files in `src/` are "hoisted" to the package root so that you can import, say, utilities with: - - ```scss - @import '@primer/css/utilities/index.scss'; - ``` - -- All bundle interdependencies within Primer CSS are defined as relative imports (e.g. with `../`), so everything should work fine as long as the `@primer/css` directory is in one of your Sass include paths (i.e. `node_modules`). - -### For a Jekyll site - -Make sure you have [Jekyll](https://jekyllrb.com/) version `3.3.1` or greater with: - -```shell -jekyll -v -``` - -If you have an older version, follow the instructions in the [upgrading docs](https://jekyllrb.com/docs/upgrading/). - -Once you have Jekyll up and running, you will need to add this configuration to your `_config.yml` file. This let's the sass compiler know where your code lives. - -```yml -sass: - # Where you keep your scss files - sass_dir: assets/css/ - # Where sass should look for other scss - load_paths: - - node_modules/ -``` - -It's best practice to import all of this scss into one file, usually named `index.scss`. From this file you'll import one or more Primer CSS bundles and any other custom code you write. - -```scss -@import '@primer/css/core/index.scss'; -// These files live in the same directory as the index file. -@import './custom-1.scss'; -@import './custom-2.scss'; -``` - -Here's an example of how it might look if you installed only a few Primer CSS components with some custom variable overrides. The `$blue` uses the default primer blue in the text utilities, then the new blue in `"custom-that-uses-primer-variables.scss"` and `.foo`. - -```scss -@import '@primer/css/utilities/index.scss'; -@import 'primer-buttons/index.scss'; - -// Import color variables for custom code -@import 'primer-support/index.scss'; - -// Override default blue -$blue: #0000ff; - -@import './custom-that-uses-primer-variables.scss'; - -.foo { - background: $blue; - font-size: $h2-size; - color: $text-gray; -} -``` - -Don't forget to add the compiled CSS to the `` section of your page. - -```html - -``` -### Troubleshooting Jekyll errors - -Currently [jekyll-sass-converter](https://github.com/jekyll/jekyll-sass-converter) uses the [deprecated `LibSass` library](https://github.com/jekyll/jekyll-sass-converter#sass-implementations). Due to this you might run into issues. One way to deal with this is to use an experimental version of `jekyll-sass-converter` which uses [dart sass](https://sass-lang.com/dart-sass). - -1. Add `jekyll-sass-converter` and `sass-embedded` to `Gemfile`: -```ruby -group :jekyll_plugins do - gem 'jekyll-sass-converter', github: 'jekyll/jekyll-sass-converter' - gem 'sass-embedded' -end -``` -2. Run `bundle install` -```bash -$ bundle install -``` -3. Update your `_config.yml`: -```yml -sass: - implementation: sass-embedded -``` - -Since GitHub pages is currently [locked to version `1.5.2` of `jekyll-sass-converter`](https://pages.github.com/versions/). If you run into errors you should look into [using the built CSS](#using-primer-css-on-a-static-site). - -## Using Primer CSS on a static site - -You won't need to install any node modules or Sass compilers for a static site; you can use the built CSS. The best thing to do is to [download the built CSS](https://unpkg.com/@primer/css/dist/primer.css) from [unpkg.com](https://unpkg.com) and host it yourself. If that's not an option, you can include a CDN link in your HTML: - -```html - -``` diff --git a/docs/content/index.mdx b/docs/content/index.mdx deleted file mode 100644 index 2960ebd4..00000000 --- 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 0d3b44dd..00000000 --- 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/principles/accessibility.md b/docs/content/principles/accessibility.md deleted file mode 100644 index 307a1088..00000000 --- a/docs/content/principles/accessibility.md +++ /dev/null @@ -1,191 +0,0 @@ ---- -title: Accessibility -path: principles/accessibility ---- - -Accessibility is everyone’s responsibility, and the purpose of this document is to provide general accessibility guidelines to developers and designers. - - - -## Overview - -Our products should be accessible to all. At minimum, features should comply to the requirements listed in [508 Reference Guide - 1194.22](https://www.access-board.gov/guidelines-and-standards/communications-and-it/about-the-section-508-standards/guide-to-the-section-508-standards/web-based-intranet-and-internet-information-and-applications-1194-22) from the US Access Board, and conform to [Web Content Accessibility Guidelines 2.0](https://www.w3.org/TR/WCAG20/#conformance) at Level AA. - -Making our products accessible benefits everyone, not just people with disabilities. Below are some examples of use cases in which accessibility is important: - -- **Visual**: blindness, low vision, color blindness, using a screen reader or related assistive tech for lifestyle reasons (e.g. long car commute), machine readability and screen scraping technologies - -- **Hearing**: deafness, hearing impairment, speech impairment, using closed captioning or other assistive features for lifestyle reasons (e.g. coworking in a loud coffee shop) - -- **Cognitive**: including short-term memory issues, dyslexia, learning disabilities, trying to work or consume content while distracted or multitasking, etc. - -- **Mobility**: mobility impairments, repetitive stress injuries, power users who love keyboard shortcuts, busy parents holding a sleeping child while trying to operate a computer with one hand, etc. - -## General guidelines - -### Semantic markup - -Always use semantic HTML elements, like `button`, `ul`, `nav`. Most modern browsers implement the accessibility features outlined in the specs for these elements; without them, elements will need additional [ARIA attributes and roles](https://www.w3.org/WAI/PF/aria) to be recognized by assistive technologies. - -Elements like `h1`-`h6`, `nav`, `footer`, `header` have [meaningful roles](https://www.w3.org/WAI/PF/aria/roles) assigned, so use them carefully. This can help assistive technologies read the page better and help users find information quicker. - -Only use a `div` or a `span` to markup up content when there isn't another HTML element that would semantically be more appropriate, or when an element is needed exclusively for applying CSS styles or JS behaviors. - -```html - - -``` - -```html - -Send -``` - -> More on semantic markup: -> -> - [Semantic Structure – WebAIM](http://webaim.org/techniques/semanticstructure/) - -### Keyboard accessibility - -Make sure elements can be reached via tabbing, and actions can be triggered with a keyboard. Using semantic markup is especially important in this case as it ensures that actionable elements are tabbable and triggerable without a mouse. Note that elements positioned off-screen are still tabbable, but those hidden with `display: none` or `visibility: hidden` are effectively removed from content since they are neither read by screen readers nor reachable by keyboard. - -Tab order is determined by the order of elements in the DOM, and not by their visual positioning on the page after CSS is applied. CSS properties `float` and `order` for flex items are two common sources for disconnection between visual and DOM order. - -The `tabindex` attribute should only be used when absolutely necessary. - -- `tabindex=0/-1` makes an element focusable, while `tabindex=0` also includes the element in the normal tab order. In both cases, keyboard triggers of the element still require scripting, so where possible, use [interactive content](http://w3c.github.io/html/dom.html#kinds-of-content-interactive-content) instead. - -- `tabindex=1+` takes an element to the very front of the default tab order. When it's applied, the element's visual positioning is no longer indicative of its tab order, and the only way to find out where an element is would be by tabbing through the page. Therefore, unless a page is carefully designed around elements with positive tabindex, it is very error-prone, and thus currently prohibited in github.com. - -Finally, bear in mind that some assistive technologies have keyboard combinations of their own that will override the combination on the web page, so don't rely on keyboard shortcuts as the only alternative to mouse actions. - -```html - - - - -``` - -```html - - - - -``` - -> More on keyboard accessibility: -> -> - [Focus Order – Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/navigation-mechanisms-focus-order.html) -> - [Time to revisit accesskey? by Léonie Watson](http://tink.uk/time-to-revisit-accesskey/) -> - [Flexbox & the keyboard navigation disconnect by Léonie Watson](http://tink.uk/flexbox-the-keyboard-navigation-disconnect/) - -### Visual accessibility - -Be mindful when using small font size, thin font weight, low contrast colors in designs as it can severely affect usability. - -Instead of relying solely on color to communicate information, always combine color with another factor, like shape or position change. This is important because some colors can be hard to tell apart due to color blindness or weak eyesight. - -> More on visual accessibility: -> -> - [Use of Color – Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-without-color.html) -> - [Contrast – Understanding WCAG 2.0](http://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html) - -### Text and labels - -Make sure text-based alternative is always available when using icons, images, and graphs, and that the text by itself presents meaningful information. - -```html - -

Find out more about GitHub Enterprise pricing.

-``` - -```html - -

To find out more about GitHub Enterprise pricing, click here.

-``` - -Use `aria-label` when there is no text. - -```html -<%= octicon("question", :"aria-label" => "Help") %> -``` - -### Link responsibly - -Navigating from a list of all the links on a given web page is very common for assistive technology users. We should make sure that the link text itself is meaningful and unique, and there should be as few duplicated references as possible. - -> More on link responsibly: -> -> - [Link Purpose – Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/navigation-mechanisms-refs.html) - -### Dynamic content - -When using JavaScript to change the content on the page, always make sure that screen reader users are informed about the change. This can be done with `aria-live`, or focus management. - -> More on dynamic content: -> -> - [ARIA Live Regions – MDN](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) - -### Focus management - -Focus management is useful for informing users about updated content, and for making sure users land on the next useful section after performing an action. This means using scripts to change user’s currently focused element, and when focus changes, screen readers will read out change. - -### Accessible forms - -It is common for assistive technology users to jump straight to a form when using a website, so make sure most relevant information is in the form and is labelled properly. Labels and inputs should be associated with the `label[for]` and `input[id]`, and help texts should either be part of the label or be associated with `aria-describedby`. - -```html - -
- -
Please enter an email ending with @github.com.
-``` - -```html - -
- -
Please enter an email ending with @github.com.
-``` - -## Development tools - -### Linting - -We currently run basic linting [against positive `tabindex`](https://github.com/github/github/blob/8546895623677abc70f61951642f32c16de231a1/test/fast/linting/accessible_tabindex_test.rb) and [anchor links with `href="#"`](https://github.com/github/github/blob/8546895623677abc70f61951642f32c16de231a1/test/rubocop/cop/rails/link_href.rb). - -We do client side scanning of inaccessible elements in development environment. The inaccessible elements will be styled with red borders with an onclick alert and console warnings. - -### External tools - -- Google Chrome provides an [Accessibility Developer Tools extension](https://chrome.google.com/webstore/detail/accessibility-developer-t/fpkknkljclfencbdbgkenhalefipecmb). Once installed, go to Audits tab in developer tools, tick Accessibility. It scans the page for violations and suggests solutions. - -- If you're working on a design that uses color to communicate something, grab the [Chromatic Vision Simulator app](https://itunes.apple.com/tw/app/chromatic-vision-simulator/id389310222?mt=8), this will let you use your iPhone camera to see what a colorblind person would see. - -- Check out [the Web Accessibility showcase on GitHub](https://github.com/showcases/web-accessibility). GitHubbers are free to add more projects to the showcase. - -## Manual testing - -### Screen reader - -To use VoiceOver, the built-in screen reader for Mac, just hit ⌘ + F5. This will start voice narration and display most of the spoken information in a text box. - -Use alt + control + left/right to navigate a web page. alt + control + space to click on an element. For more help with VoiceOver, check out the built-in tutorial in `System Preferences > Accessibility > VoiceOver > Open VoiceOver Training`. - -Keep in mind that behaviors in different screen readers can differ when navigating the same web page; just like designing for different browsers, when it comes to accessibility, it is not just the implementation of the browsers that can be different, but also the ones of assistive softwares. - -## Internal resources - -1. You can mention these teams when looking for help: - - - [@github/accessibility](https://github.com/orgs/github/teams/accessibility): GitHubbers interested in accessibility related topics and work on website accessibility issues. - - [@github/colorblind](https://github.com/orgs/github/teams/colorblind): GitHubbers who are interested in accessibility for colorblindness. - -2. Go to #accessibility Slack channel to ask questions or discuss accessibility issues. -3. Check [github/accessibility repository](https://github.com/github/accessibility) for information on events or learning resources. - -## User support - -Accessibility is a priority for us, if you ever encounter accessibility related issues when using github.com, please don’t hesitate to reach out to us via [the contact page](https://github.com/contact) or email us at [support@github.com](mailto:support@github.com), we will try our best to assist. - -For information about the accessibility compliance of GitHub products, please refer to our [VPAT report, outlining §508 accessibility information for GitHub.com, GitHub Enterprise, and GitHub Desktop](https://government.github.com/accessibility/). diff --git a/docs/content/principles/html.md b/docs/content/principles/html.md deleted file mode 100644 index eeda0519..00000000 --- a/docs/content/principles/html.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: HTML -path: principles/html ---- - - - -## General formatting - -* Use soft-tabs with a two space indent. Spaces are the only way to guarantee code renders the same in any person's environment. -* Paragraphs of text should always be placed in a `

` tag. Never use multiple `
` tags. -* Items in list form should always be in `

    `, `
      `, or `
      `. Never use a set of `
      ` or `

      `. -* Every form input that has text attached should utilize a `

      `, ``, and ``. -* Don't set `tabindex` manually—rely on the browser to set the order. - -```html inert=true -

      - This is my paragraph of special text. -

      -``` - -## Boolean attributes - -Many attributes don't require a value to be set, like `checked`, so don't set them. - -```html inert=true - - - -``` - -For more information, [read the WhatWG section](http://www.whatwg.org/specs/web-apps/current-work/multipage/common-microsyntaxes.html#boolean-attributes). - -## Lean markup - -Whenever possible, avoid superfluous parent elements when writing HTML. Many times this requires iteration and refactoring, but produces less HTML. For example: - -```html inert=true - - - - - - - -``` - -## Forms - -* Lean towards radio or checkbox lists instead of select menus. -* Wrap radio and checkbox inputs and their text in `