@primer/primitives 11.4.0-rc.daff2d10 → 11.4.0-rc.e472be0d

package/token-guidelines.llm.md

@@ -4,22 +4,22 @@
 
 ### bgColor-accent-emphasis
 Strong accent background for active states and focused states
-**Usage:** active-states, current, selected, active-toggle
+**Usage:** active-states, active-toggle, current, selected
 **Rules:** MUST use for selected or active states. Pair with fgColor.onEmphasis for text.
 
 ### bgColor-accent-muted
 Subtle accent background for informational or selected elements
-**Usage:** selected-row, info-banner, active-nav-item, highlight
+**Usage:** active-nav-item, highlight, info-banner, selected-row
 **Rules:** Use for selected states or informational highlights. Pair with fgColor.accent for text.
 
 ### bgColor-attention-emphasis
 Strong attention background for prominent warnings
-**Usage:** warning-badge, caution-label, attention-indicator
+**Usage:** attention-indicator, caution-label, warning-badge
 **Rules:** Use for prominent warnings. Consider fgColor.default for text due to yellow contrast.
 
 ### bgColor-attention-muted
 Subtle attention background for warnings and caution states
-**Usage:** warning-banner, caution-message, pending-state
+**Usage:** caution-message, pending-state, warning-banner
 **Rules:** Use for warnings that need user attention. Pair with fgColor.attention for text.
 
 ### bgColor-closed-emphasis
@@ -34,17 +34,17 @@ Subtle background for closed state indicators (issues, PRs)
 
 ### bgColor-danger-emphasis
 Emphasized danger background for critical errors and delete confirmations
-**Usage:** delete-button, critical-alert, destructive-confirmation
+**Usage:** critical-alert, delete-button, destructive-confirmation
 **Rules:** MUST use for destructive action buttons like delete. Use fgColor.onEmphasis for text on this background.
 
 ### bgColor-danger-muted
 Muted danger background for error states and destructive action contexts
-**Usage:** error-message, destructive-action, validation-error
+**Usage:** destructive-action, error-message, validation-error
 **Rules:** Use for error states and destructive action backgrounds. Pair with fgColor.danger for text.
 
 ### bgColor-default
 Default background color for pages and main content areas
-**Usage:** page-background, main-content, card-background
+**Usage:** card-background, main-content, page-background
 **Rules:** Use as the primary background for pages and content areas. Do NOT use for emphasis or highlighting.
 
 ### bgColor-disabled
@@ -54,12 +54,12 @@ Background for disabled interactive elements
 
 ### bgColor-done-emphasis
 Strong background for completed/done state badges and labels
-**Usage:** done-badge, merged-label, completed-indicator
+**Usage:** completed-indicator, done-badge, merged-label
 **Rules:** Use for prominent done/completed state indicators. Pair with fgColor.onEmphasis for text.
 
 ### bgColor-done-muted
 Subtle background for completed/done state indicators
-**Usage:** completed-task, merged-pr, done-state
+**Usage:** completed-task, done-state, merged-pr
 **Rules:** Use for completed/done status indicators. Conveys finished or merged state.
 
 ### bgColor-draft-emphasis
@@ -69,77 +69,77 @@ Strong background for draft state badges and labels
 
 ### bgColor-draft-muted
 Subtle background for draft state indicators
-**Usage:** draft-pr, draft-issue, work-in-progress
+**Usage:** draft-issue, draft-pr, work-in-progress
 **Rules:** Use for draft/WIP status indicators. Conveys incomplete or pending state.
 
 ### bgColor-emphasis
 High-emphasis dark background for strong visual contrast
-**Usage:** tooltip, badge-background, high-contrast-element
+**Usage:** badge-background, high-contrast-element, tooltip
 **Rules:** Use for elements needing strong visual emphasis. Pair with fgColor.onEmphasis for text. Do NOT use for large areas.
 
 ### bgColor-inset
 Inset background for recessed content areas like wells or sunken panels
-**Usage:** well, sunken-panel, recessed-area, input-background
+**Usage:** input-background, recessed-area, sunken-panel, well
 **Rules:** 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
-**Usage:** overlay-content, inverse-theme-element
+**Usage:** inverse-theme-element, overlay-content
 **Rules:** Use when you need opposite theme background. Pair with fgColor.onInverse for text.
 
 ### bgColor-muted
 Muted background for secondary content areas and subtle grouping
-**Usage:** secondary-content, code-block-background, table-header, sidebar
+**Usage:** code-block-background, secondary-content, sidebar, table-header
 **Rules:** Use for secondary content areas or to create visual grouping. Do NOT use for primary page backgrounds.
 
 ### bgColor-neutral-emphasis
 Strong neutral background for prominent neutral elements
-**Usage:** neutral-button, secondary-action, neutral-indicator
+**Usage:** neutral-button, neutral-indicator, secondary-action
 **Rules:** Use for emphasized neutral elements. Pair with fgColor.onEmphasis for text.
 
 ### bgColor-neutral-muted
 Subtle neutral background for tags, labels, and secondary UI elements
-**Usage:** neutral-label, neutral-badge, secondary-tag, counter
+**Usage:** counter, neutral-badge, neutral-label, secondary-tag
 **Rules:** Use for neutral semantic meaning. Pair with fgColor.default for text. Do NOT use for status indicators.
 
 ### bgColor-open-emphasis
 Strong background for open state badges and labels
-**Usage:** open-badge, open-label, active-status-badge
+**Usage:** active-status-badge, open-badge, open-label
 **Rules:** Use for prominent open/active state indicators. Pair with fgColor.onEmphasis for text.
 
 ### bgColor-open-muted
 Subtle background for open state indicators (issues, PRs)
-**Usage:** open-issue, open-pr, active-status
+**Usage:** active-status, open-issue, open-pr
 **Rules:** Use for open/active status indicators. Specifically for GitHub issues and PRs.
 
 ### bgColor-severe-emphasis
 Strong severe background for prominent high-priority warnings
-**Usage:** severe-badge, urgent-label, high-priority-indicator
+**Usage:** high-priority-indicator, severe-badge, urgent-label
 **Rules:** Use for prominent severe warnings. Pair with fgColor.onEmphasis for text.
 
 ### bgColor-severe-muted
 Subtle severe background for high-priority warnings
-**Usage:** high-priority-warning, urgent-message, escalation
+**Usage:** escalation, high-priority-warning, urgent-message
 **Rules:** Use for severe warnings, less critical than danger. Pair with fgColor.severe for text.
 
 ### bgColor-sponsors-emphasis
 Strong background for prominent GitHub Sponsors elements
-**Usage:** sponsor-button, sponsor-badge, funding-cta
+**Usage:** funding-cta, sponsor-badge, sponsor-button
 **Rules:** Use for prominent Sponsors CTAs. Pair with fgColor.onEmphasis for text.
 
 ### bgColor-sponsors-muted
 Subtle background for GitHub Sponsors content
-**Usage:** sponsor-card, sponsor-highlight, funding-prompt
+**Usage:** funding-prompt, sponsor-card, sponsor-highlight
 **Rules:** Use for GitHub Sponsors related content. Do NOT use for general pink-colored elements.
 
 ### bgColor-success-emphasis
 Strong success background for prominent positive actions
-**Usage:** merge-button, confirm-action, success-badge
+**Usage:** confirm-action, merge-button, success-badge
 **Rules:** Use for positive action buttons like merge or confirm. Pair with fgColor.onEmphasis for text.
 
 ### bgColor-success-muted
 Subtle success background for positive feedback and completed states
-**Usage:** success-message, completed-state, positive-feedback
+**Usage:** completed-state, positive-feedback, success-message
 **Rules:** Use for success states and positive feedback. Pair with fgColor.success for text.
 
 ### bgColor-transparent
@@ -149,34 +149,34 @@ Fully transparent background
 
 ### bgColor-upsell-emphasis
 Strong background for prominent upsell elements
-**Usage:** upgrade-button, premium-badge, upsell-cta
+**Usage:** premium-badge, upgrade-button, upsell-cta
 **Rules:** Use for prominent upgrade/upsell CTAs. Pair with fgColor.onEmphasis for text.
 
 ### bgColor-upsell-muted
 Subtle background for upsell and promotional content
-**Usage:** upgrade-prompt, premium-feature, promotional-banner
+**Usage:** premium-feature, promotional-banner, upgrade-prompt
 **Rules:** Use for upgrade prompts and premium feature highlights. Do NOT use for regular content.
 
 ## BorderColor
 
 ### borderColor-accent-emphasis
 Strong accent border for selected or focused elements
-**Usage:** accent-emphasis, selected-border, focus-border
+**Usage:** accent-emphasis, focus-border, selected-border
 **Rules:** Use for selected elements and focus states. Strong visual emphasis.
 
 ### borderColor-accent-muted
 Subtle accent border for selected or focused elements
-**Usage:** accent-muted, selected-muted, info-muted
+**Usage:** accent-muted, info-muted, selected-muted
 **Rules:** Use for accent-colored borders on selected elements. Pair with bgColor.accent.muted.
 
 ### borderColor-attention-emphasis
 Strong attention border for prominent warnings
-**Usage:** attention-emphasis, warning-emphasis, caution-emphasis
+**Usage:** attention-emphasis, caution-emphasis, warning-emphasis
 **Rules:** Use for emphasized warning borders. Pair with bgColor.attention.emphasis.
 
 ### borderColor-attention-muted
 Subtle attention border for warnings and caution states
-**Usage:** attention-muted, warning-muted, caution-muted
+**Usage:** attention-muted, caution-muted, warning-muted
 **Rules:** Use for warning state borders. Pair with bgColor.attention.muted.
 
 ### borderColor-closed-emphasis
@@ -186,22 +186,22 @@ Strong border for closed state badges
 
 ### borderColor-closed-muted
 Subtle border for closed state indicators
-**Usage:** closed-muted, closed-issue, closed-pr
+**Usage:** closed-issue, closed-muted, closed-pr
 **Rules:** Use for closed/declined status borders. Specifically for GitHub issues and PRs.
 
 ### borderColor-danger-emphasis
 Strong danger border for destructive actions and errors
-**Usage:** danger-emphasis, error-emphasis, destructive-emphasis
+**Usage:** danger-emphasis, destructive-emphasis, error-emphasis
 **Rules:** MUST use for destructive action borders. Pair with bgColor.danger.emphasis.
 
 ### borderColor-danger-muted
 Subtle danger border for errors and destructive contexts
-**Usage:** danger-muted, error-muted, destructive-muted
+**Usage:** danger-muted, destructive-muted, error-muted
 **Rules:** Use for error state borders. Pair with bgColor.danger.muted.
 
 ### borderColor-default
 Default border color for most UI elements
-**Usage:** default-border, card-border, input-border, divider
+**Usage:** card-border, default-border, divider, input-border
 **Rules:** RECOMMENDED default for all borders. Use for cards, inputs, and dividers.
 
 ### borderColor-disabled
@@ -216,7 +216,7 @@ Strong border for completed/done state badges
 
 ### borderColor-done-muted
 Subtle border for completed/done state indicators
-**Usage:** done-muted, merged, completed
+**Usage:** completed, done-muted, merged
 **Rules:** Use for completed/done status borders. Conveys finished or merged state.
 
 ### borderColor-draft-emphasis
@@ -226,17 +226,17 @@ Strong border for draft state badges
 
 ### borderColor-draft-muted
 Subtle border for draft state indicators
-**Usage:** draft-muted, draft-pr, draft-issue
+**Usage:** draft-issue, draft-muted, draft-pr
 **Rules:** Use for draft/WIP status borders. Conveys incomplete or pending state.
 
 ### borderColor-emphasis
 Strong border for emphasis and visual weight
-**Usage:** emphasis-border, strong-border, selected-border
+**Usage:** emphasis-border, selected-border, strong-border
 **Rules:** Use for borders needing more visual weight. Darker than borderColor.default.
 
 ### borderColor-muted
 Subtle border for secondary elements and light separators
-**Usage:** subtle-border, light-divider, secondary-border
+**Usage:** light-divider, secondary-border, subtle-border
 **Rules:** Use for subtle borders and separators. Less prominent than borderColor.default.
 
 ### borderColor-neutral-emphasis
@@ -256,7 +256,7 @@ Strong border for open state badges
 
 ### borderColor-open-muted
 Subtle border for open state indicators
-**Usage:** open-muted, open-issue, open-pr
+**Usage:** open-issue, open-muted, open-pr
 **Rules:** Use for open/active status borders. Specifically for GitHub issues and PRs.
 
 ### borderColor-severe-emphasis
@@ -271,22 +271,22 @@ Subtle severe border for high-priority warnings
 
 ### borderColor-sponsors-emphasis
 Strong border for prominent GitHub Sponsors elements
-**Usage:** sponsors-emphasis, funding-emphasis
+**Usage:** funding-emphasis, sponsors-emphasis
 **Rules:** Use for emphasized Sponsors borders. Pair with bgColor.sponsors.emphasis.
 
 ### borderColor-sponsors-muted
 Subtle border for GitHub Sponsors content
-**Usage:** sponsors-muted, funding-muted
+**Usage:** funding-muted, sponsors-muted
 **Rules:** Use for GitHub Sponsors related borders. Do NOT use for general pink-colored elements.
 
 ### borderColor-success-emphasis
 Strong success border for prominent positive elements
-**Usage:** success-emphasis, confirmed, positive-emphasis
+**Usage:** confirmed, positive-emphasis, success-emphasis
 **Rules:** Use for emphasized success borders. Pair with bgColor.success.emphasis.
 
 ### borderColor-success-muted
 Subtle success border for positive feedback elements
-**Usage:** success-muted, valid-muted, positive-muted
+**Usage:** positive-muted, success-muted, valid-muted
 **Rules:** Use for success state borders. Pair with bgColor.success.muted.
 
 ### borderColor-translucent
@@ -296,95 +296,104 @@ Semi-transparent border for overlays and layered elements
 
 ### borderColor-upsell-emphasis
 Strong border for prominent upsell elements
-**Usage:** upsell-emphasis, premium-emphasis
+**Usage:** premium-emphasis, upsell-emphasis
 **Rules:** Use for emphasized upsell borders. Pair with bgColor.upsell.emphasis.
 
 ### borderColor-upsell-muted
 Subtle border for upsell and promotional content
-**Usage:** upsell-muted, premium-muted
+**Usage:** premium-muted, upsell-muted
 **Rules:** Use for upgrade prompts and premium feature borders. Do NOT use for regular content.
 
 ## BorderRadius
 
 ### borderRadius-full
 Use this border radius for pill shaped elements
-**Usage:** avatar, pill-badge, circular-button
+**Usage:** avatar, circular-button, pill-badge
 **Rules:** 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.
-**Usage:** dialog, card, modal
+**Usage:** card, dialog, modal
 **Rules:** Recommended for dialogs and modals.
 
 ### borderRadius-medium
 Medium border radius (6px). The default choice for most buttons, cards, and containers
-**Usage:** button, input, textarea, select, card, container
+**Usage:** button, card, container, input, select, textarea
 **Rules:** 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
-**Usage:** badge, tag, label, small-input
+**Usage:** badge, label, small-input, tag
 **Rules:** Use for small UI elements under 16px height. Do NOT use for buttons or cards.
 
 ## BorderWidth
 
 ### borderWidth-thick
 Thick 2px border for emphasis. Use for focus indicators, selected states, or to emphasize important boundaries
-**Usage:** focus-indicator, selected-state, emphasis-border
+**Usage:** emphasis-border, focus-indicator, selected-state
 **Rules:** MUST use for focus rings on interactive elements. Do NOT use for subtle dividers.
 
+## Data
+
+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.
+
+**Usage:** area-chart, bar-fill, chart-series, data-point, graph-line, pie-segment
+**Rules:** Use data colors for visualizations only. Do NOT use for semantic meaning (use bgColor.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
 
 ### base-easing-ease
 CSS default easing. Use for hover state changes and micro-interactions.
-**Usage:** hover-state, micro-interaction, button-hover, link-hover
+**Usage:** button-hover, hover-state, link-hover, micro-interaction
 **Rules:** Use for hover state changes.
 
 ### base-easing-easeIn
 Accelerating motion. Use for elements exiting the viewport (moving off-screen).
-**Usage:** exit-animation, element-leaving, off-screen-motion
+**Usage:** element-leaving, exit-animation, off-screen-motion
 **Rules:** 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.
-**Usage:** position-change, size-change, morph-animation, expand-collapse, slide-transition
+**Usage:** expand-collapse, morph-animation, position-change, size-change, slide-transition
 **Rules:** Use if an element moves or morphs on screen.
 
 ### base-easing-easeOut
 Decelerating motion. Use for elements entering the viewport or appearing on screen.
-**Usage:** enter-animation, element-appearing, modal-open, dropdown-open, tooltip-appear
+**Usage:** dropdown-open, element-appearing, enter-animation, modal-open, tooltip-appear
 **Rules:** 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.
-**Usage:** progress-bar, loader, continuous-animation, scrolling
+**Usage:** continuous-animation, loader, progress-bar, scrolling
 **Rules:** Use if the motion is constant.
 
 ## text and foreground color
 
 ### fgColor-accent
 Accent text for links and interactive elements
-**Usage:** accent-text, info-text, accent-icon
+**Usage:** accent-icon, accent-text, info-text
 **Rules:** Use for accent-colored text and icons. Pair with bgColor.accent.muted for backgrounds.
 
 ### fgColor-attention
 Attention text for warnings and caution states
-**Usage:** attention-text, warning-text, caution-text
+**Usage:** attention-text, caution-text, warning-text
 **Rules:** Use for warning and caution text. Pair with bgColor.attention.muted for backgrounds.
 
 ### fgColor-closed
 Text color for closed state indicators (issues, PRs)
-**Usage:** closed-text, closed-issue, closed-pr
+**Usage:** closed-issue, closed-pr, closed-text
 **Rules:** Use for closed/declined status text. Specifically for GitHub issues and PRs.
 
 ### fgColor-danger
 Danger text for errors and destructive actions
-**Usage:** danger-text, error-text, destructive-text
+**Usage:** danger-text, destructive-text, error-text
 **Rules:** Use for error messages and destructive action text. Pair with bgColor.danger.muted for backgrounds.
 
 ### fgColor-default
 Default text color for primary content and headings
-**Usage:** default-text, heading, body-text
+**Usage:** body-text, default-text, heading
 **Rules:** RECOMMENDED default for all text. Use for headings, body text, and primary labels.
 
 ### fgColor-disabled
@@ -394,22 +403,22 @@ Text color for disabled interactive elements
 
 ### fgColor-done
 Text color for completed/done state indicators
-**Usage:** done-text, merged, completed
+**Usage:** completed, done-text, merged
 **Rules:** Use for completed/done status text. Conveys finished or merged state.
 
 ### fgColor-draft
 Text color for draft state indicators
-**Usage:** draft-text, draft-pr, draft-issue
+**Usage:** draft-issue, draft-pr, draft-text
 **Rules:** Use for draft/WIP status text. Conveys incomplete or pending state.
 
 ### fgColor-link
 Text color for hyperlinks
-**Usage:** link-text, hyperlink
+**Usage:** hyperlink, link-text
 **Rules:** MUST use for all text links. Provides expected link affordance.
 
 ### fgColor-muted
 Muted text for secondary content and less important information
-**Usage:** muted-text, secondary-text, helper-text, placeholder
+**Usage:** helper-text, muted-text, placeholder, secondary-text
 **Rules:** Use for secondary text like timestamps, metadata, and helper text. Do NOT use for primary content.
 
 ### fgColor-neutral
@@ -419,44 +428,51 @@ Neutral semantic text for icons and secondary elements
 
 ### fgColor-onEmphasis
 Text color for use on emphasis backgrounds
-**Usage:** text-on-emphasis, contrast-text
+**Usage:** contrast-text, text-on-emphasis
 **Rules:** MUST use for text on any emphasis background (bgColor.*.emphasis). Ensures accessibility contrast.
 
 ### fgColor-onInverse
 Text color for use on inverse backgrounds
-**Usage:** text-on-inverse, inverse-text
+**Usage:** inverse-text, text-on-inverse
 **Rules:** Use for text on bgColor.inverse. Provides appropriate contrast in both themes.
 
 ### fgColor-open
 Text color for open state indicators (issues, PRs)
-**Usage:** open-text, open-issue, open-pr
+**Usage:** open-issue, open-pr, open-text
 **Rules:** Use for open/active status text. Specifically for GitHub issues and PRs.
 
 ### fgColor-severe
 Severe text for high-priority warnings
-**Usage:** severe-text, urgent-text, severe-icon
+**Usage:** severe-icon, severe-text, urgent-text
 **Rules:** Use for severe warnings, less critical than danger. Pair with bgColor.severe.muted for backgrounds.
 
 ### fgColor-sponsors
 Text color for GitHub Sponsors content
-**Usage:** sponsors-text, funding-text, sponsors-icon
+**Usage:** funding-text, sponsors-icon, sponsors-text
 **Rules:** Use for GitHub Sponsors related text. Do NOT use for general pink-colored text.
 
 ### fgColor-success
 Success text for positive feedback and completed states
-**Usage:** success-text, positive-text, success-icon
+**Usage:** positive-text, success-icon, success-text
 **Rules:** Use for success states and positive feedback text. Pair with bgColor.success.muted for backgrounds.
 
 ### fgColor-upsell
 Text color for upsell and promotional content
-**Usage:** upsell-text, premium-text, promotional
+**Usage:** premium-text, promotional, upsell-text
 **Rules:** Use for upgrade prompts and premium feature text. Do NOT use for regular content.
 
+## Focus
+
+### focus-outlineColor
+Outline color for focus states on interactive elements
+**Usage:** accessibility-indicator, focus-ring, keyboard-navigation
+**Rules:** 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.
+
 ## FontStack
 
 ### fontStack-monospace
 Monospace font stack for code, technical content, and tabular data.
-**Usage:** code-block, inline-code, terminal, technical-data, tabular-numbers
+**Usage:** code-block, inline-code, tabular-numbers, technical-data, terminal
 **Rules:** MUST use for all code display. Use for technical content requiring fixed-width characters.
 
 ### fontStack-sansSerif
@@ -466,58 +482,65 @@ Sans-serif font stack for body text and general UI elements.
 
 ### fontStack-sansSerifDisplay
 Display font stack for headings and titles. Same as sansSerif but semantically distinct.
-**Usage:** heading, title, display-text, hero-text
+**Usage:** display-text, heading, hero-text, title
 **Rules:** Use for headings and display text. Prefer over sansSerif for titles.
 
 ## Outline
 
 ### outline-focus-width
 Focus outline width (2px). Standard width for keyboard focus indicators to meet WCAG 2.4.7 accessibility requirements
-**Usage:** focus-ring, keyboard-focus, accessibility
+**Usage:** accessibility, focus-ring, keyboard-focus
 **Rules:** MUST use for all keyboard focus indicators. Required for WCAG 2.4.7 compliance.
 
+## Selection
+
+### selection-bgColor
+Background color for text selection highlights
+**Usage:** highlighted-text, selected-content, text-selection
+**Rules:** Use for native text selection (::selection) and programmatic text highlighting. Do NOT use for general emphasis or background colors on containers.
+
 ## Shadow
 
 ### shadow-floating-large
 Large floating shadow for modals and dialogs
-**Usage:** modal, dialog, full-screen-overlay
+**Usage:** dialog, full-screen-overlay, modal
 **Rules:** 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
-**Usage:** dropdown, tooltip, popover, menu
+**Usage:** dropdown, menu, popover, tooltip
 **Rules:** Use for small floating elements like dropdowns and tooltips. Do NOT use for modals or dialogs.
 
 ## Text
 
 ### text-body-shorthand-large
 User-generated content, markdown rendering.
-**Usage:** markdown-content, article-text, readme, comment-body
+**Usage:** article-text, comment-body, markdown-content, readme
 **Rules:** 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.
-**Usage:** body-text, ui-text, form-label, button-text, navigation
+**Usage:** body-text, button-text, form-label, navigation, ui-text
 **Rules:** 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.
-**Usage:** helper-text, footnote, metadata, timestamp
+**Usage:** footnote, helper-text, metadata, timestamp
 **Rules:** 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.
-**Usage:** caption, label, badge-text, single-line-metadata
+**Usage:** badge-text, caption, label, single-line-metadata
 **Rules:** Use only for single-line or short text. Does NOT meet accessibility requirements for body text.
 
 ### text-codeBlock-shorthand
 Default style for rendering code blocks.
-**Usage:** code-block, pre-element, code-snippet, terminal-output
+**Usage:** code-block, code-snippet, pre-element, terminal-output
 **Rules:** 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.
-**Usage:** inline-code, code-element, variable-name, command
+**Usage:** code-element, command, inline-code, variable-name
 **Rules:** Use for inline code within text. Size inherits from parent using em units.
 
 ### text-display-shorthand
@@ -527,20 +550,20 @@ Hero-style text for brand to product transition pages. Utilize Title (large) sty
 
 ### 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).
-**Usage:** subtitle, description, secondary-heading, lead-text
+**Usage:** description, lead-text, secondary-heading, subtitle
 **Rules:** 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.
-**Usage:** page-heading, issue-title, pr-title, h1
+**Usage:** h1, issue-title, page-heading, pr-title
 **Rules:** 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.
-**Usage:** section-heading, card-title, dialog-title, h2
+**Usage:** card-title, dialog-title, h2, section-heading
 **Rules:** 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).
-**Usage:** subsection-heading, list-title, h3, sidebar-heading
+**Usage:** h3, list-title, sidebar-heading, subsection-heading
 **Rules:** Use for smaller headings within sections. Same size as body.large but semibold.