docs: fix based on reviews

Author: git-nandor

docs/contributing/agentic-coding.md …tributing/building-and-running-instui.mddocs/contributing/agentic-coding.md renamed to docs/contributing/building-and-running-instui.md docs/contributing/agentic-coding.md renamed to docs/contributing/building-and-running-instui.md

@@ -1,5 +1,5 @@
 ---
-title: Agentic coding
+title: Building and running InstUI
 category: Contributing
 order: 2
 ---

docs/contributing/contributing-getting-started.md

@@ -23,7 +23,7 @@ constructed from the existing ones. For these reasons adding a new component has
 
 ### Building InstUI from the source
 
-Please follow the steps on the [how to build guide page](agentic-coding).
+Please follow the steps on the [how to build guide page](building-and-running-instui).
 
 ### Running the documentation app
 

docs/contributing/multi-version-system.md

@@ -312,5 +312,3 @@ When you add a breaking change to a component, you manually add the new `./v11_8
 3. **Implement** breaking changes in the new version (keep `/latest` imports)
 4. **Create** a new lettered export file that exports all components at their latest versions
 5. **Update** `package.json` exports: add the new `./vX_Y` entry and point `./latest` to the new letter
-
-For information on how documentation is versioned alongside components, see the [Docs Versioning](/docs-versioning) guide.

docs/contributing/versioning/docs-versioning.md

@@ -15,7 +15,6 @@ The following steps will create a React app that uses Instructure UI. Recommende
 ---
 type: code
 ---
-
 npm create vite@latest my-cool-app
 ```
 
@@ -63,7 +62,7 @@ export default App
 
 What does this code do?
 
-- [InstUISettingsProvider](InstUISettingsProvider) allows to specify the text direction (default is the direction that the user's browser supplies) and the theme to your application. InstUI components require a theme to work, all components are themeable, and themes control their look and feel. There are 2 built-in themes: [`canvas`](canvas) and [`canvasHighContrast`](canvas-high-contrast). The component examples seen throughout the documentation use the [canvas theme](canvas) by default.
+- [InstUISettingsProvider](InstUISettingsProvider) allows to specify the text direction (default is the direction that the user's browser supplies) and the theme to your application. InstUI components require a theme to work, all components are themeable, and themes control their look and feel. Starting from v11.7 there are 4 built-in themes: [`canvas`](canvas), [`canvas-high-contrast`](canvas-high-contrast), [`light`](light) and [`dark`](dark). For v11.6 components the legacy themes [`legacy-canvas`](legacy-canvas) and [`legacy-canvas-high-contrast`](legacy-canvas-high-contrast) are available. The component examples seen throughout the documentation use the [canvas theme](canvas) by default.
 - [Button](Button) is an Instructure UI button component
 
 Finally, run `pnpm run dev` to start up a basic development server.

docs/guides/guides-getting-started.md

@@ -5,7 +5,14 @@ id: UsingIcons
 relevantForAI: true
 ---
 
-Note: These icons are only meant to be used with the new theming system (beta), please don't use them with the old (pre v11.7) components
+```js
+---
+type: embed
+---
+<Alert variant="info" margin="0 0 medium">
+  These icons are only meant to be used with the new theming system, please do not use them with the old (pre v11.7)
+</Alert>
+```
 
 ## Using Icons
 

docs/guides/using-icons.md

@@ -527,9 +527,9 @@ type: example
 </InstUISettingsProvider>
 ```
 
-### 13. Targeted override for a parent component
+### 13. Provider-level overrides cannot target a child component selectively
 
-You can use the parent component's name (e.g. `Button`) in `themeOverride.components` to override its internal child component's tokens. When both `BaseButton` and `Button` overrides are present, the `Button` override should take precedence for `Button` instances, while `BaseButton` stays unaffected.
+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.
 
 ```js
 ---
@@ -551,15 +551,17 @@ type: example
     }}
   >
     <BaseButton color="primary" margin="small">
-      BaseButton - still purple (BaseButton override)
+      BaseButton - purple (BaseButton override)
     </BaseButton>
     <Button color="primary" margin="small">
-      Button - deeppink (Button override wins)
+      Button - also purple (Button uses BaseButton's theme; deeppink has no effect)
     </Button>
   </InstUISettingsProvider>
 </InstUISettingsProvider>
 ```
 
+To override a specific `Button` instance without affecting others, use the per-component `themeOverride` prop instead (see section 14).
+
 ### 14. Per-component `themeOverride` prop overriding provider-level child overrides
 
 When a provider sets `components.BaseButton` overrides, a specific `Button` instance can override those via its own `themeOverride` prop. The per-component prop has the highest priority.
@@ -599,54 +601,6 @@ type: example
 </InstUISettingsProvider>
 ```
 
-### 15. Overrides on functional (`useStyleNew`) components
-
-All override patterns work identically on functional components that use the `useStyleNew` hook. Here, Avatar tokens are overridden the same way as class-based components using `withStyleNew`.
-
-```js
----
-type: example
----
-<InstUISettingsProvider theme={light}>
-  <Avatar name="Default" color="accent1" margin="0 small 0 0" />
-
-  <InstUISettingsProvider
-    themeOverride={{
-      components: {
-        Avatar: {
-          backgroundColor: 'navy',
-          blueTextColor: 'lime'
-        }
-      }
-    }}
-  >
-    <Avatar name="Overridden" color="accent1" margin="0 small 0 0" />
-    <Avatar name="Unaffected" color="accent2" />
-  </InstUISettingsProvider>
-</InstUISettingsProvider>
-```
-
-### 16. Function form `themeOverride` on functional components
-
-The function form also works on `useStyleNew` components. The function receives the component's calculated theme as the first argument, letting you derive overrides from existing token values.
-
-```js
----
-type: example
----
-<InstUISettingsProvider theme={light}>
-  <Avatar name="Default Blue" color="accent1" margin="0 small 0 0" />
-  <Avatar
-    name="Swapped to Green"
-    color="accent1"
-    themeOverride={(componentTheme) => ({
-      backgroundColor: componentTheme.greenBackgroundColor,
-      blueTextColor: componentTheme.greenTextColor
-    })}
-  />
-</InstUISettingsProvider>
-```
-
 ### Override priority (highest to lowest)
 
 1. **Per-component `themeOverride` prop** - affects a single instance

docs/theming/new-theme-overrides.md

@@ -1,10 +1,10 @@
 ---
-title: Upgrade Guide for Version 11
+title: Upgrade guide for v10 -> v11
 category: Upgrading
 order: 1
 ---
 
-# Upgrade Guide for Version 11
+# Upgrade guide for v10 -> v11
 
 ## InstUI and React
 

docs/upgrading/upgrade-guide-v11.md

@@ -1,7 +1,7 @@
 ---
-title: Upgrade Guide for multi version
+title: Upgrade guide for v11.7
 category: Upgrading
-order: 9999999
+order: 2
 ---
 
 # Upgrade Guide for multi version support
@@ -52,7 +52,7 @@ type: example
 >
   <TextInput
     renderLabel="Name"
-    placeholder="Note: Change example when the old theme is renamed!"
+    placeholder="Focus me!"
   />
 </InstUISettingsProvider>
 ```

docs/upgrading/upgrade-guide.md

@@ -24,6 +24,13 @@
 
 // This is the format of the saved JSON files
 import type { Documentation } from 'react-docgen'
+import type { BaseTheme } from '@instructure/shared-types'
+import type {
+  NewBaseTheme,
+  LightTheme,
+  DarkTheme,
+  SharedTokens
+} from '@instructure/ui-themes'
 
 type ProcessedFile =
   Documentation &
@@ -137,8 +144,21 @@ type Glyph = {
 
 type LegacyIconsData = Glyph[]
 
+type ResolvedColors = {
+  primitives: Record<string, string>
+  semantic: Record<string, string>
+}
+
+type ThemeResource =
+  | (BaseTheme & { resolvedComponents: Record<string, any> })   // legacy-canvas, legacy-canvas-high-contrast
+  | (NewBaseTheme & { resolvedColors: ResolvedColors })          // canvas, canvas-high-contrast
+  | (LightTheme & { resolvedColors: ResolvedColors })
+  | (DarkTheme & { resolvedColors: ResolvedColors })
+  | SharedTokens
+
 type MainDocsData = {
-  // resource is `any` to support both old BaseTheme and new token objects
+  // `any` instead of ThemeResource: the union breaks property access (.key, .description)
+  // and typed function calls in consumers — would need type guards throughout to fix properly
   themes: Record<string, { resource: any }>
   library: LibraryOptions
 } & ParsedDoc
@@ -172,6 +192,8 @@ export type {
   JsDocResult,
   MinorVersionData,
   Section,
+  ThemeResource,
+  ResolvedColors,
   VersionMapEntry,
   VersionMap
 }