@primer/primitives 0.0.0-20260220144751 → 0.0.0-20260220163920

package/DESIGN_TOKENS_GUIDE.md

@@ -98,30 +98,6 @@
 | 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,48 +568,6 @@ 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/css/base/size/size.css

@@ -0,0 +1,35 @@
+:root {
+  --base-size-112: 7rem;
+  --base-size-12: 0.75rem;
+  --base-size-128: 8rem;
+  --base-size-16: 1rem;
+  --base-size-2: 0.125rem;
+  --base-size-20: 1.25rem;
+  --base-size-24: 1.5rem;
+  --base-size-28: 1.75rem;
+  --base-size-32: 2rem;
+  --base-size-36: 2.25rem;
+  --base-size-4: 0.25rem;
+  --base-size-40: 2.5rem;
+  --base-size-44: 2.75rem;
+  --base-size-48: 3rem;
+  --base-size-6: 0.375rem;
+  --base-size-64: 4rem;
+  --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/functional/size/border.css

@@ -0,0 +1,11 @@
+:root {
+  --borderWidth-thick: 0.125rem; /** Thick 2px border for emphasis. Use for focus indicators, selected states, or to emphasize important boundaries */
+  --borderWidth-thicker: 0.25rem; /** Extra thick 4px border for maximum emphasis. Use sparingly for high-contrast focus indicators or critical visual separators */
+  --borderWidth-thin: 0.0625rem; /** Standard 1px border width. Use for most borders, dividers, and outlines throughout the interface */
+  --outline-focus-offset: -0.125rem; /** Focus outline offset (-2px). Negative value creates an inset outline for keyboard focus indicators, ensuring the focus ring stays within the element bounds */
+  --outline-focus-width: 0.125rem; /** Focus outline width (2px). Standard width for keyboard focus indicators to meet WCAG 2.4.7 accessibility requirements */
+  --borderWidth-default: var(--borderWidth-thin); /** Default border width for most UI elements. Alias of borderWidth.thin (1px) */
+  --boxShadow-thick: inset 0 0 0 var(--borderWidth-thick); /** Thick shadow (2px) used instead of a border for emphasis without layout shift */
+  --boxShadow-thicker: inset 0 0 0 var(--borderWidth-thicker); /** Thickest shadow (4px) used for high emphasis borders without layout shift. Use sparingly for maximum visual impact */
+  --boxShadow-thin: inset 0 0 0 var(--borderWidth-thin); /** Thin shadow used instead of a border to prevent layout shift */
+}

package/dist/css/functional/size/breakpoints.css

@@ -0,0 +1,8 @@
+:root {
+  --breakpoint-large: 63.25rem;
+  --breakpoint-medium: 48rem;
+  --breakpoint-small: 34rem;
+  --breakpoint-xlarge: 80rem;
+  --breakpoint-xsmall: 20rem;
+  --breakpoint-xxlarge: 87.5rem;
+}

package/dist/css/functional/size/radius.css

@@ -0,0 +1,7 @@
+:root {
+  --borderRadius-full: 624.9375rem; /** Use this border radius for pill shaped elements */
+  --borderRadius-large: 0.75rem; /** Large border radius (12px). Use for larger containers, dialogs, or when more visual softness is desired. */
+  --borderRadius-medium: 0.375rem; /** Medium border radius (6px). The default choice for most buttons, cards, and containers */
+  --borderRadius-small: 0.1875rem; /** Small border radius (3px). Use for small variants of components or small UI elements like badges, tags, or anything below 16px in height */
+  --borderRadius-default: var(--borderRadius-medium); /** Default border radius for most UI elements. Alias of borderRadius.medium (6px). Use when in doubt */
+}

package/dist/css/functional/size/size-coarse.css

@@ -0,0 +1,8 @@
+@media (pointer: coarse) {
+  :root {
+    --control-minTarget-auto: 2.75rem; /** Minimum touch target size for coarse pointer devices (touch screens) */
+    --controlStack-large-gap-auto: 0.75rem; /** Gap between stacked controls in large density layouts for touch devices */
+    --controlStack-medium-gap-auto: 0.75rem; /** Gap between stacked controls in medium density layouts for touch devices */
+    --controlStack-small-gap-auto: 1rem; /** Gap between stacked controls in small density layouts for touch devices */
+  }
+}

package/dist/css/functional/size/size-fine.css

@@ -0,0 +1,8 @@
+@media (pointer: fine) {
+  :root {
+    --control-minTarget-auto: 1rem; /** Minimum target size for fine pointer devices (mouse) */
+    --controlStack-large-gap-auto: 0.5rem; /** Gap between stacked controls in large density layouts for mouse interfaces */
+    --controlStack-medium-gap-auto: 0.5rem; /** Gap between stacked controls in medium density layouts for mouse interfaces */
+    --controlStack-small-gap-auto: 0.5rem; /** Gap between stacked controls in small density layouts for mouse interfaces */
+  }
+}

package/dist/css/functional/size/size.css

@@ -0,0 +1,73 @@
+:root {
+  --control-large-paddingBlock: 0.625rem;
+  --control-medium-paddingBlock: 0.375rem;
+  --control-xlarge-paddingBlock: 0.875rem;
+  --control-xsmall-paddingBlock: 0.125rem;
+  --overlay-height-large: 27rem;
+  --overlay-height-medium: 20rem;
+  --overlay-height-small: 16rem;
+  --overlay-height-xlarge: 37.5rem;
+  --overlay-offset: 0.25rem;
+  --overlay-width-large: 40rem;
+  --overlay-width-medium: 30rem;
+  --overlay-width-small: 20rem;
+  --overlay-width-xlarge: 60rem;
+  --overlay-width-xsmall: 12rem;
+  --spinner-strokeWidth-default: 0.125rem;
+  --control-large-gap: 0.5rem;
+  --control-large-lineBoxHeight: 1.25rem;
+  --control-large-paddingInline-condensed: 0.5rem;
+  --control-large-paddingInline-normal: 0.75rem;
+  --control-large-paddingInline-spacious: 1rem;
+  --control-large-size: 2.5rem;
+  --control-medium-gap: 0.5rem;
+  --control-medium-lineBoxHeight: 1.25rem;
+  --control-medium-paddingInline-condensed: 0.5rem;
+  --control-medium-paddingInline-normal: 0.75rem;
+  --control-medium-paddingInline-spacious: 1rem;
+  --control-medium-size: 2rem;
+  --control-minTarget-coarse: 2.75rem;
+  --control-minTarget-fine: 1rem;
+  --control-small-gap: 0.25rem;
+  --control-small-lineBoxHeight: 1.25rem;
+  --control-small-paddingBlock: 0.25rem;
+  --control-small-paddingInline-condensed: 0.5rem;
+  --control-small-paddingInline-normal: 0.75rem;
+  --control-small-paddingInline-spacious: 1rem;
+  --control-small-size: 1.75rem;
+  --control-xlarge-gap: 0.5rem;
+  --control-xlarge-lineBoxHeight: 1.25rem;
+  --control-xlarge-paddingInline-condensed: 0.5rem;
+  --control-xlarge-paddingInline-normal: 0.75rem;
+  --control-xlarge-paddingInline-spacious: 1rem;
+  --control-xlarge-size: 3rem;
+  --control-xsmall-gap: 0.25rem;
+  --control-xsmall-lineBoxHeight: 1.25rem;
+  --control-xsmall-paddingInline-condensed: 0.25rem;
+  --control-xsmall-paddingInline-normal: 0.5rem;
+  --control-xsmall-paddingInline-spacious: 0.75rem;
+  --control-xsmall-size: 1.5rem;
+  --controlStack-large-gap-auto: 0.5rem;
+  --controlStack-large-gap-condensed: 0.5rem;
+  --controlStack-large-gap-spacious: 0.75rem;
+  --controlStack-medium-gap-auto: 0.5rem;
+  --controlStack-medium-gap-condensed: 0.5rem;
+  --controlStack-medium-gap-spacious: 0.75rem;
+  --controlStack-small-gap-auto: 0.5rem;
+  --controlStack-small-gap-condensed: 0.5rem;
+  --controlStack-small-gap-spacious: 1rem;
+  --overlay-borderRadius: 0.375rem;
+  --overlay-padding-condensed: 0.5rem;
+  --overlay-padding-normal: 1rem;
+  --overlay-paddingBlock-condensed: 0.25rem;
+  --overlay-paddingBlock-normal: 0.75rem;
+  --spinner-size-large: 4rem;
+  --spinner-size-medium: 2rem;
+  --spinner-size-small: 1rem;
+  --stack-gap-condensed: 0.5rem;
+  --stack-gap-normal: 1rem;
+  --stack-gap-spacious: 1.5rem;
+  --stack-padding-condensed: 0.5rem;
+  --stack-padding-normal: 1rem;
+  --stack-padding-spacious: 1.5rem;
+}

package/dist/css/functional/size/viewport.css

@@ -0,0 +1,6 @@
+@custom-media --viewportRange-landscape (orientation: landscape);
+@custom-media --viewportRange-narrow (max-width: calc(48rem - 0.02px));
+@custom-media --viewportRange-narrowLandscape ((max-width: calc(63.25rem - 0.02px)) and (max-height: calc(34rem - 0.02px)) and (orientation: landscape));
+@custom-media --viewportRange-portrait (orientation: portrait);
+@custom-media --viewportRange-regular (min-width: 48rem);
+@custom-media --viewportRange-wide (min-width: 87.5rem);

package/dist/css/primitives.css

@@ -3,5 +3,12 @@
  * @rule Never use raw values (hex/px). Use semantic tokens ONLY.
  */
 @import './base/motion/motion.css';
+@import './base/size/size.css';
 @import './base/typography/typography.css';
+@import './functional/size/border.css';
+@import './functional/size/breakpoints.css';
+@import './functional/size/radius.css';
+@import './functional/size/size-coarse.css';
+@import './functional/size/size-fine.css';
+@import './functional/size/size.css';
 @import './functional/typography/typography.css';