feat(many): support current spacing tokens in the margin prop for v2 components by balzss · Pull Request #2587 · instructure/instructure-ui

balzss · 2026-06-10T12:32:42Z

What & why

The current (era-3) spacing tokens — general.*, gap.*, padding.card.* (dot-path notation, e.g. margin="general.spaceMd") — already resolved at runtime in View v2, but the Spacing prop type and the docs only advertised the two older token eras. So the new tokens had no autocomplete, no type hints, and weren't documented.

This PR makes them first-class on the margin prop of v2 components. Non-breaking — the older tokens still resolve at runtime and are only marked @deprecated.

What changed

Area	Change
Types (`emotion`)	Add `CurrentSpacingValues` (era-3 dot-paths) to the `Spacing` union; mark era-1 / era-2 unions `@deprecated`.
v2 components	Sync the `margin` JSDoc across all v2 `props.ts` files — link to the spacing guide + current-token example.
v2 READMEs	Convert legacy spacing keywords in `margin` examples to `general.*` tokens (value-preserving mapping).
Docs guide	Re-add the Layout Spacing page (removed on master during the docs rework) as a v11.7+ version-gated page, following the `theme-overrides` version-banner pattern.
Tests	era-3 dot-path resolution in `calcSpacingFromShorthand`; View v2 integration test (`general.spaceMd` → `0.75rem`); regression-test page examples.

Reviewer notes

Legacy → era-3 example mapping is value-preserving where an equivalent exists (small→general.spaceMd, medium→general.spaceXl, …). large/x-large have no general equivalent (scale tops out at 2rem) and compress to general.space2xl — the only intentional visual change, limited to doc examples.
Live doc examples use margin/padding only. These resolve era-3 dot-paths via calcSpacingFromShorthand. The Flex gap prop uses a separate flat-key resolver that doesn't understand dot-paths, so it's intentionally not shown with them.
Scope: v2 components only; the dot-path resolver / token-merge logic is unchanged.

Testing

pnpm run test:vitest emotion → 78 passed
pnpm run test:vitest ui-view → 16 passed
Visual regression (Cypress/Chromatic) not run; doc/regression page examples added for it.

Follow-ups (not in this PR)

padding prop examples still use legacy tokens (kept out of scope; easy identical sweep).
Misspelled tokens compile (type ends in (string & {})) and only warn at runtime — a louder dev-mode warning could be added later.

github-actions · 2026-06-10T12:38:06Z

PR Preview Action v1.8.1
🚀 View preview at https://instructure.design/pr-preview/pr-2587/
Built to branch `gh-pages` at 2026-07-07 16:05 UTC. Preview will be ready when the GitHub Pages deployment is complete.

github-actions · 2026-06-10T12:38:59Z

Visual regression report

⚠️ Changes detected.

Status	Count
Unchanged	31
Changed	1
New	0
Removed	0

📊 View full report

Diff images (1)

view.png — 411709 pixels differ

_{Baselines come from the visual-baselines branch. They refresh on every merge to master.}

ToMESSKa

I haven't checked all, but some of the v2 examples still use older spacing values in the margin prop (e.g. Alert, Badge), those should be updated too.

git-nandor

See my comment

git-nandor · 2026-06-15T12:40:43Z

-   * 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"`.


In v2 Avatar, Flex, FormFieldLayout, Link still recommend the legacy margin="small auto large"

matyasf

see my comments. Also looking at the token code, its really not clear for me where the tokens are coming from. Is it in SharedTokens or in Semantics? I guess its in SharedTokens, otherwise we could have different values for each theme. But then the token values from semaintics need to be deleted? e.g. ui-themes/src/themes/newThemeTokens/dark/semantics.ts vs ui-themes/src/themes/newThemeTokens/dark/sharedTokens.ts

matyasf · 2026-07-02T13:38:50Z

+type: embed
+---
+<Alert variant="warning" margin="0 0 medium">
+  The spacing tokens documented on this page (such as <code>general.spaceMd</code>) require <strong>v11.7+</strong> components and are applied through the <code>margin</code> and <code>padding</code> props. If you are viewing the v11.6 version, <Link href={window.location.pathname.match(/v\d+_\d+/) ? window.location.pathname.replace(/v\d+_\d+/, 'v11_7') : `/v11_7${window.location.pathname}`}>switch to v11.7</Link> to see the examples working correctly.


If you are viewing the v11.6 version, switch to v11.7 to see the examples working correctly.

no need for this text, it always shows 11.7

matyasf · 2026-07-02T14:11:42Z

+
+## Tokens
+
+### General scale


I would also add that the actual values are theme-dependent

matyasf · 2026-07-02T14:16:02Z

+| padding.card.md               | 0.75rem | 12px            |
+| padding.card.lg               | 1rem    | 16px            |
+
+## Applying spacing


I would also mention which part of our themes contain these tokens (is it in sharedTokens?)

@deprecated

…components Surface the current (era-3) spacing tokens (general.*, gap.*, padding.card.* dot-paths) on the `margin` prop of v2 components. View v2 already resolved them at runtime, but the `Spacing` type and component docs only advertised the older token eras. - emotion: add CurrentSpacingValues dot-path literals to the Spacing union and mark the legacy (era-1) and phased-out (era-2) unions as @deprecated - v2 components: sync the margin JSDoc across all v2 components to point at the spacing guide and use a current-token example - docs: re-add the Layout Spacing guide as a v11.7+ version-gated page, following the theme-overrides version-banner pattern; convert legacy margin values in v2 README examples to the current general.* tokens (value-preserving mapping) - tests: cover era-3 dot-path resolution in calcSpacingFromShorthand and add View v2 integration tests; add regression-test examples 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…anner Address review feedback on the Layout Spacing guide: - add a "Where these tokens come from" section explaining the primitives -> semantics -> sharedTokens.spacing -> prop pipeline, and that sharedTokens reshapes semantic tokens rather than owning values - note the tokens are theme-dependent in principle but uniform across the themes currently shipped - remove the version-gate banner and its "switch to v11.7" fallback link now that the docs site serves v11.7 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

balzss · 2026-07-07T15:58:44Z

@matyasf thanks — the "where do the tokens come from" question was a real doc gap, so I've added a "Where these tokens come from" section to the Layout Spacing guide that spells out the pipeline.

To answer directly: the margin/padding props resolve against sharedTokens.spacing (see ui-view/src/View/v2/styles.ts — it merges sharedTokens.spacing with sharedTokens.legacy.spacing). So your guess about SharedTokens is right about where the prop reads from.

But nothing in semantics.ts should be deleted — there's no duplication. sharedTokens.ts is a function (semantic: Semantics) => SharedTokens that doesn't hold values of its own; it references semantic.spacing.* and just reshapes it into the flat dot-path structure the prop API exposes (spacing.general.*, spacing.gap.*, spacing.padding.card.*). The layering is: primitives → semantics (source of truth, per theme) → sharedTokens (prop-facing view) → prop. Deleting the semantic spacing values would break sharedTokens, which reads from them.

On theme-dependence: because the values originate in each theme's semantic tokens, they can differ per theme — but all themes we currently ship resolve them to the same values (the ones in the tables). I've noted that in the guide too.

Also dropped the "switch to v11.7" banner text per your other comment.

github-actions Bot pushed a commit that referenced this pull request Jun 10, 2026

visual-regression: PR #2587 (20f340e) 20f340e

c54d5eb

balzss self-assigned this Jun 10, 2026

balzss marked this pull request as ready for review June 11, 2026 11:44

balzss requested review from HerrTopi, ToMESSKa and git-nandor June 11, 2026 11:44

ToMESSKa requested changes Jun 18, 2026

View reviewed changes

git-nandor requested changes Jun 18, 2026

View reviewed changes

HerrTopi removed their request for review June 23, 2026 09:59

balzss force-pushed the new-margin-spacing branch from 4eb8fa9 to 6da57ff Compare June 30, 2026 13:26

balzss requested review from HerrTopi, joyenjoyer and matyasf as code owners June 30, 2026 13:26

github-actions Bot pushed a commit that referenced this pull request Jun 30, 2026

visual-regression: PR #2587 (9e6ea9e) 9e6ea9e

4708079

balzss requested review from ToMESSKa and git-nandor June 30, 2026 14:28

git-nandor approved these changes Jul 1, 2026

View reviewed changes

ToMESSKa approved these changes Jul 2, 2026

View reviewed changes

matyasf requested changes Jul 2, 2026

View reviewed changes

HerrTopi removed their request for review July 7, 2026 07:06

joyenjoyer removed their request for review July 7, 2026 08:23

balzss and others added 2 commits July 7, 2026 17:42

balzss force-pushed the new-margin-spacing branch from 6da57ff to f3a2629 Compare July 7, 2026 16:01

balzss requested a review from matyasf July 7, 2026 16:01

github-actions Bot pushed a commit that referenced this pull request Jul 7, 2026

visual-regression: PR #2587 (f8adad2) f8adad2

897c77a

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(many): support current spacing tokens in the margin prop for v2 components#2587

feat(many): support current spacing tokens in the margin prop for v2 components#2587
balzss wants to merge 2 commits into
masterfrom
new-margin-spacing

balzss commented Jun 10, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 10, 2026 •

edited

Loading

Built to branch `gh-pages` at 2026-07-07 16:05 UTC.
Preview will be ready when the GitHub Pages deployment is complete.

Uh oh!

github-actions Bot commented Jun 10, 2026 •

edited

Loading

view.png — 411709 pixels differ

Uh oh!

ToMESSKa left a comment •

edited

Loading

Uh oh!

git-nandor left a comment

Uh oh!

git-nandor Jun 15, 2026

Uh oh!

matyasf left a comment •

edited

Loading

Uh oh!

matyasf Jul 2, 2026

Uh oh!

matyasf Jul 2, 2026

Uh oh!

matyasf Jul 2, 2026

Uh oh!

balzss commented Jul 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

balzss commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What & why

What changed

Reviewer notes

Testing

Follow-ups (not in this PR)

Uh oh!

github-actions Bot commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Built to branch gh-pages at 2026-07-07 16:05 UTC. Preview will be ready when the GitHub Pages deployment is complete.

Uh oh!

github-actions Bot commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Visual regression report

view.png — 411709 pixels differ

Uh oh!

ToMESSKa left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

git-nandor left a comment

Choose a reason for hiding this comment

Uh oh!

git-nandor Jun 15, 2026

Choose a reason for hiding this comment

Uh oh!

matyasf left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matyasf Jul 2, 2026

Choose a reason for hiding this comment

Uh oh!

matyasf Jul 2, 2026

Choose a reason for hiding this comment

Uh oh!

matyasf Jul 2, 2026

Choose a reason for hiding this comment

Uh oh!

balzss commented Jul 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

balzss commented Jun 10, 2026 •

edited

Loading

github-actions Bot commented Jun 10, 2026 •

edited

Loading

Built to branch `gh-pages` at 2026-07-07 16:05 UTC.
Preview will be ready when the GitHub Pages deployment is complete.

github-actions Bot commented Jun 10, 2026 •

edited

Loading

ToMESSKa left a comment •

edited

Loading

matyasf left a comment •

edited

Loading