Add CSS utilities (#364)

* Add getting started * Add CSS Utilities * Switch to mdx * Fix rendering issue * Fix markdownlint * Update nav.yml * Replace live examples with Storybook links * Fix markdownlint * Update src/@primer/gatsby-theme-doctocat/nav.yml * Test StoryBook playground component (#374) * Add storyBookEmbed component * Use table for animation descriptions * Add height + singleStory * Replace links with `<StorybookEmbed>` * Replace more links with `<StorybookEmbed>` --------- Co-authored-by: simurai <simurai@github.com> * Update flexbox.mdx --------- Co-authored-by: Cole Bemis <colebemis@github.com> Co-authored-by: Josep Martins <josepmartins@github.com>
primer · Feb 1, 2023 · 5010ff7 · 5010ff7
1 parent 09a5f4a
commit 5010ff7
Show file tree

Hide file tree

Showing 16 changed files with 2,020 additions and 2 deletions.
diff --git a/content/foundations/css-utilities/animations.mdx b/content/foundations/css-utilities/animations.mdx
@@ -0,0 +1,50 @@
+---
+title: Animations
+description: Animations are reusable animation classes that you can use to emphasize an element. All of these animations will animate if you toggle their visibility using the "Toggle" button.
+---
+
+<StorybookEmbed
+  framework="css"
+  componentId="utilities-animation"
+  stories={{
+    'fade-in': {
+      name: 'Fade in'
+    },
+    'fade-out': {
+      name: 'Fade out'
+    },
+    'fade-up': {
+      name: 'Fade up'
+    },
+    'fade-down': {
+      name: 'Fade down'
+    },
+    'scale-in': {
+      name: 'Scale in'
+    },
+    'grow-x': {
+      name: 'Grow x'
+    },
+    pulse: {
+      name: 'Pulse'
+    },
+    hover: {
+      name: 'Hover animation'
+    },
+    rotate: {
+      name: 'Rotation'
+    }
+  }}
+/>
+
+Animation | Description
+--- | ---
+Fade in | The `.anim-fade-in` class is used to fade in an element on the page. This will run once when the element is revealed.
+Fade out | The `.anim-fade-out` class is used to fade out an element on the page. This will run once when the element is revealed.
+Fade up | The `.anim-fade-up` class is used to reveal an element on the page by sliding it up from below the fold. You should use this in a container with `overflow: hidden;` or on the bottom of the page.
+Fade down | The `.anim-fade-down` class is used to slide an element down hiding it. You should use this in a container with `overflow: hidden;` or on the bottom of the page.
+Scale in | The `.anim-scale-in` class will scale the element in. This is useful on menus when you want them to appear more friendly.
+Grow x | The `.anim-grow-x` class will grow an element width from 0-:100: real quick.
+Pulse | The `.anim-pulse` class will pulse an element infinitely.
+Hover animation | The `.anim-hover-grow` class will increase the scale of the element upon hover.
+Rotation | The `.anim-rotate` class will rotate the element indefinitely around the coordinate specified by `transform-origin`. Most elements have a default of `transform-origin: 50% 50%` and will rotate around the center.
diff --git a/content/foundations/css-utilities/borders.mdx b/content/foundations/css-utilities/borders.mdx
@@ -0,0 +1,84 @@
+---
+title: Borders
+description: Utilities for borders, and border radius.
+---
+
+## Default border
+
+The default border utility applies a solid, 1px border, with a default gray color.
+
+<StorybookEmbed
+  framework="css"
+  componentId="utilities-border"
+  stories={{'default': {name: 'Default'}}}
+  height="80"
+/>
+
+Borders can be applied to a specific edge or to the X and Y axes individually:
+
+<StorybookEmbed
+  framework="css"
+  componentId="utilities-border"
+  stories={{'direction': {name: 'Direction'}}}
+  height="340"
+/>
+
+Remove borders from all sides or a single side with `.border-0`, `.border-top-0`, `.border-right-0`, `.border-bottom-0`, `.border-left-0`.
+
+<StorybookEmbed
+  framework="css"
+  componentId="utilities-border"
+  stories={{'hide': {name: 'Hide'}}}
+  height="80"
+/>
+
+## Border style
+
+Use `border-dashed` to give an element a dashed border.
+
+<StorybookEmbed
+  framework="css"
+  componentId="utilities-border"
+  stories={{'style': {name: 'Style'}}}
+  height="80"
+/>
+
+## Rounded corners
+
+Use the following utilities to add or remove rounded corners: `rounded-0` removes rounded corners, `rounded-1` applies a border radius of 4px, `rounded-2` applies a border radius of 6px, and `rounded-3` applies a border radius of 8px. `.circle` applies a border radius of 50%, which turns square elements into perfect circles.
+
+<StorybookEmbed
+  framework="css"
+  componentId="utilities-border"
+  stories={{'rounded': {name: 'Rounded'}}}
+  height="360"
+/>
+
+You can also add rounded corners to each edge (top, right, bottom, left) with the following utilities:
+
+<StorybookEmbed
+  framework="css"
+  componentId="utilities-border"
+  stories={{'rounded-direction': {name: 'Rounded Direction'}}}
+  height="240"
+/>
+
+## Responsive borders
+
+You can adjust border widths on all sides or each side individually with responsive border utilities:
+
+- `border-(sm|md|lg|xl)` adds borders on all sides at and above the breakpoint. The `border-(sm|md|lg|xl)` shorthand is also supported.
+- `border-(sm|md|lg|xl)-0` removes borders from all sides at and above the breakpoint.
+- `border-(sm|md|lg|xl)-(top|right|bottom|left)` adds a border on the given side at and above the breakpoint.
+- `border-(sm|md|lg|xl)-(top|right|bottom|left)-0` the border from the given side at and above the breakpoint.
+
+<StorybookEmbed
+  framework="css"
+  componentId="utilities-border"
+  stories={{'responsive': {name: 'Responsive'}}}
+  height="150"
+/>
+
+## Border colors
+
+Border colors are documented on the [colors utilities page](../utilities/colors#border).
diff --git a/content/foundations/css-utilities/box-shadow.mdx b/content/foundations/css-utilities/box-shadow.mdx
@@ -0,0 +1,88 @@
+---
+title: Box shadow
+description: Box shadows are used to make content appear elevated. They are typically applied to containers of content that users need to pay attention to or content that appears on top of (overlapping) other elements on the page (like a pop-over or modal).
+---
+
+## Small
+
+Small shadows are mainly used on things that need to appear slightly elevated, like pricing cards or UI elements containing important information.
+
+<StorybookEmbed
+  framework="css"
+  componentId="utilities-shadow"
+  stories={{'small': {name: 'small'}}}
+  height="75"
+/>
+
+These types of shadows are typically applied to elements with borders, such as the [Box component](/components/box).
+
+<StorybookEmbed
+  framework="css"
+  componentId="utilities-shadow"
+  stories={{'small-example': {name: 'small-example'}}}
+  height="300"
+/>
+
+## Medium
+
+Medium box shadows are more diffused and slightly larger than small box shadows.
+
+<StorybookEmbed
+  framework="css"
+  componentId="utilities-shadow"
+  stories={{'medium': {name: 'medium'}}}
+  height="75"
+/>
+
+Medium box shadows are typically used on editorialized content that needs to appear elevated. Most of the time, the elements using this level of shadow will be clickable.
+
+<StorybookEmbed
+  framework="css"
+  componentId="utilities-shadow"
+  stories={{'medium-example': {name: 'medium-example'}}}
+  height="220"
+/>
+
+## Large
+
+Large box shadows are very diffused and used sparingly in the product UI.
+
+<StorybookEmbed
+  framework="css"
+  componentId="utilities-shadow"
+  stories={{'large': {name: 'large'}}}
+  height="75"
+/>
+
+These shadows are used for marketing content, UI screenshots, and content that appears on top of other page elements.
+
+<StorybookEmbed
+  framework="css"
+  componentId="utilities-shadow"
+  stories={{'large-example': {name: 'large-example'}}}
+  height="375"
+/>
+
+## Extra large
+
+Extra large box shadows are even more diffused.
+
+<StorybookEmbed
+  framework="css"
+  componentId="utilities-shadow"
+  stories={{'extra-large': {name: 'extra-large'}}}
+  height="75"
+/>
+
+These shadows are used for marketing content and content that appears on top of other page elements.
+
+## Remove a box shadow
+
+Additionally there is a `box-shadow-none` class that removes `box-shadow`:
+
+<StorybookEmbed
+  framework="css"
+  componentId="utilities-shadow"
+  stories={{'none': {name: 'none'}}}
+  height="75"
+/>
diff --git a/content/foundations/css-utilities/colors.mdx b/content/foundations/css-utilities/colors.mdx
@@ -0,0 +1,56 @@
+---
+title: Colors
+description: Use color utilities to apply color to the background of elements, text, and borders.
+---
+
+<Note>
+  Please note Primer CSS v18 has changed the naming of these color classes. Check the <a href="/css/support/v18-migration">migration guide</a> to make sure your app is up to date.
+</Note>
+
+These utilities should only be used where color is not provided by a component. To learn more about how to apply color, read the [color documentation](https://primer.style/design/foundations/color) in the [interface guidelines](https://primer.style/design/).
+
+## Text
+
+Use text color utilities to set text to a specific color. Color contrast must pass a minimum WCAG accessibility rating of [level AA](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html). This ensures that viewers who cannot see the full color spectrum are able to read the text. To customize outside of the suggested combinations below, we recommend using this [color contrast testing tool](https://colorable.jxnblk.com/). For more information, read our [accessibility standards](../principles/accessibility).
+
+<StorybookEmbed
+  framework="css"
+  componentId="utilities-color"
+  stories={{'text': {name: 'text'}}}
+  height="410"
+/>
+
+You can set the color inheritance on an element by using the `color-fg-inherit` class.
+
+<StorybookEmbed
+  framework="css"
+  componentId="utilities-color"
+  stories={{'text-inherit': {name: 'text-inherit'}}}
+  height="60"
+/>
+
+## Background
+
+Background colors are most commonly used for filling large blocks of content or areas with a color. When selecting a background color, make sure the foreground color contrast passes a minimum WCAG accessibility rating of [level AA](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html). Meeting these standards ensures that content is accessible by everyone, regardless of disability or user device. You can [check your color combination with this demo site](https://colorable.jxnblk.com/). For more information, read our [accessibility standards](../principles/accessibility).
+
+<StorybookEmbed
+  framework="css"
+  componentId="utilities-color"
+  stories={{'background': {name: 'background'}}}
+  height="1250"
+/>
+
+## Border
+
+Override default border colors with the following utilities.
+
+<StorybookEmbed
+  framework="css"
+  componentId="utilities-color"
+  stories={{'border': {name: 'border'}}}
+  height="1170"
+/>
+
+## Link
+
+You can use the [Link component](../components/links) to change the link colors.
diff --git a/content/foundations/css-utilities/details.mdx b/content/foundations/css-utilities/details.mdx
@@ -0,0 +1,53 @@
+---
+title: Details
+description: Details classes are created to enhance the native behaviors of details elements.
+---
+
+## Fullscreen click area
+
+Use `.details-overlay` to expand the click area of `<summary>` to cover the full screen, so user can click anywhere on a page to close `<details>`.
+
+<StorybookEmbed
+  framework="css"
+  componentId="utilities-details"
+  stories={{'overlay': {name: 'overlay'}}}
+  height="130"
+/>
+
+## Darkened fullscreen click area
+
+Use `.details-overlay-dark` darken the click area overlay. Useful for modals.
+
+<StorybookEmbed
+  framework="css"
+  componentId="utilities-details"
+  stories={{'overlay-dark': {name: 'overlay-dark'}}}
+  height="130"
+/>
+
+## Custom caret
+
+Use `.details-reset` to remove the default caret (that little triangle on the left). You then can add the `.dropdown-caret` on the right of the text.
+
+<StorybookEmbed
+  framework="css"
+  componentId="utilities-details"
+  stories={{'caret': {name: 'caret'}}}
+  height="130"
+/>
+
+## Using button styles with the details summary element
+
+You can add `.btn` and `.btn-*` classes to any
+[`<summary>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary)
+element so that it gains the appearance of a button, and
+selected/active styles when the parent
+[`<details>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details)
+element is open.
+
+<StorybookEmbed
+  framework="css"
+  componentId="utilities-details"
+  stories={{'summary': {name: 'summary'}}}
+  height="170"
+/>