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

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

@@ -2,21 +2,24 @@
   boxShadow: {
     thin: {
       $value: 'inset 0 0 0 {borderWidth.thin}',
-      $description: 'Thin shadow for borders',
+      $description: 'Thin shadow used instead of a border to prevent layout shift',
       $type: 'string',
     },
     thick: {
       $value: 'inset 0 0 0 {borderWidth.thick}',
+      $description: 'Thick shadow (2px) used instead of a border for emphasis without layout shift',
       $type: 'string',
     },
     thicker: {
       $value: 'inset 0 0 0 {borderWidth.thicker}',
+      $description: 'Thickest shadow (4px) used for high emphasis borders without layout shift. Use sparingly for maximum visual impact',
       $type: 'string',
     },
   },
   borderWidth: {
     default: {
       $value: '{borderWidth.thin}',
+      $description: 'Default border width for most UI elements. Alias of borderWidth.thin (1px)',
       $type: 'dimension',
       $extensions: {
         'org.primer.figma': {
@@ -26,7 +29,8 @@
       },
     },
     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: {
         'org.primer.figma': {
@@ -36,17 +40,23 @@
       },
     },
     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: {
         'org.primer.figma': {
           collection: 'functional/size',
           scopes: ['borderWidth', 'effectFloat'],
         },
+        'org.primer.llm': {
+          usage: ['focus-indicator', 'selected-state', 'emphasis-border'],
+          rules: 'MUST use for focus rings on interactive elements. Do NOT use for subtle dividers.',
+        },
       },
     },
     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: {
         'org.primer.figma': {
@@ -56,78 +66,11 @@
       },
     },
   },
-  borderRadius: {
-    small: {
-      $value: '3px',
-      $type: 'dimension',
-      $extensions: {
-        'org.primer.figma': {
-          collection: 'functional/size',
-          scopes: ['radius'],
-          codeSyntax: {
-            web: 'var(--borderRadius-small) /* utility class: .rounded-1 */',
-          },
-        },
-      },
-    },
-    medium: {
-      $value: '6px',
-      $type: 'dimension',
-      $extensions: {
-        'org.primer.figma': {
-          collection: 'functional/size',
-          scopes: ['radius'],
-          codeSyntax: {
-            web: 'var(--borderRadius-medium) /* utility class: .rounded-2 */',
-          },
-        },
-      },
-    },
-    large: {
-      $value: '12px',
-      $type: 'dimension',
-      $extensions: {
-        'org.primer.figma': {
-          collection: 'functional/size',
-          scopes: ['radius'],
-          codeSyntax: {
-            web: 'var(--borderRadius-large) /* utility class: .rounded-3 */',
-          },
-        },
-      },
-    },
-    full: {
-      $value: '9999px',
-      $type: 'dimension',
-      $description: 'Use this border radius for pill shaped elements',
-      $extensions: {
-        'org.primer.figma': {
-          collection: 'functional/size',
-          scopes: ['radius'],
-          codeSyntax: {
-            web: 'var(--borderRadius-full) /* utility class: .circle */',
-          },
-        },
-      },
-    },
-    default: {
-      $value: '{borderRadius.medium}',
-      $type: 'dimension',
-      $extensions: {
-        'org.primer.figma': {
-          collection: 'functional/size',
-          scopes: ['radius'],
-          codeSyntax: {
-            web: 'var(--borderRadius-default) /* utility class: .rounded-2 */',
-          },
-        },
-      },
-    },
-  },
   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: {
           'org.primer.figma': {
@@ -137,13 +80,18 @@
         },
       },
       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: {
           'org.primer.figma': {
             collection: 'functional/size',
             scopes: ['borderWidth', 'effectFloat'],
           },
+          'org.primer.llm': {
+            usage: ['focus-ring', 'keyboard-focus', 'accessibility'],
+            rules: 'MUST use for all keyboard focus indicators. Required for WCAG 2.4.7 compliance.',
+          },
         },
       },
     },

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

@@ -0,0 +1,90 @@
+{
+  borderRadius: {
+    small: {
+      $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: {
+        'org.primer.figma': {
+          collection: 'functional/size',
+          scopes: ['radius'],
+          codeSyntax: {
+            web: 'var(--borderRadius-small) /* utility class: .rounded-1 */',
+          },
+        },
+        'org.primer.llm': {
+          usage: ['badge', 'tag', 'label', 'small-input'],
+          rules: 'Use for small UI elements under 16px height. Do NOT use for buttons or cards.',
+        },
+      },
+    },
+    medium: {
+      $value: {value: 6, unit: 'px'},
+      $description: 'Medium border radius (6px). The default choice for most buttons, cards, and containers',
+      $type: 'dimension',
+      $extensions: {
+        'org.primer.figma': {
+          collection: 'functional/size',
+          scopes: ['radius'],
+          codeSyntax: {
+            web: 'var(--borderRadius-medium) /* utility class: .rounded-2 */',
+          },
+        },
+        'org.primer.llm': {
+          usage: ['button', 'input', 'textarea', 'select', 'card', 'container'],
+          rules: 'Default choice for most components. Use for inputs, cards, and general containers.',
+        },
+      },
+    },
+    large: {
+      $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: {
+        'org.primer.figma': {
+          collection: 'functional/size',
+          scopes: ['radius'],
+          codeSyntax: {
+            web: 'var(--borderRadius-large) /* utility class: .rounded-3 */',
+          },
+        },
+        'org.primer.llm': {
+          usage: ['dialog', 'card', 'modal'],
+          rules: 'Recommended for dialogs and modals.',
+        },
+      },
+    },
+    full: {
+      $value: {value: 9999, unit: 'px'},
+      $type: 'dimension',
+      $description: 'Use this border radius for pill shaped elements',
+      $extensions: {
+        'org.primer.figma': {
+          collection: 'functional/size',
+          scopes: ['radius'],
+          codeSyntax: {
+            web: 'var(--borderRadius-full) /* utility class: .circle */',
+          },
+        },
+        'org.primer.llm': {
+          usage: ['avatar', 'pill-badge', 'circular-button'],
+          rules: 'Use for avatars and pill-shaped elements. Do NOT use for rectangular containers.',
+        },
+      },
+    },
+    default: {
+      $value: '{borderRadius.medium}',
+      $description: 'Default border radius for most UI elements. Alias of borderRadius.medium (6px). Use when in doubt',
+      $type: 'dimension',
+      $extensions: {
+        'org.primer.figma': {
+          collection: 'functional/size',
+          scopes: ['radius'],
+          codeSyntax: {
+            web: 'var(--borderRadius-default) /* utility class: .rounded-2 */',
+          },
+        },
+      },
+    },
+  },
+}

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

@@ -3,7 +3,14 @@
     "minTarget": {
       "auto": {
         "$value": "{base.size.44}",
-        "$type": "dimension"
+        "$type": "dimension",
+        "$description": "Minimum touch target size for coarse pointer devices (touch screens)",
+        "$extensions": {
+          "org.primer.llm": {
+            "usage": ["touch-target", "mobile-button", "tap-area"],
+            "rules": "Use as minimum size for interactive elements on touch devices. Ensures WCAG 2.5.5 compliance (44x44px minimum). Do NOT use for fine pointer (mouse) contexts."
+          }
+        }
       }
     }
   },
@@ -12,7 +19,14 @@
       "gap": {
         "auto": {
           "$value": "{base.size.16}",
-          "$type": "dimension"
+          "$type": "dimension",
+          "$description": "Gap between stacked controls in small density layouts for touch devices",
+          "$extensions": {
+            "org.primer.llm": {
+              "usage": ["touch-control-spacing", "mobile-form-gap", "stacked-buttons"],
+              "rules": "Use for spacing between interactive controls on touch devices in compact layouts. Provides adequate touch separation. Do NOT use for desktop/mouse interfaces."
+            }
+          }
         }
       }
     },
@@ -20,7 +34,14 @@
       "gap": {
         "auto": {
           "$value": "{base.size.12}",
-          "$type": "dimension"
+          "$type": "dimension",
+          "$description": "Gap between stacked controls in medium density layouts for touch devices",
+          "$extensions": {
+            "org.primer.llm": {
+              "usage": ["touch-control-spacing", "mobile-form-gap", "stacked-buttons"],
+              "rules": "Use for spacing between interactive controls on touch devices in standard layouts. Do NOT use for desktop/mouse interfaces."
+            }
+          }
         }
       }
     }

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

@@ -1,28 +1,49 @@
 {
-  "control": {
-    "minTarget": {
-      "auto": {
-        "$value": "{base.size.16}",
-        "$type": "dimension"
-      }
-    }
+  control: {
+    minTarget: {
+      auto: {
+        $value: '{base.size.16}',
+        $type: 'dimension',
+        $description: 'Minimum target size for fine pointer devices (mouse)',
+        $extensions: {
+          'org.primer.llm': {
+            usage: ['mouse-target', 'desktop-button', 'click-area'],
+            rules: 'Use as minimum size for interactive elements on desktop/mouse interfaces. Smaller than touch targets for denser layouts. Do NOT use for touch/mobile contexts.',
+          },
+        },
+      },
+    },
   },
-  "controlStack": {
-    "small": {
-      "gap": {
-        "auto": {
-          "$value": "{base.size.8}",
-          "$type": "dimension"
-        }
-      }
+  controlStack: {
+    small: {
+      gap: {
+        auto: {
+          $value: '{base.size.8}',
+          $type: 'dimension',
+          $description: 'Gap between stacked controls in small density layouts for mouse interfaces',
+          $extensions: {
+            'org.primer.llm': {
+              usage: ['desktop-control-spacing', 'form-gap', 'stacked-buttons'],
+              rules: 'Use for spacing between interactive controls on desktop in compact layouts. Tighter spacing than touch devices. Do NOT use for mobile/touch interfaces.',
+            },
+          },
+        },
+      },
+    },
+    medium: {
+      gap: {
+        auto: {
+          $value: '{base.size.8}',
+          $type: 'dimension',
+          $description: 'Gap between stacked controls in medium density layouts for mouse interfaces',
+          $extensions: {
+            'org.primer.llm': {
+              usage: ['desktop-control-spacing', 'form-gap', 'stacked-buttons'],
+              rules: 'Use for spacing between interactive controls on desktop in standard layouts. Do NOT use for mobile/touch interfaces.',
+            },
+          },
+        },
+      },
     },
-    "medium": {
-      "gap": {
-        "auto": {
-          "$value": "{base.size.8}",
-          "$type": "dimension"
-        }
-      }
-    }
-  }
+  },
 }

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

@@ -1,5 +1,12 @@
 {
   "control": {
+    "$description": "Size tokens for interactive controls (buttons, inputs, selects). Includes overall size, padding, line height, and gap values for each size variant.",
+    "$extensions": {
+      "org.primer.llm": {
+        "usage": ["button", "input", "select", "form-control", "interactive-element"],
+        "rules": "Use size variants consistently across related controls. Match control size to context: xsmall/small for dense UIs, medium for standard forms, large/xlarge for prominent CTAs. Use minTarget values to ensure touch accessibility on coarse pointer devices."
+      }
+    },
     "minTarget": {
       "fine": {
         "$value": "{base.size.16}",
@@ -44,7 +51,7 @@
         }
       },
       "paddingBlock": {
-        "$value": "2px",
+        "$value": {"value": 2, "unit": "px"},
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -182,7 +189,7 @@
         }
       },
       "paddingBlock": {
-        "$value": "6px",
+        "$value": {"value": 6, "unit": "px"},
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -256,7 +263,7 @@
         }
       },
       "paddingBlock": {
-        "$value": "10px",
+        "$value": {"value": 10, "unit": "px"},
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -320,7 +327,7 @@
         }
       },
       "paddingBlock": {
-        "$value": "14px",
+        "$value": {"value": 14, "unit": "px"},
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -364,9 +371,16 @@
     }
   },
   "spinner": {
+    "$description": "Size and stroke tokens for loading spinner components.",
+    "$extensions": {
+      "org.primer.llm": {
+        "usage": ["loading-spinner", "progress-indicator", "async-loading"],
+        "rules": "Match spinner size to context: small for inline loading, medium for buttons and cards, large for full-page loading states."
+      }
+    },
     "strokeWidth": {
       "default": {
-        "$value": "2px",
+        "$value": {"value": 2, "unit": "px"},
         "$type": "dimension"
       }
     },
@@ -404,6 +418,13 @@
     }
   },
   "stack": {
+    "$description": "Spacing tokens for Stack layout components including padding and gap values.",
+    "$extensions": {
+      "org.primer.llm": {
+        "usage": ["stack-layout", "vertical-stack", "horizontal-stack", "flex-container"],
+        "rules": "Use condensed for dense lists, normal for standard layouts, spacious for prominent sections. Stack tokens provide consistent spacing within layout containers."
+      }
+    },
     "padding": {
       "condensed": {
         "$value": "{base.size.8}",
@@ -494,6 +515,13 @@
     }
   },
   "controlStack": {
+    "$description": "Gap tokens for groups of controls (buttons, form elements) arranged in a row or column.",
+    "$extensions": {
+      "org.primer.llm": {
+        "usage": ["button-group", "form-control-group", "action-bar", "toolbar"],
+        "rules": "Use with groups of related controls. Match gap size to control size (small controls use small gaps). Condensed for tight groupings, spacious for separated actions."
+      }
+    },
     "small": {
       "gap": {
         "condensed": {
@@ -578,9 +606,16 @@
     }
   },
   "overlay": {
+    "$description": "Dimension tokens for overlay components like modals, dialogs, popovers, and dropdown menus.",
+    "$extensions": {
+      "org.primer.llm": {
+        "usage": ["modal", "dialog", "popover", "dropdown", "tooltip", "overlay-panel"],
+        "rules": "Match overlay size to content: xsmall/small for menus and tooltips, medium for dialogs, large/xlarge for complex modals. Use height tokens to constrain scrollable overlays. Always consider viewport size constraints."
+      }
+    },
     "width": {
       "xsmall": {
-        "$value": "192px",
+        "$value": {"value": 192, "unit": "px"},
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -590,7 +625,7 @@
         }
       },
       "small": {
-        "$value": "320px",
+        "$value": {"value": 320, "unit": "px"},
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -600,7 +635,7 @@
         }
       },
       "medium": {
-        "$value": "480px",
+        "$value": {"value": 480, "unit": "px"},
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -610,7 +645,7 @@
         }
       },
       "large": {
-        "$value": "640px",
+        "$value": {"value": 640, "unit": "px"},
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -620,7 +655,7 @@
         }
       },
       "xlarge": {
-        "$value": "960px",
+        "$value": {"value": 960, "unit": "px"},
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -632,7 +667,7 @@
     },
     "height": {
       "small": {
-        "$value": "256px",
+        "$value": {"value": 256, "unit": "px"},
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -642,7 +677,7 @@
         }
       },
       "medium": {
-        "$value": "320px",
+        "$value": {"value": 320, "unit": "px"},
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -652,7 +687,7 @@
         }
       },
       "large": {
-        "$value": "432px",
+        "$value": {"value": 432, "unit": "px"},
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -662,7 +697,7 @@
         }
       },
       "xlarge": {
-        "$value": "600px",
+        "$value": {"value": 600, "unit": "px"},
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -727,7 +762,7 @@
       }
     },
     "offset": {
-      "$value": "4px",
+      "$value": {"value": 4, "unit": "px"},
       "$type": "dimension",
       "$extensions": {
         "org.primer.figma": {

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

@@ -5,7 +5,7 @@
       "$type": "custom-viewportRange"
     },
     "narrowLandscape": {
-      "$value": "(max-width: calc({breakpoint.large} - 0.02px) and (max-height: calc({breakpoint.small} - 0.02px)) and (orientation: landscape))",
+      "$value": "((max-width: calc({breakpoint.large} - 0.02px)) and (max-height: calc({breakpoint.small} - 0.02px)) and (orientation: landscape))",
       "$type": "custom-viewportRange"
     },
     "regular": {