diff --git a/docs/guides/layout-spacing.md b/docs/guides/layout-spacing.md index c492e12111..a718b31f32 100644 --- a/docs/guides/layout-spacing.md +++ b/docs/guides/layout-spacing.md @@ -7,40 +7,42 @@ relevantForAI: true # 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. +Our design system provides a set of spacing tokens for consistent layouts and components. The current tokens are organized into a general t-shirt scale plus a handful of semantic tokens. Some tokens share a value but carry different meaning — prefer the semantically correct token for the context (e.g. use `gap.buttons` for spacing between buttons). + +The `margin` and `padding` props on InstUI components accept these tokens via **dot-path notation** (for example `margin="general.spaceMd"` or `padding="padding.card.lg"`), and support the familiar CSS-like 1–4 value shorthand. ## 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 | +### General scale + +| Key | Value | Value in pixels | +| -------------------- | -------- | --------------- | +| general.spaceNone | 0rem | 0px | +| general.space2xs | 0.125rem | 2px | +| general.spaceXs | 0.25rem | 4px | +| general.spaceSm | 0.5rem | 8px | +| general.spaceMd | 0.75rem | 12px | +| general.spaceLg | 1rem | 16px | +| general.spaceXl | 1.5rem | 24px | +| general.space2xl | 2rem | 32px | + +### Semantic tokens + +| Key | Value | Value in pixels | +| ---------------------------------- | -------- | --------------- | +| gap.sections | 3rem | 48px | +| gap.buttons | 0.75rem | 12px | +| gap.cards.sm | 0.75rem | 12px | +| gap.cards.md | 1rem | 16px | +| gap.cards.lg | 1.5rem | 24px | +| gap.cards.nestedContainers.sm | 0.5rem | 8px | +| gap.cards.nestedContainers.md | 0.75rem | 12px | +| gap.cards.nestedContainers.lg | 1rem | 16px | +| gap.inputs.horizontal | 0.75rem | 12px | +| gap.inputs.vertical | 1rem | 16px | +| padding.card.sm | 0.5rem | 8px | +| padding.card.md | 0.75rem | 12px | +| padding.card.lg | 1rem | 16px | ## Applying Spacing @@ -55,7 +57,7 @@ Most components in the library support a `margin` prop that works similarly to t type: example ---
- +
``` @@ -92,6 +94,14 @@ import canvas from '@instructure/ui-themes' ``` -## Legacy tokens +## Deprecated tokens + +For compatibility reasons we still resolve two earlier generations of spacing tokens at runtime, but they should **not** be used when creating new layouts — prefer the current tokens above. + +### Phased-out tokens + +The flat `space0`–`space60` scale and the flat semantic tokens (`sections`, `buttons`, `paddingCardLarge`, `selects`, `tags`, etc.) were an interim set and have been superseded by the current general scale and dot-path semantic tokens. + +### 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. +The original legacy keywords (`xxxSmall`, `small`, `medium`, `large`, `xxLarge`, etc.) remain so old layouts don't break when updating InstUI. diff --git a/packages/emotion/src/styleUtils/ThemeablePropValues.ts b/packages/emotion/src/styleUtils/ThemeablePropValues.ts index f2ba3287c8..f8c490b2d6 100644 --- a/packages/emotion/src/styleUtils/ThemeablePropValues.ts +++ b/packages/emotion/src/styleUtils/ThemeablePropValues.ts @@ -90,7 +90,18 @@ const ThemeablePropValues = { // SPACING type OldSpacingKeys = keyof typeof ThemeablePropValues.SPACING +/** + * @deprecated Era-1 (legacy) spacing keywords. Still resolved at runtime, but + * prefer the current `CurrentSpacingValues` dot-path tokens (e.g. `general.spaceMd`). + * See https://instructure.design/layout-spacing. + */ type OldSpacingValues = (typeof ThemeablePropValues.SPACING)[OldSpacingKeys] +/** + * @deprecated Era-2 spacing tokens (the `space0`–`space60` and flat semantic set) + * have been phased out. Still resolved at runtime, but prefer the current + * `CurrentSpacingValues` dot-path tokens (e.g. `general.spaceMd`, `gap.cards.md`). + * See https://instructure.design/layout-spacing. + */ type NewSpacingValues = | 'space0' | 'space2' @@ -120,7 +131,38 @@ type NewSpacingValues = | 'tags' | 'statusIndicators' | 'dataPoints' -type SpacingValues = OldSpacingValues | NewSpacingValues +/** + * Current (era-3) spacing tokens. Referenced via dot-path notation and resolved + * against the new theme's `sharedTokens.spacing` map (see + * `@instructure/ui-themes` `newThemeTokens`). These are the recommended values + * for the `margin`/`padding` props. See https://instructure.design/layout-spacing. + */ +type CurrentSpacingValues = + // general t-shirt scale + | 'general.spaceNone' + | 'general.space2xs' + | 'general.spaceXs' + | 'general.spaceSm' + | 'general.spaceMd' + | 'general.spaceLg' + | 'general.spaceXl' + | 'general.space2xl' + // semantic gap tokens + | 'gap.sections' + | 'gap.buttons' + | 'gap.cards.sm' + | 'gap.cards.md' + | 'gap.cards.lg' + | 'gap.cards.nestedContainers.sm' + | 'gap.cards.nestedContainers.md' + | 'gap.cards.nestedContainers.lg' + | 'gap.inputs.horizontal' + | 'gap.inputs.vertical' + // semantic padding tokens + | 'padding.card.sm' + | 'padding.card.md' + | 'padding.card.lg' +type SpacingValues = CurrentSpacingValues | OldSpacingValues | NewSpacingValues // adding `(string & {})` allows to use any string while still allowing specific string values to be suggested by IDEs type Spacing = SpacingValues | (string & {}) @@ -152,6 +194,7 @@ export default ThemeablePropValues export { ThemeablePropValues } export type { SpacingValues, + CurrentSpacingValues, Spacing, Shadow, Stacking, diff --git a/packages/emotion/src/styleUtils/__tests__/calcSpacingFromShorthand.test.tsx b/packages/emotion/src/styleUtils/__tests__/calcSpacingFromShorthand.test.tsx index cf4e535125..8be6ba52dc 100644 --- a/packages/emotion/src/styleUtils/__tests__/calcSpacingFromShorthand.test.tsx +++ b/packages/emotion/src/styleUtils/__tests__/calcSpacingFromShorthand.test.tsx @@ -239,4 +239,70 @@ describe('calcSpacingFromShorthand', () => { consoleWarnSpy.mockRestore() }) }) + + // Era-3 (current) tokens are referenced via dot-path notation and resolved + // against the new theme's nested `sharedTokens.spacing` map. This block mirrors + // that shape to verify the real consumer syntax (e.g. `margin="general.spaceMd"`). + describe('era-3 (current) spacing tokens', () => { + const eraThreeMap = { + general: { + spaceNone: '0rem', + space2xs: '0.125rem', + spaceXs: '0.25rem', + spaceSm: '0.5rem', + spaceMd: '0.75rem', + spaceLg: '1rem', + spaceXl: '1.5rem', + space2xl: '2rem' + }, + gap: { + sections: '3rem', + buttons: '0.75rem', + cards: { + sm: '0.75rem', + md: '1rem', + lg: '1.5rem', + nestedContainers: { sm: '0.5rem', md: '0.75rem', lg: '1rem' } + }, + inputs: { horizontal: '0.75rem', vertical: '1rem' } + }, + padding: { + card: { sm: '0.5rem', md: '0.75rem', lg: '1rem' } + } + } + + it('resolves a general scale token', () => { + expect(calcSpacingFromShorthand('general.spaceMd', eraThreeMap)).toBe('0.75rem') + }) + + it('resolves general.spaceNone', () => { + expect(calcSpacingFromShorthand('general.spaceNone', eraThreeMap)).toBe('0rem') + }) + + it('resolves a deeply nested semantic gap token', () => { + expect( + calcSpacingFromShorthand('gap.cards.nestedContainers.md', eraThreeMap) + ).toBe('0.75rem') + }) + + it('resolves a semantic padding token', () => { + expect(calcSpacingFromShorthand('padding.card.lg', eraThreeMap)).toBe('1rem') + }) + + it('handles CSS-like shorthand mixing the general scale with auto', () => { + const consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {}) + + expect( + calcSpacingFromShorthand('general.spaceLg auto general.spaceXl', eraThreeMap) + ).toBe('1rem auto 1.5rem') + + consoleWarnSpy.mockRestore() + }) + + it('mixes semantic gap and padding tokens', () => { + expect( + calcSpacingFromShorthand('gap.cards.sm padding.card.md', eraThreeMap) + ).toBe('0.75rem 0.75rem') + }) + }) }) diff --git a/packages/ui-alerts/src/Alert/v2/props.ts b/packages/ui-alerts/src/Alert/v2/props.ts index 33a1966d06..fce9f0fe81 100644 --- a/packages/ui-alerts/src/Alert/v2/props.ts +++ b/packages/ui-alerts/src/Alert/v2/props.ts @@ -79,9 +79,9 @@ type AlertOwnProps = { */ timeout?: number /** - * Valid values are `0`, `none`, `auto`, `xxx-small`, `xx-small`, `x-small`, - * `small`, `medium`, `large`, `x-large`, `xx-large`. Apply these values via - * familiar CSS-like shorthand. For example: `margin="small auto large"`. + * Valid values are `0`, `none`, `auto`, and Spacing token values, + * see https://instructure.design/layout-spacing. Apply these values via + * familiar CSS-like shorthand. For example, `margin="general.spaceMd auto"`. */ margin?: Spacing /** diff --git a/packages/ui-badge/src/Badge/v2/props.ts b/packages/ui-badge/src/Badge/v2/props.ts index dfdda5271d..41339d85e2 100644 --- a/packages/ui-badge/src/Badge/v2/props.ts +++ b/packages/ui-badge/src/Badge/v2/props.ts @@ -71,9 +71,9 @@ type BadgeOwnProps = { */ display?: 'inline-block' | 'block' /** - * Valid values are `0`, `none`, `auto`, `xxx-small`, `xx-small`, `x-small`, - * `small`, `medium`, `large`, `x-large`, `xx-large`. Apply these values via - * familiar CSS-like shorthand. For example: `margin="small auto large"`. + * Valid values are `0`, `none`, `auto`, and Spacing token values, + * see https://instructure.design/layout-spacing. Apply these values via + * familiar CSS-like shorthand. For example, `margin="general.spaceMd auto"`. */ margin?: Spacing /** diff --git a/packages/ui-billboard/src/Billboard/v2/props.ts b/packages/ui-billboard/src/Billboard/v2/props.ts index 085b147a46..7b8bd2cbe4 100644 --- a/packages/ui-billboard/src/Billboard/v2/props.ts +++ b/packages/ui-billboard/src/Billboard/v2/props.ts @@ -90,9 +90,9 @@ type BillboardOwnProps = { */ readOnly?: boolean /** - * Valid values are `0`, `none`, `auto`, `xxx-small`, `xx-small`, `x-small`, - * `small`, `medium`, `large`, `x-large`, `xx-large`. Apply these values via - * familiar CSS-like shorthand. For example: `margin="small auto large"`. + * Valid values are `0`, `none`, `auto`, and Spacing token values, + * see https://instructure.design/layout-spacing. Apply these values via + * familiar CSS-like shorthand. For example, `margin="general.spaceMd auto"`. */ margin?: Spacing } diff --git a/packages/ui-breadcrumb/src/Breadcrumb/v2/props.ts b/packages/ui-breadcrumb/src/Breadcrumb/v2/props.ts index 8b5b1fc495..baf64511c5 100644 --- a/packages/ui-breadcrumb/src/Breadcrumb/v2/props.ts +++ b/packages/ui-breadcrumb/src/Breadcrumb/v2/props.ts @@ -42,9 +42,9 @@ type BreadcrumbOwnProps = { */ size?: 'small' | 'medium' | 'large' /** - * Valid values are `0`, `none`, `auto`, `xxx-small`, `xx-small`, `x-small`, - * `small`, `medium`, `large`, `x-large`, `xx-large`. Apply these values via - * familiar CSS-like shorthand. For example: `margin="small auto large"`. + * Valid values are `0`, `none`, `auto`, and Spacing token values, + * see https://instructure.design/layout-spacing. Apply these values via + * familiar CSS-like shorthand. For example, `margin="general.spaceMd auto"`. */ margin?: Spacing } diff --git a/packages/ui-buttons/src/BaseButton/v2/props.ts b/packages/ui-buttons/src/BaseButton/v2/props.ts index 02f0ec5508..a9299186dc 100644 --- a/packages/ui-buttons/src/BaseButton/v2/props.ts +++ b/packages/ui-buttons/src/BaseButton/v2/props.ts @@ -120,9 +120,9 @@ type BaseButtonOwnProps = { isCondensed?: boolean /** - * Valid values are `0`, `none`, `auto`, `xxx-small`, `xx-small`, `x-small`, - * `small`, `medium`, `large`, `x-large`, `xx-large`. Apply these values via - * familiar CSS-like shorthand. For example: `margin="small auto large"`. + * Valid values are `0`, `none`, `auto`, and Spacing token values, + * see https://instructure.design/layout-spacing. Apply these values via + * familiar CSS-like shorthand. For example, `margin="general.spaceMd auto"`. */ margin?: Spacing diff --git a/packages/ui-buttons/src/Button/v2/props.ts b/packages/ui-buttons/src/Button/v2/props.ts index 65c2e48175..a9cf57332a 100644 --- a/packages/ui-buttons/src/Button/v2/props.ts +++ b/packages/ui-buttons/src/Button/v2/props.ts @@ -98,9 +98,9 @@ type ButtonOwnProps = { withBackground?: boolean /** - * Valid values are `0`, `none`, `auto`, `xxx-small`, `xx-small`, `x-small`, - * `small`, `medium`, `large`, `x-large`, `xx-large`. Apply these values via - * familiar CSS-like shorthand. For example: `margin="small auto large"`. + * Valid values are `0`, `none`, `auto`, and Spacing token values, + * see https://instructure.design/layout-spacing. Apply these values via + * familiar CSS-like shorthand. For example, `margin="general.spaceMd auto"`. */ margin?: Spacing diff --git a/packages/ui-buttons/src/CloseButton/v2/props.ts b/packages/ui-buttons/src/CloseButton/v2/props.ts index b3c3ce62c2..63ae72dde7 100644 --- a/packages/ui-buttons/src/CloseButton/v2/props.ts +++ b/packages/ui-buttons/src/CloseButton/v2/props.ts @@ -71,9 +71,9 @@ type CloseButtonOwnProps = { ) => void /** - * Valid values are `0`, `none`, `auto`, `xxx-small`, `xx-small`, `x-small`, - * `small`, `medium`, `large`, `x-large`, `xx-large`. Apply these values via - * familiar CSS-like shorthand. For example: `margin="small auto large"`. + * Valid values are `0`, `none`, `auto`, and Spacing token values, + * see https://instructure.design/layout-spacing. Apply these values via + * familiar CSS-like shorthand. For example, `margin="general.spaceMd auto"`. */ margin?: Spacing diff --git a/packages/ui-buttons/src/CondensedButton/v2/props.ts b/packages/ui-buttons/src/CondensedButton/v2/props.ts index f2a6c5e661..f778a954d0 100644 --- a/packages/ui-buttons/src/CondensedButton/v2/props.ts +++ b/packages/ui-buttons/src/CondensedButton/v2/props.ts @@ -70,9 +70,9 @@ type CondensedButtonOwnProps = { color?: 'primary' | 'primary-inverse' | 'secondary' /** - * Valid values are `0`, `none`, `auto`, `xxx-small`, `xx-small`, `x-small`, - * `small`, `medium`, `large`, `x-large`, `xx-large`. Apply these values via - * familiar CSS-like shorthand. For example: `margin="small auto large"`. + * Valid values are `0`, `none`, `auto`, and Spacing token values, + * see https://instructure.design/layout-spacing. Apply these values via + * familiar CSS-like shorthand. For example, `margin="general.spaceMd auto"`. */ margin?: Spacing diff --git a/packages/ui-buttons/src/IconButton/v2/props.ts b/packages/ui-buttons/src/IconButton/v2/props.ts index 2676f41b32..bb8f0e5311 100644 --- a/packages/ui-buttons/src/IconButton/v2/props.ts +++ b/packages/ui-buttons/src/IconButton/v2/props.ts @@ -109,9 +109,9 @@ type IconButtonOwnProps = { withBorder?: boolean /** - * Valid values are `0`, `none`, `auto`, `xxx-small`, `xx-small`, `x-small`, - * `small`, `medium`, `large`, `x-large`, `xx-large`. Apply these values via - * familiar CSS-like shorthand. For example: `margin="small auto large"`. + * Valid values are `0`, `none`, `auto`, and Spacing token values, + * see https://instructure.design/layout-spacing. Apply these values via + * familiar CSS-like shorthand. For example, `margin="general.spaceMd auto"`. */ margin?: Spacing diff --git a/packages/ui-byline/src/Byline/v2/props.ts b/packages/ui-byline/src/Byline/v2/props.ts index 3e8d73fe62..fb8fb616db 100644 --- a/packages/ui-byline/src/Byline/v2/props.ts +++ b/packages/ui-byline/src/Byline/v2/props.ts @@ -49,9 +49,9 @@ type BylineOwnProps = { */ alignContent?: 'top' | 'center' /** - * Valid values are `0`, `none`, `auto`, `xxx-small`, `xx-small`, `x-small`, - * `small`, `medium`, `large`, `x-large`, `xx-large`. Apply these values via - * familiar CSS-like shorthand. For example: `margin="small auto large"`. + * Valid values are `0`, `none`, `auto`, and Spacing token values, + * see https://instructure.design/layout-spacing. Apply these values via + * familiar CSS-like shorthand. For example, `margin="general.spaceMd auto"`. */ margin?: Spacing /* diff --git a/packages/ui-file-drop/src/FileDrop/v2/props.ts b/packages/ui-file-drop/src/FileDrop/v2/props.ts index 8e9e9633ee..d6ddb281f9 100644 --- a/packages/ui-file-drop/src/FileDrop/v2/props.ts +++ b/packages/ui-file-drop/src/FileDrop/v2/props.ts @@ -141,9 +141,9 @@ type FileDropOwnProps = { */ minWidth?: string | number /** - * Valid values are 0, none, auto, xxx-small, xx-small, x-small, small, - * medium, large, x-large, xx-large. Apply these values via familiar - * CSS-like shorthand. For example: margin="small auto large". + * Valid values are `0`, `none`, `auto`, and Spacing token values, + * see https://instructure.design/layout-spacing. Apply these values via + * familiar CSS-like shorthand. For example, `margin="general.spaceMd auto"`. */ margin?: Spacing /** diff --git a/packages/ui-flex/src/Flex/v2/README.md b/packages/ui-flex/src/Flex/v2/README.md index aefa6d084d..8a471f791b 100644 --- a/packages/ui-flex/src/Flex/v2/README.md +++ b/packages/ui-flex/src/Flex/v2/README.md @@ -19,19 +19,19 @@ Flex defaults to a `direction` of `row`, creating a horizontal layout. Change `d type: example ---
- + One Two Three Four - + One Two Three Four - + One Two Three @@ -55,19 +55,19 @@ Flex items will have no gap by default. You can set the gap between Flex.Items b type: example ---
- + One Two Three Four - + One Two Three Four - + One Two Three @@ -89,25 +89,25 @@ You can also set the gap between rows and columns by using the `gap` property. M type: example ---
- + One Two Three Four - + One Two Three Four - + One Two Three Four - + One Two Three diff --git a/packages/ui-heading/src/Heading/v2/props.ts b/packages/ui-heading/src/Heading/v2/props.ts index f2013ad1f5..b39e15ef81 100644 --- a/packages/ui-heading/src/Heading/v2/props.ts +++ b/packages/ui-heading/src/Heading/v2/props.ts @@ -75,9 +75,9 @@ type HeadingOwnProps = { */ as?: AsElementType /** - * Valid values are `0`, `none`, `auto`, `xxx-small`, `xx-small`, `x-small`, - * `small`, `medium`, `large`, `x-large`, `xx-large`. Apply these values via - * familiar CSS-like shorthand. For example: `margin="small auto large"`. + * Valid values are `0`, `none`, `auto`, and Spacing token values, + * see https://instructure.design/layout-spacing. Apply these values via + * familiar CSS-like shorthand. For example, `margin="general.spaceMd auto"`. */ margin?: Spacing /** diff --git a/packages/ui-img/src/Img/v2/props.ts b/packages/ui-img/src/Img/v2/props.ts index abe9b9bee6..7826484e49 100644 --- a/packages/ui-img/src/Img/v2/props.ts +++ b/packages/ui-img/src/Img/v2/props.ts @@ -39,9 +39,9 @@ type ImgOwnProps = { */ loading?: 'eager' | 'lazy' /** - * Valid values are `0`, `none`, `auto`, `xxx-small`, `xx-small`, `x-small`, - * `small`, `medium`, `large`, `x-large`, `xx-large`. Apply these values via - * familiar CSS-like shorthand. For example: `margin="small auto large"`. + * Valid values are `0`, `none`, `auto`, and Spacing token values, + * see https://instructure.design/layout-spacing. Apply these values via + * familiar CSS-like shorthand. For example, `margin="general.spaceMd auto"`. */ margin?: Spacing /** diff --git a/packages/ui-list/src/InlineList/v2/props.ts b/packages/ui-list/src/InlineList/v2/props.ts index 1c6098cb0d..deefdb93c1 100644 --- a/packages/ui-list/src/InlineList/v2/props.ts +++ b/packages/ui-list/src/InlineList/v2/props.ts @@ -34,9 +34,9 @@ type InlineListOwnProps = { children?: React.ReactNode as?: 'ul' | 'ol' /** - * Valid values are `0`, `none`, `auto`, `xxx-small`, `xx-small`, `x-small`, - * `small`, `medium`, `large`, `x-large`, `xx-large`. Apply these values via - * familiar CSS-like shorthand. For example: `margin="small auto large"`. + * Valid values are `0`, `none`, `auto`, and Spacing token values, + * see https://instructure.design/layout-spacing. Apply these values via + * familiar CSS-like shorthand. For example, `margin="general.spaceMd auto"`. */ margin?: Spacing size?: 'small' | 'medium' | 'large' diff --git a/packages/ui-list/src/List/v2/props.ts b/packages/ui-list/src/List/v2/props.ts index 2b46b58abb..f1ce45847d 100644 --- a/packages/ui-list/src/List/v2/props.ts +++ b/packages/ui-list/src/List/v2/props.ts @@ -47,9 +47,9 @@ type ListOwnProps = { */ isUnstyled?: boolean /** - * Valid values are `0`, `none`, `auto`, `xxx-small`, `xx-small`, `x-small`, - * `small`, `medium`, `large`, `x-large`, `xx-large`. Apply these values via - * familiar CSS-like shorthand. For example: `margin="small auto large"`. + * Valid values are `0`, `none`, `auto`, and Spacing token values, + * see https://instructure.design/layout-spacing. Apply these values via + * familiar CSS-like shorthand. For example, `margin="general.spaceMd auto"`. */ margin?: Spacing size?: 'small' | 'medium' | 'large' diff --git a/packages/ui-navigation/src/AppNav/v2/props.ts b/packages/ui-navigation/src/AppNav/v2/props.ts index 56aa43669d..2c359ed6b1 100644 --- a/packages/ui-navigation/src/AppNav/v2/props.ts +++ b/packages/ui-navigation/src/AppNav/v2/props.ts @@ -52,9 +52,9 @@ type AppNavOwnProps = { */ renderAfterItems?: Renderable /** - * Valid values are `0`, `none`, `auto`, `xxx-small`, `xx-small`, `x-small`, - * `small`, `medium`, `large`, `x-large`, `xx-large`. Apply these values via - * familiar CSS-like shorthand. For example: `margin="small auto large"`. + * Valid values are `0`, `none`, `auto`, and Spacing token values, + * see https://instructure.design/layout-spacing. Apply these values via + * familiar CSS-like shorthand. For example, `margin="general.spaceMd auto"`. */ margin?: Spacing /** diff --git a/packages/ui-pagination/src/Pagination/v2/props.ts b/packages/ui-pagination/src/Pagination/v2/props.ts index b10661d5e0..cb5b85b210 100644 --- a/packages/ui-pagination/src/Pagination/v2/props.ts +++ b/packages/ui-pagination/src/Pagination/v2/props.ts @@ -121,9 +121,9 @@ type PaginationOwnProps = { variant?: 'full' | 'compact' | 'input' /** - * Spacing token values can be found here: [Spacing Tokens](https://instructure.design/#layout-spacing/%23Tokens) - * - * Apply these values via familiar CSS-like shorthand. For example: `margin="space8 0 space12"`. + * Valid values are `0`, `none`, `auto`, and Spacing token values, + * see https://instructure.design/layout-spacing. Apply these values via + * familiar CSS-like shorthand. For example, `margin="general.spaceMd auto"`. */ margin?: Spacing diff --git a/packages/ui-pill/src/Pill/v2/props.ts b/packages/ui-pill/src/Pill/v2/props.ts index caa9f4eeea..fdd95aa045 100644 --- a/packages/ui-pill/src/Pill/v2/props.ts +++ b/packages/ui-pill/src/Pill/v2/props.ts @@ -41,9 +41,9 @@ type PillOwnProps = { */ elementRef?: (element: Element | null) => void /** - * Valid values are `0`, `none`, `auto`, `xxx-small`, `xx-small`, `x-small`, - * `small`, `medium`, `large`, `x-large`, `xx-large`. Apply these values via - * familiar CSS-like shorthand. For example: `margin="small auto large"`. + * Valid values are `0`, `none`, `auto`, and Spacing token values, + * see https://instructure.design/layout-spacing. Apply these values via + * familiar CSS-like shorthand. For example, `margin="general.spaceMd auto"`. */ margin?: Spacing children: React.ReactNode diff --git a/packages/ui-progress/src/ProgressBar/v2/props.ts b/packages/ui-progress/src/ProgressBar/v2/props.ts index 5435e01a47..230f5173e1 100644 --- a/packages/ui-progress/src/ProgressBar/v2/props.ts +++ b/packages/ui-progress/src/ProgressBar/v2/props.ts @@ -95,9 +95,9 @@ type ProgressBarOwnProps = { shouldAnimate?: boolean /** - * Valid values are `0`, `none`, `auto`, `xxx-small`, `xx-small`, `x-small`, - * `small`, `medium`, `large`, `x-large`, `xx-large`. Apply these values via - * familiar CSS-like shorthand. For example: `margin="small auto large"`. + * Valid values are `0`, `none`, `auto`, and Spacing token values, + * see https://instructure.design/layout-spacing. Apply these values via + * familiar CSS-like shorthand. For example, `margin="general.spaceMd auto"`. */ margin?: Spacing diff --git a/packages/ui-progress/src/ProgressCircle/v2/props.ts b/packages/ui-progress/src/ProgressCircle/v2/props.ts index a4df44aa93..b53022e004 100644 --- a/packages/ui-progress/src/ProgressCircle/v2/props.ts +++ b/packages/ui-progress/src/ProgressCircle/v2/props.ts @@ -82,9 +82,9 @@ type ProgressCircleOwnProps = { | ((values: Values) => ProgressCircleMeterColor) | ProgressCircleMeterColor /** - * Valid values are `0`, `none`, `auto`, `xxx-small`, `xx-small`, `x-small`, - * `small`, `medium`, `large`, `x-large`, `xx-large`. Apply these values via - * familiar CSS-like shorthand. For example: `margin="small auto large"`. + * Valid values are `0`, `none`, `auto`, and Spacing token values, + * see https://instructure.design/layout-spacing. Apply these values via + * familiar CSS-like shorthand. For example, `margin="general.spaceMd auto"`. */ margin?: Spacing /** diff --git a/packages/ui-rating/src/Rating/v2/props.ts b/packages/ui-rating/src/Rating/v2/props.ts index 9b05a2cf96..be6ed04cec 100644 --- a/packages/ui-rating/src/Rating/v2/props.ts +++ b/packages/ui-rating/src/Rating/v2/props.ts @@ -59,9 +59,9 @@ type RatingOwnProps = { */ animateFill?: boolean /** - * Valid values are `0`, `none`, `auto`, `xxx-small`, `xx-small`, `x-small`, - * `small`, `medium`, `large`, `x-large`, `xx-large`. Apply these values via - * familiar CSS-like shorthand. For example: `margin="small auto large"`. + * Valid values are `0`, `none`, `auto`, and Spacing token values, + * see https://instructure.design/layout-spacing. Apply these values via + * familiar CSS-like shorthand. For example, `margin="general.spaceMd auto"`. */ margin?: Spacing } diff --git a/packages/ui-spinner/src/Spinner/v2/props.ts b/packages/ui-spinner/src/Spinner/v2/props.ts index 1198610581..82e3995457 100644 --- a/packages/ui-spinner/src/Spinner/v2/props.ts +++ b/packages/ui-spinner/src/Spinner/v2/props.ts @@ -40,7 +40,7 @@ type SpinnerOwnProps = { /** * Valid values are `0`, `none`, `auto`, and Spacing token values, * see https://instructure.design/layout-spacing. Apply these values via - * familiar CSS-like shorthand. For example, `gap="small auto large"`. + * familiar CSS-like shorthand. For example, `margin="general.spaceMd auto"`. */ margin?: Spacing /** diff --git a/packages/ui-table/src/Table/v2/props.ts b/packages/ui-table/src/Table/v2/props.ts index f2afc07c07..6e81b46570 100644 --- a/packages/ui-table/src/Table/v2/props.ts +++ b/packages/ui-table/src/Table/v2/props.ts @@ -39,9 +39,9 @@ type TableOwnProps = { */ caption: React.ReactNode /** - * Valid values are `0`, `none`, `auto`, `xxx-small`, `xx-small`, `x-small`, - * `small`, `medium`, `large`, `x-large`, `xx-large`. Apply these values via - * familiar CSS-like shorthand. For example: `margin="small auto large"`. + * Valid values are `0`, `none`, `auto`, and Spacing token values, + * see https://instructure.design/layout-spacing. Apply these values via + * familiar CSS-like shorthand. For example, `margin="general.spaceMd auto"`. */ margin?: Spacing /** diff --git a/packages/ui-tabs/src/Tabs/v2/props.ts b/packages/ui-tabs/src/Tabs/v2/props.ts index 8a54504db6..29890a9dd6 100644 --- a/packages/ui-tabs/src/Tabs/v2/props.ts +++ b/packages/ui-tabs/src/Tabs/v2/props.ts @@ -56,9 +56,9 @@ type TabsOwnProps = { minHeight?: string | number fixHeight?: string | number /** - * Valid values are `0`, `none`, `auto`, `xxx-small`, `xx-small`, `x-small`, - * `small`, `medium`, `large`, `x-large`, `xx-large`. Apply these values via - * familiar CSS-like shorthand. For example: `margin="small auto large"`. + * Valid values are `0`, `none`, `auto`, and Spacing token values, + * see https://instructure.design/layout-spacing. Apply these values via + * familiar CSS-like shorthand. For example, `margin="general.spaceMd auto"`. */ margin?: Spacing /** diff --git a/packages/ui-tag/src/Tag/v2/README.md b/packages/ui-tag/src/Tag/v2/README.md index f072a7df77..68cfcb564c 100644 --- a/packages/ui-tag/src/Tag/v2/README.md +++ b/packages/ui-tag/src/Tag/v2/README.md @@ -8,7 +8,7 @@ Use `` to represent a category or group in a form. --- type: example --- - + ``` ### Dismissible @@ -28,7 +28,7 @@ type: example } dismissible - margin="0 xx-small 0 0" + margin="0 general.spaceXs 0 0" onClick={function () { alert("This Tag was dismissed") }} @@ -47,7 +47,7 @@ type: example text="Dismissible Disabled" dismissible disabled - margin="0 xx-small 0 0" + margin="0 general.spaceXs 0 0" onClick={function () { alert("This Tag was dismissed. This shouldn't happen") }} @@ -63,9 +63,9 @@ type: example type: example ---
- - - + + +
``` diff --git a/packages/ui-tag/src/Tag/v2/props.ts b/packages/ui-tag/src/Tag/v2/props.ts index b0ccf49e04..078d82bd0e 100644 --- a/packages/ui-tag/src/Tag/v2/props.ts +++ b/packages/ui-tag/src/Tag/v2/props.ts @@ -45,9 +45,9 @@ type TagOwnProps = { readOnly?: boolean dismissible?: boolean /** - * Valid values are `0`, `none`, `auto`, `xxxx-small`, `xx-small`, `x-small`, - * `small`, `medium`, `large`, `x-large`, `xx-large`. Apply these values via - * familiar CSS-like shorthand. For example: `margin="small auto large"`. + * Valid values are `0`, `none`, `auto`, and Spacing token values, + * see https://instructure.design/layout-spacing. Apply these values via + * familiar CSS-like shorthand. For example, `margin="general.spaceMd auto"`. */ margin?: Spacing /** diff --git a/packages/ui-view/src/View/__tests__/View.test.tsx b/packages/ui-view/src/View/__tests__/View.test.tsx index 7cb967b878..ae49c53023 100644 --- a/packages/ui-view/src/View/__tests__/View.test.tsx +++ b/packages/ui-view/src/View/__tests__/View.test.tsx @@ -233,6 +233,45 @@ describe('', () => { expect(newStyles.maxWidth).toEqual('200px') }) + it('should resolve current (era-3) spacing tokens for the margin prop', () => { + const { container } = render( + +

View Content

+ + ) + + const view = container.querySelector("span[class$='-view']") + const styles = getComputedStyle(view!) + + // general.spaceMd resolves to 0.75rem (12px) + expect(styles.marginTop).toEqual('0.75rem') + expect(styles.marginRight).toEqual('0.75rem') + expect(styles.marginBottom).toEqual('0.75rem') + expect(styles.marginLeft).toEqual('0.75rem') + + // a known token should not emit the "not found in theme" warning + expect(consoleWarningMock).not.toHaveBeenCalledWith( + expect.stringContaining('not found in theme') + ) + }) + + it('should resolve era-3 tokens via CSS-like shorthand for the margin prop', () => { + const { container } = render( + +

View Content

+ + ) + + const view = container.querySelector("span[class$='-view']") + const styles = getComputedStyle(view!) + + // 3-value shorthand: top | left+right | bottom + expect(styles.marginTop).toEqual('1rem') // general.spaceLg + expect(styles.marginRight).toEqual('auto') + expect(styles.marginBottom).toEqual('1.5rem') // general.spaceXl + expect(styles.marginLeft).toEqual('auto') + }) + it('should meet a11y standards', async () => { const { container } = render(View Content) diff --git a/packages/ui-view/src/View/v2/README.md b/packages/ui-view/src/View/v2/README.md index 31e3fe54fd..77e32d3680 100644 --- a/packages/ui-view/src/View/v2/README.md +++ b/packages/ui-view/src/View/v2/README.md @@ -20,7 +20,7 @@ type: example --- @@ -52,7 +52,7 @@ type: example as="div" display="inline-block" maxWidth="10rem" - margin="small" + margin="general.spaceMd" padding="small" background="primary" > @@ -62,7 +62,7 @@ type: example as="div" display="inline-block" maxWidth="10rem" - margin="small" + margin="general.spaceMd" padding="small" background="secondary" > @@ -72,7 +72,7 @@ type: example as="div" display="inline-block" maxWidth="10rem" - margin="small" + margin="general.spaceMd" padding="small" background="primary-inverse" > @@ -82,7 +82,7 @@ type: example as="div" display="inline-block" maxWidth="10rem" - margin="small" + margin="general.spaceMd" padding="small" background="brand" > @@ -92,7 +92,7 @@ type: example as="div" display="inline-block" maxWidth="10rem" - margin="small" + margin="general.spaceMd" padding="small" background="alert" > @@ -102,7 +102,7 @@ type: example as="div" display="inline-block" maxWidth="10rem" - margin="small" + margin="general.spaceMd" padding="small" background="success" > @@ -112,7 +112,7 @@ type: example as="div" display="inline-block" maxWidth="10rem" - margin="small" + margin="general.spaceMd" padding="small" background="danger" > @@ -122,7 +122,7 @@ type: example as="div" display="inline-block" maxWidth="10rem" - margin="small" + margin="general.spaceMd" padding="small" background="warning" > @@ -144,7 +144,7 @@ type: example as="span" display="inline-block" maxWidth="10rem" - margin="small" + margin="general.spaceMd" padding="large" background="primary" shadow="resting" @@ -155,7 +155,7 @@ type: example as="span" display="inline-block" maxWidth="10rem" - margin="small" + margin="general.spaceMd" padding="large" background="primary" shadow="above" @@ -166,7 +166,7 @@ type: example as="span" display="inline-block" maxWidth="10rem" - margin="small" + margin="general.spaceMd" padding="large" background="primary" shadow="topmost" @@ -191,7 +191,7 @@ type: example as="span" display="inline-block" maxWidth="10rem" - margin="small" + margin="general.spaceMd" padding="small" background="primary" borderWidth="small" @@ -202,7 +202,7 @@ type: example as="span" display="inline-block" maxWidth="10rem" - margin="small" + margin="general.spaceMd" padding="small" background="primary" borderWidth="medium" @@ -213,7 +213,7 @@ type: example as="span" display="inline-block" maxWidth="10rem" - margin="small" + margin="general.spaceMd" padding="small" background="primary" borderWidth="large none" @@ -222,7 +222,7 @@ type: example { as="div" background="primary" padding="small" - margin="0 0 small" + margin="0 0 general.spaceMd" borderWidth="small" > { borderRadius = { { { display="inline-block" height="100px" width="100px" - margin="small" + margin="general.spaceMd" background="primary" borderRadius="circle" borderWidth="small" @@ -583,7 +583,7 @@ const FocusedExample = () => { > { { @@ -744,7 +744,7 @@ type: example diff --git a/packages/ui-view/src/View/v2/props.ts b/packages/ui-view/src/View/v2/props.ts index c14df20c36..919dffee51 100644 --- a/packages/ui-view/src/View/v2/props.ts +++ b/packages/ui-view/src/View/v2/props.ts @@ -163,7 +163,7 @@ type ViewOwnProps = { /** * Valid values are `0`, `none`, `auto`, and Spacing token values, * see https://instructure.design/layout-spacing. Apply these values via - * familiar CSS-like shorthand. For example, `margin="small auto large"`. + * familiar CSS-like shorthand. For example, `margin="general.spaceMd auto"`. */ margin?: Spacing /** diff --git a/regression-test/src/app/view/page.tsx b/regression-test/src/app/view/page.tsx index 8fb11fe12d..00c245d64f 100644 --- a/regression-test/src/app/view/page.tsx +++ b/regression-test/src/app/view/page.tsx @@ -271,6 +271,27 @@ export default function ViewPage() {
Paragraph-like content
+ + {/* Current (era-3) spacing tokens via dot-path notation */} +
+ + margin="general.spaceMd" + + + margin="general.spaceLg auto general.spaceXl" + + + margin="gap.cards.md" + + + margin="padding.card.lg" + +
) }