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

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

@@ -240,7 +240,7 @@
   },
   "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": {
@@ -274,7 +274,7 @@
   },
   "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": {
@@ -308,7 +308,7 @@
   },
   "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": {
@@ -342,7 +342,7 @@
   },
   "text-body-size-large": {
     "key": "{text.body.size.large}",
-    "$value": [null, "16px"],
+    "$value": ["1rem", "16px"],
     "$type": "dimension",
     "$extensions": {
       "org.primer.figma": {
@@ -369,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": {
@@ -396,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": {
@@ -483,7 +483,7 @@
   },
   "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": {
@@ -517,7 +517,7 @@
   },
   "text-caption-size": {
     "key": "{text.caption.size}",
-    "$value": [null, "12px"],
+    "$value": ["0.75rem", "12px"],
     "$type": "dimension",
     "$extensions": {
       "org.primer.figma": {
@@ -649,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": {
@@ -692,7 +695,7 @@
   },
   "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": {
@@ -725,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": {
@@ -736,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": {
@@ -847,7 +853,7 @@
   },
   "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": {
@@ -881,7 +887,7 @@
   },
   "text-display-size": {
     "key": "{text.display.size}",
-    "$value": [null, "40px"],
+    "$value": ["2.5rem", "40px"],
     "$type": "dimension",
     "$extensions": {
       "org.primer.figma": {
@@ -968,7 +974,7 @@
   },
   "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": {
@@ -1002,7 +1008,7 @@
   },
   "text-subtitle-size": {
     "key": "{text.subtitle.size}",
-    "$value": [null, "20px"],
+    "$value": ["1.25rem", "20px"],
     "$type": "dimension",
     "$extensions": {
       "org.primer.figma": {
@@ -1155,7 +1161,7 @@
   },
   "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": {
@@ -1189,7 +1195,7 @@
   },
   "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": {
@@ -1223,7 +1229,7 @@
   },
   "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": {
@@ -1257,7 +1263,7 @@
   },
   "text-title-size-large": {
     "key": "{text.title.size.large}",
-    "$value": [null, "32px"],
+    "$value": ["2rem", "32px"],
     "$type": "dimension",
     "$extensions": {
       "org.primer.figma": {
@@ -1284,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": {
@@ -1311,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,13 +1,13 @@
 {
   "name": "@primer/primitives",
-  "version": "11.4.0",
+  "version": "11.4.1-rc.4e2d1de5",
   "description": "Typography, spacing, and color primitives for Primer design system",
   "type": "module",
   "files": [
     "dist",
     "src/tokens",
-    "token-guidelines.llm.md",
-    "guidelines"
+    "DESIGN_TOKENS_SPEC.md",
+    "DESIGN_TOKENS_GUIDE.md"
   ],
   "repository": "https://github.com/primer/primitives",
   "keywords": [
@@ -25,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}'",
@@ -79,4 +80,4 @@
     "zod": "^4.1.3",
     "zod-validation-error": "^4.0.1"
   }
-}
+}

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

@@ -2,51 +2,51 @@
   base: {
     duration: {
       '0': {
-        $value: '0ms',
+        $value: {value: 0, unit: 'ms'},
         $type: 'duration',
       },
       '50': {
-        $value: '50ms',
+        $value: {value: 50, unit: 'ms'},
         $type: 'duration',
       },
       '100': {
-        $value: '100ms',
+        $value: {value: 100, unit: 'ms'},
         $type: 'duration',
       },
       '200': {
-        $value: '200ms',
+        $value: {value: 200, unit: 'ms'},
         $type: 'duration',
       },
       '300': {
-        $value: '300ms',
+        $value: {value: 300, unit: 'ms'},
         $type: 'duration',
       },
       '400': {
-        $value: '400ms',
+        $value: {value: 400, unit: 'ms'},
         $type: 'duration',
       },
       '500': {
-        $value: '500ms',
+        $value: {value: 500, unit: 'ms'},
         $type: 'duration',
       },
       '600': {
-        $value: '600ms',
+        $value: {value: 600, unit: 'ms'},
         $type: 'duration',
       },
       '700': {
-        $value: '700ms',
+        $value: {value: 700, unit: 'ms'},
         $type: 'duration',
       },
       '800': {
-        $value: '800ms',
+        $value: {value: 800, unit: 'ms'},
         $type: 'duration',
       },
       '900': {
-        $value: '900ms',
+        $value: {value: 900, unit: 'ms'},
         $type: 'duration',
       },
       '1000': {
-        $value: '1000ms',
+        $value: {value: 1000, unit: 'ms'},
         $type: 'duration',
       },
     },

package/src/tokens/base/size/size.json5

@@ -2,7 +2,7 @@
   "base": {
     "size": {
       "2": {
-        "$value": "2px",
+        "$value": { "value": 2, "unit": "px" },
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -12,7 +12,7 @@
         }
       },
       "4": {
-        "$value": "4px",
+        "$value": { "value": 4, "unit": "px" },
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -22,7 +22,7 @@
         }
       },
       "6": {
-        "$value": "6px",
+        "$value": { "value": 6, "unit": "px" },
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -32,7 +32,7 @@
         }
       },
       "8": {
-        "$value": "8px",
+        "$value": { "value": 8, "unit": "px" },
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -42,7 +42,7 @@
         }
       },
       "12": {
-        "$value": "12px",
+        "$value": { "value": 12, "unit": "px" },
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -52,7 +52,7 @@
         }
       },
       "16": {
-        "$value": "16px",
+        "$value": { "value": 16, "unit": "px" },
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -62,7 +62,7 @@
         }
       },
       "20": {
-        "$value": "20px",
+        "$value": { "value": 20, "unit": "px" },
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -72,7 +72,7 @@
         }
       },
       "24": {
-        "$value": "24px",
+        "$value": { "value": 24, "unit": "px" },
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -82,7 +82,7 @@
         }
       },
       "28": {
-        "$value": "28px",
+        "$value": { "value": 28, "unit": "px" },
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -92,7 +92,7 @@
         }
       },
       "32": {
-        "$value": "32px",
+        "$value": { "value": 32, "unit": "px" },
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -102,7 +102,7 @@
         }
       },
       "36": {
-        "$value": "36px",
+        "$value": { "value": 36, "unit": "px" },
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -112,7 +112,7 @@
         }
       },
       "40": {
-        "$value": "40px",
+        "$value": { "value": 40, "unit": "px" },
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -122,7 +122,7 @@
         }
       },
       "44": {
-        "$value": "44px",
+        "$value": { "value": 44, "unit": "px" },
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -132,7 +132,7 @@
         }
       },
       "48": {
-        "$value": "48px",
+        "$value": { "value": 48, "unit": "px" },
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -142,7 +142,7 @@
         }
       },
       "64": {
-        "$value": "64px",
+        "$value": { "value": 64, "unit": "px" },
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -152,7 +152,7 @@
         }
       },
       "80": {
-        "$value": "80px",
+        "$value": { "value": 80, "unit": "px" },
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -162,7 +162,7 @@
         }
       },
       "96": {
-        "$value": "96px",
+        "$value": { "value": 96, "unit": "px" },
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -172,7 +172,7 @@
         }
       },
       "112": {
-        "$value": "112px",
+        "$value": { "value": 112, "unit": "px" },
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {
@@ -182,7 +182,7 @@
         }
       },
       "128": {
-        "$value": "128px",
+        "$value": { "value": 128, "unit": "px" },
         "$type": "dimension",
         "$extensions": {
           "org.primer.figma": {

package/src/tokens/base/typography/typography.json5

@@ -3,7 +3,7 @@
     text: {
       size: {
         xs: {
-          $value: '0.75rem',
+          $value: {value: 0.75, unit: 'rem'},
           $type: 'dimension',
           $description: '12px - Smallest text size for captions and compact UI elements.',
           $extensions: {
@@ -14,7 +14,7 @@
           },
         },
         sm: {
-          $value: '0.875rem',
+          $value: {value: 0.875, unit: 'rem'},
           $type: 'dimension',
           $description: '14px - Default body text size for UI.',
           $extensions: {
@@ -25,7 +25,7 @@
           },
         },
         md: {
-          $value: '1rem',
+          $value: {value: 1, unit: 'rem'},
           $type: 'dimension',
           $description: '16px - Large body text and small titles.',
           $extensions: {
@@ -36,7 +36,7 @@
           },
         },
         lg: {
-          $value: '1.25rem',
+          $value: {value: 1.25, unit: 'rem'},
           $type: 'dimension',
           $description: '20px - Medium titles and subtitles.',
           $extensions: {
@@ -47,7 +47,7 @@
           },
         },
         xl: {
-          $value: '2rem',
+          $value: {value: 2, unit: 'rem'},
           $type: 'dimension',
           $description: '32px - Large titles and page headings.',
           $extensions: {
@@ -58,7 +58,7 @@
           },
         },
         '2xl': {
-          $value: '2.5rem',
+          $value: {value: 2.5, unit: 'rem'},
           $type: 'dimension',
           $description: '40px - Display text for hero sections.',
           $extensions: {

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

@@ -138,6 +138,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.',
+        },
       },
     },
     black: {
@@ -153,6 +157,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.',
+        },
       },
     },
     disabled: {

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

@@ -1,5 +1,12 @@
 {
   display: {
+    $description: 'Decorative colors for categorization and visual distinction without semantic meaning. Use for labels, tags, avatars, status indicators, and user-assigned colors. Do NOT use for success/error/warning states—use semantic colors (bgColor.success/danger/attention) instead.',
+    $extensions: {
+      'org.primer.llm': {
+        usage: ['label', 'tag', 'avatar', 'badge', 'category-indicator', 'user-assigned-color', 'project-color', 'decorative-element'],
+        rules: 'Use display colors for arbitrary categorization where the color has no inherent meaning (e.g., project labels, user avatars). For meaningful states like success, error, or warning, use semantic colors instead. Scales 0-2 are lighter (backgrounds), 3-5 are mid-tones, 6-9 are darker (foregrounds/borders).',
+      },
+    },
     blue: {
       scale: {
         '0': {

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

@@ -108,6 +108,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.',
+        },
       },
     },
     black: {
@@ -123,6 +127,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.',
+        },
       },
     },
     disabled: {

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

@@ -1,6 +1,13 @@
 {
   color: {
     ansi: {
+      $description: 'ANSI terminal color palette for command-line interfaces and terminal emulators. Maps standard ANSI color names to theme-appropriate values.',
+      $extensions: {
+        'org.primer.llm': {
+          usage: ['terminal-output', 'cli-interface', 'console-text', 'shell-prompt'],
+          rules: 'Use exclusively for terminal/CLI contexts. Do NOT use for general UI—use semantic colors (fgColor, bgColor) instead. These colors follow ANSI naming conventions (black, red, green, yellow, blue, magenta, cyan, white) with bright variants.',
+        },
+      },
       black: {
         $value: '{base.color.neutral.13}',
         $type: 'color',
@@ -248,6 +255,13 @@
       },
     },
     prettylights: {
+      $description: 'Syntax highlighting colors for code display. Used by GitHub code rendering (prettylights theme).',
+      $extensions: {
+        'org.primer.llm': {
+          usage: ['code-syntax-highlighting', 'code-block', 'inline-code', 'diff-view'],
+          rules: 'Use exclusively for syntax highlighting in code display contexts. Do NOT use for general UI text or backgrounds. Each token maps to a specific syntax element (comment, keyword, string, etc.).',
+        },
+      },
       syntax: {
         comment: {
           $value: '{base.color.neutral.9}',