Skip to content

docs: update upgrade-guide #2590

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
git-nandor merged 1 commit into from
Jun 16, 2026
+27 −13
Merged

docs: update upgrade-guide #2590

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 27 additions & 13 deletions docs/upgrading/upgrade-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,12 @@ order: 2

## New theming system

InstUI v11.7 introduces a new theming engine. Components imported from `/v11_7` (the `v2` label in the docs "Component version" selector) consume design tokens directly from the active theme. Components imported from `/v11_6` (the `v1` label) continue to use the legacy `generateComponentTheme` approach. **Both engines run side-by-side in the same app without conflict** — you can migrate component-by-component on your own schedule.
InstUI v11.7 introduces a new theming engine. Components imported from `/v11_7` consume design tokens directly from the active theme. Components imported from `/v11_6` continue to use the legacy `generateComponentTheme` approach. **Both engines run side-by-side in the same app without conflict** — you can migrate component-by-component on your own schedule.

### What's different

- **Layered token model.** Tokens are organized as **primitives** (raw values like colors and spacings) → **semantics** (contextual mappings like `color.text.base`) → **components** (per-component tokens). Cross-component concerns such as focus rings and box shadows live in `sharedTokens`. Most overrides happen at the component layer.
- **No per-component `theme.ts`.** v2 components don't define a `generateComponentTheme` function, their tokens are emitted by the active theme rather than computed by the component itself.
- **No per-component `theme.ts`.** v11.7 components don't define a `generateComponentTheme` function, their tokens are emitted by the active theme rather than computed by the component itself.

### New themes

Expand All @@ -24,7 +24,7 @@ The new engine ships four themes:
- **`light`** — new light theme.
- **`dark`** — new dark theme.

The legacy `canvas` and `canvasHighContrast` themes still exist and remain the correct choice for v1 components.
The legacy `canvas` and `canvasHighContrast` themes still exist and remain the correct choice for v11.6 components.

### Override mechanism

Expand All @@ -34,8 +34,22 @@ The two entry points are the same as in the legacy system:
- **Per-component** — `themeOverride` prop directly on a single component instance. Has the highest priority and overrides any provider-level setting for that instance.

What changed:

- **Theme overrides**: in v11.7 `InstUISettingsProvider`'s theme prop only accepts a full theme object. For v11.7 or later use the new `themeOverride` prop
- **Token names/values**: Lots of components had their theme tokens changed -- removed, added or renamed. Check the rest of this guide for the full list of changes.
- **Branding (`ic-brand-*` variables)**: the legacy Canvas `ic-brand-*` variables are now exposed under `semantics.color.institutional.*` in the new theming system. Branding overrides are supported on the `canvas` (legacy) theme. Support for the new `light` and `dark` themes is coming soon. High-contrast themes will never accept branding overrides, by design.

| Legacy variable | New semantic token |
| --------------------------------------------------- | --------------------------------------- |
| `ic-brand-primary` | `brandPrimary` |
| `ic-brand-font-color-dark` | `brandFontColorDark` |
| `ic-link-color` | `linkColor` |
| `ic-brand-button--primary-bgd` | `brandButtonPrimaryBgd` |
| `ic-brand-button--primary-text` | `brandButtonPrimaryText` |
| `ic-brand-global-nav-bgd` | `brandGlobalNavBgd` |
| `ic-global-nav-link-hover` | `globalNavLinkHover` |
| `ic-brand-global-nav-menu-item__text-color` | `brandGlobalNavMenuItemTextColor` |
| `ic-brand-global-nav-menu-item__text-color--active` | `brandGlobalNavMenuItemTextColorActive` |

`themeOverride` remains separate from the `theme` prop — `theme` swaps the active theme entirely, `themeOverride` layers changes on top. See [New theme overrides](new-theme-overrides) for subtree-scoped overrides, primitives / semantics overrides, shared tokens, and priority rules.

Expand Down Expand Up @@ -63,7 +77,7 @@ The recommended path uses the **`updateInstUIImportVersions` codemod**

3. **Switch the theme.** Replace `canvas` with `legacyCanvas` wherever the bumped components live — visuals stay identical and the new override surface becomes available. Use `light` or `dark` for a redesign. The `theme` prop on `InstUISettingsProvider` can scope this to a subtree.

4. **Update per-component theme overrides.** Many v2 components have renamed / added / removed tokens — see the component-specific sections below for the exact changes.
4. **Update per-component theme overrides.** Many v11.7 components have renamed / added / removed tokens — see the component-specific sections below for the exact changes.

### Further reading

Expand Down Expand Up @@ -435,7 +449,7 @@ type: embed

### CloseButton

CloseButton no longer has its own dedicated theme tokens in v2. Offset spacing now uses `sharedTokens.spacing`, and visual styling comes from BaseButton tokens.
CloseButton no longer has its own dedicated theme tokens in v11.7. Offset spacing now uses `sharedTokens.spacing`, and visual styling comes from BaseButton tokens.

```js
---
Expand Down Expand Up @@ -497,9 +511,9 @@ type: embed

Now that InstUI supports component versioning, we no longer need the separate `DateInput2` name. Instead:

- **[DateInput v2](/v11_7/DateInput)** (from v11.7) — the recommended version. Same component that was previously `DateInput2`, same API. **This is the only version that will receive the new theming.**
- **[DateInput v1](/v11_6/DateInput)** (up to v11.6) — the original component. **Deprecated.** Does not support the new theming system.
- **[DateInput2 v1](/v11_6/DateInput2)** — **Deprecated.** Will not get a v2 and does not support the new theming system. If you're using `DateInput2`, switch your import to `DateInput` (from v11.7) — the API is identical, no other code changes needed.
- **[DateInput (v11.7)](/v11_7/DateInput)** — the recommended version. Same component that was previously `DateInput2`, same API. **This is the only version that will receive the new theming.**
- **[DateInput (v11.6)](/v11_6/DateInput)** — the original component. **Deprecated.** Does not support the new theming system.
- **[DateInput2 (v11.6)](/v11_6/DateInput2)** — **Deprecated.** Will not get a v11.7 version and does not support the new theming system. If you're using `DateInput2`, switch your import to `DateInput` (in v11.7) — the API is identical, no other code changes needed.

### DateTimeInput

Expand All @@ -519,7 +533,7 @@ Now that InstUI supports component versioning, we no longer need the separate `D
| ------------ | ------------------------------------- | --------------------------------------------------------- |
| `dateFormat` | Moment.js format string (e.g. `'LL'`) | Locale string (e.g. `'en-US'`) or `{ parser, formatter }` |

If you were passing a Moment format string like `dateFormat="LL"`, replace it with a locale string or a custom `{ parser, formatter }` object. If you were relying on the default `'LL'` format, note that v2 now uses the locale's default date format (e.g. `1/18/2018` in `en-US`) instead of the long format (e.g. `January 18, 2018`). To preserve the long format, pass a custom `{ parser, formatter }` object.
If you were passing a Moment format string like `dateFormat="LL"`, replace it with a locale string or a custom `{ parser, formatter }` object. If you were relying on the default `'LL'` format, note that v11.7 now uses the locale's default date format (e.g. `1/18/2018` in `en-US`) instead of the long format (e.g. `January 18, 2018`). To preserve the long format, pass a custom `{ parser, formatter }` object.

**New props:**

Expand Down Expand Up @@ -549,15 +563,15 @@ type: code
/>
```

#### DateTimeInput v1 → v2 API changes
#### DateTimeInput v11.6 → v11.7 API changes

**Removed props:**

| Removed prop | Replacement |
| --------------------- | -------------------------------- |
| `renderWeekdayLabels` | Built in — no replacement needed |

**New props in v2:**
**New props in v11.7:**

| New prop | Description |
| ------------------ | ------------------------------------------------------------------------------------------ |
Expand All @@ -566,13 +580,13 @@ type: code
| `withYearPicker` | Optional. Enables a year dropdown in the calendar. |

```jsx
// v1
// v11.6
<DateTimeInput
prevMonthLabel="Previous month"
nextMonthLabel="Next month"
/>

// v2
// v11.7
<DateTimeInput
prevMonthLabel="Previous month"
nextMonthLabel="Next month"
Expand Down
Loading