Rework documentation by git-nandor · Pull Request #2550 · instructure/instructure-ui

git-nandor · 2026-05-11T13:01:21Z

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 · 2026-05-11T14:27:05Z

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 · 2026-05-11T17:04:27Z

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

matyasf

Looks good, nice work!

balzss · 2026-06-09T12:13:20Z



-> 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 [here](/#legacy-theme-overrides)


This renames the page id using-theme-overrides → legacy-theme-overrides, but the anchor was only updated in a few in-app files. These still point at the now-dead #using-theme-overrides and will render as broken links:

packages/ui-themes/README.md

packages/emotion/src/withStyleNew.tsx

packages/emotion/src/InstUISettingsProvider/README.md

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

Same risk for the usage → guides-getting-started rename. Could we grep the repo for every renamed page id and fix all inbound links (incl. package READMEs/JSDoc) before merge? A link check over the built docs would catch the rest.

balzss · 2026-06-09T12:13:20Z

  componentDidMount() {
    this.props.makeStyles?.()
+    // Defer color card rendering so the initial page paint is not blocked
+    requestAnimationFrame(() => this.setState({ showColors: true }))


This rAF (and the one in componentDidUpdate) is never cancelled. On fast navigation the component can unmount before the frame fires, triggering a setState-on-unmounted warning. Storing the handle and calling cancelAnimationFrame in componentWillUnmount would close that.

…s, 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

git-nandor self-assigned this May 11, 2026

git-nandor force-pushed the rework-documentation branch from 5d2192b to add5121 Compare May 11, 2026 14:20

github-actions Bot pushed a commit that referenced this pull request May 11, 2026

visual-regression: PR #2550 (bf9257d) bf9257d

d50858d

balzss mentioned this pull request May 11, 2026

chore: rewrite v2 component history to preserve git blame #2551

Merged

6 tasks

git-nandor marked this pull request as ready for review May 12, 2026 07:27

git-nandor requested review from HerrTopi, ToMESSKa, balzss, joyenjoyer and matyasf May 12, 2026 12:07

git-nandor force-pushed the rework-documentation branch 2 times, most recently from 408073b to a8a412c Compare May 12, 2026 13:06

github-actions Bot pushed a commit that referenced this pull request May 12, 2026

visual-regression: PR #2550 (8684cba) 8684cba

82fcb2b

git-nandor force-pushed the rework-documentation branch from a8a412c to d128181 Compare May 14, 2026 08:12

git-nandor requested a review from hajnaldo May 14, 2026 08:15

This comment was marked as outdated.

Sign in to view

git-nandor force-pushed the rework-documentation branch from d128181 to a65c973 Compare May 14, 2026 12:27

balzss force-pushed the master branch from d5c1198 to eaf8876 Compare May 14, 2026 12:51

git-nandor force-pushed the rework-documentation branch 2 times, most recently from 1959e8e to 59b7ab8 Compare May 14, 2026 14:00

git-nandor marked this pull request as draft May 15, 2026 09:07

git-nandor marked this pull request as ready for review May 15, 2026 11:32

git-nandor force-pushed the rework-documentation branch from 59b7ab8 to ba6ede5 Compare May 15, 2026 11:36

This comment was marked as outdated.

Sign in to view

git-nandor requested a review from hajnaldo May 15, 2026 12:01

joyenjoyer reviewed May 19, 2026

View reviewed changes

Comment thread docs/guides/using-icons.md Outdated

This comment was marked as outdated.

Sign in to view

This comment was marked as resolved.

Sign in to view

joyenjoyer reviewed May 19, 2026

View reviewed changes

Comment thread packages/__docs__/buildScripts/DataTypes.mts Outdated

This comment was marked as resolved.

Sign in to view

git-nandor force-pushed the rework-documentation branch from 66a57b5 to dfad812 Compare May 26, 2026 17:27

git-nandor requested review from joyenjoyer and matyasf May 27, 2026 06:12

git-nandor force-pushed the rework-documentation branch 2 times, most recently from 1f6033a to cdd775d Compare May 27, 2026 12:29

matyasf approved these changes May 27, 2026

View reviewed changes

git-nandor force-pushed the rework-documentation branch 3 times, most recently from e713885 to ced0fb5 Compare June 2, 2026 12:37

balzss reviewed Jun 9, 2026

View reviewed changes

git-nandor requested review from balzss and joyenjoyer and removed request for HerrTopi, ToMESSKa, hajnaldo and joyenjoyer June 10, 2026 12:42

git-nandor added 3 commits June 11, 2026 15:59

docs(many): rework documentation

f5457c2

docs: fix stale slug references after rework-documentation renames

01baa9e

git-nandor force-pushed the rework-documentation branch from 1c6da87 to 01baa9e Compare June 11, 2026 14:06

git-nandor requested a review from hajnaldo June 11, 2026 15:04

docs: move transpile-diff into proper group

9617d09



		> 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 [here](/#legacy-theme-overrides)

Conversation

git-nandor commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

github-actions Bot commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Visual regression report

Uh oh!

github-actions Bot commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Built to branch gh-pages at 2026-06-11 17:45 UTC. Preview will be ready when the GitHub Pages deployment is complete.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

This comment was marked as resolved.

This comment was marked as resolved.

Uh oh!

matyasf left a comment

Choose a reason for hiding this comment

Uh oh!

balzss Jun 9, 2026

Choose a reason for hiding this comment

Uh oh!

git-nandor Jun 10, 2026

Choose a reason for hiding this comment

Uh oh!

balzss Jun 9, 2026

Choose a reason for hiding this comment

Uh oh!

git-nandor Jun 10, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

git-nandor commented May 11, 2026 •

edited

Loading

github-actions Bot commented May 11, 2026 •

edited

Loading

github-actions Bot commented May 11, 2026 •

edited

Loading

Built to branch `gh-pages` at 2026-06-11 17:45 UTC.
Preview will be ready when the GitHub Pages deployment is complete.