feat: Elevation tokens scale for core and percipio themes

[LinKCoding]

Overview

Adds a themeable elevation scale to the Gamut themes so surfaces like Card get their hover shadow and lift from the active theme instead of hardcoded Core values.

• Adds packages/gamut-styles/src/variables/elevation.ts with coreElevation and percipioElevation scale factories, plus exported ElevationScale / ElevationState / ElevationStateStyles / ElevationScaleFactory types. Factories receive the theme's colors via .addScale('elevation', ...), so colors['shadow-primary'] resolves per theme and color mode without circular theme imports.
• Registers the scale on coreTheme and percipioTheme; each scale defines rest, hover, and hoverMirrored states with shadow and transform tokens (flattened to dashcase keys like elevation['hover-shadow']). The shared return type guarantees every theme emits the same tokens.
• Percipio's scale uses a soft blurred shadow with no hover lift; Core keeps the hard offset shadow with a translate lift.
• Replaces Card's hoverShadowLeft/hoverShadowRight style factories with a useCardElevation hook that reads the elevation tokens from useTheme(), regrouped into framer-motion variants via a getElevationStyles helper. Outline shadow variants keep their bespoke two-layer shadow but share the scale's transforms.
• Documents the scale in the styleguide: new Elevation sections in CoreTheme.mdx and PercipioTheme.mdx, backed by a shared createElevationTable that renders one row per state with paths, values, and a live shadow/lift example (dashed outline marks the resting position).

PR Checklist

• Related to designs: https://www.figma.com/file/ReGfRNillGABAj5SlITalN?type=design&node-id=137344%3A3804&mode=dev
• Related to JIRA ticket: GMT-1704
• Version plan added/updated (or not needed)
• 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

1. Go to Foundations → Theme → Core Theme — confirm the new Elevation section renders rest, hover, and hoverMirrored rows with shadow/transform paths, values, and example boxes (dashed outline should hug the box with no gap at the bottom).
2. Open Foundations → Theme → Percipio Theme and confirm its Elevation section shows the soft blurred shadows with transform: none on every state.
3. Go to the Card story with isInteractive and hover it — the shadow and lift should match the previous behavior (patternLeft/default lifts up-right with a left shadow, patternRight mirrors it, outline keeps its two-layer outline shadow).
4. Toggle color mode and see that the Card's shadow reflect the changes (note that some Cards have static colors)
5. Change the theme to Percipio and see that the shadows reflect accurately
6. Toggle color mode again to see the changes in light/dark mode
7. ...
8. Profit

PR Links and Envs

Repository	PR Link
Monolith	Monolith PR
Mono	Mono PR

[nx-cloud]

View your CI Pipeline Execution ↗ for commit f27e4dd

---

☁️ Nx Cloud last updated this comment at 2026-08-20 16:07:53 UTC

[codecov]

⚠️ JUnit XML file not found

The CLI was unable to find any JUnit XML files to upload.
For more help, visit our troubleshooting guide.

[dreamwasp]

looks great!

[codecademydev]

📬 Published Alpha Packages:

Package	Version	npm	Diff
@codecademy/gamut	73.0.1-alpha.909ba2.0	npm	diff
@codecademy/gamut-icons	10.0.1-alpha.909ba2.0	npm	diff
@codecademy/gamut-illustrations	1.0.1-alpha.909ba2.0	npm	diff
@codecademy/gamut-kit	3.0.18-alpha.909ba2.0	npm	diff
@codecademy/gamut-patterns	1.0.1-alpha.909ba2.0	npm	diff
@codecademy/gamut-styles	21.0.1-alpha.909ba2.0	npm	diff
@codecademy/gamut-tests	7.0.1-alpha.909ba2.0	npm	diff
@codecademy/variance	1.0.1-alpha.909ba2.0	npm	diff
eslint-plugin-gamut	3.0.1-alpha.909ba2.0	npm	diff

[github-actions]

🚀 Styleguide deploy preview ready!

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