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

package/dist/styleLint/functional/typography/typography.json

@@ -3,21 +3,31 @@
     "key": "{fontStack.monospace}",
     "$value": "ui-monospace, SFMono-Regular, SF Mono, Menlo, Consolas, Liberation Mono, monospace",
     "$type": "fontFamily",
+    "$description": "Monospace font stack for code, technical content, and tabular data.",
     "$extensions": {
       "org.primer.figma": {
         "collection": "typography",
         "scopes": ["fontFamily"]
+      },
+      "org.primer.llm": {
+        "usage": ["code-block", "inline-code", "terminal", "technical-data", "tabular-numbers"],
+        "rules": "MUST use for all code display. Use for technical content requiring fixed-width characters."
       }
     },
-    "filePath": "src/tokens/functional/typography/typography.json5",
+    "filePath": "src/tokens/functional/typography/font-stack.json5",
     "isSource": true,
     "original": {
       "$value": "ui-monospace, SFMono-Regular, SF Mono, Menlo, Consolas, Liberation Mono, monospace",
       "$type": "fontFamily",
+      "$description": "Monospace font stack for code, technical content, and tabular data.",
       "$extensions": {
         "org.primer.figma": {
           "collection": "typography",
           "scopes": ["fontFamily"]
+        },
+        "org.primer.llm": {
+          "usage": ["code-block", "inline-code", "terminal", "technical-data", "tabular-numbers"],
+          "rules": "MUST use for all code display. Use for technical content requiring fixed-width characters."
         }
       },
       "key": "{fontStack.monospace}"
@@ -30,21 +40,31 @@
     "key": "{fontStack.sansSerif}",
     "$value": "-apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji'",
     "$type": "fontFamily",
+    "$description": "Sans-serif font stack for body text and general UI elements.",
     "$extensions": {
       "org.primer.figma": {
         "collection": "typography",
         "scopes": ["fontFamily"]
+      },
+      "org.primer.llm": {
+        "usage": ["body-text", "form-inputs", "labels", "paragraphs"],
+        "rules": "Default font stack for all UI text. Use for body text and standard UI elements. MUST use for readable content."
       }
     },
-    "filePath": "src/tokens/functional/typography/typography.json5",
+    "filePath": "src/tokens/functional/typography/font-stack.json5",
     "isSource": true,
     "original": {
       "$value": "-apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji'",
       "$type": "fontFamily",
+      "$description": "Sans-serif font stack for body text and general UI elements.",
       "$extensions": {
         "org.primer.figma": {
           "collection": "typography",
           "scopes": ["fontFamily"]
+        },
+        "org.primer.llm": {
+          "usage": ["body-text", "form-inputs", "labels", "paragraphs"],
+          "rules": "Default font stack for all UI text. Use for body text and standard UI elements. MUST use for readable content."
         }
       },
       "key": "{fontStack.sansSerif}"
@@ -57,21 +77,31 @@
     "key": "{fontStack.sansSerifDisplay}",
     "$value": "-apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji'",
     "$type": "fontFamily",
+    "$description": "Display font stack for headings and titles. Same as sansSerif but semantically distinct.",
     "$extensions": {
       "org.primer.figma": {
         "collection": "typography",
         "scopes": ["fontFamily"]
+      },
+      "org.primer.llm": {
+        "usage": ["heading", "title", "display-text", "hero-text"],
+        "rules": "Use for headings and display text. Prefer over sansSerif for titles."
       }
     },
-    "filePath": "src/tokens/functional/typography/typography.json5",
+    "filePath": "src/tokens/functional/typography/font-stack.json5",
     "isSource": true,
     "original": {
       "$value": "-apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji'",
       "$type": "fontFamily",
+      "$description": "Display font stack for headings and titles. Same as sansSerif but semantically distinct.",
       "$extensions": {
         "org.primer.figma": {
           "collection": "typography",
           "scopes": ["fontFamily"]
+        },
+        "org.primer.llm": {
+          "usage": ["heading", "title", "display-text", "hero-text"],
+          "rules": "Use for headings and display text. Prefer over sansSerif for titles."
         }
       },
       "key": "{fontStack.sansSerifDisplay}"
@@ -84,17 +114,19 @@
     "key": "{fontStack.system}",
     "$value": "-apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji'",
     "$type": "fontFamily",
+    "$description": "System font stack optimized for cross-platform rendering. Primary font for all UI text.",
     "$extensions": {
       "org.primer.figma": {
         "collection": "typography",
         "scopes": ["fontFamily"]
       }
     },
-    "filePath": "src/tokens/functional/typography/typography.json5",
+    "filePath": "src/tokens/functional/typography/font-stack.json5",
     "isSource": true,
     "original": {
       "$value": "-apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji'",
       "$type": "fontFamily",
+      "$description": "System font stack optimized for cross-platform rendering. Primary font for all UI text.",
       "$extensions": {
         "org.primer.figma": {
           "collection": "typography",
@@ -208,9 +240,15 @@
   },
   "text-body-shorthand-large": {
     "key": "{text.body.shorthand.large}",
-    "$value": "400 ,16px/1.5 -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji'",
+    "$value": "400 1rem,16px/1.5 -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji'",
     "$type": "typography",
     "$description": "User-generated content, markdown rendering.",
+    "$extensions": {
+      "org.primer.llm": {
+        "usage": ["markdown-content", "article-text", "readme", "comment-body"],
+        "rules": "Use for user-generated content and markdown. Better readability for longer text."
+      }
+    },
     "filePath": "src/tokens/functional/typography/typography.json5",
     "isSource": true,
     "original": {
@@ -222,6 +260,12 @@
       },
       "$type": "typography",
       "$description": "User-generated content, markdown rendering.",
+      "$extensions": {
+        "org.primer.llm": {
+          "usage": ["markdown-content", "article-text", "readme", "comment-body"],
+          "rules": "Use for user-generated content and markdown. Better readability for longer text."
+        }
+      },
       "key": "{text.body.shorthand.large}"
     },
     "name": "text-body-shorthand-large",
@@ -230,9 +274,15 @@
   },
   "text-body-shorthand-medium": {
     "key": "{text.body.shorthand.medium}",
-    "$value": "400 ,14px/1.5 -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji'",
+    "$value": "400 0.875rem,14px/1.5 -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji'",
     "$type": "typography",
     "$description": "Default UI font. Most commonly used for body text.",
+    "$extensions": {
+      "org.primer.llm": {
+        "usage": ["body-text", "ui-text", "form-label", "button-text", "navigation"],
+        "rules": "RECOMMENDED default for UI text. Use for buttons, labels, and general interface text."
+      }
+    },
     "filePath": "src/tokens/functional/typography/typography.json5",
     "isSource": true,
     "original": {
@@ -244,6 +294,12 @@
       },
       "$type": "typography",
       "$description": "Default UI font. Most commonly used for body text.",
+      "$extensions": {
+        "org.primer.llm": {
+          "usage": ["body-text", "ui-text", "form-label", "button-text", "navigation"],
+          "rules": "RECOMMENDED default for UI text. Use for buttons, labels, and general interface text."
+        }
+      },
       "key": "{text.body.shorthand.medium}"
     },
     "name": "text-body-shorthand-medium",
@@ -252,9 +308,15 @@
   },
   "text-body-shorthand-small": {
     "key": "{text.body.shorthand.small}",
-    "$value": "400 ,12px/1.625 -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji'",
+    "$value": "400 0.75rem,12px/1.625 -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji'",
     "$type": "typography",
     "$description": "Small body text for discrete UI applications, such as helper, footnote text. Should be used sparingly across pages. Line-height matches Body (medium) at 20px.",
+    "$extensions": {
+      "org.primer.llm": {
+        "usage": ["helper-text", "footnote", "metadata", "timestamp"],
+        "rules": "Use sparingly for secondary information. Do NOT use for primary content or interactive elements."
+      }
+    },
     "filePath": "src/tokens/functional/typography/typography.json5",
     "isSource": true,
     "original": {
@@ -266,6 +328,12 @@
       },
       "$type": "typography",
       "$description": "Small body text for discrete UI applications, such as helper, footnote text. Should be used sparingly across pages. Line-height matches Body (medium) at 20px.",
+      "$extensions": {
+        "org.primer.llm": {
+          "usage": ["helper-text", "footnote", "metadata", "timestamp"],
+          "rules": "Use sparingly for secondary information. Do NOT use for primary content or interactive elements."
+        }
+      },
       "key": "{text.body.shorthand.small}"
     },
     "name": "text-body-shorthand-small",
@@ -274,7 +342,7 @@
   },
   "text-body-size-large": {
     "key": "{text.body.size.large}",
-    "$value": [null, "16px"],
+    "$value": ["1rem", "16px"],
     "$type": "dimension",
     "$extensions": {
       "org.primer.figma": {
@@ -301,7 +369,7 @@
   },
   "text-body-size-medium": {
     "key": "{text.body.size.medium}",
-    "$value": [null, "14px"],
+    "$value": ["0.875rem", "14px"],
     "$type": "dimension",
     "$extensions": {
       "org.primer.figma": {
@@ -328,7 +396,7 @@
   },
   "text-body-size-small": {
     "key": "{text.body.size.small}",
-    "$value": [null, "12px"],
+    "$value": ["0.75rem", "12px"],
     "$type": "dimension",
     "$extensions": {
       "org.primer.figma": {
@@ -415,9 +483,15 @@
   },
   "text-caption-shorthand": {
     "key": "{text.caption.shorthand}",
-    "$value": "400 ,12px/1.25 -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji'",
+    "$value": "400 0.75rem,12px/1.25 -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji'",
     "$type": "typography",
     "$description": "Compact small font with a smaller line height of 16px. Use it for single-line scenarios, as the small sizing doesn’t pass accessibility requirements.",
+    "$extensions": {
+      "org.primer.llm": {
+        "usage": ["caption", "label", "badge-text", "single-line-metadata"],
+        "rules": "Use only for single-line or short text. Does NOT meet accessibility requirements for body text."
+      }
+    },
     "filePath": "src/tokens/functional/typography/typography.json5",
     "isSource": true,
     "original": {
@@ -429,6 +503,12 @@
       },
       "$type": "typography",
       "$description": "Compact small font with a smaller line height of 16px. Use it for single-line scenarios, as the small sizing doesn’t pass accessibility requirements.",
+      "$extensions": {
+        "org.primer.llm": {
+          "usage": ["caption", "label", "badge-text", "single-line-metadata"],
+          "rules": "Use only for single-line or short text. Does NOT meet accessibility requirements for body text."
+        }
+      },
       "key": "{text.caption.shorthand}"
     },
     "name": "text-caption-shorthand",
@@ -437,7 +517,7 @@
   },
   "text-caption-size": {
     "key": "{text.caption.size}",
-    "$value": [null, "12px"],
+    "$value": ["0.75rem", "12px"],
     "$type": "dimension",
     "$extensions": {
       "org.primer.figma": {
@@ -527,6 +607,12 @@
     "$value": "400 0.8125rem,13px/1.5 ui-monospace, SFMono-Regular, SF Mono, Menlo, Consolas, Liberation Mono, monospace",
     "$type": "typography",
     "$description": "Default style for rendering code blocks.",
+    "$extensions": {
+      "org.primer.llm": {
+        "usage": ["code-block", "pre-element", "code-snippet", "terminal-output"],
+        "rules": "MUST use for multi-line code. Use monospace font stack."
+      }
+    },
     "filePath": "src/tokens/functional/typography/typography.json5",
     "isSource": true,
     "original": {
@@ -538,6 +624,12 @@
       },
       "$type": "typography",
       "$description": "Default style for rendering code blocks.",
+      "$extensions": {
+        "org.primer.llm": {
+          "usage": ["code-block", "pre-element", "code-snippet", "terminal-output"],
+          "rules": "MUST use for multi-line code. Use monospace font stack."
+        }
+      },
       "key": "{text.codeBlock.shorthand}"
     },
     "name": "text-codeBlock-shorthand",
@@ -557,7 +649,10 @@
     "filePath": "src/tokens/functional/typography/typography.json5",
     "isSource": true,
     "original": {
-      "$value": "13px",
+      "$value": {
+        "value": 13,
+        "unit": "px"
+      },
       "$type": "dimension",
       "$extensions": {
         "org.primer.figma": {
@@ -600,9 +695,15 @@
   },
   "text-codeInline-shorthand": {
     "key": "{text.codeInline.shorthand}",
-    "$value": "400 ,14.856px ui-monospace, SFMono-Regular, SF Mono, Menlo, Consolas, Liberation Mono, monospace",
+    "$value": "400 0.9285em,0.9285em ui-monospace, SFMono-Regular, SF Mono, Menlo, Consolas, Liberation Mono, monospace",
     "$type": "typography",
     "$description": "Inline code blocks using em units to inherit size from its parent.",
+    "$extensions": {
+      "org.primer.llm": {
+        "usage": ["inline-code", "code-element", "variable-name", "command"],
+        "rules": "Use for inline code within text. Size inherits from parent using em units."
+      }
+    },
     "filePath": "src/tokens/functional/typography/typography.json5",
     "isSource": true,
     "original": {
@@ -613,6 +714,12 @@
       },
       "$type": "typography",
       "$description": "Inline code blocks using em units to inherit size from its parent.",
+      "$extensions": {
+        "org.primer.llm": {
+          "usage": ["inline-code", "code-element", "variable-name", "command"],
+          "rules": "Use for inline code within text. Size inherits from parent using em units."
+        }
+      },
       "key": "{text.codeInline.shorthand}"
     },
     "name": "text-codeInline-shorthand",
@@ -621,7 +728,7 @@
   },
   "text-codeInline-size": {
     "key": "{text.codeInline.size}",
-    "$value": [null, "14.856px"],
+    "$value": ["0.9285em", "0.9285em"],
     "$type": "dimension",
     "$extensions": {
       "org.primer.figma": {
@@ -632,7 +739,10 @@
     "filePath": "src/tokens/functional/typography/typography.json5",
     "isSource": true,
     "original": {
-      "$value": "0.9285em",
+      "$value": {
+        "value": 0.9285,
+        "unit": "em"
+      },
       "$type": "dimension",
       "$extensions": {
         "org.primer.figma": {
@@ -743,9 +853,15 @@
   },
   "text-display-shorthand": {
     "key": "{text.display.shorthand}",
-    "$value": "500 ,40px/1.375 -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji'",
+    "$value": "500 2.5rem,40px/1.375 -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji'",
     "$type": "typography",
     "$description": "Hero-style text for brand to product transition pages. Utilize Title (large) styles on narrow viewports.",
+    "$extensions": {
+      "org.primer.llm": {
+        "usage": ["hero-section", "landing-page", "marketing-header"],
+        "rules": "Use sparingly for hero sections. Switch to title.large on narrow viewports."
+      }
+    },
     "filePath": "src/tokens/functional/typography/typography.json5",
     "isSource": true,
     "original": {
@@ -757,6 +873,12 @@
       },
       "$type": "typography",
       "$description": "Hero-style text for brand to product transition pages. Utilize Title (large) styles on narrow viewports.",
+      "$extensions": {
+        "org.primer.llm": {
+          "usage": ["hero-section", "landing-page", "marketing-header"],
+          "rules": "Use sparingly for hero sections. Switch to title.large on narrow viewports."
+        }
+      },
       "key": "{text.display.shorthand}"
     },
     "name": "text-display-shorthand",
@@ -765,7 +887,7 @@
   },
   "text-display-size": {
     "key": "{text.display.size}",
-    "$value": [null, "40px"],
+    "$value": ["2.5rem", "40px"],
     "$type": "dimension",
     "$extensions": {
       "org.primer.figma": {
@@ -852,9 +974,15 @@
   },
   "text-subtitle-shorthand": {
     "key": "{text.subtitle.shorthand}",
-    "$value": "400 ,20px/1.625 -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji'",
+    "$value": "400 1.25rem,20px/1.625 -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji'",
     "$type": "typography",
     "$description": "Page sections/sub headings, or less important object names in page titles (automated action titles, for example). Same line-height as title (medium).",
+    "$extensions": {
+      "org.primer.llm": {
+        "usage": ["subtitle", "description", "secondary-heading", "lead-text"],
+        "rules": "Use below titles for supporting text. Normal weight distinguishes from title styles."
+      }
+    },
     "filePath": "src/tokens/functional/typography/typography.json5",
     "isSource": true,
     "original": {
@@ -866,6 +994,12 @@
       },
       "$type": "typography",
       "$description": "Page sections/sub headings, or less important object names in page titles (automated action titles, for example). Same line-height as title (medium).",
+      "$extensions": {
+        "org.primer.llm": {
+          "usage": ["subtitle", "description", "secondary-heading", "lead-text"],
+          "rules": "Use below titles for supporting text. Normal weight distinguishes from title styles."
+        }
+      },
       "key": "{text.subtitle.shorthand}"
     },
     "name": "text-subtitle-shorthand",
@@ -874,7 +1008,7 @@
   },
   "text-subtitle-size": {
     "key": "{text.subtitle.size}",
-    "$value": [null, "20px"],
+    "$value": ["1.25rem", "20px"],
     "$type": "dimension",
     "$extensions": {
       "org.primer.figma": {
@@ -1027,9 +1161,15 @@
   },
   "text-title-shorthand-large": {
     "key": "{text.title.shorthand.large}",
-    "$value": "600 ,32px/1.5 -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji'",
+    "$value": "600 2rem,32px/1.5 -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji'",
     "$type": "typography",
     "$description": "Page headings for user-created objects, such as issues or pull requests. Utilize title (medium) styles on narrow viewports.",
+    "$extensions": {
+      "org.primer.llm": {
+        "usage": ["page-heading", "issue-title", "pr-title", "h1"],
+        "rules": "Use for primary page headings. Switch to title.medium on narrow viewports."
+      }
+    },
     "filePath": "src/tokens/functional/typography/typography.json5",
     "isSource": true,
     "original": {
@@ -1041,6 +1181,12 @@
       },
       "$type": "typography",
       "$description": "Page headings for user-created objects, such as issues or pull requests. Utilize title (medium) styles on narrow viewports.",
+      "$extensions": {
+        "org.primer.llm": {
+          "usage": ["page-heading", "issue-title", "pr-title", "h1"],
+          "rules": "Use for primary page headings. Switch to title.medium on narrow viewports."
+        }
+      },
       "key": "{text.title.shorthand.large}"
     },
     "name": "text-title-shorthand-large",
@@ -1049,9 +1195,15 @@
   },
   "text-title-shorthand-medium": {
     "key": "{text.title.shorthand.medium}",
-    "$value": "600 ,20px/1.625 -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji'",
+    "$value": "600 1.25rem,20px/1.625 -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji'",
     "$type": "typography",
     "$description": "Default page title. The 32px-equivalent line-height matches with button and other medium control heights. Great for page header composition.",
+    "$extensions": {
+      "org.primer.llm": {
+        "usage": ["section-heading", "card-title", "dialog-title", "h2"],
+        "rules": "RECOMMENDED default for page titles. Use for section headings and dialog titles."
+      }
+    },
     "filePath": "src/tokens/functional/typography/typography.json5",
     "isSource": true,
     "original": {
@@ -1063,6 +1215,12 @@
       },
       "$type": "typography",
       "$description": "Default page title. The 32px-equivalent line-height matches with button and other medium control heights. Great for page header composition.",
+      "$extensions": {
+        "org.primer.llm": {
+          "usage": ["section-heading", "card-title", "dialog-title", "h2"],
+          "rules": "RECOMMENDED default for page titles. Use for section headings and dialog titles."
+        }
+      },
       "key": "{text.title.shorthand.medium}"
     },
     "name": "text-title-shorthand-medium",
@@ -1071,9 +1229,15 @@
   },
   "text-title-shorthand-small": {
     "key": "{text.title.shorthand.small}",
-    "$value": "600 ,16px/1.5 -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji'",
+    "$value": "600 1rem,16px/1.5 -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji'",
     "$type": "typography",
     "$description": "Uses the same size as body (large) with a heavier weight of semibold (600).",
+    "$extensions": {
+      "org.primer.llm": {
+        "usage": ["subsection-heading", "list-title", "h3", "sidebar-heading"],
+        "rules": "Use for smaller headings within sections. Same size as body.large but semibold."
+      }
+    },
     "filePath": "src/tokens/functional/typography/typography.json5",
     "isSource": true,
     "original": {
@@ -1085,6 +1249,12 @@
       },
       "$type": "typography",
       "$description": "Uses the same size as body (large) with a heavier weight of semibold (600).",
+      "$extensions": {
+        "org.primer.llm": {
+          "usage": ["subsection-heading", "list-title", "h3", "sidebar-heading"],
+          "rules": "Use for smaller headings within sections. Same size as body.large but semibold."
+        }
+      },
       "key": "{text.title.shorthand.small}"
     },
     "name": "text-title-shorthand-small",
@@ -1093,7 +1263,7 @@
   },
   "text-title-size-large": {
     "key": "{text.title.size.large}",
-    "$value": [null, "32px"],
+    "$value": ["2rem", "32px"],
     "$type": "dimension",
     "$extensions": {
       "org.primer.figma": {
@@ -1120,7 +1290,7 @@
   },
   "text-title-size-medium": {
     "key": "{text.title.size.medium}",
-    "$value": [null, "20px"],
+    "$value": ["1.25rem", "20px"],
     "$type": "dimension",
     "$extensions": {
       "org.primer.figma": {
@@ -1147,7 +1317,7 @@
   },
   "text-title-size-small": {
     "key": "{text.title.size.small}",
-    "$value": [null, "16px"],
+    "$value": ["1rem", "16px"],
     "$type": "dimension",
     "$extensions": {
       "org.primer.figma": {

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "@primer/primitives",
-  "version": "11.4.0-rc.f798df25",
+  "version": "11.4.1-rc.4e2d1de5",
   "description": "Typography, spacing, and color primitives for Primer design system",
   "type": "module",
   "files": [
     "dist",
-    "src/tokens"
+    "src/tokens",
+    "DESIGN_TOKENS_SPEC.md",
+    "DESIGN_TOKENS_GUIDE.md"
   ],
   "repository": "https://github.com/primer/primitives",
   "keywords": [
@@ -23,11 +25,12 @@
   },
   "homepage": "https://github.com/primer/primitives#readme",
   "scripts": {
-    "build": "npm run clean && npm run build:tokens && npm run build:fallbacks && npm run build:figma && npm run build:config",
+    "build": "npm run clean && npm run build:tokens && npm run build:fallbacks && npm run build:figma && npm run build:config && npm run build:llm",
     "build:tokens": "tsx ./scripts/buildTokens.ts",
     "build:fallbacks": "tsx ./scripts/buildFallbacks.ts",
     "build:figma": "tsx scripts/buildFigma.ts",
     "build:config": "tsc -p build.tsconfig.jsonc && tsx ./scripts/copyDir.ts src/types dist/build/types",
+    "build:llm": "tsx ./scripts/buildLlm.ts",
     "clean": "rm -rf dist",
     "validate:contrast": "tsx scripts/colorContrast.ts",
     "format": "prettier --check '**/*.{js,jsx,ts,tsx,md,mdx,css}'",

package/src/tokens/base/motion/easing.json5

@@ -4,22 +4,57 @@
       linear: {
         $value: [0, 0, 1, 1],
         $type: 'cubicBezier',
-        $description: 'Ideal for non-movement properties, like opacity or background color.',
+        $description: 'Constant motion with no acceleration. Use for continuous animations like progress bars or loaders.',
+        $extensions: {
+          'org.primer.llm': {
+            usage: ['progress-bar', 'loader', 'continuous-animation', 'scrolling'],
+            rules: 'Use if the motion is constant.',
+          },
+        },
+      },
+      ease: {
+        $value: [0.25, 0.1, 0.25, 1],
+        $type: 'cubicBezier',
+        $description: 'CSS default easing. Use for hover state changes and micro-interactions.',
+        $extensions: {
+          'org.primer.llm': {
+            usage: ['hover-state', 'micro-interaction', 'button-hover', 'link-hover'],
+            rules: 'Use for hover state changes.',
+          },
+        },
       },
       easeIn: {
         $value: [0.7, 0.1, 0.75, 0.9],
         $type: 'cubicBezier',
-        $description: 'Ideal for movement that starts on the page and ends off the page.',
+        $description: 'Accelerating motion. Use for elements exiting the viewport (moving off-screen).',
+        $extensions: {
+          'org.primer.llm': {
+            usage: ['exit-animation', 'element-leaving', 'off-screen-motion'],
+            rules: 'Rarely used alone. Prefer ease-out for most exit animations.',
+          },
+        },
       },
       easeOut: {
         $value: [0.3, 0.8, 0.6, 1],
         $type: 'cubicBezier',
-        $description: 'Ideal for movement that starts off the page and ends on the page.',
+        $description: 'Decelerating motion. Use for elements entering the viewport or appearing on screen.',
+        $extensions: {
+          'org.primer.llm': {
+            usage: ['enter-animation', 'element-appearing', 'modal-open', 'dropdown-open', 'tooltip-appear'],
+            rules: 'RECOMMENDED default. Use if an element enters or exits the viewport.',
+          },
+        },
       },
       easeInOut: {
         $value: [0.6, 0, 0.2, 1],
         $type: 'cubicBezier',
-        $description: 'Ideal for movement that starts and ends on the page.',
+        $description: 'Smooth acceleration and deceleration. Use for elements moving or morphing within the viewport.',
+        $extensions: {
+          'org.primer.llm': {
+            usage: ['position-change', 'size-change', 'morph-animation', 'expand-collapse', 'slide-transition'],
+            rules: 'Use if an element moves or morphs on screen.',
+          },
+        },
       },
     },
   },