feat(ui-global-nav): add the GlobalNav API types, the collapsible rail, its items and the logo by balzss · Pull Request #2768 · instructure/instructure-ui

balzss · 2026-10-28T12:25:03Z

Summary

Bump @instructure/instructure-design-tokens from v2.3.0 to v2.4.0. GlobalNav needs the new MainNav.minimizedGap token, the spacing of the collapsed rail. Other token changes:
- mainNavItem.selectedBackgroundColor is renamed to activeBackgroundColor.
- New CollapseButton, SubNav and SubNavItem tokens, new Banner typography and SegmentedControl opacity tokens, and the Stepper spacing tokens moved to StepItem. No code uses these yet.
- Legacy themes: stroke.warning is orange instead of honey. It is the warning border color of Alert, Pill, ProgressCircle and View.
- Legacy themes: the GlobalNav box shadow changes from transparent to a real shadow, so the legacy rail has a shadow now.
Add the GlobalNav props and data types, exported from @instructure/ui-global-nav and @instructure/ui. The app passes the nav content as data (items, logo, account). Where needed, it can also pass its own JSX, HTML attributes or a custom element.
Add the rail with a collapse button. Sizes and colors come from the GlobalNav, MainNav and MainNavItem tokens. The button is an InstUI IconButton with a Tooltip, and it calls onCollapse with the new value.
Add the rail items: links or buttons with an icon, a label, an optional badge and a chevron for items with a sub navigation. In the collapsed rail, the label moves to a tooltip and to screen reader text.
Items accept elementProps (HTML attributes, for example data-*) and render (a custom element, for example a router link). GlobalNav applies its own props last, so the app can't override the aria attributes, the href check or the click handling.
Add the logo: an image, a name, or both, with an optional link. With wordmark, the image already shows the name, and name is its alternative text. The docs example uses a Canvas wordmark and mark. These images are only in the docs app, not in a package.
Not in this PR: new unit tests and regression screenshots (they come when the markup is final). Some props are typed but don't work yet: account, the SubNav panel, backLabel and closeSubNavLabel. They come in the next PRs. Known gap: the collapse button's focus ring has too little contrast on the legacy rail.

Test Plan

Open the preview at https://instructure.design/pr-preview/pr-2768/#GlobalNav. The page is hidden from the nav and the search. Keep the # in the link: without it, the production docs open, and they don't have GlobalNav.
Click the collapse button. The rail changes from 232px to 92px wide, and the label changes between "Collapse navigation" and "Expand navigation".
Switch the theme. Light and dark have 12px padding inside the rail, and the legacy themes have none.
Collapse the rail in each theme. The logo is 8px below the top, with 8px between the logo, the collapse button and the items.
Check the logo. Expanded, it shows the wordmark, and collapsed, the square mark, both 32px tall. Light shows the dark version, the other themes the white one.
Turn on RTL in the example. The rail and the chevrons are mirrored.
Click Courses. Screen readers announce it as expanded, also when the rail is collapsed. Inbox reads as "Inbox 9 unread messages".
The visual regression report shows changed global-nav screenshots. These changes are expected: the regression page now shows the rail with the collapse button. Diffs in the legacy rail shadow, or in the warning borders of Alert, Pill, ProgressCircle or View in a legacy theme, come from the token bump.

Refs INSTUI-5215

🤖 Generated with Claude Code

github-actions · 2026-10-28T12:30:05Z

PR Preview Action v1.8.2
🚀 View preview at https://instructure.design/pr-preview/pr-2768/
Built to branch `gh-pages` at 2026-10-30 17:04 UTC. Preview will be ready when the GitHub Pages deployment is complete.

github-actions · 2026-10-28T12:30:49Z

Visual regression report

Cypress suite: ✅ Passing

Visual diff: ⚠️ Changes detected.

Status	Count
Unchanged	101
Changed	7
New	0
Removed	0

Accessibility (axe): ✅ No violations.

📊 View full report — click a screenshot's ⚠ badge to see each violation boxed on the image, with the offending element named and contrast failures shown as color swatches.

Diff images (7)

alert-canvas.png — 753 pixels differ

global-nav-canvas.png — 1415 pixels differ

global-nav-dark.png — 179 pixels differ

global-nav-light.png — 1449 pixels differ

progressbar-canvas.png — 1661 pixels differ

small-components-canvas.png — 85 pixels differ

view-canvas.png — 1088 pixels differ

_{Baselines come from the visual-baselines branch. They refresh on every merge to master. The Cypress suite line covers the a11y and console-error assertions — a ❌ there means the suite found real issues even if the visual diff is clean.}

matyasf · 2026-10-29T10:53:38Z

+  /**
+   * The institution logo at the top of the rail.
+   */
+  logo?: GlobalNavLogo


This should not be optional IMO

I was wondering about this, I will ask design if there can ever be exceptions

made it required. if design says there can be a nav without a logo we can make it optional later without a breaking change

joyenjoyer · 2026-10-30T12:13:59Z

 const Components = getComponentsForVersion()

+// an SVG shown with <img> can't inherit the text color, so the examples get one URL per color
+const svgUrl = (svg: string, color: string) =>


Question about the canvas-wordmark icon here: may non-instui devs use it later or is it added just for the docs app example? if yes, it would be worth to add it as an official icon to our ui-icons package and use it here with setting color through its API

i've asked design about this, they didn't have a clear answer yet but most likely we won't be providing this to end users and this is just here for docs example purposes

joyenjoyer · 2026-10-30T12:27:53Z

+  /**
+   * The heading of the panel.
+   */
+  title: Renderable


Isn't a string enough here?

probably yes or if not, we can expand it later, i'll update this

changed it to string

joyenjoyer · 2026-10-30T12:48:33Z

+ * @return The final style object, which will be used in the component
+ */
+const generateStyle = (
+  componentTheme: ReturnType<NewComponentTypes['MainNavItem']>


I would create a dedicated theme for this component instead of using MainNavItem's theme. Moreover, since this is a tiny unit of the larger component, I would remove it and just add the code to MainNavItem's render.

this is something that i'll consider but I would suggest to leave it like this for now and once we decide what to do, we can update this in a future pr

joyenjoyer · 2026-10-30T12:49:43Z

+    },
+    mark: {
+      label: 'institutionLogo__mark',
+      // MainNavInstitutionLogo has no size tokens


Maybe design team should add tokens here?
tagging @adamlobler

i'll let him know this needs to be added but until that is done i think this can be left like this and replaced in a future pr

joyenjoyer · 2026-10-30T13:52:18Z

@balzss one more thing: when I collapse an opened GlobalNav, it is flickering; it closes, reopens and closes quite quickly before it settles

GlobalNav needs the new MainNav.minimizedGap token, the spacing of the collapsed main column. Token changes: - MainNav: new minimizedGap. MainNavItem: selectedBackgroundColor is renamed to activeBackgroundColor. New CollapseButton set and new SubNav and SubNavItem colors. Nothing uses these yet. - Legacy themes: the GlobalNav box shadow and the MainNavAccountItem hover color changed. - Legacy themes: stroke.warning is orange instead of honey. It is the warning border color of Alert, Pill, ProgressCircle and View. - New Banner typography and SegmentedControl opacity tokens, and the Stepper spacing tokens moved to StepItem. No component uses these sets yet. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

The app describes the nav as data (items, logo, account) instead of nested sub-components, so InstUI renders all the markup and keeps roles, focus and keyboard handling in one place. GlobalNav hasn't been released yet, so dropping children isn't a breaking change. Co-Authored-By: Claude <noreply@anthropic.com>

The collapse button is an InstUI IconButton with colors from the MainNavItem tokens. Its focus ring keeps the default info color for now, which has too little contrast on the legacy rail. Co-Authored-By: Claude <noreply@anthropic.com>

Items with a sub navigation are buttons with aria-expanded. In the collapsed rail the tooltip wraps a span around the item, because Tooltip overwrites the aria-expanded of its trigger. Co-Authored-By: Claude <noreply@anthropic.com>

GlobalNav applies its own props after the app's, so elementProps can't override the aria attributes, the href check or the click handling. Co-Authored-By: Claude <noreply@anthropic.com>

The divider under the logo row uses the GlobalNav border color, and the main column has a hardcoded width, until the design tokens add a MainNav divider color and width. Co-Authored-By: Claude <noreply@anthropic.com>

balzss self-assigned this Oct 28, 2026

github-actions Bot pushed a commit that referenced this pull request Oct 28, 2026

visual-regression: PR #2768 (29e2fa5) 29e2fa5

0c93d67

balzss force-pushed the feat/global-nav-api branch from 0a77ba6 to 37ce0d7 Compare October 28, 2026 12:53

github-actions Bot pushed a commit that referenced this pull request Oct 28, 2026

visual-regression: PR #2768 (0b4fcd7) 0b4fcd7

13e9c1d

balzss force-pushed the feat/global-nav-api branch from 37ce0d7 to c7f9aaa Compare October 28, 2026 13:30

balzss changed the title ~~feat(ui-global-nav): add the GlobalNav API types and the collapsible rail~~ feat(ui-global-nav): add the GlobalNav API types, the collapsible rail and its items Oct 28, 2026

github-actions Bot pushed a commit that referenced this pull request Oct 28, 2026

visual-regression: PR #2768 (517b11d) 517b11d

25ab8e3

balzss force-pushed the feat/global-nav-api branch 2 times, most recently from 00fa1dd to c52015f Compare October 28, 2026 13:55

balzss requested review from joyenjoyer and matyasf October 28, 2026 13:56

github-actions Bot pushed a commit that referenced this pull request Oct 28, 2026

visual-regression: PR #2768 (533489a) 533489a

2d22d30

balzss force-pushed the feat/global-nav-api branch from c52015f to 31ff8d1 Compare October 28, 2026 14:04

github-actions Bot pushed a commit that referenced this pull request Oct 28, 2026

visual-regression: PR #2768 (f311ed3) f311ed3

37ad945

balzss force-pushed the feat/global-nav-api branch from 31ff8d1 to f9c950c Compare October 28, 2026 15:24

github-actions Bot pushed a commit that referenced this pull request Oct 28, 2026

visual-regression: PR #2768 (3e197f0) 3e197f0

6f0b8fd

balzss force-pushed the feat/global-nav-api branch from f9c950c to ae032ef Compare October 28, 2026 16:41

balzss changed the title ~~feat(ui-global-nav): add the GlobalNav API types, the collapsible rail and its items~~ feat(ui-global-nav): add the GlobalNav API types, the collapsible rail, its items and the logo Oct 28, 2026

github-actions Bot pushed a commit that referenced this pull request Oct 28, 2026

visual-regression: PR #2768 (d2377a8) d2377a8

e5494a1

balzss force-pushed the feat/global-nav-api branch from ae032ef to 88f8e47 Compare October 28, 2026 16:54

github-actions Bot pushed a commit that referenced this pull request Oct 28, 2026

visual-regression: PR #2768 (4b8d11e) 4b8d11e

49f1ebc

matyasf requested a review from git-nandor October 29, 2026 09:35

matyasf requested changes Oct 29, 2026

View reviewed changes

balzss force-pushed the feat/global-nav-api branch from 88f8e47 to 8ab3332 Compare October 30, 2026 10:03

github-actions Bot pushed a commit that referenced this pull request Oct 30, 2026

visual-regression: PR #2768 (5e885a7) 5e885a7

a8964c2

balzss force-pushed the feat/global-nav-api branch from 8ab3332 to a4d5b9f Compare October 30, 2026 10:14

github-actions Bot pushed a commit that referenced this pull request Oct 30, 2026

visual-regression: PR #2768 (7aa6d23) 7aa6d23

3a57224

balzss force-pushed the feat/global-nav-api branch from a4d5b9f to ec94dc0 Compare October 30, 2026 11:25

balzss force-pushed the feat/global-nav-api branch from ec94dc0 to ce82ec8 Compare October 30, 2026 11:31

matyasf self-requested a review October 30, 2026 11:34

matyasf approved these changes Oct 30, 2026

View reviewed changes

github-actions Bot pushed a commit that referenced this pull request Oct 30, 2026

visual-regression: PR #2768 (01512d3) 01512d3

8845460

balzss force-pushed the feat/global-nav-api branch from ce82ec8 to 9ba330e Compare October 30, 2026 11:50

github-actions Bot pushed a commit that referenced this pull request Oct 30, 2026

visual-regression: PR #2768 (9d2131d) 9d2131d

b126744

joyenjoyer requested changes Oct 30, 2026

View reviewed changes

balzss and others added 2 commits October 30, 2026 16:27

balzss force-pushed the feat/global-nav-api branch from 9ba330e to e462ade Compare October 30, 2026 15:31

github-actions Bot pushed a commit that referenced this pull request Oct 30, 2026

visual-regression: PR #2768 (e70097c) e70097c

abd9840

balzss requested a review from joyenjoyer October 30, 2026 16:33

balzss and others added 4 commits October 30, 2026 17:47

feat(ui-global-nav): add the rail items

aa0d978

Items with a sub navigation are buttons with aria-expanded. In the collapsed rail the tooltip wraps a span around the item, because Tooltip overwrites the aria-expanded of its trigger. Co-Authored-By: Claude <noreply@anthropic.com>

feat(ui-global-nav): add elementProps to the rail items

b9700fc

GlobalNav applies its own props after the app's, so elementProps can't override the aria attributes, the href check or the click handling. Co-Authored-By: Claude <noreply@anthropic.com>

feat(ui-global-nav,docs-app): add the institution logo

aae4cba

The divider under the logo row uses the GlobalNav border color, and the main column has a hardcoded width, until the design tokens add a MainNav divider color and width. Co-Authored-By: Claude <noreply@anthropic.com>

balzss force-pushed the feat/global-nav-api branch from e462ade to aae4cba Compare October 30, 2026 17:01

github-actions Bot pushed a commit that referenced this pull request Oct 30, 2026

visual-regression: PR #2768 (c2e0012) c2e0012

13711be

Conversation

balzss commented Oct 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test Plan

Uh oh!

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

Uh oh!

Built to branch gh-pages at 2026-10-30 17:04 UTC. Preview will be ready when the GitHub Pages deployment is complete.

Uh oh!

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

Uh oh!

Visual regression report

alert-canvas.png — 753 pixels differ

global-nav-canvas.png — 1415 pixels differ

global-nav-dark.png — 179 pixels differ

global-nav-light.png — 1449 pixels differ

progressbar-canvas.png — 1661 pixels differ

small-components-canvas.png — 85 pixels differ

view-canvas.png — 1088 pixels differ

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

Uh oh!

Uh oh!

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

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!

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

Uh oh!

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

balzss commented Oct 28, 2026 •

edited

Loading

github-actions Bot commented Oct 28, 2026 •

edited

Loading

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

github-actions Bot commented Oct 28, 2026 •

edited

Loading

joyenjoyer Oct 30, 2026 •

edited

Loading

joyenjoyer commented Oct 30, 2026 •

edited

Loading