diff --git a/docs/content/utilities/gap.md b/docs/content/utilities/gap.md new file mode 100644 index 0000000000..9a7e926d00 --- /dev/null +++ b/docs/content/utilities/gap.md @@ -0,0 +1,78 @@ +--- +title: Gap +path: utilities/gap +status: Stable +source: 'https://github.com/primer/css/blob/main/src/utilities/gap.scss' +bundle: utilities +--- + +Gap utilities can be used on elements with a display type of `flex` or `grid` to create consistent spacing between child elements. This can replace the need for using margins in many cases. + +Gap utilities are based on a global [spacing scale](/support/spacing) which helps keep spacing consistent. These utilities help us reduce the amount of custom CSS that share the same properties, and allows to achieve many different page layouts using the same styles. + + +## Naming convention + +Since gap utilities have many variations and will be used in many places, we use a shorthand naming convention to help keep class names succinct. + +| Shorthand | Description | +| --- | --- | +| 0 | 0 | +| 1 | 4px | +| 2 | 8px | +| 3 | 16px | +| 4 | 24px | +| 5 | 32px | +| 6 | 40px | + + +## Gap utilities + +Use gap utilities on parent elements to apply equal spacing between all of their child elements. These utilities can be used with a spacing scale from 0-6. + +```html live +
+
.gap-0
+
.gap-0
+
.gap-0
+
+
+
.gap-1
+
.gap-1
+
.gap-1
+
+
+
.gap-2
+
.gap-2
+
.gap-2
+
+
+
.gap-3
+
.gap-3
+
.gap-3
+
+
+
.gap-4
+
.gap-4
+
.gap-4
+
+
+
.gap-5
+
.gap-5
+
.gap-5
+
+
+
.gap-6
+
.gap-6
+
.gap-6
+
+``` + + +## Reset gap +Reset gap values built into components with `gap-0`. + + +## Responsive gaps + +All gap utilities can be adjusted per [breakpoint](/utilities/grid#breakpoints) using the following formula: `gap-[breakpoint]-[spacer]`. Each responsive style is applied to the specified breakpoint and up. diff --git a/docs/src/@primer/gatsby-theme-doctocat/nav.yml b/docs/src/@primer/gatsby-theme-doctocat/nav.yml index fa72f456ed..0280924a42 100644 --- a/docs/src/@primer/gatsby-theme-doctocat/nav.yml +++ b/docs/src/@primer/gatsby-theme-doctocat/nav.yml @@ -39,6 +39,8 @@ url: /utilities/margin - title: Padding url: /utilities/padding + - title: Gap + url: /utilities/gap - title: Typography url: /utilities/typography - title: Components diff --git a/src/support/variables/layout.scss b/src/support/variables/layout.scss index 15abe59e82..0d4eb845d3 100644 --- a/src/support/variables/layout.scss +++ b/src/support/variables/layout.scss @@ -20,8 +20,8 @@ $edges: ( left: (bottom-left, top-left) ) !default; -// These are our margin and padding utility spacers. The default step size we -// use is 8px. This gives us a key of: +// These are our margin, padding, and gap utility spacers. The default step +// size we use is 8px. This gives us a key of: // 0 => 0px // 1 => 4px // 2 => 8px diff --git a/src/utilities/gap.scss b/src/utilities/gap.scss new file mode 100644 index 0000000000..baf8860d5b --- /dev/null +++ b/src/utilities/gap.scss @@ -0,0 +1,12 @@ +// Gap spacer utilities +// stylelint-disable block-opening-brace-space-before + +// Loop through the breakpoint values +@each $breakpoint, $variant in $responsive-variants { + @include breakpoint($breakpoint) { + // Loop through the spacer values + @each $scale, $size in $spacer-map { + .gap#{$variant}-#{$scale} { gap: $size !important; } + } + } +} diff --git a/src/utilities/index.scss b/src/utilities/index.scss index f03006c2bc..752f4a828b 100644 --- a/src/utilities/index.scss +++ b/src/utilities/index.scss @@ -6,6 +6,7 @@ @import './colors.scss'; @import './details.scss'; @import './flexbox.scss'; +@import './gap.scss'; @import './layout.scss'; @import './margin.scss'; @import './padding.scss';