# 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

- **U:** Use cases
- **R:** Token-specific rules (see Semantic Key for general meaning)
- **emphasis** variant: Strong/prominent version, use `fg.onEmphasis` for text
- **muted** variant: Subtle version, use matching `fg.*` color for text
- **[a, b]** Bracket notation groups related tokens

## Semantic Key

These semantic meanings apply across all token types (bgColor, borderColor, fgColor, border).

| Semantic | Meaning | Example Usage | Text Pairing |
|---|---|---|---|
| **danger** | Errors, destructive actions, critical warnings | delete buttons, error messages, validation errors | fg.danger (muted bg) or fg.onEmphasis (emphasis bg) |
| **success** | Positive states, confirmations, completed actions | merge buttons, success messages, confirmations | fg.success (muted bg) or fg.onEmphasis (emphasis bg) |
| **attention** | Warnings, caution states requiring user awareness | warning banners, caution labels, pending states | fg.attention (muted bg) or fg.default (emphasis bg, due to yellow contrast) |
| **severe** | High-priority warnings, more urgent than attention | urgent messages, escalations, high-priority indicators | fg.severe (muted bg) or fg.onEmphasis (emphasis bg) |
| **accent** | Selected, focused, or highlighted interactive elements | active states, selected rows, focus indicators | fg.accent (muted bg) or fg.onEmphasis (emphasis bg) |
| **neutral** | Non-semantic, secondary UI elements | secondary buttons, tags, labels without status meaning | fg.default (muted bg) or fg.onEmphasis (emphasis bg) |
| **open** | Open/active state indicators (GitHub issues, PRs) | open issues, open PRs, active discussions | fg.open (muted bg) or fg.onEmphasis (emphasis bg) |
| **closed** | Closed/declined state indicators (GitHub issues, PRs) | closed issues, closed PRs, declined items | fg.closed (muted bg) or fg.onEmphasis (emphasis bg) |
| **done** | Completed/merged state indicators | merged PRs, completed tasks, finished items | fg.done (muted bg) or fg.onEmphasis (emphasis bg) |
| **sponsors** | GitHub Sponsors content only | sponsor buttons, funding prompts, sponsor cards | fg.sponsors (muted bg) or fg.onEmphasis (emphasis bg) |
| **upsell** | Upgrade prompts, premium features, promotional content | upgrade buttons, premium badges, promotional banners | fg.upsell (muted bg) or fg.onEmphasis (emphasis bg) |

## Ansi

**U:** cli-interface, console-text, terminal-output
**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.

### ansi-black
ANSI black for terminal text and backgrounds

### ansi-blackBright
ANSI bright black (dark gray) for dimmed terminal text

### ansi-blue
ANSI blue for informational terminal text

### ansi-blueBright
ANSI bright blue for highlighted info in terminal

### ansi-cyan
ANSI cyan for terminal text

### ansi-cyanBright
ANSI bright cyan for highlighted terminal text

### ansi-gray
ANSI gray for secondary terminal text

### ansi-green
ANSI green for success indicators in terminal

### ansi-greenBright
ANSI bright green for highlighted success in terminal

### ansi-magenta
ANSI magenta for special terminal text

### ansi-magentaBright
ANSI bright magenta for highlighted special text

### ansi-red
ANSI red for errors and alerts in terminal output

### ansi-redBright
ANSI bright red for highlighted errors in terminal

### ansi-white
ANSI white for terminal text

### ansi-whiteBright
ANSI bright white for emphasized terminal text

### ansi-yellow
ANSI yellow for warnings in terminal output

### ansi-yellowBright
ANSI bright yellow for highlighted warnings in terminal

## Background Colors

Background color tokens for surfaces, containers, and UI elements.

**Semantic tokens** (see Semantic Key for meaning):
- `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
**R:** Use as the primary background for pages and content areas. Do NOT use for emphasis or highlighting.

### bgColor-disabled
Background for disabled interactive elements
**U:** disabled-button, disabled-input, inactive-element
**R:** MUST use for disabled state backgrounds. Pair -> fg.disabled for text. Do NOT use for active elements.

### bgColor-draft-emphasis
Strong background for draft state badges and labels
**U:** draft-badge, draft-label, wip-indicator
**R:** Use for prominent draft state indicators. Pair -> fg.onEmphasis for text.

### bgColor-draft-muted
Subtle background for draft state indicators
**U:** draft-issue, draft-pr, work-in-progress
**R:** Use for draft/WIP status indicators. Conveys incomplete or pending state.

### bgColor-emphasis
High-emphasis dark background for strong visual contrast
**U:** badge-background, high-contrast-element, tooltip
**R:** Use for elements needing strong visual emphasis. Pair -> fg.onEmphasis for text. Do NOT use for large areas.

### bgColor-inset
Inset background for recessed content areas like wells or sunken panels
**U:** recessed-area, sunken-panel, well
**R:** Use for visually recessed areas. Creates depth hierarchy. Suitable for input fields and wells.

### bgColor-inverse
Inverse background that flips between light and dark modes
**U:** inverse-theme-element, overlay-content
**R:** Use when you need opposite theme background. Pair -> fg.onInverse for text.

### bgColor-muted
Muted background for secondary content areas and subtle grouping
**U:** code-block-background, secondary-content, table-header
**R:** Use for secondary content areas or to create visual grouping. Do NOT use for primary page backgrounds.

### bgColor-transparent
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.

**Semantic tokens** (see Semantic Key for meaning):
- `border-[accent, attention, closed, danger, done, neutral, open, severe, sponsors, success, upsell]-emphasis`
- `border-[accent, attention, closed, danger, done, neutral, open, severe, sponsors, success, upsell]-muted`

**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.

**Semantic tokens** (see Semantic Key for meaning):
- `borderColor-[accent, attention, closed, danger, done, neutral, open, severe, sponsors, success, upsell]-emphasis`
- `borderColor-[accent, attention, closed, danger, done, neutral, open, severe, sponsors, success, upsell]-muted`

### borderColor-default
Default border color for most UI elements
**U:** card-border, default-border, input-border
**R:** RECOMMENDED default for all borders. Use for cards, inputs, and dividers.

### borderColor-disabled
Border color for disabled interactive elements
**U:** disabled-border, inactive-border, unavailable
**R:** MUST use for disabled state borders. Pair -> bg.disabled. Do NOT use for active elements.

### borderColor-draft-emphasis
Strong border for draft state badges
**U:** draft-emphasis, draft-status
**R:** Use for emphasized draft state borders. Pair -> bg.draft.emphasis.

### borderColor-draft-muted
Subtle border for draft state indicators
**U:** draft-issue, draft-muted, draft-pr
**R:** Use for draft/WIP status borders. Conveys incomplete or pending state.

### borderColor-emphasis
Strong border for emphasis and visual weight
**U:** emphasis-border, selected-border, strong-border
**R:** Use for borders needing more visual weight. Darker than border.default.

### borderColor-muted
Subtle border for secondary elements and light separators
**U:** light-divider, secondary-border, subtle-border
**R:** Use for subtle borders and separators. Less prominent than border.default.

### borderColor-translucent
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.

### borderRadius-full
Shape token for fully rounded or pill-shaped elements.
**U:** avatar, circular-button, pill-badge
**R:** Use for avatars and pill-shaped elements. Do NOT use for rectangular containers.

### borderRadius-large
Scale token: 12px radius for larger surfaces or softer container treatments.
**U:** card, dialog, modal
**R:** Recommended for dialogs and modals.

### borderRadius-medium
Scale token: 6px radius in the border-radius scale. Use when selecting a specific radius intentionally.
**U:** button, input, textarea
**R:** Default choice for most components. Use for inputs, cards, and general containers.

### borderRadius-small
Scale token: 3px radius for compact UI elements or small component variants.
**U:** badge, label, tag
**R:** Use for small UI elements under 16px height. Do NOT use for buttons or cards.

## Border Width

Border thickness tokens.

### borderWidth-thick
Scale token: 2px border width for emphasis or focus states.
**U:** emphasis-border, focus-indicator, selected-state
**R:** MUST use for focus rings on interactive elements. Do NOT use for subtle dividers.

## Controls

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, 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]`
- `control-transparent-[bgColor-active, bgColor-disabled, bgColor-hover, bgColor-rest, bgColor-selected, borderColor-active, borderColor-hover, borderColor-rest]`

**Other tokens:**
- `control-bgColor-[active, disabled, hover, rest, selected]`
- `control-borderColor-[danger, disabled, emphasis, rest, selected, success, warning]`
- `control-danger-bgColor-[active, hover]`
- `control-danger-fgColor-[hover, rest]`
- `control-fgColor-[disabled, placeholder, rest]`
- `control-iconColor-rest`
- `control-minTarget-[auto, coarse, fine]`

## Control Knob

Colors for toggle switch knobs (the circular handle that moves along the track).

**U:** slider-thumb, switch-handle, toggle-knob
**R:** Use for the movable handle/thumb of toggle switches and sliders. Pair -> controlTrack tokens for the background rail.

**Tokens:** controlKnob-bgColor-checked, controlKnob-bgColor-disabled, controlKnob-bgColor-rest, controlKnob-borderColor-checked, controlKnob-borderColor-disabled, controlKnob-borderColor-rest

## Control Stack

Gap tokens for groups of controls arranged in a row or column.

**Scale:** Match gap size to control size. Use condensed for tight groupings, spacious for separated actions.

**Size patterns:**
- `controlStack-[small, medium, large]-[gap-auto, gap-condensed, gap-spacious]`

## Control Track

Colors for toggle switch tracks (the background rail that the knob slides along).

**U:** slider-track, switch-track, toggle-track
**R:** Use for the track/rail element of toggle switches and sliders. Pair -> controlKnob tokens for the movable handle.

**Tokens:** controlTrack-bgColor-active, controlTrack-bgColor-disabled, controlTrack-bgColor-hover, controlTrack-bgColor-rest, controlTrack-borderColor-disabled, controlTrack-borderColor-rest, controlTrack-fgColor-disabled, controlTrack-fgColor-rest

## Data Visualization

Color tokens for charts, graphs, and diagrams. Use emphasis variants for lines/bars, muted variants for fills.

**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.

**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

Animation easing function tokens.

### base-easing-ease
CSS default easing. Use for hover state changes and micro-interactions.
**U:** button-hover, hover-state, micro-interaction
**R:** Use for hover state changes.

### base-easing-easeIn
Accelerating motion. Use for elements exiting the viewport (moving off-screen).
**U:** element-leaving, exit-animation, off-screen-motion
**R:** Rarely used alone. Prefer ease-out for most exit animations.

### base-easing-easeInOut
Smooth acceleration and deceleration. Use for elements moving or morphing within the viewport.
**U:** morph-animation, position-change, size-change
**R:** Use if an element moves or morphs on screen.

### base-easing-easeOut
Decelerating motion. Use for elements entering the viewport or appearing on screen.
**U:** element-appearing, enter-animation, modal-open
**R:** RECOMMENDED default. Use if an element enters or exits the viewport.

### base-easing-linear
Constant motion with no acceleration. Use for continuous animations like progress bars or loaders.
**U:** continuous-animation, loader, progress-bar
**R:** Use if the motion is constant.

## Foreground Colors

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
**R:** RECOMMENDED default for all text. Use for headings, body text, and primary labels.

### fgColor-disabled
Text color for disabled interactive elements
**U:** disabled-text, inactive-text, unavailable
**R:** MUST use for disabled state text. Pair -> bg.disabled. Do NOT use for active elements.

### fgColor-draft
Text color for draft state indicators
**U:** draft-issue, draft-pr, draft-text
**R:** Use for draft/WIP status text. Conveys incomplete or pending state.

### fgColor-link
Text color for hyperlinks
**U:** hyperlink, link-text
**R:** MUST use for all text links. Provides expected link affordance.

### fgColor-muted
Muted text for secondary content and less important information
**U:** helper-text, muted-text, secondary-text
**R:** Use for secondary text like timestamps, metadata, and helper text. Do NOT use for primary content.

### fgColor-onEmphasis
Text color for use on emphasis backgrounds
**U:** contrast-text, text-on-emphasis
**R:** MUST use for text on any emphasis background (bg.*.emphasis). Ensures accessibility contrast.

### fgColor-onInverse
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.

### focus-outline
Focus ring outline for keyboard navigation and accessibility.
**U:** accessibility-indicator, focus-ring, keyboard-navigation
**R:** Always ensure focus states are visible. Do not override with custom focus styles that reduce visibility. Use for interactive elements like buttons, links, and form controls.

### focus-outline-color
Outline color for focus states on interactive elements
**U:** accessibility-indicator, focus-ring, keyboard-navigation
**R:** Use for focus outlines on interactive elements like buttons, links, and form controls. MUST be visible for keyboard navigation accessibility. Do NOT use for decorative borders or non-interactive elements.

### focus-outline-width
Focus outline width (2px). Standard width for keyboard focus indicators to meet WCAG 2.4.7 accessibility requirements
**U:** accessibility, focus-ring, keyboard-focus
**R:** MUST use for all keyboard focus indicators. Required for WCAG 2.4.7 compliance.

## Font Stacks

Font family tokens.

### fontStack-monospace
Monospace font stack for code, technical content, and tabular data.
**U:** code-block, inline-code, terminal
**R:** MUST use for all code display. Use for technical content requiring fixed-width characters.

### fontStack-sansSerif
Sans-serif font stack for body text and general UI elements.
**U:** body-text, form-inputs, labels
**R:** Default font stack for all UI text. Use for body text and standard UI elements. MUST use for readable content.

### fontStack-sansSerifDisplay
Display font stack for headings and titles. Same as sansSerif but semantically distinct.
**U:** display-text, heading, title
**R:** Use for headings and display text. Prefer over sansSerif for titles.

## Motion

### motion-duration-long
Longer duration for complex multi-step animations or large-scale layout shifts. Use sparingly.
**U:** complex-animation, layout-shift, multi-step
**R:** Use sparingly for complex animations. NEVER use for simple UI interactions.

### motion-duration-medium
Standard duration for elements entering or exiting the viewport, such as modals and dropdowns.
**U:** dropdown-appear, modal-open, tooltip-show
**R:** Use for elements entering or leaving the viewport. Maximum recommended duration for UI interactions.

### motion-duration-micro
Fast micro-interactions like hover, focus ring, and color shifts.
**U:** color-shift, focus-ring, hover-transition
**R:** Use for instantaneous feedback on hover and focus states.

### motion-duration-short
Quick transitions for state changes like expand/collapse, toggles, and visibility changes.
**U:** expand-collapse, toggle, visibility-change
**R:** Use for interactive state changes that need to feel responsive.

### motion-easing-enter
Decelerating easing for elements entering the viewport or appearing on screen.
**U:** element-appearing, enter-animation, modal-open
**R:** RECOMMENDED default for enter animations. Element decelerates into its final position.

### motion-easing-exit
Accelerating easing for elements exiting the viewport or leaving the screen.
**U:** element-leaving, exit-animation, modal-close
**R:** Use for elements leaving the viewport. Element accelerates away.

### motion-easing-hover
Easing for hover state changes and micro-interactions.
**U:** button-hover, hover-state, micro-interaction
**R:** Use for hover state changes.

### motion-easing-linear
Constant motion with no acceleration. Use for continuous animations like progress bars or loaders.
**U:** continuous-animation, loader, progress-bar
**R:** Use only for constant, uninterrupted motion.

### motion-easing-move
Smooth easing for elements moving or morphing within the viewport.
**U:** morph-animation, position-change, size-change
**R:** Use for elements that move or change shape on screen.

### motion-transition-enter
Transition for elements entering the viewport, such as modals, dropdowns, and tooltips.
**U:** dropdown-appear, modal-open, tooltip-show
**R:** Use for elements appearing on screen. Element decelerates into final position.

### motion-transition-exit
Transition for elements exiting the viewport, such as closing modals and dismissing dropdowns.
**U:** dropdown-dismiss, modal-close, tooltip-hide
**R:** Use for elements leaving the screen. Shorter than enter to feel snappy.

### motion-transition-hover
Transition for hover state changes on interactive elements like buttons and links.
**U:** button-hover, interactive-hover, link-hover
**R:** Use for all hover state transitions. Keeps interactions feeling instantaneous.

### motion-transition-stateChange
Transition for state changes like toggles, expand/collapse, and visibility changes.
**U:** accordion, expand-collapse, toggle
**R:** Use for interactive elements that change between states.

## Overlay

Tokens for modals, dialogs, popovers, and dropdown menus.

**Scale:** Use xsmall/small for menus and tooltips, medium for dialogs, large/xlarge for complex modals or sheets.

**Size patterns:**
- `overlay-height-[small, medium, large, xlarge]`
- `overlay-width-[xsmall, small, medium, large, xlarge]`

**Other tokens:**
- `overlay-backdrop-bgColor`
- `overlay-bgColor-default`
- `overlay-borderColor-default`
- `overlay-borderRadius-default`
- `overlay-offset-default`
- `overlay-padding-[condensed, normal]`
- `overlay-paddingBlock-[condensed, normal]`

## Prettylights

**U:** code-block, code-syntax-highlighting, 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.).

### prettylights-syntax-bracketHighlighterAngle
Syntax highlighting color for angle brackets

### prettylights-syntax-bracketHighlighterUnmatched
Syntax highlighting color for unmatched brackets

### prettylights-syntax-brackethighlighter-angle
Deprecated. Use prettylights.syntax.bracketHighlighterAngle instead.

### prettylights-syntax-brackethighlighter-unmatched
Deprecated. Use prettylights.syntax.bracketHighlighterUnmatched instead.

### prettylights-syntax-carriage-return-bg
Deprecated. Use prettylights.syntax.carriageReturn.bg instead.

### prettylights-syntax-carriage-return-text
Deprecated. Use prettylights.syntax.carriageReturn.text instead.

### prettylights-syntax-carriageReturn-bg
Background color for carriage return characters in diffs

### prettylights-syntax-carriageReturn-text
Text color for carriage return characters in diffs

### prettylights-syntax-comment
Syntax highlighting color for code comments

### prettylights-syntax-constant
Syntax highlighting color for constants and literal values

### prettylights-syntax-constant-other-reference-link
Deprecated. Use prettylights.syntax.constantOtherReferenceLink instead.

### prettylights-syntax-constantOtherReferenceLink
Syntax highlighting color for reference links and URLs in code

### prettylights-syntax-entity
Syntax highlighting color for class names, type definitions, and declarations

### prettylights-syntax-entity-tag
Deprecated. Use prettylights.syntax.entityTag instead.

### prettylights-syntax-entityTag
Syntax highlighting color for HTML/XML tags

### prettylights-syntax-invalid-illegal-bg
Deprecated. Use prettylights.syntax.invalidIllegal.bg instead.

### prettylights-syntax-invalid-illegal-text
Deprecated. Use prettylights.syntax.invalidIllegal.text instead.

### prettylights-syntax-invalidIllegal-bg
Background color for invalid or illegal code syntax

### prettylights-syntax-invalidIllegal-text
Text color for invalid or illegal code syntax

### prettylights-syntax-keyword
Syntax highlighting color for language keywords (if, else, return)

### prettylights-syntax-markup-bold
Syntax highlighting color for bold text in markdown

### prettylights-syntax-markup-changed-bg
Background color for changed lines in diff views

### prettylights-syntax-markup-changed-text
Text color for changed lines in diff views

### prettylights-syntax-markup-deleted-bg
Background color for deleted lines in diff views

### prettylights-syntax-markup-deleted-text
Text color for deleted lines in diff views

### prettylights-syntax-markup-heading
Syntax highlighting color for headings in markdown

### prettylights-syntax-markup-ignored-bg
Background color for ignored content in diffs

### prettylights-syntax-markup-ignored-text
Text color for ignored content in diffs

### prettylights-syntax-markup-inserted-bg
Background color for inserted lines in diff views

### prettylights-syntax-markup-inserted-text
Text color for inserted lines in diff views

### prettylights-syntax-markup-italic
Syntax highlighting color for italic text in markdown

### prettylights-syntax-markup-list
Syntax highlighting color for list markers in markdown

### prettylights-syntax-meta-diff-range
Deprecated. Use prettylights.syntax.metaDiffRange instead.

### prettylights-syntax-metaDiffRange
Syntax highlighting color for diff range information (@@ lines)

### prettylights-syntax-storage-modifier-import
Deprecated. Use prettylights.syntax.storageModifierImport instead.

### prettylights-syntax-storageModifierImport
Syntax highlighting color for import and require statements

### prettylights-syntax-string
Syntax highlighting color for string literals

### prettylights-syntax-string-regexp
Deprecated. Use prettylights.syntax.stringRegexp instead.

### prettylights-syntax-stringRegexp
Syntax highlighting color for regular expression literals

### prettylights-syntax-sublimeLinterGutterMark
Color for linter gutter marks in code editors

### prettylights-syntax-sublimelinter-gutter-mark
Deprecated. Use prettylights.syntax.sublimeLinterGutterMark instead.

### prettylights-syntax-variable
Syntax highlighting color for variables and parameters

## Selection

Tokens for text selection highlights.

### selection-bgColor
Background color for text selection highlights
**U:** highlighted-text, selected-content, text-selection
**R:** Use for native text selection (::selection) and programmatic text highlighting. Do NOT use for general emphasis or background colors on containers.

## Shadow

Box shadow tokens for elevation and depth.

### shadow-floating-large
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-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.

## Space

### space-lg
Spacious spacing for major layout divisions and visual separation between content blocks.
**U:** gap, margin, padding
**R:** Spacious (16px). Use for major layout divisions, visual separation between content blocks, and primary container margins.

### space-md
Relaxed spacing for breathing room and comfortable internal container space.
**U:** gap, margin, padding
**R:** Relaxed (12px). Use for comfortable container padding, relaxed layouts, section separators, and breathing room in dense layouts.

### space-sm
Default spacing for most UI elements. Comfortable visual density for standard component layouts.
**U:** gap, margin, padding
**R:** Default (8px). Use for standard component spacing, flex/grid item separation, container padding, and most element margins.

### space-xl
Expansive spacing for large sections and top-level structure separation.
**U:** gap, margin, padding
**R:** Expansive (24px). Use for large section separation, top-level layout structure, major page divisions, and expansive breathing room.

### space-xs
Compact spacing for small badges, tight internal spacing, and minimal breathing room.
**U:** gap, margin, padding
**R:** Compact (4px). Use for small component spacing, tight list separations, badge padding, and minimal internal margins.

### space-xxs
Ultra-compact spacing for form field separators and tight visual divisions.
**U:** gap, margin, padding
**R:** Ultra-compact (2px). Use for form field separators, tight dividers, and minimal breathing room between small elements.

## Spinner

Loading spinner size and stroke tokens.

**Scale:** Use small for inline loading, medium for buttons/cards, large for full-page states.

**Size patterns:**
- `spinner-size-[small, medium, large]`

**Other tokens:**
- `spinner-strokeWidth-default`

## Stack

Spacing tokens for Stack layout components.

**Scale:** Use condensed for dense lists, normal for standard layouts, spacious for prominent sections.

**Other tokens:**
- `stack-gap-[condensed, normal, spacious]`
- `stack-padding-[condensed, normal, spacious]`

## Typography

Text style shorthand tokens for consistent typography across the UI.

### Headings

Title and display text styles for headings and hero sections.

| Token | Description | U: | R: |
|---|---|---|---|
| **text-display-shorthand** | Hero-style text for brand to product transition pages. Utilize Title (large) styles on narrow viewports. | hero-section, landing-page, marketing-header | Use sparingly for hero sections. Switch to title.large on narrow viewports. |
| **text-subtitle-shorthand** | Page sections/sub headings, or less important object names in page titles (automated action titles, for example). Same line-height as title (medium). | subtitle, description, secondary-heading | Use below titles for supporting text. Normal weight distinguishes from title styles. |
| **text-title-shorthand-large** | Page headings for user-created objects, such as issues or pull requests. Utilize title (medium) styles on narrow viewports. | page-heading, issue-title, pr-title | Use for primary page headings. Switch to title.medium on narrow viewports. |
| **text-title-shorthand-medium** | Default page title. The 32px-equivalent line-height matches with button and other medium control heights. Great for page header composition. | section-heading, card-title, dialog-title | RECOMMENDED default for page titles. Use for section headings and dialog titles. |
| **text-title-shorthand-small** | Uses the same size as body (large) with a heavier weight of semibold (600). | subsection-heading, list-title, h3 | Use for smaller headings within sections. Same size as body.large but semibold. |

### Body

Body text and caption styles for content and UI labels.

| Token | Description | U: | R: |
|---|---|---|---|
| **text-body-shorthand-large** | User-generated content, markdown rendering. | markdown-content, article-text, readme | Use for user-generated content and markdown. Better readability for longer text. |
| **text-body-shorthand-medium** | Default UI font. Most commonly used for body text. | body-text, ui-text, form-label | RECOMMENDED default for UI text. Use for buttons, labels, and general interface text. |
| **text-body-shorthand-small** | 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. | helper-text, footnote, metadata | Use sparingly for secondary information. Do NOT use for primary content or interactive elements. |
| **text-caption-shorthand** | 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. | caption, label, badge-text | Use only for single-line or short text. Does NOT meet accessibility requirements for body text. |

### Code

Monospace text styles for code blocks and inline code.

| Token | Description | U: | R: |
|---|---|---|---|
| **text-codeBlock-shorthand** | Default style for rendering code blocks. | code-block, pre-element, code-snippet | MUST use for multi-line code. Use monospace font stack. |
| **text-codeInline-shorthand** | Inline code blocks using em units to inherit size from its parent. | inline-code, code-element, variable-name | Use for inline code within text. Size inherits from parent using em units. |

## ZIndex

### zIndex-behind
Place element behind base content. Use for decorative backgrounds or canvas elements.
**U:** background-pattern, canvas-element, decorative-background
**R:** Use to push an element behind its siblings. WARNING: Negative z-index can behave unpredictably if any ancestor creates a new stacking context (via transform, opacity < 1, filter, will-change, etc.). Only use when you control the full stacking context chain. Do NOT use as a general "hide" mechanism.

### zIndex-default
Default stacking order. No elevation above surrounding content.
**U:** default-content, in-flow-element, reset
**R:** Use to explicitly reset z-index to the default layer. Suitable for elements that should participate in normal document flow stacking. Do NOT use for any element that needs to appear above other content.

### zIndex-dropdown
Dropdown menus and select panels that appear above page content.
**U:** autocomplete-list, dropdown-menu, select-panel
**R:** Use for menus, select panels, and autocomplete lists that overlay page content. These should appear above sticky elements but below overlays and modals. Pair -> `shadow.floating.small` or `shadow.floating.medium` for visual elevation.

### zIndex-modal
Modal dialogs and full-screen overlays.
**U:** dialog, full-screen-overlay, modal-dialog
**R:** Use for modal dialogs that require user interaction before returning to the page. MUST trap focus within the modal. MUST appear above all other page content except popovers and skip links. Pair -> `shadow.floating.large` or `shadow.floating.xlarge` for visual elevation.

### zIndex-overlay
Overlay backdrops, side panels, and drawers.
**U:** drawer, overlay-backdrop, side-panel
**R:** Use for overlay surfaces that partially cover the page — drawers, side panels, and backdrop layers. These appear above dropdowns but below modal dialogs. SHOULD be paired with a backdrop/scrim element to indicate the overlay is blocking interaction with content beneath.

### zIndex-popover
Tooltips and popovers that appear above all normal UI.
**U:** hover-card, popover, tooltip
**R:** Use for tooltips, popovers, and hover cards that must appear above all other UI elements including modals. These are the highest layer in normal UI. Do NOT use for persistent navigation — use `sticky` instead.

### zIndex-skipLink
Accessibility skip links. Must always be the topmost layer.
**U:** skip-link, skip-navigation, skip-to-content
**R:** MUST use for accessibility skip links that allow keyboard users to bypass navigation. This is the highest z-index level and MUST always appear above everything else including modals and tooltips. NEVER use for non-accessibility purposes.

### zIndex-sticky
Sticky elements that remain visible while scrolling.
**U:** sticky-header, sticky-sidebar, sticky-table-header
**R:** MUST use with `position: sticky` or `position: fixed` for headers, sidebars, and navigation bars that persist during scroll. Do NOT use for floating overlays or dropdowns — use higher z-index levels instead.

---

**Final Directive for AI**:
Always cross-reference the `Semantic Key` at the top of this SPEC before confirming a token choice. If a specific component token is missing, derive it using the `[category]-[semantic]-[variant]` pattern.