docs(box): add documentation to dev and staging

config/styleguide.config.js

@@ -125,6 +125,14 @@ module.exports = {
     {
       name: 'Components',
       sections: [
+        {
+          name: 'Layout',
+          components() {
+            return compact([
+              toggleByEnv('Box', path.resolve('src/components/Box/Box.jsx'), undefined),
+            ])
+          },
+        },
         {
           name: 'Grid',
           components() {

src/components/Box/Box.jsx

@@ -23,6 +23,9 @@ const getBetweenClasses = betweenSize => {
   return styles[`betweenBottomMargin-${betweenSize}`]
 }
 
+/**
+ * Box - apply spacing within or around components
+ */
 const Box = ({
   inline,
   tag,
@@ -67,16 +70,49 @@ const Box = ({
 }
 
 Box.propTypes = {
+  /**
+   * If `true`, render a `<span>` instead of `<div>`.
+   */
   inline: PropTypes.bool,
+  /**
+   *
+   */
   tag: PropTypes.string,
+  /**
+   * Sets a `padding-top` and `padding-bottom`.
+   */
   vertical: PropTypes.oneOf([1, 2, 3, 4, 6]),
+  /**
+   * Sets a `padding-left` and `padding-right`.
+   */
   horizontal: PropTypes.oneOf([1, 2, 3, 4, 6]),
+  /**
+   * Sets `padding` on all four sides.
+   */
   inset: PropTypes.oneOf([1, 2, 3, 4, 6]),
+  /**
+   * Sets a `margin-bottom`.
+   */
   below: PropTypes.oneOf([1, 2, 3, 4, 5, 6, 7, 8]),
+  /**
+   * Sets a `margin-right`.
+   */
   right: PropTypes.oneOf([1, 2, 3, 4, 6]),
+  /**
+   * Sets a `margin-left`.
+   */
   left: PropTypes.oneOf([1, 2, 3, 4, 6]),
+  /**
+   * Sets a `margin-bottom` to all direct children except the last. If the `inline` prop is set to `true`, this sets a `margin-right` to all direct children except the last.
+   */
   between: PropTypes.oneOf([1, 2, 3, 4, 5, 6, 7, 8]),
+  /**
+   * Append custom classes to `className`.
+   */
   dangerouslyAddClassName: PropTypes.string,
+  /**
+   * The content. Can be text, any HTML element, or any component.
+   */
   children: PropTypes.node.isRequired,
 }
 

src/components/Box/Box.md

@@ -1,3 +1,42 @@
+```jsx
+<Card>
+  <Box below={3}>
+    <Heading level="h1">Our latest and greatest</Heading>
+  </Box>
+  <Box below={3}>
+    <Paragraph>Everything you would expect, without conditions.</Paragraph>
+  </Box>
+  <ButtonLink href="//telus.com">Learn more</ButtonLink>
+</Card>
 ```
-<Box/>
+
+## Spacing matrix
+
+The Box component contains props that accept values from `1` to `8`. These numbered values correspond to our spacing system. Numbers `4` and above feature responsive spacing, as detailed in this table:
+
+| Number | Default value | Value in viewports above or equal to `768px` | 
+| ------ | ------------: | -------------------------------------------: |
+| 1 | 0.25rem | _unchanged_ |
+| 2 | 0.5rem | _unchanged_ |
+| 3 | 1rem | _unchanged_ |
+| 4 | 1.5rem | 2rem |
+| 5 | 2rem | 3rem |
+| 6 | 2.5rem | 4rem |
+| 7 | 3rem | 4.5rem |
+| 8 | 4rem | 6rem |
+
+### Usage tips
+
+- Numbers `1` to `3` are suitable for spacing inline content such as [Typography](#typography), [Button](#button), and [ButtonLink](#buttonlink) components
+- Numbers `4` to `8` are suitable for spacing major types of content, usually with the `below` prop wrapping [Cards](#card) and [Dividers](#dividers)
+- Numbers `5`, `7`, and `8` are exclusively used to separating blocks vertically
+
+### Example separating blocks
+
+```jsx noeditor static
+<Box el="section" below={5} inset={4}>
+  <Box below={3}>
+    <Heading level="h2">Lots to discover</Heading>
+  </Box>
+</Box>
 ```