@primer/primitives 11.5.0-rc.1d57246f → 11.5.0-rc.33df3625

package/DESIGN_TOKENS_GUIDE.md

@@ -98,6 +98,30 @@
 | MUST    | Match padding density to control's purpose  |
 | SHOULD  | Use `medium` size as default                |
 
+### Z-Index
+
+```
+--zIndex-[layer]
+  └── layer: behind | default | sticky | dropdown | overlay | modal | popover | skipLink
+```
+
+| Keyword | Rule                                                                                                         |
+| ------- | ------------------------------------------------------------------------------------------------------------ |
+| MUST    | Use z-index tokens instead of raw numeric values                                                             |
+| MUST    | Use `skipLink` only for accessibility skip-navigation links                                                  |
+| MUST    | Pair z-index with appropriate shadow level (see table below)                                                 |
+| SHOULD  | Prefer creating a new stacking context (`isolation: isolate`) over escalating z-index                        |
+| NEVER   | Use `behind` (-1) without verifying no ancestor creates a stacking context (transform, opacity, filter, etc) |
+| NEVER   | Use arbitrary z-index values outside the token scale                                                         |
+
+**Shadow ↔ Z-Index Alignment:**
+
+| Shadow Level                   | Z-Index Token                        | Example               |
+| ------------------------------ | ------------------------------------ | --------------------- |
+| `shadow.resting.*`             | `zIndex.default` / `zIndex.sticky`   | Cards, sticky headers |
+| `shadow.floating.small/medium` | `zIndex.dropdown` / `zIndex.overlay` | Menus, drawers        |
+| `shadow.floating.large/xlarge` | `zIndex.modal` / `zIndex.popover`    | Dialogs, tooltips     |
+
 ---
 
 ## Decision Tree: Easing Selection

package/DESIGN_TOKENS_SPEC.md

@@ -568,6 +568,48 @@ Monospace text styles for code blocks and inline code.
 | **text-codeBlock-shorthand** | Default style for rendering code blocks. | code-block, pre-element, code-snippet | MUST use for multi-line code. Use monospace font stack. |
 | **text-codeInline-shorthand** | Inline code blocks using em units to inherit size from its parent. | inline-code, code-element, variable-name | Use for inline code within text. Size inherits from parent using em units. |
 
+## ZIndex
+
+### zIndex-behind
+Place element behind base content. Use for decorative backgrounds or canvas elements.
+**U:** background-pattern, canvas-element, decorative-background
+**R:** Use to push an element behind its siblings. WARNING: Negative z-index can behave unpredictably if any ancestor creates a new stacking context (via transform, opacity < 1, filter, will-change, etc.). Only use when you control the full stacking context chain. Do NOT use as a general "hide" mechanism.
+
+### zIndex-default
+Default stacking order. No elevation above surrounding content.
+**U:** default-content, in-flow-element, reset
+**R:** Use to explicitly reset z-index to the default layer. Suitable for elements that should participate in normal document flow stacking. Do NOT use for any element that needs to appear above other content.
+
+### zIndex-dropdown
+Dropdown menus and select panels that appear above page content.
+**U:** autocomplete-list, dropdown-menu, select-panel
+**R:** Use for menus, select panels, and autocomplete lists that overlay page content. These should appear above sticky elements but below overlays and modals. Pair -> `shadow.floating.small` or `shadow.floating.medium` for visual elevation.
+
+### zIndex-modal
+Modal dialogs and full-screen overlays.
+**U:** dialog, full-screen-overlay, modal-dialog
+**R:** Use for modal dialogs that require user interaction before returning to the page. MUST trap focus within the modal. MUST appear above all other page content except popovers and skip links. Pair -> `shadow.floating.large` or `shadow.floating.xlarge` for visual elevation.
+
+### zIndex-overlay
+Overlay backdrops, side panels, and drawers.
+**U:** drawer, overlay-backdrop, side-panel
+**R:** Use for overlay surfaces that partially cover the page — drawers, side panels, and backdrop layers. These appear above dropdowns but below modal dialogs. SHOULD be paired with a backdrop/scrim element to indicate the overlay is blocking interaction with content beneath.
+
+### zIndex-popover
+Tooltips and popovers that appear above all normal UI.
+**U:** hover-card, popover, tooltip
+**R:** Use for tooltips, popovers, and hover cards that must appear above all other UI elements including modals. These are the highest layer in normal UI. Do NOT use for persistent navigation — use `sticky` instead.
+
+### zIndex-skipLink
+Accessibility skip links. Must always be the topmost layer.
+**U:** skip-link, skip-navigation, skip-to-content
+**R:** MUST use for accessibility skip links that allow keyboard users to bypass navigation. This is the highest z-index level and MUST always appear above everything else including modals and tooltips. NEVER use for non-accessibility purposes.
+
+### zIndex-sticky
+Sticky elements that remain visible while scrolling.
+**U:** sticky-header, sticky-sidebar, sticky-table-header
+**R:** MUST use with `position: sticky` or `position: fixed` for headers, sidebars, and navigation bars that persist during scroll. Do NOT use for floating overlays or dropdowns — use higher z-index levels instead.
+
 ---
 
 **Final Directive for AI**:

package/dist/build/transformers/durationToCss.js

@@ -27,9 +27,9 @@ export const durationToCss = {
         if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
             throw new Error(`duration token value must be a finite, non-negative number, invalid token: ${token.name} with value: ${value}`);
         }
-        // Always output in ms
+        // Always output in ms, rounding to avoid floating-point noise (e.g. 0.0049s → 4.9ms not 4.8999…ms)
         if (unit === 's') {
-            return `${value * 1000}ms`;
+            return `${parseFloat((value * 1000).toPrecision(12))}ms`;
         }
         return `${value}ms`;
     },

package/dist/css/base/size/size.css

@@ -18,4 +18,18 @@
   --base-size-8: 0.5rem;
   --base-size-80: 5rem;
   --base-size-96: 6rem;
+  --base-size-negative-12: -0.75rem;
+  --base-size-negative-16: -1rem;
+  --base-size-negative-2: -0.125rem;
+  --base-size-negative-20: -1.25rem;
+  --base-size-negative-24: -1.5rem;
+  --base-size-negative-28: -1.75rem;
+  --base-size-negative-32: -2rem;
+  --base-size-negative-36: -2.25rem;
+  --base-size-negative-4: -0.25rem;
+  --base-size-negative-40: -2.5rem;
+  --base-size-negative-44: -2.75rem;
+  --base-size-negative-48: -3rem;
+  --base-size-negative-6: -0.375rem;
+  --base-size-negative-8: -0.5rem;
 }

package/dist/css/base/size/z-index.css

@@ -0,0 +1,9 @@
+:root {
+  --base-zIndex-0: 0;
+  --base-zIndex-100: 100;
+  --base-zIndex-200: 200;
+  --base-zIndex-300: 300;
+  --base-zIndex-400: 400;
+  --base-zIndex-500: 500;
+  --base-zIndex-600: 600;
+}

package/dist/css/functional/size/z-index.css

@@ -0,0 +1,10 @@
+:root {
+  --zIndex-behind: -1; /** Place element behind base content. Use for decorative backgrounds or canvas elements. */
+  --zIndex-default: 0; /** Default stacking order. No elevation above surrounding content. */
+  --zIndex-dropdown: 200; /** Dropdown menus and select panels that appear above page content. */
+  --zIndex-modal: 400; /** Modal dialogs and full-screen overlays. */
+  --zIndex-overlay: 300; /** Overlay backdrops, side panels, and drawers. */
+  --zIndex-popover: 500; /** Tooltips and popovers that appear above all normal UI. */
+  --zIndex-skipLink: 600; /** Accessibility skip links. Must always be the topmost layer. */
+  --zIndex-sticky: 100; /** Sticky elements that remain visible while scrolling. */
+}

package/dist/css/primitives.css

@@ -4,6 +4,7 @@
  */
 @import './base/motion/motion.css';
 @import './base/size/size.css';
+@import './base/size/z-index.css';
 @import './base/typography/typography.css';
 @import './functional/size/border.css';
 @import './functional/size/breakpoints.css';
@@ -11,4 +12,5 @@
 @import './functional/size/size-coarse.css';
 @import './functional/size/size-fine.css';
 @import './functional/size/size.css';
+@import './functional/size/z-index.css';
 @import './functional/typography/typography.css';

package/dist/docs/base/size/size.json

@@ -568,5 +568,257 @@
     "path": ["base", "size", "96"],
     "value": "6rem",
     "type": "dimension"
+  },
+  "base-size-negative-12": {
+    "key": "{base.size.negative-12}",
+    "filePath": "src/tokens/base/size/size.json5",
+    "isSource": true,
+    "original": {
+      "$value": {
+        "value": -12,
+        "unit": "px"
+      },
+      "$type": "dimension",
+      "key": "{base.size.negative-12}"
+    },
+    "name": "base-size-negative-12",
+    "attributes": {},
+    "path": ["base", "size", "negative-12"],
+    "value": "-0.75rem",
+    "type": "dimension"
+  },
+  "base-size-negative-16": {
+    "key": "{base.size.negative-16}",
+    "filePath": "src/tokens/base/size/size.json5",
+    "isSource": true,
+    "original": {
+      "$value": {
+        "value": -16,
+        "unit": "px"
+      },
+      "$type": "dimension",
+      "key": "{base.size.negative-16}"
+    },
+    "name": "base-size-negative-16",
+    "attributes": {},
+    "path": ["base", "size", "negative-16"],
+    "value": "-1rem",
+    "type": "dimension"
+  },
+  "base-size-negative-2": {
+    "key": "{base.size.negative-2}",
+    "filePath": "src/tokens/base/size/size.json5",
+    "isSource": true,
+    "original": {
+      "$value": {
+        "value": -2,
+        "unit": "px"
+      },
+      "$type": "dimension",
+      "key": "{base.size.negative-2}"
+    },
+    "name": "base-size-negative-2",
+    "attributes": {},
+    "path": ["base", "size", "negative-2"],
+    "value": "-0.125rem",
+    "type": "dimension"
+  },
+  "base-size-negative-20": {
+    "key": "{base.size.negative-20}",
+    "filePath": "src/tokens/base/size/size.json5",
+    "isSource": true,
+    "original": {
+      "$value": {
+        "value": -20,
+        "unit": "px"
+      },
+      "$type": "dimension",
+      "key": "{base.size.negative-20}"
+    },
+    "name": "base-size-negative-20",
+    "attributes": {},
+    "path": ["base", "size", "negative-20"],
+    "value": "-1.25rem",
+    "type": "dimension"
+  },
+  "base-size-negative-24": {
+    "key": "{base.size.negative-24}",
+    "filePath": "src/tokens/base/size/size.json5",
+    "isSource": true,
+    "original": {
+      "$value": {
+        "value": -24,
+        "unit": "px"
+      },
+      "$type": "dimension",
+      "key": "{base.size.negative-24}"
+    },
+    "name": "base-size-negative-24",
+    "attributes": {},
+    "path": ["base", "size", "negative-24"],
+    "value": "-1.5rem",
+    "type": "dimension"
+  },
+  "base-size-negative-28": {
+    "key": "{base.size.negative-28}",
+    "filePath": "src/tokens/base/size/size.json5",
+    "isSource": true,
+    "original": {
+      "$value": {
+        "value": -28,
+        "unit": "px"
+      },
+      "$type": "dimension",
+      "key": "{base.size.negative-28}"
+    },
+    "name": "base-size-negative-28",
+    "attributes": {},
+    "path": ["base", "size", "negative-28"],
+    "value": "-1.75rem",
+    "type": "dimension"
+  },
+  "base-size-negative-32": {
+    "key": "{base.size.negative-32}",
+    "filePath": "src/tokens/base/size/size.json5",
+    "isSource": true,
+    "original": {
+      "$value": {
+        "value": -32,
+        "unit": "px"
+      },
+      "$type": "dimension",
+      "key": "{base.size.negative-32}"
+    },
+    "name": "base-size-negative-32",
+    "attributes": {},
+    "path": ["base", "size", "negative-32"],
+    "value": "-2rem",
+    "type": "dimension"
+  },
+  "base-size-negative-36": {
+    "key": "{base.size.negative-36}",
+    "filePath": "src/tokens/base/size/size.json5",
+    "isSource": true,
+    "original": {
+      "$value": {
+        "value": -36,
+        "unit": "px"
+      },
+      "$type": "dimension",
+      "key": "{base.size.negative-36}"
+    },
+    "name": "base-size-negative-36",
+    "attributes": {},
+    "path": ["base", "size", "negative-36"],
+    "value": "-2.25rem",
+    "type": "dimension"
+  },
+  "base-size-negative-4": {
+    "key": "{base.size.negative-4}",
+    "filePath": "src/tokens/base/size/size.json5",
+    "isSource": true,
+    "original": {
+      "$value": {
+        "value": -4,
+        "unit": "px"
+      },
+      "$type": "dimension",
+      "key": "{base.size.negative-4}"
+    },
+    "name": "base-size-negative-4",
+    "attributes": {},
+    "path": ["base", "size", "negative-4"],
+    "value": "-0.25rem",
+    "type": "dimension"
+  },
+  "base-size-negative-40": {
+    "key": "{base.size.negative-40}",
+    "filePath": "src/tokens/base/size/size.json5",
+    "isSource": true,
+    "original": {
+      "$value": {
+        "value": -40,
+        "unit": "px"
+      },
+      "$type": "dimension",
+      "key": "{base.size.negative-40}"
+    },
+    "name": "base-size-negative-40",
+    "attributes": {},
+    "path": ["base", "size", "negative-40"],
+    "value": "-2.5rem",
+    "type": "dimension"
+  },
+  "base-size-negative-44": {
+    "key": "{base.size.negative-44}",
+    "filePath": "src/tokens/base/size/size.json5",
+    "isSource": true,
+    "original": {
+      "$value": {
+        "value": -44,
+        "unit": "px"
+      },
+      "$type": "dimension",
+      "key": "{base.size.negative-44}"
+    },
+    "name": "base-size-negative-44",
+    "attributes": {},
+    "path": ["base", "size", "negative-44"],
+    "value": "-2.75rem",
+    "type": "dimension"
+  },
+  "base-size-negative-48": {
+    "key": "{base.size.negative-48}",
+    "filePath": "src/tokens/base/size/size.json5",
+    "isSource": true,
+    "original": {
+      "$value": {
+        "value": -48,
+        "unit": "px"
+      },
+      "$type": "dimension",
+      "key": "{base.size.negative-48}"
+    },
+    "name": "base-size-negative-48",
+    "attributes": {},
+    "path": ["base", "size", "negative-48"],
+    "value": "-3rem",
+    "type": "dimension"
+  },
+  "base-size-negative-6": {
+    "key": "{base.size.negative-6}",
+    "filePath": "src/tokens/base/size/size.json5",
+    "isSource": true,
+    "original": {
+      "$value": {
+        "value": -6,
+        "unit": "px"
+      },
+      "$type": "dimension",
+      "key": "{base.size.negative-6}"
+    },
+    "name": "base-size-negative-6",
+    "attributes": {},
+    "path": ["base", "size", "negative-6"],
+    "value": "-0.375rem",
+    "type": "dimension"
+  },
+  "base-size-negative-8": {
+    "key": "{base.size.negative-8}",
+    "filePath": "src/tokens/base/size/size.json5",
+    "isSource": true,
+    "original": {
+      "$value": {
+        "value": -8,
+        "unit": "px"
+      },
+      "$type": "dimension",
+      "key": "{base.size.negative-8}"
+    },
+    "name": "base-size-negative-8",
+    "attributes": {},
+    "path": ["base", "size", "negative-8"],
+    "value": "-0.5rem",
+    "type": "dimension"
   }
 }

package/dist/docs/base/size/z-index.json

@@ -0,0 +1,107 @@
+{
+  "base-zIndex-0": {
+    "key": "{base.zIndex.0}",
+    "filePath": "src/tokens/base/size/z-index.json5",
+    "isSource": true,
+    "original": {
+      "$value": 0,
+      "$type": "number",
+      "key": "{base.zIndex.0}"
+    },
+    "name": "base-zIndex-0",
+    "attributes": {},
+    "path": ["base", "zIndex", "0"],
+    "value": 0,
+    "type": "number"
+  },
+  "base-zIndex-100": {
+    "key": "{base.zIndex.100}",
+    "filePath": "src/tokens/base/size/z-index.json5",
+    "isSource": true,
+    "original": {
+      "$value": 100,
+      "$type": "number",
+      "key": "{base.zIndex.100}"
+    },
+    "name": "base-zIndex-100",
+    "attributes": {},
+    "path": ["base", "zIndex", "100"],
+    "value": 100,
+    "type": "number"
+  },
+  "base-zIndex-200": {
+    "key": "{base.zIndex.200}",
+    "filePath": "src/tokens/base/size/z-index.json5",
+    "isSource": true,
+    "original": {
+      "$value": 200,
+      "$type": "number",
+      "key": "{base.zIndex.200}"
+    },
+    "name": "base-zIndex-200",
+    "attributes": {},
+    "path": ["base", "zIndex", "200"],
+    "value": 200,
+    "type": "number"
+  },
+  "base-zIndex-300": {
+    "key": "{base.zIndex.300}",
+    "filePath": "src/tokens/base/size/z-index.json5",
+    "isSource": true,
+    "original": {
+      "$value": 300,
+      "$type": "number",
+      "key": "{base.zIndex.300}"
+    },
+    "name": "base-zIndex-300",
+    "attributes": {},
+    "path": ["base", "zIndex", "300"],
+    "value": 300,
+    "type": "number"
+  },
+  "base-zIndex-400": {
+    "key": "{base.zIndex.400}",
+    "filePath": "src/tokens/base/size/z-index.json5",
+    "isSource": true,
+    "original": {
+      "$value": 400,
+      "$type": "number",
+      "key": "{base.zIndex.400}"
+    },
+    "name": "base-zIndex-400",
+    "attributes": {},
+    "path": ["base", "zIndex", "400"],
+    "value": 400,
+    "type": "number"
+  },
+  "base-zIndex-500": {
+    "key": "{base.zIndex.500}",
+    "filePath": "src/tokens/base/size/z-index.json5",
+    "isSource": true,
+    "original": {
+      "$value": 500,
+      "$type": "number",
+      "key": "{base.zIndex.500}"
+    },
+    "name": "base-zIndex-500",
+    "attributes": {},
+    "path": ["base", "zIndex", "500"],
+    "value": 500,
+    "type": "number"
+  },
+  "base-zIndex-600": {
+    "key": "{base.zIndex.600}",
+    "filePath": "src/tokens/base/size/z-index.json5",
+    "isSource": true,
+    "original": {
+      "$value": 600,
+      "$type": "number",
+      "key": "{base.zIndex.600}"
+    },
+    "name": "base-zIndex-600",
+    "attributes": {},
+    "path": ["base", "zIndex", "600"],
+    "value": 600,
+    "type": "number"
+  }
+}