@primer/primitives 11.4.0 → 11.4.1-rc.eb8ee149

package/DESIGN_TOKENS_SPEC.md

@@ -0,0 +1,446 @@
+# Primer Design Token Guidelines
+
+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-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.
+
+## 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.
+
+## 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
+
+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.
+
+**U:** bar-fill, chart-series, graph-line
+**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
+
+## 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-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.
+
+## 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-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.
+
+## 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;