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

package/dist/docs/functional/themes/dark-dimmed.json

@@ -310,6 +310,10 @@
         "dark-dimmed-high-contrast": "#1b4b91",
         "dark-tritanopia-high-contrast": "#0f2d5c",
         "dark-protanopia-deuteranopia-high-contrast": "#0f2d5c"
+      },
+      "org.primer.llm": {
+        "usage": ["active-states", "current", "selected", "active-toggle"],
+        "rules": "MUST use for selected or active states. Pair with fgColor.onEmphasis for text."
       }
     },
     "filePath": "src/tokens/functional/color/bgColor.json5",
@@ -317,6 +321,7 @@
     "original": {
       "$value": "{base.color.blue.5}",
       "$type": "color",
+      "$description": "Strong accent background for active states and focused states",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -332,6 +337,10 @@
           "dark-dimmed-high-contrast": "{base.color.blue.7}",
           "dark-tritanopia-high-contrast": "{base.color.blue.9}",
           "dark-protanopia-deuteranopia-high-contrast": "{base.color.blue.9}"
+        },
+        "org.primer.llm": {
+          "usage": ["active-states", "current", "selected", "active-toggle"],
+          "rules": "MUST use for selected or active states. Pair with fgColor.onEmphasis for text."
         }
       },
       "key": "{bgColor.accent.emphasis}"
@@ -340,7 +349,8 @@
     "attributes": {},
     "path": ["bgColor", "accent", "emphasis"],
     "value": "#316dca",
-    "type": "color"
+    "type": "color",
+    "description": "Strong accent background for active states and focused states"
   },
   "bgColor-accent-muted": {
     "key": "{bgColor.accent.muted}",
@@ -361,6 +371,10 @@
           "isSource": true,
           "$type": "color"
         }
+      },
+      "org.primer.llm": {
+        "usage": ["selected-row", "info-banner", "active-nav-item", "highlight"],
+        "rules": "Use for selected states or informational highlights. Pair with fgColor.accent for text."
       }
     },
     "filePath": "src/tokens/functional/color/bgColor.json5",
@@ -369,6 +383,7 @@
     "original": {
       "$value": "{base.color.blue.4}",
       "$type": "color",
+      "$description": "Subtle accent background for informational or selected elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -386,6 +401,10 @@
             "isSource": true,
             "$type": "color"
           }
+        },
+        "org.primer.llm": {
+          "usage": ["selected-row", "info-banner", "active-nav-item", "highlight"],
+          "rules": "Use for selected states or informational highlights. Pair with fgColor.accent for text."
         }
       },
       "alpha": 0.1,
@@ -395,7 +414,8 @@
     "attributes": {},
     "path": ["bgColor", "accent", "muted"],
     "value": "#4184e41a",
-    "type": "color"
+    "type": "color",
+    "description": "Subtle accent background for informational or selected elements"
   },
   "bgColor-attention-emphasis": {
     "key": "{bgColor.attention.emphasis}",
@@ -413,6 +433,10 @@
         "dark-dimmed-high-contrast": "#6c4400",
         "dark-protanopia-deuteranopia-high-contrast": "#452700",
         "dark-tritanopia-high-contrast": "#452700"
+      },
+      "org.primer.llm": {
+        "usage": ["warning-badge", "caution-label", "attention-indicator"],
+        "rules": "Use for prominent warnings. Consider fgColor.default for text due to yellow contrast."
       }
     },
     "filePath": "src/tokens/functional/color/bgColor.json5",
@@ -420,6 +444,7 @@
     "original": {
       "$value": "{base.color.yellow.5}",
       "$type": "color",
+      "$description": "Strong attention background for prominent warnings",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -434,6 +459,10 @@
           "dark-dimmed-high-contrast": "{base.color.yellow.7}",
           "dark-protanopia-deuteranopia-high-contrast": "{base.color.yellow.9}",
           "dark-tritanopia-high-contrast": "{base.color.yellow.9}"
+        },
+        "org.primer.llm": {
+          "usage": ["warning-badge", "caution-label", "attention-indicator"],
+          "rules": "Use for prominent warnings. Consider fgColor.default for text due to yellow contrast."
         }
       },
       "key": "{bgColor.attention.emphasis}"
@@ -442,7 +471,8 @@
     "attributes": {},
     "path": ["bgColor", "attention", "emphasis"],
     "value": "#966600",
-    "type": "color"
+    "type": "color",
+    "description": "Strong attention background for prominent warnings"
   },
   "bgColor-attention-muted": {
     "key": "{bgColor.attention.muted}",
@@ -463,6 +493,10 @@
           "isSource": true,
           "$type": "color"
         }
+      },
+      "org.primer.llm": {
+        "usage": ["warning-banner", "caution-message", "pending-state"],
+        "rules": "Use for warnings that need user attention. Pair with fgColor.attention for text."
       }
     },
     "filePath": "src/tokens/functional/color/bgColor.json5",
@@ -471,6 +505,7 @@
     "original": {
       "$value": "{base.color.yellow.4}",
       "$type": "color",
+      "$description": "Subtle attention background for warnings and caution states",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -488,6 +523,10 @@
             "isSource": true,
             "$type": "color"
           }
+        },
+        "org.primer.llm": {
+          "usage": ["warning-banner", "caution-message", "pending-state"],
+          "rules": "Use for warnings that need user attention. Pair with fgColor.attention for text."
         }
       },
       "alpha": 0.15,
@@ -497,7 +536,8 @@
     "attributes": {},
     "path": ["bgColor", "attention", "muted"],
     "value": "#ae7c1426",
-    "type": "color"
+    "type": "color",
+    "description": "Subtle attention background for warnings and caution states"
   },
   "bgColor-black": {
     "key": "{bgColor.black}",
@@ -509,6 +549,10 @@
       },
       "org.primer.overrides": {
         "dark": "#010409"
+      },
+      "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."
       }
     },
     "filePath": "src/tokens/functional/color/bgColor.json5",
@@ -516,6 +560,7 @@
     "original": {
       "$value": "{base.color.neutral.0}",
       "$type": "color",
+      "$description": "Pure black background",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -524,6 +569,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."
         }
       },
       "key": "{bgColor.black}"
@@ -532,7 +581,8 @@
     "attributes": {},
     "path": ["bgColor", "black"],
     "value": "#010409",
-    "type": "color"
+    "type": "color",
+    "description": "Pure black background"
   },
   "bgColor-closed-emphasis": {
     "key": "{bgColor.closed.emphasis}",
@@ -554,6 +604,10 @@
         "light-protanopia-deuteranopia-high-contrast": "#656c76",
         "dark-protanopia-deuteranopia": "#656c76",
         "dark-protanopia-deuteranopia-high-contrast": "#656c76"
+      },
+      "org.primer.llm": {
+        "usage": ["closed-badge", "closed-label", "declined-status-badge"],
+        "rules": "Use for prominent closed/declined state indicators. Pair with fgColor.onEmphasis for text."
       }
     },
     "filePath": "src/tokens/functional/color/bgColor.json5",
@@ -561,6 +615,7 @@
     "original": {
       "$value": "{bgColor.danger.emphasis}",
       "$type": "color",
+      "$description": "Strong background for closed state badges and labels",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -579,6 +634,10 @@
           "light-protanopia-deuteranopia-high-contrast": "{bgColor.neutral.emphasis}",
           "dark-protanopia-deuteranopia": "{bgColor.neutral.emphasis}",
           "dark-protanopia-deuteranopia-high-contrast": "{bgColor.neutral.emphasis}"
+        },
+        "org.primer.llm": {
+          "usage": ["closed-badge", "closed-label", "declined-status-badge"],
+          "rules": "Use for prominent closed/declined state indicators. Pair with fgColor.onEmphasis for text."
         }
       },
       "key": "{bgColor.closed.emphasis}"
@@ -587,7 +646,8 @@
     "attributes": {},
     "path": ["bgColor", "closed", "emphasis"],
     "value": "#c93c37",
-    "type": "color"
+    "type": "color",
+    "description": "Strong background for closed state badges and labels"
   },
   "bgColor-closed-muted": {
     "key": "{bgColor.closed.muted}",
@@ -626,6 +686,10 @@
           "isSource": true,
           "$type": "color"
         }
+      },
+      "org.primer.llm": {
+        "usage": ["closed-issue", "closed-pr", "declined-state"],
+        "rules": "Use for closed/declined status indicators. Specifically for GitHub issues and PRs."
       }
     },
     "filePath": "src/tokens/functional/color/bgColor.json5",
@@ -633,6 +697,7 @@
     "original": {
       "$value": "{bgColor.danger.muted}",
       "$type": "color",
+      "$description": "Subtle background for closed state indicators (issues, PRs)",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -668,6 +733,10 @@
             "isSource": true,
             "$type": "color"
           }
+        },
+        "org.primer.llm": {
+          "usage": ["closed-issue", "closed-pr", "declined-state"],
+          "rules": "Use for closed/declined status indicators. Specifically for GitHub issues and PRs."
         }
       },
       "key": "{bgColor.closed.muted}"
@@ -676,7 +745,8 @@
     "attributes": {},
     "path": ["bgColor", "closed", "muted"],
     "value": "#e5534b1a",
-    "type": "color"
+    "type": "color",
+    "description": "Subtle background for closed state indicators (issues, PRs)"
   },
   "bgColor-danger-emphasis": {
     "key": "{bgColor.danger.emphasis}",
@@ -697,6 +767,10 @@
         "dark-high-contrast": "#5d0f12",
         "dark-dimmed-high-contrast": "#922323",
         "dark-tritanopia-high-contrast": "#5d0f12"
+      },
+      "org.primer.llm": {
+        "usage": ["delete-button", "critical-alert", "destructive-confirmation"],
+        "rules": "MUST use for destructive action buttons like delete. Use fgColor.onEmphasis for text on this background."
       }
     },
     "filePath": "src/tokens/functional/color/bgColor.json5",
@@ -704,6 +778,7 @@
     "original": {
       "$value": "{base.color.red.5}",
       "$type": "color",
+      "$description": "Emphasized danger background for critical errors and delete confirmations",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -721,6 +796,10 @@
           "dark-high-contrast": "{base.color.red.9}",
           "dark-dimmed-high-contrast": "{base.color.red.7}",
           "dark-tritanopia-high-contrast": "{base.color.red.9}"
+        },
+        "org.primer.llm": {
+          "usage": ["delete-button", "critical-alert", "destructive-confirmation"],
+          "rules": "MUST use for destructive action buttons like delete. Use fgColor.onEmphasis for text on this background."
         }
       },
       "key": "{bgColor.danger.emphasis}"
@@ -729,7 +808,8 @@
     "attributes": {},
     "path": ["bgColor", "danger", "emphasis"],
     "value": "#c93c37",
-    "type": "color"
+    "type": "color",
+    "description": "Emphasized danger background for critical errors and delete confirmations"
   },
   "bgColor-danger-muted": {
     "key": "{bgColor.danger.muted}",
@@ -759,6 +839,10 @@
           "isSource": true,
           "$type": "color"
         }
+      },
+      "org.primer.llm": {
+        "usage": ["error-message", "destructive-action", "validation-error"],
+        "rules": "Use for error states and destructive action backgrounds. Pair with fgColor.danger for text."
       }
     },
     "filePath": "src/tokens/functional/color/bgColor.json5",
@@ -767,6 +851,7 @@
     "original": {
       "$value": "{base.color.red.4}",
       "$type": "color",
+      "$description": "Muted danger background for error states and destructive action contexts",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -793,6 +878,10 @@
             "isSource": true,
             "$type": "color"
           }
+        },
+        "org.primer.llm": {
+          "usage": ["error-message", "destructive-action", "validation-error"],
+          "rules": "Use for error states and destructive action backgrounds. Pair with fgColor.danger for text."
         }
       },
       "alpha": 0.1,
@@ -802,7 +891,8 @@
     "attributes": {},
     "path": ["bgColor", "danger", "muted"],
     "value": "#e5534b1a",
-    "type": "color"
+    "type": "color",
+    "description": "Muted danger background for error states and destructive action contexts"
   },
   "bgColor-default": {
     "key": "{bgColor.default}",
@@ -822,6 +912,10 @@
         "dark-high-contrast": "#010409",
         "dark-tritanopia-high-contrast": "#010409",
         "dark-protanopia-deuteranopia-high-contrast": "#010409"
+      },
+      "org.primer.llm": {
+        "usage": ["page-background", "main-content", "card-background"],
+        "rules": "Use as the primary background for pages and content areas. Do NOT use for emphasis or highlighting."
       }
     },
     "filePath": "src/tokens/functional/color/bgColor.json5",
@@ -829,6 +923,7 @@
     "original": {
       "$value": "{base.color.neutral.3}",
       "$type": "color",
+      "$description": "Default background color for pages and main content areas",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -845,6 +940,10 @@
           "dark-high-contrast": "{base.color.neutral.0}",
           "dark-tritanopia-high-contrast": "{base.color.neutral.0}",
           "dark-protanopia-deuteranopia-high-contrast": "{base.color.neutral.0}"
+        },
+        "org.primer.llm": {
+          "usage": ["page-background", "main-content", "card-background"],
+          "rules": "Use as the primary background for pages and content areas. Do NOT use for emphasis or highlighting."
         }
       },
       "key": "{bgColor.default}"
@@ -853,7 +952,8 @@
     "attributes": {},
     "path": ["bgColor", "default"],
     "value": "#212830",
-    "type": "color"
+    "type": "color",
+    "description": "Default background color for pages and main content areas"
   },
   "bgColor-disabled": {
     "key": "{bgColor.disabled}",
@@ -873,6 +973,10 @@
         "dark-high-contrast": "#262c36",
         "dark-tritanopia-high-contrast": "#262c36",
         "dark-protanopia-deuteranopia-high-contrast": "#262c36"
+      },
+      "org.primer.llm": {
+        "usage": ["disabled-button", "disabled-input", "inactive-element"],
+        "rules": "MUST use for disabled state backgrounds. Pair with fgColor.disabled for text. Do NOT use for active elements."
       }
     },
     "filePath": "src/tokens/functional/color/bgColor.json5",
@@ -880,6 +984,7 @@
     "original": {
       "$value": "{base.color.neutral.5}",
       "$type": "color",
+      "$description": "Background for disabled interactive elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -896,6 +1001,10 @@
           "dark-high-contrast": "{base.color.neutral.4}",
           "dark-tritanopia-high-contrast": "{base.color.neutral.4}",
           "dark-protanopia-deuteranopia-high-contrast": "{base.color.neutral.4}"
+        },
+        "org.primer.llm": {
+          "usage": ["disabled-button", "disabled-input", "inactive-element"],
+          "rules": "MUST use for disabled state backgrounds. Pair with fgColor.disabled for text. Do NOT use for active elements."
         }
       },
       "key": "{bgColor.disabled}"
@@ -904,7 +1013,8 @@
     "attributes": {},
     "path": ["bgColor", "disabled"],
     "value": "#2a313c",
-    "type": "color"
+    "type": "color",
+    "description": "Background for disabled interactive elements"
   },
   "bgColor-done-emphasis": {
     "key": "{bgColor.done.emphasis}",
@@ -922,6 +1032,10 @@
         "dark-dimmed-high-contrast": "#5936a2",
         "dark-tritanopia-high-contrast": "#352160",
         "dark-protanopia-deuteranopia-high-contrast": "#352160"
+      },
+      "org.primer.llm": {
+        "usage": ["done-badge", "merged-label", "completed-indicator"],
+        "rules": "Use for prominent done/completed state indicators. Pair with fgColor.onEmphasis for text."
       }
     },
     "filePath": "src/tokens/functional/color/bgColor.json5",
@@ -929,6 +1043,7 @@
     "original": {
       "$value": "{base.color.purple.5}",
       "$type": "color",
+      "$description": "Strong background for completed/done state badges and labels",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -943,6 +1058,10 @@
           "dark-dimmed-high-contrast": "{base.color.purple.7}",
           "dark-tritanopia-high-contrast": "{base.color.purple.9}",
           "dark-protanopia-deuteranopia-high-contrast": "{base.color.purple.9}"
+        },
+        "org.primer.llm": {
+          "usage": ["done-badge", "merged-label", "completed-indicator"],
+          "rules": "Use for prominent done/completed state indicators. Pair with fgColor.onEmphasis for text."
         }
       },
       "key": "{bgColor.done.emphasis}"
@@ -951,7 +1070,8 @@
     "attributes": {},
     "path": ["bgColor", "done", "emphasis"],
     "value": "#8256d0",
-    "type": "color"
+    "type": "color",
+    "description": "Strong background for completed/done state badges and labels"
   },
   "bgColor-done-muted": {
     "key": "{bgColor.done.muted}",
@@ -972,6 +1092,10 @@
           "isSource": true,
           "$type": "color"
         }
+      },
+      "org.primer.llm": {
+        "usage": ["completed-task", "merged-pr", "done-state"],
+        "rules": "Use for completed/done status indicators. Conveys finished or merged state."
       }
     },
     "filePath": "src/tokens/functional/color/bgColor.json5",
@@ -980,6 +1104,7 @@
     "original": {
       "$value": "{base.color.purple.4}",
       "$type": "color",
+      "$description": "Subtle background for completed/done state indicators",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -997,6 +1122,10 @@
             "isSource": true,
             "$type": "color"
           }
+        },
+        "org.primer.llm": {
+          "usage": ["completed-task", "merged-pr", "done-state"],
+          "rules": "Use for completed/done status indicators. Conveys finished or merged state."
         }
       },
       "alpha": 0.15,
@@ -1006,7 +1135,8 @@
     "attributes": {},
     "path": ["bgColor", "done", "muted"],
     "value": "#986ee226",
-    "type": "color"
+    "type": "color",
+    "description": "Subtle background for completed/done state indicators"
   },
   "bgColor-draft-emphasis": {
     "key": "{bgColor.draft.emphasis}",
@@ -1018,6 +1148,10 @@
         "codeSyntax": {
           "web": "var(--bgColor-draft-emphasis)"
         }
+      },
+      "org.primer.llm": {
+        "usage": ["draft-badge", "draft-label", "wip-indicator"],
+        "rules": "Use for prominent draft state indicators. Pair with fgColor.onEmphasis for text."
       }
     },
     "filePath": "src/tokens/functional/color/bgColor.json5",
@@ -1025,6 +1159,7 @@
     "original": {
       "$value": "{bgColor.neutral.emphasis}",
       "$type": "color",
+      "$description": "Strong background for draft state badges and labels",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -1033,6 +1168,10 @@
           "codeSyntax": {
             "web": "var(--bgColor-draft-emphasis)"
           }
+        },
+        "org.primer.llm": {
+          "usage": ["draft-badge", "draft-label", "wip-indicator"],
+          "rules": "Use for prominent draft state indicators. Pair with fgColor.onEmphasis for text."
         }
       },
       "key": "{bgColor.draft.emphasis}"
@@ -1041,7 +1180,8 @@
     "attributes": {},
     "path": ["bgColor", "draft", "emphasis"],
     "value": "#656c76",
-    "type": "color"
+    "type": "color",
+    "description": "Strong background for draft state badges and labels"
   },
   "bgColor-draft-muted": {
     "key": "{bgColor.draft.muted}",
@@ -1080,6 +1220,10 @@
           "isSource": true,
           "$type": "color"
         }
+      },
+      "org.primer.llm": {
+        "usage": ["draft-pr", "draft-issue", "work-in-progress"],
+        "rules": "Use for draft/WIP status indicators. Conveys incomplete or pending state."
       }
     },
     "filePath": "src/tokens/functional/color/bgColor.json5",
@@ -1087,6 +1231,7 @@
     "original": {
       "$value": "{bgColor.neutral.muted}",
       "$type": "color",
+      "$description": "Subtle background for draft state indicators",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -1122,6 +1267,10 @@
             "isSource": true,
             "$type": "color"
           }
+        },
+        "org.primer.llm": {
+          "usage": ["draft-pr", "draft-issue", "work-in-progress"],
+          "rules": "Use for draft/WIP status indicators. Conveys incomplete or pending state."
         }
       },
       "key": "{bgColor.draft.muted}"
@@ -1130,7 +1279,8 @@
     "attributes": {},
     "path": ["bgColor", "draft", "muted"],
     "value": "#656c7633",
-    "type": "color"
+    "type": "color",
+    "description": "Subtle background for draft state indicators"
   },
   "bgColor-emphasis": {
     "key": "{bgColor.emphasis}",
@@ -1145,6 +1295,10 @@
       },
       "org.primer.overrides": {
         "dark": "#3d444d"
+      },
+      "org.primer.llm": {
+        "usage": ["tooltip", "badge-background", "high-contrast-element"],
+        "rules": "Use for elements needing strong visual emphasis. Pair with fgColor.onEmphasis for text. Do NOT use for large areas."
       }
     },
     "filePath": "src/tokens/functional/color/bgColor.json5",
@@ -1152,6 +1306,7 @@
     "original": {
       "$value": "{base.color.neutral.7}",
       "$type": "color",
+      "$description": "High-emphasis dark background for strong visual contrast",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -1163,6 +1318,10 @@
         },
         "org.primer.overrides": {
           "dark": "{base.color.neutral.7}"
+        },
+        "org.primer.llm": {
+          "usage": ["tooltip", "badge-background", "high-contrast-element"],
+          "rules": "Use for elements needing strong visual emphasis. Pair with fgColor.onEmphasis for text. Do NOT use for large areas."
         }
       },
       "key": "{bgColor.emphasis}"
@@ -1171,7 +1330,8 @@
     "attributes": {},
     "path": ["bgColor", "emphasis"],
     "value": "#3d444d",
-    "type": "color"
+    "type": "color",
+    "description": "High-emphasis dark background for strong visual contrast"
   },
   "bgColor-inset": {
     "key": "{bgColor.inset}",
@@ -1191,6 +1351,10 @@
         "light-high-contrast": "#151b23",
         "light-tritanopia-high-contrast": "#151b23",
         "light-protanopia-deuteranopia-high-contrast": "#151b23"
+      },
+      "org.primer.llm": {
+        "usage": ["well", "sunken-panel", "recessed-area", "input-background"],
+        "rules": "Use for visually recessed areas. Creates depth hierarchy. Suitable for input fields and wells."
       }
     },
     "filePath": "src/tokens/functional/color/bgColor.json5",
@@ -1198,6 +1362,7 @@
     "original": {
       "$value": "{base.color.neutral.2}",
       "$type": "color",
+      "$description": "Inset background for recessed content areas like wells or sunken panels",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -1214,6 +1379,10 @@
           "light-high-contrast": "{base.color.neutral.2}",
           "light-tritanopia-high-contrast": "{base.color.neutral.2}",
           "light-protanopia-deuteranopia-high-contrast": "{base.color.neutral.2}"
+        },
+        "org.primer.llm": {
+          "usage": ["well", "sunken-panel", "recessed-area", "input-background"],
+          "rules": "Use for visually recessed areas. Creates depth hierarchy. Suitable for input fields and wells."
         }
       },
       "key": "{bgColor.inset}"
@@ -1222,7 +1391,8 @@
     "attributes": {},
     "path": ["bgColor", "inset"],
     "value": "#151b23",
-    "type": "color"
+    "type": "color",
+    "description": "Inset background for recessed content areas like wells or sunken panels"
   },
   "bgColor-inverse": {
     "key": "{bgColor.inverse}",
@@ -1234,6 +1404,10 @@
       },
       "org.primer.overrides": {
         "dark": "#cdd9e5"
+      },
+      "org.primer.llm": {
+        "usage": ["overlay-content", "inverse-theme-element"],
+        "rules": "Use when you need opposite theme background. Pair with fgColor.onInverse for text."
       }
     },
     "filePath": "src/tokens/functional/color/bgColor.json5",
@@ -1241,6 +1415,7 @@
     "original": {
       "$value": "{base.color.neutral.13}",
       "$type": "color",
+      "$description": "Inverse background that flips between light and dark modes",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -1249,6 +1424,10 @@
         },
         "org.primer.overrides": {
           "dark": "{base.color.neutral.13}"
+        },
+        "org.primer.llm": {
+          "usage": ["overlay-content", "inverse-theme-element"],
+          "rules": "Use when you need opposite theme background. Pair with fgColor.onInverse for text."
         }
       },
       "key": "{bgColor.inverse}"
@@ -1257,7 +1436,8 @@
     "attributes": {},
     "path": ["bgColor", "inverse"],
     "value": "#cdd9e5",
-    "type": "color"
+    "type": "color",
+    "description": "Inverse background that flips between light and dark modes"
   },
   "bgColor-muted": {
     "key": "{bgColor.muted}",
@@ -1280,6 +1460,10 @@
         "dark-high-contrast": "#151b23",
         "dark-tritanopia-high-contrast": "#151b23",
         "dark-protanopia-deuteranopia-high-contrast": "#151b23"
+      },
+      "org.primer.llm": {
+        "usage": ["secondary-content", "code-block-background", "table-header", "sidebar"],
+        "rules": "Use for secondary content areas or to create visual grouping. Do NOT use for primary page backgrounds."
       }
     },
     "filePath": "src/tokens/functional/color/bgColor.json5",
@@ -1287,6 +1471,7 @@
     "original": {
       "$value": "{base.color.neutral.4}",
       "$type": "color",
+      "$description": "Muted background for secondary content areas and subtle grouping",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -1306,6 +1491,10 @@
           "dark-high-contrast": "{base.color.neutral.2}",
           "dark-tritanopia-high-contrast": "{base.color.neutral.2}",
           "dark-protanopia-deuteranopia-high-contrast": "{base.color.neutral.2}"
+        },
+        "org.primer.llm": {
+          "usage": ["secondary-content", "code-block-background", "table-header", "sidebar"],
+          "rules": "Use for secondary content areas or to create visual grouping. Do NOT use for primary page backgrounds."
         }
       },
       "key": "{bgColor.muted}"
@@ -1314,7 +1503,8 @@
     "attributes": {},
     "path": ["bgColor", "muted"],
     "value": "#262c36",
-    "type": "color"
+    "type": "color",
+    "description": "Muted background for secondary content areas and subtle grouping"
   },
   "bgColor-neutral-emphasis": {
     "key": "{bgColor.neutral.emphasis}",
@@ -1334,6 +1524,10 @@
         "dark-high-contrast": "#3d444d",
         "dark-tritanopia-high-contrast": "#3d444d",
         "dark-protanopia-deuteranopia-high-contrast": "#3d444d"
+      },
+      "org.primer.llm": {
+        "usage": ["neutral-button", "secondary-action", "neutral-indicator"],
+        "rules": "Use for emphasized neutral elements. Pair with fgColor.onEmphasis for text."
       }
     },
     "filePath": "src/tokens/functional/color/bgColor.json5",
@@ -1341,6 +1535,7 @@
     "original": {
       "$value": "{base.color.neutral.8}",
       "$type": "color",
+      "$description": "Strong neutral background for prominent neutral elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -1357,6 +1552,10 @@
           "dark-high-contrast": "{base.color.neutral.7}",
           "dark-tritanopia-high-contrast": "{base.color.neutral.7}",
           "dark-protanopia-deuteranopia-high-contrast": "{base.color.neutral.7}"
+        },
+        "org.primer.llm": {
+          "usage": ["neutral-button", "secondary-action", "neutral-indicator"],
+          "rules": "Use for emphasized neutral elements. Pair with fgColor.onEmphasis for text."
         }
       },
       "key": "{bgColor.neutral.emphasis}"
@@ -1365,7 +1564,8 @@
     "attributes": {},
     "path": ["bgColor", "neutral", "emphasis"],
     "value": "#656c76",
-    "type": "color"
+    "type": "color",
+    "description": "Strong neutral background for prominent neutral elements"
   },
   "bgColor-neutral-muted": {
     "key": "{bgColor.neutral.muted}",
@@ -1396,6 +1596,10 @@
         "dark-high-contrast": "#212830",
         "dark-tritanopia-high-contrast": "#212830",
         "dark-protanopia-deuteranopia-high-contrast": "#212830"
+      },
+      "org.primer.llm": {
+        "usage": ["neutral-label", "neutral-badge", "secondary-tag", "counter"],
+        "rules": "Use for neutral semantic meaning. Pair with fgColor.default for text. Do NOT use for status indicators."
       }
     },
     "filePath": "src/tokens/functional/color/bgColor.json5",
@@ -1404,6 +1608,7 @@
     "original": {
       "$value": "{base.color.neutral.8}",
       "$type": "color",
+      "$description": "Subtle neutral background for tags, labels, and secondary UI elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -1431,6 +1636,10 @@
           "dark-high-contrast": "{base.color.neutral.3}",
           "dark-tritanopia-high-contrast": "{base.color.neutral.3}",
           "dark-protanopia-deuteranopia-high-contrast": "{base.color.neutral.3}"
+        },
+        "org.primer.llm": {
+          "usage": ["neutral-label", "neutral-badge", "secondary-tag", "counter"],
+          "rules": "Use for neutral semantic meaning. Pair with fgColor.default for text. Do NOT use for status indicators."
         }
       },
       "alpha": 0.2,
@@ -1440,7 +1649,8 @@
     "attributes": {},
     "path": ["bgColor", "neutral", "muted"],
     "value": "#656c7633",
-    "type": "color"
+    "type": "color",
+    "description": "Subtle neutral background for tags, labels, and secondary UI elements"
   },
   "bgColor-open-emphasis": {
     "key": "{bgColor.open.emphasis}",
@@ -1462,6 +1672,10 @@
         "light-protanopia-deuteranopia-high-contrast": "#ae5622",
         "dark-protanopia-deuteranopia": "#ae5622",
         "dark-protanopia-deuteranopia-high-contrast": "#4d210c"
+      },
+      "org.primer.llm": {
+        "usage": ["open-badge", "open-label", "active-status-badge"],
+        "rules": "Use for prominent open/active state indicators. Pair with fgColor.onEmphasis for text."
       }
     },
     "filePath": "src/tokens/functional/color/bgColor.json5",
@@ -1469,6 +1683,7 @@
     "original": {
       "$value": "{bgColor.success.emphasis}",
       "$type": "color",
+      "$description": "Strong background for open state badges and labels",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -1487,6 +1702,10 @@
           "light-protanopia-deuteranopia-high-contrast": "{base.color.orange.5}",
           "dark-protanopia-deuteranopia": "{base.color.orange.5}",
           "dark-protanopia-deuteranopia-high-contrast": "{base.color.orange.9}"
+        },
+        "org.primer.llm": {
+          "usage": ["open-badge", "open-label", "active-status-badge"],
+          "rules": "Use for prominent open/active state indicators. Pair with fgColor.onEmphasis for text."
         }
       },
       "key": "{bgColor.open.emphasis}"
@@ -1495,7 +1714,8 @@
     "attributes": {},
     "path": ["bgColor", "open", "emphasis"],
     "value": "#347d39",
-    "type": "color"
+    "type": "color",
+    "description": "Strong background for open state badges and labels"
   },
   "bgColor-open-muted": {
     "key": "{bgColor.open.muted}",
@@ -1541,6 +1761,10 @@
           "isSource": true,
           "$type": "color"
         }
+      },
+      "org.primer.llm": {
+        "usage": ["open-issue", "open-pr", "active-status"],
+        "rules": "Use for open/active status indicators. Specifically for GitHub issues and PRs."
       }
     },
     "filePath": "src/tokens/functional/color/bgColor.json5",
@@ -1548,6 +1772,7 @@
     "original": {
       "$value": "{bgColor.success.muted}",
       "$type": "color",
+      "$description": "Subtle background for open state indicators (issues, PRs)",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -1590,6 +1815,10 @@
             "isSource": true,
             "$type": "color"
           }
+        },
+        "org.primer.llm": {
+          "usage": ["open-issue", "open-pr", "active-status"],
+          "rules": "Use for open/active status indicators. Specifically for GitHub issues and PRs."
         }
       },
       "key": "{bgColor.open.muted}"
@@ -1598,7 +1827,8 @@
     "attributes": {},
     "path": ["bgColor", "open", "muted"],
     "value": "#46954a26",
-    "type": "color"
+    "type": "color",
+    "description": "Subtle background for open state indicators (issues, PRs)"
   },
   "bgColor-severe-emphasis": {
     "key": "{bgColor.severe.emphasis}",
@@ -1619,6 +1849,10 @@
         "dark-high-contrast": "#4d210c",
         "dark-dimmed-high-contrast": "#7f3913",
         "dark-protanopia-deuteranopia-high-contrast": "#4d210c"
+      },
+      "org.primer.llm": {
+        "usage": ["severe-badge", "urgent-label", "high-priority-indicator"],
+        "rules": "Use for prominent severe warnings. Pair with fgColor.onEmphasis for text."
       }
     },
     "filePath": "src/tokens/functional/color/bgColor.json5",
@@ -1626,6 +1860,7 @@
     "original": {
       "$value": "{base.color.orange.5}",
       "$type": "color",
+      "$description": "Strong severe background for prominent high-priority warnings",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -1643,6 +1878,10 @@
           "dark-high-contrast": "{base.color.orange.9}",
           "dark-dimmed-high-contrast": "{base.color.orange.7}",
           "dark-protanopia-deuteranopia-high-contrast": "{base.color.orange.9}"
+        },
+        "org.primer.llm": {
+          "usage": ["severe-badge", "urgent-label", "high-priority-indicator"],
+          "rules": "Use for prominent severe warnings. Pair with fgColor.onEmphasis for text."
         }
       },
       "key": "{bgColor.severe.emphasis}"
@@ -1651,7 +1890,8 @@
     "attributes": {},
     "path": ["bgColor", "severe", "emphasis"],
     "value": "#ae5622",
-    "type": "color"
+    "type": "color",
+    "description": "Strong severe background for prominent high-priority warnings"
   },
   "bgColor-severe-muted": {
     "key": "{bgColor.severe.muted}",
@@ -1681,6 +1921,10 @@
           "isSource": true,
           "$type": "color"
         }
+      },
+      "org.primer.llm": {
+        "usage": ["high-priority-warning", "urgent-message", "escalation"],
+        "rules": "Use for severe warnings, less critical than danger. Pair with fgColor.severe for text."
       }
     },
     "filePath": "src/tokens/functional/color/bgColor.json5",
@@ -1689,6 +1933,7 @@
     "original": {
       "$value": "{base.color.orange.4}",
       "$type": "color",
+      "$description": "Subtle severe background for high-priority warnings",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -1715,6 +1960,10 @@
             "isSource": true,
             "$type": "color"
           }
+        },
+        "org.primer.llm": {
+          "usage": ["high-priority-warning", "urgent-message", "escalation"],
+          "rules": "Use for severe warnings, less critical than danger. Pair with fgColor.severe for text."
         }
       },
       "alpha": 0.1,
@@ -1724,7 +1973,8 @@
     "attributes": {},
     "path": ["bgColor", "severe", "muted"],
     "value": "#cc6b2c1a",
-    "type": "color"
+    "type": "color",
+    "description": "Subtle severe background for high-priority warnings"
   },
   "bgColor-sponsors-emphasis": {
     "key": "{bgColor.sponsors.emphasis}",
@@ -1742,6 +1992,10 @@
         "dark-dimmed-high-contrast": "#7e325a",
         "dark-tritanopia-high-contrast": "#551639",
         "dark-protanopia-deuteranopia-high-contrast": "#551639"
+      },
+      "org.primer.llm": {
+        "usage": ["sponsor-button", "sponsor-badge", "funding-cta"],
+        "rules": "Use for prominent Sponsors CTAs. Pair with fgColor.onEmphasis for text."
       }
     },
     "filePath": "src/tokens/functional/color/bgColor.json5",
@@ -1749,6 +2003,7 @@
     "original": {
       "$value": "{base.color.pink.5}",
       "$type": "color",
+      "$description": "Strong background for prominent GitHub Sponsors elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -1763,6 +2018,10 @@
           "dark-dimmed-high-contrast": "{base.color.pink.7}",
           "dark-tritanopia-high-contrast": "{base.color.pink.9}",
           "dark-protanopia-deuteranopia-high-contrast": "{base.color.pink.9}"
+        },
+        "org.primer.llm": {
+          "usage": ["sponsor-button", "sponsor-badge", "funding-cta"],
+          "rules": "Use for prominent Sponsors CTAs. Pair with fgColor.onEmphasis for text."
         }
       },
       "key": "{bgColor.sponsors.emphasis}"
@@ -1771,7 +2030,8 @@
     "attributes": {},
     "path": ["bgColor", "sponsors", "emphasis"],
     "value": "#ae4c82",
-    "type": "color"
+    "type": "color",
+    "description": "Strong background for prominent GitHub Sponsors elements"
   },
   "bgColor-sponsors-muted": {
     "key": "{bgColor.sponsors.muted}",
@@ -1799,6 +2059,10 @@
           "isSource": true,
           "$type": "color"
         }
+      },
+      "org.primer.llm": {
+        "usage": ["sponsor-card", "sponsor-highlight", "funding-prompt"],
+        "rules": "Use for GitHub Sponsors related content. Do NOT use for general pink-colored elements."
       }
     },
     "filePath": "src/tokens/functional/color/bgColor.json5",
@@ -1807,6 +2071,7 @@
     "original": {
       "$value": "{base.color.pink.4}",
       "$type": "color",
+      "$description": "Subtle background for GitHub Sponsors content",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -1831,6 +2096,10 @@
             "isSource": true,
             "$type": "color"
           }
+        },
+        "org.primer.llm": {
+          "usage": ["sponsor-card", "sponsor-highlight", "funding-prompt"],
+          "rules": "Use for GitHub Sponsors related content. Do NOT use for general pink-colored elements."
         }
       },
       "alpha": 0.1,
@@ -1840,7 +2109,8 @@
     "attributes": {},
     "path": ["bgColor", "sponsors", "muted"],
     "value": "#c961981a",
-    "type": "color"
+    "type": "color",
+    "description": "Subtle background for GitHub Sponsors content"
   },
   "bgColor-success-emphasis": {
     "key": "{bgColor.success.emphasis}",
@@ -1866,6 +2136,10 @@
         "light-high-contrast": "#347d39",
         "dark-high-contrast": "#113417",
         "dark-dimmed-high-contrast": "#245829"
+      },
+      "org.primer.llm": {
+        "usage": ["merge-button", "confirm-action", "success-badge"],
+        "rules": "Use for positive action buttons like merge or confirm. Pair with fgColor.onEmphasis for text."
       }
     },
     "filePath": "src/tokens/functional/color/bgColor.json5",
@@ -1873,6 +2147,7 @@
     "original": {
       "$value": "{base.color.green.5}",
       "$type": "color",
+      "$description": "Strong success background for prominent positive actions",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -1895,6 +2170,10 @@
           "light-high-contrast": "{base.color.green.5}",
           "dark-high-contrast": "{base.color.green.9}",
           "dark-dimmed-high-contrast": "{base.color.green.7}"
+        },
+        "org.primer.llm": {
+          "usage": ["merge-button", "confirm-action", "success-badge"],
+          "rules": "Use for positive action buttons like merge or confirm. Pair with fgColor.onEmphasis for text."
         }
       },
       "key": "{bgColor.success.emphasis}"
@@ -1903,7 +2182,8 @@
     "attributes": {},
     "path": ["bgColor", "success", "emphasis"],
     "value": "#347d39",
-    "type": "color"
+    "type": "color",
+    "description": "Strong success background for prominent positive actions"
   },
   "bgColor-success-muted": {
     "key": "{bgColor.success.muted}",
@@ -1956,6 +2236,10 @@
           "isSource": true,
           "$type": "color"
         }
+      },
+      "org.primer.llm": {
+        "usage": ["success-message", "completed-state", "positive-feedback"],
+        "rules": "Use for success states and positive feedback. Pair with fgColor.success for text."
       }
     },
     "filePath": "src/tokens/functional/color/bgColor.json5",
@@ -1964,6 +2248,7 @@
     "original": {
       "$value": "{base.color.green.4}",
       "$type": "color",
+      "$description": "Subtle success background for positive feedback and completed states",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -2013,6 +2298,10 @@
             "isSource": true,
             "$type": "color"
           }
+        },
+        "org.primer.llm": {
+          "usage": ["success-message", "completed-state", "positive-feedback"],
+          "rules": "Use for success states and positive feedback. Pair with fgColor.success for text."
         }
       },
       "alpha": 0.15,
@@ -2022,7 +2311,8 @@
     "attributes": {},
     "path": ["bgColor", "success", "muted"],
     "value": "#46954a26",
-    "type": "color"
+    "type": "color",
+    "description": "Subtle success background for positive feedback and completed states"
   },
   "bgColor-transparent": {
     "key": "{bgColor.transparent}",
@@ -2034,6 +2324,10 @@
         "codeSyntax": {
           "web": "var(--bgColor-transparent) /* utility class: .color-bg-transparent */"
         }
+      },
+      "org.primer.llm": {
+        "usage": ["ghost-button", "icon-button", "overlay-trigger"],
+        "rules": "Use for ghost/icon buttons or when element should blend with parent. Ensure sufficient contrast for interactive states."
       }
     },
     "filePath": "src/tokens/functional/color/bgColor.json5",
@@ -2041,6 +2335,7 @@
     "original": {
       "$value": "{base.color.transparent}",
       "$type": "color",
+      "$description": "Fully transparent background",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -2049,6 +2344,10 @@
           "codeSyntax": {
             "web": "var(--bgColor-transparent) /* utility class: .color-bg-transparent */"
           }
+        },
+        "org.primer.llm": {
+          "usage": ["ghost-button", "icon-button", "overlay-trigger"],
+          "rules": "Use for ghost/icon buttons or when element should blend with parent. Ensure sufficient contrast for interactive states."
         }
       },
       "key": "{bgColor.transparent}"
@@ -2057,7 +2356,8 @@
     "attributes": {},
     "path": ["bgColor", "transparent"],
     "value": "#00000000",
-    "type": "color"
+    "type": "color",
+    "description": "Fully transparent background"
   },
   "bgColor-upsell-emphasis": {
     "key": "{bgColor.upsell.emphasis}",
@@ -2069,6 +2369,10 @@
         "codeSyntax": {
           "web": "var(--bgColor-upsell-emphasis)"
         }
+      },
+      "org.primer.llm": {
+        "usage": ["upgrade-button", "premium-badge", "upsell-cta"],
+        "rules": "Use for prominent upgrade/upsell CTAs. Pair with fgColor.onEmphasis for text."
       }
     },
     "filePath": "src/tokens/functional/color/bgColor.json5",
@@ -2076,6 +2380,7 @@
     "original": {
       "$value": "{bgColor.done.emphasis}",
       "$type": "color",
+      "$description": "Strong background for prominent upsell elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -2084,6 +2389,10 @@
           "codeSyntax": {
             "web": "var(--bgColor-upsell-emphasis)"
           }
+        },
+        "org.primer.llm": {
+          "usage": ["upgrade-button", "premium-badge", "upsell-cta"],
+          "rules": "Use for prominent upgrade/upsell CTAs. Pair with fgColor.onEmphasis for text."
         }
       },
       "key": "{bgColor.upsell.emphasis}"
@@ -2092,7 +2401,8 @@
     "attributes": {},
     "path": ["bgColor", "upsell", "emphasis"],
     "value": "#8256d0",
-    "type": "color"
+    "type": "color",
+    "description": "Strong background for prominent upsell elements"
   },
   "bgColor-upsell-muted": {
     "key": "{bgColor.upsell.muted}",
@@ -2104,6 +2414,10 @@
         "codeSyntax": {
           "web": "var(--bgColor-upsell-muted)"
         }
+      },
+      "org.primer.llm": {
+        "usage": ["upgrade-prompt", "premium-feature", "promotional-banner"],
+        "rules": "Use for upgrade prompts and premium feature highlights. Do NOT use for regular content."
       }
     },
     "filePath": "src/tokens/functional/color/bgColor.json5",
@@ -2111,6 +2425,7 @@
     "original": {
       "$value": "{bgColor.done.muted}",
       "$type": "color",
+      "$description": "Subtle background for upsell and promotional content",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -2119,6 +2434,10 @@
           "codeSyntax": {
             "web": "var(--bgColor-upsell-muted)"
           }
+        },
+        "org.primer.llm": {
+          "usage": ["upgrade-prompt", "premium-feature", "promotional-banner"],
+          "rules": "Use for upgrade prompts and premium feature highlights. Do NOT use for regular content."
         }
       },
       "key": "{bgColor.upsell.muted}"
@@ -2127,7 +2446,8 @@
     "attributes": {},
     "path": ["bgColor", "upsell", "muted"],
     "value": "#986ee226",
-    "type": "color"
+    "type": "color",
+    "description": "Subtle background for upsell and promotional content"
   },
   "bgColor-white": {
     "key": "{bgColor.white}",
@@ -2139,6 +2459,10 @@
       },
       "org.primer.overrides": {
         "dark": "#cdd9e5"
+      },
+      "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."
       }
     },
     "filePath": "src/tokens/functional/color/bgColor.json5",
@@ -2146,6 +2470,7 @@
     "original": {
       "$value": "{base.color.neutral.13}",
       "$type": "color",
+      "$description": "Pure white background",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -2154,6 +2479,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."
         }
       },
       "key": "{bgColor.white}"
@@ -2162,7 +2491,8 @@
     "attributes": {},
     "path": ["bgColor", "white"],
     "value": "#cdd9e5",
-    "type": "color"
+    "type": "color",
+    "description": "Pure white background"
   },
   "border-accent-emphasis": {
     "key": "{border.accent.emphasis}",
@@ -2674,6 +3004,10 @@
       },
       "org.primer.overrides": {
         "dark-dimmed-high-contrast": "#6cb6ff"
+      },
+      "org.primer.llm": {
+        "usage": ["accent-emphasis", "selected-border", "focus-border"],
+        "rules": "Use for selected elements and focus states. Strong visual emphasis."
       }
     },
     "filePath": "src/tokens/functional/color/borderColor.json5",
@@ -2681,6 +3015,7 @@
     "original": {
       "$value": "{base.color.blue.5}",
       "$type": "color",
+      "$description": "Strong accent border for selected or focused elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -2692,6 +3027,10 @@
         },
         "org.primer.overrides": {
           "dark-dimmed-high-contrast": "{base.color.blue.2}"
+        },
+        "org.primer.llm": {
+          "usage": ["accent-emphasis", "selected-border", "focus-border"],
+          "rules": "Use for selected elements and focus states. Strong visual emphasis."
         }
       },
       "key": "{borderColor.accent.emphasis}"
@@ -2700,7 +3039,8 @@
     "attributes": {},
     "path": ["borderColor", "accent", "emphasis"],
     "value": "#316dca",
-    "type": "color"
+    "type": "color",
+    "description": "Strong accent border for selected or focused elements"
   },
   "borderColor-accent-muted": {
     "key": "{borderColor.accent.muted}",
@@ -2764,6 +3104,10 @@
           "isSource": true,
           "$type": "color"
         }
+      },
+      "org.primer.llm": {
+        "usage": ["accent-muted", "selected-muted", "info-muted"],
+        "rules": "Use for accent-colored borders on selected elements. Pair with bgColor.accent.muted."
       }
     },
     "alpha": 0.4,
@@ -2772,6 +3116,7 @@
     "original": {
       "$value": "{base.color.blue.4}",
       "$type": "color",
+      "$description": "Subtle accent border for selected or focused elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -2832,6 +3177,10 @@
             "isSource": true,
             "$type": "color"
           }
+        },
+        "org.primer.llm": {
+          "usage": ["accent-muted", "selected-muted", "info-muted"],
+          "rules": "Use for accent-colored borders on selected elements. Pair with bgColor.accent.muted."
         }
       },
       "alpha": 0.4,
@@ -2841,7 +3190,8 @@
     "attributes": {},
     "path": ["borderColor", "accent", "muted"],
     "value": "#4184e466",
-    "type": "color"
+    "type": "color",
+    "description": "Subtle accent border for selected or focused elements"
   },
   "borderColor-attention-emphasis": {
     "key": "{borderColor.attention.emphasis}",
@@ -2856,6 +3206,10 @@
       },
       "org.primer.overrides": {
         "dark-dimmed-high-contrast": "#daaa3f"
+      },
+      "org.primer.llm": {
+        "usage": ["attention-emphasis", "warning-emphasis", "caution-emphasis"],
+        "rules": "Use for emphasized warning borders. Pair with bgColor.attention.emphasis."
       }
     },
     "filePath": "src/tokens/functional/color/borderColor.json5",
@@ -2863,6 +3217,7 @@
     "original": {
       "$value": "{base.color.yellow.5}",
       "$type": "color",
+      "$description": "Strong attention border for prominent warnings",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -2874,6 +3229,10 @@
         },
         "org.primer.overrides": {
           "dark-dimmed-high-contrast": "{base.color.yellow.2}"
+        },
+        "org.primer.llm": {
+          "usage": ["attention-emphasis", "warning-emphasis", "caution-emphasis"],
+          "rules": "Use for emphasized warning borders. Pair with bgColor.attention.emphasis."
         }
       },
       "key": "{borderColor.attention.emphasis}"
@@ -2882,7 +3241,8 @@
     "attributes": {},
     "path": ["borderColor", "attention", "emphasis"],
     "value": "#966600",
-    "type": "color"
+    "type": "color",
+    "description": "Strong attention border for prominent warnings"
   },
   "borderColor-attention-muted": {
     "key": "{borderColor.attention.muted}",
@@ -2946,6 +3306,10 @@
           "isSource": true,
           "$type": "color"
         }
+      },
+      "org.primer.llm": {
+        "usage": ["attention-muted", "warning-muted", "caution-muted"],
+        "rules": "Use for warning state borders. Pair with bgColor.attention.muted."
       }
     },
     "alpha": 0.4,
@@ -2954,6 +3318,7 @@
     "original": {
       "$value": "{base.color.yellow.4}",
       "$type": "color",
+      "$description": "Subtle attention border for warnings and caution states",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -3014,6 +3379,10 @@
             "isSource": true,
             "$type": "color"
           }
+        },
+        "org.primer.llm": {
+          "usage": ["attention-muted", "warning-muted", "caution-muted"],
+          "rules": "Use for warning state borders. Pair with bgColor.attention.muted."
         }
       },
       "alpha": 0.4,
@@ -3023,7 +3392,8 @@
     "attributes": {},
     "path": ["borderColor", "attention", "muted"],
     "value": "#ae7c1466",
-    "type": "color"
+    "type": "color",
+    "description": "Subtle attention border for warnings and caution states"
   },
   "borderColor-closed-emphasis": {
     "key": "{borderColor.closed.emphasis}",
@@ -3045,6 +3415,10 @@
         "dark-tritanopia-high-contrast": "#656c76",
         "light-tritanopia": "#656c76",
         "light-tritanopia-high-contrast": "#656c76"
+      },
+      "org.primer.llm": {
+        "usage": ["closed-emphasis", "closed-status"],
+        "rules": "Use for emphasized closed state borders. Pair with bgColor.closed.emphasis."
       }
     },
     "filePath": "src/tokens/functional/color/borderColor.json5",
@@ -3052,6 +3426,7 @@
     "original": {
       "$value": "{borderColor.danger.emphasis}",
       "$type": "color",
+      "$description": "Strong border for closed state badges",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -3070,6 +3445,10 @@
           "dark-tritanopia-high-contrast": "{borderColor.emphasis}",
           "light-tritanopia": "{borderColor.emphasis}",
           "light-tritanopia-high-contrast": "{borderColor.emphasis}"
+        },
+        "org.primer.llm": {
+          "usage": ["closed-emphasis", "closed-status"],
+          "rules": "Use for emphasized closed state borders. Pair with bgColor.closed.emphasis."
         }
       },
       "key": "{borderColor.closed.emphasis}"
@@ -3078,7 +3457,8 @@
     "attributes": {},
     "path": ["borderColor", "closed", "emphasis"],
     "value": "#c93c37",
-    "type": "color"
+    "type": "color",
+    "description": "Strong border for closed state badges"
   },
   "borderColor-closed-muted": {
     "key": "{borderColor.closed.muted}",
@@ -3148,6 +3528,10 @@
           "isSource": true,
           "$type": "color"
         }
+      },
+      "org.primer.llm": {
+        "usage": ["closed-muted", "closed-issue", "closed-pr"],
+        "rules": "Use for closed/declined status borders. Specifically for GitHub issues and PRs."
       }
     },
     "filePath": "src/tokens/functional/color/borderColor.json5",
@@ -3155,6 +3539,7 @@
     "original": {
       "$value": "{borderColor.danger.muted}",
       "$type": "color",
+      "$description": "Subtle border for closed state indicators",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -3221,6 +3606,10 @@
             "isSource": true,
             "$type": "color"
           }
+        },
+        "org.primer.llm": {
+          "usage": ["closed-muted", "closed-issue", "closed-pr"],
+          "rules": "Use for closed/declined status borders. Specifically for GitHub issues and PRs."
         }
       },
       "key": "{borderColor.closed.muted}"
@@ -3229,7 +3618,8 @@
     "attributes": {},
     "path": ["borderColor", "closed", "muted"],
     "value": "#e5534b66",
-    "type": "color"
+    "type": "color",
+    "description": "Subtle border for closed state indicators"
   },
   "borderColor-danger-emphasis": {
     "key": "{borderColor.danger.emphasis}",
@@ -3268,6 +3658,10 @@
           "$type": "color"
         },
         "dark-dimmed-high-contrast": "#ff938a"
+      },
+      "org.primer.llm": {
+        "usage": ["danger-emphasis", "error-emphasis", "destructive-emphasis"],
+        "rules": "MUST use for destructive action borders. Pair with bgColor.danger.emphasis."
       }
     },
     "filePath": "src/tokens/functional/color/borderColor.json5",
@@ -3275,6 +3669,7 @@
     "original": {
       "$value": "{base.color.red.5}",
       "$type": "color",
+      "$description": "Strong danger border for destructive actions and errors",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -3310,6 +3705,10 @@
             "$type": "color"
           },
           "dark-dimmed-high-contrast": "{base.color.red.2}"
+        },
+        "org.primer.llm": {
+          "usage": ["danger-emphasis", "error-emphasis", "destructive-emphasis"],
+          "rules": "MUST use for destructive action borders. Pair with bgColor.danger.emphasis."
         }
       },
       "key": "{borderColor.danger.emphasis}"
@@ -3318,7 +3717,8 @@
     "attributes": {},
     "path": ["borderColor", "danger", "emphasis"],
     "value": "#c93c37",
-    "type": "color"
+    "type": "color",
+    "description": "Strong danger border for destructive actions and errors"
   },
   "borderColor-danger-muted": {
     "key": "{borderColor.danger.muted}",
@@ -3395,6 +3795,10 @@
           "isSource": true,
           "$type": "color"
         }
+      },
+      "org.primer.llm": {
+        "usage": ["danger-muted", "error-muted", "destructive-muted"],
+        "rules": "Use for error state borders. Pair with bgColor.danger.muted."
       }
     },
     "alpha": 0.4,
@@ -3403,6 +3807,7 @@
     "original": {
       "$value": "{base.color.red.4}",
       "$type": "color",
+      "$description": "Subtle danger border for errors and destructive contexts",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -3476,6 +3881,10 @@
             "isSource": true,
             "$type": "color"
           }
+        },
+        "org.primer.llm": {
+          "usage": ["danger-muted", "error-muted", "destructive-muted"],
+          "rules": "Use for error state borders. Pair with bgColor.danger.muted."
         }
       },
       "alpha": 0.4,
@@ -3485,7 +3894,8 @@
     "attributes": {},
     "path": ["borderColor", "danger", "muted"],
     "value": "#e5534b66",
-    "type": "color"
+    "type": "color",
+    "description": "Subtle danger border for errors and destructive contexts"
   },
   "borderColor-default": {
     "key": "{borderColor.default}",
@@ -3508,6 +3918,10 @@
         "codeSyntax": {
           "web": "var(--borderColor-default) /* utility class: .color-border-default */"
         }
+      },
+      "org.primer.llm": {
+        "usage": ["default-border", "card-border", "input-border", "divider"],
+        "rules": "RECOMMENDED default for all borders. Use for cards, inputs, and dividers."
       }
     },
     "filePath": "src/tokens/functional/color/borderColor.json5",
@@ -3515,6 +3929,7 @@
     "original": {
       "$value": "{base.color.neutral.7}",
       "$type": "color",
+      "$description": "Default border color for most UI elements",
       "$extensions": {
         "org.primer.overrides": {
           "dark": "{base.color.neutral.7}",
@@ -3534,6 +3949,10 @@
           "codeSyntax": {
             "web": "var(--borderColor-default) /* utility class: .color-border-default */"
           }
+        },
+        "org.primer.llm": {
+          "usage": ["default-border", "card-border", "input-border", "divider"],
+          "rules": "RECOMMENDED default for all borders. Use for cards, inputs, and dividers."
         }
       },
       "key": "{borderColor.default}"
@@ -3542,7 +3961,8 @@
     "attributes": {},
     "path": ["borderColor", "default"],
     "value": "#3d444d",
-    "type": "color"
+    "type": "color",
+    "description": "Default border color for most UI elements"
   },
   "borderColor-disabled": {
     "key": "{borderColor.disabled}",
@@ -3588,6 +4008,10 @@
           "isSource": true,
           "$type": "color"
         }
+      },
+      "org.primer.llm": {
+        "usage": ["disabled-border", "inactive-border", "unavailable"],
+        "rules": "MUST use for disabled state borders. Pair with bgColor.disabled. Do NOT use for active elements."
       }
     },
     "alpha": 0.1,
@@ -3596,6 +4020,7 @@
     "original": {
       "$value": "{base.color.neutral.8}",
       "$type": "color",
+      "$description": "Border color for disabled interactive elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -3638,6 +4063,10 @@
             "isSource": true,
             "$type": "color"
           }
+        },
+        "org.primer.llm": {
+          "usage": ["disabled-border", "inactive-border", "unavailable"],
+          "rules": "MUST use for disabled state borders. Pair with bgColor.disabled. Do NOT use for active elements."
         }
       },
       "alpha": 0.1,
@@ -3647,7 +4076,8 @@
     "attributes": {},
     "path": ["borderColor", "disabled"],
     "value": "#656c761a",
-    "type": "color"
+    "type": "color",
+    "description": "Border color for disabled interactive elements"
   },
   "borderColor-done-emphasis": {
     "key": "{borderColor.done.emphasis}",
@@ -3662,6 +4092,10 @@
       },
       "org.primer.overrides": {
         "dark-dimmed-high-contrast": "#dcbdfb"
+      },
+      "org.primer.llm": {
+        "usage": ["done-emphasis", "merged-status"],
+        "rules": "Use for emphasized done state borders. Pair with bgColor.done.emphasis."
       }
     },
     "filePath": "src/tokens/functional/color/borderColor.json5",
@@ -3669,6 +4103,7 @@
     "original": {
       "$value": "{base.color.purple.5}",
       "$type": "color",
+      "$description": "Strong border for completed/done state badges",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -3680,6 +4115,10 @@
         },
         "org.primer.overrides": {
           "dark-dimmed-high-contrast": "{base.color.purple.2}"
+        },
+        "org.primer.llm": {
+          "usage": ["done-emphasis", "merged-status"],
+          "rules": "Use for emphasized done state borders. Pair with bgColor.done.emphasis."
         }
       },
       "key": "{borderColor.done.emphasis}"
@@ -3688,7 +4127,8 @@
     "attributes": {},
     "path": ["borderColor", "done", "emphasis"],
     "value": "#8256d0",
-    "type": "color"
+    "type": "color",
+    "description": "Strong border for completed/done state badges"
   },
   "borderColor-done-muted": {
     "key": "{borderColor.done.muted}",
@@ -3752,6 +4192,10 @@
           "isSource": true,
           "$type": "color"
         }
+      },
+      "org.primer.llm": {
+        "usage": ["done-muted", "merged", "completed"],
+        "rules": "Use for completed/done status borders. Conveys finished or merged state."
       }
     },
     "alpha": 0.4,
@@ -3760,6 +4204,7 @@
     "original": {
       "$value": "{base.color.purple.4}",
       "$type": "color",
+      "$description": "Subtle border for completed/done state indicators",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -3820,6 +4265,10 @@
             "isSource": true,
             "$type": "color"
           }
+        },
+        "org.primer.llm": {
+          "usage": ["done-muted", "merged", "completed"],
+          "rules": "Use for completed/done status borders. Conveys finished or merged state."
         }
       },
       "alpha": 0.4,
@@ -3829,7 +4278,8 @@
     "attributes": {},
     "path": ["borderColor", "done", "muted"],
     "value": "#986ee266",
-    "type": "color"
+    "type": "color",
+    "description": "Subtle border for completed/done state indicators"
   },
   "borderColor-draft-emphasis": {
     "key": "{borderColor.draft.emphasis}",
@@ -3841,6 +4291,10 @@
         "codeSyntax": {
           "web": "var(--borderColor-draft-emphasis)"
         }
+      },
+      "org.primer.llm": {
+        "usage": ["draft-emphasis", "draft-status"],
+        "rules": "Use for emphasized draft state borders. Pair with bgColor.draft.emphasis."
       }
     },
     "filePath": "src/tokens/functional/color/borderColor.json5",
@@ -3848,6 +4302,7 @@
     "original": {
       "$value": "{borderColor.neutral.emphasis}",
       "$type": "color",
+      "$description": "Strong border for draft state badges",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -3856,6 +4311,10 @@
           "codeSyntax": {
             "web": "var(--borderColor-draft-emphasis)"
           }
+        },
+        "org.primer.llm": {
+          "usage": ["draft-emphasis", "draft-status"],
+          "rules": "Use for emphasized draft state borders. Pair with bgColor.draft.emphasis."
         }
       },
       "key": "{borderColor.draft.emphasis}"
@@ -3864,7 +4323,8 @@
     "attributes": {},
     "path": ["borderColor", "draft", "emphasis"],
     "value": "#656c76",
-    "type": "color"
+    "type": "color",
+    "description": "Strong border for draft state badges"
   },
   "borderColor-draft-muted": {
     "key": "{borderColor.draft.muted}",
@@ -3934,6 +4394,10 @@
           "isSource": true,
           "$type": "color"
         }
+      },
+      "org.primer.llm": {
+        "usage": ["draft-muted", "draft-pr", "draft-issue"],
+        "rules": "Use for draft/WIP status borders. Conveys incomplete or pending state."
       }
     },
     "filePath": "src/tokens/functional/color/borderColor.json5",
@@ -3941,6 +4405,7 @@
     "original": {
       "$value": "{borderColor.neutral.muted}",
       "$type": "color",
+      "$description": "Subtle border for draft state indicators",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -4007,6 +4472,10 @@
             "isSource": true,
             "$type": "color"
           }
+        },
+        "org.primer.llm": {
+          "usage": ["draft-muted", "draft-pr", "draft-issue"],
+          "rules": "Use for draft/WIP status borders. Conveys incomplete or pending state."
         }
       },
       "key": "{borderColor.draft.muted}"
@@ -4015,7 +4484,8 @@
     "attributes": {},
     "path": ["borderColor", "draft", "muted"],
     "value": "#3d444db3",
-    "type": "color"
+    "type": "color",
+    "description": "Subtle border for draft state indicators"
   },
   "borderColor-emphasis": {
     "key": "{borderColor.emphasis}",
@@ -4033,6 +4503,10 @@
         "dark-dimmed-high-contrast": "#3d444d",
         "dark-tritanopia-high-contrast": "#3d444d",
         "dark-protanopia-deuteranopia-high-contrast": "#3d444d"
+      },
+      "org.primer.llm": {
+        "usage": ["emphasis-border", "strong-border", "selected-border"],
+        "rules": "Use for borders needing more visual weight. Darker than borderColor.default."
       }
     },
     "filePath": "src/tokens/functional/color/borderColor.json5",
@@ -4040,6 +4514,7 @@
     "original": {
       "$value": "{base.color.neutral.8}",
       "$type": "color",
+      "$description": "Strong border for emphasis and visual weight",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -4054,6 +4529,10 @@
           "dark-dimmed-high-contrast": "{borderColor.default}",
           "dark-tritanopia-high-contrast": "{borderColor.default}",
           "dark-protanopia-deuteranopia-high-contrast": "{borderColor.default}"
+        },
+        "org.primer.llm": {
+          "usage": ["emphasis-border", "strong-border", "selected-border"],
+          "rules": "Use for borders needing more visual weight. Darker than borderColor.default."
         }
       },
       "key": "{borderColor.emphasis}"
@@ -4062,7 +4541,8 @@
     "attributes": {},
     "path": ["borderColor", "emphasis"],
     "value": "#656c76",
-    "type": "color"
+    "type": "color",
+    "description": "Strong border for emphasis and visual weight"
   },
   "borderColor-muted": {
     "key": "{borderColor.muted}",
@@ -4132,6 +4612,10 @@
           "isSource": true,
           "$type": "color"
         }
+      },
+      "org.primer.llm": {
+        "usage": ["subtle-border", "light-divider", "secondary-border"],
+        "rules": "Use for subtle borders and separators. Less prominent than borderColor.default."
       }
     },
     "alpha": 0.7,
@@ -4140,6 +4624,7 @@
     "original": {
       "$value": "{base.color.neutral.7}",
       "$type": "color",
+      "$description": "Subtle border for secondary elements and light separators",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -4206,6 +4691,10 @@
             "isSource": true,
             "$type": "color"
           }
+        },
+        "org.primer.llm": {
+          "usage": ["subtle-border", "light-divider", "secondary-border"],
+          "rules": "Use for subtle borders and separators. Less prominent than borderColor.default."
         }
       },
       "alpha": 0.7,
@@ -4215,7 +4704,8 @@
     "attributes": {},
     "path": ["borderColor", "muted"],
     "value": "#3d444db3",
-    "type": "color"
+    "type": "color",
+    "description": "Subtle border for secondary elements and light separators"
   },
   "borderColor-neutral-emphasis": {
     "key": "{borderColor.neutral.emphasis}",
@@ -4227,6 +4717,10 @@
       },
       "org.primer.overrides": {
         "dark": "#656c76"
+      },
+      "org.primer.llm": {
+        "usage": ["neutral-emphasis", "neutral-strong"],
+        "rules": "Use for emphasized neutral semantic borders. Stronger than neutral.muted."
       }
     },
     "filePath": "src/tokens/functional/color/borderColor.json5",
@@ -4234,6 +4728,7 @@
     "original": {
       "$value": "{borderColor.emphasis}",
       "$type": "color",
+      "$description": "Strong neutral semantic border",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -4242,6 +4737,10 @@
         },
         "org.primer.overrides": {
           "dark": "{borderColor.emphasis}"
+        },
+        "org.primer.llm": {
+          "usage": ["neutral-emphasis", "neutral-strong"],
+          "rules": "Use for emphasized neutral semantic borders. Stronger than neutral.muted."
         }
       },
       "key": "{borderColor.neutral.emphasis}"
@@ -4250,7 +4749,8 @@
     "attributes": {},
     "path": ["borderColor", "neutral", "emphasis"],
     "value": "#656c76",
-    "type": "color"
+    "type": "color",
+    "description": "Strong neutral semantic border"
   },
   "borderColor-neutral-muted": {
     "key": "{borderColor.neutral.muted}",
@@ -4275,6 +4775,10 @@
           "isSource": true,
           "$type": "color"
         }
+      },
+      "org.primer.llm": {
+        "usage": ["neutral-muted", "neutral-secondary"],
+        "rules": "Use for neutral semantic borders on tags and badges. Prefer borderColor.muted for general use."
       }
     },
     "filePath": "src/tokens/functional/color/borderColor.json5",
@@ -4283,6 +4787,7 @@
     "original": {
       "$value": "{base.color.neutral.7}",
       "$type": "color",
+      "$description": "Subtle neutral semantic border",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -4304,6 +4809,10 @@
             "isSource": true,
             "$type": "color"
           }
+        },
+        "org.primer.llm": {
+          "usage": ["neutral-muted", "neutral-secondary"],
+          "rules": "Use for neutral semantic borders on tags and badges. Prefer borderColor.muted for general use."
         }
       },
       "alpha": 0.7,
@@ -4313,7 +4822,8 @@
     "attributes": {},
     "path": ["borderColor", "neutral", "muted"],
     "value": "#3d444db3",
-    "type": "color"
+    "type": "color",
+    "description": "Subtle neutral semantic border"
   },
   "borderColor-open-emphasis": {
     "key": "{borderColor.open.emphasis}",
@@ -4335,6 +4845,10 @@
         "dark-protanopia-deuteranopia-high-contrast": "#ae5622",
         "light-protanopia-deuteranopia": "#ae5622",
         "light-protanopia-deuteranopia-high-contrast": "#ae5622"
+      },
+      "org.primer.llm": {
+        "usage": ["open-emphasis", "open-status"],
+        "rules": "Use for emphasized open state borders. Pair with bgColor.open.emphasis."
       }
     },
     "filePath": "src/tokens/functional/color/borderColor.json5",
@@ -4342,6 +4856,7 @@
     "original": {
       "$value": "{borderColor.success.emphasis}",
       "$type": "color",
+      "$description": "Strong border for open state badges",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -4360,6 +4875,10 @@
           "dark-protanopia-deuteranopia-high-contrast": "{base.color.orange.5}",
           "light-protanopia-deuteranopia": "{base.color.orange.5}",
           "light-protanopia-deuteranopia-high-contrast": "{base.color.orange.5}"
+        },
+        "org.primer.llm": {
+          "usage": ["open-emphasis", "open-status"],
+          "rules": "Use for emphasized open state borders. Pair with bgColor.open.emphasis."
         }
       },
       "key": "{borderColor.open.emphasis}"
@@ -4368,7 +4887,8 @@
     "attributes": {},
     "path": ["borderColor", "open", "emphasis"],
     "value": "#347d39",
-    "type": "color"
+    "type": "color",
+    "description": "Strong border for open state badges"
   },
   "borderColor-open-muted": {
     "key": "{borderColor.open.muted}",
@@ -4438,6 +4958,10 @@
           "isSource": true,
           "$type": "color"
         }
+      },
+      "org.primer.llm": {
+        "usage": ["open-muted", "open-issue", "open-pr"],
+        "rules": "Use for open/active status borders. Specifically for GitHub issues and PRs."
       }
     },
     "filePath": "src/tokens/functional/color/borderColor.json5",
@@ -4445,6 +4969,7 @@
     "original": {
       "$value": "{borderColor.success.muted}",
       "$type": "color",
+      "$description": "Subtle border for open state indicators",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -4511,6 +5036,10 @@
             "isSource": true,
             "$type": "color"
           }
+        },
+        "org.primer.llm": {
+          "usage": ["open-muted", "open-issue", "open-pr"],
+          "rules": "Use for open/active status borders. Specifically for GitHub issues and PRs."
         }
       },
       "key": "{borderColor.open.muted}"
@@ -4519,7 +5048,8 @@
     "attributes": {},
     "path": ["borderColor", "open", "muted"],
     "value": "#46954a66",
-    "type": "color"
+    "type": "color",
+    "description": "Subtle border for open state indicators"
   },
   "borderColor-severe-emphasis": {
     "key": "{borderColor.severe.emphasis}",
@@ -4537,6 +5067,10 @@
         "light-tritanopia": "#c93c37",
         "light-tritanopia-high-contrast": "#c93c37",
         "dark-dimmed-high-contrast": "#f69d50"
+      },
+      "org.primer.llm": {
+        "usage": ["severe-emphasis", "urgent-emphasis"],
+        "rules": "Use for emphasized severe borders. Pair with bgColor.severe.emphasis."
       }
     },
     "filePath": "src/tokens/functional/color/borderColor.json5",
@@ -4544,6 +5078,7 @@
     "original": {
       "$value": "{base.color.orange.5}",
       "$type": "color",
+      "$description": "Strong severe border for prominent high-priority warnings",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -4558,6 +5093,10 @@
           "light-tritanopia": "{base.color.red.5}",
           "light-tritanopia-high-contrast": "{base.color.red.5}",
           "dark-dimmed-high-contrast": "{base.color.orange.2}"
+        },
+        "org.primer.llm": {
+          "usage": ["severe-emphasis", "urgent-emphasis"],
+          "rules": "Use for emphasized severe borders. Pair with bgColor.severe.emphasis."
         }
       },
       "key": "{borderColor.severe.emphasis}"
@@ -4566,7 +5105,8 @@
     "attributes": {},
     "path": ["borderColor", "severe", "emphasis"],
     "value": "#ae5622",
-    "type": "color"
+    "type": "color",
+    "description": "Strong severe border for prominent high-priority warnings"
   },
   "borderColor-severe-muted": {
     "key": "{borderColor.severe.muted}",
@@ -4625,6 +5165,10 @@
           "isSource": true,
           "$type": "color"
         }
+      },
+      "org.primer.llm": {
+        "usage": ["severe-muted", "urgent-muted"],
+        "rules": "Use for severe warning borders. More critical than attention, less than danger."
       }
     },
     "alpha": 0.4,
@@ -4633,6 +5177,7 @@
     "original": {
       "$value": "{base.color.orange.4}",
       "$type": "color",
+      "$description": "Subtle severe border for high-priority warnings",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -4688,6 +5233,10 @@
             "isSource": true,
             "$type": "color"
           }
+        },
+        "org.primer.llm": {
+          "usage": ["severe-muted", "urgent-muted"],
+          "rules": "Use for severe warning borders. More critical than attention, less than danger."
         }
       },
       "alpha": 0.4,
@@ -4697,7 +5246,8 @@
     "attributes": {},
     "path": ["borderColor", "severe", "muted"],
     "value": "#cc6b2c66",
-    "type": "color"
+    "type": "color",
+    "description": "Subtle severe border for high-priority warnings"
   },
   "borderColor-sponsors-emphasis": {
     "key": "{borderColor.sponsors.emphasis}",
@@ -4712,6 +5262,10 @@
       },
       "org.primer.overrides": {
         "dark-dimmed-high-contrast": "#e275ad"
+      },
+      "org.primer.llm": {
+        "usage": ["sponsors-emphasis", "funding-emphasis"],
+        "rules": "Use for emphasized Sponsors borders. Pair with bgColor.sponsors.emphasis."
       }
     },
     "filePath": "src/tokens/functional/color/borderColor.json5",
@@ -4719,6 +5273,7 @@
     "original": {
       "$value": "{base.color.pink.5}",
       "$type": "color",
+      "$description": "Strong border for prominent GitHub Sponsors elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -4730,6 +5285,10 @@
         },
         "org.primer.overrides": {
           "dark-dimmed-high-contrast": "{base.color.pink.3}"
+        },
+        "org.primer.llm": {
+          "usage": ["sponsors-emphasis", "funding-emphasis"],
+          "rules": "Use for emphasized Sponsors borders. Pair with bgColor.sponsors.emphasis."
         }
       },
       "key": "{borderColor.sponsors.emphasis}"
@@ -4738,7 +5297,8 @@
     "attributes": {},
     "path": ["borderColor", "sponsors", "emphasis"],
     "value": "#ae4c82",
-    "type": "color"
+    "type": "color",
+    "description": "Strong border for prominent GitHub Sponsors elements"
   },
   "borderColor-sponsors-muted": {
     "key": "{borderColor.sponsors.muted}",
@@ -4802,6 +5362,10 @@
           "isSource": true,
           "$type": "color"
         }
+      },
+      "org.primer.llm": {
+        "usage": ["sponsors-muted", "funding-muted"],
+        "rules": "Use for GitHub Sponsors related borders. Do NOT use for general pink-colored elements."
       }
     },
     "alpha": 0.4,
@@ -4810,6 +5374,7 @@
     "original": {
       "$value": "{base.color.pink.4}",
       "$type": "color",
+      "$description": "Subtle border for GitHub Sponsors content",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -4870,6 +5435,10 @@
             "isSource": true,
             "$type": "color"
           }
+        },
+        "org.primer.llm": {
+          "usage": ["sponsors-muted", "funding-muted"],
+          "rules": "Use for GitHub Sponsors related borders. Do NOT use for general pink-colored elements."
         }
       },
       "alpha": 0.4,
@@ -4879,7 +5448,8 @@
     "attributes": {},
     "path": ["borderColor", "sponsors", "muted"],
     "value": "#c9619866",
-    "type": "color"
+    "type": "color",
+    "description": "Subtle border for GitHub Sponsors content"
   },
   "borderColor-success-emphasis": {
     "key": "{borderColor.success.emphasis}",
@@ -4902,6 +5472,10 @@
         "light-protanopia-deuteranopia": "#316dca",
         "light-protanopia-deuteranopia-high-contrast": "#316dca",
         "dark-dimmed-high-contrast": "#6bc46d"
+      },
+      "org.primer.llm": {
+        "usage": ["success-emphasis", "confirmed", "positive-emphasis"],
+        "rules": "Use for emphasized success borders. Pair with bgColor.success.emphasis."
       }
     },
     "filePath": "src/tokens/functional/color/borderColor.json5",
@@ -4909,6 +5483,7 @@
     "original": {
       "$value": "{base.color.green.5}",
       "$type": "color",
+      "$description": "Strong success border for prominent positive elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -4928,6 +5503,10 @@
           "light-protanopia-deuteranopia": "{base.color.blue.5}",
           "light-protanopia-deuteranopia-high-contrast": "{base.color.blue.5}",
           "dark-dimmed-high-contrast": "{base.color.green.2}"
+        },
+        "org.primer.llm": {
+          "usage": ["success-emphasis", "confirmed", "positive-emphasis"],
+          "rules": "Use for emphasized success borders. Pair with bgColor.success.emphasis."
         }
       },
       "key": "{borderColor.success.emphasis}"
@@ -4936,7 +5515,8 @@
     "attributes": {},
     "path": ["borderColor", "success", "emphasis"],
     "value": "#347d39",
-    "type": "color"
+    "type": "color",
+    "description": "Strong success border for prominent positive elements"
   },
   "borderColor-success-muted": {
     "key": "{borderColor.success.muted}",
@@ -5027,6 +5607,10 @@
           "isSource": true,
           "$type": "color"
         }
+      },
+      "org.primer.llm": {
+        "usage": ["success-muted", "valid-muted", "positive-muted"],
+        "rules": "Use for success state borders. Pair with bgColor.success.muted."
       }
     },
     "alpha": 0.4,
@@ -5035,6 +5619,7 @@
     "original": {
       "$value": "{base.color.green.4}",
       "$type": "color",
+      "$description": "Subtle success border for positive feedback elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -5122,6 +5707,10 @@
             "isSource": true,
             "$type": "color"
           }
+        },
+        "org.primer.llm": {
+          "usage": ["success-muted", "valid-muted", "positive-muted"],
+          "rules": "Use for success state borders. Pair with bgColor.success.muted."
         }
       },
       "alpha": 0.4,
@@ -5131,7 +5720,8 @@
     "attributes": {},
     "path": ["borderColor", "success", "muted"],
     "value": "#46954a66",
-    "type": "color"
+    "type": "color",
+    "description": "Subtle success border for positive feedback elements"
   },
   "borderColor-translucent": {
     "key": "{borderColor.translucent}",
@@ -5191,6 +5781,10 @@
           "isSource": true,
           "$type": "color"
         }
+      },
+      "org.primer.llm": {
+        "usage": ["overlay-border", "translucent-border"],
+        "rules": "Use for semi-transparent borders on overlays. Works well with translucent backgrounds."
       }
     },
     "alpha": 0.15,
@@ -5199,6 +5793,7 @@
     "original": {
       "$value": "{base.color.neutral.13}",
       "$type": "color",
+      "$description": "Semi-transparent border for overlays and layered elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -5255,6 +5850,10 @@
             "isSource": true,
             "$type": "color"
           }
+        },
+        "org.primer.llm": {
+          "usage": ["overlay-border", "translucent-border"],
+          "rules": "Use for semi-transparent borders on overlays. Works well with translucent backgrounds."
         }
       },
       "alpha": 0.15,
@@ -5264,7 +5863,8 @@
     "attributes": {},
     "path": ["borderColor", "translucent"],
     "value": "#cdd9e526",
-    "type": "color"
+    "type": "color",
+    "description": "Semi-transparent border for overlays and layered elements"
   },
   "borderColor-transparent": {
     "key": "{borderColor.transparent}",
@@ -5280,6 +5880,7 @@
     "original": {
       "$value": "{base.color.transparent}",
       "$type": "color",
+      "$description": "Fully transparent border",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -5293,7 +5894,8 @@
     "attributes": {},
     "path": ["borderColor", "transparent"],
     "value": "#00000000",
-    "type": "color"
+    "type": "color",
+    "description": "Fully transparent border"
   },
   "borderColor-upsell-emphasis": {
     "key": "{borderColor.upsell.emphasis}",
@@ -5305,6 +5907,10 @@
         "codeSyntax": {
           "web": "var(--borderColor-upsell-emphasis)"
         }
+      },
+      "org.primer.llm": {
+        "usage": ["upsell-emphasis", "premium-emphasis"],
+        "rules": "Use for emphasized upsell borders. Pair with bgColor.upsell.emphasis."
       }
     },
     "filePath": "src/tokens/functional/color/borderColor.json5",
@@ -5312,6 +5918,7 @@
     "original": {
       "$value": "{borderColor.done.emphasis}",
       "$type": "color",
+      "$description": "Strong border for prominent upsell elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -5320,6 +5927,10 @@
           "codeSyntax": {
             "web": "var(--borderColor-upsell-emphasis)"
           }
+        },
+        "org.primer.llm": {
+          "usage": ["upsell-emphasis", "premium-emphasis"],
+          "rules": "Use for emphasized upsell borders. Pair with bgColor.upsell.emphasis."
         }
       },
       "key": "{borderColor.upsell.emphasis}"
@@ -5328,7 +5939,8 @@
     "attributes": {},
     "path": ["borderColor", "upsell", "emphasis"],
     "value": "#8256d0",
-    "type": "color"
+    "type": "color",
+    "description": "Strong border for prominent upsell elements"
   },
   "borderColor-upsell-muted": {
     "key": "{borderColor.upsell.muted}",
@@ -5340,6 +5952,10 @@
         "codeSyntax": {
           "web": "var(--borderColor-upsell-muted)"
         }
+      },
+      "org.primer.llm": {
+        "usage": ["upsell-muted", "premium-muted"],
+        "rules": "Use for upgrade prompts and premium feature borders. Do NOT use for regular content."
       }
     },
     "filePath": "src/tokens/functional/color/borderColor.json5",
@@ -5347,6 +5963,7 @@
     "original": {
       "$value": "{borderColor.done.muted}",
       "$type": "color",
+      "$description": "Subtle border for upsell and promotional content",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -5355,6 +5972,10 @@
           "codeSyntax": {
             "web": "var(--borderColor-upsell-muted)"
           }
+        },
+        "org.primer.llm": {
+          "usage": ["upsell-muted", "premium-muted"],
+          "rules": "Use for upgrade prompts and premium feature borders. Do NOT use for regular content."
         }
       },
       "key": "{borderColor.upsell.muted}"
@@ -5363,7 +5984,8 @@
     "attributes": {},
     "path": ["borderColor", "upsell", "muted"],
     "value": "#986ee266",
-    "type": "color"
+    "type": "color",
+    "description": "Subtle border for upsell and promotional content"
   },
   "button-danger-bgColor-active": {
     "key": "{button.danger.bgColor.active}",
@@ -6766,7 +7388,7 @@
       },
       "org.primer.overrides": {
         "dark": {
-          "$value": "#d1d7e0",
+          "$value": "#f0f6fc",
           "filePath": "src/tokens/component/button.json5",
           "isSource": true,
           "$type": "color"
@@ -6798,7 +7420,7 @@
     "name": "button-default-fgColor-rest",
     "attributes": {},
     "path": ["button", "default", "fgColor", "rest"],
-    "value": "#d1d7e0",
+    "value": "#f0f6fc",
     "type": "color"
   },
   "button-default-shadow-resting": {
@@ -7493,7 +8115,7 @@
       },
       "org.primer.overrides": {
         "dark": {
-          "$value": "#d1d7e0",
+          "$value": "#f0f6fc",
           "filePath": "src/tokens/component/button.json5",
           "isSource": true,
           "$type": "color"
@@ -7525,7 +8147,7 @@
     "name": "button-invisible-fgColor-active",
     "attributes": {},
     "path": ["button", "invisible", "fgColor", "active"],
-    "value": "#d1d7e0",
+    "value": "#f0f6fc",
     "type": "color"
   },
   "button-invisible-fgColor-disabled": {
@@ -7583,7 +8205,7 @@
       },
       "org.primer.overrides": {
         "dark": {
-          "$value": "#d1d7e0",
+          "$value": "#f0f6fc",
           "filePath": "src/tokens/component/button.json5",
           "isSource": true,
           "$type": "color"
@@ -7651,7 +8273,7 @@
     "name": "button-invisible-fgColor-hover",
     "attributes": {},
     "path": ["button", "invisible", "fgColor", "hover"],
-    "value": "#d1d7e0",
+    "value": "#f0f6fc",
     "type": "color"
   },
   "button-invisible-fgColor-rest": {
@@ -7664,7 +8286,7 @@
       },
       "org.primer.overrides": {
         "dark": {
-          "$value": "#d1d7e0",
+          "$value": "#f0f6fc",
           "filePath": "src/tokens/component/button.json5",
           "isSource": true,
           "$type": "color"
@@ -7696,7 +8318,7 @@
     "name": "button-invisible-fgColor-rest",
     "attributes": {},
     "path": ["button", "invisible", "fgColor", "rest"],
-    "value": "#d1d7e0",
+    "value": "#f0f6fc",
     "type": "color"
   },
   "button-invisible-iconColor-disabled": {
@@ -12330,7 +12952,7 @@
         "scopes": ["fgColor"]
       },
       "org.primer.overrides": {
-        "dark": "#d1d7e0"
+        "dark": "#f0f6fc"
       }
     },
     "filePath": "src/tokens/component/codeMirror.json5",
@@ -12353,7 +12975,7 @@
     "name": "codeMirror-cursor-fgColor",
     "attributes": {},
     "path": ["codeMirror", "cursor", "fgColor"],
-    "value": "#d1d7e0",
+    "value": "#f0f6fc",
     "type": "color"
   },
   "codeMirror-fgColor": {
@@ -12365,7 +12987,7 @@
         "scopes": ["fgColor"]
       },
       "org.primer.overrides": {
-        "dark": "#d1d7e0"
+        "dark": "#f0f6fc"
       }
     },
     "filePath": "src/tokens/component/codeMirror.json5",
@@ -12388,7 +13010,7 @@
     "name": "codeMirror-fgColor",
     "attributes": {},
     "path": ["codeMirror", "fgColor"],
-    "value": "#d1d7e0",
+    "value": "#f0f6fc",
     "type": "color"
   },
   "codeMirror-gutterMarker-fgColor-default": {
@@ -12575,7 +13197,7 @@
         "scopes": ["fgColor"]
       },
       "org.primer.overrides": {
-        "dark": "#d1d7e0"
+        "dark": "#f0f6fc"
       }
     },
     "filePath": "src/tokens/component/codeMirror.json5",
@@ -12598,7 +13220,7 @@
     "name": "codeMirror-matchingBracket-fgColor",
     "attributes": {},
     "path": ["codeMirror", "matchingBracket", "fgColor"],
-    "value": "#d1d7e0",
+    "value": "#f0f6fc",
     "type": "color"
   },
   "codeMirror-selection-bgColor": {
@@ -17562,7 +18184,7 @@
         "scopes": ["fgColor"]
       },
       "org.primer.overrides": {
-        "dark": "#d1d7e0"
+        "dark": "#f0f6fc"
       }
     },
     "filePath": "src/tokens/functional/color/control.json5",
@@ -17585,7 +18207,7 @@
     "name": "control-fgColor-rest",
     "attributes": {},
     "path": ["control", "fgColor", "rest"],
-    "value": "#d1d7e0",
+    "value": "#f0f6fc",
     "type": "color"
   },
   "control-iconColor-rest": {
@@ -19325,19 +19947,19 @@
       "org.primer.overrides": {
         "dark": "#9198a1",
         "dark-high-contrast": {
-          "$value": "#d1d7e0",
+          "$value": "#f0f6fc",
           "filePath": "src/tokens/functional/color/control.json5",
           "isSource": true,
           "$type": "color"
         },
         "dark-tritanopia-high-contrast": {
-          "$value": "#d1d7e0",
+          "$value": "#f0f6fc",
           "filePath": "src/tokens/functional/color/control.json5",
           "isSource": true,
           "$type": "color"
         },
         "dark-protanopia-deuteranopia-high-contrast": {
-          "$value": "#d1d7e0",
+          "$value": "#f0f6fc",
           "filePath": "src/tokens/functional/color/control.json5",
           "isSource": true,
           "$type": "color"
@@ -20904,7 +21526,7 @@
     "name": "diffBlob-additionLine-fgColor",
     "attributes": {},
     "path": ["diffBlob", "additionLine", "fgColor"],
-    "value": "#d1d7e0",
+    "value": "#f0f6fc",
     "type": "color"
   },
   "diffBlob-additionNum-bgColor": {
@@ -21046,7 +21668,7 @@
     "name": "diffBlob-additionNum-fgColor",
     "attributes": {},
     "path": ["diffBlob", "additionNum", "fgColor"],
-    "value": "#d1d7e0",
+    "value": "#f0f6fc",
     "type": "color"
   },
   "diffBlob-additionWord-bgColor": {
@@ -21178,7 +21800,7 @@
     "name": "diffBlob-additionWord-fgColor",
     "attributes": {},
     "path": ["diffBlob", "additionWord", "fgColor"],
-    "value": "#d1d7e0",
+    "value": "#f0f6fc",
     "type": "color"
   },
   "diffBlob-deletionLine-bgColor": {
@@ -21306,7 +21928,7 @@
     "name": "diffBlob-deletionLine-fgColor",
     "attributes": {},
     "path": ["diffBlob", "deletionLine", "fgColor"],
-    "value": "#d1d7e0",
+    "value": "#f0f6fc",
     "type": "color"
   },
   "diffBlob-deletionNum-bgColor": {
@@ -21416,7 +22038,7 @@
     "name": "diffBlob-deletionNum-fgColor",
     "attributes": {},
     "path": ["diffBlob", "deletionNum", "fgColor"],
-    "value": "#d1d7e0",
+    "value": "#f0f6fc",
     "type": "color"
   },
   "diffBlob-deletionWord-bgColor": {
@@ -21546,7 +22168,7 @@
     "name": "diffBlob-deletionWord-fgColor",
     "attributes": {},
     "path": ["diffBlob", "deletionWord", "fgColor"],
-    "value": "#d1d7e0",
+    "value": "#f0f6fc",
     "type": "color"
   },
   "diffBlob-emptyLine-bgColor": {
@@ -21616,12 +22238,12 @@
         "scopes": ["fgColor"]
       },
       "org.primer.overrides": {
-        "light-high-contrast": "#d1d7e0",
-        "light-tritanopia-high-contrast": "#d1d7e0",
-        "light-protanopia-deuteranopia-high-contrast": "#d1d7e0",
-        "dark-high-contrast": "#d1d7e0",
-        "dark-tritanopia-high-contrast": "#d1d7e0",
-        "dark-protanopia-deuteranopia-high-contrast": "#d1d7e0"
+        "light-high-contrast": "#f0f6fc",
+        "light-tritanopia-high-contrast": "#f0f6fc",
+        "light-protanopia-deuteranopia-high-contrast": "#f0f6fc",
+        "dark-high-contrast": "#f0f6fc",
+        "dark-tritanopia-high-contrast": "#f0f6fc",
+        "dark-protanopia-deuteranopia-high-contrast": "#f0f6fc"
       }
     },
     "filePath": "src/tokens/component/diffBlob.json5",
@@ -21867,10 +22489,10 @@
         "scopes": ["fgColor"]
       },
       "org.primer.overrides": {
-        "light-protanopia-deuteranopia": "#d1d7e0",
-        "light-tritanopia": "#d1d7e0",
-        "light-protanopia-deuteranopia-high-contrast": "#d1d7e0",
-        "light-tritanopia-high-contrast": "#d1d7e0"
+        "light-protanopia-deuteranopia": "#f0f6fc",
+        "light-tritanopia": "#f0f6fc",
+        "light-protanopia-deuteranopia-high-contrast": "#f0f6fc",
+        "light-tritanopia-high-contrast": "#f0f6fc"
       }
     },
     "filePath": "src/tokens/component/diffBlob.json5",
@@ -21925,7 +22547,7 @@
     "name": "diffBlob-hunkNum-fgColor-rest",
     "attributes": {},
     "path": ["diffBlob", "hunkNum", "fgColor", "rest"],
-    "value": "#d1d7e0",
+    "value": "#f0f6fc",
     "type": "color"
   },
   "display-auburn-bgColor-emphasis": {
@@ -36522,6 +37144,10 @@
         "light-high-contrast": "#255ab2",
         "light-tritanopia-high-contrast": "#255ab2",
         "light-protanopia-deuteranopia-high-contrast": "#255ab2"
+      },
+      "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."
       }
     },
     "filePath": "src/tokens/functional/color/fgColor.json5",
@@ -36529,6 +37155,7 @@
     "original": {
       "$value": "#478be6",
       "$type": "color",
+      "$description": "Accent text for links and interactive elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -36548,6 +37175,10 @@
           "light-high-contrast": "{base.color.blue.6}",
           "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."
         }
       },
       "key": "{fgColor.accent}"
@@ -36556,7 +37187,8 @@
     "attributes": {},
     "path": ["fgColor", "accent"],
     "value": "#478be6",
-    "type": "color"
+    "type": "color",
+    "description": "Accent text for links and interactive elements"
   },
   "fgColor-attention": {
     "key": "{fgColor.attention}",
@@ -36575,6 +37207,10 @@
         "light-protanopia-deuteranopia-high-contrast": "#805400",
         "light-tritanopia-high-contrast": "#805400",
         "dark-dimmed-high-contrast": "#eac55f"
+      },
+      "org.primer.llm": {
+        "usage": ["attention-text", "warning-text", "caution-text"],
+        "rules": "Use for warning and caution text. Pair with bgColor.attention.muted for backgrounds."
       }
     },
     "filePath": "src/tokens/functional/color/fgColor.json5",
@@ -36582,6 +37218,7 @@
     "original": {
       "$value": "{base.color.yellow.3}",
       "$type": "color",
+      "$description": "Attention text for warnings and caution states",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -36597,6 +37234,10 @@
           "light-protanopia-deuteranopia-high-contrast": "{base.color.yellow.6}",
           "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."
         }
       },
       "key": "{fgColor.attention}"
@@ -36605,7 +37246,8 @@
     "attributes": {},
     "path": ["fgColor", "attention"],
     "value": "#c69026",
-    "type": "color"
+    "type": "color",
+    "description": "Attention text for warnings and caution states"
   },
   "fgColor-black": {
     "key": "{fgColor.black}",
@@ -36617,6 +37259,10 @@
       },
       "org.primer.overrides": {
         "dark": "#010409"
+      },
+      "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."
       }
     },
     "filePath": "src/tokens/functional/color/fgColor.json5",
@@ -36624,6 +37270,7 @@
     "original": {
       "$value": "{base.color.neutral.0}",
       "$type": "color",
+      "$description": "Pure black text",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -36632,6 +37279,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."
         }
       },
       "key": "{fgColor.black}"
@@ -36640,7 +37291,8 @@
     "attributes": {},
     "path": ["fgColor", "black"],
     "value": "#010409",
-    "type": "color"
+    "type": "color",
+    "description": "Pure black text"
   },
   "fgColor-closed": {
     "key": "{fgColor.closed}",
@@ -36662,6 +37314,10 @@
         "dark-tritanopia-high-contrast": "#9198a1",
         "light-tritanopia": "#9198a1",
         "light-tritanopia-high-contrast": "#9198a1"
+      },
+      "org.primer.llm": {
+        "usage": ["closed-text", "closed-issue", "closed-pr"],
+        "rules": "Use for closed/declined status text. Specifically for GitHub issues and PRs."
       }
     },
     "filePath": "src/tokens/functional/color/fgColor.json5",
@@ -36669,6 +37325,7 @@
     "original": {
       "$value": "{fgColor.danger}",
       "$type": "color",
+      "$description": "Text color for closed state indicators (issues, PRs)",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -36687,6 +37344,10 @@
           "dark-tritanopia-high-contrast": "{fgColor.muted}",
           "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."
         }
       },
       "key": "{fgColor.closed}"
@@ -36695,7 +37356,8 @@
     "attributes": {},
     "path": ["fgColor", "closed"],
     "value": "#e5534b",
-    "type": "color"
+    "type": "color",
+    "description": "Text color for closed state indicators (issues, PRs)"
   },
   "fgColor-danger": {
     "key": "{fgColor.danger}",
@@ -36719,6 +37381,10 @@
         "dark-tritanopia-high-contrast": "#f47067",
         "light-high-contrast": "#ad2e2c",
         "light-tritanopia-high-contrast": "#ad2e2c"
+      },
+      "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."
       }
     },
     "filePath": "src/tokens/functional/color/fgColor.json5",
@@ -36726,6 +37392,7 @@
     "original": {
       "$value": "{base.color.red.4}",
       "$type": "color",
+      "$description": "Danger text for errors and destructive actions",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -36746,6 +37413,10 @@
           "dark-tritanopia-high-contrast": "{base.color.red.3}",
           "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."
         }
       },
       "key": "{fgColor.danger}"
@@ -36754,7 +37425,8 @@
     "attributes": {},
     "path": ["fgColor", "danger"],
     "value": "#e5534b",
-    "type": "color"
+    "type": "color",
+    "description": "Danger text for errors and destructive actions"
   },
   "fgColor-default": {
     "key": "{fgColor.default}",
@@ -36772,15 +37444,20 @@
         "dark-high-contrast": "#cdd9e5",
         "dark-tritanopia-high-contrast": "#cdd9e5",
         "dark-protanopia-deuteranopia-high-contrast": "#cdd9e5",
-        "dark-dimmed": "#d1d7e0",
+        "dark-dimmed": "#f0f6fc",
         "dark-dimmed-high-contrast": "#f0f6fc"
+      },
+      "org.primer.llm": {
+        "usage": ["default-text", "heading", "body-text"],
+        "rules": "RECOMMENDED default for all text. Use for headings, body text, and primary labels."
       }
     },
     "filePath": "src/tokens/functional/color/fgColor.json5",
     "isSource": true,
     "original": {
-      "$value": "{base.color.neutral.11}",
+      "$value": "{base.color.neutral.12}",
       "$type": "color",
+      "$description": "Default text color for primary content and headings",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -36795,8 +37472,12 @@
           "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."
         }
       },
       "key": "{fgColor.default}"
@@ -36804,8 +37485,9 @@
     "name": "fgColor-default",
     "attributes": {},
     "path": ["fgColor", "default"],
-    "value": "#d1d7e0",
-    "type": "color"
+    "value": "#f0f6fc",
+    "type": "color",
+    "description": "Default text color for primary content and headings"
   },
   "fgColor-disabled": {
     "key": "{fgColor.disabled}",
@@ -36830,6 +37512,10 @@
         "dark-high-contrast": "#656c76",
         "dark-tritanopia-high-contrast": "#656c76",
         "dark-protanopia-deuteranopia-high-contrast": "#656c76"
+      },
+      "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."
       }
     },
     "filePath": "src/tokens/functional/color/fgColor.json5",
@@ -36837,6 +37523,7 @@
     "original": {
       "$value": "{base.color.neutral.8}",
       "$type": "color",
+      "$description": "Text color for disabled interactive elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -36858,6 +37545,10 @@
           "dark-high-contrast": "{base.color.neutral.8}",
           "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."
         }
       },
       "key": "{fgColor.disabled}"
@@ -36866,7 +37557,8 @@
     "attributes": {},
     "path": ["fgColor", "disabled"],
     "value": "#656c76",
-    "type": "color"
+    "type": "color",
+    "description": "Text color for disabled interactive elements"
   },
   "fgColor-done": {
     "key": "{fgColor.done}",
@@ -36888,6 +37580,10 @@
         "light-high-contrast": "#6b44bc",
         "light-protanopia-deuteranopia-high-contrast": "#6b44bc",
         "light-tritanopia-high-contrast": "#6b44bc"
+      },
+      "org.primer.llm": {
+        "usage": ["done-text", "merged", "completed"],
+        "rules": "Use for completed/done status text. Conveys finished or merged state."
       }
     },
     "filePath": "src/tokens/functional/color/fgColor.json5",
@@ -36895,6 +37591,7 @@
     "original": {
       "$value": "{base.color.purple.4}",
       "$type": "color",
+      "$description": "Text color for completed/done state indicators",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -36913,6 +37610,10 @@
           "light-high-contrast": "{base.color.purple.6}",
           "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."
         }
       },
       "key": "{fgColor.done}"
@@ -36921,7 +37622,8 @@
     "attributes": {},
     "path": ["fgColor", "done"],
     "value": "#986ee2",
-    "type": "color"
+    "type": "color",
+    "description": "Text color for completed/done state indicators"
   },
   "fgColor-draft": {
     "key": "{fgColor.draft}",
@@ -36933,6 +37635,10 @@
         "codeSyntax": {
           "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."
       }
     },
     "filePath": "src/tokens/functional/color/fgColor.json5",
@@ -36940,6 +37646,7 @@
     "original": {
       "$value": "{fgColor.neutral}",
       "$type": "color",
+      "$description": "Text color for draft state indicators",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -36948,6 +37655,10 @@
           "codeSyntax": {
             "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."
         }
       },
       "key": "{fgColor.draft}"
@@ -36956,7 +37667,8 @@
     "attributes": {},
     "path": ["fgColor", "draft"],
     "value": "#9198a1",
-    "type": "color"
+    "type": "color",
+    "description": "Text color for draft state indicators"
   },
   "fgColor-link": {
     "key": "{fgColor.link}",
@@ -36968,6 +37680,10 @@
         "codeSyntax": {
           "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."
       }
     },
     "filePath": "src/tokens/functional/color/fgColor.json5",
@@ -36975,6 +37691,7 @@
     "original": {
       "$value": "{fgColor.accent}",
       "$type": "color",
+      "$description": "Text color for hyperlinks",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -36983,6 +37700,10 @@
           "codeSyntax": {
             "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."
         }
       },
       "key": "{fgColor.link}"
@@ -36991,7 +37712,8 @@
     "attributes": {},
     "path": ["fgColor", "link"],
     "value": "#478be6",
-    "type": "color"
+    "type": "color",
+    "description": "Text color for hyperlinks"
   },
   "fgColor-muted": {
     "key": "{fgColor.muted}",
@@ -37012,6 +37734,10 @@
         "dark-dimmed-high-contrast": "#b7bdc8",
         "dark-tritanopia-high-contrast": "#b7bdc8",
         "dark-protanopia-deuteranopia-high-contrast": "#b7bdc8"
+      },
+      "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."
       }
     },
     "filePath": "src/tokens/functional/color/fgColor.json5",
@@ -37019,6 +37745,7 @@
     "original": {
       "$value": "{base.color.neutral.9}",
       "$type": "color",
+      "$description": "Muted text for secondary content and less important information",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -37036,6 +37763,10 @@
           "dark-dimmed-high-contrast": "{base.color.neutral.10}",
           "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."
         }
       },
       "key": "{fgColor.muted}"
@@ -37044,7 +37775,8 @@
     "attributes": {},
     "path": ["fgColor", "muted"],
     "value": "#9198a1",
-    "type": "color"
+    "type": "color",
+    "description": "Muted text for secondary content and less important information"
   },
   "fgColor-neutral": {
     "key": "{fgColor.neutral}",
@@ -37062,6 +37794,10 @@
         "dark-dimmed-high-contrast": "#d1d7e0",
         "dark-tritanopia-high-contrast": "#d1d7e0",
         "dark-protanopia-deuteranopia-high-contrast": "#d1d7e0"
+      },
+      "org.primer.llm": {
+        "usage": ["neutral-icon", "neutral-text"],
+        "rules": "Use for neutral semantic elements. Prefer fgColor.muted for secondary text."
       }
     },
     "filePath": "src/tokens/functional/color/fgColor.json5",
@@ -37069,6 +37805,7 @@
     "original": {
       "$value": "{base.color.neutral.9}",
       "$type": "color",
+      "$description": "Neutral semantic text for icons and secondary elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -37083,6 +37820,10 @@
           "dark-dimmed-high-contrast": "{base.color.neutral.11}",
           "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."
         }
       },
       "key": "{fgColor.neutral}"
@@ -37091,7 +37832,8 @@
     "attributes": {},
     "path": ["fgColor", "neutral"],
     "value": "#9198a1",
-    "type": "color"
+    "type": "color",
+    "description": "Neutral semantic text for icons and secondary elements"
   },
   "fgColor-onEmphasis": {
     "key": "{fgColor.onEmphasis}",
@@ -37108,6 +37850,10 @@
         "dark": "#cdd9e5",
         "dark-dimmed": "#f0f6fc",
         "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."
       }
     },
     "filePath": "src/tokens/functional/color/fgColor.json5",
@@ -37115,6 +37861,7 @@
     "original": {
       "$value": "{base.color.neutral.12}",
       "$type": "color",
+      "$description": "Text color for use on emphasis backgrounds",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -37128,6 +37875,10 @@
           "dark": "{base.color.neutral.13}",
           "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."
         }
       },
       "key": "{fgColor.onEmphasis}"
@@ -37136,7 +37887,8 @@
     "attributes": {},
     "path": ["fgColor", "onEmphasis"],
     "value": "#f0f6fc",
-    "type": "color"
+    "type": "color",
+    "description": "Text color for use on emphasis backgrounds"
   },
   "fgColor-onInverse": {
     "key": "{fgColor.onInverse}",
@@ -37145,6 +37897,10 @@
         "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."
       }
     },
     "filePath": "src/tokens/functional/color/fgColor.json5",
@@ -37152,11 +37908,16 @@
     "original": {
       "$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."
         }
       },
       "key": "{fgColor.onInverse}"
@@ -37165,7 +37926,8 @@
     "attributes": {},
     "path": ["fgColor", "onInverse"],
     "value": "#010409",
-    "type": "color"
+    "type": "color",
+    "description": "Text color for use on inverse backgrounds"
   },
   "fgColor-open": {
     "key": "{fgColor.open}",
@@ -37187,6 +37949,10 @@
         "dark-tritanopia-high-contrast": "#ff938a",
         "light-tritanopia": "#c93c37",
         "light-tritanopia-high-contrast": "#ad2e2c"
+      },
+      "org.primer.llm": {
+        "usage": ["open-text", "open-issue", "open-pr"],
+        "rules": "Use for open/active status text. Specifically for GitHub issues and PRs."
       }
     },
     "filePath": "src/tokens/functional/color/fgColor.json5",
@@ -37194,6 +37960,7 @@
     "original": {
       "$value": "{fgColor.success}",
       "$type": "color",
+      "$description": "Text color for open state indicators (issues, PRs)",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -37212,6 +37979,10 @@
           "dark-tritanopia-high-contrast": "{base.color.red.2}",
           "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."
         }
       },
       "key": "{fgColor.open}"
@@ -37220,7 +37991,8 @@
     "attributes": {},
     "path": ["fgColor", "open"],
     "value": "#57ab5a",
-    "type": "color"
+    "type": "color",
+    "description": "Text color for open state indicators (issues, PRs)"
   },
   "fgColor-severe": {
     "key": "{fgColor.severe}",
@@ -37244,6 +38016,10 @@
         "light-tritanopia": "#c93c37",
         "light-tritanopia-high-contrast": "#ad2e2c",
         "light-protanopia-deuteranopia-high-contrast": "#94471b"
+      },
+      "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."
       }
     },
     "filePath": "src/tokens/functional/color/fgColor.json5",
@@ -37251,6 +38027,7 @@
     "original": {
       "$value": "{base.color.orange.4}",
       "$type": "color",
+      "$description": "Severe text for high-priority warnings",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -37271,6 +38048,10 @@
           "light-tritanopia": "{base.color.red.5}",
           "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."
         }
       },
       "key": "{fgColor.severe}"
@@ -37279,7 +38060,8 @@
     "attributes": {},
     "path": ["fgColor", "severe"],
     "value": "#cc6b2c",
-    "type": "color"
+    "type": "color",
+    "description": "Severe text for high-priority warnings"
   },
   "fgColor-sponsors": {
     "key": "{fgColor.sponsors}",
@@ -37301,6 +38083,10 @@
         "light-high-contrast": "#983b6e",
         "light-protanopia-deuteranopia-high-contrast": "#983b6e",
         "light-tritanopia-high-contrast": "#983b6e"
+      },
+      "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."
       }
     },
     "filePath": "src/tokens/functional/color/fgColor.json5",
@@ -37308,6 +38094,7 @@
     "original": {
       "$value": "{base.color.pink.4}",
       "$type": "color",
+      "$description": "Text color for GitHub Sponsors content",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -37326,6 +38113,10 @@
           "light-high-contrast": "{base.color.pink.6}",
           "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."
         }
       },
       "key": "{fgColor.sponsors}"
@@ -37334,7 +38125,8 @@
     "attributes": {},
     "path": ["fgColor", "sponsors"],
     "value": "#c96198",
-    "type": "color"
+    "type": "color",
+    "description": "Text color for GitHub Sponsors content"
   },
   "fgColor-success": {
     "key": "{fgColor.success}",
@@ -37360,6 +38152,10 @@
         "dark-tritanopia-high-contrast": "#6cb6ff",
         "light-tritanopia": "#316dca",
         "light-tritanopia-high-contrast": "#255ab2"
+      },
+      "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."
       }
     },
     "filePath": "src/tokens/functional/color/fgColor.json5",
@@ -37367,6 +38163,7 @@
     "original": {
       "$value": "{base.color.green.3}",
       "$type": "color",
+      "$description": "Success text for positive feedback and completed states",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -37389,6 +38186,10 @@
           "dark-tritanopia-high-contrast": "{base.color.blue.2}",
           "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."
         }
       },
       "key": "{fgColor.success}"
@@ -37397,7 +38198,8 @@
     "attributes": {},
     "path": ["fgColor", "success"],
     "value": "#57ab5a",
-    "type": "color"
+    "type": "color",
+    "description": "Success text for positive feedback and completed states"
   },
   "fgColor-upsell": {
     "key": "{fgColor.upsell}",
@@ -37409,6 +38211,10 @@
         "codeSyntax": {
           "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."
       }
     },
     "filePath": "src/tokens/functional/color/fgColor.json5",
@@ -37416,6 +38222,7 @@
     "original": {
       "$value": "{fgColor.done}",
       "$type": "color",
+      "$description": "Text color for upsell and promotional content",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -37424,6 +38231,10 @@
           "codeSyntax": {
             "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."
         }
       },
       "key": "{fgColor.upsell}"
@@ -37432,7 +38243,8 @@
     "attributes": {},
     "path": ["fgColor", "upsell"],
     "value": "#986ee2",
-    "type": "color"
+    "type": "color",
+    "description": "Text color for upsell and promotional content"
   },
   "fgColor-white": {
     "key": "{fgColor.white}",
@@ -37444,6 +38256,10 @@
       },
       "org.primer.overrides": {
         "dark": "#cdd9e5"
+      },
+      "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."
       }
     },
     "filePath": "src/tokens/functional/color/fgColor.json5",
@@ -37451,6 +38267,7 @@
     "original": {
       "$value": "{base.color.neutral.13}",
       "$type": "color",
+      "$description": "Pure white text",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -37459,6 +38276,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."
         }
       },
       "key": "{fgColor.white}"
@@ -37467,10 +38288,17 @@
     "attributes": {},
     "path": ["fgColor", "white"],
     "value": "#cdd9e5",
-    "type": "color"
+    "type": "color",
+    "description": "Pure white text"
   },
   "focus-outline": {
     "key": "{focus.outline}",
+    "$extensions": {
+      "org.primer.llm": {
+        "usage": ["focus-ring", "keyboard-navigation", "accessibility-indicator"],
+        "rules": "Always ensure focus states are visible. Do not override with custom focus styles that reduce visibility. Use for interactive elements like buttons, links, and form controls."
+      }
+    },
     "filePath": "src/tokens/functional/border/border.json5",
     "isSource": true,
     "original": {
@@ -37480,13 +38308,21 @@
         "width": "2px"
       },
       "$type": "border",
+      "$description": "Focus ring outline for keyboard navigation and accessibility.",
+      "$extensions": {
+        "org.primer.llm": {
+          "usage": ["focus-ring", "keyboard-navigation", "accessibility-indicator"],
+          "rules": "Always ensure focus states are visible. Do not override with custom focus styles that reduce visibility. Use for interactive elements like buttons, links, and form controls."
+        }
+      },
       "key": "{focus.outline}"
     },
     "name": "focus-outline",
     "attributes": {},
     "path": ["focus", "outline"],
     "value": "2px solid #316dca",
-    "type": "border"
+    "type": "border",
+    "description": "Focus ring outline for keyboard navigation and accessibility."
   },
   "focus-outlineColor": {
     "key": "{focus.outlineColor}",
@@ -37495,6 +38331,10 @@
         "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."
       }
     },
     "filePath": "src/tokens/functional/color/focus.json5",
@@ -37502,11 +38342,16 @@
     "original": {
       "$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."
         }
       },
       "key": "{focus.outlineColor}"
@@ -37515,7 +38360,8 @@
     "attributes": {},
     "path": ["focus", "outlineColor"],
     "value": "#316dca",
-    "type": "color"
+    "type": "color",
+    "description": "Outline color for focus states on interactive elements"
   },
   "header-bgColor": {
     "key": "{header.bgColor}",
@@ -46576,6 +47422,10 @@
           "isSource": true,
           "$type": "color"
         }
+      },
+      "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.7,
@@ -46584,6 +47434,7 @@
     "original": {
       "$value": "{bgColor.accent.emphasis}",
       "$type": "color",
+      "$description": "Background color for text selection highlights",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -46598,6 +47449,10 @@
             "isSource": true,
             "$type": "color"
           }
+        },
+        "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.7,
@@ -46607,7 +47462,8 @@
     "attributes": {},
     "path": ["selection", "bgColor"],
     "value": "#316dcab3",
-    "type": "color"
+    "type": "color",
+    "description": "Background color for text selection highlights"
   },
   "shadow-floating-large": {
     "key": "{shadow.floating.large}",
@@ -46640,6 +47496,10 @@
           "isSource": true,
           "$type": "shadow"
         }
+      },
+      "org.primer.llm": {
+        "usage": ["modal", "dialog", "full-screen-overlay"],
+        "rules": "MUST use for modals and dialogs. Do NOT use for small floating elements."
       }
     },
     "filePath": "src/tokens/functional/shadow/shadow.json5",
@@ -46664,6 +47524,7 @@
         }
       ],
       "$type": "shadow",
+      "$description": "Large floating shadow for modals and dialogs",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -46693,6 +47554,10 @@
             "isSource": true,
             "$type": "shadow"
           }
+        },
+        "org.primer.llm": {
+          "usage": ["modal", "dialog", "full-screen-overlay"],
+          "rules": "MUST use for modals and dialogs. Do NOT use for small floating elements."
         }
       },
       "key": "{shadow.floating.large}"
@@ -46701,7 +47566,8 @@
     "attributes": {},
     "path": ["shadow", "floating", "large"],
     "value": "0px 0px 0px 1px #3d444d, 0px 24px 48px 0px #010409",
-    "type": "shadow"
+    "type": "shadow",
+    "description": "Large floating shadow for modals and dialogs"
   },
   "shadow-floating-legacy": {
     "key": "{shadow.floating.legacy}",
@@ -46731,6 +47597,10 @@
           "isSource": true,
           "$type": "shadow"
         }
+      },
+      "org.primer.llm": {
+        "usage": ["legacy-component", "backward-compatibility"],
+        "rules": "DEPRECATED: Use shadow-floating-small instead. Only use for maintaining backward compatibility with existing implementations."
       }
     },
     "filePath": "src/tokens/functional/shadow/shadow.json5",
@@ -46755,6 +47625,7 @@
         }
       ],
       "$type": "shadow",
+      "$description": "Legacy floating shadow for backward compatibility",
       "$extensions": {
         "org.primer.figma": {},
         "org.primer.overrides": {
@@ -46781,6 +47652,10 @@
             "isSource": true,
             "$type": "shadow"
           }
+        },
+        "org.primer.llm": {
+          "usage": ["legacy-component", "backward-compatibility"],
+          "rules": "DEPRECATED: Use shadow-floating-small instead. Only use for maintaining backward compatibility with existing implementations."
         }
       },
       "key": "{shadow.floating.legacy}"
@@ -46789,7 +47664,8 @@
     "attributes": {},
     "path": ["shadow", "floating", "legacy"],
     "value": "0px 6px 12px -3px #01040966, 0px 6px 18px 0px #01040966",
-    "type": "shadow"
+    "type": "shadow",
+    "description": "Legacy floating shadow for backward compatibility"
   },
   "shadow-floating-medium": {
     "key": "{shadow.floating.medium}",
@@ -46846,6 +47722,10 @@
           "isSource": true,
           "$type": "shadow"
         }
+      },
+      "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."
       }
     },
     "filePath": "src/tokens/functional/shadow/shadow.json5",
@@ -46894,6 +47774,7 @@
         }
       ],
       "$type": "shadow",
+      "$description": "Medium floating shadow for popovers and action menus",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -46947,6 +47828,10 @@
             "isSource": true,
             "$type": "shadow"
           }
+        },
+        "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."
         }
       },
       "key": "{shadow.floating.medium}"
@@ -46955,7 +47840,8 @@
     "attributes": {},
     "path": ["shadow", "floating", "medium"],
     "value": "0px 0px 0px 1px #3d444d, 0px 8px 16px -4px #01040966, 0px 4px 32px -4px #01040966, 0px 24px 48px -12px #01040966, 0px 48px 96px -24px #01040966",
-    "type": "shadow"
+    "type": "shadow",
+    "description": "Medium floating shadow for popovers and action menus"
   },
   "shadow-floating-small": {
     "key": "{shadow.floating.small}",
@@ -46996,6 +47882,10 @@
           "isSource": true,
           "$type": "shadow"
         }
+      },
+      "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."
       }
     },
     "filePath": "src/tokens/functional/shadow/shadow.json5",
@@ -47028,6 +47918,7 @@
         }
       ],
       "$type": "shadow",
+      "$description": "Small floating shadow for dropdowns, tooltips, and small overlays",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -47065,6 +47956,10 @@
             "isSource": true,
             "$type": "shadow"
           }
+        },
+        "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."
         }
       },
       "key": "{shadow.floating.small}"
@@ -47073,7 +47968,8 @@
     "attributes": {},
     "path": ["shadow", "floating", "small"],
     "value": "0px 0px 0px 1px #3d444d, 0px 6px 12px -3px #01040966, 0px 6px 18px 0px #01040966",
-    "type": "shadow"
+    "type": "shadow",
+    "description": "Small floating shadow for dropdowns, tooltips, and small overlays"
   },
   "shadow-floating-xlarge": {
     "key": "{shadow.floating.xlarge}",
@@ -47106,6 +48002,10 @@
           "isSource": true,
           "$type": "shadow"
         }
+      },
+      "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."
       }
     },
     "filePath": "src/tokens/functional/shadow/shadow.json5",
@@ -47130,6 +48030,7 @@
         }
       ],
       "$type": "shadow",
+      "$description": "Extra large floating shadow for full-screen overlays and sheets",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -47159,6 +48060,10 @@
             "isSource": true,
             "$type": "shadow"
           }
+        },
+        "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."
         }
       },
       "key": "{shadow.floating.xlarge}"
@@ -47167,7 +48072,8 @@
     "attributes": {},
     "path": ["shadow", "floating", "xlarge"],
     "value": "0px 0px 0px 1px #3d444d, 0px 32px 64px 0px #010409",
-    "type": "shadow"
+    "type": "shadow",
+    "description": "Extra large floating shadow for full-screen overlays and sheets"
   },
   "shadow-inset": {
     "key": "{shadow.inset}",
@@ -47191,6 +48097,10 @@
           "isSource": true,
           "$type": "shadow"
         }
+      },
+      "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."
       }
     },
     "filePath": "src/tokens/functional/shadow/shadow.json5",
@@ -47206,6 +48116,7 @@
         "inset": true
       },
       "$type": "shadow",
+      "$description": "Inset shadow for recessed elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -47226,6 +48137,10 @@
             "isSource": true,
             "$type": "shadow"
           }
+        },
+        "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."
         }
       },
       "key": "{shadow.inset}"
@@ -47234,7 +48149,8 @@
     "attributes": {},
     "path": ["shadow", "inset"],
     "value": "inset 0px 1px 0px 0px #0104093d",
-    "type": "shadow"
+    "type": "shadow",
+    "description": "Inset shadow for recessed elements"
   },
   "shadow-resting-medium": {
     "key": "{shadow.resting.medium}",
@@ -47267,6 +48183,10 @@
           "isSource": true,
           "$type": "shadow"
         }
+      },
+      "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."
       }
     },
     "filePath": "src/tokens/functional/shadow/shadow.json5",
@@ -47291,6 +48211,7 @@
         }
       ],
       "$type": "shadow",
+      "$description": "Medium resting shadow for cards and elevated surfaces",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -47320,6 +48241,10 @@
             "isSource": true,
             "$type": "shadow"
           }
+        },
+        "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."
         }
       },
       "key": "{shadow.resting.medium}"
@@ -47328,7 +48253,8 @@
     "attributes": {},
     "path": ["shadow", "resting", "medium"],
     "value": "0px 1px 1px 0px #01040966, 0px 3px 6px 0px #010409cc",
-    "type": "shadow"
+    "type": "shadow",
+    "description": "Medium resting shadow for cards and elevated surfaces"
   },
   "shadow-resting-small": {
     "key": "{shadow.resting.small}",
@@ -47363,6 +48289,10 @@
           "isSource": true,
           "$type": "shadow"
         }
+      },
+      "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."
       }
     },
     "filePath": "src/tokens/functional/shadow/shadow.json5",
@@ -47389,6 +48319,7 @@
         }
       ],
       "$type": "shadow",
+      "$description": "Small resting shadow for buttons and interactive elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -47420,6 +48351,10 @@
             "isSource": true,
             "$type": "shadow"
           }
+        },
+        "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."
         }
       },
       "key": "{shadow.resting.small}"
@@ -47428,7 +48363,8 @@
     "attributes": {},
     "path": ["shadow", "resting", "small"],
     "value": "0px 1px 1px 0px #01040999, 0px 1px 3px 0px #01040999",
-    "type": "shadow"
+    "type": "shadow",
+    "description": "Small resting shadow for buttons and interactive elements"
   },
   "shadow-resting-xsmall": {
     "key": "{shadow.resting.xsmall}",
@@ -47452,6 +48388,10 @@
           "isSource": true,
           "$type": "shadow"
         }
+      },
+      "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."
       }
     },
     "filePath": "src/tokens/functional/shadow/shadow.json5",
@@ -47467,6 +48407,7 @@
         "inset": false
       },
       "$type": "shadow",
+      "$description": "Extra small resting shadow for minimal elevation",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -47487,6 +48428,10 @@
             "isSource": true,
             "$type": "shadow"
           }
+        },
+        "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."
         }
       },
       "key": "{shadow.resting.xsmall}"
@@ -47495,7 +48440,8 @@
     "attributes": {},
     "path": ["shadow", "resting", "xsmall"],
     "value": "0px 1px 1px 0px #010409cc",
-    "type": "shadow"
+    "type": "shadow",
+    "description": "Extra small resting shadow for minimal elevation"
   },
   "sideNav-bgColor-selected": {
     "key": "{sideNav.bgColor.selected}",