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-05-26 17:32 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:

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 · 2026-05-15T12:01:24Z

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:

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.

joyenjoyer · 2026-05-19T13:13:03Z

Please wrap this into an info Alert, it would look better.

joyenjoyer · 2026-05-19T13:20:56Z

When I click on any themes, the page loads quite slowly

joyenjoyer · 2026-05-19T13:25:06Z

Nitpick: if there is an unnecessary newline at the beginning of a code example, remove it. IMHO it looks ugly. In one place there is one, in another there is none. For example:

joyenjoyer · 2026-05-19T13:31:06Z

 type MainDocsData = {
-  themes: Record<string, { resource: Theme }>
+  // resource is `any` to support both old BaseTheme and new token objects
+  themes: Record<string, { resource: any }>


maybe better typing here, combo of BaseTheme and type of new token objects?

matyasf

Looks good, just some smaller comments. Also:

Please add an info box to the legacy themes, that they are used by InstUI v 11.6 components.
Add an info box to all new themes, that states "This theme meets WCAG 2.1 AA rules for color contrast."
something is off with the themes, they are not showing for new themes after I switch them

HerrTopi · 2026-05-20T08:29:36Z

hex and grb works unexpected with shadow colors

HerrTopi · 2026-05-20T08:32:23Z

When I click on any themes, the page loads quite slowly

It is indeed. It's because of the bunch of colors we display on them. Maybe use the same virtualization as in icons? Not sure, just a suggestion

matyasf

See my comments. Also something is still off with theme variables, in 11.6 https://instructure.design/pr-preview/pr-2550/Avatar there are no theme variables shown

matyasf · 2026-05-26T10:20:48Z

+  renderNewThemePageAlert(subject = 'This theme') {
+    const v11_7Href = window.location.pathname.match(/v\d+_\d+/)
+      ? window.location.pathname.replace(/v\d+_\d+/, 'v11_7')
+      : `/v11_7${window.location.pathname}`
+    return (
+      <Alert variant="info" margin="0 0 medium">
+        {subject} is designed for components for <strong>v11.7</strong> and
+        later. If you are viewing an older version,{' '}
+        <Link href={v11_7Href}>switch to v11.7</Link>
+      </Alert>
+    )
+  }


It would be much nicer, if this alert would only show if the user views the 11.6 page. (so if the URL has no v11_6 part or no v11_ part at all

matyasf · 2026-05-26T10:23:08Z

@@ -1,6 +1,6 @@
 ---
 title: Upgrade Guide for Version 11


Can you rename this to "Upgrade guide for v10 -> v11" Now all the versions are v11, so its not clear what this is about.

matyasf · 2026-05-26T10:24:02Z

-title: Upgrade Guide for multi version (beta)
-category: Guides
-order: 9999999
+title: Upgrade Guide for multi version


Can you rename this to "Upgrade guide for v11.7"?

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

hajnaldo requested changes May 14, 2026

View reviewed changes

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

docs(ui-themes): rework documentation

ba6ede5

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

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

joyenjoyer reviewed May 19, 2026

View reviewed changes

matyasf requested changes May 19, 2026

View reviewed changes

matyasf requested changes May 26, 2026

View reviewed changes

docs: fix based on reviews

dfad812

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

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-05-26 17:32 UTC. Preview will be ready when the GitHub Pages deployment is complete.

Uh oh!

hajnaldo left a comment

Choose a reason for hiding this comment

Uh oh!

git-nandor commented May 15, 2026

Uh oh!

joyenjoyer May 19, 2026

Choose a reason for hiding this comment

Uh oh!

joyenjoyer commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

joyenjoyer commented May 19, 2026

Uh oh!

joyenjoyer May 19, 2026

Choose a reason for hiding this comment

Uh oh!

matyasf left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

HerrTopi commented May 20, 2026

Uh oh!

HerrTopi commented May 20, 2026

Uh oh!

matyasf left a comment

Choose a reason for hiding this comment

Uh oh!

matyasf May 26, 2026

Choose a reason for hiding this comment

Uh oh!

matyasf May 26, 2026

Choose a reason for hiding this comment

Uh oh!

matyasf May 26, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 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-05-26 17:32 UTC.
Preview will be ready when the GitHub Pages deployment is complete.

joyenjoyer commented May 19, 2026 •

edited

Loading