@primer/primitives 11.4.1-rc.eb8ee149 → 11.5.0-rc.14eaeb12

package/DESIGN_TOKENS_GUIDE.md

@@ -0,0 +1,185 @@
+# Design Tokens Master Guide
+
+> Metadata: This file defines the Logic and Rules for the design system. For individual token definitions and raw values, refer to DESIGN_TOKENS_SPEC.md.
+
+---
+
+## Core Rule
+
+**You are a CSS expert. Never use raw values (hex, px, etc.). Only use semantic tokens.**
+
+---
+
+## Logic Matrix: Color Pairings
+
+| Background Token       | Foreground Token       | Notes                     |
+| ---------------------- | ---------------------- | ------------------------- |
+| `--bgColor-*-emphasis` | `--fgColor-onEmphasis` | MUST pair                 |
+| `--bgColor-*-muted`    | `--fgColor-{semantic}` | MUST use semantic fg      |
+| `--bgColor-default`    | `--fgColor-default`    | Standard pairing          |
+| `--bgColor-muted`      | `--fgColor-default`    | NEVER use `fgColor-muted` |
+
+**Contrast Requirements:**
+
+| Context         | Ratio | Standard |
+| --------------- | ----- | -------- |
+| Normal text     | 4.5:1 | WCAG AA  |
+| Large text / UI | 3:1   | WCAG AA  |
+
+---
+
+## Pattern Compression
+
+### Control Tokens
+
+```
+--control-[size]-[property]
+  ├── size: xsmall | small | medium | large | xlarge
+  └── property: size | paddingInline-[density] | paddingBlock
+                 └── density: condensed | normal | spacious
+```
+
+### Stack Tokens
+
+```
+--stack-[property]-[size]
+  ├── property: gap | padding
+  └── size: condensed | normal | spacious
+
+--controlStack-[size]-gap-[density]
+  ├── size: small | medium | large
+  └── density: condensed | auto | spacious
+```
+
+### Typography Tokens
+
+```
+--text-[role]-shorthand-[size]
+  ├── role: display | title | body | subtitle | caption | codeBlock | codeInline
+  └── size: small | medium | large
+```
+
+---
+
+## Keyword Enforcement (RFC 2119)
+
+### Motion
+
+| Keyword | Rule                                                           |
+| ------- | -------------------------------------------------------------- |
+| MUST    | Use motion for interactive state changes (hover, focus, press) |
+| MUST    | Keep animations ≤300ms for UI interactions                     |
+| MUST    | Respect `prefers-reduced-motion` media query                   |
+| MUST    | Provide instant alternatives when motion is reduced            |
+| SHOULD  | Use 100-200ms for micro-interactions                           |
+| SHOULD  | Use 200-300ms for state changes                                |
+| NEVER   | Exceed 500ms for UI interactions                               |
+| NEVER   | Use motion purely for decoration                               |
+| NEVER   | Create indefinitely looping motion without user control        |
+| NEVER   | Rely solely on motion to convey information                    |
+
+### Typography
+
+| Keyword    | Rule                                                                                                            |
+| ---------- | --------------------------------------------------------------------------------------------------------------- |
+| **MUST**   | Use **shorthand** tokens (e.g., `font: var(...)`) to ensure `line-height` and `font-weight` are synchronized.   |
+| **MUST**   | Use `text-codeBlock` for multi-line blocks and `text-codeInline` for inline spans.                              |
+| **SHOULD** | Match the token to the **semantic role** (e.g., use `title` tokens for headers, not just a large `body` token). |
+| **SHOULD** | Downgrade one size level for mobile viewports (e.g., `title-large` → `title-medium`).                           |
+| **NEVER**  | Use individual `font-size` or `line-height` tokens if a shorthand variant is available.                         |
+| **NEVER**  | Use `text-caption-shorthand` for multi-line body text (accessibility/readability failure).                      |
+
+### Spacing
+
+| Keyword | Rule                                        |
+| ------- | ------------------------------------------- |
+| MUST    | Use control tokens for interactive elements |
+| MUST    | Use stack tokens for layout spacing         |
+| MUST    | Match padding density to control's purpose  |
+| SHOULD  | Use `medium` size as default                |
+
+---
+
+## Decision Tree: Easing Selection
+
+1. Is element entering/exiting viewport? → ease-out (default)
+2. Is element moving/morphing on screen? → ease-in-out
+3. Is this a hover state change? → ease
+4. Is this constant motion (loaders)? → linear
+
+---
+
+## Golden Example: Reference Component
+
+```css
+/* Button: All 5 interactive states with correct token usage */
+.btn {
+  /* Base styles */
+  background-color: var(--control-bgColor-rest);
+  color: var(--fgColor-default);
+  border: none;
+  border-radius: var(--borderRadius-medium);
+  padding-block: var(--control-medium-paddingBlock);
+  padding-inline: var(--control-medium-paddingInline-normal);
+  font: var(--text-body-shorthand-medium);
+  cursor: pointer;
+
+  /* Motion: MUST be <300ms */
+  transition:
+    background-color 150ms ease,
+    box-shadow 150ms ease,
+    transform 100ms ease;
+}
+
+/* State: Hover */
+.btn:hover {
+  background-color: var(--control-bgColor-hover);
+}
+
+/* State: Focus-visible (MUST use :focus-visible, not :focus) */
+.btn:focus-visible {
+  outline: var(--focus-outline);
+  outline-offset: var(--outline-focus-offset);
+}
+
+/* State: Active/Pressed */
+.btn:active {
+  background-color: var(--control-bgColor-active);
+  transform: scale(0.98);
+}
+
+/* State: Disabled */
+.btn:disabled {
+  background-color: var(--bgColor-disabled);
+  color: var(--fgColor-disabled);
+  cursor: not-allowed;
+  opacity: 1; /* NEVER use opacity for disabled */
+}
+
+/* Accessibility: MUST respect reduced motion */
+@media (prefers-reduced-motion: reduce) {
+  .btn {
+    transition: none;
+  }
+}
+```
+
+---
+
+## Interactive States Checklist
+
+All interactive elements MUST define:
+
+| State    | Selector                               | Required                 |
+| -------- | -------------------------------------- | ------------------------ |
+| Rest     | `.element`                             | ✓                        |
+| Hover    | `:hover`                               | ✓                        |
+| Focus    | `:focus-visible`                       | ✓ (NEVER `:focus` alone) |
+| Active   | `:active`                              | ✓                        |
+| Disabled | `:disabled` / `[aria-disabled="true"]` | ✓                        |
+
+---
+
+## Hallucination Guard
+
+> **If you suggest a token name not found in this spec or the system, suffix it with `/* check-token */`.**

package/DESIGN_TOKENS_SPEC.md

@@ -1,5 +1,7 @@
 # Primer Design Token Guidelines
 
+> Metadata: This file is a Dictionary of tokens. For usage rules, contrast requirements, and motion logic, refer to DESIGN_TOKENS_GUIDE.md.
+
 Reference for using GitHub Primer design tokens.
 
 ## Legend
@@ -36,6 +38,10 @@ Background color tokens for surfaces, containers, and UI elements.
 - `bgColor-[accent, attention, closed, danger, done, neutral, open, severe, sponsors, success, upsell]-emphasis`
 - `bgColor-[accent, attention, closed, danger, done, neutral, open, severe, sponsors, success, upsell]-muted`
 
+### bgColor-black
+Pure black background
+**R:** Avoid using raw black. Use semantic alternatives: bg.emphasis for dark backgrounds, bg.inverse for inverted contexts. Raw black/white ignore theme preferences and accessibility settings.
+
 ### bgColor-default
 Default background color for pages and main content areas
 **U:** card-background, main-content, page-background
@@ -81,6 +87,10 @@ Fully transparent background
 **U:** ghost-button, icon-button, overlay-trigger
 **R:** Use for ghost/icon buttons or when element should blend with parent. Ensure sufficient contrast for interactive states.
 
+### bgColor-white
+Pure white background
+**R:** Avoid using raw white. Use semantic alternatives: bg.default for standard backgrounds, bg.inset for recessed areas, or bg.inverse for inverted contexts. Raw black/white ignore theme preferences and accessibility settings.
+
 ## Border
 
 Composite border tokens combining color, width, and style.
@@ -91,6 +101,12 @@ Composite border tokens combining color, width, and style.
 
 **Tokens:** border-default, border-disabled, border-emphasis, border-muted, border-transparent
 
+### draft
+**Tokens:** border-draft-emphasis, border-draft-muted
+
+### border-translucent
+Semi-transparent border shorthand for overlays and layered elements. Border-specific token — no bgColor-translucent counterpart exists by design.
+
 ## Border Colors
 
 Border color tokens for boundaries, dividers, and outlines.
@@ -130,10 +146,15 @@ Subtle border for secondary elements and light separators
 **R:** Use for subtle borders and separators. Less prominent than border.default.
 
 ### borderColor-translucent
-Semi-transparent border for overlays and layered elements
+Semi-transparent border for overlays and layered elements. Border-specific token — no bgColor-translucent counterpart exists by design.
 **U:** overlay-border, translucent-border
 **R:** Use for semi-transparent borders on overlays. Works well with translucent backgrounds.
 
+### borderColor-transparent
+Fully transparent border
+**U:** border-color, border-styling
+**R:** These are COLOR-ONLY tokens (resolve to a hex value like #cf222e). Use for the CSS `border-color` property. Do NOT use for the CSS `border` shorthand — use border.* tokens instead.
+
 ## Border Radius
 
 Corner radius tokens for rounded elements.
@@ -144,7 +165,7 @@ Use this border radius for pill shaped elements
 **R:** Use for avatars and pill-shaped elements. Do NOT use for rectangular containers.
 
 ### borderRadius-large
-Large border radius (12px). Use for larger containers, dialogs, or when more visual softness is desired. Always use this for buttons.
+Large border radius (12px). Use for larger containers, dialogs, or when more visual softness is desired.
 **U:** card, dialog, modal
 **R:** Recommended for dialogs and modals.
 
@@ -167,6 +188,44 @@ Thick 2px border for emphasis. Use for focus indicators, selected states, or to
 **U:** emphasis-border, focus-indicator, selected-state
 **R:** MUST use for focus rings on interactive elements. Do NOT use for subtle dividers.
 
+## Color
+### ANSI Terminal Colors
+
+ANSI terminal color palette for command-line interfaces and terminal emulators. Maps standard ANSI color names to theme-appropriate values.
+
+**U:** terminal-output, cli-interface, console-text
+**R:** 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.
+
+**Pattern:** `color-ansi-[color]` or `color-ansi-[color]-bright`
+
+**Variables:**
+- **color:** black | red | green | yellow | blue | magenta | cyan | white | gray
+- **variant:** default (no suffix) | bright
+
+### Syntax Highlighting (prettylights)
+
+Syntax highlighting colors for code display. Used by GitHub code rendering (prettylights theme).
+
+**U:** code-syntax-highlighting, code-block, inline-code
+**R:** 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.).
+
+**Pattern:** `color-prettylights-syntax-[element]`
+
+**Core elements:** comment, constant, entity, keyword, string, variable
+
+**Compound elements:**
+- `brackethighlighter-[angle, unmatched]`
+- `carriage-[return]-[bg, text]`
+- `constant-[other-reference-link]`
+- `entity-[tag]`
+- `invalid-[illegal]-[bg, text]`
+- `markup-[bold, heading, italic, list]`
+- `markup-[changed, deleted, ignored, inserted]-[bg, text]`
+- `meta-[diff-range]`
+- `storage-[modifier-import]`
+- `string-[regexp]`
+- `sublimelinter-[gutter-mark]`
+
 ## Controls
 
 Tokens for interactive controls like buttons, inputs, and selects.
@@ -174,9 +233,7 @@ Tokens for interactive controls like buttons, inputs, and selects.
 **Scale:** Use xsmall/small for dense layouts, medium for default UI, large/xlarge for prominent CTAs.
 
 **Size patterns:**
-- `control-[xsmall, small, medium, large, xlarge]-[gap, lineBoxHeight, paddingBlock, paddingInline-normal, size]`
-- `control-[xsmall, medium, large, xlarge]-paddingInline-spacious`
-- `control-[xsmall, small, medium]-paddingInline-condensed`
+- `control-[xsmall, small, medium, large, xlarge]-[gap, lineBoxHeight, paddingBlock, paddingInline-condensed, paddingInline-normal, paddingInline-spacious, size]`
 
 **State variants:**
 - `control-checked-[bgColor-active, bgColor-disabled, bgColor-hover, bgColor-rest, borderColor-active, borderColor-disabled, borderColor-hover, borderColor-rest, fgColor-disabled, fgColor-rest]`
@@ -220,12 +277,40 @@ Colors for toggle switch tracks (the background rail that the knob slides along)
 
 ## Data Visualization
 
-Colors for data visualization including charts, graphs, and diagrams. Use these colors to differentiate data series. Emphasis variants are for lines, bars, and borders. Muted variants are for area fills and backgrounds.
+Color tokens for charts, graphs, and diagrams. Use emphasis variants for lines/bars, muted variants for fills.
 
-**U:** bar-fill, chart-series, graph-line
+**U:** chart-series, graph-line, bar-fill
 **R:** Use data colors for visualizations only. Do NOT use for semantic meaning (use bg.success/danger instead). When using multiple series, ensure sufficient contrast between adjacent colors. Pair emphasis with muted variants of the same color for cohesive styling.
 
-**Tokens:** data-auburn-color-emphasis, data-auburn-color-muted, data-blue-color-emphasis, data-blue-color-muted, data-brown-color-emphasis, data-brown-color-muted, data-coral-color-emphasis, data-coral-color-muted, data-gray-color-emphasis, data-gray-color-muted, data-green-color-emphasis, data-green-color-muted, data-lemon-color-emphasis, data-lemon-color-muted, data-lime-color-emphasis, data-lime-color-muted, data-olive-color-emphasis, data-olive-color-muted, data-orange-color-emphasis, data-orange-color-muted, data-pine-color-emphasis, data-pine-color-muted, data-pink-color-emphasis, data-pink-color-muted, data-plum-color-emphasis, data-plum-color-muted, data-purple-color-emphasis, data-purple-color-muted, data-red-color-emphasis, data-red-color-muted, data-teal-color-emphasis, data-teal-color-muted, data-yellow-color-emphasis, data-yellow-color-muted
+**Pattern:** `data-[color]-color-[variant]`
+
+**Variables:**
+- **color:** auburn | blue | brown | coral | gray | green | lemon | lime | olive | orange | pine | pink | plum | purple | red | teal | yellow
+- **variant:** emphasis | muted
+
+**Variant usage:**
+- **emphasis:** Lines, bars, borders, data points
+- **muted:** Area fills, backgrounds, subtle regions
+
+*Pair emphasis with muted variants of the same color for cohesive chart styling.*
+
+## Display Colors
+
+Decorative colors for categorization without semantic meaning. Use for labels, tags, avatars, and user-assigned colors. Do NOT use for success/error/warning—use semantic colors instead.
+
+**U:** label, tag, avatar
+**R:** 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).
+
+**Pattern:** `display-[color]-[property]`
+
+**Variables:**
+- **color:** auburn | blue | brown | coral | cyan | gray | green | indigo | lemon | lime | olive | orange | pine | pink | plum | purple | red | teal | yellow
+- **property:** bgColor-emphasis | bgColor-muted | borderColor-emphasis | borderColor-muted | fgColor
+
+**Scale pattern:** `display-[color]-scale-[n]`
+- **n:** 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
+
+*Scale 0-2: lighter (backgrounds), 3-5: mid-tones, 6-9: darker (foregrounds/borders)*
 
 ## Easing
 
@@ -263,6 +348,10 @@ Text and icon color tokens.
 **Semantic tokens** (see Semantic Key for meaning):
 - `fgColor-[accent, attention, closed, danger, done, neutral, open, severe, sponsors, success, upsell]`
 
+### fgColor-black
+Pure black text
+**R:** Avoid using raw black. Use semantic alternatives: fg.default for standard text, fg.muted for secondary text. Raw black/white ignore theme preferences and accessibility settings.
+
 ### fgColor-default
 Default text color for primary content and headings
 **U:** body-text, default-text, heading
@@ -298,6 +387,10 @@ Text color for use on inverse backgrounds
 **U:** inverse-text, text-on-inverse
 **R:** Use for text on bg.inverse. Provides appropriate contrast in both themes.
 
+### fgColor-white
+Pure white text
+**R:** Avoid using raw white. Use semantic alternatives: fg.onEmphasis for text on dark backgrounds, fg.onInverse for inverted contexts. Raw black/white ignore theme preferences and accessibility settings.
+
 ## Focus
 
 Focus ring and outline tokens for keyboard navigation accessibility.
@@ -377,11 +470,46 @@ Large floating shadow for modals and dialogs
 **U:** dialog, full-screen-overlay, modal
 **R:** MUST use for modals and dialogs. Do NOT use for small floating elements.
 
+### shadow-floating-legacy
+Legacy floating shadow for backward compatibility
+**U:** backward-compatibility, legacy-component
+**R:** DEPRECATED: Use shadow-floating-small instead. Only use for maintaining backward compatibility with existing implementations.
+
+### shadow-floating-medium
+Medium floating shadow for popovers and action menus
+**U:** action-menu, popover, select-panel
+**R:** 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.
+
 ### shadow-floating-small
 Small floating shadow for dropdowns, tooltips, and small overlays
 **U:** dropdown, popover, tooltip
 **R:** Use for small floating elements like dropdowns and tooltips. Do NOT use for modals or dialogs.
 
+### shadow-floating-xlarge
+Extra large floating shadow for full-screen overlays and sheets
+**U:** drawer, full-screen-overlay, side-sheet
+**R:** 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.
+
+### shadow-inset
+Inset shadow for recessed elements
+**U:** input-field, pressed-button, recessed-area
+**R:** Use for elements that appear pressed or inset into the surface. Commonly used for input fields and wells. Do NOT use for floating elements.
+
+### shadow-resting-medium
+Medium resting shadow for cards and elevated surfaces
+**U:** card, elevated-surface, panel
+**R:** 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.
+
+### shadow-resting-small
+Small resting shadow for buttons and interactive elements
+**U:** button, clickable-element, interactive-card
+**R:** Use for buttons and small interactive elements at rest. Provides subtle depth and clickable affordance. RECOMMENDED for default button shadows.
+
+### shadow-resting-xsmall
+Extra small resting shadow for minimal elevation
+**U:** badge, chip, small-card
+**R:** Use for very subtle elevation on small elements. Provides minimal lift from surface. Do NOT use for interactive elements needing clear affordance.
+
 ## Spinner
 
 Loading spinner size and stroke tokens.

package/dist/build/formats/jsonFigma.js

@@ -35,10 +35,17 @@ const getFigmaType = (type) => {
     throw new Error(`Invalid type: ${type}`);
 };
 const shadowToVariables = (name, values, token) => {
+    // Helper to extract numeric value from W3C dimension object
+    const getDimensionValue = (dim) => {
+        if (typeof dim === 'object' && 'value' in dim) {
+            return dim.value;
+        }
+        throw new Error(`Invalid shadow dimension: expected W3C object format, got ${JSON.stringify(dim)}`);
+    };
     // floatValue
     const floatValue = (property) => ({
         name: `${name}/${property}`,
-        value: parseInt(values[property].replace('px', '')),
+        value: getDimensionValue(values[property]),
         type: 'FLOAT',
         scopes: ['EFFECT_FLOAT'],
         mode,