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

package/dist/styleLint/functional/themes/light.json

@@ -295,6 +295,7 @@
     "key": "{bgColor.accent.emphasis}",
     "$value": "#0969da",
     "$type": "color",
+    "$description": "Strong accent background for active states and focused states",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -310,6 +311,10 @@
         "dark-dimmed-high-contrast": "#033d8b",
         "dark-tritanopia-high-contrast": "#002155",
         "dark-protanopia-deuteranopia-high-contrast": "#002155"
+      },
+      "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 +322,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 +338,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}"
@@ -344,6 +354,7 @@
     "key": "{bgColor.accent.muted}",
     "$value": "#ddf4ff",
     "$type": "color",
+    "$description": "Subtle accent background for informational or selected elements",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -361,6 +372,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",
@@ -368,6 +383,7 @@
     "original": {
       "$value": "{base.color.blue.0}",
       "$type": "color",
+      "$description": "Subtle accent background for informational or selected elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -385,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."
         }
       },
       "key": "{bgColor.accent.muted}"
@@ -397,6 +417,7 @@
     "key": "{bgColor.attention.emphasis}",
     "$value": "#9a6700",
     "$type": "color",
+    "$description": "Strong attention background for prominent warnings",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -411,6 +432,10 @@
         "dark-dimmed-high-contrast": "#633c01",
         "dark-protanopia-deuteranopia-high-contrast": "#3b2300",
         "dark-tritanopia-high-contrast": "#3b2300"
+      },
+      "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",
@@ -418,6 +443,7 @@
     "original": {
       "$value": "{base.color.yellow.5}",
       "$type": "color",
+      "$description": "Strong attention background for prominent warnings",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -432,6 +458,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}"
@@ -444,6 +474,7 @@
     "key": "{bgColor.attention.muted}",
     "$value": "#fff8c5",
     "$type": "color",
+    "$description": "Subtle attention background for warnings and caution states",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -461,6 +492,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",
@@ -468,6 +503,7 @@
     "original": {
       "$value": "{base.color.yellow.0}",
       "$type": "color",
+      "$description": "Subtle attention background for warnings and caution states",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -485,6 +521,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."
         }
       },
       "key": "{bgColor.attention.muted}"
@@ -497,6 +537,7 @@
     "key": "{bgColor.black}",
     "$value": "#1f2328",
     "$type": "color",
+    "$description": "Pure black background",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -505,6 +546,10 @@
       },
       "org.primer.overrides": {
         "dark": "#ffffff"
+      },
+      "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",
@@ -512,6 +557,7 @@
     "original": {
       "$value": "{base.color.neutral.13}",
       "$type": "color",
+      "$description": "Pure black background",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -520,6 +566,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,6 +582,7 @@
     "key": "{bgColor.closed.emphasis}",
     "$value": "#cf222e",
     "$type": "color",
+    "$description": "Strong background for closed state badges and labels",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -550,6 +601,10 @@
         "light-protanopia-deuteranopia-high-contrast": "#59636e",
         "dark-protanopia-deuteranopia": "#59636e",
         "dark-protanopia-deuteranopia-high-contrast": "#59636e"
+      },
+      "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",
@@ -557,6 +612,7 @@
     "original": {
       "$value": "{bgColor.danger.emphasis}",
       "$type": "color",
+      "$description": "Strong background for closed state badges and labels",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -575,6 +631,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,6 +647,7 @@
     "key": "{bgColor.closed.muted}",
     "$value": "#ffebe9",
     "$type": "color",
+    "$description": "Subtle background for closed state indicators (issues, PRs)",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -622,6 +683,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",
@@ -629,6 +694,7 @@
     "original": {
       "$value": "{bgColor.danger.muted}",
       "$type": "color",
+      "$description": "Subtle background for closed state indicators (issues, PRs)",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -664,6 +730,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,6 +746,7 @@
     "key": "{bgColor.danger.emphasis}",
     "$value": "#cf222e",
     "$type": "color",
+    "$description": "Emphasized danger background for critical errors and delete confirmations",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -693,6 +764,10 @@
         "dark-high-contrast": "#4c0014",
         "dark-dimmed-high-contrast": "#82071e",
         "dark-tritanopia-high-contrast": "#4c0014"
+      },
+      "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",
@@ -700,6 +775,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",
@@ -717,6 +793,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,6 +809,7 @@
     "key": "{bgColor.danger.muted}",
     "$value": "#ffebe9",
     "$type": "color",
+    "$description": "Muted danger background for error states and destructive action contexts",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -755,6 +836,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",
@@ -762,6 +847,7 @@
     "original": {
       "$value": "{base.color.red.0}",
       "$type": "color",
+      "$description": "Muted danger background for error states and destructive action contexts",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -788,6 +874,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."
         }
       },
       "key": "{bgColor.danger.muted}"
@@ -800,6 +890,7 @@
     "key": "{bgColor.default}",
     "$value": "#ffffff",
     "$type": "color",
+    "$description": "Default background color for pages and main content areas",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -816,6 +907,10 @@
         "dark-high-contrast": "#ffffff",
         "dark-tritanopia-high-contrast": "#ffffff",
         "dark-protanopia-deuteranopia-high-contrast": "#ffffff"
+      },
+      "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",
@@ -823,6 +918,7 @@
     "original": {
       "$value": "{base.color.neutral.0}",
       "$type": "color",
+      "$description": "Default background color for pages and main content areas",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -839,6 +935,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}"
@@ -851,6 +951,7 @@
     "key": "{bgColor.disabled}",
     "$value": "#eff2f5",
     "$type": "color",
+    "$description": "Background for disabled interactive elements",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -867,6 +968,10 @@
         "dark-high-contrast": "#e0e6eb",
         "dark-tritanopia-high-contrast": "#e0e6eb",
         "dark-protanopia-deuteranopia-high-contrast": "#e0e6eb"
+      },
+      "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",
@@ -874,6 +979,7 @@
     "original": {
       "$value": "{base.color.neutral.2}",
       "$type": "color",
+      "$description": "Background for disabled interactive elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -890,6 +996,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}"
@@ -902,6 +1012,7 @@
     "key": "{bgColor.done.emphasis}",
     "$value": "#8250df",
     "$type": "color",
+    "$description": "Strong background for completed/done state badges and labels",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -916,6 +1027,10 @@
         "dark-dimmed-high-contrast": "#512a97",
         "dark-tritanopia-high-contrast": "#2e1461",
         "dark-protanopia-deuteranopia-high-contrast": "#2e1461"
+      },
+      "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",
@@ -923,6 +1038,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",
@@ -937,6 +1053,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}"
@@ -949,6 +1069,7 @@
     "key": "{bgColor.done.muted}",
     "$value": "#fbefff",
     "$type": "color",
+    "$description": "Subtle background for completed/done state indicators",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -966,6 +1087,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",
@@ -973,6 +1098,7 @@
     "original": {
       "$value": "{base.color.purple.0}",
       "$type": "color",
+      "$description": "Subtle background for completed/done state indicators",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -990,6 +1116,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."
         }
       },
       "key": "{bgColor.done.muted}"
@@ -1002,6 +1132,7 @@
     "key": "{bgColor.draft.emphasis}",
     "$value": "#59636e",
     "$type": "color",
+    "$description": "Strong background for draft state badges and labels",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -1010,6 +1141,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",
@@ -1017,6 +1152,7 @@
     "original": {
       "$value": "{bgColor.neutral.emphasis}",
       "$type": "color",
+      "$description": "Strong background for draft state badges and labels",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -1025,6 +1161,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}"
@@ -1037,6 +1177,7 @@
     "key": "{bgColor.draft.muted}",
     "$value": "#818b981f",
     "$type": "color",
+    "$description": "Subtle background for draft state indicators",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -1072,6 +1213,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",
@@ -1079,6 +1224,7 @@
     "original": {
       "$value": "{bgColor.neutral.muted}",
       "$type": "color",
+      "$description": "Subtle background for draft state indicators",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -1114,6 +1260,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}"
@@ -1126,6 +1276,7 @@
     "key": "{bgColor.emphasis}",
     "$value": "#25292e",
     "$type": "color",
+    "$description": "High-emphasis dark background for strong visual contrast",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -1137,6 +1288,10 @@
       },
       "org.primer.overrides": {
         "dark": "#c8d1da"
+      },
+      "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",
@@ -1144,6 +1299,7 @@
     "original": {
       "$value": "{base.color.neutral.12}",
       "$type": "color",
+      "$description": "High-emphasis dark background for strong visual contrast",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -1155,6 +1311,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}"
@@ -1167,6 +1327,7 @@
     "key": "{bgColor.inset}",
     "$value": "#f6f8fa",
     "$type": "color",
+    "$description": "Inset background for recessed content areas like wells or sunken panels",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -1183,6 +1344,10 @@
         "light-high-contrast": "#eff2f5",
         "light-tritanopia-high-contrast": "#eff2f5",
         "light-protanopia-deuteranopia-high-contrast": "#eff2f5"
+      },
+      "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",
@@ -1190,6 +1355,7 @@
     "original": {
       "$value": "{bgColor.muted}",
       "$type": "color",
+      "$description": "Inset background for recessed content areas like wells or sunken panels",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -1206,6 +1372,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}"
@@ -1218,6 +1388,7 @@
     "key": "{bgColor.inverse}",
     "$value": "#25292e",
     "$type": "color",
+    "$description": "Inverse background that flips between light and dark modes",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -1226,6 +1397,10 @@
       },
       "org.primer.overrides": {
         "dark": "#1f2328"
+      },
+      "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",
@@ -1233,6 +1408,7 @@
     "original": {
       "$value": "{base.color.neutral.12}",
       "$type": "color",
+      "$description": "Inverse background that flips between light and dark modes",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -1241,6 +1417,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}"
@@ -1253,6 +1433,7 @@
     "key": "{bgColor.muted}",
     "$value": "#f6f8fa",
     "$type": "color",
+    "$description": "Muted background for secondary content areas and subtle grouping",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -1272,6 +1453,10 @@
         "dark-high-contrast": "#eff2f5",
         "dark-tritanopia-high-contrast": "#eff2f5",
         "dark-protanopia-deuteranopia-high-contrast": "#eff2f5"
+      },
+      "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",
@@ -1279,6 +1464,7 @@
     "original": {
       "$value": "{base.color.neutral.1}",
       "$type": "color",
+      "$description": "Muted background for secondary content areas and subtle grouping",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -1298,6 +1484,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}"
@@ -1310,6 +1500,7 @@
     "key": "{bgColor.neutral.emphasis}",
     "$value": "#59636e",
     "$type": "color",
+    "$description": "Strong neutral background for prominent neutral elements",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -1326,6 +1517,10 @@
         "dark-high-contrast": "#c8d1da",
         "dark-tritanopia-high-contrast": "#c8d1da",
         "dark-protanopia-deuteranopia-high-contrast": "#c8d1da"
+      },
+      "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",
@@ -1333,6 +1528,7 @@
     "original": {
       "$value": "{base.color.neutral.9}",
       "$type": "color",
+      "$description": "Strong neutral background for prominent neutral elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -1349,6 +1545,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}"
@@ -1361,6 +1561,7 @@
     "key": "{bgColor.neutral.muted}",
     "$value": "#818b981f",
     "$type": "color",
+    "$description": "Subtle neutral background for tags, labels, and secondary UI elements",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -1388,6 +1589,10 @@
         "dark-high-contrast": "#e6eaef",
         "dark-tritanopia-high-contrast": "#e6eaef",
         "dark-protanopia-deuteranopia-high-contrast": "#e6eaef"
+      },
+      "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",
@@ -1396,6 +1601,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",
@@ -1423,6 +1629,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.12,
@@ -1436,6 +1646,7 @@
     "key": "{bgColor.open.emphasis}",
     "$value": "#1f883d",
     "$type": "color",
+    "$description": "Strong background for open state badges and labels",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -1454,6 +1665,10 @@
         "light-protanopia-deuteranopia-high-contrast": "#bc4c00",
         "dark-protanopia-deuteranopia": "#bc4c00",
         "dark-protanopia-deuteranopia-high-contrast": "#471700"
+      },
+      "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",
@@ -1461,6 +1676,7 @@
     "original": {
       "$value": "{bgColor.success.emphasis}",
       "$type": "color",
+      "$description": "Strong background for open state badges and labels",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -1479,6 +1695,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}"
@@ -1491,6 +1711,7 @@
     "key": "{bgColor.open.muted}",
     "$value": "#dafbe1",
     "$type": "color",
+    "$description": "Subtle background for open state indicators (issues, PRs)",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -1533,6 +1754,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",
@@ -1540,6 +1765,7 @@
     "original": {
       "$value": "{bgColor.success.muted}",
       "$type": "color",
+      "$description": "Subtle background for open state indicators (issues, PRs)",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -1582,6 +1808,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}"
@@ -1594,6 +1824,7 @@
     "key": "{bgColor.severe.emphasis}",
     "$value": "#bc4c00",
     "$type": "color",
+    "$description": "Strong severe background for prominent high-priority warnings",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -1611,6 +1842,10 @@
         "dark-high-contrast": "#471700",
         "dark-dimmed-high-contrast": "#762c00",
         "dark-protanopia-deuteranopia-high-contrast": "#471700"
+      },
+      "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",
@@ -1618,6 +1853,7 @@
     "original": {
       "$value": "{base.color.orange.5}",
       "$type": "color",
+      "$description": "Strong severe background for prominent high-priority warnings",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -1635,6 +1871,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}"
@@ -1647,6 +1887,7 @@
     "key": "{bgColor.severe.muted}",
     "$value": "#fff1e5",
     "$type": "color",
+    "$description": "Subtle severe background for high-priority warnings",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -1673,6 +1914,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",
@@ -1680,6 +1925,7 @@
     "original": {
       "$value": "{base.color.orange.0}",
       "$type": "color",
+      "$description": "Subtle severe background for high-priority warnings",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -1706,6 +1952,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."
         }
       },
       "key": "{bgColor.severe.muted}"
@@ -1718,6 +1968,7 @@
     "key": "{bgColor.sponsors.emphasis}",
     "$value": "#bf3989",
     "$type": "color",
+    "$description": "Strong background for prominent GitHub Sponsors elements",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -1732,6 +1983,10 @@
         "dark-dimmed-high-contrast": "#772057",
         "dark-tritanopia-high-contrast": "#4d0336",
         "dark-protanopia-deuteranopia-high-contrast": "#4d0336"
+      },
+      "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",
@@ -1739,6 +1994,7 @@
     "original": {
       "$value": "{base.color.pink.5}",
       "$type": "color",
+      "$description": "Strong background for prominent GitHub Sponsors elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -1753,6 +2009,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}"
@@ -1765,6 +2025,7 @@
     "key": "{bgColor.sponsors.muted}",
     "$value": "#ffeff7",
     "$type": "color",
+    "$description": "Subtle background for GitHub Sponsors content",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -1789,6 +2050,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",
@@ -1796,6 +2061,7 @@
     "original": {
       "$value": "{base.color.pink.0}",
       "$type": "color",
+      "$description": "Subtle background for GitHub Sponsors content",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -1820,6 +2086,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."
         }
       },
       "key": "{bgColor.sponsors.muted}"
@@ -1832,6 +2102,7 @@
     "key": "{bgColor.success.emphasis}",
     "$value": "#1f883d",
     "$type": "color",
+    "$description": "Strong success background for prominent positive actions",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -1854,6 +2125,10 @@
         "light-high-contrast": "#1a7f37",
         "dark-high-contrast": "#002d11",
         "dark-dimmed-high-contrast": "#044f1e"
+      },
+      "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",
@@ -1861,6 +2136,7 @@
     "original": {
       "$value": "#1f883d",
       "$type": "color",
+      "$description": "Strong success background for prominent positive actions",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -1883,6 +2159,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}"
@@ -1895,6 +2175,7 @@
     "key": "{bgColor.success.muted}",
     "$value": "#dafbe1",
     "$type": "color",
+    "$description": "Subtle success background for positive feedback and completed states",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -1944,6 +2225,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",
@@ -1951,6 +2236,7 @@
     "original": {
       "$value": "{base.color.green.0}",
       "$type": "color",
+      "$description": "Subtle success background for positive feedback and completed states",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -2000,6 +2286,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."
         }
       },
       "key": "{bgColor.success.muted}"
@@ -2012,6 +2302,7 @@
     "key": "{bgColor.transparent}",
     "$value": "#ffffff00",
     "$type": "color",
+    "$description": "Fully transparent background",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -2020,6 +2311,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",
@@ -2027,6 +2322,7 @@
     "original": {
       "$value": "{base.color.transparent}",
       "$type": "color",
+      "$description": "Fully transparent background",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -2035,6 +2331,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}"
@@ -2047,6 +2347,7 @@
     "key": "{bgColor.upsell.emphasis}",
     "$value": "#8250df",
     "$type": "color",
+    "$description": "Strong background for prominent upsell elements",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -2055,6 +2356,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",
@@ -2062,6 +2367,7 @@
     "original": {
       "$value": "{bgColor.done.emphasis}",
       "$type": "color",
+      "$description": "Strong background for prominent upsell elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -2070,6 +2376,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}"
@@ -2082,6 +2392,7 @@
     "key": "{bgColor.upsell.muted}",
     "$value": "#fbefff",
     "$type": "color",
+    "$description": "Subtle background for upsell and promotional content",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -2090,6 +2401,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",
@@ -2097,6 +2412,7 @@
     "original": {
       "$value": "{bgColor.done.muted}",
       "$type": "color",
+      "$description": "Subtle background for upsell and promotional content",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -2105,6 +2421,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}"
@@ -2117,6 +2437,7 @@
     "key": "{bgColor.white}",
     "$value": "#ffffff",
     "$type": "color",
+    "$description": "Pure white background",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -2125,6 +2446,10 @@
       },
       "org.primer.overrides": {
         "dark": "#1f2328"
+      },
+      "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",
@@ -2132,6 +2457,7 @@
     "original": {
       "$value": "{base.color.neutral.0}",
       "$type": "color",
+      "$description": "Pure white background",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -2140,6 +2466,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}"
@@ -2150,7 +2480,7 @@
   },
   "border-accent-emphasis": {
     "key": "{border.accent.emphasis}",
-    "$value": "0.00390625rem,0.0625px solid #0969da",
+    "$value": "0.0625rem,1px solid #0969da",
     "$type": "border",
     "filePath": "src/tokens/functional/border/border.json5",
     "isSource": true,
@@ -2169,7 +2499,7 @@
   },
   "border-accent-muted": {
     "key": "{border.accent.muted}",
-    "$value": "0.00390625rem,0.0625px solid #54aeff66",
+    "$value": "0.0625rem,1px solid #54aeff66",
     "$type": "border",
     "filePath": "src/tokens/functional/border/border.json5",
     "isSource": true,
@@ -2188,7 +2518,7 @@
   },
   "border-attention-emphasis": {
     "key": "{border.attention.emphasis}",
-    "$value": "0.00390625rem,0.0625px solid #9a6700",
+    "$value": "0.0625rem,1px solid #9a6700",
     "$type": "border",
     "filePath": "src/tokens/functional/border/border.json5",
     "isSource": true,
@@ -2207,7 +2537,7 @@
   },
   "border-attention-muted": {
     "key": "{border.attention.muted}",
-    "$value": "0.00390625rem,0.0625px solid #d4a72c66",
+    "$value": "0.0625rem,1px solid #d4a72c66",
     "$type": "border",
     "filePath": "src/tokens/functional/border/border.json5",
     "isSource": true,
@@ -2226,7 +2556,7 @@
   },
   "border-closed-emphasis": {
     "key": "{border.closed.emphasis}",
-    "$value": "0.00390625rem,0.0625px solid #cf222e",
+    "$value": "0.0625rem,1px solid #cf222e",
     "$type": "border",
     "filePath": "src/tokens/functional/border/border.json5",
     "isSource": true,
@@ -2241,7 +2571,7 @@
   },
   "border-closed-muted": {
     "key": "{border.closed.muted}",
-    "$value": "0.00390625rem,0.0625px solid #ff818266",
+    "$value": "0.0625rem,1px solid #ff818266",
     "$type": "border",
     "filePath": "src/tokens/functional/border/border.json5",
     "isSource": true,
@@ -2256,7 +2586,7 @@
   },
   "border-danger-emphasis": {
     "key": "{border.danger.emphasis}",
-    "$value": "0.00390625rem,0.0625px solid #cf222e",
+    "$value": "0.0625rem,1px solid #cf222e",
     "$type": "border",
     "filePath": "src/tokens/functional/border/border.json5",
     "isSource": true,
@@ -2275,7 +2605,7 @@
   },
   "border-danger-muted": {
     "key": "{border.danger.muted}",
-    "$value": "0.00390625rem,0.0625px solid #ff818266",
+    "$value": "0.0625rem,1px solid #ff818266",
     "$type": "border",
     "filePath": "src/tokens/functional/border/border.json5",
     "isSource": true,
@@ -2294,7 +2624,7 @@
   },
   "border-default": {
     "key": "{border.default}",
-    "$value": "0.00390625rem,0.0625px solid #d1d9e0",
+    "$value": "0.0625rem,1px solid #d1d9e0",
     "$type": "border",
     "filePath": "src/tokens/functional/border/border.json5",
     "isSource": true,
@@ -2313,7 +2643,7 @@
   },
   "border-disabled": {
     "key": "{border.disabled}",
-    "$value": "0.00390625rem,0.0625px solid #818b981a",
+    "$value": "0.0625rem,1px solid #818b981a",
     "$type": "border",
     "filePath": "src/tokens/functional/border/border.json5",
     "isSource": true,
@@ -2332,7 +2662,7 @@
   },
   "border-done-emphasis": {
     "key": "{border.done.emphasis}",
-    "$value": "0.00390625rem,0.0625px solid #8250df",
+    "$value": "0.0625rem,1px solid #8250df",
     "$type": "border",
     "filePath": "src/tokens/functional/border/border.json5",
     "isSource": true,
@@ -2351,7 +2681,7 @@
   },
   "border-done-muted": {
     "key": "{border.done.muted}",
-    "$value": "0.00390625rem,0.0625px solid #c297ff66",
+    "$value": "0.0625rem,1px solid #c297ff66",
     "$type": "border",
     "filePath": "src/tokens/functional/border/border.json5",
     "isSource": true,
@@ -2370,7 +2700,7 @@
   },
   "border-emphasis": {
     "key": "{border.emphasis}",
-    "$value": "0.00390625rem,0.0625px solid #818b98",
+    "$value": "0.0625rem,1px solid #818b98",
     "$type": "border",
     "filePath": "src/tokens/functional/border/border.json5",
     "isSource": true,
@@ -2389,7 +2719,7 @@
   },
   "border-muted": {
     "key": "{border.muted}",
-    "$value": "0.00390625rem,0.0625px solid #d1d9e0b3",
+    "$value": "0.0625rem,1px solid #d1d9e0b3",
     "$type": "border",
     "filePath": "src/tokens/functional/border/border.json5",
     "isSource": true,
@@ -2408,7 +2738,7 @@
   },
   "border-neutral-emphasis": {
     "key": "{border.neutral.emphasis}",
-    "$value": "0.00390625rem,0.0625px solid #59636e",
+    "$value": "0.0625rem,1px solid #59636e",
     "$type": "border",
     "filePath": "src/tokens/functional/border/border.json5",
     "isSource": true,
@@ -2427,7 +2757,7 @@
   },
   "border-neutral-muted": {
     "key": "{border.neutral.muted}",
-    "$value": "0.00390625rem,0.0625px solid #d1d9e0b3",
+    "$value": "0.0625rem,1px solid #d1d9e0b3",
     "$type": "border",
     "filePath": "src/tokens/functional/border/border.json5",
     "isSource": true,
@@ -2446,7 +2776,7 @@
   },
   "border-open-emphasis": {
     "key": "{border.open.emphasis}",
-    "$value": "0.00390625rem,0.0625px solid #1a7f37",
+    "$value": "0.0625rem,1px solid #1a7f37",
     "$type": "border",
     "filePath": "src/tokens/functional/border/border.json5",
     "isSource": true,
@@ -2461,7 +2791,7 @@
   },
   "border-open-muted": {
     "key": "{border.open.muted}",
-    "$value": "0.00390625rem,0.0625px solid #4ac26b66",
+    "$value": "0.0625rem,1px solid #4ac26b66",
     "$type": "border",
     "filePath": "src/tokens/functional/border/border.json5",
     "isSource": true,
@@ -2476,7 +2806,7 @@
   },
   "border-severe-emphasis": {
     "key": "{border.severe.emphasis}",
-    "$value": "0.00390625rem,0.0625px solid #bc4c00",
+    "$value": "0.0625rem,1px solid #bc4c00",
     "$type": "border",
     "filePath": "src/tokens/functional/border/border.json5",
     "isSource": true,
@@ -2495,7 +2825,7 @@
   },
   "border-severe-muted": {
     "key": "{border.severe.muted}",
-    "$value": "0.00390625rem,0.0625px solid #fb8f4466",
+    "$value": "0.0625rem,1px solid #fb8f4466",
     "$type": "border",
     "filePath": "src/tokens/functional/border/border.json5",
     "isSource": true,
@@ -2514,7 +2844,7 @@
   },
   "border-sponsors-emphasis": {
     "key": "{border.sponsors.emphasis}",
-    "$value": "0.00390625rem,0.0625px solid #bf3989",
+    "$value": "0.0625rem,1px solid #bf3989",
     "$type": "border",
     "filePath": "src/tokens/functional/border/border.json5",
     "isSource": true,
@@ -2533,7 +2863,7 @@
   },
   "border-sponsors-muted": {
     "key": "{border.sponsors.muted}",
-    "$value": "0.00390625rem,0.0625px solid #ff80c866",
+    "$value": "0.0625rem,1px solid #ff80c866",
     "$type": "border",
     "filePath": "src/tokens/functional/border/border.json5",
     "isSource": true,
@@ -2552,7 +2882,7 @@
   },
   "border-success-emphasis": {
     "key": "{border.success.emphasis}",
-    "$value": "0.00390625rem,0.0625px solid #1a7f37",
+    "$value": "0.0625rem,1px solid #1a7f37",
     "$type": "border",
     "filePath": "src/tokens/functional/border/border.json5",
     "isSource": true,
@@ -2571,7 +2901,7 @@
   },
   "border-success-muted": {
     "key": "{border.success.muted}",
-    "$value": "0.00390625rem,0.0625px solid #4ac26b66",
+    "$value": "0.0625rem,1px solid #4ac26b66",
     "$type": "border",
     "filePath": "src/tokens/functional/border/border.json5",
     "isSource": true,
@@ -2590,7 +2920,7 @@
   },
   "border-transparent": {
     "key": "{border.transparent}",
-    "$value": "0.00390625rem,0.0625px solid #ffffff00",
+    "$value": "0.0625rem,1px solid #ffffff00",
     "$type": "border",
     "filePath": "src/tokens/functional/border/border.json5",
     "isSource": true,
@@ -2609,7 +2939,7 @@
   },
   "border-upsell-emphasis": {
     "key": "{border.upsell.emphasis}",
-    "$value": "0.00390625rem,0.0625px solid #8250df",
+    "$value": "0.0625rem,1px solid #8250df",
     "$type": "border",
     "filePath": "src/tokens/functional/border/border.json5",
     "isSource": true,
@@ -2628,7 +2958,7 @@
   },
   "border-upsell-muted": {
     "key": "{border.upsell.muted}",
-    "$value": "0.00390625rem,0.0625px solid #c297ff66",
+    "$value": "0.0625rem,1px solid #c297ff66",
     "$type": "border",
     "filePath": "src/tokens/functional/border/border.json5",
     "isSource": true,
@@ -2649,6 +2979,7 @@
     "key": "{borderColor.accent.emphasis}",
     "$value": "#0969da",
     "$type": "color",
+    "$description": "Strong accent border for selected or focused elements",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -2660,6 +2991,10 @@
       },
       "org.primer.overrides": {
         "dark-dimmed-high-contrast": "#80ccff"
+      },
+      "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",
@@ -2667,6 +3002,7 @@
     "original": {
       "$value": "{base.color.blue.5}",
       "$type": "color",
+      "$description": "Strong accent border for selected or focused elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -2678,6 +3014,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}"
@@ -2690,6 +3030,7 @@
     "key": "{borderColor.accent.muted}",
     "$value": "#54aeff66",
     "$type": "color",
+    "$description": "Subtle accent border for selected or focused elements",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -2750,6 +3091,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,
@@ -2758,6 +3103,7 @@
     "original": {
       "$value": "{base.color.blue.3}",
       "$type": "color",
+      "$description": "Subtle accent border for selected or focused elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -2818,6 +3164,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,
@@ -2831,6 +3181,7 @@
     "key": "{borderColor.attention.emphasis}",
     "$value": "#9a6700",
     "$type": "color",
+    "$description": "Strong attention border for prominent warnings",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -2842,6 +3193,10 @@
       },
       "org.primer.overrides": {
         "dark-dimmed-high-contrast": "#eac54f"
+      },
+      "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",
@@ -2849,6 +3204,7 @@
     "original": {
       "$value": "{base.color.yellow.5}",
       "$type": "color",
+      "$description": "Strong attention border for prominent warnings",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -2860,6 +3216,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}"
@@ -2872,6 +3232,7 @@
     "key": "{borderColor.attention.muted}",
     "$value": "#d4a72c66",
     "$type": "color",
+    "$description": "Subtle attention border for warnings and caution states",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -2932,6 +3293,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,
@@ -2940,6 +3305,7 @@
     "original": {
       "$value": "{base.color.yellow.3}",
       "$type": "color",
+      "$description": "Subtle attention border for warnings and caution states",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -3000,6 +3366,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,
@@ -3013,6 +3383,7 @@
     "key": "{borderColor.closed.emphasis}",
     "$value": "#cf222e",
     "$type": "color",
+    "$description": "Strong border for closed state badges",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -3031,6 +3402,10 @@
         "dark-tritanopia-high-contrast": "#818b98",
         "light-tritanopia": "#818b98",
         "light-tritanopia-high-contrast": "#818b98"
+      },
+      "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",
@@ -3038,6 +3413,7 @@
     "original": {
       "$value": "{borderColor.danger.emphasis}",
       "$type": "color",
+      "$description": "Strong border for closed state badges",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -3056,6 +3432,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}"
@@ -3068,6 +3448,7 @@
     "key": "{borderColor.closed.muted}",
     "$value": "#ff818266",
     "$type": "color",
+    "$description": "Subtle border for closed state indicators",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -3134,6 +3515,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",
@@ -3141,6 +3526,7 @@
     "original": {
       "$value": "{borderColor.danger.muted}",
       "$type": "color",
+      "$description": "Subtle border for closed state indicators",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -3207,6 +3593,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}"
@@ -3219,6 +3609,7 @@
     "key": "{borderColor.danger.emphasis}",
     "$value": "#cf222e",
     "$type": "color",
+    "$description": "Strong danger border for destructive actions and errors",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -3254,6 +3645,10 @@
           "$type": "color"
         },
         "dark-dimmed-high-contrast": "#ffaba8"
+      },
+      "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",
@@ -3261,6 +3656,7 @@
     "original": {
       "$value": "{base.color.red.5}",
       "$type": "color",
+      "$description": "Strong danger border for destructive actions and errors",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -3296,6 +3692,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}"
@@ -3308,6 +3708,7 @@
     "key": "{borderColor.danger.muted}",
     "$value": "#ff818266",
     "$type": "color",
+    "$description": "Subtle danger border for errors and destructive contexts",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -3381,6 +3782,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,
@@ -3389,6 +3794,7 @@
     "original": {
       "$value": "{base.color.red.3}",
       "$type": "color",
+      "$description": "Subtle danger border for errors and destructive contexts",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -3462,6 +3868,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,
@@ -3475,6 +3885,7 @@
     "key": "{borderColor.default}",
     "$value": "#d1d9e0",
     "$type": "color",
+    "$description": "Default border color for most UI elements",
     "$extensions": {
       "org.primer.overrides": {
         "dark": "#c8d1da",
@@ -3494,6 +3905,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",
@@ -3501,6 +3916,7 @@
     "original": {
       "$value": "{base.color.neutral.6}",
       "$type": "color",
+      "$description": "Default border color for most UI elements",
       "$extensions": {
         "org.primer.overrides": {
           "dark": "{base.color.neutral.7}",
@@ -3520,6 +3936,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}"
@@ -3532,6 +3952,7 @@
     "key": "{borderColor.disabled}",
     "$value": "#818b981a",
     "$type": "color",
+    "$description": "Border color for disabled interactive elements",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -3574,6 +3995,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,
@@ -3582,6 +4007,7 @@
     "original": {
       "$value": "{base.color.neutral.8}",
       "$type": "color",
+      "$description": "Border color for disabled interactive elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -3624,6 +4050,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,
@@ -3637,6 +4067,7 @@
     "key": "{borderColor.done.emphasis}",
     "$value": "#8250df",
     "$type": "color",
+    "$description": "Strong border for completed/done state badges",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -3648,6 +4079,10 @@
       },
       "org.primer.overrides": {
         "dark-dimmed-high-contrast": "#d8b9ff"
+      },
+      "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",
@@ -3655,6 +4090,7 @@
     "original": {
       "$value": "{base.color.purple.5}",
       "$type": "color",
+      "$description": "Strong border for completed/done state badges",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -3666,6 +4102,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}"
@@ -3678,6 +4118,7 @@
     "key": "{borderColor.done.muted}",
     "$value": "#c297ff66",
     "$type": "color",
+    "$description": "Subtle border for completed/done state indicators",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -3738,6 +4179,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,
@@ -3746,6 +4191,7 @@
     "original": {
       "$value": "{base.color.purple.3}",
       "$type": "color",
+      "$description": "Subtle border for completed/done state indicators",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -3806,6 +4252,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,
@@ -3819,6 +4269,7 @@
     "key": "{borderColor.draft.emphasis}",
     "$value": "#59636e",
     "$type": "color",
+    "$description": "Strong border for draft state badges",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -3827,6 +4278,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",
@@ -3834,6 +4289,7 @@
     "original": {
       "$value": "{borderColor.neutral.emphasis}",
       "$type": "color",
+      "$description": "Strong border for draft state badges",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -3842,6 +4298,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}"
@@ -3854,6 +4314,7 @@
     "key": "{borderColor.draft.muted}",
     "$value": "#d1d9e0b3",
     "$type": "color",
+    "$description": "Subtle border for draft state indicators",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -3920,6 +4381,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",
@@ -3927,6 +4392,7 @@
     "original": {
       "$value": "{borderColor.neutral.muted}",
       "$type": "color",
+      "$description": "Subtle border for draft state indicators",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -3993,6 +4459,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}"
@@ -4005,6 +4475,7 @@
     "key": "{borderColor.emphasis}",
     "$value": "#818b98",
     "$type": "color",
+    "$description": "Strong border for emphasis and visual weight",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -4019,6 +4490,10 @@
         "dark-dimmed-high-contrast": "#d1d9e0",
         "dark-tritanopia-high-contrast": "#d1d9e0",
         "dark-protanopia-deuteranopia-high-contrast": "#d1d9e0"
+      },
+      "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",
@@ -4026,6 +4501,7 @@
     "original": {
       "$value": "{base.color.neutral.8}",
       "$type": "color",
+      "$description": "Strong border for emphasis and visual weight",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -4040,6 +4516,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}"
@@ -4052,6 +4532,7 @@
     "key": "{borderColor.muted}",
     "$value": "#d1d9e0b3",
     "$type": "color",
+    "$description": "Subtle border for secondary elements and light separators",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -4118,6 +4599,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,
@@ -4126,6 +4611,7 @@
     "original": {
       "$value": "{borderColor.default}",
       "$type": "color",
+      "$description": "Subtle border for secondary elements and light separators",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -4192,6 +4678,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,
@@ -4205,6 +4695,7 @@
     "key": "{borderColor.neutral.emphasis}",
     "$value": "#59636e",
     "$type": "color",
+    "$description": "Strong neutral semantic border",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -4213,6 +4704,10 @@
       },
       "org.primer.overrides": {
         "dark": "#818b98"
+      },
+      "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",
@@ -4220,6 +4715,7 @@
     "original": {
       "$value": "{base.color.neutral.9}",
       "$type": "color",
+      "$description": "Strong neutral semantic border",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -4228,6 +4724,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}"
@@ -4240,6 +4740,7 @@
     "key": "{borderColor.neutral.muted}",
     "$value": "#d1d9e0b3",
     "$type": "color",
+    "$description": "Subtle neutral semantic border",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -4261,6 +4762,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",
@@ -4268,6 +4773,7 @@
     "original": {
       "$value": "{borderColor.muted}",
       "$type": "color",
+      "$description": "Subtle neutral semantic border",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -4289,6 +4795,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."
         }
       },
       "key": "{borderColor.neutral.muted}"
@@ -4301,6 +4811,7 @@
     "key": "{borderColor.open.emphasis}",
     "$value": "#1a7f37",
     "$type": "color",
+    "$description": "Strong border for open state badges",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -4319,6 +4830,10 @@
         "dark-protanopia-deuteranopia-high-contrast": "#bc4c00",
         "light-protanopia-deuteranopia": "#bc4c00",
         "light-protanopia-deuteranopia-high-contrast": "#bc4c00"
+      },
+      "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",
@@ -4326,6 +4841,7 @@
     "original": {
       "$value": "{borderColor.success.emphasis}",
       "$type": "color",
+      "$description": "Strong border for open state badges",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -4344,6 +4860,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}"
@@ -4356,6 +4876,7 @@
     "key": "{borderColor.open.muted}",
     "$value": "#4ac26b66",
     "$type": "color",
+    "$description": "Subtle border for open state indicators",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -4422,6 +4943,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",
@@ -4429,6 +4954,7 @@
     "original": {
       "$value": "{borderColor.success.muted}",
       "$type": "color",
+      "$description": "Subtle border for open state indicators",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -4495,6 +5021,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}"
@@ -4507,6 +5037,7 @@
     "key": "{borderColor.severe.emphasis}",
     "$value": "#bc4c00",
     "$type": "color",
+    "$description": "Strong severe border for prominent high-priority warnings",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -4521,6 +5052,10 @@
         "light-tritanopia": "#cf222e",
         "light-tritanopia-high-contrast": "#cf222e",
         "dark-dimmed-high-contrast": "#ffb77c"
+      },
+      "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",
@@ -4528,6 +5063,7 @@
     "original": {
       "$value": "{base.color.orange.5}",
       "$type": "color",
+      "$description": "Strong severe border for prominent high-priority warnings",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -4542,6 +5078,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}"
@@ -4554,6 +5094,7 @@
     "key": "{borderColor.severe.muted}",
     "$value": "#fb8f4466",
     "$type": "color",
+    "$description": "Subtle severe border for high-priority warnings",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -4609,6 +5150,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,
@@ -4617,6 +5162,7 @@
     "original": {
       "$value": "{base.color.orange.3}",
       "$type": "color",
+      "$description": "Subtle severe border for high-priority warnings",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -4672,6 +5218,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,
@@ -4685,6 +5235,7 @@
     "key": "{borderColor.sponsors.emphasis}",
     "$value": "#bf3989",
     "$type": "color",
+    "$description": "Strong border for prominent GitHub Sponsors elements",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -4696,6 +5247,10 @@
       },
       "org.primer.overrides": {
         "dark-dimmed-high-contrast": "#ff80c8"
+      },
+      "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",
@@ -4703,6 +5258,7 @@
     "original": {
       "$value": "{base.color.pink.5}",
       "$type": "color",
+      "$description": "Strong border for prominent GitHub Sponsors elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -4714,6 +5270,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}"
@@ -4726,6 +5286,7 @@
     "key": "{borderColor.sponsors.muted}",
     "$value": "#ff80c866",
     "$type": "color",
+    "$description": "Subtle border for GitHub Sponsors content",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -4786,6 +5347,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,
@@ -4794,6 +5359,7 @@
     "original": {
       "$value": "{base.color.pink.3}",
       "$type": "color",
+      "$description": "Subtle border for GitHub Sponsors content",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -4854,6 +5420,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,
@@ -4867,6 +5437,7 @@
     "key": "{borderColor.success.emphasis}",
     "$value": "#1a7f37",
     "$type": "color",
+    "$description": "Strong success border for prominent positive elements",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -4886,6 +5457,10 @@
         "light-protanopia-deuteranopia": "#0969da",
         "light-protanopia-deuteranopia-high-contrast": "#0969da",
         "dark-dimmed-high-contrast": "#6fdd8b"
+      },
+      "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",
@@ -4893,6 +5468,7 @@
     "original": {
       "$value": "{base.color.green.5}",
       "$type": "color",
+      "$description": "Strong success border for prominent positive elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -4912,6 +5488,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}"
@@ -4924,6 +5504,7 @@
     "key": "{borderColor.success.muted}",
     "$value": "#4ac26b66",
     "$type": "color",
+    "$description": "Subtle success border for positive feedback elements",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -5011,6 +5592,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,
@@ -5019,6 +5604,7 @@
     "original": {
       "$value": "{base.color.green.3}",
       "$type": "color",
+      "$description": "Subtle success border for positive feedback elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -5106,6 +5692,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,
@@ -5119,6 +5709,7 @@
     "key": "{borderColor.translucent}",
     "$value": "#1f232826",
     "$type": "color",
+    "$description": "Semi-transparent border for overlays and layered elements",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -5175,6 +5766,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,
@@ -5183,6 +5778,7 @@
     "original": {
       "$value": "{base.color.neutral.13}",
       "$type": "color",
+      "$description": "Semi-transparent border for overlays and layered elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -5239,6 +5835,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,
@@ -5252,6 +5852,7 @@
     "key": "{borderColor.transparent}",
     "$value": "#ffffff00",
     "$type": "color",
+    "$description": "Fully transparent border",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -5264,6 +5865,7 @@
     "original": {
       "$value": "{base.color.transparent}",
       "$type": "color",
+      "$description": "Fully transparent border",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -5281,6 +5883,7 @@
     "key": "{borderColor.upsell.emphasis}",
     "$value": "#8250df",
     "$type": "color",
+    "$description": "Strong border for prominent upsell elements",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -5289,6 +5892,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",
@@ -5296,6 +5903,7 @@
     "original": {
       "$value": "{borderColor.done.emphasis}",
       "$type": "color",
+      "$description": "Strong border for prominent upsell elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -5304,6 +5912,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}"
@@ -5316,6 +5928,7 @@
     "key": "{borderColor.upsell.muted}",
     "$value": "#c297ff66",
     "$type": "color",
+    "$description": "Subtle border for upsell and promotional content",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -5324,6 +5937,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",
@@ -5331,6 +5948,7 @@
     "original": {
       "$value": "{borderColor.done.muted}",
       "$type": "color",
+      "$description": "Subtle border for upsell and promotional content",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -5339,6 +5957,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}"
@@ -36473,6 +37095,7 @@
     "key": "{fgColor.accent}",
     "$value": "#0969da",
     "$type": "color",
+    "$description": "Accent text for links and interactive elements",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -36492,6 +37115,10 @@
         "light-high-contrast": "#0550ae",
         "light-tritanopia-high-contrast": "#0550ae",
         "light-protanopia-deuteranopia-high-contrast": "#0550ae"
+      },
+      "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",
@@ -36499,6 +37126,7 @@
     "original": {
       "$value": "{base.color.blue.5}",
       "$type": "color",
+      "$description": "Accent text for links and interactive elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -36518,6 +37146,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}"
@@ -36530,6 +37162,7 @@
     "key": "{fgColor.attention}",
     "$value": "#9a6700",
     "$type": "color",
+    "$description": "Attention text for warnings and caution states",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -36545,6 +37178,10 @@
         "light-protanopia-deuteranopia-high-contrast": "#7d4e00",
         "light-tritanopia-high-contrast": "#7d4e00",
         "dark-dimmed-high-contrast": "#fae17d"
+      },
+      "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",
@@ -36552,6 +37189,7 @@
     "original": {
       "$value": "{base.color.yellow.5}",
       "$type": "color",
+      "$description": "Attention text for warnings and caution states",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -36567,6 +37205,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}"
@@ -36579,6 +37221,7 @@
     "key": "{fgColor.black}",
     "$value": "#1f2328",
     "$type": "color",
+    "$description": "Pure black text",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -36587,6 +37230,10 @@
       },
       "org.primer.overrides": {
         "dark": "#ffffff"
+      },
+      "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",
@@ -36594,6 +37241,7 @@
     "original": {
       "$value": "{base.color.neutral.13}",
       "$type": "color",
+      "$description": "Pure black text",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -36602,6 +37250,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}"
@@ -36614,6 +37266,7 @@
     "key": "{fgColor.closed}",
     "$value": "#d1242f",
     "$type": "color",
+    "$description": "Text color for closed state indicators (issues, PRs)",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -36632,6 +37285,10 @@
         "dark-tritanopia-high-contrast": "#59636e",
         "light-tritanopia": "#59636e",
         "light-tritanopia-high-contrast": "#59636e"
+      },
+      "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",
@@ -36639,6 +37296,7 @@
     "original": {
       "$value": "{fgColor.danger}",
       "$type": "color",
+      "$description": "Text color for closed state indicators (issues, PRs)",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -36657,6 +37315,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}"
@@ -36669,6 +37331,7 @@
     "key": "{fgColor.danger}",
     "$value": "#d1242f",
     "$type": "color",
+    "$description": "Danger text for errors and destructive actions",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -36689,6 +37352,10 @@
         "dark-tritanopia-high-contrast": "#ff8182",
         "light-high-contrast": "#a40e26",
         "light-tritanopia-high-contrast": "#a40e26"
+      },
+      "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",
@@ -36696,6 +37363,7 @@
     "original": {
       "$value": "#d1242f",
       "$type": "color",
+      "$description": "Danger text for errors and destructive actions",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -36716,6 +37384,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}"
@@ -36728,6 +37400,7 @@
     "key": "{fgColor.default}",
     "$value": "#1f2328",
     "$type": "color",
+    "$description": "Default text color for primary content and headings",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -36742,8 +37415,12 @@
         "dark-high-contrast": "#1f2328",
         "dark-tritanopia-high-contrast": "#1f2328",
         "dark-protanopia-deuteranopia-high-contrast": "#1f2328",
-        "dark-dimmed": "#393f46",
+        "dark-dimmed": "#25292e",
         "dark-dimmed-high-contrast": "#25292e"
+      },
+      "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",
@@ -36751,6 +37428,7 @@
     "original": {
       "$value": "{base.color.neutral.13}",
       "$type": "color",
+      "$description": "Default text color for primary content and headings",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -36765,8 +37443,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}"
@@ -36779,6 +37461,7 @@
     "key": "{fgColor.disabled}",
     "$value": "#818b98",
     "$type": "color",
+    "$description": "Text color for disabled interactive elements",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -36800,6 +37483,10 @@
         "dark-high-contrast": "#818b98",
         "dark-tritanopia-high-contrast": "#818b98",
         "dark-protanopia-deuteranopia-high-contrast": "#818b98"
+      },
+      "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",
@@ -36807,6 +37494,7 @@
     "original": {
       "$value": "{base.color.neutral.8}",
       "$type": "color",
+      "$description": "Text color for disabled interactive elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -36828,6 +37516,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}"
@@ -36840,6 +37532,7 @@
     "key": "{fgColor.done}",
     "$value": "#8250df",
     "$type": "color",
+    "$description": "Text color for completed/done state indicators",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -36858,6 +37551,10 @@
         "light-high-contrast": "#6639ba",
         "light-protanopia-deuteranopia-high-contrast": "#6639ba",
         "light-tritanopia-high-contrast": "#6639ba"
+      },
+      "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",
@@ -36865,6 +37562,7 @@
     "original": {
       "$value": "{base.color.purple.5}",
       "$type": "color",
+      "$description": "Text color for completed/done state indicators",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -36883,6 +37581,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}"
@@ -36895,6 +37597,7 @@
     "key": "{fgColor.draft}",
     "$value": "#59636e",
     "$type": "color",
+    "$description": "Text color for draft state indicators",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -36903,6 +37606,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",
@@ -36910,6 +37617,7 @@
     "original": {
       "$value": "{fgColor.neutral}",
       "$type": "color",
+      "$description": "Text color for draft state indicators",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -36918,6 +37626,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}"
@@ -36930,6 +37642,7 @@
     "key": "{fgColor.link}",
     "$value": "#0969da",
     "$type": "color",
+    "$description": "Text color for hyperlinks",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -36938,6 +37651,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",
@@ -36945,6 +37662,7 @@
     "original": {
       "$value": "{fgColor.accent}",
       "$type": "color",
+      "$description": "Text color for hyperlinks",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -36953,6 +37671,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}"
@@ -36965,6 +37687,7 @@
     "key": "{fgColor.muted}",
     "$value": "#59636e",
     "$type": "color",
+    "$description": "Muted text for secondary content and less important information",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -36982,6 +37705,10 @@
         "dark-dimmed-high-contrast": "#454c54",
         "dark-tritanopia-high-contrast": "#454c54",
         "dark-protanopia-deuteranopia-high-contrast": "#454c54"
+      },
+      "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",
@@ -36989,6 +37716,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",
@@ -37006,6 +37734,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}"
@@ -37018,6 +37750,7 @@
     "key": "{fgColor.neutral}",
     "$value": "#59636e",
     "$type": "color",
+    "$description": "Neutral semantic text for icons and secondary elements",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -37032,6 +37765,10 @@
         "dark-dimmed-high-contrast": "#393f46",
         "dark-tritanopia-high-contrast": "#393f46",
         "dark-protanopia-deuteranopia-high-contrast": "#393f46"
+      },
+      "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",
@@ -37039,6 +37776,7 @@
     "original": {
       "$value": "{base.color.neutral.9}",
       "$type": "color",
+      "$description": "Neutral semantic text for icons and secondary elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -37053,6 +37791,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}"
@@ -37065,6 +37807,7 @@
     "key": "{fgColor.onEmphasis}",
     "$value": "#ffffff",
     "$type": "color",
+    "$description": "Text color for use on emphasis backgrounds",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -37078,6 +37821,10 @@
         "dark": "#1f2328",
         "dark-dimmed": "#25292e",
         "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",
@@ -37085,6 +37832,7 @@
     "original": {
       "$value": "{base.color.neutral.0}",
       "$type": "color",
+      "$description": "Text color for use on emphasis backgrounds",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -37098,6 +37846,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}"
@@ -37110,11 +37862,16 @@
     "key": "{fgColor.onInverse}",
     "$value": "#ffffff",
     "$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."
       }
     },
     "filePath": "src/tokens/functional/color/fgColor.json5",
@@ -37122,11 +37879,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}"
@@ -37139,6 +37901,7 @@
     "key": "{fgColor.open}",
     "$value": "#1a7f37",
     "$type": "color",
+    "$description": "Text color for open state indicators (issues, PRs)",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -37157,6 +37920,10 @@
         "dark-tritanopia-high-contrast": "#ffaba8",
         "light-tritanopia": "#cf222e",
         "light-tritanopia-high-contrast": "#a40e26"
+      },
+      "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",
@@ -37164,6 +37931,7 @@
     "original": {
       "$value": "{fgColor.success}",
       "$type": "color",
+      "$description": "Text color for open state indicators (issues, PRs)",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -37182,6 +37950,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}"
@@ -37194,6 +37966,7 @@
     "key": "{fgColor.severe}",
     "$value": "#bc4c00",
     "$type": "color",
+    "$description": "Severe text for high-priority warnings",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -37214,6 +37987,10 @@
         "light-tritanopia": "#cf222e",
         "light-tritanopia-high-contrast": "#a40e26",
         "light-protanopia-deuteranopia-high-contrast": "#953800"
+      },
+      "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",
@@ -37221,6 +37998,7 @@
     "original": {
       "$value": "{base.color.orange.5}",
       "$type": "color",
+      "$description": "Severe text for high-priority warnings",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -37241,6 +38019,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}"
@@ -37253,6 +38035,7 @@
     "key": "{fgColor.sponsors}",
     "$value": "#bf3989",
     "$type": "color",
+    "$description": "Text color for GitHub Sponsors content",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -37271,6 +38054,10 @@
         "light-high-contrast": "#99286e",
         "light-protanopia-deuteranopia-high-contrast": "#99286e",
         "light-tritanopia-high-contrast": "#99286e"
+      },
+      "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",
@@ -37278,6 +38065,7 @@
     "original": {
       "$value": "{base.color.pink.5}",
       "$type": "color",
+      "$description": "Text color for GitHub Sponsors content",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -37296,6 +38084,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}"
@@ -37308,6 +38100,7 @@
     "key": "{fgColor.success}",
     "$value": "#1a7f37",
     "$type": "color",
+    "$description": "Success text for positive feedback and completed states",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -37330,6 +38123,10 @@
         "dark-tritanopia-high-contrast": "#80ccff",
         "light-tritanopia": "#0969da",
         "light-tritanopia-high-contrast": "#0550ae"
+      },
+      "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",
@@ -37337,6 +38134,7 @@
     "original": {
       "$value": "{base.color.green.5}",
       "$type": "color",
+      "$description": "Success text for positive feedback and completed states",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -37359,6 +38157,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}"
@@ -37371,6 +38173,7 @@
     "key": "{fgColor.upsell}",
     "$value": "#8250df",
     "$type": "color",
+    "$description": "Text color for upsell and promotional content",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -37379,6 +38182,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",
@@ -37386,6 +38193,7 @@
     "original": {
       "$value": "{fgColor.done}",
       "$type": "color",
+      "$description": "Text color for upsell and promotional content",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -37394,6 +38202,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}"
@@ -37406,6 +38218,7 @@
     "key": "{fgColor.white}",
     "$value": "#ffffff",
     "$type": "color",
+    "$description": "Pure white text",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -37414,6 +38227,10 @@
       },
       "org.primer.overrides": {
         "dark": "#1f2328"
+      },
+      "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",
@@ -37421,6 +38238,7 @@
     "original": {
       "$value": "{base.color.neutral.0}",
       "$type": "color",
+      "$description": "Pure white text",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -37429,6 +38247,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}"
@@ -37441,6 +38263,13 @@
     "key": "{focus.outline}",
     "$value": "2px solid #0969da",
     "$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."
+      }
+    },
     "filePath": "src/tokens/functional/border/border.json5",
     "isSource": true,
     "original": {
@@ -37450,6 +38279,13 @@
         "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",
@@ -37460,11 +38296,16 @@
     "key": "{focus.outlineColor}",
     "$value": "#0969da",
     "$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."
       }
     },
     "filePath": "src/tokens/functional/color/focus.json5",
@@ -37472,11 +38313,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}"
@@ -46524,6 +47370,7 @@
     "key": "{selection.bgColor}",
     "$value": "#0969da33",
     "$type": "color",
+    "$description": "Background color for text selection highlights",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -46538,6 +47385,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.2,
@@ -46546,6 +47397,7 @@
     "original": {
       "$value": "{bgColor.accent.emphasis}",
       "$type": "color",
+      "$description": "Background color for text selection highlights",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -46560,6 +47412,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.2,
@@ -46573,6 +47429,7 @@
     "key": "{shadow.floating.large}",
     "$value": "0px 0px 0px 1px #d1d9e0, 0px 40px 80px 0px #25292e3d",
     "$type": "shadow",
+    "$description": "Large floating shadow for modals and dialogs",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -46602,6 +47459,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",
@@ -46626,6 +47487,7 @@
         }
       ],
       "$type": "shadow",
+      "$description": "Large floating shadow for modals and dialogs",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -46655,6 +47517,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}"
@@ -46667,6 +47533,7 @@
     "key": "{shadow.floating.legacy}",
     "$value": "0px 6px 12px -3px #25292e0a, 0px 6px 18px 0px #25292e1f",
     "$type": "shadow",
+    "$description": "Legacy floating shadow for backward compatibility",
     "$extensions": {
       "org.primer.figma": {},
       "org.primer.overrides": {
@@ -46693,6 +47560,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",
@@ -46717,6 +47588,7 @@
         }
       ],
       "$type": "shadow",
+      "$description": "Legacy floating shadow for backward compatibility",
       "$extensions": {
         "org.primer.figma": {},
         "org.primer.overrides": {
@@ -46743,6 +47615,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}"
@@ -46755,6 +47631,7 @@
     "key": "{shadow.floating.medium}",
     "$value": "0px 0px 0px 1px #d1d9e0, 0px 8px 16px -4px #25292e14, 0px 4px 32px -4px #25292e14, 0px 24px 48px -12px #25292e14, 0px 48px 96px -24px #25292e14",
     "$type": "shadow",
+    "$description": "Medium floating shadow for popovers and action menus",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -46808,6 +47685,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",
@@ -46856,6 +47737,7 @@
         }
       ],
       "$type": "shadow",
+      "$description": "Medium floating shadow for popovers and action menus",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -46909,6 +47791,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}"
@@ -46921,6 +47807,7 @@
     "key": "{shadow.floating.small}",
     "$value": "0px 0px 0px 1px #d1d9e080, 0px 6px 12px -3px #25292e0a, 0px 6px 18px 0px #25292e1f",
     "$type": "shadow",
+    "$description": "Small floating shadow for dropdowns, tooltips, and small overlays",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -46958,6 +47845,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",
@@ -46990,6 +47881,7 @@
         }
       ],
       "$type": "shadow",
+      "$description": "Small floating shadow for dropdowns, tooltips, and small overlays",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -47027,6 +47919,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}"
@@ -47039,6 +47935,7 @@
     "key": "{shadow.floating.xlarge}",
     "$value": "0px 0px 0px 1px #d1d9e0, 0px 56px 112px 0px #25292e52",
     "$type": "shadow",
+    "$description": "Extra large floating shadow for full-screen overlays and sheets",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -47068,6 +47965,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",
@@ -47092,6 +47993,7 @@
         }
       ],
       "$type": "shadow",
+      "$description": "Extra large floating shadow for full-screen overlays and sheets",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -47121,6 +48023,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}"
@@ -47133,6 +48039,7 @@
     "key": "{shadow.inset}",
     "$value": "inset 0px 1px 0px 0px #1f23280a",
     "$type": "shadow",
+    "$description": "Inset shadow for recessed elements",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -47153,6 +48060,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",
@@ -47168,6 +48079,7 @@
         "inset": true
       },
       "$type": "shadow",
+      "$description": "Inset shadow for recessed elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -47188,6 +48100,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}"
@@ -47200,6 +48116,7 @@
     "key": "{shadow.resting.medium}",
     "$value": "0px 1px 1px 0px #25292e1a, 0px 3px 6px 0px #25292e1f",
     "$type": "shadow",
+    "$description": "Medium resting shadow for cards and elevated surfaces",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -47229,6 +48146,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",
@@ -47253,6 +48174,7 @@
         }
       ],
       "$type": "shadow",
+      "$description": "Medium resting shadow for cards and elevated surfaces",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -47282,6 +48204,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}"
@@ -47292,8 +48218,9 @@
   },
   "shadow-resting-small": {
     "key": "{shadow.resting.small}",
-    "$value": "0px 1px 1px 0px #1f23280f, 0px 1px 3px 0px #1f23280f",
+    "$value": "0px 1px 1px 0px #1f23280a, 0px 1px 2px 0px #1f232808",
     "$type": "shadow",
+    "$description": "Small resting shadow for buttons and interactive elements",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -47325,6 +48252,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",
@@ -47333,7 +48264,7 @@
       "$value": [
         {
           "color": "{base.color.neutral.13}",
-          "alpha": 0.06,
+          "alpha": 0.04,
           "offsetX": "0px",
           "offsetY": "1px",
           "blur": "1px",
@@ -47342,15 +48273,16 @@
         },
         {
           "color": "{base.color.neutral.13}",
-          "alpha": 0.06,
+          "alpha": 0.03,
           "offsetX": "0px",
           "offsetY": "1px",
-          "blur": "3px",
+          "blur": "2px",
           "spread": "0px",
           "inset": false
         }
       ],
       "$type": "shadow",
+      "$description": "Small resting shadow for buttons and interactive elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -47382,6 +48314,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}"
@@ -47392,8 +48328,9 @@
   },
   "shadow-resting-xsmall": {
     "key": "{shadow.resting.xsmall}",
-    "$value": "0px 1px 1px 0px #1f23280f",
+    "$value": "0px 1px 1px 0px #1f23280d",
     "$type": "shadow",
+    "$description": "Extra small resting shadow for minimal elevation",
     "$extensions": {
       "org.primer.figma": {
         "collection": "mode",
@@ -47414,6 +48351,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",
@@ -47421,7 +48362,7 @@
     "original": {
       "$value": {
         "color": "{base.color.neutral.13}",
-        "alpha": 0.06,
+        "alpha": 0.05,
         "offsetX": "0px",
         "offsetY": "1px",
         "blur": "1px",
@@ -47429,6 +48370,7 @@
         "inset": false
       },
       "$type": "shadow",
+      "$description": "Extra small resting shadow for minimal elevation",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -47449,6 +48391,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}"