@primer/primitives 11.4.1-rc.eb8ee149 → 11.5.0-rc.14eaeb12

package/src/tokens/component/reactionButton.json5

@@ -20,7 +20,11 @@
           },
         },
         hover: {
-          $value: '#caecff',
+          $value: {
+            colorSpace: 'hsl',
+            components: [201.5, 100, 89.6],
+            hex: '#caecff',
+          },
           $type: 'color',
           $extensions: {
             'org.primer.figma': {
@@ -30,16 +34,28 @@
             },
             'org.primer.overrides': {
               dark: {
-                $value: '#3a8cfd',
+                $value: {
+                  colorSpace: 'hsl',
+                  components: [214.8, 98, 61],
+                  hex: '#3a8cfd',
+                },
                 alpha: 0.36,
               },
               'dark-dimmed': {
-                $value: '#4285e5',
+                $value: {
+                  colorSpace: 'hsl',
+                  components: [215.3, 75.8, 57.8],
+                  hex: '#4285e5',
+                },
                 alpha: 0.36,
               },
               'light-high-contrast': '#c7e9ff',
               'dark-high-contrast': {
-                $value: '#5dadff',
+                $value: {
+                  colorSpace: 'hsl',
+                  components: [210.4, 100, 68.2],
+                  hex: '#5dadff',
+                },
                 alpha: 0.36,
               },
             },

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

@@ -4,7 +4,10 @@
       $value: {
         color: '{focus.outlineColor}',
         style: 'solid',
-        width: '2px',
+        width: {
+          value: 2,
+          unit: 'px',
+        },
       },
       $type: 'border',
       $description: 'Focus ring outline for keyboard navigation and accessibility.',
@@ -21,7 +24,7 @@
     $extensions: {
       'org.primer.llm': {
         usage: ['container-border', 'card-border', 'divider', 'input-border', 'panel-border'],
-        rules: 'Use default for standard container borders. Use muted for subtle dividers and low-emphasis boundaries. Use emphasis when borders need to stand out. Match status border colors to their semantic meaning (danger for errors, success for positive states). Use disabled only for non-interactive or disabled elements. Prefer semantic variants (open/closed, done) over raw color variants when the context matches.',
+        rules: 'These are COMPOSITE border shorthand tokens that resolve to CSS shorthand values like "1px solid #color". Use for the CSS `border` property. Do NOT use for `border-color` — use borderColor.* tokens instead. Every border.* token includes width, style, AND color. Use default for standard container borders. Use muted for subtle dividers and low-emphasis boundaries. Use emphasis when borders need to stand out. Match status border colors to their semantic meaning (danger for errors, success for positive states). Use disabled only for non-interactive or disabled elements. Prefer semantic variants (open/closed, done) over raw color variants when the context matches.',
       },
     },
     default: {
@@ -64,6 +67,15 @@
       },
       $type: 'border',
     },
+    translucent: {
+      $description: 'Semi-transparent border shorthand for overlays and layered elements. Border-specific token — no bgColor-translucent counterpart exists by design.',
+      $value: {
+        color: '{borderColor.translucent}',
+        style: 'solid',
+        width: '{borderWidth.default}',
+      },
+      $type: 'border',
+    },
     neutral: {
       $description: 'Neutral gray borders for non-semantic boundaries and subtle UI separation.',
       emphasis: {
@@ -162,6 +174,25 @@
         $type: 'border',
       },
     },
+    draft: {
+      $description: 'Borders for draft/WIP state indicators. Use for draft pull requests and unpublished items.',
+      emphasis: {
+        $value: {
+          color: '{borderColor.draft.emphasis}',
+          style: 'solid',
+          width: '{borderWidth.default}',
+        },
+        $type: 'border',
+      },
+      muted: {
+        $value: {
+          color: '{borderColor.draft.muted}',
+          style: 'solid',
+          width: '{borderWidth.default}',
+        },
+        $type: 'border',
+      },
+    },
     attention: {
       $description: 'Yellow borders for warnings, caution states, and items requiring user attention.',
       emphasis: {

package/src/tokens/functional/color/bgColor.json5

@@ -138,6 +138,10 @@
         'org.primer.overrides': {
           dark: '{base.color.neutral.13}',
         },
+        'org.primer.llm': {
+          doNotUse: true,
+          rules: 'Avoid using raw white. Use semantic alternatives: bgColor.default for standard backgrounds, bgColor.inset for recessed areas, or bgColor.inverse for inverted contexts. Raw black/white ignore theme preferences and accessibility settings.',
+        },
       },
     },
     black: {
@@ -153,6 +157,10 @@
         'org.primer.overrides': {
           dark: '{base.color.neutral.0}',
         },
+        'org.primer.llm': {
+          doNotUse: true,
+          rules: 'Avoid using raw black. Use semantic alternatives: bgColor.emphasis for dark backgrounds, bgColor.inverse for inverted contexts. Raw black/white ignore theme preferences and accessibility settings.',
+        },
       },
     },
     disabled: {
@@ -362,7 +370,11 @@
         },
       },
       emphasis: {
-        $value: '#1f883d',
+        $value: {
+          colorSpace: 'hsl',
+          components: [137.1, 62.9, 32.7],
+          hex: '#1f883d',
+        },
         $type: 'color',
         $description: 'Strong success background for prominent positive actions',
         $extensions: {
@@ -879,7 +891,11 @@
               alpha: 0.1,
             },
             'dark-tritanopia': {
-              $value: '#db61a2',
+              $value: {
+                colorSpace: 'hsl',
+                components: [328, 62.9, 62],
+                hex: '#db61a2',
+              },
               alpha: 0.1,
             },
           },

package/src/tokens/functional/color/borderColor.json5

@@ -1,5 +1,12 @@
 {
   borderColor: {
+    $description: 'Border color tokens that resolve to a single color value (e.g. #cf222e). For composite border shorthand (color + style + width), use border.* tokens instead.',
+    $extensions: {
+      'org.primer.llm': {
+        usage: ['border-color', 'border-styling'],
+        rules: 'These are COLOR-ONLY tokens (resolve to a hex value like #cf222e). Use for the CSS `border-color` property. Do NOT use for the CSS `border` shorthand — use border.* tokens instead.',
+      },
+    },
     default: {
       $value: '{base.color.neutral.6}',
       $type: 'color',
@@ -163,7 +170,7 @@
     translucent: {
       $value: '{base.color.neutral.13}',
       $type: 'color',
-      $description: 'Semi-transparent border for overlays and layered elements',
+      $description: 'Semi-transparent border for overlays and layered elements. Border-specific token — no bgColor-translucent counterpart exists by design.',
       $extensions: {
         'org.primer.figma': {
           collection: 'mode',

package/src/tokens/functional/color/control.json5

@@ -229,7 +229,11 @@
           'org.primer.overrides': {
             dark: '{borderColor.default}',
             'dark-dimmed': {
-              $value: '#3d444d',
+              $value: {
+                colorSpace: 'hsl',
+                components: [213.8, 11.6, 27.1],
+                hex: '#3d444d',
+              },
             },
           },
         },
@@ -732,25 +736,45 @@
                 alpha: 0.4,
               },
               'dark-high-contrast': {
-                $value: '#c51120',
+                $value: {
+                  colorSpace: 'hsl',
+                  components: [355, 84.1, 42],
+                  hex: '#c51120',
+                },
                 alpha: 1,
               },
               'dark-dimmed-high-contrast': {
-                $value: '#c51120',
+                $value: {
+                  colorSpace: 'hsl',
+                  components: [355, 84.1, 42],
+                  hex: '#c51120',
+                },
                 alpha: 1,
               },
               'dark-tritanopia-high-contrast': {
-                $value: '#c51120',
+                $value: {
+                  colorSpace: 'hsl',
+                  components: [355, 84.1, 42],
+                  hex: '#c51120',
+                },
                 alpha: 1,
               },
               'dark-protanopia-deuteranopia-high-contrast': {
                 $value: '{bgColor.danger.emphasis}',
               },
               'light-high-contrast': {
-                $value: '#8c0b1d',
+                $value: {
+                  colorSpace: 'hsl',
+                  components: [351.6, 85.4, 29.6],
+                  hex: '#8c0b1d',
+                },
               },
               'light-tritanopia-high-contrast': {
-                $value: '#8c0b1d',
+                $value: {
+                  colorSpace: 'hsl',
+                  components: [351.6, 85.4, 29.6],
+                  hex: '#8c0b1d',
+                },
               },
               'light-protanopia-deuteranopia-high-contrast': {
                 $value: '{base.color.orange.6}',
@@ -778,7 +802,11 @@
           },
         },
         hover: {
-          $value: '#0860ca',
+          $value: {
+            colorSpace: 'hsl',
+            components: [212.8, 92.4, 41.2],
+            hex: '#0860ca',
+          },
           $type: 'color',
           $extensions: {
             'org.primer.figma': {
@@ -789,34 +817,70 @@
             'org.primer.overrides': {
               dark: '#2A7AEF',
               'dark-high-contrast': {
-                $value: '#2b64c1',
+                $value: {
+                  colorSpace: 'hsl',
+                  components: [217.2, 63.6, 46.3],
+                  hex: '#2b64c1',
+                },
               },
               'dark-tritanopia-high-contrast': {
-                $value: '#2b64c1',
+                $value: {
+                  colorSpace: 'hsl',
+                  components: [217.2, 63.6, 46.3],
+                  hex: '#2b64c1',
+                },
               },
               'dark-protanopia-deuteranopia-high-contrast': {
-                $value: '#2b64c1',
+                $value: {
+                  colorSpace: 'hsl',
+                  components: [217.2, 63.6, 46.3],
+                  hex: '#2b64c1',
+                },
               },
               'dark-dimmed': {
-                $value: '#3876d3',
+                $value: {
+                  colorSpace: 'hsl',
+                  components: [216, 63.8, 52.4],
+                  hex: '#3876d3',
+                },
               },
               'dark-dimmed-high-contrast': {
-                $value: '#2b64c1',
+                $value: {
+                  colorSpace: 'hsl',
+                  components: [217.2, 63.6, 46.3],
+                  hex: '#2b64c1',
+                },
               },
               'light-high-contrast': {
-                $value: '#0344a8',
+                $value: {
+                  colorSpace: 'hsl',
+                  components: [216.4, 96.5, 33.5],
+                  hex: '#0344a8',
+                },
               },
               'light-tritanopia-high-contrast': {
-                $value: '#0344a8',
+                $value: {
+                  colorSpace: 'hsl',
+                  components: [216.4, 96.5, 33.5],
+                  hex: '#0344a8',
+                },
               },
               'light-protanopia-deuteranopia-high-contrast': {
-                $value: '#0344a8',
+                $value: {
+                  colorSpace: 'hsl',
+                  components: [216.4, 96.5, 33.5],
+                  hex: '#0344a8',
+                },
               },
             },
           },
         },
         active: {
-          $value: '#0757ba',
+          $value: {
+            colorSpace: 'hsl',
+            components: [213.2, 92.7, 37.8],
+            hex: '#0757ba',
+          },
           $type: 'color',
           $extensions: {
             'org.primer.figma': {
@@ -827,28 +891,60 @@
             'org.primer.overrides': {
               dark: '#3685F3',
               'dark-high-contrast': {
-                $value: '#3c79d0',
+                $value: {
+                  colorSpace: 'hsl',
+                  components: [215.3, 61.2, 52.5],
+                  hex: '#3c79d0',
+                },
               },
               'dark-protanopia-deuteranopia-high-contrast': {
-                $value: '#3c79d0',
+                $value: {
+                  colorSpace: 'hsl',
+                  components: [215.3, 61.2, 52.5],
+                  hex: '#3c79d0',
+                },
               },
               'dark-tritanopia-high-contrast': {
-                $value: '#3c79d0',
+                $value: {
+                  colorSpace: 'hsl',
+                  components: [215.3, 61.2, 52.5],
+                  hex: '#3c79d0',
+                },
               },
               'dark-dimmed': {
-                $value: '#3f7fdb',
+                $value: {
+                  colorSpace: 'hsl',
+                  components: [215.4, 68.4, 55.3],
+                  hex: '#3f7fdb',
+                },
               },
               'dark-dimmed-high-contrast': {
-                $value: '#3c79d0',
+                $value: {
+                  colorSpace: 'hsl',
+                  components: [215.3, 61.2, 52.5],
+                  hex: '#3c79d0',
+                },
               },
               'light-high-contrast': {
-                $value: '#033f9d',
+                $value: {
+                  colorSpace: 'hsl',
+                  components: [216.6, 96.3, 31.4],
+                  hex: '#033f9d',
+                },
               },
               'light-tritanopia-high-contrast': {
-                $value: '#033f9d',
+                $value: {
+                  colorSpace: 'hsl',
+                  components: [216.6, 96.3, 31.4],
+                  hex: '#033f9d',
+                },
               },
               'light-protanopia-deuteranopia-high-contrast': {
-                $value: '#033f9d',
+                $value: {
+                  colorSpace: 'hsl',
+                  components: [216.6, 96.3, 31.4],
+                  hex: '#033f9d',
+                },
               },
             },
           },
@@ -946,19 +1042,35 @@
                 $value: '{base.color.blue.2}',
               },
               'dark-dimmed': {
-                $value: '#3876d3',
+                $value: {
+                  colorSpace: 'hsl',
+                  components: [216, 63.8, 52.4],
+                  hex: '#3876d3',
+                },
               },
               'dark-dimmed-high-contrast': {
                 $value: '{base.color.blue.2}',
               },
               'light-high-contrast': {
-                $value: '#0344a8',
+                $value: {
+                  colorSpace: 'hsl',
+                  components: [216.4, 96.5, 33.5],
+                  hex: '#0344a8',
+                },
               },
               'light-tritanopia-high-contrast': {
-                $value: '#0344a8',
+                $value: {
+                  colorSpace: 'hsl',
+                  components: [216.4, 96.5, 33.5],
+                  hex: '#0344a8',
+                },
               },
               'light-protanopia-deuteranopia-high-contrast': {
-                $value: '#0344a8',
+                $value: {
+                  colorSpace: 'hsl',
+                  components: [216.4, 96.5, 33.5],
+                  hex: '#0344a8',
+                },
               },
             },
           },
@@ -984,19 +1096,35 @@
                 $value: '{base.color.blue.2}',
               },
               'dark-dimmed': {
-                $value: '#3f7fdb',
+                $value: {
+                  colorSpace: 'hsl',
+                  components: [215.4, 68.4, 55.3],
+                  hex: '#3f7fdb',
+                },
               },
               'dark-dimmed-high-contrast': {
                 $value: '{base.color.blue.2}',
               },
               'light-high-contrast': {
-                $value: '#033f9d',
+                $value: {
+                  colorSpace: 'hsl',
+                  components: [216.6, 96.3, 31.4],
+                  hex: '#033f9d',
+                },
               },
               'light-protanopia-deuteranopia-high-contrast': {
-                $value: '#033f9d',
+                $value: {
+                  colorSpace: 'hsl',
+                  components: [216.6, 96.3, 31.4],
+                  hex: '#033f9d',
+                },
               },
               'light-tritanopia-high-contrast': {
-                $value: '#033f9d',
+                $value: {
+                  colorSpace: 'hsl',
+                  components: [216.6, 96.3, 31.4],
+                  hex: '#033f9d',
+                },
               },
             },
           },

package/src/tokens/functional/color/display.json5

@@ -1,5 +1,12 @@
 {
   display: {
+    $description: 'Decorative colors for categorization and visual distinction without semantic meaning. Use for labels, tags, avatars, status indicators, and user-assigned colors. Do NOT use for success/error/warning states—use semantic colors (bgColor.success/danger/attention) instead.',
+    $extensions: {
+      'org.primer.llm': {
+        usage: ['label', 'tag', 'avatar', 'badge', 'category-indicator', 'user-assigned-color', 'project-color', 'decorative-element'],
+        rules: 'Use display colors for arbitrary categorization where the color has no inherent meaning (e.g., project labels, user avatars). For meaningful states like success, error, or warning, use semantic colors instead. Scales 0-2 are lighter (backgrounds), 3-5 are mid-tones, 6-9 are darker (foregrounds/borders).',
+      },
+    },
     blue: {
       scale: {
         '0': {

package/src/tokens/functional/color/fgColor.json5

@@ -108,6 +108,10 @@
         'org.primer.overrides': {
           dark: '{base.color.neutral.13}',
         },
+        'org.primer.llm': {
+          doNotUse: true,
+          rules: 'Avoid using raw white. Use semantic alternatives: fgColor.onEmphasis for text on dark backgrounds, fgColor.onInverse for inverted contexts. Raw black/white ignore theme preferences and accessibility settings.',
+        },
       },
     },
     black: {
@@ -123,6 +127,10 @@
         'org.primer.overrides': {
           dark: '{base.color.neutral.0}',
         },
+        'org.primer.llm': {
+          doNotUse: true,
+          rules: 'Avoid using raw black. Use semantic alternatives: fgColor.default for standard text, fgColor.muted for secondary text. Raw black/white ignore theme preferences and accessibility settings.',
+        },
       },
     },
     disabled: {
@@ -348,7 +356,11 @@
       },
     },
     danger: {
-      $value: '#d1242f',
+      $value: {
+        colorSpace: 'hsl',
+        components: [356.2, 70.6, 48],
+        hex: '#d1242f',
+      },
       $type: 'color',
       $description: 'Danger text for errors and destructive actions',
       $extensions: {

package/src/tokens/functional/color/syntax.json5

@@ -1,6 +1,13 @@
 {
   color: {
     ansi: {
+      $description: 'ANSI terminal color palette for command-line interfaces and terminal emulators. Maps standard ANSI color names to theme-appropriate values.',
+      $extensions: {
+        'org.primer.llm': {
+          usage: ['terminal-output', 'cli-interface', 'console-text', 'shell-prompt'],
+          rules: 'Use exclusively for terminal/CLI contexts. Do NOT use for general UI—use semantic colors (fgColor, bgColor) instead. These colors follow ANSI naming conventions (black, red, green, yellow, blue, magenta, cyan, white) with bright variants.',
+        },
+      },
       black: {
         $value: '{base.color.neutral.13}',
         $type: 'color',
@@ -221,7 +228,11 @@
         },
       },
       cyan: {
-        $value: '#1b7c83',
+        $value: {
+          colorSpace: 'hsl',
+          components: [184, 65.8, 31],
+          hex: '#1b7c83',
+        },
         $type: 'color',
         $extensions: {
           'org.primer.figma': {
@@ -234,7 +245,11 @@
         },
       },
       'cyan-bright': {
-        $value: '#3192aa',
+        $value: {
+          colorSpace: 'hsl',
+          components: [191.9, 55.3, 42.9],
+          hex: '#3192aa',
+        },
         $type: 'color',
         $extensions: {
           'org.primer.figma': {
@@ -248,6 +263,13 @@
       },
     },
     prettylights: {
+      $description: 'Syntax highlighting colors for code display. Used by GitHub code rendering (prettylights theme).',
+      $extensions: {
+        'org.primer.llm': {
+          usage: ['code-syntax-highlighting', 'code-block', 'inline-code', 'diff-view'],
+          rules: 'Use exclusively for syntax highlighting in code display contexts. Do NOT use for general UI text or backgrounds. Each token maps to a specific syntax element (comment, keyword, string, etc.).',
+        },
+      },
       syntax: {
         comment: {
           $value: '{base.color.neutral.9}',