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-20 21:36 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

matyasf · 2026-05-19T12:45:55Z

-category: Contributor Guides
+category: Contributing/Versioning
 order: 7
+isWIP: true


Why is this now non-visible?

I looked it up again, and I should have deleted it instead of set isWIP. Deleted.

matyasf · 2026-05-19T12:48:03Z

@@ -0,0 +1,177 @@
+---
+title: Agentic coding


This should be called "Building and running InstUI"

matyasf · 2026-05-19T13:00:11Z


- To use a different theme or customize one read about [Using theme overrides](using-theme-overrides)
+- To use a different theme or customize one read about [New Theme Overrides](new-theme-overrides)
 - Make sure you read about [Accessibility](accessibility) with InstUI.


In this doc please rewrite the part: "There are 2 built-in themes:..." to something that explains that there are 6 themes, legacy ones for 11.6, others for >11.7.

matyasf · 2026-05-19T13:00:53Z

-category: Guides
+title: Upgrade Guide for multi version
+category: Upgrading
 order: 9999999


The order can now be here 2

matyasf · 2026-05-19T13:11:45Z

+>
+  <TextInput
+    renderLabel="Name"
+    placeholder="Note: Change example when the old theme is renamed!"


change this text to "Focus me!"

matyasf · 2026-05-19T13:21:31Z

+</Alert>
+```
+
 This guide covers all the override patterns available in the new theming system (v11.7+). The new system uses a layered token architecture: **primitives** (raw values) -> **semantics** (meaning) -> **components** (per-component tokens).


in this file the "13. Targeted override for a parent component" might be broken, its all purple

Also in this file "15. Overrides on functional (useStyleNew) components" and "16. Function form themeOverride on functional components
" are unnecessary, you can delete it

I investigated it, and Button v2 uses BaseButton as its componentId, so components.Button overrides are ignored. I updated the docs to reflect the actual behavior.

matyasf · 2026-05-19T13:35:00Z

+          Use these tokens when building custom solutions to ensure your
+          components respond correctly to theme changes, including dark mode and
+          high contrast.


Mention here, that one can access the theme and these tokens with the useComputedTheme hook from @instructure/emotion

matyasf · 2026-05-19T13:35:32Z

    )
  }

+  renderSharedTokens() {


Can you extract this to its own component? This page is already huge

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

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

docs: fix based on reviews

66a57b5

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-20 21:36 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!

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!

Choose a reason for hiding this comment

Uh oh!

matyasf left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

HerrTopi commented May 20, 2026

Uh oh!

HerrTopi commented May 20, 2026

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-20 21:36 UTC.
Preview will be ready when the GitHub Pages deployment is complete.

joyenjoyer commented May 19, 2026 •

edited

Loading