Skip to content

refactor(emotion): migrate the docs app to the new theming engine - #2680

Open
ToMESSKa wants to merge 1 commit into
masterfrom
INSTUI-5087-docs-migrate-the-docs-app-to-the-new-theming-engine
Open

refactor(emotion): migrate the docs app to the new theming engine#2680
ToMESSKa wants to merge 1 commit into
masterfrom
INSTUI-5087-docs-migrate-the-docs-app-to-the-new-theming-engine

Conversation

@ToMESSKa

@ToMESSKa ToMESSKa commented Aug 7, 2026

Copy link
Copy Markdown
Contributor

Closes INSTUI-5087

OVERVIEW:

  1. The docs app now uses the light theme
  2. Docs own components moved to the new theming engine
  • all 9 theme.ts files are deleted. withStyleForDocs was rewritten to resolve the theme itself and hand the tokens to styles.ts
  1. InstUI components upgraded v1 → v2
  2. Icons swapped to the new set
  3. Spacing moved to the current token scale

TEST PLAN:

  • the docs page should be on the canvas theme e.g. TextInputs should look like the light theme on the main page, new fonts
  • go through as many pages as you can, there should be no errors or misaligned layouts, elements, focus rings etc.
  • choosing a theme from the dropdown should not affect the theme of the docs app, only the examples
  • there should not be old icons left
  • the docs' own components which got a new theming engine should function and look alright
Component What it is Where to see it
Hero the homepage — blue banner, search, CTA buttons, "Components everyone can count on" main page
ColorBand the blue/orange/red strip bottom of the homepage banner
SearchStatus search box indicator — magnifier when idle, 4 animated squares while loading type in the homepage search field
NavToggle the expand/collapse section rows in the sidebar left sidebar — "Guides", "Components", "Utilities", "Contributing", "Upgrading", "Themes"
Document a component's whole doc page — tabs, description, the sections below any component page, e.g. Alert
Properties the Properties table (name / type / default / description) on every component page
ComponentTheme the Default Theme Variables table bottom of component pages that have tokens
Playground the interactive, editable example — code toggle, fullscreen, RTL switch the type: example blocks on component pages
Preview the frame around a rendered example same place — it's the box Playground renders into
Figure Do / Don't / Accessibility guidance boxes with the coloured badge bottom of component pages, and in guides e.g. Alert
Theme the big variable tables on a theme page sidebar → Themes → pick one
ColorSwatch the small colour square next to a hex value inside Theme tables and Default Theme Variables tables
LoadingScreen the loading state before docs data arrives briefly on first load, or throttle the network

@ToMESSKa ToMESSKa self-assigned this Aug 7, 2026
@github-actions

github-actions Bot commented Aug 7, 2026

Copy link
Copy Markdown
Contributor
PR Preview Action v1.8.1

QR code for preview link

🚀 View preview at
https://instructure.design/pr-preview/pr-2680/

Built to branch gh-pages at 2026-08-14 10:03 UTC.
Preview will be ready when the GitHub Pages deployment is complete.

@github-actions

github-actions Bot commented Aug 7, 2026

Copy link
Copy Markdown
Contributor

Visual regression report

⚠️ Changes detected.

Status Count
Unchanged 0
Changed 1
New 96
Removed 32

📊 View full report

Diff images (33)

alert.png — baseline no longer produced

avatar.png — baseline no longer produced

badge.png — baseline no longer produced

billboard.png — baseline no longer produced

breadcrumb.png — baseline no longer produced

button-and-derivatives.png — baseline no longer produced

byline.png — baseline no longer produced

calendar.png — baseline no longer produced

checkbox.png — baseline no longer produced

checkboxgroup.png — baseline no longer produced

colorpicker.png — baseline no longer produced

contextview.png — baseline no longer produced

custom-and-lucide-icons.png — baseline no longer produced

dateinput-dateinput2.png — baseline no longer produced

datetimeinput.png — baseline no longer produced

diff-demo.png — 6324 pixels differ

drilldown.png — baseline no longer produced

filedrop.png — baseline no longer produced

form-errors.png — baseline no longer produced

heading.png — baseline no longer produced

img.png — baseline no longer produced

link.png — baseline no longer produced

menu.png — baseline no longer produced

metric-pill-tag-timeselect-text.png — baseline no longer produced

options.png — baseline no longer produced

pagination.png — baseline no longer produced

progressbar.png — baseline no longer produced

select-simpleselect.png — baseline no longer produced

table.png — baseline no longer produced

tabs.png — baseline no longer produced

tooltip.png — baseline no longer produced

treebrowser.png — baseline no longer produced

view.png — baseline no longer produced

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

github-actions Bot pushed a commit that referenced this pull request Aug 7, 2026
borderRadius: '0rem',
warningBorderColor: '#BF32A4',
warningIconBackground: '#BF32A4',
boxShadow: 'none'

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was replaced with hasShadow={false} as v2 removed Alert's boxShadow token.

label: 'app__hamburger',
position: 'fixed',
zIndex: componentTheme.menuToggleZIndex,
zIndex: 1,

@ToMESSKa ToMESSKa Aug 7, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

new theming system has no stacking tokens in semantics or sharedTokens so a hard-coded value was used

flexShrink: 0,
borderInlineEndColor: componentTheme.navBorderColor,
borderInlineEndWidth: componentTheme.navBorderWidth,
borderInlineEndColor: semantics.color.stroke.muted,

@ToMESSKa ToMESSKa Aug 7, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

new values were chosen to match the old value (resolved to a concrete hex/rem) everywhere in styles.ts files

margin={smallScreen ? 'none none medium' : 'none none x-small'}
margin={
smallScreen
? 'none none general.spaceXl'

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

mapping the old spacing values to the new ones were based on previous mapping e.g. #2647

return {
...componentVariables
}
export default function GithubLogo() {

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Lucide has no brand GitHub logo so I created this, similar to Header/instui-panda.tsx

@ToMESSKa
ToMESSKa force-pushed the INSTUI-5087-docs-migrate-the-docs-app-to-the-new-theming-engine branch from c32fa6e to 21bfb45 Compare August 7, 2026 10:27
borderRadius="medium"
>
<Table caption={label} layout="fixed">
<Table caption={() => label} layout="fixed">

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Table's caption changed type in v2

<InstUISettingsProvider
theme={{
componentOverrides: {
themeOverride={{

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this was changed to the new form

padding={
layout === 'small' ? 'xx-large large' : 'x-large xx-large'
}
padding="general.space2xl general.space2xl"

@ToMESSKa ToMESSKa Aug 7, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

x-large and xx-large all map to general.space2xl so both branches became identical. Padding is bit smaller here now vs the current docs app.

Image

github-actions Bot pushed a commit that referenced this pull request Aug 7, 2026
export { mirrorShorthandEdges } from './mirrorShorthandEdges.js'
export { calcSpacingFromShorthand } from './calcSpacingFromShorthand.js'
export { calcFocusOutlineStyles } from './calcFocusOutlineStyles.js'
export { applyColorModifiers } from './applyColorModifiers.js'

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

withStyleForDocs decorator needs it to resolve {value, modify} tokens the way withStyleNew does but it was not exported.

@ToMESSKa
ToMESSKa requested a review from HerrTopi August 7, 2026 11:40

@HerrTopi HerrTopi left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On first load, the components' theme is light mode despite the dropdown showing canvas

@ToMESSKa
ToMESSKa force-pushed the INSTUI-5087-docs-migrate-the-docs-app-to-the-new-theming-engine branch from 21bfb45 to 29879e2 Compare August 14, 2026 10:00
github-actions Bot pushed a commit that referenced this pull request Aug 14, 2026
)
this.setState({
docsData,
themeKey: Object.keys(docsData.themes)[0]

@ToMESSKa ToMESSKa Aug 14, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On first load, the components' theme is light mode despite the dropdown showing canvas

@HerrTopi The examples showed light theme instead of canvas because the first one in this list was taken ['legacy-canvas', 'legacy-canvas-high-contrast', 'canvas', 'canvas-high-contrast', 'light', 'dark', 'shared-tokens'], when it should have been 'canvas'. The preview examples never could use 'legacy-canvas' as a theme so they defaulted to the App's theme (which was coincidentally canvas). Switching the App to the light theme exposed this bug.

@ToMESSKa

Copy link
Copy Markdown
Contributor Author

On first load, the components' theme is light mode despite the dropdown showing canvas

@HerrTopi great catch, I fixed this.

@ToMESSKa
ToMESSKa requested a review from HerrTopi August 14, 2026 10:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants