diff --git a/.markdownlint.json b/.markdownlint.json index b5cd7e3d1d..6b09841cb0 100644 --- a/.markdownlint.json +++ b/.markdownlint.json @@ -1,6 +1,7 @@ { "default": true, "MD004": { "style": "dash" }, + "MD011": false, "MD013": false, "MD024": false, "MD025": false, @@ -14,4 +15,4 @@ "MD046": false, "line-length": false, "no-inline-html": false -} \ No newline at end of file +} diff --git a/site/data/sidebar.yml b/site/data/sidebar.yml index fcaffa4941..d8e732f5a4 100644 --- a/site/data/sidebar.yml +++ b/site/data/sidebar.yml @@ -117,27 +117,52 @@ icon_color: red pages: - title: API - - title: Aspect ratio - title: Background - title: Border - title: Border radius - title: Colors - - title: Display - - title: Flex - - title: Float - - title: Interactions - - title: Link - - title: Object fit - - title: Opacity - - title: Overflow - - title: Position - - title: Shadows - - title: Sizing - - title: Spacing - - title: Text - - title: Vertical align - - title: Visibility - - title: Z-index + - group: Layout + pages: + - title: Aspect ratio + - title: Display + - title: Float + - title: Object fit + - title: Overflow + - title: Position + - title: Visibility + - title: Z-index + - group: Flex & Grid + pages: + - title: Align content + - title: Align items + - title: Align self + - title: Flex + - title: Justify content + - title: Justify items + - title: Place items + - group: Sizing + pages: + - title: Width + - title: Height + - group: Spacing + pages: + - title: Margin + - title: Padding + - group: Type + pages: + - title: Font style + - title: Text alignment + - title: Text decoration + - title: Text wrapping + - title: Vertical align + - group: Interactions + pages: + - title: Pointer events + - title: User select + - group: Effects + pages: + - title: Opacity + - title: Shadows - title: Extend icon: tools diff --git a/site/src/components/DocsSidebar.astro b/site/src/components/DocsSidebar.astro index fb207fb2e9..ca28fb16f5 100644 --- a/site/src/components/DocsSidebar.astro +++ b/site/src/components/DocsSidebar.astro @@ -29,8 +29,50 @@ const sidebar = getData('sidebar') {group.title} -## Auto margins - -Flexbox can do some pretty awesome things when you mix flex alignments with auto margins. Shown below are three examples of controlling flex items via auto margins: default (no auto margin), pushing two items to the right (`.me-auto`), and pushing two items to the left (`.ms-auto`). - - -
Flex item
-
Flex item
-
Flex item
- - -
-
Flex item
-
Flex item
-
Flex item
-
- -
-
Flex item
-
Flex item
-
Flex item
-
`} /> - -### With align-items - -Vertically move one flex item to the top or bottom of a container by mixing `align-items`, `flex-direction: column`, and `margin-top: auto` or `margin-bottom: auto`. - - -
Flex item
-
Flex item
-
Flex item
- - -
-
Flex item
-
Flex item
-
Flex item
-
`} /> - ## Wrap Change how flex items wrap in a flex container. Choose from no wrapping at all (the browser default) with `.flex-nowrap`, wrapping with `.flex-wrap`, or reverse wrapping with `.flex-wrap-reverse`. @@ -424,335 +211,10 @@ Responsive variations also exist for `flex-wrap`. })} -## Order - -Change the _visual_ order of specific flex items with a handful of `order` utilities. We only provide options for making an item first or last, as well as a reset to use the DOM order. As `order` takes any integer value from 0 to 5, add custom CSS for any additional values needed. - - -
First flex item
-
Second flex item
-
Third flex item
- `} /> - -Responsive variations also exist for `order`. - -
    -{getData('breakpoints').map((breakpoint) => getSequence(0, 5).map((value) => { - return ( -
  • .order{breakpoint.abbr}-{value}
    • - ) -}))} -
- -Additionally there are also responsive `.order-first` and `.order-last` classes that change the `order` of an element by applying `order: -1` and `order: 6`, respectively. - -
    -{getData('breakpoints').map((breakpoint) => ['first', 'last'].map((value) => { - return ( -
  • .order{breakpoint.abbr}-{value}
    • - ) -}))} -
- -## Align content - -Use `align-content` utilities on flexbox containers to align flex items _together_ on the cross axis. Choose from `start` (browser default), `end`, `center`, `between`, `around`, or `stretch`. To demonstrate these utilities, we’ve enforced `flex-wrap: wrap` and increased the number of flex items. - -**Heads up!** This property has no effect on single rows of flex items. - -
-
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
-
- -```html -
- ... -
-``` - -
-
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
-
- -```html -
...
-``` - -
-
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
-
- -```html -
...
-``` - -
-
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
-
- -```html -
...
-``` - -
-
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
-
- -```html -
...
-``` - -
-
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
Flex item
-
-
- -```html -
...
-``` - -Responsive variations also exist for `align-content`. - -
    -{getData('breakpoints').map((breakpoint) => { - return ( - -
  • .align-content{breakpoint.abbr}-start
    • -
  • .align-content{breakpoint.abbr}-end
    • -
  • .align-content{breakpoint.abbr}-center
    • -
  • .align-content{breakpoint.abbr}-between
    • -
  • .align-content{breakpoint.abbr}-around
    • -
  • .align-content{breakpoint.abbr}-stretch
    • -     - ) -})} -
- -## CSS Grid utilities - -While most of the utilities above apply to flexbox containers, Bootstrap also includes utilities specifically for CSS Grid layouts. - -### Justify items - -Use `justify-items` utilities on CSS Grid containers to change the alignment of grid items along the inline (row) axis. Choose from `start`, `end`, `center`, or `stretch` (browser default). - -
-
-
Grid item
-
Grid item
-
Grid item
-
-
-
Grid item
-
Grid item
-
Grid item
-
-
-
Grid item
-
Grid item
-
Grid item
-
-
-
Grid item
-
Grid item
-
Grid item
-
-
- -```html -
...
-
...
-
...
-
...
-``` - -Responsive variations also exist for `justify-items`. - -
    -{getData('breakpoints').map((breakpoint) => { - return ( - -
  • .justify-items{breakpoint.abbr}-start
    • -
  • .justify-items{breakpoint.abbr}-end
    • -
  • .justify-items{breakpoint.abbr}-center
    • -
  • .justify-items{breakpoint.abbr}-stretch
    • -     - ) -})} -
- -### Place items - -Use `place-items` utilities on CSS Grid containers as a shorthand to set both `align-items` and `justify-items` at once. Choose from `start`, `end`, `center`, or `stretch` (browser default). - -
-
-
Grid item
-
Grid item
-
Grid item
-
-
-
Grid item
-
Grid item
-
Grid item
-
-
-
Grid item
-
Grid item
-
Grid item
-
-
-
Grid item
-
Grid item
-
Grid item
-
-
- -```html -
...
-
...
-
...
-
...
-``` - -Responsive variations also exist for `place-items`. - -
    -{getData('breakpoints').map((breakpoint) => { - return ( - -
  • .place-items{breakpoint.abbr}-start
    • -
  • .place-items{breakpoint.abbr}-end
    • -
  • .place-items{breakpoint.abbr}-center
    • -
  • .place-items{breakpoint.abbr}-stretch
    • -     - ) -})} -
- -## Media object - -Looking to replicate the [media object component](https://getbootstrap.com/docs/4.6/components/media-object/) from Bootstrap 4? Recreate it in no time with a few flex utilities that allow even more flexibility and customization than before. - - -
- -
-
- This is some content from a media component. You can replace this with any content and adjust it as needed. -
- `} /> - -And say you want to vertically center the content next to the image: - - -
- -
-
- This is some content from a media component. You can replace this with any content and adjust it as needed. -
- `} /> - ## CSS ### Sass utilities API -Flexbox and CSS Grid utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]([[docsref:/utilities/api#using-the-api]]) +Flexbox utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]([[docsref:/utilities/api#using-the-api]]) diff --git a/site/src/content/docs/utilities/font-style.mdx b/site/src/content/docs/utilities/font-style.mdx new file mode 100644 index 0000000000..b1d9e655c9 --- /dev/null +++ b/site/src/content/docs/utilities/font-style.mdx @@ -0,0 +1,122 @@ +--- +title: Font style +description: Utilities for controlling font properties including size, weight, style, line height, and font family. +toc: true +reference: + - class: fs-1 + styles: + font-size: 'calc(1.375rem + 1.5vw)' + - class: fs-6 + styles: + font-size: '1rem' + - class: fw-bold + styles: + font-weight: '700' + - class: fw-normal + styles: + font-weight: '400' + - class: fst-italic + styles: + font-style: 'italic' + - class: fst-normal + styles: + font-style: 'normal' + - class: lh-1 + styles: + line-height: '1' + - class: font-monospace + styles: + font-family: 'var(--bs-font-monospace)' +--- + +import { getData } from '@libs/data' + +## Font size + +Quickly change the `font-size` of text. While our heading classes (e.g., `.h1`–`.h6`) apply `font-size`, `font-weight`, and `line-height`, these utilities _only_ apply `font-size`. Sizing for these utilities matches HTML's heading elements, so as the number increases, their size decreases. + +.fs-1 text

+

.fs-2 text

+

.fs-3 text

+

.fs-4 text

+

.fs-5 text

+

.fs-6 text

`} /> + +Customize your available `font-size`s by modifying the `$font-sizes` Sass map. + +## Font weight and italics + +Quickly change the `font-weight` or `font-style` of text with these utilities. `font-style` utilities are abbreviated as `.fst-*` and `font-weight` utilities are abbreviated as `.fw-*`. + +Bold text.

+

Bolder weight text (relative to the parent element).

+

Semibold weight text.

+

Medium weight text.

+

Normal weight text.

+

Light weight text.

+

Lighter weight text (relative to the parent element).

+

Italic text.

+

Text with normal font style

`} /> + +## Line height + +Change the line height with `.lh-*` utilities. + +This is a long paragraph written to show how the line-height of an element is affected by our utilities. Classes are applied to the element itself or sometimes the parent element. These classes can be customized as needed with our utility API.

+

This is a long paragraph written to show how the line-height of an element is affected by our utilities. Classes are applied to the element itself or sometimes the parent element. These classes can be customized as needed with our utility API.

+

This is a long paragraph written to show how the line-height of an element is affected by our utilities. Classes are applied to the element itself or sometimes the parent element. These classes can be customized as needed with our utility API.

+

This is a long paragraph written to show how the line-height of an element is affected by our utilities. Classes are applied to the element itself or sometimes the parent element. These classes can be customized as needed with our utility API.

`} /> + +## Font family + +Change a selection to our monospace font stack with `.font-monospace`. + +This is in monospace

`} /> + +## CSS + +### Sass utilities API + +Font style utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]([[docsref:/utilities/api#using-the-api]]) + +```scss +"font-family": ( + property: font-family, + class: font, + values: (monospace: var(--#{$prefix}font-monospace)) +), +"font-size": ( + rfs: true, + property: font-size, + class: fs, + values: $font-sizes +), +"font-style": ( + property: font-style, + class: fst, + values: italic normal +), +"font-weight": ( + property: font-weight, + class: fw, + values: ( + lighter: $font-weight-lighter, + light: $font-weight-light, + normal: $font-weight-normal, + medium: $font-weight-medium, + semibold: $font-weight-semibold, + bold: $font-weight-bold, + bolder: $font-weight-bolder + ) +), +"line-height": ( + property: line-height, + class: lh, + values: ( + 1: 1, + sm: $line-height-sm, + base: $line-height-base, + lg: $line-height-lg, + ) +), +``` diff --git a/site/src/content/docs/utilities/height.mdx b/site/src/content/docs/utilities/height.mdx new file mode 100644 index 0000000000..d1b2b489a1 --- /dev/null +++ b/site/src/content/docs/utilities/height.mdx @@ -0,0 +1,148 @@ +--- +title: Height +description: Use height utilities to control the height of elements with responsive height classes. +toc: true +mdn: https://developer.mozilla.org/en-US/docs/Web/CSS/height +reference: + - class: h-25 + styles: + height: '25%' + - class: h-50 + styles: + height: '50%' + - class: h-75 + styles: + height: '75%' + - class: h-100 + styles: + height: '100%' + - class: h-auto + styles: + height: 'auto' + - class: h-min + styles: + height: 'min-content' + - class: h-max + styles: + height: 'max-content' + - class: h-fit + styles: + height: 'fit-content' + - class: max-h-100 + styles: + max-height: '100%' + - class: min-h-0 + styles: + min-height: '0' + - class: min-h-100 + styles: + min-height: '100%' + - class: vh-100 + styles: + height: '100vh' + - class: min-vh-100 + styles: + min-height: '100vh' +--- + +## Overview + +Use height utilities to set the height of elements. Height utilities are generated from the utility API and include support for percentage values, intrinsic sizing keywords, and viewport units. + +## Relative height + +Set height relative to the parent element using percentage-based utilities. Includes support for `25%`, `50%`, `75%`, `100%`, and `auto` by default. + + +
Height 25%
+
Height 50%
+
Height 75%
+
Height 100%
+
Height auto
+ `} /> + +## Intrinsic sizing + +Use intrinsic sizing keywords to set height based on content. + + +
Height min-content
+
Height max-content
+
Height fit-content
+ `} /> + +## Max height + +Set maximum height using `max-height` utilities. + + +
Max-height 100%
+ `} /> + +## Min height + +Set minimum height using `min-height` utilities. + + + Min-height 0 (allows content to determine height) + +
Min-height 100%
`} /> + +## Viewport height + +Set height relative to the viewport using viewport units. + +```html +
Height 100vh
+
Min-height 100vh
+``` + + +**Full viewport height sections!** Using `vh-100` makes an element take up the entire viewport height, which is useful for hero sections and full-screen layouts. + + +## CSS + +### Sass utilities API + +Height utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]([[docsref:/utilities/api#using-the-api]]) + +```scss +"height": ( + property: height, + class: h, + values: ( + 25: 25%, + 50: 50%, + 75: 75%, + 100: 100%, + auto: auto, + min: min-content, + max: max-content, + fit: fit-content, + ) +), +"max-height": ( + property: max-height, + class: max-h, + values: (100: 100%) +), +"min-height": ( + property: min-height, + class: min-h, + values: ( + 0: 0, + 100: 100%, + ), +), +"viewport-height": ( + property: height, + class: vh, + values: (100: 100vh) +), +"min-viewport-height": ( + property: min-height, + class: min-vh, + values: (100: 100vh) +), +``` diff --git a/site/src/content/docs/utilities/justify-content.mdx b/site/src/content/docs/utilities/justify-content.mdx new file mode 100644 index 0000000000..e61fe278d7 --- /dev/null +++ b/site/src/content/docs/utilities/justify-content.mdx @@ -0,0 +1,96 @@ +--- +title: Justify content +description: Use justify-content utilities to change the alignment of flex items on the main axis. +toc: true +mdn: https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content +--- + +import { getData } from '@libs/data' + +## Overview + +Use `justify-content` utilities on flexbox containers to change the alignment of flex items on the main axis (the x-axis to start, y-axis if `flex-direction: column`). Choose from `start` (browser default), `end`, `center`, `between`, `around`, or `evenly`. + +## Basic usage + +
+
+
Justify
+
Content
+
Start
+
+
+
Justify
+
Content
+
End
+
+
+
Justify
+
Content
+
Center
+
+
+
Justify
+
Content
+
Between
+
+
+
Justify
+
Content
+
Around
+
+
+
Justify
+
Content
+
Evenly
+
+
+ +```html +
...
+
...
+
...
+
...
+
...
+
...
+``` + +## Responsive + +Responsive variations also exist for `justify-content`. + +
    +{getData('breakpoints').map((breakpoint) => { + return ( + +
  • .justify-content{breakpoint.abbr}-start
    • +
  • .justify-content{breakpoint.abbr}-end
    • +
  • .justify-content{breakpoint.abbr}-center
    • +
  • .justify-content{breakpoint.abbr}-between
    • +
  • .justify-content{breakpoint.abbr}-around
    • +
  • .justify-content{breakpoint.abbr}-evenly
    • +     + ) +})} +
+ +## CSS + +### Sass utilities API + +Justify content utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]([[docsref:/utilities/api#using-the-api]]) + +```scss +"justify-content": ( + responsive: true, + property: justify-content, + values: ( + start: flex-start, + end: flex-end, + center: center, + between: space-between, + around: space-around, + evenly: space-evenly, + ) +), +``` diff --git a/site/src/content/docs/utilities/justify-items.mdx b/site/src/content/docs/utilities/justify-items.mdx new file mode 100644 index 0000000000..0540a4b2f5 --- /dev/null +++ b/site/src/content/docs/utilities/justify-items.mdx @@ -0,0 +1,82 @@ +--- +title: Justify items +description: Use justify-items utilities to control the alignment of grid items along the inline axis (horizontally, in most writing modes). +toc: true +mdn: https://developer.mozilla.org/en-US/docs/Web/CSS/justify-items +--- + +import { getData } from '@libs/data' + +## Overview + +Use `justify-items` utilities on CSS Grid containers to change the alignment of grid items along the inline (row) axis. This property controls how grid items are positioned horizontally within their grid areas. + +## Basic usage + +Use `justify-items` utilities to control the horizontal alignment of grid items. Choose from `start`, `end`, `center`, or `stretch` (browser default). + +
+
+
Grid item
+
Grid item
+
Grid item
+
+
+
Grid item
+
Grid item
+
Grid item
+
+
+
Grid item
+
Grid item
+
Grid item
+
+
+
Grid item
+
Grid item
+
Grid item
+
+
+ +```html +
...
+
...
+
...
+
...
+``` + +## Responsive + +Responsive variations also exist for `justify-items`. + +
    +{getData('breakpoints').map((breakpoint) => { + return ( + +
  • .justify-items{breakpoint.abbr}-start
    • +
  • .justify-items{breakpoint.abbr}-end
    • +
  • .justify-items{breakpoint.abbr}-center
    • +
  • .justify-items{breakpoint.abbr}-stretch
    • +     + ) +})} +
+ +## CSS + +### Sass utilities API + +Justify items utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]([[docsref:/utilities/api#using-the-api]]) + +```scss +"justify-items": ( + responsive: true, + property: justify-items, + values: ( + start: start, + end: end, + center: center, + stretch: stretch, + ) +), +``` diff --git a/site/src/content/docs/utilities/margin.mdx b/site/src/content/docs/utilities/margin.mdx new file mode 100644 index 0000000000..43d9c19cc4 --- /dev/null +++ b/site/src/content/docs/utilities/margin.mdx @@ -0,0 +1,208 @@ +--- +title: Margin +description: Use margin utilities to control the space around elements with responsive margin classes. +toc: true +mdn: https://developer.mozilla.org/en-US/docs/Web/CSS/margin +reference: + - class: m-0 + styles: + margin: '0' + - class: m-1 + styles: + margin: '0.25rem' + - class: m-2 + styles: + margin: '0.5rem' + - class: m-3 + styles: + margin: '1rem' + - class: m-4 + styles: + margin: '1.5rem' + - class: m-5 + styles: + margin: '3rem' + - class: m-auto + styles: + margin: 'auto' + - class: mt-0 + styles: + margin-top: '0' + - class: me-0 + styles: + margin-right: '0' + - class: mb-0 + styles: + margin-bottom: '0' + - class: ms-0 + styles: + margin-left: '0' + - class: mx-0 + styles: + margin-right: '0' + margin-left: '0' + - class: my-0 + styles: + margin-top: '0' + margin-bottom: '0' +--- + +import { getData } from '@libs/data' + +## Overview + +Use margin utilities to control the outer space around elements. Margin utilities are built from a default Sass map ranging from `.25rem` to `3rem`. + + +**Using the CSS Grid layout module?** Consider using [the gap utility]([[docsref:/utilities/spacing#gap]]) instead. + + +## Notation + +Margin utilities that apply to all breakpoints, from `xs` to `xxl`, have no breakpoint abbreviation in them. This is because those classes are applied from `min-width: 0` and up, and thus are not bound by a media query. The remaining breakpoints, however, do include a breakpoint abbreviation. + +The classes are named using the format `{property}{sides}-{size}` for `xs` and `{property}{sides}-{breakpoint}-{size}` for `sm`, `md`, `lg`, `xl`, and `xxl`. + +Where *property* is: + +- `m` - for classes that set `margin` + +Where *sides* is one of: + +- `t` - for classes that set `margin-top` +- `b` - for classes that set `margin-bottom` +- `s` - (start) for classes that set `margin-left` in LTR, `margin-right` in RTL +- `e` - (end) for classes that set `margin-right` in LTR, `margin-left` in RTL +- `x` - for classes that set both `*-left` and `*-right` +- `y` - for classes that set both `*-top` and `*-bottom` +- blank - for classes that set a `margin` on all 4 sides of the element + +Where *size* is one of: + +- `0` - for classes that eliminate the `margin` by setting it to `0` +- `1` - (by default) for classes that set the `margin` to `$spacer * .25` +- `2` - (by default) for classes that set the `margin` to `$spacer * .5` +- `3` - (by default) for classes that set the `margin` to `$spacer` +- `4` - (by default) for classes that set the `margin` to `$spacer * 1.5` +- `5` - (by default) for classes that set the `margin` to `$spacer * 3` +- `auto` - for classes that set the `margin` to auto + +(You can add more sizes by adding entries to the `$spacers` Sass map variable.) + +## Examples + +Here are some representative examples of these classes: + +```scss +.mt-0 { + margin-top: 0; +} + +.ms-1 { + margin-left: ($spacer * .25); +} + +.mx-2 { + margin-left: ($spacer * .5); + margin-right: ($spacer * .5); +} + +.m-3 { + margin: $spacer; +} +``` + +## Horizontal centering + +Bootstrap includes an `.mx-auto` class for horizontally centering fixed-width block level content—that is, content that has `display: block` and a `width` set—by setting the horizontal margins to `auto`. + + + Centered element + `} /> + +```html +
+ Centered element +
+``` + +## Negative margin + +When using `display: grid`, you can make use of negative margin utilities along the parent grid container. This can sometimes be helpful to match visual alignment of a child grid with the rest of your layout. Remember that [CSS Grid has a gap property]([[docsref:/utilities/spacing#gap]]) that might be an alternative solution. + + +
.g-col-1
+
.g-col-1
+
.g-col-1
+ `} /> + +```html +
+
.g-col-1
+
.g-col-1
+
.g-col-1
+
+``` + +## Responsive + +All margin utilities are responsive and include all breakpoints. + +
    +{getData('breakpoints').map((breakpoint) => { + return ( +
  • .m{breakpoint.abbr}-0 through .m{breakpoint.abbr}-5 and .m{breakpoint.abbr}-auto
    • + ) +})} +
+ +## CSS + +### Sass utilities API + +Margin utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]([[docsref:/utilities/api#using-the-api]]) + +```scss +"margin": ( + responsive: true, + property: margin, + class: m, + values: map.merge($spacers, (auto: auto)) +), +"margin-x": ( + responsive: true, + property: margin-right margin-left, + class: mx, + values: map.merge($spacers, (auto: auto)) +), +"margin-y": ( + responsive: true, + property: margin-top margin-bottom, + class: my, + values: map.merge($spacers, (auto: auto)) +), +"margin-top": ( + responsive: true, + property: margin-top, + class: mt, + values: map.merge($spacers, (auto: auto)) +), +"margin-end": ( + responsive: true, + property: margin-right, + class: me, + values: map.merge($spacers, (auto: auto)) +), +"margin-bottom": ( + responsive: true, + property: margin-bottom, + class: mb, + values: map.merge($spacers, (auto: auto)) +), +"margin-start": ( + responsive: true, + property: margin-left, + class: ms, + values: map.merge($spacers, (auto: auto)) +), +``` diff --git a/site/src/content/docs/utilities/padding.mdx b/site/src/content/docs/utilities/padding.mdx new file mode 100644 index 0000000000..bb812459a3 --- /dev/null +++ b/site/src/content/docs/utilities/padding.mdx @@ -0,0 +1,180 @@ +--- +title: Padding +description: Use padding utilities to control the inner space of elements with responsive padding classes. +toc: true +mdn: https://developer.mozilla.org/en-US/docs/Web/CSS/padding +reference: + - class: p-0 + styles: + padding: '0' + - class: p-1 + styles: + padding: '0.25rem' + - class: p-2 + styles: + padding: '0.5rem' + - class: p-3 + styles: + padding: '1rem' + - class: p-4 + styles: + padding: '1.5rem' + - class: p-5 + styles: + padding: '3rem' + - class: pt-0 + styles: + padding-top: '0' + - class: pe-0 + styles: + padding-right: '0' + - class: pb-0 + styles: + padding-bottom: '0' + - class: ps-0 + styles: + padding-left: '0' + - class: px-0 + styles: + padding-right: '0' + padding-left: '0' + - class: py-0 + styles: + padding-top: '0' + padding-bottom: '0' +--- + +import { getData } from '@libs/data' + +## Overview + +Use padding utilities to control the inner space within elements. Padding utilities are built from a default Sass map ranging from `.25rem` to `3rem`. + +## Notation + +Padding utilities that apply to all breakpoints, from `xs` to `xxl`, have no breakpoint abbreviation in them. This is because those classes are applied from `min-width: 0` and up, and thus are not bound by a media query. The remaining breakpoints, however, do include a breakpoint abbreviation. + +The classes are named using the format `{property}{sides}-{size}` for `xs` and `{property}{sides}-{breakpoint}-{size}` for `sm`, `md`, `lg`, `xl`, and `xxl`. + +Where *property* is: + +- `p` - for classes that set `padding` + +Where *sides* is one of: + +- `t` - for classes that set `padding-top` +- `b` - for classes that set `padding-bottom` +- `s` - (start) for classes that set `padding-left` in LTR, `padding-right` in RTL +- `e` - (end) for classes that set `padding-right` in LTR, `padding-left` in RTL +- `x` - for classes that set both `*-left` and `*-right` +- `y` - for classes that set both `*-top` and `*-bottom` +- blank - for classes that set a `padding` on all 4 sides of the element + +Where *size* is one of: + +- `0` - for classes that eliminate the `padding` by setting it to `0` +- `1` - (by default) for classes that set the `padding` to `$spacer * .25` +- `2` - (by default) for classes that set the `padding` to `$spacer * .5` +- `3` - (by default) for classes that set the `padding` to `$spacer` +- `4` - (by default) for classes that set the `padding` to `$spacer * 1.5` +- `5` - (by default) for classes that set the `padding` to `$spacer * 3` + +(You can add more sizes by adding entries to the `$spacers` Sass map variable.) + +## Examples + +Here are some representative examples of these classes: + +```scss +.pt-0 { + padding-top: 0; +} + +.ps-1 { + padding-left: ($spacer * .25); +} + +.px-2 { + padding-left: ($spacer * .5); + padding-right: ($spacer * .5); +} + +.p-3 { + padding: $spacer; +} +``` + +## Basic usage + + + Regular padding on all sides + +
+ Horizontal and vertical padding +
+
+ Top padding only +
`} /> + +## Responsive + +All padding utilities are responsive and include all breakpoints. + +
    +{getData('breakpoints').map((breakpoint) => { + return ( +
  • .p{breakpoint.abbr}-0 through .p{breakpoint.abbr}-5
    • + ) +})} +
+ +## CSS + +### Sass utilities API + +Padding utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]([[docsref:/utilities/api#using-the-api]]) + +```scss +"padding": ( + responsive: true, + property: padding, + class: p, + values: $spacers +), +"padding-x": ( + responsive: true, + property: padding-right padding-left, + class: px, + values: $spacers +), +"padding-y": ( + responsive: true, + property: padding-top padding-bottom, + class: py, + values: $spacers +), +"padding-top": ( + responsive: true, + property: padding-top, + class: pt, + values: $spacers +), +"padding-end": ( + responsive: true, + property: padding-right, + class: pe, + values: $spacers +), +"padding-bottom": ( + responsive: true, + property: padding-bottom, + class: pb, + values: $spacers +), +"padding-start": ( + responsive: true, + property: padding-left, + class: ps, + values: $spacers +), +``` diff --git a/site/src/content/docs/utilities/place-items.mdx b/site/src/content/docs/utilities/place-items.mdx new file mode 100644 index 0000000000..87413eb8ae --- /dev/null +++ b/site/src/content/docs/utilities/place-items.mdx @@ -0,0 +1,82 @@ +--- +title: Place items +description: Use place-items utilities to control the alignment of grid items within their grid areas on both the block and inline axes simultaneously. +toc: true +mdn: https://developer.mozilla.org/en-US/docs/Web/CSS/place-items +--- + +import { getData } from '@libs/data' + +## Overview + +Use `place-items` utilities on CSS Grid containers as a shorthand to set both `align-items` and `justify-items` at once. This property controls how grid items are positioned within their grid areas on both axes. + +## Basic usage + +Use `place-items` utilities to control the alignment of grid items. Choose from `start`, `end`, `center`, or `stretch` (browser default). + +
+
+
Grid item
+
Grid item
+
Grid item
+
+
+
Grid item
+
Grid item
+
Grid item
+
+
+
Grid item
+
Grid item
+
Grid item
+
+
+
Grid item
+
Grid item
+
Grid item
+
+
+ +```html +
...
+
...
+
...
+
...
+``` + +## Responsive + +Responsive variations also exist for `place-items`. + +
    +{getData('breakpoints').map((breakpoint) => { + return ( + +
  • .place-items{breakpoint.abbr}-start
    • +
  • .place-items{breakpoint.abbr}-end
    • +
  • .place-items{breakpoint.abbr}-center
    • +
  • .place-items{breakpoint.abbr}-stretch
    • +     + ) +})} +
+ +## CSS + +### Sass utilities API + +Place items utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]([[docsref:/utilities/api#using-the-api]]) + +```scss +"place-items": ( + responsive: true, + property: place-items, + values: ( + start: start, + end: end, + center: center, + stretch: stretch, + ) +), +``` diff --git a/site/src/content/docs/utilities/pointer-events.mdx b/site/src/content/docs/utilities/pointer-events.mdx new file mode 100644 index 0000000000..5955b17852 --- /dev/null +++ b/site/src/content/docs/utilities/pointer-events.mdx @@ -0,0 +1,63 @@ +--- +title: Pointer events +description: Control how elements respond to mouse and touch interactions with pointer-events utilities. +toc: true +mdn: https://developer.mozilla.org/en-US/docs/Web/CSS/pointer-events +reference: + - class: pe-none + styles: + pointer-events: 'none' + - class: pe-auto + styles: + pointer-events: 'auto' +--- + +## Overview + +Bootstrap provides `.pe-none` and `.pe-auto` classes to prevent or add element interactions through the `pointer-events` CSS property. + +## Basic usage + +This link can not be clicked.

+

This link can be clicked (this is default behavior).

+

This link can not be clicked because the pointer-events property is inherited from its parent. However, this link has a pe-auto class and can be clicked.

`} /> + +## Important considerations + +The `.pe-none` class (and the `pointer-events` CSS property it sets) only prevents interactions with a pointer (mouse, stylus, touch). Links and controls with `.pe-none` are, by default, still focusable and actionable for keyboard users. + +To ensure that they are completely neutralized even for keyboard users, you may need to add further attributes such as: + +- `tabindex="-1"` (to prevent them from receiving keyboard focus) +- `aria-disabled="true"` (to convey the fact they are effectively disabled to assistive technologies) +- JavaScript to completely prevent them from being actionable + +## Better alternatives + +If possible, the simpler solution is: + +- **For form controls**: Add the `disabled` HTML attribute +- **For links**: Remove the `href` attribute, making it a non-interactive anchor or placeholder link + + +**Accessibility warning:** Using `pointer-events: none` can create accessibility barriers. Always ensure that disabled elements are properly marked up with appropriate ARIA attributes and that keyboard users can't accidentally focus them. + + +## Use cases + +- **`.pe-none`** - Disable interactions on overlays, loading states, or temporarily disabled elements +- **`.pe-auto`** - Re-enable interactions on child elements when parent has `pe-none` + +## CSS + +### Sass utilities API + +Pointer events utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]([[docsref:/utilities/api#using-the-api]]) + +```scss +"pointer-events": ( + property: pointer-events, + class: pe, + values: none auto, +), +``` diff --git a/site/src/content/docs/utilities/text-alignment.mdx b/site/src/content/docs/utilities/text-alignment.mdx new file mode 100644 index 0000000000..fd28a9bfbd --- /dev/null +++ b/site/src/content/docs/utilities/text-alignment.mdx @@ -0,0 +1,73 @@ +--- +title: Text alignment +description: Easily realign text with text alignment utilities for start, end, and center alignment. +toc: true +mdn: https://developer.mozilla.org/en-US/docs/Web/CSS/text-align +reference: + - class: text-start + styles: + text-align: 'left' + - class: text-center + styles: + text-align: 'center' + - class: text-end + styles: + text-align: 'right' +--- + +import { getData } from '@libs/data' + +## Overview + +Easily realign text to components with text alignment classes. For start, end, and center alignment, responsive classes are available that use the same viewport width breakpoints as the grid system. + +## Basic usage + +Start aligned text on all viewport sizes.

+

Center aligned text on all viewport sizes.

+

End aligned text on all viewport sizes.

+ +

End aligned text on viewports sized SM (small) or wider.

+

End aligned text on viewports sized MD (medium) or wider.

+

End aligned text on viewports sized LG (large) or wider.

+

End aligned text on viewports sized XL (extra large) or wider.

+

End aligned text on viewports sized XXL (extra extra large) or wider.

`} /> + + +Note that we don't provide utility classes for justified text. While, aesthetically, justified text might look more appealing, it does make word-spacing more random and therefore harder to read. + + +## Responsive + +Responsive variations also exist for `text-align`. + +
    +{getData('breakpoints').map((breakpoint) => { + return ( + +
  • .text{breakpoint.abbr}-start
    • +
  • .text{breakpoint.abbr}-center
    • +
  • .text{breakpoint.abbr}-end
    • +     + ) +})} +
+ +## CSS + +### Sass utilities API + +Text alignment utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]([[docsref:/utilities/api#using-the-api]]) + +```scss +"text-align": ( + responsive: true, + property: text-align, + class: text, + values: ( + start: left, + end: right, + center: center, + ) +), +``` diff --git a/site/src/content/docs/utilities/text-decoration.mdx b/site/src/content/docs/utilities/text-decoration.mdx new file mode 100644 index 0000000000..db0f749476 --- /dev/null +++ b/site/src/content/docs/utilities/text-decoration.mdx @@ -0,0 +1,69 @@ +--- +title: Text decoration +description: Utilities for controlling text decoration, text transform, and text color reset. +toc: true +mdn: https://developer.mozilla.org/en-US/docs/Web/CSS/text-decoration +reference: + - class: text-decoration-underline + styles: + text-decoration: 'underline' + - class: text-decoration-line-through + styles: + text-decoration: 'line-through' + - class: text-decoration-none + styles: + text-decoration: 'none' + - class: text-lowercase + styles: + text-transform: 'lowercase' + - class: text-uppercase + styles: + text-transform: 'uppercase' + - class: text-capitalize + styles: + text-transform: 'capitalize' +--- + +## Text decoration + +Decorate text in components with text decoration classes. + +This text has a line underneath it.

+

This text has a line going through it.

+This link has its text decoration removed`} /> + +## Text transform + +Transform text in components with our text capitalization classes: `text-lowercase`, `text-uppercase` or `text-capitalize`. + +Lowercased text.

+

Uppercased text.

+

CapiTaliZed text.

`} /> + +Note how `.text-capitalize` only changes the first letter of each word, leaving the case of any other letters unaffected. + +## Reset color + +Reset a text or link's color with `.text-reset`, so that it inherits the color from its parent. + + + Secondary body text with a reset link. +

`} /> + +## CSS + +### Sass utilities API + +Text decoration utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]([[docsref:/utilities/api#using-the-api]]) + +```scss +"text-decoration": ( + property: text-decoration, + values: none underline line-through +), +"text-transform": ( + property: text-transform, + class: text, + values: lowercase uppercase capitalize +), +``` diff --git a/site/src/content/docs/utilities/text-wrapping.mdx b/site/src/content/docs/utilities/text-wrapping.mdx new file mode 100644 index 0000000000..98c68d7f28 --- /dev/null +++ b/site/src/content/docs/utilities/text-wrapping.mdx @@ -0,0 +1,64 @@ +--- +title: Text wrapping +description: Utilities for controlling text wrapping, overflow, and word breaking behavior. +toc: true +mdn: https://developer.mozilla.org/en-US/docs/Web/CSS/white-space +reference: + - class: text-wrap + styles: + white-space: 'normal' + - class: text-nowrap + styles: + white-space: 'nowrap' + - class: text-break + styles: + word-wrap: 'break-word' + word-break: 'break-word' +--- + +## Text wrapping and overflow + +Wrap text with a `.text-wrap` class. + + + This text should wrap. + `} /> + +Prevent text from wrapping with a `.text-nowrap` class. + + + This text should overflow the parent. + `} /> + +## Word break + +Prevent long strings of text from breaking your components' layout by using `.text-break` to set `word-wrap: break-word` and `word-break: break-word`. We use `word-wrap` instead of the more common `overflow-wrap` for wider browser support, and add the deprecated `word-break: break-word` to avoid issues with flex containers. + +mmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmm

`} /> + + +Note that [breaking words isn't possible in Arabic](https://rtlstyling.com/posts/rtl-styling#3.-line-break), which is the most used RTL language. Therefore `.text-break` is removed from our RTL compiled CSS. + + +## CSS + +### Sass utilities API + +Text wrapping utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]([[docsref:/utilities/api#using-the-api]]) + +```scss +"white-space": ( + property: white-space, + class: text, + values: ( + wrap: normal, + nowrap: nowrap, + ) +), +"word-wrap": ( + property: word-wrap word-break, + class: text, + values: (break: break-word), + rtl: false +), +``` diff --git a/site/src/content/docs/utilities/user-select.mdx b/site/src/content/docs/utilities/user-select.mdx new file mode 100644 index 0000000000..5664aba0d3 --- /dev/null +++ b/site/src/content/docs/utilities/user-select.mdx @@ -0,0 +1,49 @@ +--- +title: User select +description: Control how users can select text content with user-select utilities. +toc: true +mdn: https://developer.mozilla.org/en-US/docs/Web/CSS/user-select +reference: + - class: user-select-all + styles: + user-select: 'all' + - class: user-select-auto + styles: + user-select: 'auto' + - class: user-select-none + styles: + user-select: 'none' +--- + +## Overview + +Change the way in which the content is selected when the user interacts with it using user-select utilities. + +## Basic usage + +This paragraph will be entirely selected when clicked by the user.

+

This paragraph has default select behavior.

+

This paragraph will not be selectable when clicked by the user.

`} /> + +## Use cases + +- **`.user-select-all`** - Useful for code snippets, IDs, or other content users might want to copy entirely +- **`.user-select-auto`** - Default browser behavior, allows normal text selection +- **`.user-select-none`** - Prevents text selection, useful for UI elements, buttons, or decorative text + + +**Accessibility note:** Be careful when using `user-select: none` as it can interfere with assistive technologies and keyboard navigation. Ensure that important content remains accessible through other means. + + +## CSS + +### Sass utilities API + +User select utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]([[docsref:/utilities/api#using-the-api]]) + +```scss +"user-select": ( + property: user-select, + values: all auto none +), +``` diff --git a/site/src/content/docs/utilities/width.mdx b/site/src/content/docs/utilities/width.mdx new file mode 100644 index 0000000000..25ccddaa7d --- /dev/null +++ b/site/src/content/docs/utilities/width.mdx @@ -0,0 +1,144 @@ +--- +title: Width +description: Use width utilities to control the width of elements with responsive width classes. +toc: true +mdn: https://developer.mozilla.org/en-US/docs/Web/CSS/width +reference: + - class: w-25 + styles: + width: '25%' + - class: w-50 + styles: + width: '50%' + - class: w-75 + styles: + width: '75%' + - class: w-100 + styles: + width: '100%' + - class: w-auto + styles: + width: 'auto' + - class: w-min + styles: + width: 'min-content' + - class: w-max + styles: + width: 'max-content' + - class: w-fit + styles: + width: 'fit-content' + - class: max-w-100 + styles: + max-width: '100%' + - class: min-w-0 + styles: + min-width: '0' + - class: min-w-100 + styles: + min-width: '100%' + - class: vw-100 + styles: + width: '100vw' + - class: min-vw-100 + styles: + min-width: '100vw' +--- + +## Overview + +Use width utilities to set the width of elements. Width utilities are generated from the utility API and include support for percentage values, intrinsic sizing keywords, and viewport units. + +## Relative width + +Set width relative to the parent element using percentage-based utilities. Includes support for `25%`, `50%`, `75%`, `100%`, and `auto` by default. + +Width 25% +
Width 50%
+
Width 75%
+
Width 100%
+
Width auto
`} /> + +## Intrinsic sizing + +Use intrinsic sizing keywords to set width based on content. + +Width min-content +
Width max-content
+
Width fit-content
`} /> + +## Max width + +Set maximum width using `max-width` utilities. + + +
Max-width 100%
+ `} /> + +## Min width + +Set minimum width using `min-width` utilities. + + +
This content is wider than the min-width: 0 container
+ +
Min-width 100%
`} /> + +## Viewport width + +Set width relative to the viewport using viewport units. + +```html +
Width 100vw
+
Min-width 100vw
+``` + + +**Beware of the viewport width!** Using `vw-100` can cause horizontal scrollbars if the content is wider than the viewport, particularly on smaller screens. + + +## CSS + +### Sass utilities API + +Width utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]([[docsref:/utilities/api#using-the-api]]) + +```scss +"width": ( + property: width, + class: w, + values: ( + 25: 25%, + 50: 50%, + 75: 75%, + 100: 100%, + auto: auto, + min: min-content, + max: max-content, + fit: fit-content, + ) +), +"max-width": ( + property: max-width, + class: max-w, + values: (100: 100%) +), +"min-width": ( + property: min-width, + class: min-w, + values: ( + 0: 0, + 100: 100% + ) +), +"viewport-width": ( + property: width, + class: vw, + values: (100: 100vw) +), +"min-viewport-width": ( + property: min-width, + class: min-vw, + values: (100: 100vw) +), +``` diff --git a/site/src/libs/data.ts b/site/src/libs/data.ts index b4279b965d..d388ffcd02 100644 --- a/site/src/libs/data.ts +++ b/site/src/libs/data.ts @@ -82,7 +82,14 @@ const dataDefinitions = { icon_color: z.string().optional(), pages: z .object({ - title: z.string() + title: z.string().optional(), + group: z.string().optional(), + pages: z + .object({ + title: z.string() + }) + .array() + .optional() }) .array() .optional() @@ -117,7 +124,7 @@ let data = new Map>() export function getData(type: TType): z.infer<(typeof dataDefinitions)[TType]> { if (data.has(type)) { // Returns the data if it has already been loaded. - return data.get(type) + return data.get(type) as z.infer<(typeof dataDefinitions)[TType]> } const dataPath = `./site/data/${type}.yml` @@ -127,7 +134,7 @@ export function getData(type: TType): z.infer<(typeof da const rawData = yaml.load(fs.readFileSync(dataPath, 'utf8')) // Parse the data using the data schema to validate its content and get back a fully typed data object. - const parsedData = dataDefinitions[type].parse(rawData) + const parsedData = dataDefinitions[type].parse(rawData) as z.infer<(typeof dataDefinitions)[TType]> // Cache the data. data.set(type, parsedData) diff --git a/site/src/scss/_sidebar.scss b/site/src/scss/_sidebar.scss index 10e750f32b..edf7db77e8 100644 --- a/site/src/scss/_sidebar.scss +++ b/site/src/scss/_sidebar.scss @@ -28,6 +28,11 @@ color: var(--bs-emphasis-color); } +.bd-links-subgroup { + margin-left: 1.625rem; + color: var(--bs-emphasis-color); +} + .bd-links-nav { // @include media-breakpoint-down(lg) { // font-size: .875rem; diff --git a/site/src/scss/_variables.scss b/site/src/scss/_variables.scss index f30e6f8987..3f278e07c4 100644 --- a/site/src/scss/_variables.scss +++ b/site/src/scss/_variables.scss @@ -24,7 +24,7 @@ $bd-callout-variants: info, warning, danger !default; // --bd-teal-rgb: #{to-rgb($teal-500)}; --bd-violet-bg: var(--bd-violet); --bd-toc-color: light-dark(var(--bd-violet), var(--bs-indigo-300)); - --bd-sidebar-link-bg: color-mix(in srgb, var(--bd-violet), transparent 90%); + --bd-sidebar-link-bg: light-dark(color-mix(in srgb, var(--bd-violet), transparent 90%), color-mix(in srgb, var(--bd-violet), transparent 70%)); --bd-callout-link: #{$blue-600}; --bd-callout-code-color: light-dark(var(--bs-pink-600), var(--bs-pink-300)); --bd-pre-bg: light-dark(var(--bs-gray-100), color-mix(in srgb, var(--bs-gray-900), var(--bs-black) 25%));