Skip to content

Commit 766d791

Browse files
balzssclaude
andcommitted
docs(instructure-ui): clarify spacing token source and drop version banner
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>
1 parent 1b47c5f commit 766d791

1 file changed

Lines changed: 9 additions & 8 deletions

File tree

docs/guides/layout-spacing.md

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -7,19 +7,20 @@ relevantForAI: true
77

88
## Layout Spacing
99

10-
```js
11-
---
12-
type: embed
13-
---
14-
<Alert variant="warning" margin="0 0 medium">
15-
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.
16-
</Alert>
17-
```
10+
The spacing tokens documented on this page (such as `general.spaceMd`) require **v11.7+** components and are applied through the `margin` and `padding` props.
1811

1912
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).
2013

2114
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.
2215

16+
### Where these tokens come from
17+
18+
A 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:
19+
20+
`primitives` (raw `rem` values) → `semantics.spacing` (named tokens per theme) → `sharedTokens.spacing` (the dot-paths this page documents) → the `margin` / `padding` prop.
21+
22+
Because 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).
23+
2324
## Tokens
2425

2526
### General scale

0 commit comments

Comments
 (0)