diff --git a/docs/contributing/transpile-diff.md b/docs/contributing/transpile-diff.md
index bd735c6521..ebe5721fee 100644
--- a/docs/contributing/transpile-diff.md
+++ b/docs/contributing/transpile-diff.md
@@ -1,6 +1,7 @@
---
title: Comparing Transpiled Output
-category: Contributor Guides
+category: Contributing
+order: 8
---
# Comparing Transpiled Output
diff --git a/docs/theming/legacy-theme-overrides.md b/docs/theming/legacy-theme-overrides.md
index 7a118e0624..0a8825da1a 100644
--- a/docs/theming/legacy-theme-overrides.md
+++ b/docs/theming/legacy-theme-overrides.md
@@ -387,203 +387,260 @@ The `canvas` theme has specific theme variables that are meant as a basis to pro
> `canvas-high-contrast` does not have this functionality, so a11y color contrast requirements (e.g. [WCAG](https://webaim.org/articles/contrast/)) are always met
+Some of these branding variables — notably `ic-brand-primary` — intentionally affect many components (focus rings, tab indicators, secondary button borders, etc.) because they serve as the primary brand color hooks in the `canvas` theme.
+
+However, a small number of `canvas` theme branding variables are not currently consumed by any InstUI component, so changing them has no visible effect: `ic-brand-button--secondary-bgd`, `ic-brand-button--secondary-text`, `ic-link-decoration`.
+
+#### Common variables — broad-impact branding
+
+`ic-brand-primary` is the main brand color hook. It is used for borders, backgrounds, focus rings, shadows and similar accents in many components (Tabs active indicator, secondary `Button` border, `TextInput` focus ring, etc.). `ic-brand-font-color-dark` is the default dark text color used in many places.
+
```ts
---
type: example
---
const Example = () => {
- // global stuff
const [icBrandPrimary, setIcBrandPrimary] = useState(canvas['ic-brand-primary'])
const [icBrandFontColorDark, setIcBrandFontColorDark] = useState(canvas['ic-brand-font-color-dark'])
- // Link
- const [icLinkColor, setIcLinkColor] = useState(canvas['ic-link-color'])
- const [icLinkDecoration, setIcLinkDecoration] = useState(canvas['ic-link-decoration'])
- // Button
- const [icBrandButtonPrimaryBgd, setIcBrandButtonPrimaryBgd] = useState(canvas['ic-brand-button--primary-bgd'])
- const [icBrandButtonPrimaryText, setIcBrandButtonPrimaryText] = useState(canvas['ic-brand-button--primary-text'])
- const [icBrandButtonSecondaryBgd, setIcBrandButtonSecondaryBgd] = useState(canvas['ic-brand-button--secondary-bgd'])
- const [icBrandButtonSecondaryText, setIcBrandButtonSecondaryText] = useState(canvas['ic-brand-button--secondary-text'])
- // SideNavBar
- const [icBrandGlobalNavBgd, setIcBrandGlobalNavBgd] = useState(canvas['ic-brand-global-nav-bgd'])
- const [icGlobalNavLinkHover, setIcGlobalNavLinkHover] = useState(canvas['ic-global-nav-link-hover'])
- const [icBrandGlobalNavIcIconSvgFill, setIcBrandGlobalNavIcIconSvgFill] = useState(canvas['ic-brand-global-nav-ic-icon-svg-fill'])
- const [icBrandGlobalNavIcIconSvgFillActive, setIcBrandGlobalNavIcIconSvgFillActive] = useState(canvas['ic-brand-global-nav-ic-icon-svg-fill--active'])
- const [icBrandGlobalNavMenuItemTextColor, setIcBrandGlobalNavMenuItemTextColor] = useState(canvas['ic-brand-global-nav-menu-item__text-color'])
- const [icBrandGlobalNavMenuItemTextColorActive, setIcBrandGlobalNavMenuItemTextColorActive] = useState(canvas['ic-brand-global-nav-menu-item__text-color--active'])
return (
-
Common variables
- setIcBrandPrimary(v)}
- messages={[{text:'used for border/background/focus/shadow/.. colors in many places',type:'hint'}]} />
+ setIcBrandPrimary(v)}
+ messages={[{text:'border/background/focus/shadow colors in many components',type:'hint'}]}
+ />
- setIcBrandFontColorDark(v)}
- messages={[{text:'used in lots of places for text color',type:'hint'}]} />
+ setIcBrandFontColorDark(v)}
+ messages={[{text:'default text color in many components',type:'hint'}]}
+ />
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ )
+}
+
+render()
+```
+
+#### `Button` branding
+
+These variables only affect the `primary` color `Button`.
-
)
}
diff --git a/docs/theming/new-theme-overrides.md b/docs/theming/new-theme-overrides.md
index 5fcdc279e2..1258decd59 100644
--- a/docs/theming/new-theme-overrides.md
+++ b/docs/theming/new-theme-overrides.md
@@ -601,6 +601,353 @@ type: example
```
+### 15. Branding (user customizable theming)
+
+The new theming system exposes the equivalents of the legacy Canvas `ic-brand-*` variables under `semantics.color.institutional.*`. Overriding these has the same broad effect as Canvas's [Theme Editor](https://community.canvaslms.com/t5/Admin-Guide/How-do-I-create-a-theme-for-an-account-using-the-Theme-Editor/ta-p/242) — the Button family, `SideNavBar`, `Link`, `Billboard`, and several other components consume them automatically.
+
+> **Theme support for branding:**
+>
+> - **`canvas` (legacy)** — branding overrides are supported.
+> - **`light`** — branding support is coming soon.
+> - **`dark`** — branding support is coming soon.
+> - **High-contrast themes** — branding will **never** be available, by design. These themes maintain WCAG-compliant color contrast at all times, so user-customizable colors cannot override them.
+
+| Legacy variable | New semantic token |
+| --------------------------------------------------- | --------------------------------------- |
+| `ic-brand-primary` | `brandPrimary` |
+| `ic-brand-font-color-dark` | `brandFontColorDark` |
+| `ic-link-color` | `linkColor` |
+| `ic-brand-button--primary-bgd` | `brandButtonPrimaryBgd` |
+| `ic-brand-button--primary-text` | `brandButtonPrimaryText` |
+| `ic-brand-global-nav-bgd` | `brandGlobalNavBgd` |
+| `ic-global-nav-link-hover` | `globalNavLinkHover` |
+| `ic-brand-global-nav-menu-item__text-color` | `brandGlobalNavMenuItemTextColor` |
+| `ic-brand-global-nav-menu-item__text-color--active` | `brandGlobalNavMenuItemTextColorActive` |
+
+A handful of legacy variables are not in the new system, for two different reasons:
+
+- **SVG icon-fill variables** (`ic-brand-global-nav-ic-icon-svg-fill` and `--active`) — these _were_ consumed by the `v11.6` to recolor its icons, but `v11.7` uses a different icon-coloring mechanism so they were not migrated.
+- **Variables that no InstUI component ever consumed** (`ic-brand-button--secondary-bgd`, `ic-brand-button--secondary-text`, `ic-link-decoration`)
+
+#### Common variables — broad-impact branding
+
+`brandPrimary` is the main brand color hook — consumed by the Tabs active indicator, `Badge` primary color, `RangeInput` handle, `TableRow` hover border, and several other accent colors. `brandFontColorDark` is the default dark text color used across many components.
+
+> **Heads up:** unlike the legacy `ic-brand-primary`, in the new system `brandPrimary` **no longer drives** the secondary `Button` border or the `TextInput` focus ring. Focus rings are now centrally controlled via `sharedTokens.focusOutline` — see the [Overriding shared tokens](#new-theme-overrides) section above to customize them.
+
+```ts
+---
+type: example
+---
+const Example = () => {
+ // Branding overrides work the same way across all new-system themes.
+ // Switch the "Base theme" selector to verify the override applies to canvas, light, and dark.
+ const themes = { canvas, light }
+ const [themeName, setThemeName] = useState('canvas')
+
+ const defaults = canvas.newTheme.semantics(canvas.newTheme.primitives).color.institutional
+ const [brandPrimary, setBrandPrimary] = useState(defaults.brandPrimary)
+ const [brandFontColorDark, setBrandFontColorDark] = useState(defaults.brandFontColorDark)
+
+ return (
+
+
+ setThemeName(value)}
+ >
+ canvas
+
+ light (coming soon)
+
+
+ dark (coming soon)
+
+
+
+
+
+ setBrandPrimary(v)}
+ messages={[{text:'Tabs indicator, Badge, RangeInput handle, etc.', type:'hint'}]}
+ />
+
+
+ setBrandFontColorDark(v)}
+ messages={[{text:'default dark text color in many components', type:'hint'}]}
+ />
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Default body text — uses brandFontColorDark.
+
+
+
+
+