Add border utilities (#1853)

Author: tylersticka

.changeset/rare-trainers-heal.md

@@ -0,0 +1,5 @@
+---
+'@cloudfour/patterns': minor
+---
+
+Add border utilities

src/base/_defaults.scss

@@ -181,11 +181,15 @@ del {
 /**
  * IE10 and earlier still show borders around linked images, and all browsers
  * still show borders around iframe elements by default.
+ *
+ * We set the `border-style` and `border-width` so that utility classes can
+ * easily set themed default colors.
  */
 
 iframe,
 img {
-  border-style: none;
+  border-style: solid;
+  border-width: 0;
 }
 
 /**

src/base/_themes.scss

@@ -16,8 +16,9 @@
   --theme-color-background-base: #{color.$text-light-emphasis};
   --theme-color-background-kbd: transparent;
   --theme-color-background-secondary: #{color.$base-gray-lighter};
-  --theme-color-border-kbd: #{color.$base-gray-light};
-  --theme-color-border-text-group: #{color.$base-gray-light};
+  --theme-color-border-base: #{color.$base-gray-light};
+  --theme-color-border-kbd: var(--theme-color-border-base);
+  --theme-color-border-text-group: var(--theme-color-border-base);
   --theme-color-text-action: #{color.$text-action};
   --theme-color-text-base: #{color.$text-dark};
   --theme-color-text-code: #{color.$base-fuchsia};
@@ -34,8 +35,9 @@
   --theme-color-background-base: #{color.$brand-primary};
   --theme-color-background-kbd: #{color.$brand-primary-dark};
   --theme-color-background-secondary: #{color.$brand-primary-dark};
-  --theme-color-border-kbd: #{color.$brand-primary-darker};
-  --theme-color-border-text-group: #{color.$brand-primary-darker};
+  --theme-color-border-base: #{color.$brand-primary-darker};
+  --theme-color-border-kbd: var(--theme-color-border-base);
+  --theme-color-border-text-group: var(--theme-color-border-base);
   --theme-color-text-action: var(--theme-color-text-emphasis);
   --theme-color-text-base: #{color.$text-light};
   --theme-color-text-code: var(--theme-color-text-emphasis);

src/utilities/border/border.scss

@@ -0,0 +1,33 @@
+@use '../../compiled/tokens/scss/size';
+
+/**
+ * To improve the convenience of using these classes without having to specify
+ * a border style and color every time, we use the `:where` selector to set some
+ * reasonable defaults with no specificity depth.
+ */
+
+:where([class^='u-border'], [class*=' u-border']) {
+  border-color: var(--theme-color-border-text-group);
+  border-style: solid;
+}
+
+/**
+ * Sizes
+ */
+
+.u-border,
+.u-border-small {
+  border-width: size.$edge-small !important;
+}
+
+.u-border-medium {
+  border-width: size.$edge-medium !important;
+}
+
+.u-border-large {
+  border-width: size.$edge-large !important;
+}
+
+.u-border-none {
+  border-width: 0 !important;
+}

src/utilities/border/border.stories.mdx

@@ -0,0 +1,53 @@
+import { Story, Canvas, Meta } from '@storybook/addon-docs';
+const borderStory = (args) => {
+  const classNames = [args.width || ''];
+  if (args.color) {
+    classNames.push(args.color);
+  }
+  const className = classNames
+    .map((segment) => (segment.length > 0 ? `u-border-${segment}` : 'u-border'))
+    .join(' ');
+  return `<div class="${className} u-pad-n1">${className}</div>`;
+};
+
+<Meta
+  title="Utilities/Border"
+  argTypes={{
+    width: {
+      options: ['small', 'medium', 'large', 'none'],
+      type: { name: 'enum' },
+      control: { type: 'inline-radio' },
+    },
+  }}
+/>
+
+# Border
+
+These utilities apply borders. They may be used to visually offset content from its surroundings. For example, a screenshot in an article with a white background might blend in too much with the page without a border.
+
+## Sizes
+
+Available sizes are based on [our `size.$edge-` tokens](/?path=/docs/design-tokens-size--page#edge):
+
+- `u-border` or `u-border-small`
+- `u-border-medium`
+- `u-border-large`
+
+<Canvas>
+  <Story name="Small (Default)">{(args) => borderStory(args)}</Story>
+  <Story name="Medium" args={{ width: 'medium' }}>
+    {(args) => borderStory(args)}
+  </Story>
+  <Story name="Large" args={{ width: 'large' }}>
+    {(args) => borderStory(args)}
+  </Story>
+  <Story name="None" args={{ width: 'none' }}>
+    {(args) => borderStory(args)}
+  </Story>
+</Canvas>
+
+## Color and style
+
+If no `border-color` is set, these utilities will use the default border color of the current [theme](/?path=/docs/design-themes--light). If no `border-style` is set, the utility will use `solid`.
+
+We may add specific color and style utilities in the future as the need arises.