docs: improve multi-version docs behavior and routing and add new Component versioning guide page

Author: git-nandor

docs/guides/accessing-the-dom.md

@@ -1,7 +1,7 @@
 ---
 title: Accessing the DOM
 category: Guides
-order: 3
+order: 4
 relevantForAI: true
 ---
 

docs/guides/component-versioning.md

@@ -0,0 +1,95 @@
+---
+title: Component versioning
+category: Guides
+order: 2
+---
+
+## 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.
+
+> The docs UI "Component version" selector labels library `v11_6` as **`v1 (legacy)`** and library `v11_7` as **`v2`**. This page uses the `v11_X` form because it matches the actual NPM import paths.
+
+## 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:
+
+- **`v1`** (library `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.
+
+- **`v2`** (library `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:
+
+- **`v1`** (library `v11_6` and earlier) supports the legacy themes:
+
+  - `canvas`
+  - `canvasHighContrast`
+
+- **`v2`** (library `v11_7` and newer) supports 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/guides/forms.md

@@ -1,7 +1,7 @@
 ---
 title: Forms
 category: Guides
-order: 4
+order: 5
 relevantForAI: true
 ---
 

docs/guides/module-federation.md

@@ -1,7 +1,7 @@
 ---
 title: Module federation
 category: Guides
-order: 2
+order: 3
 relevantForAI: true
 ---
 

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.
@@ -527,9 +518,52 @@ type: example
 </InstUISettingsProvider>
 ```
 
-### 13. Provider-level overrides cannot target a child component selectively
+### 13. Independent overrides for child parts of compound components
+
+Most compound components expose each part as a separate component with its own `componentId`. This means you can independently override each part via `components` — both overrides take effect:
+
+```js
+---
+type: example
+---
+<InstUISettingsProvider theme={canvas}>
+  <InstUISettingsProvider
+    themeOverride={{
+      components: {
+        TableColHeader: {
+          background: 'rebeccapurple',
+          color: 'gold'
+        },
+        TableRowHeader: {
+          background: 'deeppink',
+          color: 'white'
+        }
+      }
+    }}
+  >
+    <Table caption="Independent overrides: ColHeader purple, RowHeader deeppink">
+      <Table.Head>
+        <Table.Row>
+          <Table.ColHeader id="h-row">TableColHeader — purple</Table.ColHeader>
+          <Table.ColHeader id="h-col">TableColHeader — purple</Table.ColHeader>
+        </Table.Row>
+      </Table.Head>
+      <Table.Body>
+        <Table.Row>
+          <Table.RowHeader>TableRowHeader — deeppink</Table.RowHeader>
+          <Table.Cell>TableCell — unchanged</Table.Cell>
+        </Table.Row>
+                <Table.Row>
+          <Table.RowHeader>TableRowHeader — deeppink</Table.RowHeader>
+          <Table.Cell>TableCell — unchanged</Table.Cell>
+        </Table.Row>
+      </Table.Body>
+    </Table>
+  </InstUISettingsProvider>
+</InstUISettingsProvider>
+```
 
-Because `Button` uses `BaseButton`'s theme internally, a `components.Button` entry in the provider's `themeOverride` does **not** override `BaseButton`'s tokens for `Button` instances only. Both `BaseButton` and `Button` share the same `BaseButton` theme variables, so a `components.BaseButton` override affects both, regardless of whether a separate `components.Button` entry is also present.
+**Exception — `Button` and `BaseButton`:** `Button` uses `BaseButton`'s `componentId` internally, so `components.Button` has no effect. A `components.BaseButton` override affects all `BaseButton` instances including those rendered inside `Button` — there is no way to target only one:
 
 ```js
 ---

packages/__docs__/src/App/index.tsx

@@ -302,9 +302,10 @@ class App extends Component<AppProps, AppState> {
     fetchMinorVersionData(signal)
       .then((minorVersionsData) => {
         if (minorVersionsData && minorVersionsData.libraryVersions.length > 0) {
-          // If URL has a version, use it; otherwise use default
-          const selectedMinorVersion =
-            urlMinorVersion ?? minorVersionsData.defaultVersion
+          const { libraryVersions } = minorVersionsData
+          const latestVersion = libraryVersions[libraryVersions.length - 1]
+          // If URL has a version, use it; otherwise use the latest version
+          const selectedMinorVersion = urlMinorVersion ?? latestVersion
           // Update globals before fetching docs so renders use correct components
           updateGlobalsForVersion(selectedMinorVersion)
           this.setState({
@@ -342,6 +343,48 @@ class App extends Component<AppProps, AppState> {
     ) {
       this.handleNavigationFocusRegion()
     }
+
+    if (prevState.key !== this.state.key) {
+      this.handleMinorVersionForPage(this.state.key)
+    }
+
+    if (!prevState.minorVersionsData && this.state.minorVersionsData) {
+      this.handleMinorVersionForPage(this.state.key)
+    }
+  }
+
+  getLatestMinorVersion = () => {
+    const { minorVersionsData } = this.state
+    if (!minorVersionsData) return undefined
+    const { libraryVersions } = minorVersionsData
+    return libraryVersions[libraryVersions.length - 1]
+  }
+
+  handleMinorVersionForPage = (key: string | undefined) => {
+    const { selectedMinorVersion, minorVersionsData, docsData } = this.state
+    if (!minorVersionsData || !selectedMinorVersion || !key) return
+
+    const latestVersion = this.getLatestMinorVersion()!
+
+    if (key === 'legacy-theme-overrides') {
+      if (selectedMinorVersion !== 'v11_6') {
+        this.handleMinorVersionChange('v11_6')
+      }
+    } else if (key === 'new-theme-overrides') {
+      if (selectedMinorVersion !== latestVersion) {
+        this.handleMinorVersionChange(latestVersion)
+      }
+    } else {
+      const category = docsData?.docs[key]?.category
+      const isGuidePage =
+        !!category &&
+        !category.startsWith('components') &&
+        !category.startsWith('utilities')
+      if (isGuidePage && selectedMinorVersion !== latestVersion) {
+        // Guide pages (.md) always show with the latest version
+        this.handleMinorVersionChange(latestVersion)
+      }
+    }
   }
 
   componentWillUnmount() {
@@ -555,8 +598,9 @@ class App extends Component<AppProps, AppState> {
   }
 
   renderThemeSelect() {
+    const { minorVersionsData, selectedMinorVersion } = this.state
     const allThemeKeys = Object.keys(this.state.docsData!.themes)
-    const showNewThemes = this.state.selectedMinorVersion !== 'v11_6'
+    const showNewThemes = selectedMinorVersion !== 'v11_6'
 
     const themeKeys = showNewThemes
       ? allThemeKeys.filter(
@@ -579,17 +623,56 @@ class App extends Component<AppProps, AppState> {
       return themeKey
     }
 
+    const formatMinorVersion = (version: string) => {
+      if (version === 'v11_6') return 'v1 (legacy)'
+      if (version === 'v11_7') return 'v2'
+      return version.replace(/_/g, '.')
+    }
+
     const smallScreen = this.state.layout === 'small'
     const currentThemeKey =
       this.state.themeKey && themeKeys.includes(this.state.themeKey)
         ? this.state.themeKey
         : themeKeys[0]
 
+    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
+
     return themeKeys.length > 1 ? (
       <Flex
         margin={smallScreen ? 'none none medium' : 'none none x-small'}
         justifyItems={!smallScreen ? 'end' : 'start'}
+        wrap="wrap"
+        gap="small"
       >
+        {showMinorVersionSelect && (
+          <Flex.Item shouldGrow={smallScreen} shouldShrink={smallScreen}>
+            <Select
+              name="minorVersion"
+              renderLabel="Component version"
+              onChange={(_e, { value }) => {
+                if (value) this.handleMinorVersionChange(value as string)
+              }}
+              value={selectedMinorVersion ?? this.getLatestMinorVersion()}
+              width="16.5rem"
+            >
+              {[...minorVersionsData!.libraryVersions].reverse().map((ver) => (
+                <option key={ver} value={ver}>
+                  {formatMinorVersion(ver)}
+                </option>
+              ))}
+            </Select>
+          </Flex.Item>
+        )}
         <Flex.Item shouldGrow={smallScreen} shouldShrink={smallScreen}>
           <Select
             name="theme"
@@ -741,9 +824,19 @@ class App extends Component<AppProps, AppState> {
     // New-theme components are looked up via themeVariables.newTheme.components
     const themeVariables = themes[themeKey!].resource as ThemeType
     const heading = currentData.extension !== '.md' ? currentData.title : ''
+    const isGuidePage = currentData.extension === '.md'
     const documentContent = (
       <View as="div" padding="x-large none none">
         {this.renderThemeSelect()}
+        {isGuidePage && (
+          <Alert variant="info" margin="xx-large 0">
+            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>
+        )}
         <View
           elementRef={this.mainContentRef}
           tabIndex={0}
@@ -997,8 +1090,6 @@ class App extends Component<AppProps, AppState> {
           version={version}
           versionsData={versionsData}
           minorVersionsData={this.state.minorVersionsData}
-          selectedMinorVersion={this.state.selectedMinorVersion}
-          onMinorVersionChange={this.handleMinorVersionChange}
         />
 
         <Nav