docs(ui-themes,ui-link,emotion): fix for outadted theme override links, JSDocs and fix for fast theme switch and fix Link theme override example

fix outdated JSDocs. Add the new-theme-overrides entry to LLM summaries. Fix Link v2 themeOverride
example. Fix outdated theme override links. Cancel pending rAF in Theme on unmount/theme switch

Author: git-nandor

packages/__docs__/buildScripts/ai-accessible-documentation/summaries-for-llms-file.json

@@ -465,8 +465,12 @@
     "summary": "Quick start: Create a React app, add `@instructure/ui`, wrap with `InstUISettingsProvider`, and use components. Integrate with existing projects by adding the dependency and provider. Read about theme overrides and accessibility for best practices."
   },
   {
-    "title": "using-theme-overrides",
-    "summary": "Customize components via theme overrides while ensuring WCAG compliance. Use nested `InstUISettingsProvider` for subtree themes, override global or component themes, and leverage branding variables for user customization. Deprecated global theming causes issues with multiple InstUI versions."
+    "title": "legacy-theme-overrides",
+    "summary": "Theme overrides for version `/v11_6` and earlier. Apply via `themeOverride` on `InstUISettingsProvider` for a subtree or per-component `themeOverride` prop (component's own flat theme-variable map, object or function form)."
+  },
+  {
+    "title": "new-theme-overrides",
+    "summary": "Theme overrides for version `/v11_7` and later on the new token-based theming. Layered model: `primitives` → `semantics` → `components`, plus `sharedTokens` for cross-component patterns (focus rings, box shadows). Apply via structured `themeOverride` on `InstUISettingsProvider` keyed by token layer, or per-component `themeOverride` prop (object or `(componentTheme) => ({...})` function). Per-component overrides have highest priority."
   },
   {
     "title": "Upgrade Guide for Version 11",

packages/__docs__/src/Theme/index.tsx

@@ -58,22 +58,41 @@ type ThemeState = { showColors: boolean }
 
   state: ThemeState = { showColors: false }
 
+  private _showColorsRafId: number | null = null
+
   componentDidMount() {
     this.props.makeStyles?.()
     // Defer color card rendering so the initial page paint is not blocked
-    requestAnimationFrame(() => this.setState({ showColors: true }))
+    this.scheduleShowColors()
   }
 
   componentDidUpdate(prevProps: ThemeProps) {
     this.props.makeStyles?.()
     if (prevProps.themeKey !== this.props.themeKey) {
       // Reset on theme change so navigation feels instant
-      this.setState({ showColors: false }, () => {
-        requestAnimationFrame(() => this.setState({ showColors: true }))
-      })
+      this.setState({ showColors: false }, this.scheduleShowColors)
+    }
+  }
+
+  componentWillUnmount() {
+    // Avoid a setState-on-unmounted warning when the user navigates away
+    // before the deferred frame fires.
+    if (this._showColorsRafId !== null) {
+      cancelAnimationFrame(this._showColorsRafId)
+      this._showColorsRafId = null
     }
   }
 
+  scheduleShowColors = () => {
+    if (this._showColorsRafId !== null) {
+      cancelAnimationFrame(this._showColorsRafId)
+    }
+    this._showColorsRafId = requestAnimationFrame(() => {
+      this._showColorsRafId = null
+      this.setState({ showColors: true })
+    })
+  }
+
   _colorMap: Record<string, string> = {}
 
   mapColors(colorKey: Record<string, string>) {
@@ -344,9 +363,6 @@ ReactDOM.render(
   element
 )
 ${'```'}
-
-
-> You can read more about how our theming system works and how to use it [here](/#legacy-theme-overrides)
           `}
           title={`${themeKey} Theme Usage in applications`}
         />

packages/__docs__/src/withStyleForDocs.tsx

@@ -114,77 +114,27 @@ const defaultValues = {
  * category: utilities/themes
  * ---
  *
- * Same as `withStyle`, used only for the docs app.
- *
- * A decorator or higher order component that makes a component themeable.
- *
- * It adds a `makeStyles` function and the generated `styles` object to the decorated Component's props. If it has an own theme, it also adds the `themeOverride` prop to the component.
- *
- * As a HOC:
+ * Same shape as the legacy `withStyle` decorator, used only by the docs app.
+ * Injects a `makeStyles` function and the generated `styles` object as props,
+ * and forwards a `themeOverride` prop to the component.
  *
  * ```js-code
- * import { withStyleForDocs as withStyleNew } from '@instructure/emotion'
+ * import { withStyleForDocs } from '../withStyleForDocs'
  * import generateStyle from './styles'
  * import generateComponentTheme from './theme'
  *
- * export default withStyleNew(generateStyle, generateComponentTheme)(ExampleComponent)
+ * export default withStyleForDocs(generateStyle, generateComponentTheme)(ExampleComponent)
  * ```
  *
- * Themeable components inject their themed styles into the document
- * when they are mounted.
- *
- * ### Applying themes
- *
- * A themeable component’s theme can be configured via wrapping it in an
- * [InstUISettingsProvider](InstUISettingsProvider) component, and/or set
- * explicitly via its `themeOverride` prop.
- *
- * InstUISettingsProvider provides a theme object (e.g. the [canvas theme](/#canvas)).
- * These variables are mapped to the component's own variables in `theme.js`.
- *
- * With the `themeOverride` prop you can directly set/override the component theme variables declared in theme.js. It accepts an object or a function. The function has the component's theme and the currently active main theme as its parameter.
- *
- * See more about the overrides on the [Legacy theme overrides](/#legacy-theme-overrides) docs page.
- *
- * ```js-code
- * // ExampleComponent/theme.js
- * const generateComponentTheme = (theme) => {
- *   const { colors } = theme
- *
- *   const componentVariables = {
- *     background: colors?.backgroundMedium,
- *     color: colors?.textDarkest,
- *
- *     hoverColor: colors?.textLightest,
- *     hoverBackground: colors?.backgroundDarkest
- *   }
- *
- *   return componentVariables
- * }
- * export default generateComponentTheme
- * ```
- *
- * ```jsx-code
- * {// global theme override}
- * <InstUISettingsProvider theme={{
- *   colors: { backgroundMedium: '#888' }
- * }}>
- *  {// component theme override}
- *   <ExampleComponent themeOverride={{ hoverColor: '#eee' }} />
- *
- *  {// component theme override with function}
- *   <ExampleComponent themeOverride={(componentTheme, currentTheme) => ({
- *     hoverBackground: componentTheme.background,
- *     activeBackground: currentTheme.colors.backgroundBrand
- *   })} />
- * </InstUISettingsProvider>
- * ```
+ * Override patterns (provider-scoped, per-component, function form) are
+ * documented on the [Legacy theme overrides](/#legacy-theme-overrides) docs
+ * page — `withStyleForDocs` follows the same model.
  *
- * @module withStyleNew
+ * @module withStyleForDocs
  *
- * @param {function} generateStyle - The function that returns the component's style object
- * @param {function} generateComponentTheme - The function that returns the component's theme variables object
- * @returns {ReactElement} The decorated WithStyle Component
+ * @param {function} generateStyle - Returns the component's style object
+ * @param {function} generateComponentTheme - Returns the component's theme variables object
+ * @returns {ReactElement} The decorated component
  */
 const withStyleForDocs = decorator(
   (

packages/emotion/src/InstUISettingsProvider/README.md

@@ -62,7 +62,10 @@ ReactDOM.render(
 
 #### Theme overrides
 
-There are multiple ways to override themes in InstUI. You can read about how these work on the dedicated docs page: [Using theme overrides](/#using-theme-overrides).
+There are multiple ways to override themes in InstUI. You can read about how these work on the dedicated docs pages:
+
+- [Legacy theme overrides](/#legacy-theme-overrides).
+- [New theme overrides](/#new-theme-overrides).
 
 ### Text direction management
 

packages/emotion/src/withStyle.tsx

@@ -94,7 +94,11 @@ const defaultValues = {
  * ---
  * category: utilities/themes
  * ---
- * used for old (v11 and eariler) theming system
+ * Legacy decorator for the pre-v11.7 theming system. New components should use
+ * `withStyleNew` instead. Override patterns for components decorated with
+ * `withStyle` are documented on the
+ * [Legacy theme overrides](/#legacy-theme-overrides) docs page.
+ *
  * TODO delete when the theme migration is complete
  */
 const withStyle = decorator(

packages/emotion/src/withStyleNew.tsx

@@ -98,11 +98,9 @@ const defaultValues = {
  * category: utilities/themes
  * ---
  *
- * A decorator or higher order component that makes a component themeable.
- *
- * It adds a `makeStyles` function and the generated `styles` object to the decorated Component's props. If it has an own theme, it also adds the `themeOverride` prop to the component.
- *
- * As a HOC:
+ * Decorator (or HOC) that makes a component themeable using InstUI's new
+ * theming system. Injects a `makeStyles` function and the
+ * generated `styles` object as props.
  *
  * ```js-code
  * import { withStyleNew } from '@instructure/emotion'
@@ -111,42 +109,18 @@ const defaultValues = {
  * export default withStyleNew(generateStyle)(ExampleComponent)
  * ```
  *
- * Themeable components inject their themed styles into the document
- * when they are mounted.
- *
- * ### Applying themes
- *
- * A themeable component’s theme can be configured via wrapping it in an
- * [InstUISettingsProvider](InstUISettingsProvider) component, and/or set
- * explicitly via its `themeOverride` prop.
- *
- * InstUISettingsProvider provides a theme object (e.g. the [canvas theme](/#canvas)).
- * These variables are mapped to the component's own variables in `theme.js` (see [theming](theming-basics) for more info).
+ * Optionally pass a `useTokensFrom` key as the second argument to consume
+ * another component's tokens (e.g. `withStyleNew(generateStyle, 'BaseButton')`).
  *
- * With the `themeOverride` prop you can directly set/override the component theme variables declared in theme.js. It accepts an object or a function. The function has the component's theme and the currently active main theme as its parameter.
- *
- * See more about the overrides on the [Using theme overrides](/#using-theme-overrides) docs page.
- *
- * ```jsx-code
- * {// global theme override}
- * <InstUISettingsProvider theme={{
- *   colors: { backgroundMedium: '#888' }
- * }}>
- *  {// component theme override}
- *   <ExampleComponent themeOverride={{ hoverColor: '#eee' }} />
- *
- *  {// component theme override with function}
- *   <ExampleComponent themeOverride={(componentTheme, currentTheme) => ({
- *     hoverBackground: componentTheme.background,
- *     activeBackground: currentTheme.colors.backgroundBrand
- *   })} />
- * </InstUISettingsProvider>
- * ```
+ * Override patterns (provider-scoped, per-component, primitives / semantics /
+ * sharedTokens layers, priority rules) are documented on the
+ * [New theme overrides](/#new-theme-overrides) docs page.
  *
  * @module withStyleNew
  *
- * @param {function} generateStyle - The function that returns the component's style object
- * @returns {ReactElement} The decorated WithStyle Component
+ * @param {function} generateStyle - Returns the component's style object
+ * @param {string}   [useTokensFrom] - Key of another component whose tokens this one should consume
+ * @returns {ReactElement} The decorated component
  */
 const withStyleNew = decorator(
   (

packages/ui-link/src/Link/v1/README.md

@@ -10,24 +10,9 @@ describes: Link
 ---
 type: example
 ---
-  <div>
-<Text>The quick brown fox <Link href="https://instructure.github.io/instructure-ui/"
-                                themeOverride={{
-                                  focusOutlineColor: 'pink'
-                                }}>jumps</Link> over the lazy dog.</Text>
-<Link color="link-inverse" href="https://instructure.github.io/instructure-ui/">jumps</Link>
-</div>
-```
-
-```js
----
-type: example
----
-<View background="primary-inverse" as="div">
-  <Text color="primary-inverse">The quick brown fox <Link color="link-inverse" href="https://instructure.github.io/instructure-ui/" themeOverride={{
-    focusInverseIconOutlineColor: 'pink'
-  }}>jumps</Link> over the lazy dog.</Text>
-</View>
+<Link href="https://instructure.github.io/instructure-ui/" target="_blank">
+  Link text
+</Link>
 ```
 
 ### Controlled navigation
@@ -164,7 +149,7 @@ type: example
 
 ### Theme overrides
 
-Examples showing how theme overrides work for Link:
+Examples showing how [theme overrides](legacy-theme-overrides) work for Link:
 
 ```js
 ---

packages/ui-link/src/Link/v2/README.md

@@ -168,21 +168,19 @@ type: example
 
 ### Theme overrides
 
-Examples showing how [theme overrides](using-theme-overrides) work for Link:
+Examples showing how [theme overrides](new-theme-overrides) work for Link:
 
 ```js
 ---
 type: example
 ---
 <div>
   <InstUISettingsProvider
-    theme={{
-      newTheme: {
-        sharedTokens: {
-          focusOutline: {
-            infoColor: 'pink',
-            width: '0.5rem',
-          }
+    themeOverride={{
+      sharedTokens: {
+        focusOutline: {
+          infoColor: 'pink',
+          width: '0.5rem'
         }
       }
     }}

packages/ui-themes/README.md

@@ -39,7 +39,10 @@ ReactDOM.render(
 )
 ```
 
-> You can read more about how our theming system works and how to use it [here](/#using-theme-overrides)
+> You can read more about how our theming system works and how to use it:
+
+- [Legacy theme overrides](/#legacy-theme-overrides).
+- [New theme overrides](/#new-theme-overrides).
 
 [npm]: https://img.shields.io/npm/v/@instructure/ui-themes.svg
 [npm-url]: https://npmjs.com/package/@instructure/ui-themes