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

package/DESIGN_TOKENS_SPEC.md

@@ -0,0 +1,565 @@
+# 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) |
+
+## 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
+
+## 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
+**U:** overlay-border, translucent-border
+**R:** Use for semi-transparent borders on overlays. Works well with translucent backgrounds.
+
+## Border Radius
+
+Corner radius tokens for rounded elements.
+
+### borderRadius-full
+Use this border radius for 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
+Large border radius (12px). Use for larger containers, dialogs, or when more visual softness is desired. Always use this for buttons.
+**U:** card, dialog, modal
+**R:** Recommended for dialogs and modals.
+
+### borderRadius-medium
+Medium border radius (6px). The default choice for most buttons, cards, and containers
+**U:** button, input, textarea
+**R:** Default choice for most components. Use for inputs, cards, and general containers.
+
+### borderRadius-small
+Small border radius (3px). Use for small variants of components or small UI elements like badges, tags, or anything below 16px in height
+**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
+Thick 2px border for emphasis. Use for focus indicators, selected states, or to emphasize important boundaries
+**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.
+
+**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`
+
+**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-outlineColor
+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.
+
+## 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.
+
+## Outline
+
+Outline tokens for focus indicators.
+
+### outline-focus-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.
+
+## 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]`
+
+## 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-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.
+
+**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. |
+
+---
+
+**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.

package/dist/build/formats/markdownLlmGuidelines.d.ts

@@ -1,10 +1,11 @@
 import type { FormatFn } from 'style-dictionary/types';
 /**
- * @description Outputs a markdown file with LLM token guidelines, extracting
- * description from $description and usage/rules from $extensions['org.primer.llm'].
- * Tokens with identical guidelines (from group-level inheritance) are consolidated
- * into a single entry listing all token names.
- * @param FormatFnArguments
- * @returns formatted markdown `string`
+ * @description Outputs a hyper-optimized markdown file with LLM token guidelines.
+ * Optimizations:
+ * - Bracket notation for tokens with identical guidelines
+ * - Global category rules extracted to paragraph
+ * - Shortened keys (U:, R:, Pair ->)
+ * - Max 3 usage items
+ * - No boilerplate
  */
 export declare const markdownLlmGuidelines: FormatFn;