instructure · balzss · Dec 12, 2024
diff --git a/docs/contributor-docs/v10-upgrade-guide.md b/docs/contributor-docs/v10-upgrade-guide.md
@@ -1,7 +1,7 @@
 ---
 title: Upgrade Guide for Version 10.0
 category: Guides
-order: 7
+order: 98
 ---
 
 # Upgrade Guide for Version 10

diff --git a/docs/guides/layout-spacing.md b/docs/guides/layout-spacing.md
@@ -0,0 +1,96 @@
+---
+title: Layout Spacing
+category: Guides
+order: 8
+---
+
+# Layout Spacing
+
+Our design system provides a set of spacing tokens for consistent layouts and components. Some tokens share values but should be used semantically. For instance, while both `tags` and `buttons` are 0.75rem, `buttons` should be used for spacing between buttons.
+
+## Tokens
+
+| Key               | Value    | Value in pixels |
+| ----------------- | -------- | --------------- |
+| space0            | 0rem     | 0px             |
+| space2            | 0.125rem | 2px             |
+| space4            | 0.25rem  | 4px             |
+| space8            | 0.5rem   | 8px             |
+| space12           | 0.75rem  | 12px            |
+| space16           | 1rem     | 16px            |
+| space24           | 1.5rem   | 24px            |
+| space36           | 2.25rem  | 36px            |
+| space48           | 3rem     | 48px            |
+| space60           | 3.75rem  | 60px            |
+| sections          | 2.25rem  | 36px            |
+| sectionElements   | 1.5em    | 24px            |
+| trayElements      | 1.5em    | 24px            |
+| modalElements     | 1.5em    | 24px            |
+| moduleElements    | 1em      | 16px            |
+| paddingCardLarge  | 1.5rem   | 24px            |
+| paddingCardMedium | 1rem     | 16px            |
+| paddingCardSmall  | 0.75rem  | 12px            |
+| selects           | 1rem     | 16px            |
+| textAreas         | 1rem     | 16px            |
+| inputFields       | 1rem     | 16px            |
+| checkboxes        | 1rem     | 16px            |
+| radios            | 1rem     | 16px            |
+| toggles           | 1rem     | 16px            |
+| buttons           | 0.75rem  | 12px            |
+| tags              | 0.75rem  | 12px            |
+| statusIndicators  | 0.75rem  | 12px            |
+| dataPoints        | 0.75rem  | 12px            |
+
+## Applying Spacing
+
+There are three main ways to apply spacing in our component library:
+
+### 1. Using the `margin` Prop
+
+Most components in the library support a `margin` prop that works similarly to the CSS margin property. You can specify a single value or fine-tune individual margins (e.g., top, right, bottom, left).
+
+```ts
+---
+type: example
+---
+<div>
+  <Button margin="0 buttons 0 0">Button 1</Button>
+  <Button>Button 2</Button>
+</div>
+```
+
+### 2. Using a Container Component with the `gap` Prop
+
+For layouts, container components like `Flex` and `Grid` can be used with the gap prop to manage spacing between child elements.
+
+```ts
+---
+type: example
+---
+<Flex gap="buttons">
+  <Button>Button 1</Button>
+  <Button>Button 2</Button>
+</Flex>
+```
+
+### 3. Importing Values from the Theme
+
+If you need to directly reference spacing values, you can import them from the theme. This approach is useful for applying spacing in inline styles or custom components.
+
+```ts
+---
+type: code
+---
+// import the canvas theme
+import canvas from '@instructure/ui-themes'
+
+// use spacing values
+<div style={{display: 'flex', gap: canvas.spacing.buttons}}>
+  <button>Button 1</button>
+  <button>Button 2</button>
+</div>
+```
+
+## Legacy tokens
+
+For compatibility reasons we still provide the legacy spacing tokens (`xxLarge`, `medium`, etc.) so old layouts don't break when updating InstUI but these tokens shouldn't be used when creating new layouts.
diff --git a/packages/__docs__/src/ComponentTheme/index.tsx b/packages/__docs__/src/ComponentTheme/index.tsx
@@ -29,8 +29,6 @@ import { withStyle, jsx } from '@instructure/emotion'
 import { Table } from '@instructure/ui-table'
 import { View } from '@instructure/ui-view'
 
-import type { BaseColors } from '@instructure/shared-types'
-
 import { ColorSwatch } from '../ColorSwatch'
 
 import generateStyle from './styles'
@@ -42,51 +40,49 @@ class ComponentTheme extends Component<ComponentThemeProps> {
   static propTypes = propTypes
   static allowedProps = allowedProps
 
-  mapColors(colorKey: BaseColors) {
-    const map: Record<string, string> = {}
-    ;(Object.keys(colorKey) as Array<keyof BaseColors>).forEach((color) => {
-      const hex = colorKey[color]
-      if (typeof map[hex] === 'undefined') {
-        map[hex] = color
-      }
-    })
-    return map
+  renderValueCell(
+    value: undefined | string | object | number,
+    colorPrimitives: object
+  ) {
+    if (!value) {
+      return <code>$aposundefined$apos</code>
+    }
+    if (typeof value === 'object') {
+      return <code>{JSON.stringify(value)}</code>
+    }
+    if (typeof value === 'object') {
+      return <code>{JSON.stringify(value)}</code>
+    }
+    if (
+      value.toString().charAt(0) === '#' ||
+      value.toString().substring(0, 3) === 'rgb'
+    ) {
+      // find color primitive name from hex value
+      const color = Object.entries(colorPrimitives).find(([, v]) => v === value)
+      return (
+        <span>
+          <View margin="0 xx-small 0 0">
+            <ColorSwatch color={value} />
+          </View>
+          <code>{color?.[0] ?? value}</code>
+        </span>
+      )
+    }
+    return <code>{value}</code>
   }
 
   renderRows() {
     const { componentTheme, themeVariables } = this.props
-    const colorKey = themeVariables.colors.values
-      ? themeVariables.colors.values
-      : themeVariables.colors
-    const map = this.mapColors(colorKey)
+    const colorPrimitives = themeVariables.colors.primitives
 
     return Object.keys(componentTheme).map((name) => {
-      const value = componentTheme[name] || 'undefined'
-      const color = value.toString().charAt(0) === '#' ? map[value] : null
-
       return (
         <Table.Row key={name}>
           <Table.Cell>
             <code>{name}</code>
           </Table.Cell>
           <Table.Cell>
-            {value.toString().charAt(0) === '#' ? (
-              <span>
-                <View margin="0 xx-small 0 0">
-                  <ColorSwatch color={value} />
-                </View>
-                <code>{color}</code>
-              </span>
-            ) : value.toString().substring(0, 3) === 'rgb' ? (
-              <span>
-                <View margin="0 xx-small 0 0">
-                  <ColorSwatch color={value} />
-                </View>
-                <code>{value}</code>
-              </span>
-            ) : (
-              <code>{value}</code>
-            )}
+            {this.renderValueCell(componentTheme[name], colorPrimitives)}
           </Table.Cell>
         </Table.Row>
       )

diff --git a/packages/__examples__/.storybook/stories/MarginProp.tsx b/packages/__examples__/.storybook/stories/MarginProp.tsx
@@ -0,0 +1,60 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import React from 'react'
+import {
+  Button,
+  ColorPicker,
+  TextInput,
+  TextArea,
+  NumberInput,
+  DateInput2
+} from '@instructure/ui'
+
+function MarginProp() {
+  return (
+    <div>
+      <Button margin="space12">hello</Button>
+      <TextInput margin="space12" />
+      <TextArea margin="space12" label="label" />
+      <NumberInput margin="space12" renderLabel="label" />
+      <ColorPicker
+        placeholderText="placeholder"
+        label="label"
+        margin="space12"
+      />
+      <DateInput2
+        margin="space12"
+        renderLabel="label"
+        screenReaderLabels={{
+          calendarIcon: 'asdf',
+          prevMonthButton: 'asdf',
+          nextMonthButton: 'asdf'
+        }}
+      />
+    </div>
+  )
+}
+
+export default MarginProp
diff --git a/packages/__examples__/.storybook/stories/SpacingTokens.tsx b/packages/__examples__/.storybook/stories/SpacingTokens.tsx
@@ -0,0 +1,71 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import React from 'react'
+import { Button } from '@instructure/ui'
+
+function SpacingTokens() {
+  const spaceTokens = [
+    'space0',
+    'space2',
+    'space4',
+    'space8',
+    'space12',
+    'space16',
+    'space24',
+    'space36',
+    'space48',
+    'space60',
+    'sections',
+    'sectionElrements',
+    'trayElrements',
+    'modalElrements',
+    'moduleElrements',
+    'paddingCardLarge',
+    'paddingCardMedium',
+    'paddingCardSmall',
+    'selects',
+    'textareas',
+    'inputFields',
+    'checkboxes',
+    'radios',
+    'toggles',
+    'buttons',
+    'tags',
+    'statusIndicators',
+    'dataPoints'
+  ]
+
+  return (
+    <div>
+      {spaceTokens.map((token) => (
+        <Button margin={token} key={token}>
+          {token}
+        </Button>
+      ))}
+    </div>
+  )
+}
+
+export default SpacingTokens
diff --git a/packages/__examples__/.storybook/stories/stories.ts b/packages/__examples__/.storybook/stories/stories.ts
@@ -36,6 +36,8 @@ import { renderPage } from './renderPage'
 import propJSONData from '../../prop-data.json'
 import TooltipPositioning from './TooltipPositioning'
 import FormErrors from './FormErrors'
+import SpacingTokens from './SpacingTokens'
+import MarginProp from './MarginProp'
 import SourceCodeEditorExamples from './SourceCodeEditorExamples'
 
 type AdditionalExample = {
@@ -78,6 +80,24 @@ const additionalExamples: AdditionalExample[] = [
       }
     ]
   },
+  {
+    title: 'Spacing tokens',
+    stories: [
+      {
+        storyName: 'Spacing tokens',
+        storyFn: () => SpacingTokens()
+      }
+    ]
+  },
+  {
+    title: 'Margin prop',
+    stories: [
+      {
+        storyName: 'Margin prop',
+        storyFn: () => MarginProp()
+      }
+    ]
+  },
   // TODO: try to fix the editor not rendering fully on chromatic screenshot,
   //  even with delay
   {