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

Docs updates (#1895)

Browse Source 
* Remove "Atom packages"

* Remove Docset

* Remove "Local development"

* Remove "Table object"

* Move Grid to utilities

* Remove "Objects"

* Rename nav (marketing)

* Move marketing styles to their own section

* Discourage floats

* Update padding description
This commit is contained in:
simurai 2022-01-24 11:53:57 +09:00 committed by GitHub
parent 55bd498b73
commit d6160ea630
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
24 changed files with 79 additions and 321 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/content/components/box.md
View File

@ -554,7 +554,7 @@ You can put forms in boxes. Often form submission buttons are aligned to the bot
</div> </div>
``` ```
When a box is all by itself centered on a page you can use [column widths](/objects/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. 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 ```html live
<div class="Box Box--spacious col-6 mx-auto text-center"> <div class="Box Box--spacious col-6 mx-auto text-center">

2
docs/content/components/navigation.md
View File

@ -205,7 +205,7 @@ Use `.UnderlineNav--full` in combination with container styles and `.UnderlineNa
## Side Nav ## Side Nav
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](../objects/grid) classes or an inline `width` style for sizing, and [flexbox utilities](../utilities/flexbox) for positioning alongside content. 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. - 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"`. - Add `aria-current="page"` to show a link as selected. Selected button elements in tab-like UIs should instead have `aria-selected="true"`.

13
docs/content/getting-started/contributing.md
View File

@ -9,13 +9,13 @@ While this contributing guide is for GitHub employees, all contributions from th
### Components ### 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 and layout objects. [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: 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? - How often is this pattern used across the site?
- Could these styles be achieved with existing components, objects, and utilities? - 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 objects 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? - 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? - 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? - Is the desire for this new pattern a side-effect of lacking documentation or misunderstanding of use with current styles?
@ -23,12 +23,11 @@ Decisions to add new components are made on a case-by-case basis, with help from
- Is this something that would be better handled by other front-end code rather than CSS? - 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? - 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?
### Objects and utilities ### Utilities
Many of the same questions can be applied to objects and utilities, however the purpose of these styles is different: Many of the same questions can be applied to utilities, however the purpose of these styles is different:
- [Objects](/objects) aren't concerned with thematic styles. They are for common display and positioning styles we find in page layouts and common content types. [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:
- [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. - 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. - 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). - 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).

4
docs/content/index.mdx
View File

@ -6,7 +6,6 @@ import {HeroLayout} from '@primer/gatsby-theme-doctocat'
import {Grid, Box, Heading, Text, ButtonOutline, BorderBox} from '@primer/components' import {Grid, Box, Heading, Text, ButtonOutline, BorderBox} from '@primer/components'
import {Link} from 'gatsby' import {Link} from 'gatsby'
import utilitiesImage from '../src/utilities-image.svg' import utilitiesImage from '../src/utilities-image.svg'
import objectsImage from '../src/objects-image.svg'
import componentsImage from '../src/components-image.svg' import componentsImage from '../src/components-image.svg'
import typographyImage from '../src/typography-image.png' import typographyImage from '../src/typography-image.png'
import colorImage from '../src/color-image.svg' import colorImage from '../src/color-image.svg'
@ -22,14 +21,13 @@ Our goal is to create a system that enables us to build consistent user experien
Styles can be mixed and matched to achieve many different layouts, independent of their location. These styles fall into three categories: Styles can be mixed and matched to achieve many different layouts, independent of their location. These styles fall into three categories:
<Grid gridTemplateColumns={['1fr', '1fr', 'repeat(3, 1fr)']} gridGap={5} my={5}> <Grid gridTemplateColumns={['1fr', '1fr', 'repeat(2, 1fr)']} gridGap={5} my={5}>
{[ {[
{ {
name: 'Utilities', name: 'Utilities',
description: 'Single purpose, immutable styles, that do one thing well.', description: 'Single purpose, immutable styles, that do one thing well.',
image: utilitiesImage image: utilitiesImage
}, },
{name: 'Objects', description: 'Scaffolding for common page and content layouts.', image: objectsImage},
{name: 'Components', description: 'Abstracted patterns for frequently used visual styles.', image: componentsImage} {name: 'Components', description: 'Abstracted patterns for frequently used visual styles.', image: componentsImage}
].map(({name, description, image}) => ( ].map(({name, description, image}) => (
<Box> <Box>

6
docs/content/marketing/index.md Normal file
View File

@ -0,0 +1,6 @@
---
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.

6
docs/content/objects/index.md
View File

@ -1,6 +0,0 @@
---
title: Objects
path: objects/index
---
Objects help us with common layout patterns but aren't concerned with thematic styles. Examples include the table object, the grid, and the media object. Objects essentially provide some scaffolding for layouts and should be able to be used with other objects, components, and utilities.

27
docs/content/objects/table-object.md
View File

@ -1,27 +0,0 @@
---
title: Table object
path: objects/table-object
status: Deprecated
source: 'https://github.com/primer/css/tree/main/src/table-object'
bundle: table-object
---
The table object is a module for creating dynamically resizable elements that always sit on the same horizontal line (e.g., they never break to a new line). Using table styles in our CSS means it's cross browser friendly back to at least IE9.
Additional `margin` or `padding` may be required to properly space content.
```html live title="Table object"
<div class="TableObject">
<div class="TableObject-item TableObject-item--primary">
<input
class="input-block form-control"
type="text"
placeholder="Long elastic input form"
aria-label="Long elastic input form"
/>
</div>
<div class="TableObject-item">
<button class="btn ml-2" type="button">Button</button>
</div>
</div>
```

23
docs/content/principles/index.md
View File

@ -14,7 +14,7 @@ Every time new CSS is added it increases our CSS bloat, CSS maintenance, and can
_If new styles are needed:_ _If new styles are needed:_
* Use global variables where appropriate, such as spacing, typography, and color variables. * Use global variables where appropriate, such as spacing, typography, and color variables.
* Write styles in a way that can be folded back into the global style guide should it become a common pattern, i.e. following our principles for naming conventions, components, objects, and utilities as listed below. * Write styles in a way that can be folded back into the global style guide should it become a common pattern, i.e. following our principles for naming conventions, components, and utilities as listed below.
## Obvious and transparent ## Obvious and transparent
@ -74,26 +74,9 @@ Components make it easier to mark up a set of elements that are commonly grouped
.flash-error {...} .flash-error {...}
``` ```
## Objects
Objects help us with common layout patterns but aren't concerned with thematic styles. Examples include the table object, the grid, and the media object. Objects essentially provide some scaffolding for layouts and should be able to be used with other objects, components, and utilities.
Example:
```html
<div class="TableObject">
<div class="TableObject-item TableObject-item--primary">
<input class="input-block" type="text" placeholder="Long flexible input form">
</div>
<div class="TableObject-item">
<button class="btn ml-3" type="button">Button</button>
</div>
</div>
```
## BEM-style naming and structure ## BEM-style naming and structure
Components and objects should follow the [Block Element Modifier](http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/) (BEM) model in terms of structure. We've chosen to use a modified form of BEM syntax using [uppercase](https://en.wikipedia.org/wiki/Uppercase) for the block name, hyphens and lowercase for elements, and double-hyphens and lowercase for modifiers. When a block class requires two words use [Pascal case](https://en.wikipedia.org/wiki/PascalCase), for example `ProgressBar`. When an element or modifier class requires two words use [camel case](https://en.wikipedia.org/wiki/camelCase), for example `[Component]-closeButton` or `[Component]--extraLarge`. Components should follow the [Block Element Modifier](http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/) (BEM) model in terms of structure. We've chosen to use a modified form of BEM syntax using [uppercase](https://en.wikipedia.org/wiki/Uppercase) for the block name, hyphens and lowercase for elements, and double-hyphens and lowercase for modifiers. When a block class requires two words use [Pascal case](https://en.wikipedia.org/wiki/PascalCase), for example `ProgressBar`. When an element or modifier class requires two words use [camel case](https://en.wikipedia.org/wiki/camelCase), for example `[Component]-closeButton` or `[Component]--extraLarge`.
* **Block**: A block includes all of the base styles you want shared across every variation of a component. Minimal thematic styling should be applied to blocks, particularly when variations of a component include visual variations. Apply additional styles with modifers rather than overriding base styles. * **Block**: A block includes all of the base styles you want shared across every variation of a component. Minimal thematic styling should be applied to blocks, particularly when variations of a component include visual variations. Apply additional styles with modifers rather than overriding base styles.
* **Element**: An element is part of a component. Elements should work together with other elements and can have modifiers. Element styles should not override block styles - this often results in applying more styles directly to elements rather than having styles flow down from the parent level. * **Element**: An element is part of a component. Elements should work together with other elements and can have modifiers. Element styles should not override block styles - this often results in applying more styles directly to elements rather than having styles flow down from the parent level.
@ -116,7 +99,7 @@ Components and objects should follow the [Block Element Modifier](http://csswiza
``` ```
## Property order ## Property order
For base styles, components, and objects, follow the following property order. For base styles and components follow the following property order.
```scss ```scss
.element { .element {

2
docs/content/support/breakpoints.md
View File

@ -17,7 +17,7 @@ We use abbreviations for each breakpoint to keep the class names concise. This a
| Large | lg | `1012px` | | Large | lg | `1012px` |
| Extra-large | xl | `1280px` | | Extra-large | xl | `1280px` |
Responsive styles are available for [margin](/utilities/margin#responsive-margins), [padding](/utilities/padding#responsive-padding), [layout](/utilities/layout), [flexbox](/utilities/flexbox#responsive-flex-utilities), the [grid](/objects/grid#responsive-grids) system, and many more. Responsive styles are available for [margin](/utilities/margin#responsive-margins), [padding](/utilities/padding#responsive-padding), [layout](/utilities/layout), [flexbox](/utilities/flexbox#responsive-flex-utilities), the [grid](/utilities/grid#responsive-grids) system, and many more.
## Breakpoint and up... 🛫 ## Breakpoint and up... 🛫

52
docs/content/tools/atom-packages.md
View File

@ -1,52 +0,0 @@
---
title: Atom packages
path: tools/atom-packages
---
[Atom editor](https://atom.io/) is a _"A hackable text editor for the 21st Century"_ built by GitHub. If you use it as your editor of choice, the design systems team has a list of packages that we find useful for CSS development.
We keep a list of suggested packages in our [atom-packages repository](https://github.com/primer/atom-packages). To install all packages, run this command in your terminal.
```sh
apm install $(curl -L https://raw.githubusercontent.com/primer/atom-packages/master/packages)
```
## Autocomplete Primer
The [Autocomplete Primer package](https://atom.io/packages/autocomplete-primer) is a custom [Primer](https://github.com/primer) package that autocompletes class names for [utilities](/utilities) and Rails helper tags for [Octicons](https://github.com/primer/octicons/tree/master/lib/octicons_helper#readme).
Install [autocomplete-primer](https://atom.io/packages/autocomplete-primer) using Atom's package manager or enter this into your terminal:
```sh
apm install autocomplete-primer
```
## Color picker
[Color picker](https://atom.io/packages/color-picker) adds a color picking overlay with sliders and color wheels.
Install [color-picker](https://atom.io/packages/color-picker) using Atom's package manager or enter this into your terminal:
```sh
apm install color-picker
```
## Pigments
[Pigments](https://atom.io/packages/pigments) adds corresponding backgrounds to CSS color values in the editor for higher visibility. It also scans the source files for color variables and displays the true value.
Install [pigments](https://atom.io/packages/pigments) using Atom's package manager or enter this into your terminal:
```sh
apm install pigments
```
## Stylelint linter
We use [Stylelint](https://stylelint.io/), an extension to the [Atom linter package](https://atom.io/packages/linter), for [linting our SCSS](/tools/linting). To prevent linting errors during the build we recommend you install [linter-stylelint](https://atom.io/packages/linter-stylelint), which will alert you of any errors locally while you work.
Install [linter-stylelint](https://atom.io/packages/linter-stylelint) using Atom's package manager or enter this into your terminal:
```sh
apm install linter linter-stylelint
```

18
docs/content/tools/docset.md
View File

@ -1,18 +0,0 @@
---
title: Docset
path: tools/docset
---
We use and ❤️ [Kapeli's Dash app][dash] for browsing API documentation. Dash comes with 150+ offline documentation sets, but doesn't have our style guide.
So we've generated a [GitHub Style Guide docset][dash-feed] that gives you access to this site offline.
## Installation
1. First you'll need to make sure you have [Dash app][dash] installed.
2. Once installed, open the app, and click this [install docset link][dash-feed].
3. After the docset has been added to your list, click "download".
![](https://user-images.githubusercontent.com/54012/32087284-a87ed8f4-ba8f-11e7-9d84-c61913336491.png)
[dash]: https://kapeli.com/dash
[dash-feed]: dash-feed://https%3A%2F%2Fstyleguide.github.com%2Ffeeds%2FGitHub%20Style%20Guide.xml

8
docs/content/tools/linting.md
View File

@ -72,13 +72,7 @@ While linters shouldn't be disabled without consideration, essentially they act
### Plugins ### Plugins
Our linter runs on every commit, but finding you have a lint error after a push can be frustrating and waste time. To avoid this, a [collection of editor plugins](http://stylelint.io/user-guide/complementary-tools/) are available to help you lint while you code.. Our linter runs on every commit, but finding you have a lint error after a push can be frustrating and waste time. To avoid this, a [collection of editor plugins](https://stylelint.io/user-guide/integrations/editor) are available to help you lint while you code.
The Design Systems team recommends using [Atom](https://atom.io/) with the [linter-stylelint](https://github.com/AtomLinter/linter-stylelint) package installed.
![image](https://cloud.githubusercontent.com/assets/54012/21456489/6a10b370-c8f6-11e6-9199-bb3709e79794.png)
We also have a [list of Atom packages](/tools/atom-packages) that we find useful for development.
## HTML ## HTML

96
docs/content/tools/local-primer.md
View File

@ -1,96 +0,0 @@
---
title: Local development
internal: true
path: tools/local-primer
---
When you are working with the `github/github` codebase, you can link Primer CSS modules with your local development environment using the Primerize script. This will allow you to make changes to Primer CSS and see them reflected on `github.localhost` without the overhead of pulling in alpha releases of a package.
## Prerequisites
1. Working with `github/github` on the latest codebase.
2. Cloned down latest version of [primer/primer](https://github.com/primer/primer).
3. The `github/github` folder and the `primer/primer` folder must share the same parent folder.
**Example:**
```
~/codefolder/
├── github
└── primer
```
## Linking to your local Primer CSS repository
In your terminal start the server with the environment variable `LOCAL_PRIMER=1`. For example.
```
> LOCAL_PRIMER=1 script/server
```
When the variable is present, the script will check for linked local Primer CSS packages. If it's not linked, then it will proceed to link the Primer CSS packages in `../primer` to your GitHub application. When the server starts with successfully linked packages, you will see a clear message.
**Example output:**
```
❯ LOCAL_PRIMER=1 script/server
--------------------------------------------------------------------------------
Development Primer is linked to the local Primer repository found here
/Users/usera/github/primer
--------------------------------------------------------------------------------
14:09:14 web.1 | started with pid 36981
14:09:14 assets.1 | started with pid 36982
14:09:14 longpoll.1 | started with pid 36984
14:09:14 git-daemon.1 | started with pid 36986
14:09:14 gitauth.1 | started with pid 36988
14:09:14 codeload.1 | started with pid 36991
14:09:14 babeld.1 | started with pid 36996
```
## Resetting github/github development assets
To turn off Primerize, rerun `script/server` without the `LOCAL_PRIMER` flag. The script checks if you are still linked and restores everything to normal.
**Example output:**
```
❯ script/server
--------------------------------------------------------------------------------
Development Primer is linked to the local Primer repository found here
/Users/usera/github/primer
--------------------------------------------------------------------------------
Turning off linked primer
extracting primer-alerts@1.5.5.tgz
extracting primer-avatars@1.5.2.tgz
extracting primer-base@1.7.0.tgz
extracting primer-blankslate@1.4.5.tgz
extracting primer-box@2.5.5.tgz
extracting primer-branch-name@1.0.3.tgz
extracting primer-breadcrumb@1.5.1.tgz
extracting primer-buttons@2.5.3.tgz
extracting primer-core@6.8.0.tgz
extracting primer-forms@2.1.0.tgz
extracting primer-labels@1.5.5.tgz
extracting primer-layout@1.4.5.tgz
extracting primer-markdown@3.7.5.tgz
extracting primer-marketing-buttons@1.0.4.tgz
extracting primer-marketing-support@1.5.0.tgz
extracting primer-marketing-type@1.4.5.tgz
extracting primer-marketing-utilities@1.6.1.tgz
extracting primer-marketing@6.2.0.tgz
extracting primer-navigation@1.5.3.tgz
extracting primer-page-headers@1.4.5.tgz
extracting primer-page-sections@1.4.5.tgz
extracting primer-popover@0.0.6.tgz
extracting primer-product@5.6.2.tgz
extracting primer-subhead@1.0.3.tgz
extracting primer-support@4.5.2.tgz
extracting primer-table-object@1.4.5.tgz
extracting primer-tables@1.4.5.tgz
extracting primer-tooltips@1.5.3.tgz
extracting primer-truncate@1.4.5.tgz
extracting primer-utilities@4.8.5.tgz
extracting primer@10.4.0.tgz
regenerating node binstubs
14:13:17 web.1 | started with pid 38585
14:13:17 assets.1 | started with pid 38586
```

2
docs/content/utilities/flexbox.md
View File

@ -707,7 +707,7 @@ Resize window to see the effect.
## Responsive flex utilities ## Responsive flex utilities
All flexbox utilities can be adjusted per [breakpoint](/objects/grid#breakpoints) using the following formulas: All flexbox utilities can be adjusted per [breakpoint](/utilities/grid#breakpoints) using the following formulas:
- `d-[breakpoint]-[property]` for `display` - `d-[breakpoint]-[property]` for `display`
- `flex-[breakpoint]-[property]-[behavior]` for various flex properties - `flex-[breakpoint]-[property]-[behavior]` for various flex properties

42
docs/content/objects/grid.md → docs/content/utilities/grid.md
View File

@ -1,6 +1,6 @@
--- ---
title: Grid title: Grid
path: objects/grid path: utilities/grid
status: Stable status: Stable
status_issue: 'https://github.com/github/design-systems/issues/88' status_issue: 'https://github.com/github/design-systems/issues/88'
source: 'https://github.com/primer/css/tree/main/src/layout/grid.scss' source: 'https://github.com/primer/css/tree/main/src/layout/grid.scss'
@ -9,6 +9,25 @@ bundle: layout
The grid is 12 columns and percentage-based. The number of columns a container spans can be adjusted across breakpoints for responsive layouts. The grid system works with a variety of layout utilities to achieve different results. The grid is 12 columns and percentage-based. The number of columns a container spans can be adjusted across breakpoints for responsive layouts. The grid system works with a variety of layout utilities to achieve different results.
## Flexbox grids
You can use [flex utilities](/utilities/flexbox) on the container and columns to create a flexbox grid.
This can be useful for keeping columns the same height, justifying content and vertically aligning items. The flexbox grid is also great for working with responsive layouts.
```html live title="Flexbox grid"
<div class="d-flex flex-column flex-md-row flex-items-center flex-md-items-center">
<div class="col-2 d-flex flex-items-center flex-items-center flex-md-items-start">
<img class="width-full avatar mb-2 mb-md-0" src="https://github.com/github.png" alt="github" />
</div>
<div class="col-12 col-md-10 d-flex flex-column flex-justify-center flex-items-center flex-md-items-start pl-md-4">
<h1 class="text-normal lh-condensed">GitHub</h1>
<p class="h4 color-fg-muted text-normal mb-2">How people build software.</p>
<a class="color-fg-muted text-small" href="#url">https://github.com/about</a>
</div>
</div>
```
## Float based grid ## Float based grid
Use `.clearfix` on the container and float utilities with columns for a floated grid layout. Use `.clearfix` on the container and float utilities with columns for a floated grid layout.
@ -27,7 +46,7 @@ Use `.clearfix` on the container and float utilities with columns for a floated
</div> </div>
``` ```
### Reversed grid ### Reversed float grid
To reverse the order of columns, use `float-right` to float columns to the right. To reverse the order of columns, use `float-right` to float columns to the right.
@ -284,25 +303,6 @@ Note that table cells will fill the width of their container even when the total
</div> </div>
``` ```
## Flexbox grids
You can use [flex utilities](/utilities/flexbox) on the container and columns to create a flexbox grid.
This can be useful for keeping columns the same height, justifying content and vertically aligning items. The flexbox grid is also great for working with responsive layouts.
```html live title="Flexbox grid"
<div class="d-flex flex-column flex-md-row flex-items-center flex-md-items-center">
<div class="col-2 d-flex flex-items-center flex-items-center flex-md-items-start">
<img class="width-full avatar mb-2 mb-md-0" src="https://github.com/github.png" alt="github" />
</div>
<div class="col-12 col-md-10 d-flex flex-column flex-justify-center flex-items-center flex-md-items-start pl-md-4">
<h1 class="text-normal lh-condensed">GitHub</h1>
<p class="h4 color-fg-muted text-normal mb-2">How people build software.</p>
<a class="color-fg-muted text-small" href="#url">https://github.com/about</a>
</div>
</div>
```
## Responsive grids ## Responsive grids
All the column width classes can be set per breakpoint to create responsive grid layouts. Each responsive style is applied to the specified breakpoint and up. All the column width classes can be set per breakpoint to create responsive grid layouts. Each responsive style is applied to the specified breakpoint and up.

12
docs/content/utilities/layout.md
View File

@ -54,7 +54,7 @@ element.classList.toggle('d-inline', visible)
### `display:table` wrapping issues ### `display:table` wrapping issues
There are known issues with using `display:table` and wrapping long strings, particularly in Firefox. You may need to use `table-fixed` on elements with `d-table` and apply column widths to table cells, which you can do with our [column width styles](/objects/grid#column-widths). There are known issues with using `display:table` and wrapping long strings, particularly in Firefox. You may need to use `table-fixed` on elements with `d-table` and apply column widths to table cells, which you can do with our [column width styles](/utilities/grid#column-widths).
```html live ```html live
<div class="d-table table-fixed width-full"> <div class="d-table table-fixed width-full">
@ -68,7 +68,7 @@ There are known issues with using `display:table` and wrapping long strings, par
``` ```
### Responsive display ### Responsive display
A selection of display utilities are able to be applied or changed per [breakpoint](/objects/grid#breakpoints). `.d-block`, `.d-none`, `.d-inline`, and `.d-inline-block` are available as responsive utilities using the following formula: `d-[breakpoint]-[property]`. For example: `d-md-inline-block`. Each responsive display utility is applied to the specified breakpoint and up. A selection of display utilities are able to be applied or changed per [breakpoint](/utilities/grid#breakpoints). `.d-block`, `.d-none`, `.d-inline`, and `.d-inline-block` are available as responsive utilities using the following formula: `d-[breakpoint]-[property]`. For example: `d-md-inline-block`. Each responsive display utility is applied to the specified breakpoint and up.
In the following example, the `ul` element switches from `display: block` on mobile to `display: inline-block` at the `md` breakpoint, while the list items remain inline. In the following example, the `ul` element switches from `display: block` on mobile to `display: inline-block` at the `md` breakpoint, while the list items remain inline.
@ -118,10 +118,12 @@ Overflow utilities can also target x- and y-axes independently via:
* `.overflow-y-scroll` * `.overflow-y-scroll`
* `.overflow-y-visible` * `.overflow-y-visible`
Overflow utilities can be applied or changed per [breakpoint](/objects/grid#breakpoints). Each **responsive** overflow utility is applied to the specified breakpoint and up, using the following formula: `overflow-[breakpoint]-[axis]-[property]`. For example: `overflow-x-scroll` or `overflow-md-x-visible`. Overflow utilities can be applied or changed per [breakpoint](/utilities/grid#breakpoints). Each **responsive** overflow utility is applied to the specified breakpoint and up, using the following formula: `overflow-[breakpoint]-[axis]-[property]`. For example: `overflow-x-scroll` or `overflow-md-x-visible`.
## Floats ## Floats
Use `.float-left` and `.float-right` to set floats, and `.clearfix` to clear.
Using floats are discouraged since [flexbox](/utilities/flexbox) offers more features and doesn't need to be cleared. If you still need it, you can use `.float-left` and `.float-right` to set floats, and `.clearfix` to clear.
```html live ```html live
<div class="clearfix border"> <div class="clearfix border">
<div class="float-left border"> <div class="float-left border">
@ -133,7 +135,7 @@ Use `.float-left` and `.float-right` to set floats, and `.clearfix` to clear.
</div> </div>
``` ```
### Responsive floats ### Responsive floats
Float utilities can be applied or changed per [breakpoint](/objects/grid#breakpoints). This can be useful for responsive layouts when you want an element to be full width on mobile but floated at a larger breakpoint. Float utilities can be applied or changed per [breakpoint](/utilities/grid#breakpoints). This can be useful for responsive layouts when you want an element to be full width on mobile but floated at a larger breakpoint.
Each responsive float utility is applied to the specified breakpoint and up, using the following formula: `float-[breakpoint]-[property]`. For example: `float-md-left`. Remember to use `.clearfix` to clear. Each responsive float utility is applied to the specified breakpoint and up, using the following formula: `float-[breakpoint]-[property]`. For example: `float-md-left`. Remember to use `.clearfix` to clear.

2
docs/content/utilities/margin.md
View File

@ -116,7 +116,7 @@ Reset margins built into typography elements or other components with `m-0`, `mt
## Responsive margins ## Responsive margins
All margin utilities can be adjusted per [breakpoint](/objects/grid#breakpoints) using the following formula: `m[direction]-[breakpoint]-[spacer]`. Each responsive style is applied to the specified breakpoint and up. All margin utilities can be adjusted per [breakpoint](/utilities/grid#breakpoints) using the following formula: `m[direction]-[breakpoint]-[spacer]`. Each responsive style is applied to the specified breakpoint and up.
```html live ```html live
<div class="color-bg-attention d-inline-block"> <div class="color-bg-attention d-inline-block">

4
docs/content/utilities/padding.md
View File

@ -37,7 +37,7 @@ Since padding utilities have many variations and will be used in many places, we
| 11 | 112px | | 11 | 112px |
| 12 | 128px | | 12 | 128px |
_**Note:** The blue in the examples below represents the element, and the green represents the padding._ _**Note:** The gray in the examples below represents the element, and the yellow represents the padding._
## Uniform padding ## Uniform padding
@ -92,7 +92,7 @@ All padding utilities can be adjusted per [breakpoint](/support/breakpoints) usi
## Responsive container padding ## Responsive container padding
`.p-responsive` is a padding class that adds padding on the left and right sides of an element. It is intended to be used with [container styles](/objects/grid#containers). `.p-responsive` is a padding class that adds padding on the left and right sides of an element. It is intended to be used with [container styles](/utilities/grid#containers).
- On **0 to sm** screens, it gives the element padding of `$spacer-3` - On **0 to sm** screens, it gives the element padding of `$spacer-3`
- On **sm to lg** screens it gives the element padding of `$spacer-6` - On **sm to lg** screens it gives the element padding of `$spacer-6`

38
docs/src/@primer/gatsby-theme-doctocat/nav.yml
View File

@ -31,27 +31,16 @@
url: /utilities/details url: /utilities/details
- title: Flexbox - title: Flexbox
url: /utilities/flexbox url: /utilities/flexbox
- title: Grid
url: /utilities/grid
- title: Layout - title: Layout
url: /utilities/layout url: /utilities/layout
- title: Marketing layout
url: /utilities/marketing-layout
- title: Margin - title: Margin
url: /utilities/margin url: /utilities/margin
- title: Marketing filters
url: /utilities/marketing-filters
- title: Padding - title: Padding
url: /utilities/padding url: /utilities/padding
- title: Typography - title: Typography
url: /utilities/typography url: /utilities/typography
- title: Marketing typography
url: /utilities/marketing-type
- title: Objects
url: /objects
children:
- title: Grid
url: /objects/grid
- title: Table object
url: /objects/table-object
- title: Components - title: Components
url: /components url: /components
children: children:
@ -91,10 +80,6 @@
url: /components/loaders url: /components/loaders
- title: Markdown - title: Markdown
url: /components/markdown url: /components/markdown
- title: Marketing buttons
url: /components/marketing-buttons
- title: Marketing links
url: /components/marketing-links
- title: Navigation - title: Navigation
url: /components/navigation url: /components/navigation
- title: Pagination - title: Pagination
@ -115,19 +100,26 @@
url: /components/tooltips url: /components/tooltips
- title: Truncate - title: Truncate
url: /components/truncate url: /components/truncate
- title: Marketing
url: /marketing
children:
- title: Buttons
url: /components/marketing-buttons
- title: Filters
url: /utilities/marketing-filters
- title: Layout
url: /utilities/marketing-layout
- title: Links
url: /components/marketing-links
- title: Typography
url: /utilities/marketing-type
- title: Tools - title: Tools
url: /tools url: /tools
children: children:
- title: Atom packages
url: /tools/atom-packages
- title: Deprecation data - title: Deprecation data
url: /tools/deprecations url: /tools/deprecations
- title: Docset
url: /tools/docset
- title: Linting - title: Linting
url: /tools/linting url: /tools/linting
- title: Local development
url: /tools/local-primer
- title: Prototyping - title: Prototyping
url: /tools/prototyping url: /tools/prototyping
- title: Testing resources - title: Testing resources

2
docs/src/stories/components/Layout/LayoutBeta.stories.jsx
View File

@ -22,7 +22,7 @@ export default {
labels: ['fluid', 'md', 'lg', 'xl'] labels: ['fluid', 'md', 'lg', 'xl']
}, },
description: description:
'Define the maximum width of the component. `fluid` sets it to full-width. Other values center `Layout` horizontally. Refer to [container utilities](https://primer.style/css/objects/grid#containers) for reference.', 'Define the maximum width of the component. `fluid` sets it to full-width. Other values center `Layout` horizontally. Refer to [container utilities](https://primer.style/css/utilities/grid#containers) for reference.',
table: { table: {
category: 'Structure' category: 'Structure'
} }

2
docs/src/stories/components/Layout/PageLayout.stories.jsx
View File

@ -23,7 +23,7 @@ export default {
type: 'inline-radio', type: 'inline-radio',
labels: ['fluid', 'md', 'lg', 'xl'] labels: ['fluid', 'md', 'lg', 'xl']
}, },
description: 'Define the maximum width of the component. `fluid` sets it to full-width. Other values center `Layout` horizontally. Refer to [container utilities](https://primer.style/css/objects/grid#containers) for reference.', description: 'Define the maximum width of the component. `fluid` sets it to full-width. Other values center `Layout` horizontally. Refer to [container utilities](https://primer.style/css/utilities/grid#containers) for reference.',
table: { table: {
category: 'Structure' category: 'Structure'
} }

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

@ -1,25 +0,0 @@
---
bundle: "table-object"
generated: true
---
# Primer CSS: `table-object` bundle
## Usage
Primer CSS source files are written in [SCSS]. To include this Primer CSS module in your own build, ensure that your `node_modules` directory is listed in your Sass include paths, then import it with:
```scss
@import "@primer/css/table-object/index.scss";
```
## Build
The `@primer/css` npm package includes a standalone CSS build of this module in `dist/table-object.css`.
## License
[MIT](https://github.com/primer/css/blob/main/LICENSE) &copy; [GitHub](https://github.com/)
[scss]: https://sass-lang.com/documentation/syntax#scss

3
src/table-object/table-object.scss
View File

@ -1,3 +1,6 @@
// Deprecated
// TODO: Replace TableObject with flexbox or a new Table component
// TableObject is a module for creating dynamically resizable elements that // TableObject is a module for creating dynamically resizable elements that
// always sit on the same horizontal line (e.g., they never wrap). Using // always sit on the same horizontal line (e.g., they never wrap). Using
// tables means it's cross browser friendly. // tables means it's cross browser friendly.

7
vercel.json
View File

@ -18,7 +18,12 @@
{ {
"src": "/css/objects/layout/?", "src": "/css/objects/layout/?",
"status": 301, "status": 301,
"headers": {"Location": "/css/objects/grid"} "headers": {"Location": "/css/utilities/grid"}
},
{
"src": "/css/objects/grid/?",
"status": 301,
"headers": {"Location": "/css/utilities/grid"}
}, },
{ {
"src": "/css(/.*)?", "src": "/css(/.*)?",