@primer/primitives 11.4.0 → 11.4.1-rc.4e2d1de5

package/src/tokens/functional/shadow/shadow.json5

@@ -11,6 +11,7 @@
         inset: true,
       },
       $type: 'shadow',
+      $description: 'Inset shadow for recessed elements',
       $extensions: {
         'org.primer.figma': {
           collection: 'mode',
@@ -29,13 +30,17 @@
             },
           },
         },
+        'org.primer.llm': {
+          usage: ['input-field', 'pressed-button', 'recessed-area', 'well'],
+          rules: 'Use for elements that appear pressed or inset into the surface. Commonly used for input fields and wells. Do NOT use for floating elements.',
+        },
       },
     },
     resting: {
       xsmall: {
         $value: {
           color: '{base.color.neutral.13}',
-          alpha: 0.06,
+          alpha: 0.05,
           offsetX: '0px',
           offsetY: '1px',
           blur: '1px',
@@ -43,6 +48,7 @@
           inset: false,
         },
         $type: 'shadow',
+        $description: 'Extra small resting shadow for minimal elevation',
         $extensions: {
           'org.primer.figma': {
             collection: 'mode',
@@ -61,13 +67,17 @@
               },
             },
           },
+          'org.primer.llm': {
+            usage: ['badge', 'chip', 'small-card', 'subtle-elevation'],
+            rules: 'Use for very subtle elevation on small elements. Provides minimal lift from surface. Do NOT use for interactive elements needing clear affordance.',
+          },
         },
       },
       small: {
         $value: [
           {
             color: '{base.color.neutral.13}',
-            alpha: 0.06,
+            alpha: 0.04,
             offsetX: '0px',
             offsetY: '1px',
             blur: '1px',
@@ -76,15 +86,16 @@
           },
           {
             color: '{base.color.neutral.13}',
-            alpha: 0.06,
+            alpha: 0.03,
             offsetX: '0px',
             offsetY: '1px',
-            blur: '3px',
+            blur: '2px',
             spread: '0px',
             inset: false,
           },
         ],
         $type: 'shadow',
+        $description: 'Small resting shadow for buttons and interactive elements',
         $extensions: {
           'org.primer.figma': {
             collection: 'mode',
@@ -114,6 +125,10 @@
               ],
             },
           },
+          'org.primer.llm': {
+            usage: ['button', 'interactive-card', 'clickable-element'],
+            rules: 'Use for buttons and small interactive elements at rest. Provides subtle depth and clickable affordance. RECOMMENDED for default button shadows.',
+          },
         },
       },
       medium: {
@@ -136,6 +151,7 @@
           },
         ],
         $type: 'shadow',
+        $description: 'Medium resting shadow for cards and elevated surfaces',
         $extensions: {
           'org.primer.figma': {
             collection: 'mode',
@@ -163,6 +179,10 @@
               ],
             },
           },
+          'org.primer.llm': {
+            usage: ['card', 'panel', 'elevated-surface', 'elevated-sidebar'],
+            rules: 'Use for cards and content panels that sit above the page surface. Provides moderate elevation without appearing to float. Do NOT use for overlays or modals.',
+          },
         },
       },
     },
@@ -281,6 +301,7 @@
           },
         ],
         $type: 'shadow',
+        $description: 'Medium floating shadow for popovers and action menus',
         $extensions: {
           'org.primer.figma': {
             collection: 'mode',
@@ -332,6 +353,10 @@
               ],
             },
           },
+          'org.primer.llm': {
+            usage: ['popover', 'action-menu', 'select-panel', 'autocomplete'],
+            rules: 'Use for medium-sized floating elements like popovers and action menus. More prominent than small but less than dialogs. Do NOT use for full modals.',
+          },
         },
       },
       large: {
@@ -408,6 +433,7 @@
           },
         ],
         $type: 'shadow',
+        $description: 'Extra large floating shadow for full-screen overlays and sheets',
         $extensions: {
           'org.primer.figma': {
             collection: 'mode',
@@ -435,6 +461,10 @@
               ],
             },
           },
+          'org.primer.llm': {
+            usage: ['full-screen-overlay', 'side-sheet', 'drawer', 'large-modal'],
+            rules: 'Use for full-screen or near-full-screen overlays like side sheets and drawers. Maximum elevation in the system. Do NOT use for small floating elements.',
+          },
         },
       },
       legacy: {
@@ -457,6 +487,7 @@
           },
         ],
         $type: 'shadow',
+        $description: 'Legacy floating shadow for backward compatibility',
         $extensions: {
           'org.primer.figma': {},
           'org.primer.overrides': {
@@ -481,6 +512,10 @@
               ],
             },
           },
+          'org.primer.llm': {
+            usage: ['legacy-component', 'backward-compatibility'],
+            rules: 'DEPRECATED: Use shadow-floating-small instead. Only use for maintaining backward compatibility with existing implementations.',
+          },
         },
       },
     },

package/src/tokens/functional/size/border.json5

@@ -29,7 +29,7 @@
       },
     },
     thin: {
-      $value: '1px',
+      $value: {value: 1, unit: 'px'},
       $description: 'Standard 1px border width. Use for most borders, dividers, and outlines throughout the interface',
       $type: 'dimension',
       $extensions: {
@@ -40,7 +40,7 @@
       },
     },
     thick: {
-      $value: '2px',
+      $value: {value: 2, unit: 'px'},
       $description: 'Thick 2px border for emphasis. Use for focus indicators, selected states, or to emphasize important boundaries',
       $type: 'dimension',
       $extensions: {
@@ -55,7 +55,7 @@
       },
     },
     thicker: {
-      $value: '4px',
+      $value: {value: 4, unit: 'px'},
       $description: 'Extra thick 4px border for maximum emphasis. Use sparingly for high-contrast focus indicators or critical visual separators',
       $type: 'dimension',
       $extensions: {
@@ -69,7 +69,7 @@
   outline: {
     focus: {
       offset: {
-        $value: '-2px',
+        $value: {value: -2, unit: 'px'},
         $description: 'Focus outline offset (-2px). Negative value creates an inset outline for keyboard focus indicators, ensuring the focus ring stays within the element bounds',
         $type: 'dimension',
         $extensions: {
@@ -80,7 +80,7 @@
         },
       },
       width: {
-        $value: '2px',
+        $value: {value: 2, unit: 'px'},
         $description: 'Focus outline width (2px). Standard width for keyboard focus indicators to meet WCAG 2.4.7 accessibility requirements',
         $type: 'dimension',
         $extensions: {

package/src/tokens/functional/size/breakpoints.json5

@@ -1,7 +1,7 @@
 {
   "breakpoint": {
     "xsmall": {
-      "$value": "320px",
+      "$value": {"value": 320, "unit": "px"},
       "$type": "dimension",
       "$extensions": {
         "org.primer.figma": {
@@ -11,7 +11,7 @@
       }
     },
     "small": {
-      "$value": "544px",
+      "$value": {"value": 544, "unit": "px"},
       "$type": "dimension",
       "$extensions": {
         "org.primer.figma": {
@@ -21,7 +21,7 @@
       }
     },
     "medium": {
-      "$value": "768px",
+      "$value": {"value": 768, "unit": "px"},
       "$type": "dimension",
       "$extensions": {
         "org.primer.figma": {
@@ -31,7 +31,7 @@
       }
     },
     "large": {
-      "$value": "1012px",
+      "$value": {"value": 1012, "unit": "px"},
       "$type": "dimension",
       "$extensions": {
         "org.primer.figma": {
@@ -41,7 +41,7 @@
       }
     },
     "xlarge": {
-      "$value": "1280px",
+      "$value": {"value": 1280, "unit": "px"},
       "$type": "dimension",
       "$extensions": {
         "org.primer.figma": {
@@ -51,7 +51,7 @@
       }
     },
     "xxlarge": {
-      "$value": "1400px",
+      "$value": {"value": 1400, "unit": "px"},
       "$type": "dimension",
       "$extensions": {
         "org.primer.figma": {

package/src/tokens/functional/size/radius.json5

@@ -1,7 +1,7 @@
 {
   borderRadius: {
     small: {
-      $value: '3px',
+      $value: {value: 3, unit: 'px'},
       $description: 'Small border radius (3px). Use for small variants of components or small UI elements like badges, tags, or anything below 16px in height',
       $type: 'dimension',
       $extensions: {
@@ -19,7 +19,7 @@
       },
     },
     medium: {
-      $value: '6px',
+      $value: {value: 6, unit: 'px'},
       $description: 'Medium border radius (6px). The default choice for most buttons, cards, and containers',
       $type: 'dimension',
       $extensions: {
@@ -37,7 +37,7 @@
       },
     },
     large: {
-      $value: '12px',
+      $value: {value: 12, unit: 'px'},
       $description: 'Large border radius (12px). Use for larger containers, dialogs, or when more visual softness is desired. Always use this for buttons.',
       $type: 'dimension',
       $extensions: {
@@ -55,7 +55,7 @@
       },
     },
     full: {
-      $value: '9999px',
+      $value: {value: 9999, unit: 'px'},
       $type: 'dimension',
       $description: 'Use this border radius for pill shaped elements',
       $extensions: {

package/src/tokens/functional/size/size.json5

@@ -51,7 +51,7 @@
         }
       },
       "paddingBlock": {
-        "$value": "2px",
+        "$value": {"value": 2, "unit": "px"},
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -189,7 +189,7 @@
         }
       },
       "paddingBlock": {
-        "$value": "6px",
+        "$value": {"value": 6, "unit": "px"},
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -263,7 +263,7 @@
         }
       },
       "paddingBlock": {
-        "$value": "10px",
+        "$value": {"value": 10, "unit": "px"},
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -327,7 +327,7 @@
         }
       },
       "paddingBlock": {
-        "$value": "14px",
+        "$value": {"value": 14, "unit": "px"},
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -380,7 +380,7 @@
     },
     "strokeWidth": {
       "default": {
-        "$value": "2px",
+        "$value": {"value": 2, "unit": "px"},
         "$type": "dimension"
       }
     },
@@ -615,7 +615,7 @@
     },
     "width": {
       "xsmall": {
-        "$value": "192px",
+        "$value": {"value": 192, "unit": "px"},
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -625,7 +625,7 @@
         }
       },
       "small": {
-        "$value": "320px",
+        "$value": {"value": 320, "unit": "px"},
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -635,7 +635,7 @@
         }
       },
       "medium": {
-        "$value": "480px",
+        "$value": {"value": 480, "unit": "px"},
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -645,7 +645,7 @@
         }
       },
       "large": {
-        "$value": "640px",
+        "$value": {"value": 640, "unit": "px"},
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -655,7 +655,7 @@
         }
       },
       "xlarge": {
-        "$value": "960px",
+        "$value": {"value": 960, "unit": "px"},
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -667,7 +667,7 @@
     },
     "height": {
       "small": {
-        "$value": "256px",
+        "$value": {"value": 256, "unit": "px"},
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -677,7 +677,7 @@
         }
       },
       "medium": {
-        "$value": "320px",
+        "$value": {"value": 320, "unit": "px"},
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -687,7 +687,7 @@
         }
       },
       "large": {
-        "$value": "432px",
+        "$value": {"value": 432, "unit": "px"},
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -697,7 +697,7 @@
         }
       },
       "xlarge": {
-        "$value": "600px",
+        "$value": {"value": 600, "unit": "px"},
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -762,7 +762,7 @@
       }
     },
     "offset": {
-      "$value": "4px",
+      "$value": {"value": 4, "unit": "px"},
       "$type": "dimension",
       "$extensions": {
         "org.primer.figma": {

package/src/tokens/functional/typography/typography.json5

@@ -450,17 +450,18 @@
           fontFamily: '{fontStack.sansSerif}',
         },
         $type: 'typography',
-        $description: 'Compact small font with a smaller line height of 16px. Use it for single-line scenarios, as the small sizing doesn’t pass accessibility requirements.',        
+        $description: 'Compact small font with a smaller line height of 16px. Use it for single-line scenarios, as the small sizing doesn’t pass accessibility requirements.',
         $extensions: {
           'org.primer.llm': {
             usage: ['caption', 'label', 'badge-text', 'single-line-metadata'],
             rules: 'Use only for single-line or short text. Does NOT meet accessibility requirements for body text.',
           },
-        },      },
+        },
+      },
     },
     codeBlock: {
       size: {
-        $value: '13px',
+        $value: {value: 13, unit: 'px'},
         $type: 'dimension',
         $extensions: {
           'org.primer.figma': {
@@ -511,7 +512,10 @@
     },
     codeInline: {
       size: {
-        $value: '0.9285em',
+        $value: {
+          value: 0.9285,
+          unit: 'em',
+        },
         $type: 'dimension',
         $extensions: {
           'org.primer.figma': {

package/dist/build/parsers/index.d.ts

@@ -1 +0,0 @@
-export { w3cJsonParser } from './w3cJsonParser.js';

package/dist/build/parsers/index.js

@@ -1 +0,0 @@
-export { w3cJsonParser } from './w3cJsonParser.js';

package/dist/build/parsers/w3cJsonParser.d.ts

@@ -1,6 +0,0 @@
-import type { Parser } from 'style-dictionary/types';
-/**
- * @description Parses a valid [json5](https://json5.org) file and replaces `$value` with `value` and `$description` with `comment` to make a w3c standard file compatible with style dictionary
- * @pattern supported file extensions `.json` or `.json5`
- */
-export declare const w3cJsonParser: Parser;

package/dist/build/parsers/w3cJsonParser.js

@@ -1,25 +0,0 @@
-import JSON5 from 'json5';
-/**
- * @description Parses a valid [json5](https://json5.org) file and replaces `$value` with `value` and `$description` with `comment` to make a w3c standard file compatible with style dictionary
- * @pattern supported file extensions `.json` or `.json5`
- */
-export const w3cJsonParser = {
-    name: 'w3cJsonParser',
-    pattern: /\.json5?$/,
-    parser: ({ filePath, contents }) => {
-        // replace $value with value so that style dictionary recognizes it
-        try {
-            contents = contents
-                .replace(/["|']?\$value["|']?:/g, '"value":')
-                // convert $description to comment
-                .replace(/["|']?\$?description["|']?:/g, '"comment":')
-                .replace(/["|']?\$?type["|']?:/g, '"$type":')
-                .replace(/["|']?\$?extensions["|']?:/g, '"$extensions":');
-            //
-            return JSON5.parse(contents);
-        }
-        catch (error) {
-            throw new Error(`Invalid json5 file "${filePath}". Error: ${error}`);
-        }
-    },
-};

package/dist/removed/testing.json5

@@ -1,4 +0,0 @@
-/* rename token to trigger actions to run on token change */
-{
-  "testing": null 
-}

package/guidelines/color.llm.md

@@ -1,16 +0,0 @@
-# Color Guidelines
-
-How to use color tokens correctly for accessible, themeable interfaces.
-
-## Pairing Rules
-
-- MUST use `--fgColor-onEmphasis` for text on any `-emphasis` background
-- MUST use `--fgColor-{semantic}` for text on any `-muted` background
-- MUST use `--fgColor-default` for text on `--bgColor-default` or `--bgColor-muted`
-- NEVER pair `--fgColor-muted` with `--bgColor-muted` (insufficient contrast)
-
-## Contrast Requirements
-
-- MUST ensure 4.5:1 contrast ratio for normal text (WCAG AA)
-- MUST ensure 3:1 contrast ratio for large text and UI components
-- SHOULD use semantic token pairings which are pre-validated for contrast

package/guidelines/guidelines.llm.md

@@ -1,34 +0,0 @@
-# Primer Design Token Guidelines
-
-Quick reference for using Primer design tokens correctly.
-
-## Tokens
-
-- MUST use CSS custom properties (design tokens) for all values—never raw values like `#fff` or `16px`
-
-## Interactive Elements
-
-- MUST define all five states for interactive elements (rest, hover, focus, active/pressed, disabled)
-- MUST use `:focus-visible` (not `:focus`) for keyboard focus styles
-- NEVER remove hover or focus states for aesthetics
-
-## Motion
-
-Use subtle motion to enhance interactivity and understanding. All interactive states (hover, focus, press) MUST have motion transitions. Keep animations under 300ms and respect `prefers-reduced-motion`.
-
-→ [Full motion guidelines](motion.llm.md)
-
-## Color
-
-- Use semantic pairings (fg/bg) and enforce contrast requirements.
-- See: [color guidelines](color.llm.md)
-
-## Spacing
-
-- Use control/stack tokens for sizing, padding, and gaps.
-- See: [spacing guidelines](spacing.llm.md)
-
-## Typography
-
-- Use shorthand text tokens and follow responsive guidance.
-- See: [typography guidelines](typography.llm.md)

package/guidelines/motion.llm.md

@@ -1,41 +0,0 @@
-# Motion Guidelines
-
-Motion enhances user understanding and provides feedback. Keep it subtle and purposeful.
-
-## Core Principles
-
-- MUST use motion for interactive state changes (hover, focus, press)
-- MUST keep motion subtle—users should feel it, not notice it
-- MUST use motion to support understanding, not distract
-- SHOULD keep animations under 300ms for UI interactions
-- NEVER use motion purely for decoration
-- NEVER create motion that loops indefinitely without user control
-
-## When to Use Motion
-
-- MUST animate hover states on interactive elements (buttons, links, cards)
-- MUST animate focus states for keyboard navigation
-- MUST animate state transitions (expand/collapse, show/hide)
-- SHOULD animate page/view transitions
-- SHOULD animate loading states to indicate progress
-- NEVER animate static content or non-interactive elements
-
-## Easing Selection
-
-1. **Element entering or exiting viewport?** → `ease-out` (default)
-2. **Moving or morphing on screen?** → `ease-in-out`
-3. **Hover state change?** → `ease`
-4. **Constant motion (loaders)?** → `linear`
-
-## Duration Guidelines
-
-- MUST use 100-200ms for micro-interactions (hover, focus)
-- SHOULD use 200-300ms for state changes (expand, collapse)
-- SHOULD use 300-500ms for larger transitions (modals, page changes)
-- NEVER exceed 500ms for UI interactions
-
-## Accessibility
-
-- MUST respect `prefers-reduced-motion` media query
-- MUST provide instant alternatives when motion is reduced
-- NEVER rely solely on motion to convey information

package/guidelines/spacing.llm.md

@@ -1,20 +0,0 @@
-# Spacing Guidelines
-
-How to use spacing and sizing tokens for consistent layouts.
-
-## Control Sizing & Padding
-
-- Use the control size tokens (`--control-*-size`) for height and matching padding tokens per size.
-- Choose padding density via suffixes: `-condensed`, `-normal` (default), `-spacious`.
-
-## Stack Spacing
-
-- Use stack tokens for layout gaps (`--stack-gap-*`, `--stack-padding-*`).
-- For control groups, use control stack tokens (e.g., `--controlStack-*-gap-*`).
-
-## Rules
-
-- MUST use control tokens for interactive elements (buttons, inputs)
-- MUST use stack tokens for layout spacing
-- MUST match padding density to the control's purpose
-- SHOULD use `medium` size as the default

package/guidelines/typography.llm.md

@@ -1,14 +0,0 @@
-# Typography Guidelines
-
-How to use typography tokens for readable, consistent text.
-
-## Responsive Typography
-
-- SHOULD use `--text-title-shorthand-medium` on narrow viewports instead of `large`
-- SHOULD use `--text-body-shorthand-medium` instead of `large` on mobile
-
-## Rules
-
-- MUST use shorthand tokens (they ensure proper line-height)
-- SHOULD use semantic heading levels (h1-h6) with corresponding title tokens
-- NEVER set font-size without also setting line-height

package/src/tokens/removed/testing.json5

@@ -1,4 +0,0 @@
-/* rename token to trigger actions to run on token change */
-{
-  "testing": null 
-}