@primer/primitives 11.4.0 → 11.4.1-rc.24c79953

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

@@ -176,10 +176,22 @@
             {
               "color": "#f6f8fa",
               "alpha": 1,
-              "offsetX": "0px",
-              "offsetY": "0px",
-              "blur": "0px",
-              "spread": "2px"
+              "offsetX": {
+                "value": 0,
+                "unit": "px"
+              },
+              "offsetY": {
+                "value": 0,
+                "unit": "px"
+              },
+              "blur": {
+                "value": 0,
+                "unit": "px"
+              },
+              "spread": {
+                "value": 2,
+                "unit": "px"
+              }
             }
           ],
           "filePath": "src/tokens/component/avatar.json5",
@@ -195,10 +207,22 @@
         {
           "color": "{base.color.neutral.0}",
           "alpha": 0.8,
-          "offsetX": "0px",
-          "offsetY": "0px",
-          "blur": "0px",
-          "spread": "2px"
+          "offsetX": {
+            "value": 0,
+            "unit": "px"
+          },
+          "offsetY": {
+            "value": 0,
+            "unit": "px"
+          },
+          "blur": {
+            "value": 0,
+            "unit": "px"
+          },
+          "spread": {
+            "value": 2,
+            "unit": "px"
+          }
         }
       ],
       "$type": "shadow",
@@ -213,10 +237,22 @@
               {
                 "color": "{base.color.neutral.1}",
                 "alpha": 1,
-                "offsetX": "0px",
-                "offsetY": "0px",
-                "blur": "0px",
-                "spread": "2px"
+                "offsetX": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "offsetY": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "blur": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "spread": {
+                  "value": 2,
+                  "unit": "px"
+                }
               }
             ],
             "filePath": "src/tokens/component/avatar.json5",
@@ -230,7 +266,7 @@
     "name": "avatar-shadow",
     "attributes": {},
     "path": ["avatar", "shadow"],
-    "value": "0px 0px 0px 2px #ffffffcc",
+    "value": "0 0 0 2px #ffffffcc",
     "type": "shadow"
   },
   "avatarStack-fade-bgColor-default": {
@@ -543,6 +579,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",
@@ -559,6 +599,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}"
@@ -2435,6 +2479,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",
@@ -2451,6 +2499,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}"
@@ -6939,10 +6991,22 @@
             {
               "color": "#471700",
               "alpha": 0.2,
-              "offsetX": "0px",
-              "offsetY": "1px",
-              "blur": "0px",
-              "spread": "0px",
+              "offsetX": {
+                "value": 0,
+                "unit": "px"
+              },
+              "offsetY": {
+                "value": 1,
+                "unit": "px"
+              },
+              "blur": {
+                "value": 0,
+                "unit": "px"
+              },
+              "spread": {
+                "value": 0,
+                "unit": "px"
+              },
               "inset": true
             }
           ],
@@ -6955,10 +7019,22 @@
             {
               "color": "#ffffff00",
               "alpha": 0,
-              "offsetX": "0px",
-              "offsetY": "0px",
-              "blur": "0px",
-              "spread": "0px",
+              "offsetX": {
+                "value": 0,
+                "unit": "px"
+              },
+              "offsetY": {
+                "value": 0,
+                "unit": "px"
+              },
+              "blur": {
+                "value": 0,
+                "unit": "px"
+              },
+              "spread": {
+                "value": 0,
+                "unit": "px"
+              },
               "inset": false
             }
           ],
@@ -6975,10 +7051,22 @@
         {
           "color": "{base.color.red.9}",
           "alpha": 0.2,
-          "offsetX": "0px",
-          "offsetY": "1px",
-          "blur": "0px",
-          "spread": "0px",
+          "offsetX": {
+            "value": 0,
+            "unit": "px"
+          },
+          "offsetY": {
+            "value": 1,
+            "unit": "px"
+          },
+          "blur": {
+            "value": 0,
+            "unit": "px"
+          },
+          "spread": {
+            "value": 0,
+            "unit": "px"
+          },
           "inset": true
         }
       ],
@@ -6994,10 +7082,22 @@
               {
                 "color": "{base.color.orange.9}",
                 "alpha": 0.2,
-                "offsetX": "0px",
-                "offsetY": "1px",
-                "blur": "0px",
-                "spread": "0px",
+                "offsetX": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "offsetY": {
+                  "value": 1,
+                  "unit": "px"
+                },
+                "blur": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "spread": {
+                  "value": 0,
+                  "unit": "px"
+                },
                 "inset": true
               }
             ],
@@ -7010,10 +7110,22 @@
               {
                 "color": "{base.color.transparent}",
                 "alpha": 0,
-                "offsetX": "0px",
-                "offsetY": "0px",
-                "blur": "0px",
-                "spread": "0px",
+                "offsetX": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "offsetY": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "blur": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "spread": {
+                  "value": 0,
+                  "unit": "px"
+                },
                 "inset": false
               }
             ],
@@ -7028,7 +7140,7 @@
     "name": "button-danger-shadow-selected",
     "attributes": {},
     "path": ["button", "danger", "shadow", "selected"],
-    "value": "inset 0px 1px 0px 0px #4c001433",
+    "value": "inset 0 1px 0 0 #4c001433",
     "type": "shadow"
   },
   "button-default-bgColor-active": {
@@ -7402,10 +7514,22 @@
             {
               "color": "#ffffff00",
               "alpha": 0,
-              "offsetX": "0px",
-              "offsetY": "0px",
-              "blur": "0px",
-              "spread": "0px",
+              "offsetX": {
+                "value": 0,
+                "unit": "px"
+              },
+              "offsetY": {
+                "value": 0,
+                "unit": "px"
+              },
+              "blur": {
+                "value": 0,
+                "unit": "px"
+              },
+              "spread": {
+                "value": 0,
+                "unit": "px"
+              },
               "inset": false
             }
           ],
@@ -7422,10 +7546,22 @@
         {
           "color": "{base.color.neutral.13}",
           "alpha": 0.04,
-          "offsetX": "0px",
-          "offsetY": "1px",
-          "blur": "0px",
-          "spread": "0px",
+          "offsetX": {
+            "value": 0,
+            "unit": "px"
+          },
+          "offsetY": {
+            "value": 1,
+            "unit": "px"
+          },
+          "blur": {
+            "value": 0,
+            "unit": "px"
+          },
+          "spread": {
+            "value": 0,
+            "unit": "px"
+          },
           "inset": false
         }
       ],
@@ -7441,10 +7577,22 @@
               {
                 "color": "{base.color.transparent}",
                 "alpha": 0,
-                "offsetX": "0px",
-                "offsetY": "0px",
-                "blur": "0px",
-                "spread": "0px",
+                "offsetX": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "offsetY": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "blur": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "spread": {
+                  "value": 0,
+                  "unit": "px"
+                },
                 "inset": false
               }
             ],
@@ -7459,7 +7607,7 @@
     "name": "button-default-shadow-resting",
     "attributes": {},
     "path": ["button", "default", "shadow", "resting"],
-    "value": "0px 1px 0px 0px #1f23280a",
+    "value": "0 1px 0 0 #1f23280a",
     "type": "shadow"
   },
   "button-inactive-bgColor": {
@@ -9161,10 +9309,22 @@
             {
               "color": "#ffffff00",
               "alpha": 0,
-              "offsetX": "0px",
-              "offsetY": "0px",
-              "blur": "0px",
-              "spread": "0px",
+              "offsetX": {
+                "value": 0,
+                "unit": "px"
+              },
+              "offsetY": {
+                "value": 0,
+                "unit": "px"
+              },
+              "blur": {
+                "value": 0,
+                "unit": "px"
+              },
+              "spread": {
+                "value": 0,
+                "unit": "px"
+              },
               "inset": false
             }
           ],
@@ -9181,10 +9341,22 @@
         {
           "color": "{base.color.blue.9}",
           "alpha": 0.2,
-          "offsetX": "0px",
-          "offsetY": "1px",
-          "blur": "0px",
-          "spread": "0px",
+          "offsetX": {
+            "value": 0,
+            "unit": "px"
+          },
+          "offsetY": {
+            "value": 1,
+            "unit": "px"
+          },
+          "blur": {
+            "value": 0,
+            "unit": "px"
+          },
+          "spread": {
+            "value": 0,
+            "unit": "px"
+          },
           "inset": true
         }
       ],
@@ -9200,10 +9372,22 @@
               {
                 "color": "{base.color.transparent}",
                 "alpha": 0,
-                "offsetX": "0px",
-                "offsetY": "0px",
-                "blur": "0px",
-                "spread": "0px",
+                "offsetX": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "offsetY": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "blur": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "spread": {
+                  "value": 0,
+                  "unit": "px"
+                },
                 "inset": false
               }
             ],
@@ -9218,7 +9402,7 @@
     "name": "button-outline-shadow-selected",
     "attributes": {},
     "path": ["button", "outline", "shadow", "selected"],
-    "value": "inset 0px 1px 0px 0px #00215533",
+    "value": "inset 0 1px 0 0 #00215533",
     "type": "shadow"
   },
   "button-primary-bgColor-active": {
@@ -10369,10 +10553,22 @@
             {
               "color": "#002155",
               "alpha": 0.3,
-              "offsetX": "0px",
-              "offsetY": "1px",
-              "blur": "0px",
-              "spread": "0px",
+              "offsetX": {
+                "value": 0,
+                "unit": "px"
+              },
+              "offsetY": {
+                "value": 1,
+                "unit": "px"
+              },
+              "blur": {
+                "value": 0,
+                "unit": "px"
+              },
+              "spread": {
+                "value": 0,
+                "unit": "px"
+              },
               "inset": true
             }
           ],
@@ -10385,10 +10581,22 @@
             {
               "color": "#002155",
               "alpha": 0.3,
-              "offsetX": "0px",
-              "offsetY": "1px",
-              "blur": "0px",
-              "spread": "0px",
+              "offsetX": {
+                "value": 0,
+                "unit": "px"
+              },
+              "offsetY": {
+                "value": 1,
+                "unit": "px"
+              },
+              "blur": {
+                "value": 0,
+                "unit": "px"
+              },
+              "spread": {
+                "value": 0,
+                "unit": "px"
+              },
               "inset": true
             }
           ],
@@ -10401,10 +10609,22 @@
             {
               "color": "#ffffff00",
               "alpha": 0,
-              "offsetX": "0px",
-              "offsetY": "0px",
-              "blur": "0px",
-              "spread": "0px",
+              "offsetX": {
+                "value": 0,
+                "unit": "px"
+              },
+              "offsetY": {
+                "value": 0,
+                "unit": "px"
+              },
+              "blur": {
+                "value": 0,
+                "unit": "px"
+              },
+              "spread": {
+                "value": 0,
+                "unit": "px"
+              },
               "inset": false
             }
           ],
@@ -10421,10 +10641,22 @@
         {
           "color": "{base.color.green.9}",
           "alpha": 0.3,
-          "offsetX": "0px",
-          "offsetY": "1px",
-          "blur": "0px",
-          "spread": "0px",
+          "offsetX": {
+            "value": 0,
+            "unit": "px"
+          },
+          "offsetY": {
+            "value": 1,
+            "unit": "px"
+          },
+          "blur": {
+            "value": 0,
+            "unit": "px"
+          },
+          "spread": {
+            "value": 0,
+            "unit": "px"
+          },
           "inset": true
         }
       ],
@@ -10440,10 +10672,22 @@
               {
                 "color": "{base.color.blue.9}",
                 "alpha": 0.3,
-                "offsetX": "0px",
-                "offsetY": "1px",
-                "blur": "0px",
-                "spread": "0px",
+                "offsetX": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "offsetY": {
+                  "value": 1,
+                  "unit": "px"
+                },
+                "blur": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "spread": {
+                  "value": 0,
+                  "unit": "px"
+                },
                 "inset": true
               }
             ],
@@ -10456,10 +10700,22 @@
               {
                 "color": "{base.color.blue.9}",
                 "alpha": 0.3,
-                "offsetX": "0px",
-                "offsetY": "1px",
-                "blur": "0px",
-                "spread": "0px",
+                "offsetX": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "offsetY": {
+                  "value": 1,
+                  "unit": "px"
+                },
+                "blur": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "spread": {
+                  "value": 0,
+                  "unit": "px"
+                },
                 "inset": true
               }
             ],
@@ -10472,10 +10728,22 @@
               {
                 "color": "{base.color.transparent}",
                 "alpha": 0,
-                "offsetX": "0px",
-                "offsetY": "0px",
-                "blur": "0px",
-                "spread": "0px",
+                "offsetX": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "offsetY": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "blur": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "spread": {
+                  "value": 0,
+                  "unit": "px"
+                },
                 "inset": false
               }
             ],
@@ -10490,7 +10758,7 @@
     "name": "button-primary-shadow-selected",
     "attributes": {},
     "path": ["button", "primary", "shadow", "selected"],
-    "value": "inset 0px 1px 0px 0px #002d114d",
+    "value": "inset 0 1px 0 0 #002d114d",
     "type": "shadow"
   },
   "button-star-iconColor": {
@@ -37211,6 +37479,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",
@@ -37227,6 +37499,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}"
@@ -38200,6 +38476,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",
@@ -38216,6 +38496,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}"
@@ -38241,7 +38525,10 @@
       "$value": {
         "color": "{focus.outlineColor}",
         "style": "solid",
-        "width": "2px"
+        "width": {
+          "value": 2,
+          "unit": "px"
+        }
       },
       "$type": "border",
       "$description": "Focus ring outline for keyboard navigation and accessibility.",
@@ -47406,18 +47693,42 @@
             {
               "color": "#d1d9e080",
               "alpha": 1,
-              "offsetX": "0px",
-              "offsetY": "0px",
-              "blur": "0px",
-              "spread": "1px"
+              "offsetX": {
+                "value": 0,
+                "unit": "px"
+              },
+              "offsetY": {
+                "value": 0,
+                "unit": "px"
+              },
+              "blur": {
+                "value": 0,
+                "unit": "px"
+              },
+              "spread": {
+                "value": 1,
+                "unit": "px"
+              }
             },
             {
               "color": "#ffffff",
               "alpha": 1,
-              "offsetX": "0px",
-              "offsetY": "24px",
-              "blur": "48px",
-              "spread": "0px"
+              "offsetX": {
+                "value": 0,
+                "unit": "px"
+              },
+              "offsetY": {
+                "value": 24,
+                "unit": "px"
+              },
+              "blur": {
+                "value": 48,
+                "unit": "px"
+              },
+              "spread": {
+                "value": 0,
+                "unit": "px"
+              }
             }
           ],
           "filePath": "src/tokens/functional/shadow/shadow.json5",
@@ -47437,18 +47748,42 @@
         {
           "color": "{overlay.borderColor}",
           "alpha": 0,
-          "offsetX": "0px",
-          "offsetY": "0px",
-          "blur": "0px",
-          "spread": "1px"
+          "offsetX": {
+            "value": 0,
+            "unit": "px"
+          },
+          "offsetY": {
+            "value": 0,
+            "unit": "px"
+          },
+          "blur": {
+            "value": 0,
+            "unit": "px"
+          },
+          "spread": {
+            "value": 1,
+            "unit": "px"
+          }
         },
         {
           "color": "{base.color.neutral.12}",
           "alpha": 0.24,
-          "offsetX": "0px",
-          "offsetY": "40px",
-          "blur": "80px",
-          "spread": "0px"
+          "offsetX": {
+            "value": 0,
+            "unit": "px"
+          },
+          "offsetY": {
+            "value": 40,
+            "unit": "px"
+          },
+          "blur": {
+            "value": 80,
+            "unit": "px"
+          },
+          "spread": {
+            "value": 0,
+            "unit": "px"
+          }
         }
       ],
       "$type": "shadow",
@@ -47464,18 +47799,42 @@
               {
                 "color": "{overlay.borderColor}",
                 "alpha": 1,
-                "offsetX": "0px",
-                "offsetY": "0px",
-                "blur": "0px",
-                "spread": "1px"
+                "offsetX": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "offsetY": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "blur": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "spread": {
+                  "value": 1,
+                  "unit": "px"
+                }
               },
               {
                 "color": "{base.color.neutral.0}",
                 "alpha": 1,
-                "offsetX": "0px",
-                "offsetY": "24px",
-                "blur": "48px",
-                "spread": "0px"
+                "offsetX": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "offsetY": {
+                  "value": 24,
+                  "unit": "px"
+                },
+                "blur": {
+                  "value": 48,
+                  "unit": "px"
+                },
+                "spread": {
+                  "value": 0,
+                  "unit": "px"
+                }
               }
             ],
             "filePath": "src/tokens/functional/shadow/shadow.json5",
@@ -47493,7 +47852,7 @@
     "name": "shadow-floating-large",
     "attributes": {},
     "path": ["shadow", "floating", "large"],
-    "value": "0px 0px 0px 1px #d1d9e0, 0px 40px 80px 0px #25292e3d",
+    "value": "0 0 0 1px #d1d9e0, 0 40px 80px 0 #25292e3d",
     "type": "shadow",
     "description": "Large floating shadow for modals and dialogs"
   },
@@ -47507,24 +47866,52 @@
             {
               "color": "#ffffff",
               "alpha": 0.4,
-              "offsetX": "0px",
-              "offsetY": "6px",
-              "blur": "12px",
-              "spread": "-3px"
+              "offsetX": {
+                "value": 0,
+                "unit": "px"
+              },
+              "offsetY": {
+                "value": 6,
+                "unit": "px"
+              },
+              "blur": {
+                "value": 12,
+                "unit": "px"
+              },
+              "spread": {
+                "value": -3,
+                "unit": "px"
+              }
             },
             {
               "color": "#ffffff",
               "alpha": 0.4,
-              "offsetX": "0px",
-              "offsetY": "6px",
-              "blur": "18px",
-              "spread": "0px"
+              "offsetX": {
+                "value": 0,
+                "unit": "px"
+              },
+              "offsetY": {
+                "value": 6,
+                "unit": "px"
+              },
+              "blur": {
+                "value": 18,
+                "unit": "px"
+              },
+              "spread": {
+                "value": 0,
+                "unit": "px"
+              }
             }
           ],
           "filePath": "src/tokens/functional/shadow/shadow.json5",
           "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",
@@ -47534,21 +47921,46 @@
         {
           "color": "{base.color.neutral.12}",
           "alpha": 0.04,
-          "offsetX": "0px",
-          "offsetY": "6px",
-          "blur": "12px",
-          "spread": "-3px"
+          "offsetX": {
+            "value": 0,
+            "unit": "px"
+          },
+          "offsetY": {
+            "value": 6,
+            "unit": "px"
+          },
+          "blur": {
+            "value": 12,
+            "unit": "px"
+          },
+          "spread": {
+            "value": -3,
+            "unit": "px"
+          }
         },
         {
           "color": "{base.color.neutral.12}",
           "alpha": 0.12,
-          "offsetX": "0px",
-          "offsetY": "6px",
-          "blur": "18px",
-          "spread": "0px"
+          "offsetX": {
+            "value": 0,
+            "unit": "px"
+          },
+          "offsetY": {
+            "value": 6,
+            "unit": "px"
+          },
+          "blur": {
+            "value": 18,
+            "unit": "px"
+          },
+          "spread": {
+            "value": 0,
+            "unit": "px"
+          }
         }
       ],
       "$type": "shadow",
+      "$description": "Legacy floating shadow for backward compatibility",
       "$extensions": {
         "org.primer.figma": {},
         "org.primer.overrides": {
@@ -47557,24 +47969,52 @@
               {
                 "color": "{base.color.neutral.0}",
                 "alpha": 0.4,
-                "offsetX": "0px",
-                "offsetY": "6px",
-                "blur": "12px",
-                "spread": "-3px"
+                "offsetX": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "offsetY": {
+                  "value": 6,
+                  "unit": "px"
+                },
+                "blur": {
+                  "value": 12,
+                  "unit": "px"
+                },
+                "spread": {
+                  "value": -3,
+                  "unit": "px"
+                }
               },
               {
                 "color": "{base.color.neutral.0}",
                 "alpha": 0.4,
-                "offsetX": "0px",
-                "offsetY": "6px",
-                "blur": "18px",
-                "spread": "0px"
+                "offsetX": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "offsetY": {
+                  "value": 6,
+                  "unit": "px"
+                },
+                "blur": {
+                  "value": 18,
+                  "unit": "px"
+                },
+                "spread": {
+                  "value": 0,
+                  "unit": "px"
+                }
               }
             ],
             "filePath": "src/tokens/functional/shadow/shadow.json5",
             "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}"
@@ -47582,8 +48022,9 @@
     "name": "shadow-floating-legacy",
     "attributes": {},
     "path": ["shadow", "floating", "legacy"],
-    "value": "0px 6px 12px -3px #25292e0a, 0px 6px 18px 0px #25292e1f",
-    "type": "shadow"
+    "value": "0 6px 12px -3px #25292e0a, 0 6px 18px 0 #25292e1f",
+    "type": "shadow",
+    "description": "Legacy floating shadow for backward compatibility"
   },
   "shadow-floating-medium": {
     "key": "{shadow.floating.medium}",
@@ -47598,48 +48039,112 @@
             {
               "color": "#d1d9e080",
               "alpha": 1,
-              "offsetX": "0px",
-              "offsetY": "0px",
-              "blur": "0px",
-              "spread": "1px"
+              "offsetX": {
+                "value": 0,
+                "unit": "px"
+              },
+              "offsetY": {
+                "value": 0,
+                "unit": "px"
+              },
+              "blur": {
+                "value": 0,
+                "unit": "px"
+              },
+              "spread": {
+                "value": 1,
+                "unit": "px"
+              }
             },
             {
               "color": "#ffffff",
               "alpha": 0.4,
-              "offsetX": "0px",
-              "offsetY": "8px",
-              "blur": "16px",
-              "spread": "-4px"
+              "offsetX": {
+                "value": 0,
+                "unit": "px"
+              },
+              "offsetY": {
+                "value": 8,
+                "unit": "px"
+              },
+              "blur": {
+                "value": 16,
+                "unit": "px"
+              },
+              "spread": {
+                "value": -4,
+                "unit": "px"
+              }
             },
             {
               "color": "#ffffff",
               "alpha": 0.4,
-              "offsetX": "0px",
-              "offsetY": "4px",
-              "blur": "32px",
-              "spread": "-4px"
+              "offsetX": {
+                "value": 0,
+                "unit": "px"
+              },
+              "offsetY": {
+                "value": 4,
+                "unit": "px"
+              },
+              "blur": {
+                "value": 32,
+                "unit": "px"
+              },
+              "spread": {
+                "value": -4,
+                "unit": "px"
+              }
             },
             {
               "color": "#ffffff",
               "alpha": 0.4,
-              "offsetX": "0px",
-              "offsetY": "24px",
-              "blur": "48px",
-              "spread": "-12px"
+              "offsetX": {
+                "value": 0,
+                "unit": "px"
+              },
+              "offsetY": {
+                "value": 24,
+                "unit": "px"
+              },
+              "blur": {
+                "value": 48,
+                "unit": "px"
+              },
+              "spread": {
+                "value": -12,
+                "unit": "px"
+              }
             },
             {
               "color": "#ffffff",
               "alpha": 0.4,
-              "offsetX": "0px",
-              "offsetY": "48px",
-              "blur": "96px",
-              "spread": "-24px"
+              "offsetX": {
+                "value": 0,
+                "unit": "px"
+              },
+              "offsetY": {
+                "value": 48,
+                "unit": "px"
+              },
+              "blur": {
+                "value": 96,
+                "unit": "px"
+              },
+              "spread": {
+                "value": -24,
+                "unit": "px"
+              }
             }
           ],
           "filePath": "src/tokens/functional/shadow/shadow.json5",
           "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",
@@ -47649,45 +48154,106 @@
         {
           "color": "{overlay.borderColor}",
           "alpha": 0,
-          "offsetX": "0px",
-          "offsetY": "0px",
-          "blur": "0px",
-          "spread": "1px"
+          "offsetX": {
+            "value": 0,
+            "unit": "px"
+          },
+          "offsetY": {
+            "value": 0,
+            "unit": "px"
+          },
+          "blur": {
+            "value": 0,
+            "unit": "px"
+          },
+          "spread": {
+            "value": 1,
+            "unit": "px"
+          }
         },
         {
           "color": "{base.color.neutral.12}",
           "alpha": 0.08,
-          "offsetX": "0px",
-          "offsetY": "8px",
-          "blur": "16px",
-          "spread": "-4px"
+          "offsetX": {
+            "value": 0,
+            "unit": "px"
+          },
+          "offsetY": {
+            "value": 8,
+            "unit": "px"
+          },
+          "blur": {
+            "value": 16,
+            "unit": "px"
+          },
+          "spread": {
+            "value": -4,
+            "unit": "px"
+          }
         },
         {
           "color": "{base.color.neutral.12}",
           "alpha": 0.08,
-          "offsetX": "0px",
-          "offsetY": "4px",
-          "blur": "32px",
-          "spread": "-4px"
+          "offsetX": {
+            "value": 0,
+            "unit": "px"
+          },
+          "offsetY": {
+            "value": 4,
+            "unit": "px"
+          },
+          "blur": {
+            "value": 32,
+            "unit": "px"
+          },
+          "spread": {
+            "value": -4,
+            "unit": "px"
+          }
         },
         {
           "color": "{base.color.neutral.12}",
           "alpha": 0.08,
-          "offsetX": "0px",
-          "offsetY": "24px",
-          "blur": "48px",
-          "spread": "-12px"
+          "offsetX": {
+            "value": 0,
+            "unit": "px"
+          },
+          "offsetY": {
+            "value": 24,
+            "unit": "px"
+          },
+          "blur": {
+            "value": 48,
+            "unit": "px"
+          },
+          "spread": {
+            "value": -12,
+            "unit": "px"
+          }
         },
         {
           "color": "{base.color.neutral.12}",
           "alpha": 0.08,
-          "offsetX": "0px",
-          "offsetY": "48px",
-          "blur": "96px",
-          "spread": "-24px"
+          "offsetX": {
+            "value": 0,
+            "unit": "px"
+          },
+          "offsetY": {
+            "value": 48,
+            "unit": "px"
+          },
+          "blur": {
+            "value": 96,
+            "unit": "px"
+          },
+          "spread": {
+            "value": -24,
+            "unit": "px"
+          }
         }
       ],
       "$type": "shadow",
+      "$description": "Medium floating shadow for popovers and action menus",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -47699,48 +48265,112 @@
               {
                 "color": "{overlay.borderColor}",
                 "alpha": 1,
-                "offsetX": "0px",
-                "offsetY": "0px",
-                "blur": "0px",
-                "spread": "1px"
+                "offsetX": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "offsetY": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "blur": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "spread": {
+                  "value": 1,
+                  "unit": "px"
+                }
               },
               {
                 "color": "{base.color.neutral.0}",
                 "alpha": 0.4,
-                "offsetX": "0px",
-                "offsetY": "8px",
-                "blur": "16px",
-                "spread": "-4px"
+                "offsetX": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "offsetY": {
+                  "value": 8,
+                  "unit": "px"
+                },
+                "blur": {
+                  "value": 16,
+                  "unit": "px"
+                },
+                "spread": {
+                  "value": -4,
+                  "unit": "px"
+                }
               },
               {
                 "color": "{base.color.neutral.0}",
                 "alpha": 0.4,
-                "offsetX": "0px",
-                "offsetY": "4px",
-                "blur": "32px",
-                "spread": "-4px"
+                "offsetX": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "offsetY": {
+                  "value": 4,
+                  "unit": "px"
+                },
+                "blur": {
+                  "value": 32,
+                  "unit": "px"
+                },
+                "spread": {
+                  "value": -4,
+                  "unit": "px"
+                }
               },
               {
                 "color": "{base.color.neutral.0}",
                 "alpha": 0.4,
-                "offsetX": "0px",
-                "offsetY": "24px",
-                "blur": "48px",
-                "spread": "-12px"
+                "offsetX": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "offsetY": {
+                  "value": 24,
+                  "unit": "px"
+                },
+                "blur": {
+                  "value": 48,
+                  "unit": "px"
+                },
+                "spread": {
+                  "value": -12,
+                  "unit": "px"
+                }
               },
               {
                 "color": "{base.color.neutral.0}",
                 "alpha": 0.4,
-                "offsetX": "0px",
-                "offsetY": "48px",
-                "blur": "96px",
-                "spread": "-24px"
+                "offsetX": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "offsetY": {
+                  "value": 48,
+                  "unit": "px"
+                },
+                "blur": {
+                  "value": 96,
+                  "unit": "px"
+                },
+                "spread": {
+                  "value": -24,
+                  "unit": "px"
+                }
               }
             ],
             "filePath": "src/tokens/functional/shadow/shadow.json5",
             "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}"
@@ -47748,8 +48378,9 @@
     "name": "shadow-floating-medium",
     "attributes": {},
     "path": ["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"
+    "value": "0 0 0 1px #d1d9e0, 0 8px 16px -4px #25292e14, 0 4px 32px -4px #25292e14, 0 24px 48px -12px #25292e14, 0 48px 96px -24px #25292e14",
+    "type": "shadow",
+    "description": "Medium floating shadow for popovers and action menus"
   },
   "shadow-floating-small": {
     "key": "{shadow.floating.small}",
@@ -47764,26 +48395,62 @@
             {
               "color": "#d1d9e080",
               "alpha": 1,
-              "offsetX": "0px",
-              "offsetY": "0px",
-              "blur": "0px",
-              "spread": "1px"
+              "offsetX": {
+                "value": 0,
+                "unit": "px"
+              },
+              "offsetY": {
+                "value": 0,
+                "unit": "px"
+              },
+              "blur": {
+                "value": 0,
+                "unit": "px"
+              },
+              "spread": {
+                "value": 1,
+                "unit": "px"
+              }
             },
             {
               "color": "#ffffff",
               "alpha": 0.4,
-              "offsetX": "0px",
-              "offsetY": "6px",
-              "blur": "12px",
-              "spread": "-3px"
+              "offsetX": {
+                "value": 0,
+                "unit": "px"
+              },
+              "offsetY": {
+                "value": 6,
+                "unit": "px"
+              },
+              "blur": {
+                "value": 12,
+                "unit": "px"
+              },
+              "spread": {
+                "value": -3,
+                "unit": "px"
+              }
             },
             {
               "color": "#ffffff",
               "alpha": 0.4,
-              "offsetX": "0px",
-              "offsetY": "6px",
-              "blur": "18px",
-              "spread": "0px"
+              "offsetX": {
+                "value": 0,
+                "unit": "px"
+              },
+              "offsetY": {
+                "value": 6,
+                "unit": "px"
+              },
+              "blur": {
+                "value": 18,
+                "unit": "px"
+              },
+              "spread": {
+                "value": 0,
+                "unit": "px"
+              }
             }
           ],
           "filePath": "src/tokens/functional/shadow/shadow.json5",
@@ -47803,26 +48470,62 @@
         {
           "color": "{overlay.borderColor}",
           "alpha": 0.5,
-          "offsetX": "0px",
-          "offsetY": "0px",
-          "blur": "0px",
-          "spread": "1px"
+          "offsetX": {
+            "value": 0,
+            "unit": "px"
+          },
+          "offsetY": {
+            "value": 0,
+            "unit": "px"
+          },
+          "blur": {
+            "value": 0,
+            "unit": "px"
+          },
+          "spread": {
+            "value": 1,
+            "unit": "px"
+          }
         },
         {
           "color": "{base.color.neutral.12}",
           "alpha": 0.04,
-          "offsetX": "0px",
-          "offsetY": "6px",
-          "blur": "12px",
-          "spread": "-3px"
+          "offsetX": {
+            "value": 0,
+            "unit": "px"
+          },
+          "offsetY": {
+            "value": 6,
+            "unit": "px"
+          },
+          "blur": {
+            "value": 12,
+            "unit": "px"
+          },
+          "spread": {
+            "value": -3,
+            "unit": "px"
+          }
         },
         {
           "color": "{base.color.neutral.12}",
           "alpha": 0.12,
-          "offsetX": "0px",
-          "offsetY": "6px",
-          "blur": "18px",
-          "spread": "0px"
+          "offsetX": {
+            "value": 0,
+            "unit": "px"
+          },
+          "offsetY": {
+            "value": 6,
+            "unit": "px"
+          },
+          "blur": {
+            "value": 18,
+            "unit": "px"
+          },
+          "spread": {
+            "value": 0,
+            "unit": "px"
+          }
         }
       ],
       "$type": "shadow",
@@ -47838,26 +48541,62 @@
               {
                 "color": "{overlay.borderColor}",
                 "alpha": 1,
-                "offsetX": "0px",
-                "offsetY": "0px",
-                "blur": "0px",
-                "spread": "1px"
+                "offsetX": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "offsetY": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "blur": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "spread": {
+                  "value": 1,
+                  "unit": "px"
+                }
               },
               {
                 "color": "{base.color.neutral.0}",
                 "alpha": 0.4,
-                "offsetX": "0px",
-                "offsetY": "6px",
-                "blur": "12px",
-                "spread": "-3px"
+                "offsetX": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "offsetY": {
+                  "value": 6,
+                  "unit": "px"
+                },
+                "blur": {
+                  "value": 12,
+                  "unit": "px"
+                },
+                "spread": {
+                  "value": -3,
+                  "unit": "px"
+                }
               },
               {
                 "color": "{base.color.neutral.0}",
                 "alpha": 0.4,
-                "offsetX": "0px",
-                "offsetY": "6px",
-                "blur": "18px",
-                "spread": "0px"
+                "offsetX": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "offsetY": {
+                  "value": 6,
+                  "unit": "px"
+                },
+                "blur": {
+                  "value": 18,
+                  "unit": "px"
+                },
+                "spread": {
+                  "value": 0,
+                  "unit": "px"
+                }
               }
             ],
             "filePath": "src/tokens/functional/shadow/shadow.json5",
@@ -47875,7 +48614,7 @@
     "name": "shadow-floating-small",
     "attributes": {},
     "path": ["shadow", "floating", "small"],
-    "value": "0px 0px 0px 1px #d1d9e080, 0px 6px 12px -3px #25292e0a, 0px 6px 18px 0px #25292e1f",
+    "value": "0 0 0 1px #d1d9e080, 0 6px 12px -3px #25292e0a, 0 6px 18px 0 #25292e1f",
     "type": "shadow",
     "description": "Small floating shadow for dropdowns, tooltips, and small overlays"
   },
@@ -47892,24 +48631,52 @@
             {
               "color": "#d1d9e080",
               "alpha": 1,
-              "offsetX": "0px",
-              "offsetY": "0px",
-              "blur": "0px",
-              "spread": "1px"
+              "offsetX": {
+                "value": 0,
+                "unit": "px"
+              },
+              "offsetY": {
+                "value": 0,
+                "unit": "px"
+              },
+              "blur": {
+                "value": 0,
+                "unit": "px"
+              },
+              "spread": {
+                "value": 1,
+                "unit": "px"
+              }
             },
             {
               "color": "#ffffff",
               "alpha": 1,
-              "offsetX": "0px",
-              "offsetY": "32px",
-              "blur": "64px",
-              "spread": "0px"
+              "offsetX": {
+                "value": 0,
+                "unit": "px"
+              },
+              "offsetY": {
+                "value": 32,
+                "unit": "px"
+              },
+              "blur": {
+                "value": 64,
+                "unit": "px"
+              },
+              "spread": {
+                "value": 0,
+                "unit": "px"
+              }
             }
           ],
           "filePath": "src/tokens/functional/shadow/shadow.json5",
           "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",
@@ -47919,21 +48686,46 @@
         {
           "color": "{overlay.borderColor}",
           "alpha": 0,
-          "offsetX": "0px",
-          "offsetY": "0px",
-          "blur": "0px",
-          "spread": "1px"
+          "offsetX": {
+            "value": 0,
+            "unit": "px"
+          },
+          "offsetY": {
+            "value": 0,
+            "unit": "px"
+          },
+          "blur": {
+            "value": 0,
+            "unit": "px"
+          },
+          "spread": {
+            "value": 1,
+            "unit": "px"
+          }
         },
         {
           "color": "{base.color.neutral.12}",
           "alpha": 0.32,
-          "offsetX": "0px",
-          "offsetY": "56px",
-          "blur": "112px",
-          "spread": "0px"
+          "offsetX": {
+            "value": 0,
+            "unit": "px"
+          },
+          "offsetY": {
+            "value": 56,
+            "unit": "px"
+          },
+          "blur": {
+            "value": 112,
+            "unit": "px"
+          },
+          "spread": {
+            "value": 0,
+            "unit": "px"
+          }
         }
       ],
       "$type": "shadow",
+      "$description": "Extra large floating shadow for full-screen overlays and sheets",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -47945,24 +48737,52 @@
               {
                 "color": "{overlay.borderColor}",
                 "alpha": 1,
-                "offsetX": "0px",
-                "offsetY": "0px",
-                "blur": "0px",
-                "spread": "1px"
+                "offsetX": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "offsetY": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "blur": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "spread": {
+                  "value": 1,
+                  "unit": "px"
+                }
               },
               {
                 "color": "{base.color.neutral.0}",
                 "alpha": 1,
-                "offsetX": "0px",
-                "offsetY": "32px",
-                "blur": "64px",
-                "spread": "0px"
+                "offsetX": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "offsetY": {
+                  "value": 32,
+                  "unit": "px"
+                },
+                "blur": {
+                  "value": 64,
+                  "unit": "px"
+                },
+                "spread": {
+                  "value": 0,
+                  "unit": "px"
+                }
               }
             ],
             "filePath": "src/tokens/functional/shadow/shadow.json5",
             "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}"
@@ -47970,8 +48790,9 @@
     "name": "shadow-floating-xlarge",
     "attributes": {},
     "path": ["shadow", "floating", "xlarge"],
-    "value": "0px 0px 0px 1px #d1d9e0, 0px 56px 112px 0px #25292e52",
-    "type": "shadow"
+    "value": "0 0 0 1px #d1d9e0, 0 56px 112px 0 #25292e52",
+    "type": "shadow",
+    "description": "Extra large floating shadow for full-screen overlays and sheets"
   },
   "shadow-inset": {
     "key": "{shadow.inset}",
@@ -47985,16 +48806,32 @@
           "$value": {
             "color": "#ffffff",
             "alpha": 0.24,
-            "offsetX": "0px",
-            "offsetY": "1px",
-            "blur": "0px",
-            "spread": "0px",
+            "offsetX": {
+              "value": 0,
+              "unit": "px"
+            },
+            "offsetY": {
+              "value": 1,
+              "unit": "px"
+            },
+            "blur": {
+              "value": 0,
+              "unit": "px"
+            },
+            "spread": {
+              "value": 0,
+              "unit": "px"
+            },
             "inset": true
           },
           "filePath": "src/tokens/functional/shadow/shadow.json5",
           "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",
@@ -48003,13 +48840,26 @@
       "$value": {
         "color": "{base.color.neutral.13}",
         "alpha": 0.04,
-        "offsetX": "0px",
-        "offsetY": "1px",
-        "blur": "0px",
-        "spread": "0px",
+        "offsetX": {
+          "value": 0,
+          "unit": "px"
+        },
+        "offsetY": {
+          "value": 1,
+          "unit": "px"
+        },
+        "blur": {
+          "value": 0,
+          "unit": "px"
+        },
+        "spread": {
+          "value": 0,
+          "unit": "px"
+        },
         "inset": true
       },
       "$type": "shadow",
+      "$description": "Inset shadow for recessed elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -48020,16 +48870,32 @@
             "$value": {
               "color": "{base.color.neutral.0}",
               "alpha": 0.24,
-              "offsetX": "0px",
-              "offsetY": "1px",
-              "blur": "0px",
-              "spread": "0px",
+              "offsetX": {
+                "value": 0,
+                "unit": "px"
+              },
+              "offsetY": {
+                "value": 1,
+                "unit": "px"
+              },
+              "blur": {
+                "value": 0,
+                "unit": "px"
+              },
+              "spread": {
+                "value": 0,
+                "unit": "px"
+              },
               "inset": true
             },
             "filePath": "src/tokens/functional/shadow/shadow.json5",
             "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}"
@@ -48037,8 +48903,9 @@
     "name": "shadow-inset",
     "attributes": {},
     "path": ["shadow", "inset"],
-    "value": "inset 0px 1px 0px 0px #1f23280a",
-    "type": "shadow"
+    "value": "inset 0 1px 0 0 #1f23280a",
+    "type": "shadow",
+    "description": "Inset shadow for recessed elements"
   },
   "shadow-resting-medium": {
     "key": "{shadow.resting.medium}",
@@ -48053,24 +48920,52 @@
             {
               "color": "#ffffff",
               "alpha": 0.4,
-              "offsetX": "0px",
-              "offsetY": "1px",
-              "blur": "1px",
-              "spread": "0px"
+              "offsetX": {
+                "value": 0,
+                "unit": "px"
+              },
+              "offsetY": {
+                "value": 1,
+                "unit": "px"
+              },
+              "blur": {
+                "value": 1,
+                "unit": "px"
+              },
+              "spread": {
+                "value": 0,
+                "unit": "px"
+              }
             },
             {
               "color": "#ffffff",
               "alpha": 0.8,
-              "offsetX": "0px",
-              "offsetY": "3px",
-              "blur": "6px",
-              "spread": "0px"
+              "offsetX": {
+                "value": 0,
+                "unit": "px"
+              },
+              "offsetY": {
+                "value": 3,
+                "unit": "px"
+              },
+              "blur": {
+                "value": 6,
+                "unit": "px"
+              },
+              "spread": {
+                "value": 0,
+                "unit": "px"
+              }
             }
           ],
           "filePath": "src/tokens/functional/shadow/shadow.json5",
           "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",
@@ -48080,21 +48975,46 @@
         {
           "color": "{base.color.neutral.12}",
           "alpha": 0.1,
-          "offsetX": "0px",
-          "offsetY": "1px",
-          "blur": "1px",
-          "spread": "0px"
+          "offsetX": {
+            "value": 0,
+            "unit": "px"
+          },
+          "offsetY": {
+            "value": 1,
+            "unit": "px"
+          },
+          "blur": {
+            "value": 1,
+            "unit": "px"
+          },
+          "spread": {
+            "value": 0,
+            "unit": "px"
+          }
         },
         {
           "color": "{base.color.neutral.12}",
           "alpha": 0.12,
-          "offsetX": "0px",
-          "offsetY": "3px",
-          "blur": "6px",
-          "spread": "0px"
+          "offsetX": {
+            "value": 0,
+            "unit": "px"
+          },
+          "offsetY": {
+            "value": 3,
+            "unit": "px"
+          },
+          "blur": {
+            "value": 6,
+            "unit": "px"
+          },
+          "spread": {
+            "value": 0,
+            "unit": "px"
+          }
         }
       ],
       "$type": "shadow",
+      "$description": "Medium resting shadow for cards and elevated surfaces",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -48106,24 +49026,52 @@
               {
                 "color": "{base.color.neutral.0}",
                 "alpha": 0.4,
-                "offsetX": "0px",
-                "offsetY": "1px",
-                "blur": "1px",
-                "spread": "0px"
+                "offsetX": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "offsetY": {
+                  "value": 1,
+                  "unit": "px"
+                },
+                "blur": {
+                  "value": 1,
+                  "unit": "px"
+                },
+                "spread": {
+                  "value": 0,
+                  "unit": "px"
+                }
               },
               {
                 "color": "{base.color.neutral.0}",
                 "alpha": 0.8,
-                "offsetX": "0px",
-                "offsetY": "3px",
-                "blur": "6px",
-                "spread": "0px"
+                "offsetX": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "offsetY": {
+                  "value": 3,
+                  "unit": "px"
+                },
+                "blur": {
+                  "value": 6,
+                  "unit": "px"
+                },
+                "spread": {
+                  "value": 0,
+                  "unit": "px"
+                }
               }
             ],
             "filePath": "src/tokens/functional/shadow/shadow.json5",
             "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}"
@@ -48131,8 +49079,9 @@
     "name": "shadow-resting-medium",
     "attributes": {},
     "path": ["shadow", "resting", "medium"],
-    "value": "0px 1px 1px 0px #25292e1a, 0px 3px 6px 0px #25292e1f",
-    "type": "shadow"
+    "value": "0 1px 1px 0 #25292e1a, 0 3px 6px 0 #25292e1f",
+    "type": "shadow",
+    "description": "Medium resting shadow for cards and elevated surfaces"
   },
   "shadow-resting-small": {
     "key": "{shadow.resting.small}",
@@ -48147,19 +49096,43 @@
             {
               "color": "#ffffff",
               "alpha": 0.6,
-              "offsetX": "0px",
-              "offsetY": "1px",
-              "blur": "1px",
-              "spread": "0px",
+              "offsetX": {
+                "value": 0,
+                "unit": "px"
+              },
+              "offsetY": {
+                "value": 1,
+                "unit": "px"
+              },
+              "blur": {
+                "value": 1,
+                "unit": "px"
+              },
+              "spread": {
+                "value": 0,
+                "unit": "px"
+              },
               "inset": false
             },
             {
               "color": "#ffffff",
               "alpha": 0.6,
-              "offsetX": "0px",
-              "offsetY": "1px",
-              "blur": "3px",
-              "spread": "0px",
+              "offsetX": {
+                "value": 0,
+                "unit": "px"
+              },
+              "offsetY": {
+                "value": 1,
+                "unit": "px"
+              },
+              "blur": {
+                "value": 3,
+                "unit": "px"
+              },
+              "spread": {
+                "value": 0,
+                "unit": "px"
+              },
               "inset": false
             }
           ],
@@ -48167,6 +49140,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",
@@ -48175,24 +49152,49 @@
       "$value": [
         {
           "color": "{base.color.neutral.13}",
-          "alpha": 0.06,
-          "offsetX": "0px",
-          "offsetY": "1px",
-          "blur": "1px",
-          "spread": "0px",
+          "alpha": 0.04,
+          "offsetX": {
+            "value": 0,
+            "unit": "px"
+          },
+          "offsetY": {
+            "value": 1,
+            "unit": "px"
+          },
+          "blur": {
+            "value": 1,
+            "unit": "px"
+          },
+          "spread": {
+            "value": 0,
+            "unit": "px"
+          },
           "inset": false
         },
         {
           "color": "{base.color.neutral.13}",
-          "alpha": 0.06,
-          "offsetX": "0px",
-          "offsetY": "1px",
-          "blur": "3px",
-          "spread": "0px",
+          "alpha": 0.03,
+          "offsetX": {
+            "value": 0,
+            "unit": "px"
+          },
+          "offsetY": {
+            "value": 1,
+            "unit": "px"
+          },
+          "blur": {
+            "value": 2,
+            "unit": "px"
+          },
+          "spread": {
+            "value": 0,
+            "unit": "px"
+          },
           "inset": false
         }
       ],
       "$type": "shadow",
+      "$description": "Small resting shadow for buttons and interactive elements",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -48204,19 +49206,43 @@
               {
                 "color": "{base.color.neutral.0}",
                 "alpha": 0.6,
-                "offsetX": "0px",
-                "offsetY": "1px",
-                "blur": "1px",
-                "spread": "0px",
+                "offsetX": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "offsetY": {
+                  "value": 1,
+                  "unit": "px"
+                },
+                "blur": {
+                  "value": 1,
+                  "unit": "px"
+                },
+                "spread": {
+                  "value": 0,
+                  "unit": "px"
+                },
                 "inset": false
               },
               {
                 "color": "{base.color.neutral.0}",
                 "alpha": 0.6,
-                "offsetX": "0px",
-                "offsetY": "1px",
-                "blur": "3px",
-                "spread": "0px",
+                "offsetX": {
+                  "value": 0,
+                  "unit": "px"
+                },
+                "offsetY": {
+                  "value": 1,
+                  "unit": "px"
+                },
+                "blur": {
+                  "value": 3,
+                  "unit": "px"
+                },
+                "spread": {
+                  "value": 0,
+                  "unit": "px"
+                },
                 "inset": false
               }
             ],
@@ -48224,6 +49250,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}"
@@ -48231,8 +49261,9 @@
     "name": "shadow-resting-small",
     "attributes": {},
     "path": ["shadow", "resting", "small"],
-    "value": "0px 1px 1px 0px #1f23280f, 0px 1px 3px 0px #1f23280f",
-    "type": "shadow"
+    "value": "0 1px 1px 0 #1f23280a, 0 1px 2px 0 #1f232808",
+    "type": "shadow",
+    "description": "Small resting shadow for buttons and interactive elements"
   },
   "shadow-resting-xsmall": {
     "key": "{shadow.resting.xsmall}",
@@ -48246,16 +49277,32 @@
           "$value": {
             "color": "#ffffff",
             "alpha": 0.8,
-            "offsetX": "0px",
-            "offsetY": "1px",
-            "blur": "1px",
-            "spread": "0px",
+            "offsetX": {
+              "value": 0,
+              "unit": "px"
+            },
+            "offsetY": {
+              "value": 1,
+              "unit": "px"
+            },
+            "blur": {
+              "value": 1,
+              "unit": "px"
+            },
+            "spread": {
+              "value": 0,
+              "unit": "px"
+            },
             "inset": false
           },
           "filePath": "src/tokens/functional/shadow/shadow.json5",
           "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",
@@ -48263,14 +49310,27 @@
     "original": {
       "$value": {
         "color": "{base.color.neutral.13}",
-        "alpha": 0.06,
-        "offsetX": "0px",
-        "offsetY": "1px",
-        "blur": "1px",
-        "spread": "0px",
+        "alpha": 0.05,
+        "offsetX": {
+          "value": 0,
+          "unit": "px"
+        },
+        "offsetY": {
+          "value": 1,
+          "unit": "px"
+        },
+        "blur": {
+          "value": 1,
+          "unit": "px"
+        },
+        "spread": {
+          "value": 0,
+          "unit": "px"
+        },
         "inset": false
       },
       "$type": "shadow",
+      "$description": "Extra small resting shadow for minimal elevation",
       "$extensions": {
         "org.primer.figma": {
           "collection": "mode",
@@ -48281,16 +49341,32 @@
             "$value": {
               "color": "{base.color.neutral.0}",
               "alpha": 0.8,
-              "offsetX": "0px",
-              "offsetY": "1px",
-              "blur": "1px",
-              "spread": "0px",
+              "offsetX": {
+                "value": 0,
+                "unit": "px"
+              },
+              "offsetY": {
+                "value": 1,
+                "unit": "px"
+              },
+              "blur": {
+                "value": 1,
+                "unit": "px"
+              },
+              "spread": {
+                "value": 0,
+                "unit": "px"
+              },
               "inset": false
             },
             "filePath": "src/tokens/functional/shadow/shadow.json5",
             "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}"
@@ -48298,8 +49374,9 @@
     "name": "shadow-resting-xsmall",
     "attributes": {},
     "path": ["shadow", "resting", "xsmall"],
-    "value": "0px 1px 1px 0px #1f23280f",
-    "type": "shadow"
+    "value": "0 1px 1px 0 #1f23280d",
+    "type": "shadow",
+    "description": "Extra small resting shadow for minimal elevation"
   },
   "sideNav-bgColor-selected": {
     "key": "{sideNav.bgColor.selected}",