refactor(ui): tokenize raw z-index one-offs into a semantic layering scale

apps/ui/CONTRIBUTING.md

@@ -69,6 +69,25 @@ budget — keep new dependencies/imports lean.
     than hand-rolling `rounded border bg-card`.
   - External links: use `<ExternalLink>` from `@jsonbored/ui-kit`, not a raw
     `<a target="_blank">` — it sets `rel=noreferrer` and filters unsafe/private URLs.
+  - Stacking order: use one of the named `--mg-z-*` layer tokens
+    (`packages/ui-kit/src/styles.css`), never a bare `z-10`/`z-20`/etc. or a
+    one-off `z-[N]`. From lowest to highest:
+
+    | Token              | Value | Use for                                                                  |
+    | ------------------ | ----- | ------------------------------------------------------------------------ |
+    | `--mg-z-sticky`    | 10    | Sticky theads/toolbars, scroll shadows, in-flow progress bars            |
+    | `--mg-z-raised`    | 20    | Elements that must clear sticky content within the same page section     |
+    | `--mg-z-nav`       | 30    | Site header/nav chrome                                                   |
+    | `--mg-z-overlay`   | 40    | Drawers, back-to-top, hover cards, lightweight menus                     |
+    | `--mg-z-modal`     | 50    | Dialogs, popovers, sheets, command palette (matches Radix's own default) |
+    | `--mg-z-progress`  | 60    | Route-transition progress bar — must beat modal                          |
+    | `--mg-z-skip-link` | 100   | a11y skip-link — must beat everything                                    |
+
+    The only standing exception: the sticky corner cell in the two compare
+    drawers (`subnets-compare-drawer.tsx`, `validators-compare-drawer.tsx`) uses
+    raw `z-[1]`/`z-[2]` for micro-stacking inside the table's own local
+    stacking context — not a global layer, so it doesn't belong on this scale.
+
   - See `docs/ssr-safety.md` for the hydration-safety rules (also partly ESLint-enforced).
 - Keep diffs focused. Don't reformat or refactor unrelated files in a feature PR.
 

apps/ui/eslint.config.ts

@@ -116,6 +116,17 @@ const ELEVATION_RULES = [
   },
 ];
 
+// #7841: bare z-* stacking steps collapsed into a named --mg-z-* layer scale
+// (packages/ui-kit/src/styles.css). Also flags the 6 documented z-[1]/z-[2]
+// sticky-cell micro-stacking exceptions in the two compare drawers -- that's
+// intentional (matches the residual-worklist convention other guardrails use).
+const Z_INDEX_RULES = [
+  {
+    selector: "Literal[value=/\\bz-(\\[[0-9]+\\]|[0-9]+\\b)/]",
+    message: "Raw z-index step. Use one of the --mg-z-* layer tokens (see styles.css).",
+  },
+];
+
 export default tseslint.config(
   // .source is fumadocs-mdx's generated content collection output (see
   // source.config.ts) -- codegen, not authored code, same treatment as dist.
@@ -184,6 +195,7 @@ export default tseslint.config(
         ...PRIMITIVE_STEER_RULES,
         ...SSR_SAFETY_RULES,
         ...ELEVATION_RULES,
+        ...Z_INDEX_RULES,
       ],
     },
   },

apps/ui/src/components/metagraphed/analytics/coverage-matrix.tsx

@@ -134,10 +134,10 @@
           right-edge fade signals there's more to scroll. */}
       <div className="relative">
         <div className="overflow-x-auto">
           <table className="w-full border-collapse text-[11px] font-mono">
             <thead>
               <tr className="bg-paper/30">
-                <th className="sticky left-0 z-10 bg-paper/30 text-left px-3 py-2 mg-type-micro text-ink-muted border-b border-border">
+                <th className="sticky left-0 z-[var(--mg-z-sticky)] bg-paper/30 text-left px-3 py-2 mg-type-micro text-ink-muted border-b border-border">
                   Subnet
                 </th>
                 {KINDS.map((k) => (
@@ -159,14 +159,14 @@
                   key={r.netuid}
                   className="border-b border-border last:border-b-0 hover:bg-paper/30"
                 >
-                  <td className="sticky left-0 z-10 bg-card px-3 py-1.5 border-r border-border text-ink-strong">
+                  <td className="sticky left-0 z-[var(--mg-z-sticky)] bg-card px-3 py-1.5 border-r border-border text-ink-strong">
                     <div className="flex items-center gap-2">
                       <Link
                         to="/subnets/$netuid"
                         params={{ netuid: r.netuid }}
                         className="inline-flex min-w-0 items-center gap-1.5 hover:text-accent"
                       >
                         <span className="font-mono text-[10px] text-ink-muted">SN{r.netuid}</span>
                         <span className="truncate max-w-[110px] sm:max-w-[160px]">{r.name}</span>
                       </Link>
                       <CompletenessChip value={r.completeness} netuid={r.netuid} />
@@ -210,7 +210,7 @@
         </div>
       </div>
 
       <footer className="flex flex-wrap items-center justify-between gap-3 border-t border-border bg-paper/30 px-4 py-2 font-mono text-[10px] text-ink-muted">
         <div className="flex items-center gap-3">
           <Legend cell="present" count={totals.present} />
           <Legend cell="candidate" count={totals.candidate} />
@@ -242,7 +242,7 @@
     <span
       title={`SN${netuid}: ${pct}% of required public-interface kinds present`}
       className={classNames(
         "ml-auto inline-flex shrink-0 items-center rounded-full border px-1.5 py-0.5 font-mono text-[9px] font-semibold tabular-nums md:hidden",
         tone,
       )}
     >
@@ -309,7 +309,7 @@
           </h3>
         </div>
         {stats ? (
           <div className="flex items-center gap-3 font-mono text-[10px] text-ink-muted">
             <Stat label="p25" value={`${Math.round(stats.p25 * 100)}%`} />
             <Stat label="p50" value={`${Math.round(stats.p50 * 100)}%`} />
             <Stat label="p75" value={`${Math.round(stats.p75 * 100)}%`} />
@@ -381,7 +381,7 @@
             })
           : null}
       </svg>
       <p className="mt-1 font-mono text-[10px] text-ink-muted">
         {rows.length} subnets bucketed in 10% bins. Median (p50) marks the middle of the registry;
         long tail to the right is the goal.
       </p>

apps/ui/src/components/metagraphed/app-shell.tsx

@@ -212,14 +212,14 @@ export function AppShell({
           {/* Skip link: first focusable element, visible only on keyboard focus. */}
           <a
             href="#main-content"
-            className="sr-only focus:not-sr-only focus:absolute focus:left-4 focus:top-4 focus:z-[100] focus:rounded focus:bg-ink-strong focus:px-4 focus:py-2 focus:text-paper"
+            className="sr-only focus:not-sr-only focus:absolute focus:left-4 focus:top-4 focus:z-[var(--mg-z-skip-link)] focus:rounded focus:bg-ink-strong focus:px-4 focus:py-2 focus:text-paper"
           >
             Skip to main content
           </a>
           {/* Top bar */}
           <header
             data-scrolled={scrolled ? "true" : "false"}
-            className="mg-header sticky top-0 z-30 border-b border-border bg-paper/90 backdrop-blur supports-[backdrop-filter]:bg-paper/75"
+            className="mg-header sticky top-0 z-[var(--mg-z-nav)] border-b border-border bg-paper/90 backdrop-blur supports-[backdrop-filter]:bg-paper/75"
           >
             <div className="max-w-shell-max mx-auto px-4 md:px-8 flex h-nav items-center gap-3">
               <button

apps/ui/src/components/metagraphed/blocks/shortcuts-dialog.tsx

@@ -69,7 +69,7 @@ export function ShortcutsDialog({ blockRef }: { blockRef: string }) {
       role="dialog"
       aria-modal
       aria-labelledby="mg-shortcut-title"
-      className="fixed inset-0 z-50 flex items-center justify-center bg-ink-strong/30 p-4 backdrop-blur-sm"
+      className="fixed inset-0 z-[var(--mg-z-modal)] flex items-center justify-center bg-ink-strong/30 p-4 backdrop-blur-sm"
       onClick={(e) => {
         if (e.target === e.currentTarget) setOpen(false);
       }}

apps/ui/src/components/metagraphed/call-module-extrinsics-table.tsx

@@ -118,7 +118,7 @@ export function CallModuleExtrinsicsTable({
       ))}
       table={
         <table className="w-full text-left text-sm">
-          <thead className="sticky top-0 z-10 bg-card/95 backdrop-blur supports-[backdrop-filter]:bg-card/80 shadow-[var(--mg-shadow-hairline)]">
+          <thead className="sticky top-0 z-[var(--mg-z-sticky)] bg-card/95 backdrop-blur supports-[backdrop-filter]:bg-card/80 shadow-[var(--mg-shadow-hairline)]">
             <tr>
               <th className="px-4 py-2.5">Hash</th>
               <th className="px-4 py-2.5">Block</th>

apps/ui/src/components/metagraphed/charts/latency-heatmap.tsx

@@ -167,7 +167,7 @@ export function LatencyHeatmap({ endpoints, minEndpoints = 1, maxProviders = 20
           >
             <thead>
               <tr>
-                <th className="sticky left-0 z-10 bg-card text-left px-3 py-2 mg-type-micro text-ink-muted border-b border-border">
+                <th className="sticky left-0 z-[var(--mg-z-sticky)] bg-card text-left px-3 py-2 mg-type-micro text-ink-muted border-b border-border">
                   Provider
                 </th>
                 {kinds.map((k) => (
@@ -198,7 +198,7 @@ export function LatencyHeatmap({ endpoints, minEndpoints = 1, maxProviders = 20
                 const total = row.reduce((a, c) => a + c.count, 0);
                 return (
                   <tr key={p} className="border-b border-border last:border-b-0">
-                    <td className="sticky left-0 z-10 bg-card px-3 py-1.5 text-ink-strong border-r border-border">
+                    <td className="sticky left-0 z-[var(--mg-z-sticky)] bg-card px-3 py-1.5 text-ink-strong border-r border-border">
                       <Tooltip>
                         <TooltipTrigger asChild>
                           <Link

apps/ui/src/components/metagraphed/charts/validator-subnet-heatmap.tsx

@@ -69,7 +69,7 @@ export function ValidatorSubnetHeatmap() {
           <table className="w-full min-w-[640px] text-[11px] font-mono">
             <thead>
               <tr>
-                <th className="sticky left-0 z-10 border-b border-border bg-card px-3 py-2 text-left mg-type-micro text-ink-muted">
+                <th className="sticky left-0 z-[var(--mg-z-sticky)] border-b border-border bg-card px-3 py-2 text-left mg-type-micro text-ink-muted">
                   Validator
                 </th>
                 {netuids.map((n) => (
@@ -87,7 +87,7 @@ export function ValidatorSubnetHeatmap() {
                 const byNet = new Map((v.subnets ?? []).map((s) => [s.netuid, s]));
                 return (
                   <tr key={v.hotkey} className="border-b border-border last:border-b-0">
-                    <td className="sticky left-0 z-10 border-r border-border bg-card px-3 py-1.5 text-ink-strong">
+                    <td className="sticky left-0 z-[var(--mg-z-sticky)] border-r border-border bg-card px-3 py-1.5 text-ink-strong">
                       <Link
                         to="/accounts/$ss58"
                         params={{ ss58: v.hotkey }}

apps/ui/src/components/metagraphed/endpoint-operational-list.tsx

@@ -130,7 +130,7 @@ export function EndpointOperationalList({
         return (
           <section key={String(group.netuid)} aria-labelledby={`group-${group.netuid}`}>
             <header
-              className="mg-section-rule sticky z-10 -mx-1 flex items-center justify-between gap-3 bg-paper/92 px-1 py-2 backdrop-blur"
+              className="mg-section-rule sticky z-[var(--mg-z-sticky)] -mx-1 flex items-center justify-between gap-3 bg-paper/92 px-1 py-2 backdrop-blur"
               style={{ top: "calc(var(--mg-sticky-offset, 3.5rem) + 3.75rem)" }}
             >
               <div className="flex min-w-0 items-center gap-2.5">
@@ -200,7 +200,7 @@ export function EndpointOperationalList({
                       />
                       {onToggleCompare ? (
                         <label
-                          className="absolute left-2 top-2 z-10 flex items-center gap-1 rounded border border-border bg-paper/85 px-1 py-0.5 mg-type-micro text-ink-muted backdrop-blur hover:text-ink-strong"
+                          className="absolute left-2 top-2 z-[var(--mg-z-sticky)] flex items-center gap-1 rounded border border-border bg-paper/85 px-1 py-0.5 mg-type-micro text-ink-muted backdrop-blur hover:text-ink-strong"
                           onClick={(e) => e.stopPropagation()}
                           title={
                             compareIds?.has(endpoint.id)

apps/ui/src/components/metagraphed/entity-hover-card.tsx

@@ -69,7 +69,7 @@ export function EntityHoverCard(props: EntityHoverCardProps) {
         sideOffset={placement.sideOffset}
         aria-label={ariaLabel}
         data-testid="entity-hover-card"
-        className="w-80 p-3 bg-card border-border shadow-lg z-50"
+        className="w-80 p-3 bg-card border-border shadow-lg z-[var(--mg-z-modal)]"
       >
         {props.kind === "subnet" ? (
           <SubnetMiniProfile netuid={props.netuid} />

apps/ui/src/components/metagraphed/nav-mega-menu.tsx

@@ -281,7 +281,7 @@ export function NavMegaMenu({ onNavigate }: NavMegaMenuProps) {
           <div aria-hidden className="mg-mega-scrim" onClick={() => setOpenKey(null)} />
           <div
             ref={panelRef}
-            className="absolute left-1/2 -translate-x-1/2 top-full mt-3 z-40"
+            className="absolute left-1/2 -translate-x-1/2 top-full mt-3 z-[var(--mg-z-overlay)]"
             role="dialog"
             aria-modal="true"
             aria-label={`${activePanel.label} menu`}

apps/ui/src/components/metagraphed/nav-omnibox.tsx

@@ -394,7 +394,7 @@ export function NavOmnibox({ onOpenPalette }: Props) {
         <div
           id="nav-omnibox-listbox"
           role="listbox"
-          className="absolute right-0 mt-1.5 w-[600px] max-w-[calc(100vw-1.5rem)] rounded-xl border border-border bg-paper shadow-2xl z-50 overflow-hidden"
+          className="absolute right-0 mt-1.5 w-[600px] max-w-[calc(100vw-1.5rem)] rounded-xl border border-border bg-paper shadow-2xl z-[var(--mg-z-modal)] overflow-hidden"
         >
           {/* ── Empty state: no query typed ─────────────────────────── */}
           {showSuggestions ? (

apps/ui/src/components/metagraphed/profile-tabs.tsx

@@ -64,7 +64,7 @@ export function ProfileTabs({
   return (
     <nav
       aria-label="Profile sections"
-      className="sticky z-10 -mx-4 md:mx-0 mb-8 border-b border-border bg-paper/95 backdrop-blur supports-[backdrop-filter]:bg-paper/80"
+      className="sticky z-[var(--mg-z-sticky)] -mx-4 md:mx-0 mb-8 border-b border-border bg-paper/95 backdrop-blur supports-[backdrop-filter]:bg-paper/80"
       style={{ top: "var(--mg-sticky-offset, 3.5rem)" }}
     >
       <div className="flex items-stretch gap-3 px-4 md:px-0">

apps/ui/src/components/metagraphed/shortcuts-popover.tsx

@@ -65,7 +65,7 @@ export function ShortcutsPopover() {
               type="button"
               aria-label="Keyboard shortcuts"
               className={classNames(
-                "hidden md:inline-flex fixed z-40 bottom-5 left-5 md:bottom-7 md:left-7",
+                "hidden md:inline-flex fixed z-[var(--mg-z-overlay)] bottom-5 left-5 md:bottom-7 md:left-7",
                 "items-center justify-center rounded-full border border-border bg-card/95 backdrop-blur",
                 "size-10 text-ink-muted shadow-[var(--mg-shadow-pop)]",
                 "hover:border-accent/60 hover:text-accent transition-colors",

apps/ui/src/components/metagraphed/subnets-compare-drawer.tsx

@@ -20,7 +20,7 @@ export function SubnetsCompareDrawer() {
   if (selected.length === 0) return null;
 
   return (
-    <div className="fixed inset-x-0 bottom-0 z-40 pointer-events-none">
+    <div className="fixed inset-x-0 bottom-0 z-[var(--mg-z-overlay)] pointer-events-none">
       <div className="max-w-shell-max mx-auto px-4 md:px-10 pb-3">
         <div
           className={classNames(
@@ -228,6 +228,7 @@ function CompareGrid({ netuids }: { netuids: number[] }) {
   return (
     <div className="border-t border-border max-h-[55vh] overflow-auto">
       <table className="min-w-full text-[12px]">
+        {/* local stacking context: sticky corner cell over sticky row/col — not a global layer (#7841) */}
         <thead className="sticky top-0 bg-card/95 backdrop-blur z-[1]">
           <tr>
             <th className="sticky left-0 z-[2] w-40 bg-card/95 px-3 py-2 text-left mg-type-micro text-ink-muted backdrop-blur">

apps/ui/src/components/metagraphed/validator-nominators-table.tsx

@@ -114,7 +114,7 @@ export function ValidatorNominatorsTable({ queryOptions, search, setSearch }: Pr
       ))}
       table={
         <table className="w-full text-left text-sm">
-          <thead className="sticky top-0 z-10 bg-card/95 backdrop-blur supports-[backdrop-filter]:bg-card/80 shadow-[var(--mg-shadow-hairline)]">
+          <thead className="sticky top-0 z-[var(--mg-z-sticky)] bg-card/95 backdrop-blur supports-[backdrop-filter]:bg-card/80 shadow-[var(--mg-shadow-hairline)]">
             <tr>
               <th className="px-4 py-2.5">Coldkey</th>
               <th className="px-4 py-2.5 text-right">Net staked</th>

apps/ui/src/components/metagraphed/validators-compare-drawer.tsx

@@ -24,7 +24,7 @@ export function ValidatorsCompareDrawer() {
   if (selected.length === 0) return null;
 
   return (
-    <div className="fixed inset-x-0 bottom-0 z-40 pointer-events-none">
+    <div className="fixed inset-x-0 bottom-0 z-[var(--mg-z-overlay)] pointer-events-none">
       <div className="max-w-shell-max mx-auto px-4 md:px-10 pb-3">
         <div
           className={classNames(
@@ -211,6 +211,7 @@ function CompareValidatorsGrid({ hotkeys }: { hotkeys: string[] }) {
   return (
     <div className="border-t border-border max-h-[55vh] overflow-auto">
       <table className="min-w-full text-[12px]">
+        {/* local stacking context: sticky corner cell over sticky row/col — not a global layer (#7841) */}
         <thead className="sticky top-0 bg-card/95 backdrop-blur z-[1]">
           <tr>
             <th className="sticky left-0 z-[2] w-40 bg-card/95 px-3 py-2 text-left mg-type-micro text-ink-muted backdrop-blur">

apps/ui/src/routes/__root.tsx

@@ -400,7 +400,7 @@ function RouteTransitionBar() {
   return (
     <div
       aria-hidden
-      className="fixed inset-x-0 top-0 z-[60] h-0.5 pointer-events-none overflow-hidden"
+      className="fixed inset-x-0 top-0 z-[var(--mg-z-progress)] h-0.5 pointer-events-none overflow-hidden"
       style={{ opacity: isLoading ? 1 : 0, transition: "opacity 200ms ease-out" }}
     >
       {isLoading ? (

apps/ui/src/routes/blocks.index.tsx

@@ -496,7 +496,7 @@ function BlocksTable() {
         ))}
         table={
           <table className="w-full text-left text-sm">
-            <thead className="sticky top-0 z-10 bg-card/95 backdrop-blur supports-[backdrop-filter]:bg-card/80 shadow-[var(--mg-shadow-hairline)]">
+            <thead className="sticky top-0 z-[var(--mg-z-sticky)] bg-card/95 backdrop-blur supports-[backdrop-filter]:bg-card/80 shadow-[var(--mg-shadow-hairline)]">
               <tr>
                 <th className="px-4 py-2.5">Block</th>
                 <th className="px-4 py-2.5">Hash</th>

apps/ui/src/routes/endpoints.tsx

@@ -900,7 +900,7 @@ function EndpointsTable() {
       {/* One shared command surface replaces the previous stacked category,
           search, select, toggle, and view-control bars. */}
       <div
-        className="sticky z-20 -mx-1 bg-paper/92 px-1 py-2 backdrop-blur"
+        className="sticky z-[var(--mg-z-raised)] -mx-1 bg-paper/92 px-1 py-2 backdrop-blur"
         style={{ top: "var(--mg-sticky-offset, 3.5rem)" }}
       >
         <QueryBar ariaLabel="Filter endpoint directory">

apps/ui/src/routes/extrinsics.index.tsx

@@ -304,7 +304,7 @@ function ExtrinsicsTable() {
       ))}
       table={
         <table className="w-full text-left text-sm">
-          <thead className="sticky top-0 z-10 bg-card/95 backdrop-blur supports-[backdrop-filter]:bg-card/80 shadow-[var(--mg-shadow-hairline)]">
+          <thead className="sticky top-0 z-[var(--mg-z-sticky)] bg-card/95 backdrop-blur supports-[backdrop-filter]:bg-card/80 shadow-[var(--mg-shadow-hairline)]">
             <tr>
               <th className="px-4 py-2.5">Hash</th>
               <th className="px-4 py-2.5">Block</th>

apps/ui/src/routes/index.tsx

@@ -393,7 +393,7 @@ function HomeHero() {
 
   return (
     <section className="mg-hero-slab relative overflow-hidden px-4 py-12 sm:px-6 md:py-20">
-      <div className="relative z-10 mx-auto flex max-w-4xl flex-col items-center text-center">
+      <div className="relative z-[var(--mg-z-sticky)] mx-auto flex max-w-4xl flex-col items-center text-center">
         <h1 className="mg-fade-in mt-2 font-display text-[30px] sm:text-[40px] md:text-[48px] font-semibold leading-[1.08] text-ink-strong">
           <span className="block">Bittensor,</span>
           <span className="block text-accent">de-mystified.</span>
@@ -470,7 +470,7 @@ function HomeHero() {
         <ChainHeadTip />
       </div>
 
-      <div className="relative z-10 mx-auto mt-10 max-w-6xl px-0 sm:px-2">
+      <div className="relative z-[var(--mg-z-sticky)] mx-auto mt-10 max-w-6xl px-0 sm:px-2">
         <HeroFeatureRow />
       </div>
     </section>

apps/ui/src/routes/providers.index.tsx

@@ -311,7 +311,7 @@ function ProvidersGrid({ view }: { view: "grid" | "table" }) {
 
       <SourceHealthRollup />
 
-      <div className="sticky top-[var(--mg-sticky-offset)] z-20 bg-paper/95 py-2 backdrop-blur-sm">
+      <div className="sticky top-[var(--mg-sticky-offset)] z-[var(--mg-z-raised)] bg-paper/95 py-2 backdrop-blur-sm">
         <QueryBar ariaLabel="Provider directory filters">
           <QueryBar.Search
             value={q}