docs: restore full version display in side nav and add new Component versioning guide page

Author: git-nandor

docs/guides/component-versioning.md

@@ -0,0 +1,93 @@
+---
+title: Component versioning
+category: Guides
+order: 5
+---
+
+## Why components are versioned
+
+When InstUI needs to make a breaking change to a component (renamed props, changed behaviour, etc.), the old version is **kept alongside the new one** instead of being replaced. Upgrading the library no longer forces you to immediately rewrite every component usage — you can migrate to new versions on your own schedule.
+
+New component versions appear with InstUI **minor** version bumps (e.g. `11.7` → `11.8`). Patch releases never include breaking changes.
+
+## Import paths
+
+Every InstUI component package supports three import styles:
+
+### Default — `@instructure/ui-<name>`
+
+Always points to the **oldest** still-supported component version. Upgrading the library without changing your imports will keep your code working without surprises.
+
+```js
+---
+type: code
+---
+import { Alert } from '@instructure/ui-alerts'
+```
+
+### Pinned — `@instructure/ui-<name>/v11_X`
+
+Locks the import to a specific InstUI minor version of the component. When you are ready to adopt a breaking change, update the path to the next pinned version.
+
+```js
+---
+type: code
+---
+import { Alert } from '@instructure/ui-alerts/v11_7'
+```
+
+### Latest — `@instructure/ui-<name>/latest`
+
+Always points to the newest component version. This may bring breaking changes when you upgrade InstUI itself.
+
+```js
+---
+type: code
+---
+import { Alert } from '@instructure/ui-alerts/latest'
+```
+
+### Per-package or umbrella package
+
+InstUI also ships an umbrella package, `@instructure/ui`, which re-exports every component from the individual `@instructure/ui-*` packages. Two equivalent import styles work — both resolve to the same component:
+
+```js
+---
+type: code
+---
+// per-package import
+import { Alert } from '@instructure/ui-alerts/v11_7'
+
+// umbrella package import
+import { Alert } from '@instructure/ui/v11_7'
+```
+
+The same three path styles (default / `/v11_X` / `/latest`) work on the umbrella package as well. Pick per-package imports when you want better tree-shaking and only pull in what you use, or the umbrella package when you'd rather depend on a single `@instructure/ui` entry in your `package.json`.
+
+## Versions and theming engines
+
+InstUI is in the middle of a transition between two theming systems. Which engine a component uses depends on which version you import:
+
+- **`v11_6` and earlier** — legacy theming. Components are configured through the Canvas theme variables and the `themeOverride` prop, which accepts a function or object that maps to the component's own theme map. See the [Legacy theme overrides](legacy-theme-overrides) guide.
+
+- **`v11_7` and newer** — new theming system. Components consume pre-resolved design tokens, and theming is done through the new token override structure. See the [New theme overrides](new-theme-overrides) guide.
+
+Mixing imports from both groups in the same app is fully supported — the two engines run side-by-side without conflict.
+
+### Supported themes per version
+
+Each version of the library is only compatible with the themes built for its theming engine:
+
+- **`v11_6` and earlier** support the legacy themes:
+
+  - `canvas`
+  - `canvasHighContrast`
+
+- **`v11_7` and newer** support themes built on the new token system. The legacy Canvas looks are preserved (re-implemented on the new engine) and two brand-new themes are added:
+
+  - `legacyCanvas` — same visual style as the old `canvas`, but on the new engine
+  - `legacyCanvasHighContrast` — same visual style as the old `canvasHighContrast`, on the new engine
+  - `light` — new light theme
+  - `dark` — new dark theme
+
+This means that when you move a component import from `/v11_6` to `/v11_7` you don't have to change anything visually — you can stay on the `legacyCanvas` theme and opt in to `light` or `dark` only when you're ready.

docs/theming/legacy-theme-overrides.md

@@ -7,15 +7,6 @@ relevantForAI: true
 
 ## Using theme overrides
 
-```js
----
-type: embed
----
-<Alert variant="warning" margin="0 0 medium">
-  The examples on this page use the <strong>legacy theming system</strong> and are designed for <strong>v11.6</strong> components. If you are viewing the v11.7 version, <Link href={window.location.pathname.match(/v\d+_\d+/) ? window.location.pathname.replace(/v\d+_\d+/, 'v11_6') : `/v11_6${window.location.pathname}`}>switch to v11.6</Link> to see the examples working correctly.
-</Alert>
-```
-
 This document gives an overview on how you can customize Instructure UI components by tweaking their theme variables.
 While this gives you a level of flexibility on the look and feel of the components you should be aware of 2 things:
 

docs/theming/new-theme-overrides.md

@@ -7,15 +7,6 @@ relevantForAI: true
 
 ## New Theme Override Patterns
 
-```js
----
-type: embed
----
-<Alert variant="warning" margin="0 0 medium">
-  The examples on this page use the <strong>new theming system</strong> and require <strong>v11.7+</strong> components. 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.
-</Alert>
-```
-
 This guide covers all the override patterns available in the new theming system (v11.7+). The new system uses a layered token architecture: **primitives** (raw values) -> **semantics** (meaning) -> **components** (per-component tokens).
 
 Overrides are applied via the `themeOverride` prop on `InstUISettingsProvider`, which is separate from the `theme` prop. The `theme` prop replaces the active theme entirely; `themeOverride` layers modifications on top.

packages/__docs__/src/App/index.tsx

@@ -625,7 +625,7 @@ class App extends Component<AppProps, AppState> {
 
     const formatMinorVersion = (version: string) => {
       const formatted = version.replace(/_/g, '.')
-      if (version === 'v11_7') return `${formatted}`
+      if (version === 'v11_6') return `${formatted} (legacy theming)`
       return formatted
     }
 
@@ -635,10 +635,15 @@ class App extends Component<AppProps, AppState> {
         ? this.state.themeKey
         : themeKeys[0]
 
-    const { key } = this.state
+    const { key, docsData } = this.state
     const versionLockedPages = ['legacy-theme-overrides', 'new-theme-overrides']
     if (versionLockedPages.includes(key ?? '')) return null
 
+    // Only show on Components pages — other categories (guides, utilities,
+    // themes, etc.) don't need theme or component-version switching.
+    const category = key ? docsData?.docs[key]?.category : undefined
+    if (!category || !category.startsWith('components')) return null
+
     const showMinorVersionSelect =
       minorVersionsData && minorVersionsData.libraryVersions.length > 1
 
@@ -825,8 +830,9 @@ class App extends Component<AppProps, AppState> {
         {this.renderThemeSelect()}
         {isGuidePage && (
           <Alert variant="info" margin="xx-large 0">
-            This page always displays the latest version of the documentation.{' '}
-            <Link href="multi-version-system">
+            This page is made for the latest version (
+            {this.getLatestMinorVersion()?.replace('_', '.')}) of InstUI.{' '}
+            <Link href="component-versioning">
               Learn more about the versioning system
             </Link>
           </Alert>

packages/__docs__/src/Header/index.tsx

@@ -84,15 +84,12 @@ class Header extends Component<HeaderProps> {
   }
 
   /**
-   * Returns the version string for display: major only (e.g. "v10") when
-   * minor version switcher is active, full semver otherwise.
+   * Returns the full semver string for display (e.g. "11.7.0").
+   * Minor-version switching is handled in the Component version Select
+   * on Components pages, so we always show the precise library version here.
    */
   getDisplayVersion = () => {
-    const { version, minorVersionsData } = this.props
-    if (minorVersionsData && version) {
-      return version.split('.')[0]
-    }
-    return version
+    return this.props.version
   }
 
   renderVersionsBlock = () => {