+{"description":"\n## Layout Spacing\n\nThe spacing tokens documented on this page (such as `general.spaceMd`) require **v11.7+** components and are applied through the `margin` and `padding` props.\n\nOur 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).\n\nThe `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.\n\n### Where these tokens come from\n\nA prop like `margin=\"general.spaceMd\"` is resolved at runtime against the active theme's `sharedTokens.spacing` object. `sharedTokens` doesn't hold spacing values of its own — it reshapes the theme's **semantic** tokens into the flat, prop-facing structure shown below. The full pipeline is:\n\n`primitives` (raw `rem` values) → `semantics.spacing` (named tokens per theme) → `sharedTokens.spacing` (the dot-paths this page documents) → the `margin` / `padding` prop.\n\nBecause the values originate in each theme's semantic tokens, they are **theme-dependent** in principle — a theme can resolve `general.spaceMd` to a different value. In practice all themes InstUI currently ships resolve these tokens to the same values (those listed in the tables below).\n\n## Tokens\n\n### General scale\n\n| Key | Value | Value in pixels |\n| ----------------- | -------- | --------------- |\n| general.spaceNone | 0rem | 0px |\n| general.space2xs | 0.125rem | 2px |\n| general.spaceXs | 0.25rem | 4px |\n| general.spaceSm | 0.5rem | 8px |\n| general.spaceMd | 0.75rem | 12px |\n| general.spaceLg | 1rem | 16px |\n| general.spaceXl | 1.5rem | 24px |\n| general.space2xl | 2rem | 32px |\n\n### Semantic tokens\n\n| Key | Value | Value in pixels |\n| ----------------------------- | ------- | --------------- |\n| gap.sections | 3rem | 48px |\n| gap.buttons | 0.75rem | 12px |\n| gap.cards.sm | 0.75rem | 12px |\n| gap.cards.md | 1rem | 16px |\n| gap.cards.lg | 1.5rem | 24px |\n| gap.cards.nestedContainers.sm | 0.5rem | 8px |\n| gap.cards.nestedContainers.md | 0.75rem | 12px |\n| gap.cards.nestedContainers.lg | 1rem | 16px |\n| gap.inputs.horizontal | 0.75rem | 12px |\n| gap.inputs.vertical | 1rem | 16px |\n| padding.card.sm | 0.5rem | 8px |\n| padding.card.md | 0.75rem | 12px |\n| padding.card.lg | 1rem | 16px |\n\n## Applying spacing\n\n### Using the `margin` prop\n\nMost components support a `margin` prop that works like the CSS `margin` property. Pass a single token or use the 1–4 value shorthand to fine-tune individual edges.\n\n```js\n---\ntype: example\n---\n<View as=\"div\" display=\"block\" borderWidth=\"small\" padding=\"general.spaceSm\">\n <Button margin=\"0 general.spaceSm 0 0\">Button 1</Button>\n <Button>Button 2</Button>\n</View>\n```\n\n### Using the `padding` prop\n\nComponents that render their own surface accept a `padding` prop, which resolves the same tokens. Semantic `padding.card.*` tokens are a good fit for card-like containers.\n\n```js\n---\ntype: example\n---\n<View as=\"div\" display=\"block\" borderWidth=\"small\" padding=\"padding.card.lg\">\n This container uses <code>padding.card.lg</code>.\n</View>\n```\n\n## Deprecated tokens\n\nFor 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.\n\n### Phased-out tokens\n\nThe 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.\n\n### Legacy tokens\n\nThe original legacy keywords (`xxxSmall`, `small`, `medium`, `large`, `xxLarge`, etc.) remain so old layouts don't break when updating InstUI.\n","title":"Layout Spacing","category":"Guides","order":7,"relevantForAI":true,"relativePath":"docs/guides/layout-spacing.md","extension":".md","srcPath":"docs/guides/layout-spacing.md","srcUrl":"https://github.com/instructure/instructure-ui/tree/master/docs/guides/layout-spacing.md","packageName":"@instructure/docs","requirePath":"@instructure/docs/guides/layout-spacing","requireStr":"require('/home/runner/work/instructure-ui/instructure-ui/docs/guides/layout-spacing.md').default","esPath":"@instructure/docs/guides/layout-spacing","themePath":"docs/guides/layout-spacing.md","themeUrl":"https://github.com/instructure/instructure-ui/tree/master/docs/guides/layout-spacing.md","id":"layout-spacing"}
0 commit comments