From 2332fd61c2b40a2ec58d59f4d0e3e0072c7ae89e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bal=C3=A1zs=20S=C3=A1ros?= <balazs.saros@instructure.com>
Date: Thu, 12 Dec 2024 20:11:05 +0100
Subject: [PATCH] feat(many): introduce new spacing tokens; add margin prop for
 more components

---
 docs/contributor-docs/v10-upgrade-guide.md    |  2 +-
 docs/guides/layout-spacing.md                 | 96 +++++++++++++++++++
 .../.storybook/stories/MarginProp.tsx         | 60 ++++++++++++
 .../.storybook/stories/SpacingTokens.tsx      | 71 ++++++++++++++
 .../.storybook/stories/stories.ts             | 10 ++
 .../src/styleUtils/ThemeablePropValues.ts     | 37 ++++++-
 .../ui-color-picker/src/ColorPicker/index.tsx | 14 ++-
 .../ui-color-picker/src/ColorPicker/props.ts  | 17 +++-
 .../ui-date-input/src/DateInput2/index.tsx    |  4 +-
 .../ui-date-input/src/DateInput2/props.ts     | 10 +-
 .../ui-form-field/src/FormField/index.tsx     |  1 +
 packages/ui-form-field/src/FormField/props.ts | 12 ++-
 .../src/FormFieldLayout/index.tsx             |  3 +-
 .../src/FormFieldLayout/props.ts              | 17 +++-
 .../src/FormFieldLayout/styles.ts             |  9 +-
 .../src/FormFieldLayout/theme.ts              | 33 +++++++
 .../ui-number-input/src/NumberInput/index.tsx |  4 +-
 .../ui-number-input/src/NumberInput/props.ts  | 16 +++-
 packages/ui-text-area/src/TextArea/index.tsx  |  4 +-
 packages/ui-text-area/src/TextArea/props.ts   | 17 +++-
 .../ui-text-input/src/TextInput/index.tsx     |  1 +
 packages/ui-text-input/src/TextInput/props.ts | 17 +++-
 .../src/sharedThemeTokens/spacing.ts          | 33 ++++++-
 23 files changed, 453 insertions(+), 35 deletions(-)
 create mode 100644 docs/guides/layout-spacing.md
 create mode 100644 packages/__examples__/.storybook/stories/MarginProp.tsx
 create mode 100644 packages/__examples__/.storybook/stories/SpacingTokens.tsx
 create mode 100644 packages/ui-form-field/src/FormFieldLayout/theme.ts

diff --git a/docs/contributor-docs/v10-upgrade-guide.md b/docs/contributor-docs/v10-upgrade-guide.md
index 2f9590c4d2..085a462f05 100644
--- 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
new file mode 100644
index 0000000000..4a83f4df86
--- /dev/null
+++ 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/__examples__/.storybook/stories/MarginProp.tsx b/packages/__examples__/.storybook/stories/MarginProp.tsx
new file mode 100644
index 0000000000..5575a95f67
--- /dev/null
+++ 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
new file mode 100644
index 0000000000..f7ee5590f2
--- /dev/null
+++ 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
index d9b6c7df28..13a1f69b70 100644
--- a/packages/__examples__/.storybook/stories/stories.ts
+++ b/packages/__examples__/.storybook/stories/stories.ts
@@ -36,6 +36,7 @@ import { renderPage } from './renderPage'
 import propJSONData from '../../prop-data.json'
 import TooltipPositioning from './TooltipPositioning'
 import FormErrors from './FormErrors'
+import SpacingTokens from './SpacingTokens'
 import SourceCodeEditorExamples from './SourceCodeEditorExamples'
 
 type AdditionalExample = {
@@ -78,6 +79,15 @@ const additionalExamples: AdditionalExample[] = [
       }
     ]
   },
+  {
+    title: 'Spacing tokens',
+    stories: [
+      {
+        storyName: 'Spacing tokens',
+        storyFn: () => SpacingTokens()
+      }
+    ]
+  },
   // TODO: try to fix the editor not rendering fully on chromatic screenshot,
   //  even with delay
   {
diff --git a/packages/emotion/src/styleUtils/ThemeablePropValues.ts b/packages/emotion/src/styleUtils/ThemeablePropValues.ts
index 9becdbcf47..f55e32ed95 100644
--- a/packages/emotion/src/styleUtils/ThemeablePropValues.ts
+++ b/packages/emotion/src/styleUtils/ThemeablePropValues.ts
@@ -89,9 +89,40 @@ const ThemeablePropValues = {
 } as const
 
 // SPACING
-type SpacingKeys = keyof typeof ThemeablePropValues.SPACING
-type SpacingValues = (typeof ThemeablePropValues.SPACING)[SpacingKeys]
-type Spacing = CSSShorthandValue<SpacingValues>
+type OldSpacingKeys = keyof typeof ThemeablePropValues.SPACING
+type OldSpacingValues = (typeof ThemeablePropValues.SPACING)[OldSpacingKeys]
+type NewSpacingValues =
+  | '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'
+type SpacingValues = OldSpacingValues | NewSpacingValues
+// adding `(string & {})` allows to use any string while still allowing specific string values to be suggested by IDEs
+type Spacing = SpacingValues | (string & {})
 
 // SHADOW_TYPES
 type ShadowKeys = keyof typeof ThemeablePropValues.SHADOW_TYPES
diff --git a/packages/ui-color-picker/src/ColorPicker/index.tsx b/packages/ui-color-picker/src/ColorPicker/index.tsx
index 9a450c5de1..a8cb6337f2 100644
--- a/packages/ui-color-picker/src/ColorPicker/index.tsx
+++ b/packages/ui-color-picker/src/ColorPicker/index.tsx
@@ -399,7 +399,15 @@ class ColorPicker extends Component<ColorPickerProps, ColorPickerState> {
             }}
           >
             <Tooltip renderTip={<span aria-hidden={true}>{tooltip}</span>}>
-              <IconButton withBackground={false} withBorder={false} screenReaderLabel={tooltip} size="small" shape="circle" width="auto" renderIcon={IconInfoLine}/>
+              <IconButton
+                withBackground={false}
+                withBorder={false}
+                screenReaderLabel={tooltip}
+                size="small"
+                shape="circle"
+                width="auto"
+                renderIcon={IconInfoLine}
+              />
             </Tooltip>
           </InstUISettingsProvider>
         </span>
@@ -602,7 +610,8 @@ class ColorPicker extends Component<ColorPickerProps, ColorPickerState> {
   )
 
   render() {
-    const { disabled, isRequired, placeholderText, width, id } = this.props
+    const { disabled, isRequired, placeholderText, width, id, margin } =
+      this.props
 
     return (
       <div
@@ -627,6 +636,7 @@ class ColorPicker extends Component<ColorPickerProps, ColorPickerState> {
           onPaste={(event) => this.handleOnPaste(event)}
           onBlur={() => this.handleOnBlur()}
           messages={this.renderMessages()}
+          margin={margin}
         />
         {!this.isSimple && (
           <div
diff --git a/packages/ui-color-picker/src/ColorPicker/props.ts b/packages/ui-color-picker/src/ColorPicker/props.ts
index 0cd93de8f9..923333d0ab 100644
--- a/packages/ui-color-picker/src/ColorPicker/props.ts
+++ b/packages/ui-color-picker/src/ColorPicker/props.ts
@@ -26,7 +26,11 @@ import React from 'react'
 import PropTypes from 'prop-types'
 
 import type { FormMessage } from '@instructure/ui-form-field'
-import type { WithStyleProps, ComponentStyle } from '@instructure/emotion'
+import type {
+  WithStyleProps,
+  ComponentStyle,
+  Spacing
+} from '@instructure/emotion'
 import type {
   ColorPickerTheme,
   OtherHTMLAttributes,
@@ -225,6 +229,11 @@ type ColorPickerOwnProps = {
    * If true, alpha slider will be rendered. Defaults to false
    */
   withAlpha?: boolean
+
+  /**
+   * Margin around the component. Accepts a `Spacing` token. See token values and example usage in [this guide](https://instructure.design/#layout-spacing).
+   */
+  margin?: Spacing
 }
 
 type ColorPickerState = {
@@ -316,7 +325,8 @@ const propTypes: PropValidators<PropKeys> = {
   id: PropTypes.string,
   value: PropTypes.string,
   width: PropTypes.string,
-  withAlpha: PropTypes.bool
+  withAlpha: PropTypes.bool,
+  margin: PropTypes.string
 }
 
 const allowedProps: AllowedPropKeys = [
@@ -339,7 +349,8 @@ const allowedProps: AllowedPropKeys = [
   'tooltip',
   'value',
   'width',
-  'withAlpha'
+  'withAlpha',
+  'margin'
 ]
 
 export type {
diff --git a/packages/ui-date-input/src/DateInput2/index.tsx b/packages/ui-date-input/src/DateInput2/index.tsx
index df5803ad9a..d6b1a3c408 100644
--- a/packages/ui-date-input/src/DateInput2/index.tsx
+++ b/packages/ui-date-input/src/DateInput2/index.tsx
@@ -153,7 +153,7 @@ const DateInput2 = ({
   dateFormat,
   onRequestValidateDate,
   renderCalendarIcon,
-  // margin, TODO enable this prop
+  margin,
   ...rest
 }: DateInput2Props) => {
   const localeContext = useContext(ApplyLocaleContext)
@@ -278,7 +278,6 @@ const DateInput2 = ({
   return (
     <TextInput
       {...passthroughProps(rest)}
-      // margin={'large'} TODO add this prop to TextInput
       renderLabel={renderLabel}
       onChange={handleInputChange}
       onBlur={handleBlur}
@@ -289,6 +288,7 @@ const DateInput2 = ({
       display={isInline ? 'inline-block' : 'block'}
       messages={inputMessages}
       interaction={interaction}
+      margin={margin}
       renderAfterInput={
         <Popover
           renderTrigger={
diff --git a/packages/ui-date-input/src/DateInput2/props.ts b/packages/ui-date-input/src/DateInput2/props.ts
index f1ba27ab01..c7307510ca 100644
--- a/packages/ui-date-input/src/DateInput2/props.ts
+++ b/packages/ui-date-input/src/DateInput2/props.ts
@@ -33,6 +33,7 @@ import type {
   Renderable,
   PropValidators
 } from '@instructure/shared-types'
+import type { Spacing } from '@instructure/emotion'
 
 type DateInput2OwnProps = {
   /**
@@ -164,12 +165,16 @@ type DateInput2OwnProps = {
     value: string,
     utcDateString: string
   ) => void
-  // margin?: Spacing // TODO enable this prop
 
   /**
    * Custom icon for the icon button opening the picker.
    */
   renderCalendarIcon?: Renderable
+
+  /**
+   * Margin around the component. Accepts a `Spacing` token. See token values and example usage in [this guide](https://instructure.design/#layout-spacing).
+   */
+  margin?: Spacing
 }
 
 type PropKeys = keyof DateInput2OwnProps
@@ -201,7 +206,8 @@ const propTypes: PropValidators<PropKeys> = {
   withYearPicker: PropTypes.object,
   dateFormat: PropTypes.oneOfType([PropTypes.string, PropTypes.object]),
   onRequestValidateDate: PropTypes.func,
-  renderCalendarIcon: PropTypes.oneOfType([PropTypes.node, PropTypes.func])
+  renderCalendarIcon: PropTypes.oneOfType([PropTypes.node, PropTypes.func]),
+  margin: PropTypes.string
 }
 
 export type { DateInput2Props }
diff --git a/packages/ui-form-field/src/FormField/index.tsx b/packages/ui-form-field/src/FormField/index.tsx
index b97bd66202..a5cfe3cfa3 100644
--- a/packages/ui-form-field/src/FormField/index.tsx
+++ b/packages/ui-form-field/src/FormField/index.tsx
@@ -70,6 +70,7 @@ class FormField extends Component<FormFieldProps> {
         as="label"
         htmlFor={this.props.id}
         elementRef={this.handleRef}
+        margin={this.props.margin}
       />
     )
   }
diff --git a/packages/ui-form-field/src/FormField/props.ts b/packages/ui-form-field/src/FormField/props.ts
index 81dc172264..b02e3bc691 100644
--- a/packages/ui-form-field/src/FormField/props.ts
+++ b/packages/ui-form-field/src/FormField/props.ts
@@ -32,6 +32,7 @@ import type {
   PropValidators
 } from '@instructure/shared-types'
 import type { FormMessage } from '../FormPropTypes'
+import type { Spacing } from '@instructure/emotion'
 
 type FormFieldOwnProps = {
   label: React.ReactNode
@@ -62,6 +63,11 @@ type FormFieldOwnProps = {
    * provides a reference to the underlying html root element
    */
   elementRef?: (element: Element | null) => void
+
+  /**
+   * Margin around the component. Accepts a `Spacing` token. See token values and example usage in [this guide](https://instructure.design/#layout-spacing).
+   */
+  margin?: Spacing
 }
 
 type PropKeys = keyof FormFieldOwnProps
@@ -82,7 +88,8 @@ const propTypes: PropValidators<PropKeys> = {
   vAlign: PropTypes.oneOf(['top', 'middle', 'bottom']),
   width: PropTypes.string,
   inputContainerRef: PropTypes.func,
-  elementRef: PropTypes.func
+  elementRef: PropTypes.func,
+  margin: PropTypes.string
 }
 
 const allowedProps: AllowedPropKeys = [
@@ -97,7 +104,8 @@ const allowedProps: AllowedPropKeys = [
   'vAlign',
   'width',
   'inputContainerRef',
-  'elementRef'
+  'elementRef',
+  'margin'
 ]
 
 export type { FormFieldOwnProps, FormFieldProps }
diff --git a/packages/ui-form-field/src/FormFieldLayout/index.tsx b/packages/ui-form-field/src/FormFieldLayout/index.tsx
index 13de6eaa07..37b2d160fe 100644
--- a/packages/ui-form-field/src/FormFieldLayout/index.tsx
+++ b/packages/ui-form-field/src/FormFieldLayout/index.tsx
@@ -44,6 +44,7 @@ import generateStyle from './styles'
 
 import { propTypes, allowedProps } from './props'
 import type { FormFieldLayoutProps } from './props'
+import generateComponentTheme from './theme'
 
 /**
 ---
@@ -51,7 +52,7 @@ parent: FormField
 ---
 **/
 @withDeterministicId()
-@withStyle(generateStyle, null)
+@withStyle(generateStyle, generateComponentTheme)
 class FormFieldLayout extends Component<FormFieldLayoutProps> {
   static readonly componentId = 'FormFieldLayout'
 
diff --git a/packages/ui-form-field/src/FormFieldLayout/props.ts b/packages/ui-form-field/src/FormFieldLayout/props.ts
index 837443e7e5..cf2b414279 100644
--- a/packages/ui-form-field/src/FormFieldLayout/props.ts
+++ b/packages/ui-form-field/src/FormFieldLayout/props.ts
@@ -31,7 +31,11 @@ import type {
   OtherHTMLAttributes,
   PropValidators
 } from '@instructure/shared-types'
-import type { WithStyleProps, ComponentStyle } from '@instructure/emotion'
+import type {
+  WithStyleProps,
+  ComponentStyle,
+  Spacing
+} from '@instructure/emotion'
 import type { FormMessage } from '../FormPropTypes'
 import type { WithDeterministicIdProps } from '@instructure/ui-react-utils'
 
@@ -68,6 +72,11 @@ type FormFieldLayoutOwnProps = {
    */
   elementRef?: (element: Element | null) => void
   isGroup?: boolean
+
+  /**
+   * Margin around the component. Accepts a `Spacing` token. See token values and example usage in [this guide](https://instructure.design/#layout-spacing).
+   */
+  margin?: Spacing
 }
 
 type PropKeys = keyof FormFieldLayoutOwnProps
@@ -97,7 +106,8 @@ const propTypes: PropValidators<PropKeys> = {
   width: PropTypes.string,
   inputContainerRef: PropTypes.func,
   elementRef: PropTypes.func,
-  isGroup: PropTypes.bool
+  isGroup: PropTypes.bool,
+  margin: PropTypes.string
 }
 
 const allowedProps: AllowedPropKeys = [
@@ -112,7 +122,8 @@ const allowedProps: AllowedPropKeys = [
   'labelAlign',
   'width',
   'inputContainerRef',
-  'elementRef'
+  'elementRef',
+  'margin'
 
   // added vAlign because FormField and FormFieldGroup passes it, but not adding
   // it to allowedProps to prevent it from getting passed through accidentally
diff --git a/packages/ui-form-field/src/FormFieldLayout/styles.ts b/packages/ui-form-field/src/FormFieldLayout/styles.ts
index 542ad8e95d..d43ede2436 100644
--- a/packages/ui-form-field/src/FormFieldLayout/styles.ts
+++ b/packages/ui-form-field/src/FormFieldLayout/styles.ts
@@ -35,21 +35,22 @@ import type { FormFieldLayoutProps, FormFieldLayoutStyle } from './props'
  * @return {Object} The final style object, which will be used in the component
  */
 const generateStyle = (
-  _componentTheme: null,
+  componentTheme: any,
   props: FormFieldLayoutProps
 ): FormFieldLayoutStyle => {
-  const { inline } = props
+  const { inline, margin } = props
+  const { spacing } = componentTheme
 
   return {
     groupErrorMessage: {
-      margin: '0.5rem 0',
+      margin: '0.5rem 0'
     },
     formFieldLayout: {
       label: 'formFieldLayout',
       all: 'initial',
       border: '0',
       padding: '0',
-      margin: '0',
+      margin: margin ? spacing[margin] : '0',
       minWidth: '0',
       direction: 'inherit',
       textAlign: 'start',
diff --git a/packages/ui-form-field/src/FormFieldLayout/theme.ts b/packages/ui-form-field/src/FormFieldLayout/theme.ts
new file mode 100644
index 0000000000..6a7a7a6807
--- /dev/null
+++ b/packages/ui-form-field/src/FormFieldLayout/theme.ts
@@ -0,0 +1,33 @@
+/*
+ * 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 type { Theme } from '@instructure/ui-themes'
+
+const generateComponentTheme = (theme: Theme): any => {
+  const { spacing } = theme
+
+  return { spacing }
+}
+
+export default generateComponentTheme
diff --git a/packages/ui-number-input/src/NumberInput/index.tsx b/packages/ui-number-input/src/NumberInput/index.tsx
index 703cecd52d..df16136d59 100644
--- a/packages/ui-number-input/src/NumberInput/index.tsx
+++ b/packages/ui-number-input/src/NumberInput/index.tsx
@@ -248,7 +248,8 @@ class NumberInput extends Component<NumberInputProps, NumberInputState> {
       width,
       styles,
       allowStringValue,
-      renderIcons
+      renderIcons,
+      margin
     } = this.props
 
     const { interaction } = this
@@ -278,6 +279,7 @@ class NumberInput extends Component<NumberInputProps, NumberInputState> {
         inline={display === 'inline-block'}
         id={this.id}
         elementRef={this.handleRef}
+        margin={margin}
       >
         <span
           css={this.props.styles?.inputWidth}
diff --git a/packages/ui-number-input/src/NumberInput/props.ts b/packages/ui-number-input/src/NumberInput/props.ts
index 38b190d2eb..609b43be70 100644
--- a/packages/ui-number-input/src/NumberInput/props.ts
+++ b/packages/ui-number-input/src/NumberInput/props.ts
@@ -34,7 +34,11 @@ import type {
   OtherHTMLAttributes,
   PickPropsWithExceptions
 } from '@instructure/shared-types'
-import type { WithStyleProps, ComponentStyle } from '@instructure/emotion'
+import type {
+  WithStyleProps,
+  ComponentStyle,
+  Spacing
+} from '@instructure/emotion'
 import type { FormFieldOwnProps, FormMessage } from '@instructure/ui-form-field'
 import type {
   InteractionType,
@@ -174,6 +178,10 @@ type NumberInputOwnProps = {
     increase: Renderable
     decrease: Renderable
   }
+  /**
+   * Margin around the component. Accepts a `Spacing` token. See token values and example usage in [this guide](https://instructure.design/#layout-spacing).
+   */
+  margin?: Spacing
 }
 
 type NumberInputState = {
@@ -238,7 +246,8 @@ const propTypes: PropValidators<PropKeys> = {
   renderIcons: PropTypes.shape({
     increase: PropTypes.oneOfType([PropTypes.node, PropTypes.func]).isRequired,
     decrease: PropTypes.oneOfType([PropTypes.node, PropTypes.func]).isRequired
-  })
+  }),
+  margin: PropTypes.string
 }
 
 const allowedProps: AllowedPropKeys = [
@@ -263,7 +272,8 @@ const allowedProps: AllowedPropKeys = [
   'inputMode',
   'textAlign',
   'allowStringValue',
-  'renderIcons'
+  'renderIcons',
+  'margin'
 ]
 
 export type {
diff --git a/packages/ui-text-area/src/TextArea/index.tsx b/packages/ui-text-area/src/TextArea/index.tsx
index 942b5c0319..6d11a4dfab 100644
--- a/packages/ui-text-area/src/TextArea/index.tsx
+++ b/packages/ui-text-area/src/TextArea/index.tsx
@@ -315,7 +315,8 @@ class TextArea extends Component<TextAreaProps> {
       maxHeight,
       textareaRef,
       resize,
-      styles
+      styles,
+      margin
     } = this.props
 
     const props = omitProps(this.props, TextArea.allowedProps)
@@ -380,6 +381,7 @@ class TextArea extends Component<TextAreaProps> {
         elementRef={(el) => {
           this.ref = el
         }}
+        margin={margin}
       >
         <div
           css={this.props.styles?.textAreaLayout}
diff --git a/packages/ui-text-area/src/TextArea/props.ts b/packages/ui-text-area/src/TextArea/props.ts
index 771f0bed0b..4de5e0376a 100644
--- a/packages/ui-text-area/src/TextArea/props.ts
+++ b/packages/ui-text-area/src/TextArea/props.ts
@@ -36,7 +36,11 @@ import type {
   PickPropsWithExceptions
 } from '@instructure/shared-types'
 import type { FormMessage, FormFieldOwnProps } from '@instructure/ui-form-field'
-import type { WithStyleProps, ComponentStyle } from '@instructure/emotion'
+import type {
+  WithStyleProps,
+  ComponentStyle,
+  Spacing
+} from '@instructure/emotion'
 import type { WithDeterministicIdProps } from '@instructure/ui-react-utils'
 
 type TextAreaOwnProps = {
@@ -110,6 +114,11 @@ type TextAreaOwnProps = {
    * when used with the `value` prop, the component will not control its own state
    */
   onChange?: (event: React.ChangeEvent<HTMLTextAreaElement>) => void
+
+  /**
+   * Margin around the component. Accepts a `Spacing` token. See token values and example usage in [this guide](https://instructure.design/#layout-spacing).
+   */
+  margin?: Spacing
 }
 
 type PropKeys = keyof TextAreaOwnProps
@@ -153,7 +162,8 @@ const propTypes: PropValidators<PropKeys> = {
   textareaRef: PropTypes.func,
   defaultValue: PropTypes.string,
   value: controllable(PropTypes.string),
-  onChange: PropTypes.func
+  onChange: PropTypes.func,
+  margin: PropTypes.string
 }
 
 const allowedProps: AllowedPropKeys = [
@@ -175,7 +185,8 @@ const allowedProps: AllowedPropKeys = [
   'textareaRef',
   'defaultValue',
   'value',
-  'onChange'
+  'onChange',
+  'margin'
 ]
 
 export type { TextAreaProps, TextAreaStyle }
diff --git a/packages/ui-text-input/src/TextInput/index.tsx b/packages/ui-text-input/src/TextInput/index.tsx
index 5a208d45b3..8bc83830ac 100644
--- a/packages/ui-text-input/src/TextInput/index.tsx
+++ b/packages/ui-text-input/src/TextInput/index.tsx
@@ -347,6 +347,7 @@ class TextInput extends Component<TextInputProps, TextInputState> {
         inputContainerRef={inputContainerRef}
         layout={this.props.layout}
         elementRef={this.handleRef}
+        margin={this.props.margin}
       >
         <span css={styles?.facade}>
           {renderBeforeOrAfter ? (
diff --git a/packages/ui-text-input/src/TextInput/props.ts b/packages/ui-text-input/src/TextInput/props.ts
index 781accdf85..46be203955 100644
--- a/packages/ui-text-input/src/TextInput/props.ts
+++ b/packages/ui-text-input/src/TextInput/props.ts
@@ -34,7 +34,11 @@ import type {
   PropValidators,
   TextInputTheme
 } from '@instructure/shared-types'
-import type { WithStyleProps, ComponentStyle } from '@instructure/emotion'
+import type {
+  WithStyleProps,
+  ComponentStyle,
+  Spacing
+} from '@instructure/emotion'
 import type {
   InteractionType,
   WithDeterministicIdProps
@@ -172,6 +176,11 @@ type TextInputOwnProps = {
    * Callback fired when input receives focus.
    */
   onFocus?: (event: React.FocusEvent<HTMLInputElement>) => void
+
+  /**
+   * Margin around the component. Accepts a `Spacing` token. See token values and example usage in [this guide](https://instructure.design/#layout-spacing).
+   */
+  margin?: Spacing
 }
 
 type PropKeys = keyof TextInputOwnProps
@@ -221,7 +230,8 @@ const propTypes: PropValidators<PropKeys> = {
   renderAfterInput: PropTypes.oneOfType([PropTypes.node, PropTypes.func]),
   onChange: PropTypes.func,
   onBlur: PropTypes.func,
-  onFocus: PropTypes.func
+  onFocus: PropTypes.func,
+  margin: PropTypes.string
 }
 
 const allowedProps: AllowedPropKeys = [
@@ -247,7 +257,8 @@ const allowedProps: AllowedPropKeys = [
   'renderAfterInput',
   'onChange',
   'onBlur',
-  'onFocus'
+  'onFocus',
+  'margin'
 ]
 
 type TextInputState = {
diff --git a/packages/ui-themes/src/sharedThemeTokens/spacing.ts b/packages/ui-themes/src/sharedThemeTokens/spacing.ts
index 1409d4d175..a1b0a7851c 100644
--- a/packages/ui-themes/src/sharedThemeTokens/spacing.ts
+++ b/packages/ui-themes/src/sharedThemeTokens/spacing.ts
@@ -25,6 +25,7 @@
 import { Spacing } from '@instructure/shared-types'
 
 const spacing: Spacing = Object.freeze({
+  // legacy spacing tokens:
   xxxSmall: '0.125rem', // 2px
   xxSmall: '0.375rem', // 6px
   xSmall: '0.5rem', // 8px
@@ -33,7 +34,37 @@ const spacing: Spacing = Object.freeze({
   medium: '1.5rem', // 24px
   large: '2.25rem', // 36px
   xLarge: '3rem', // 48px
-  xxLarge: '3.75rem' // 60px
+  xxLarge: '3.75rem', // 60px
+
+  // new spacing tokens:
+  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
+  sectionElrements: '1.5em', // 24px
+  trayElrements: '1.5em', // 24px
+  modalElrements: '1.5em', // 24px
+  moduleElrements: '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
 } as const)
 
 export default spacing