added z-index soft scale

[LinKCoding]

Overview

Introduces a semantic z-index token scale (zIndexes) across Gamut, fixes SelectDropdown's menu positioning/stacking, and folds in Popover/Modal ref fixes, ESLint plugin updates, and a React 19 compatibility pass that landed on this branch.

• Adds packages/gamut-styles/src/variables/zIndexes.ts (renamed from zIndices.ts) defining the semantic scale (underlay, base, foreground, floating, appBar, flyout, modal, popover, topmost) and migrates all internal Gamut components (Box, BodyPortal, Overlay, Flyout, Popover, PopoverContainer, Tip/FloatingTip/InlineTip, Toaster, Menu, Tabs, List, Card, Modals/Dialog, Modals/Modal, PatternBackdrop) to use it.
• Adds gamut/no-raw-z-index ESLint rule (packages/eslint-plugin-gamut/src/no-raw-z-index.ts + test) to flag raw numeric zIndex/z-index values and registers it in recommended.ts; updates ESLint rules.mdx and adds a new Foundations/ZIndex.mdx styleguide doc.
• Updates SelectDropdown (SelectDropdown.tsx, styles.ts, elements/containers.tsx, elements/controls.tsx, elements/multi-value.tsx) to always portal its menu via menuPortalTarget={document.body}, apply zIndexes.popover by default with a raw-zIndex-prop escape hatch, and adds test coverage (SelectDropdown.test.tsx) for the portal behavior and z-index defaults.
• Fixes Popover/Modal ref handling (Popover/Popover.tsx, Popover/elements.tsx, PopoverContainer/PopoverContainer.tsx, PopoverContainer/hooks.ts, Modals/Dialog.tsx, Modals/Modal.tsx) alongside the z-index changes.
• Includes a React 19 compatibility pass: ref-handling updates across ConnectedForm, ButtonBase, Anchor, Tag, Text, Toaster, Tabs, Menu, List, DatePicker, BarChart, Card, Coachmark, DataList, GridForm, PatternBackdrop, plus new utils/nullish.ts/utils/react.ts helpers and react-hook-form version bump.
• Adds a beta dist-tag publish workflow (.github/workflows/publish-beta.yml, .github/actions/prerelease-publish/action.yml, tools/gamut-release/src/main.ts) alongside the existing alpha publish flow.
• Updates package versions (package.json, gamut-icons, gamut-illustrations, gamut-patterns, gamut-styles, gamut-tests, yarn.lock) and adds Nx version plans documenting the z-index scale changes.
• Updates theme snapshots (themes/__tests__/__snapshots__/theme.test.ts.snap) and Form/__tests__/__snapshots__/utils.test.tsx.snap to reflect the renamed/new tokens.

PR Checklist

• Related to designs:
• Related to JIRA ticket: GMT-308
• 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

Don't make me tap the sign.

1. In the SelectDropdown story/docs page, open the dropdown and confirm the menu renders above surrounding content (not clipped by any overflow: hidden ancestor) and closes/selects correctly.
2. Visit the new Foundations/ZIndex styleguide page and confirm the token table renders and matches zIndexes.ts (underlay through topmost).
3. Run the eslint-plugin-gamut test suite (no-raw-z-index.test.ts) and confirm a raw zIndex={2} in a sample component is flagged, and zIndexes.foreground is not.
4. Open a Popover/Modal/Dialog story and confirm they still open, close, and stack correctly relative to page content after the ref fixes.
5. ...
6. Finish and do a celebratory dance

PR Links and Envs

Repository	PR Link
Monolith	Monolith PR
Mono	Mono PR

[nx-cloud]

View your CI Pipeline Execution ↗ for commit a950e83

---

☁️ Nx Cloud last updated this comment at 2026-07-21 19:57:01 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.

[codecademydev]

📬 Published Alpha Packages:

Package	Version	npm	Diff
@codecademy/gamut	72.2.5-alpha.a75830.0	npm	diff
@codecademy/gamut-icons	9.57.11-alpha.a75830.0	npm	diff
@codecademy/gamut-illustrations	0.58.16-alpha.a75830.0	npm	diff
@codecademy/gamut-kit	3.0.9-alpha.a75830.0	npm	diff
@codecademy/gamut-patterns	0.10.35-alpha.a75830.0	npm	diff
@codecademy/gamut-styles	20.0.3-alpha.a75830.0	npm	diff
@codecademy/gamut-tests	6.0.6-alpha.a75830.0	npm	diff
@codecademy/variance	0.26.2-alpha.a75830.0	npm	diff
eslint-plugin-gamut	2.4.4-alpha.a75830.0	npm	diff

[github-actions]

🚀 Styleguide deploy preview ready!

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