Rework documentation

[git-nandor]

INSTUI-4997

Summary

• Restructure and extend the documentation site with new theming and upgrade guide pages, fix broken interactive examples and removed outdated pages.
• Added canvas, canvas-high-contrast, and shared-tokens pages to the theme sidebar
• Restored color cards on legacy theme pages: rewrote Theme/renderSection() which had a broken early return, now renders four grouped sections (primitives, contrasts, ui, data visualization)
• Updated ThemeColors grouping to handle both primitive-style names (grey11) and camelCase semantic names (surfacePagePrimary)
• Added version-aware warning alerts to pages whose examples only work correctly on a specific minor version (with links to switch)
• Fixed "Default Theme Variables" not rendering for v11.7 components: new theme component tokens are pre-computed at build time (resolveComponents()) since functions are silently dropped by JSON.stringify
• Fixed "Default Theme Variables" not rendering for props-free child components (e.g. Menu.Separator): renderDetails now falls back to renderTheme when a component has no props/params/returns
• Fix theme page usage examples not updating on navigation: The Description component compiled its markdown content only in the constructor, causing code examples (e.g. import { light } from '@instructure/ui-themes') to stay stale when navigating between theme pages. Moved compilation to render() so it always reflects the current props.

Co-Authored-By: 🤖 Claude

[github-actions]

Visual regression report

✅ No changes.

Status	Count
Unchanged	32
Changed	0
New	0
Removed	0

📊 View full report

_{Baselines come from the visual-baselines branch. They refresh on every merge to master.}

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://instructure.design/pr-preview/pr-2550/
Built to branch gh-pages at 2026-05-15 11:40 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[hajnaldo]

Shared Tokens:
Documentation: It would be nice to mention explicitly that devs should use these tokens when they are tasked to build custom solutions (bc if they do so, the theming will work on their custom-built stuff too).

Token list:

1. Elevation-related tokens:
   Would it be possible to reflect what values belong to certain elevation styles, such as ordering them into groups according to how it is shown in the json:
   "elevation1": { "value": [ { "x": "{semantic.dropShadow.x.elevation1.dropshadow1}", "y": "{semantic.dropShadow.y.elevation1.dropshadow1}", "blur": "{semantic.dropShadow.blur.elevation1.dropshadow1}", "spread": "{semantic.dropShadow.spread.elevation1.dropshadow1}", "color": "{semantic.color.dropShadow.shadowColor1}", "type": "dropShadow" }, { "x": "{semantic.dropShadow.x.elevation1.dropshadow2}", "y": "{semantic.dropShadow.y.elevation1.dropshadow2}", "blur": "{semantic.dropShadow.blur.elevation1.dropshadow2}", "spread": "{semantic.dropShadow.spread.elevation1.dropshadow2}", "color": "{semantic.color.dropShadow.shadowColor2}", "type": "dropShadow" } ]

Theme Overrides:
Although it is technically possible to override primitives and it may even be useful, we don't want to encourage it upfront. Would it be possible not to proactively show this option in the docu?

[git-nandor]

Shared Tokens: Documentation: It would be nice to mention explicitly that devs should use these tokens when they are tasked to build custom solutions (bc if they do so, the theming will work on their custom-built stuff too).

Token list:

1. Elevation-related tokens:
   Would it be possible to reflect what values belong to certain elevation styles, such as ordering them into groups according to how it is shown in the json:
   "elevation1": { "value": [ { "x": "{semantic.dropShadow.x.elevation1.dropshadow1}", "y": "{semantic.dropShadow.y.elevation1.dropshadow1}", "blur": "{semantic.dropShadow.blur.elevation1.dropshadow1}", "spread": "{semantic.dropShadow.spread.elevation1.dropshadow1}", "color": "{semantic.color.dropShadow.shadowColor1}", "type": "dropShadow" }, { "x": "{semantic.dropShadow.x.elevation1.dropshadow2}", "y": "{semantic.dropShadow.y.elevation1.dropshadow2}", "blur": "{semantic.dropShadow.blur.elevation1.dropshadow2}", "spread": "{semantic.dropShadow.spread.elevation1.dropshadow2}", "color": "{semantic.color.dropShadow.shadowColor2}", "type": "dropShadow" } ]

Theme Overrides: Although it is technically possible to override primitives and it may even be useful, we don't want to encourage it upfront. Would it be possible not to proactively show this option in the docu?

Thanks for the suggestions, I’ve updated the Shared Tokens page.
We discussed the primitives override with the team and decided to keep it in the docs, since it can be useful information for valid edge-case scenarios.