feat: Percipio theme + theme switcher tool #3166

dreamwasp · 2025-09-03T14:29:59Z

Overview

Adds new Percipio theme, new font handling that allows theme specific fonts, and a Storybook theme switcher tool as well as the supporting documentation.

Static font assets are here: https://static-asset-cms.codecademy.com/browse/367

PR Checklist

Related to designs: https://www.figma.com/design/ReGfRNillGABAj5SlITalN/%F0%9F%93%90-Gamut?node-id=26315-29607&m=dev
Related to JIRA ticket: GM-1212
I have run this code to verify it works
This PR includes unit tests for the code change
This PR includes testing instructions tests for the code change
The alpha package of this PR is passing end-to-end tests in all relevant Codecademy repositories

Testing Instructions

Go to the Percipio theme docs and see they match the designs
Go to Checkbox story and use the theme switcher to see it looks right
Go to another story and see the Percipio theme looks cute
Check out the new theme switcher docs
Go to the mono PR and monolith PRs and follow the instructions there
... profit

PR Links and Envs

nx-cloud · 2025-09-03T14:31:17Z

View your CI Pipeline Execution ↗ for commit eba1087

Command	Status	Duration	Result
`nx run-many --target=verify --parallel=3 --all`	✅ Succeeded	3s	View ↗
`nx run-many --target=build --all`	✅ Succeeded	1s	View ↗

☁️ Nx Cloud last updated this comment at 2025-10-15 17:34:12 UTC

LinKCoding

Left some thoughts + Qs
functionality's looking great!

LinKCoding · 2025-09-24T15:03:57Z

packages/variance/src/createTheme/createTheme.ts

+  /**
+   *
+   * @param name Adds a name to the theme
+   * This is used for referencing the theme for replacing default fonts.


Is this only for replacing fonts?
can it also be reassignment of other tokens?

it could be! right now we're only using it for fonts, i guess it could be used for other static assets in the future 🤔

LinKCoding · 2025-09-24T15:25:53Z

packages/gamut-styles/src/__tests__/AssetProvider.test.tsx

+import { AssetProvider, createFontLinks } from '../AssetProvider';
+import { coreTheme, percipioTheme } from '../themes';
+
+// Using render rather than renderView because AssetProvider is used with the GamutProvider


Q: just to check — because setupRtl uses a withMockGamutProvider, we'd want to use render which we can then use the actual GamutProvider? and not a mock?

oh yeah i'll swap back - there was an iteration of this PR that had AssetProvider moved to within the GamutProvider but i pivoted.

LinKCoding · 2025-09-24T15:28:21Z

packages/gamut-styles/src/globals/Typography.tsx

-    font-weight: ${fontWeight.base};
+    return <Global styles={typographyGlobals} />;
+  } catch (error) {
+    // Handle font loading errors gracefully


Just a note — line 32 didn't include a comment for the console.warn

LinKCoding · 2025-09-24T15:30:01Z

packages/gamut-styles/src/__tests__/fontLoading.test.tsx

+      const links = container.querySelectorAll('link[rel="preload"]');
+      expect(links).toHaveLength(1);
+
+      // Restore original fonts


Feels like robo comment

LinKCoding · 2025-09-24T15:30:18Z

packages/gamut-styles/src/__tests__/fontLoading.test.tsx

+      const links = container.querySelectorAll('link[rel="preload"]');
+      expect(links).toHaveLength(1);
+
+      // Restore original fetch


Also feels like robo comment

LinKCoding · 2025-09-24T16:49:54Z

packages/styleguide/.storybook/components/Elements/DocsContainer.tsx

      <GamutProvider
        cache={createEmotionCache({ speedy: false })}
-        theme={storybookTheme}
+        theme={currentTheme as any}


Is there a way to type the theme to something more narrow than any?
If so, would that resolve some of the need to test falsey values?

GamutProvider is typed to the theme.d.ts but i'll dry it up

LinKCoding · 2025-09-24T16:50:03Z

packages/styleguide/.storybook/components/Elements/DocsContainer.tsx

        </HelmetProvider>
        <SourceContainer channel={context.channel}>
-          <ThemeProvider theme={coreTheme}>
+          <ThemeProvider theme={currentTheme as any}>


same Q here about typing

LinKCoding · 2025-09-24T16:51:01Z

packages/styleguide/.storybook/theming/GamutThemeProvider.tsx

 type GlobalsContext = {
  globals: {
    colorMode: 'light' | 'dark';
+    theme: keyof typeof themeMap;


lol related to the typing, maybe this can serve as the base for what a type could be?

LinKCoding · 2025-09-24T16:51:56Z

packages/styleguide/.storybook/theming/GamutThemeProvider.tsx

+      <GamutProvider
+        useCache={false}
+        useGlobals={false}
+        theme={currentTheme as unknown as Theme}


I should've waited to comment before, but I guess it's still relevant —
could this typing work in the DocsContainer.tsx file?

LinKCoding · 2025-09-24T16:56:54Z

packages/styleguide/src/lib/Foundations/Theme/PercipioTheme.mdx

+
+<AboutHeader {...parameters} />
+
+The Percipio Theme is a theme used within the Percipio application. It is built off of the Core Theme with additional tokens and overrides for Percipio. For all other tokens not listed here, refer to the <LinkTo id="Foundations/Theme/CoreTheme">Core Theme</LinkTo>.


The link doesn't work, maybe the id has a space in between?

aresnik11

This is so cool!! Still testing around onsite but initial thoughts/questions from the code

packages/gamut-styles/src/__tests__/fontLoading.test.tsx

aresnik11 · 2025-10-09T14:39:42Z

packages/gamut-styles/src/variables/typography.ts

+export const percipioFontFamily = {
+  accent: '"Roboto", sans-serif',
+  base: '"Roboto", sans-serif',
+  monospace: '"Roboto Mono", monospace',
+  system: '"Roboto", sans-serif',
+} as const;


do you think it makes sense to move this into the percipio theme file? thats what i did for lxStudio (slightly different)

imo i agree unless we want to use this family outside of the percipio theme?

the palette colors of all themes are stored in packages/gamut-styles/src/variables/colors.ts so i thought it would make sense to follow that same logic here for typography

aresnik11 · 2025-10-09T14:44:44Z

packages/styleguide/.storybook/components/Elements/DocsContainer.tsx

+  /* The Platform theme is a sub-theme of the Core theme, so it doesn't work as a standalone.
+   * This is a workaround so that the Platform colors show up in the Platform theme story but keep
+   * the main Core theme.
+   */
+  platform: storybookTheme,


how is platform theme different than the others?

thought about this and figured out the issue i was having with it was only because it the only theme that was dark mode by default, fixed

aresnik11 · 2025-10-09T15:04:36Z

packages/styleguide/.storybook/components/Elements/DocsContainer.tsx

+        // This is typed to the CoreTheme in theme.d.ts
+        theme={currentTheme as unknown as CoreTheme}


is it being typed to CoreTheme in theme.d.ts why this is as CoreTheme and not as Theme like below?

the GamutTheme looks to theme.d.ts for its theme while ThemeProvider doesn't care as long as its a valid emotion Theme. turns out i don't actually need to cast the theme below so i've removed it

aresnik11 · 2025-10-09T15:07:16Z

packages/styleguide/src/lib/Foundations/Theme/CreatingThemes.mdx

+  .addScale('shadows', ({ colors }) => ({
+    sm: `0 1px 2px ${colors['emerald-200']}`,
+    md: `0 4px 6px ${colors['emerald-300']}`,
+    lg: `0 10px 15px ${colors['emerald-400']}`,
+    xl: `0 20px 25px ${colors['emerald-500']}`,
+  }))
+  .addScale('borderRadius', () => ({
+    none: '0',
+    sm: '4px',
+    md: '8px',
+    lg: '12px',
+    xl: '16px',
+    full: '9999px',
+  }))
+  .addScale('spacing', () => ({
+    xs: '4px',
+    sm: '8px',
+    md: '16px',
+    lg: '24px',
+    xl: '32px',
+    '2xl': '48px',
+    '3xl': '64px',
+  }));


how does adding a scale differ from doing an override for the scale within createTheme? is it a correct assumption that if its an existing scale you would do the override above and not add a scale? if so, can we update this to not include existing scales?

great point, i clarified in my docs update!

aresnik11 · 2025-10-09T15:09:11Z

packages/styleguide/src/lib/Foundations/Theme/CreatingThemes.mdx

+  .build();
+```
+
+## Creating a Custom Theme


this is great!!!

jakemhiller · 2025-10-13T13:58:34Z

packages/gamut-styles/src/variables/typography.ts

+  accent: '"Roboto", sans-serif',
+  base: '"Roboto", sans-serif',
+  monospace: '"Roboto Mono", monospace',
+  system: '"Roboto", sans-serif',


is this what is currently used? i think the way we fall back to the actual system fonts in the normal font families is better but 🤷‍♂️

its passed to createTheme the same way our coreTheme does currently - i agree about the fallback and will fix!

looked into this more and found this is the way its done in front right now - i'll follow up with stacey to see if we want to add more robust fallbacks in the future

jakemhiller

minor comments but overall lgtm

Co-authored-by: Amy Resnik <[email protected]>

codecademydev · 2025-10-14T13:13:22Z

📬Published Alpha Packages:

@codecademy/[email protected]
@codecademy/[email protected]
@codecademy/[email protected]
@codecademy/[email protected]
@codecademy/[email protected]
@codecademy/[email protected]
@codecademy/[email protected]
@codecademy/[email protected]
@codecademy/[email protected]

codecademydev · 2025-10-14T13:14:24Z

🚀 Styleguide deploy preview ready!

https://68ee4caa1553b8537fd73638--gamut-preview.netlify.app

Deploy Logs

aresnik11

Niceeeeee! Only outstanding thing I noticed is the platform theme in dark mode doesn't look so great, but I'm fine if you tackle this as a follow up

codecademydev · 2025-10-15T17:35:20Z

📬 Published Alpha Packages:

@codecademy/[email protected]
@codecademy/[email protected]
@codecademy/[email protected]
@codecademy/[email protected]
@codecademy/[email protected]
@codecademy/[email protected]
@codecademy/[email protected]
@codecademy/[email protected]
@codecademy/[email protected]

github-actions · 2025-10-15T17:37:23Z

🚀 Styleguide deploy preview ready!

Preview URL: https://68efdbce446e866c84e26e83--gamut-preview.netlify.app
Deploy Logs: https://app.netlify.com/projects/gamut-preview/deploys/68efdbce446e866c84e26e83

dreamwasp added 2 commits September 3, 2025 10:16

feat: fix Checkbox + Radio color tokens

8e811f3

feat: Percipio theme

f4ac4e3

dreamwasp added 3 commits September 3, 2025 11:21

first stab at theme

4e9d261

removed duplicated values + added story

0e7e452

theme switcher

df076c2

dreamwasp mentioned this pull request Sep 3, 2025

feat: fix Checkbox + Radio color tokens #3165

Merged

6 tasks

add better docs for theme switcher

a7f842d

dreamwasp changed the title ~~feat: Percipio theme~~ feat: Percipio theme + theme switcher tool Sep 3, 2025

dreamwasp marked this pull request as ready for review September 3, 2025 17:30

dreamwasp requested a review from a team as a code owner September 3, 2025 17:30

dreamwasp requested review from aresnik11 and jakemhiller and removed request for a team September 3, 2025 17:30

dreamwasp marked this pull request as draft September 3, 2025 18:19

dreamwasp added 3 commits September 3, 2025 14:50

start fixing fonts

a4fb2a8

fix font issues

cd33610

sussy webfont changes - needd to fix build

8e357f7

Base automatically changed from cass-gm-1275 to main September 5, 2025 13:31

dreamwasp and others added 11 commits September 17, 2025 10:24

Merge branch 'main' into cass-gm-1212

cf21d73

build fixes + utilities added

b124b22

add defaults for createFontLink

7fac438

better types

28fc28e

new snapshots

9b9cf19

refactor + clean up

30f9583

first draft of docs

461382d

more docs

f97fd12

reset to gamut themeing

a797647

AssetProvider theme not required

10a8149

still working through theming;

6520af3

dreamwasp added 3 commits September 24, 2025 15:57

remove comments

5d3db5d

dinger fixed

5a6dc38

danger fix

37246e9

LinKCoding reviewed Sep 24, 2025

View reviewed changes

dreamwasp and others added 4 commits September 25, 2025 16:15

kenny comments

35244f5

fix link

f1251ec

Merge branch 'main' into cass-gm-1212

1b9927a

asset provider

f7712b8

aresnik11 reviewed Oct 9, 2025

View reviewed changes

jakemhiller reviewed Oct 13, 2025

View reviewed changes

jakemhiller approved these changes Oct 13, 2025

View reviewed changes

dreamwasp and others added 3 commits October 13, 2025 15:21

Apply suggestion from @aresnik11

91d12d4

Co-authored-by: Amy Resnik <[email protected]>

amy feedback

e405a74

docs tweaks

98d415d

dreamwasp added 2 commits October 14, 2025 10:48

Merge branch 'main' into cass-gm-1212

c733d74

Merge branch 'main' into cass-gm-1212

82d13d5

aresnik11 approved these changes Oct 14, 2025

View reviewed changes

dreamwasp and others added 5 commits October 14, 2025 15:27

variables for stories

4c116b9

Merge branch 'main' into cass-gm-1212

0970504

plat added

b682ab1

as any

fdea32d

formatted

eba1087

dreamwasp added the Ship It Automerge this PR when possible label Oct 15, 2025

codecademydev merged commit 4307902 into main Oct 15, 2025
21 of 22 checks passed

codecademydev removed the Ship It Automerge this PR when possible label Oct 15, 2025

codecademydev deleted the cass-gm-1212 branch October 15, 2025 17:40


		<AboutHeader {...parameters} />

		The Percipio Theme is a theme used within the Percipio application. It is built off of the Core Theme with additional tokens and overrides for Percipio. For all other tokens not listed here, refer to the <LinkTo id="Foundations/Theme/CoreTheme">Core Theme</LinkTo>.

		// This is typed to the CoreTheme in theme.d.ts
		theme={currentTheme as unknown as CoreTheme}

feat: Percipio theme + theme switcher tool #3166

feat: Percipio theme + theme switcher tool #3166

Uh oh!

Conversation

dreamwasp commented Sep 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

PR Checklist

Testing Instructions

PR Links and Envs

Uh oh!

nx-cloud bot commented Sep 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

LinKCoding 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!

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!

aresnik11 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dreamwasp Oct 13, 2025 • 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jakemhiller left a comment

Choose a reason for hiding this comment

Uh oh!

codecademydev commented Oct 14, 2025

📬Published Alpha Packages:

dreamwasp commented Sep 3, 2025 •

edited

Loading

nx-cloud bot commented Sep 3, 2025 •

edited

Loading

dreamwasp Oct 13, 2025 •

edited

Loading