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

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

@@ -3,6 +3,7 @@
     default: {
       $value: '{base.color.neutral.13}',
       $type: 'color',
+      $description: 'Default text color for primary content and headings',
       $extensions: {
         'org.primer.figma': {
           collection: 'mode',
@@ -17,14 +18,19 @@
           'dark-high-contrast': '{base.color.neutral.13}',
           'dark-tritanopia-high-contrast': '{base.color.neutral.13}',
           'dark-protanopia-deuteranopia-high-contrast': '{base.color.neutral.13}',
-          'dark-dimmed': '{base.color.neutral.11}',
+          'dark-dimmed': '{base.color.neutral.12}',
           'dark-dimmed-high-contrast': '{base.color.neutral.12}',
         },
+        'org.primer.llm': {
+          usage: ['default-text', 'heading', 'body-text'],
+          rules: 'RECOMMENDED default for all text. Use for headings, body text, and primary labels.',
+        },
       },
     },
     muted: {
       $value: '{base.color.neutral.9}',
       $type: 'color',
+      $description: 'Muted text for secondary content and less important information',
       $extensions: {
         'org.primer.figma': {
           collection: 'mode',
@@ -43,11 +49,16 @@
           'dark-tritanopia-high-contrast': '{base.color.neutral.10}',
           'dark-protanopia-deuteranopia-high-contrast': '{base.color.neutral.10}',
         },
+        'org.primer.llm': {
+          usage: ['muted-text', 'secondary-text', 'helper-text', 'placeholder'],
+          rules: 'Use for secondary text like timestamps, metadata, and helper text. Do NOT use for primary content.',
+        },
       },
     },
     onEmphasis: {
       $value: '{base.color.neutral.0}',
       $type: 'color',
+      $description: 'Text color for use on emphasis backgrounds',
       $extensions: {
         'org.primer.figma': {
           collection: 'mode',
@@ -62,22 +73,32 @@
           'dark-dimmed': '{base.color.neutral.12}',
           'dark-dimmed-high-contrast': '#ffffff',
         },
+        'org.primer.llm': {
+          usage: ['text-on-emphasis', 'contrast-text'],
+          rules: 'MUST use for text on any emphasis background (bgColor.*.emphasis). Ensures accessibility contrast.',
+        },
       },
     },
     onInverse: {
       $value: '{base.color.neutral.0}',
       $type: 'color',
+      $description: 'Text color for use on inverse backgrounds',
       $extensions: {
         'org.primer.figma': {
           collection: 'mode',
           group: 'semantic',
           scopes: ['fgColor'],
         },
+        'org.primer.llm': {
+          usage: ['text-on-inverse', 'inverse-text'],
+          rules: 'Use for text on bgColor.inverse. Provides appropriate contrast in both themes.',
+        },
       },
     },
     white: {
       $value: '{base.color.neutral.0}',
       $type: 'color',
+      $description: 'Pure white text',
       $extensions: {
         'org.primer.figma': {
           collection: 'mode',
@@ -87,11 +108,16 @@
         '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: {
       $value: '{base.color.neutral.13}',
       $type: 'color',
+      $description: 'Pure black text',
       $extensions: {
         'org.primer.figma': {
           collection: 'mode',
@@ -101,11 +127,16 @@
         '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: {
       $value: '{base.color.neutral.8}',
       $type: 'color',
+      $description: 'Text color for disabled interactive elements',
       $extensions: {
         'org.primer.figma': {
           collection: 'mode',
@@ -125,11 +156,16 @@
           'dark-tritanopia-high-contrast': '{base.color.neutral.8}',
           'dark-protanopia-deuteranopia-high-contrast': '{base.color.neutral.8}',
         },
+        'org.primer.llm': {
+          usage: ['disabled-text', 'inactive-text', 'unavailable'],
+          rules: 'MUST use for disabled state text. Pair with bgColor.disabled. Do NOT use for active elements.',
+        },
       },
     },
     link: {
       $value: '{fgColor.accent}',
       $type: 'color',
+      $description: 'Text color for hyperlinks',
       $extensions: {
         'org.primer.figma': {
           collection: 'mode',
@@ -139,11 +175,16 @@
             web: 'var(--fgColor-link) /* utility class: .color-fg-accent */',
           },
         },
+        'org.primer.llm': {
+          usage: ['link-text', 'hyperlink'],
+          rules: 'MUST use for all text links. Provides expected link affordance.',
+        },
       },
     },
     neutral: {
       $value: '{base.color.neutral.9}',
       $type: 'color',
+      $description: 'Neutral semantic text for icons and secondary elements',
       $extensions: {
         'org.primer.figma': {
           collection: 'mode',
@@ -159,11 +200,16 @@
           'dark-tritanopia-high-contrast': '{base.color.neutral.11}',
           'dark-protanopia-deuteranopia-high-contrast': '{base.color.neutral.11}',
         },
+        'org.primer.llm': {
+          usage: ['neutral-icon', 'neutral-text'],
+          rules: 'Use for neutral semantic elements. Prefer fgColor.muted for secondary text.',
+        },
       },
     },
     accent: {
       $value: '{base.color.blue.5}',
       $type: 'color',
+      $description: 'Accent text for links and interactive elements',
       $extensions: {
         'org.primer.figma': {
           collection: 'mode',
@@ -184,11 +230,16 @@
           'light-tritanopia-high-contrast': '{base.color.blue.6}',
           'light-protanopia-deuteranopia-high-contrast': '{base.color.blue.6}',
         },
+        'org.primer.llm': {
+          usage: ['accent-text', 'info-text', 'accent-icon'],
+          rules: 'Use for accent-colored text and icons. Pair with bgColor.accent.muted for backgrounds.',
+        },
       },
     },
     success: {
       $value: '{base.color.green.5}',
       $type: 'color',
+      $description: 'Success text for positive feedback and completed states',
       $extensions: {
         'org.primer.figma': {
           collection: 'mode',
@@ -212,11 +263,16 @@
           'light-tritanopia': '{base.color.blue.5}',
           'light-tritanopia-high-contrast': '{base.color.blue.6}',
         },
+        'org.primer.llm': {
+          usage: ['success-text', 'positive-text', 'success-icon'],
+          rules: 'Use for success states and positive feedback text. Pair with bgColor.success.muted for backgrounds.',
+        },
       },
     },
     open: {
       $value: '{fgColor.success}',
       $type: 'color',
+      $description: 'Text color for open state indicators (issues, PRs)',
       $extensions: {
         'org.primer.figma': {
           collection: 'mode',
@@ -236,11 +292,16 @@
           'light-tritanopia': '{base.color.red.5}',
           'light-tritanopia-high-contrast': '{base.color.red.6}',
         },
+        'org.primer.llm': {
+          usage: ['open-text', 'open-issue', 'open-pr'],
+          rules: 'Use for open/active status text. Specifically for GitHub issues and PRs.',
+        },
       },
     },
     attention: {
       $value: '{base.color.yellow.5}',
       $type: 'color',
+      $description: 'Attention text for warnings and caution states',
       $extensions: {
         'org.primer.figma': {
           collection: 'mode',
@@ -257,11 +318,16 @@
           'light-tritanopia-high-contrast': '{base.color.yellow.6}',
           'dark-dimmed-high-contrast': '{base.color.yellow.1}',
         },
+        'org.primer.llm': {
+          usage: ['attention-text', 'warning-text', 'caution-text'],
+          rules: 'Use for warning and caution text. Pair with bgColor.attention.muted for backgrounds.',
+        },
       },
     },
     severe: {
       $value: '{base.color.orange.5}',
       $type: 'color',
+      $description: 'Severe text for high-priority warnings',
       $extensions: {
         'org.primer.figma': {
           collection: 'mode',
@@ -283,11 +349,16 @@
           'light-tritanopia-high-contrast': '{base.color.red.6}',
           'light-protanopia-deuteranopia-high-contrast': '{base.color.orange.6}',
         },
+        'org.primer.llm': {
+          usage: ['severe-text', 'urgent-text', 'severe-icon'],
+          rules: 'Use for severe warnings, less critical than danger. Pair with bgColor.severe.muted for backgrounds.',
+        },
       },
     },
     danger: {
       $value: '#d1242f',
       $type: 'color',
+      $description: 'Danger text for errors and destructive actions',
       $extensions: {
         'org.primer.figma': {
           collection: 'mode',
@@ -309,11 +380,16 @@
           'light-high-contrast': '{base.color.red.6}',
           'light-tritanopia-high-contrast': '{base.color.red.6}',
         },
+        'org.primer.llm': {
+          usage: ['danger-text', 'error-text', 'destructive-text'],
+          rules: 'Use for error messages and destructive action text. Pair with bgColor.danger.muted for backgrounds.',
+        },
       },
     },
     closed: {
       $value: '{fgColor.danger}',
       $type: 'color',
+      $description: 'Text color for closed state indicators (issues, PRs)',
       $extensions: {
         'org.primer.figma': {
           collection: 'mode',
@@ -333,11 +409,16 @@
           'light-tritanopia': '{fgColor.muted}',
           'light-tritanopia-high-contrast': '{fgColor.muted}',
         },
+        'org.primer.llm': {
+          usage: ['closed-text', 'closed-issue', 'closed-pr'],
+          rules: 'Use for closed/declined status text. Specifically for GitHub issues and PRs.',
+        },
       },
     },
     draft: {
       $value: '{fgColor.neutral}',
       $type: 'color',
+      $description: 'Text color for draft state indicators',
       $extensions: {
         'org.primer.figma': {
           collection: 'mode',
@@ -347,11 +428,16 @@
             web: 'var(--fgColor-draft)',
           },
         },
+        'org.primer.llm': {
+          usage: ['draft-text', 'draft-pr', 'draft-issue'],
+          rules: 'Use for draft/WIP status text. Conveys incomplete or pending state.',
+        },
       },
     },
     done: {
       $value: '{base.color.purple.5}',
       $type: 'color',
+      $description: 'Text color for completed/done state indicators',
       $extensions: {
         'org.primer.figma': {
           collection: 'mode',
@@ -371,11 +457,16 @@
           'light-protanopia-deuteranopia-high-contrast': '{base.color.purple.6}',
           'light-tritanopia-high-contrast': '{base.color.purple.6}',
         },
+        'org.primer.llm': {
+          usage: ['done-text', 'merged', 'completed'],
+          rules: 'Use for completed/done status text. Conveys finished or merged state.',
+        },
       },
     },
     upsell: {
       $value: '{fgColor.done}',
       $type: 'color',
+      $description: 'Text color for upsell and promotional content',
       $extensions: {
         'org.primer.figma': {
           collection: 'mode',
@@ -385,11 +476,16 @@
             web: 'var(--fgColor-upsell)',
           },
         },
+        'org.primer.llm': {
+          usage: ['upsell-text', 'premium-text', 'promotional'],
+          rules: 'Use for upgrade prompts and premium feature text. Do NOT use for regular content.',
+        },
       },
     },
     sponsors: {
       $value: '{base.color.pink.5}',
       $type: 'color',
+      $description: 'Text color for GitHub Sponsors content',
       $extensions: {
         'org.primer.figma': {
           collection: 'mode',
@@ -409,6 +505,10 @@
           'light-protanopia-deuteranopia-high-contrast': '{base.color.pink.6}',
           'light-tritanopia-high-contrast': '{base.color.pink.6}',
         },
+        'org.primer.llm': {
+          usage: ['sponsors-text', 'funding-text', 'sponsors-icon'],
+          rules: 'Use for GitHub Sponsors related text. Do NOT use for general pink-colored text.',
+        },
       },
     },
   },

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

@@ -3,12 +3,17 @@
     outlineColor: {
       $value: '{borderColor.accent.emphasis}',
       $type: 'color',
+      $description: 'Outline color for focus states on interactive elements',
       $extensions: {
         'org.primer.figma': {
           collection: 'mode',
           group: 'component (internal)',
           scopes: ['borderColor', 'effectColor'],
         },
+        'org.primer.llm': {
+          usage: ['focus-ring', 'keyboard-navigation', 'accessibility-indicator'],
+          rules: 'Use for focus outlines on interactive elements like buttons, links, and form controls. MUST be visible for keyboard navigation accessibility. Do NOT use for decorative borders or non-interactive elements.',
+        },
       },
     },
   },

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

@@ -3,6 +3,7 @@
     bgColor: {
       $value: '{bgColor.accent.emphasis}',
       $type: 'color',
+      $description: 'Background color for text selection highlights',
       $extensions: {
         'org.primer.figma': {
           collection: 'mode',
@@ -15,6 +16,10 @@
             alpha: 0.7,
           },
         },
+        'org.primer.llm': {
+          usage: ['text-selection', 'highlighted-text', 'selected-content'],
+          rules: 'Use for native text selection (::selection) and programmatic text highlighting. Do NOT use for general emphasis or background colors on containers.',
+        },
       },
       alpha: 0.2,
     },

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',
@@ -248,6 +255,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}',

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.',
+          },
         },
       },
     },
@@ -195,6 +215,7 @@
           },
         ],
         $type: 'shadow',
+        $description: 'Small floating shadow for dropdowns, tooltips, and small overlays',
         $extensions: {
           'org.primer.figma': {
             collection: 'mode',
@@ -230,6 +251,10 @@
               ],
             },
           },
+          'org.primer.llm': {
+            usage: ['dropdown', 'tooltip', 'popover', 'menu'],
+            rules: 'Use for small floating elements like dropdowns and tooltips. Do NOT use for modals or dialogs.',
+          },
         },
       },
       medium: {
@@ -276,6 +301,7 @@
           },
         ],
         $type: 'shadow',
+        $description: 'Medium floating shadow for popovers and action menus',
         $extensions: {
           'org.primer.figma': {
             collection: 'mode',
@@ -327,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: {
@@ -349,6 +379,7 @@
           },
         ],
         $type: 'shadow',
+        $description: 'Large floating shadow for modals and dialogs',
         $extensions: {
           'org.primer.figma': {
             collection: 'mode',
@@ -376,6 +407,10 @@
               ],
             },
           },
+          'org.primer.llm': {
+            usage: ['modal', 'dialog', 'full-screen-overlay'],
+            rules: 'MUST use for modals and dialogs. Do NOT use for small floating elements.',
+          },
         },
       },
       xlarge: {
@@ -398,6 +433,7 @@
           },
         ],
         $type: 'shadow',
+        $description: 'Extra large floating shadow for full-screen overlays and sheets',
         $extensions: {
           'org.primer.figma': {
             collection: 'mode',
@@ -425,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: {
@@ -447,6 +487,7 @@
           },
         ],
         $type: 'shadow',
+        $description: 'Legacy floating shadow for backward compatibility',
         $extensions: {
           'org.primer.figma': {},
           'org.primer.overrides': {
@@ -471,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.',
+          },
         },
       },
     },