docs: add version alerts and fix for child components theme section

Author: git-nandor

docs/guides/forms.md

@@ -71,6 +71,15 @@ const PasswordExample = () => {
 render(<PasswordExample/>)
 ```
 
+```js
+---
+type: embed
+---
+<Alert variant="warning" margin="0 0 medium">
+  The following section describes behavior introduced in <strong>v11.7</strong>: the updated <code>error</code> type and the required asterisk feature. 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 these features working correctly.
+</Alert>
+```
+
 The `error` type has been updated to meet accessibility requirements with proper icons and visual styling. Previously, there was a `newError` type that provided this enhanced behavior, but it has been consolidated into the standard `error` type for consistency. `newError` has been deprecated.
 
 We also introduced the "required asterisk" which displays an `*` character next to field labels that are required. This update applies to **all** InstUI form components, so if you were relying on a custom solution for this feature before, you need to remove that to avoid having double asterisks.

docs/theming/legacy-theme-overrides.md

@@ -7,6 +7,15 @@ 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

@@ -1,12 +1,21 @@
 ---
-title: New Theme Overrides
+title: New theme overrides
 category: Theming
 order: 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.

docs/upgrading/upgrade-guide.md

@@ -1,5 +1,5 @@
 ---
-title: Upgrade Guide for multi version (beta)
+title: Upgrade Guide for multi version
 category: Upgrading
 order: 9999999
 ---
@@ -72,23 +72,6 @@ type: embed
 
 ```
 
-### Billboard
-
-```js
----
-type: embed
----
-<V12ChangelogTable
-  removed={[
-    {name:"iconHoverColorInverse",note:""},
-    {name:"iconHoverColor",note:""},
-    {name:"iconColor",note:""},
-    {name:"messageColorInverse",note:""}
-  ]}
-/>
-
-```
-
 ### BaseButton
 
 All button components (Button, IconButton, CondensedButton) share BaseButton's theme tokens.
@@ -229,20 +212,18 @@ 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.
+### Billboard
 
 ```js
 ---
 type: embed
 ---
 <V12ChangelogTable
   removed={[
-    {name:"offsetMedium",note:"now uses sharedTokens.spacing"},
-    {name:"offsetSmall",note:"now uses sharedTokens.spacing"},
-    {name:"offsetXSmall",note:"now uses sharedTokens.spacing"},
-    {name:"zIndex",note:"hardcoded to 1"}
+    {name:"iconHoverColorInverse",note:""},
+    {name:"iconHoverColor",note:""},
+    {name:"iconColor",note:""},
+    {name:"messageColorInverse",note:""}
   ]}
 />
 
@@ -392,6 +373,62 @@ 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.
+
+```js
+---
+type: embed
+---
+<V12ChangelogTable
+  removed={[
+    {name:"offsetMedium",note:"now uses sharedTokens.spacing"},
+    {name:"offsetSmall",note:"now uses sharedTokens.spacing"},
+    {name:"offsetXSmall",note:"now uses sharedTokens.spacing"},
+    {name:"zIndex",note:"hardcoded to 1"}
+  ]}
+/>
+
+```
+
+### ColorPicker
+
+```js
+---
+type: embed
+---
+<V12ChangelogTable
+  removed={[
+    {name:"warningIconColor",note:""},
+    {name:"errorIconColor",note:""},
+    {name:"successIconColor",note:""},
+    {name:"spacing",note:"now uses sharedTokens.spacing"}
+  ]}
+/>
+
+```
+
+### DataPermissionLevels
+
+```js
+---
+type: embed
+---
+<V12ChangelogTable
+  added={[
+    {name:"contentContainerBorderRadius",note:""},
+    {name:"contentContainerColor",note:""}
+  ]}
+  removed={[
+    {name:"cardPadding",note:""},
+    {name:"cardExplainerContainerBottomMargin",note:""},
+    {name:"cardGap",note:""}
+  ]}
+/>
+
+```
+
 ### DateInput / DateInput2
 
 **Short version:** Use [`DateInput`](/v11_7/DateInput). Forget `DateInput2` exists.
@@ -452,26 +489,6 @@ type: code
 />
 ```
 
-### DataPermissionLevels
-
-```js
----
-type: embed
----
-<V12ChangelogTable
-  added={[
-    {name:"contentContainerBorderRadius",note:""},
-    {name:"contentContainerColor",note:""}
-  ]}
-  removed={[
-    {name:"cardPadding",note:""},
-    {name:"cardExplainerContainerBottomMargin",note:""},
-    {name:"cardGap",note:""}
-  ]}
-/>
-
-```
-
 #### DateTimeInput v1 → v2 API changes
 
 **Removed props:**
@@ -504,23 +521,6 @@ type: embed
 />
 ```
 
-### ColorPicker
-
-```js
----
-type: embed
----
-<V12ChangelogTable
-  removed={[
-    {name:"warningIconColor",note:""},
-    {name:"errorIconColor",note:""},
-    {name:"successIconColor",note:""},
-    {name:"spacing",note:"now uses sharedTokens.spacing"}
-  ]}
-/>
-
-```
-
 ### Drilldown
 
 Drilldown itself has no token changes. However, its sub-components share tokens with Options components, so the token changes listed under Options apply here as well:
@@ -1164,40 +1164,40 @@ type: embed
 
 ```
 
-### Rating
+### RangeInput
+
+- `thumbVariant` prop has been removed. The component now always renders the previously-`accessible` thumb (better color contrast, border, and inset focus ring).
 
 ```js
 ---
 type: embed
 ---
 <V12ChangelogTable
   removed={[
-    {name:"smallIconFontSize",note:""},
-    {name:"mediumIconFontSize",note:""},
-    {name:"largeIconFontSize",note:""}
+    {name:"handleFocusRingSize",note:"style uses sharedTokens.focusOutline.width token"},
+    {name:"handleFocusRingColor",note:"style uses sharedTokens.focusOutline.onColor token"}
+  ]}
+  changed={[
+    {oldName:"handleShadow",newName:"boxShadow",note:""},
+    {oldName:"valueSmallPadding",newName:"valueSmallPadding",note:"now only sets horizontal padding of the value"},
+    {oldName:"valueMediumPadding",newName:"valueMediumPadding",note:"now only sets horizontal padding of the value"},
+    {oldName:"valueLargePadding",newName:"valueLargePadding",note:"now only sets horizontal padding of the value"}
   ]}
 />
 
 ```
 
-### RangeInput
-
-- `thumbVariant` prop has been removed. The component now always renders the previously-`accessible` thumb (better color contrast, border, and inset focus ring).
+### Rating
 
 ```js
 ---
 type: embed
 ---
 <V12ChangelogTable
   removed={[
-    {name:"handleFocusRingSize",note:"style uses sharedTokens.focusOutline.width token"},
-    {name:"handleFocusRingColor",note:"style uses sharedTokens.focusOutline.onColor token"}
-  ]}
-  changed={[
-    {oldName:"handleShadow",newName:"boxShadow",note:""},
-    {oldName:"valueSmallPadding",newName:"valueSmallPadding",note:"now only sets horizontal padding of the value"},
-    {oldName:"valueMediumPadding",newName:"valueMediumPadding",note:"now only sets horizontal padding of the value"},
-    {oldName:"valueLargePadding",newName:"valueLargePadding",note:"now only sets horizontal padding of the value"}
+    {name:"smallIconFontSize",note:""},
+    {name:"mediumIconFontSize",note:""},
+    {name:"largeIconFontSize",note:""}
   ]}
 />
 
@@ -1504,6 +1504,12 @@ type: embed
 
 ```
 
+### TopNavBar
+
+#### TopNavBar.Brand
+
+The deprecated `renderName` and `nameBackground` props have been removed. Please remove them from your code.
+
 ### Tray
 
 ```js
@@ -1527,12 +1533,6 @@ type: embed
 
 ```
 
-### TopNavBar
-
-#### TopNavBar.Brand
-
-The deprecated `renderName` and `nameBackground` props have been removed. Please remove them from your code.
-
 ### TreeBrowser
 
 #### Icon system migration

packages/__docs__/src/Document/index.tsx

@@ -378,7 +378,10 @@ import { ${importName} } from '${esPath}'
         {this.renderProps(doc)}
         {this.renderTheme(doc)}
       </div>
-    ) : null
+    ) : (
+      // Props-free components (e.g. Menu.Separator) still need their theme section rendered
+      this.renderTheme(doc)
+    )
   }
 
   hasDetails(doc: DocDataType) {