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

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

@@ -1,7 +1,9 @@
 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']
+ * 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`
  */

package/dist/build/formats/markdownLlmGuidelines.js

@@ -8,6 +8,17 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 import { sortByName } from 'style-dictionary/utils';
+/**
+ * Creates a unique key for grouping tokens with identical guidelines
+ */
+function createGuidelineKey(guideline) {
+    var _a;
+    return JSON.stringify({
+        description: guideline.description || '',
+        usage: ((_a = guideline.usage) === null || _a === void 0 ? void 0 : _a.sort()) || [],
+        rules: guideline.rules || '',
+    });
+}
 /**
  * Extracts category from token name
  * - For "base-*" tokens, uses second word (e.g., "base-easing-ease" -> "easing")
@@ -36,7 +47,9 @@ function formatCategoryName(category) {
 }
 /**
  * @description Outputs a markdown file with LLM token guidelines, extracting
- * description from $description and usage/rules from $extensions['org.primer.llm']
+ * 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`
  */
@@ -75,18 +88,48 @@ export const markdownLlmGuidelines = (_a) => __awaiter(void 0, [_a], void 0, fun
     const lines = ['# Token Guidelines', ''];
     for (const category of Object.keys(grouped).sort()) {
         lines.push(`## ${formatCategoryName(category)}`, '');
-        for (const guideline of grouped[category]) {
-            lines.push(`### ${guideline.name}`);
-            if (guideline.description) {
-                lines.push(guideline.description);
+        const categoryGuidelines = grouped[category];
+        // Group tokens with identical guidelines
+        const consolidatedGroups = new Map();
+        for (const guideline of categoryGuidelines) {
+            const key = createGuidelineKey(guideline);
+            if (!consolidatedGroups.has(key)) {
+                consolidatedGroups.set(key, []);
             }
-            if (guideline.usage && guideline.usage.length > 0) {
-                lines.push(`**Usage:** ${guideline.usage.join(', ')}`);
+            consolidatedGroups.get(key).push(guideline);
+        }
+        for (const [, guidelinesGroup] of consolidatedGroups) {
+            const first = guidelinesGroup[0];
+            if (guidelinesGroup.length > 1) {
+                // Multiple tokens share the same guidelines - consolidate
+                if (first.description) {
+                    lines.push(first.description);
+                    lines.push('');
+                }
+                if (first.usage && first.usage.length > 0) {
+                    lines.push(`**Usage:** ${first.usage.join(', ')}`);
+                }
+                if (first.rules) {
+                    lines.push(`**Rules:** ${first.rules}`);
+                }
+                lines.push('');
+                lines.push(`**Tokens:** ${guidelinesGroup.map(g => g.name).join(', ')}`);
+                lines.push('');
             }
-            if (guideline.rules) {
-                lines.push(`**Rules:** ${guideline.rules}`);
+            else {
+                // Single token - output individually
+                lines.push(`### ${first.name}`);
+                if (first.description) {
+                    lines.push(first.description);
+                }
+                if (first.usage && first.usage.length > 0) {
+                    lines.push(`**Usage:** ${first.usage.join(', ')}`);
+                }
+                if (first.rules) {
+                    lines.push(`**Rules:** ${first.rules}`);
+                }
+                lines.push('');
             }
-            lines.push('');
         }
     }
     return lines.join('\n');

package/dist/build/platforms/llmGuidelines.js

@@ -2,6 +2,7 @@ import { hasLlmExtensions } from '../filters/index.js';
 export const llmGuidelines = (outputFile, prefix, buildPath) => ({
     prefix,
     buildPath,
+    preprocessors: ['inheritGroupProperties'],
     transforms: ['name/pathToKebabCase'],
     files: [
         {

package/dist/build/preprocessors/inheritGroupProperties.d.ts

@@ -0,0 +1,7 @@
+import type { Preprocessor } from 'style-dictionary/types';
+/**
+ * Preprocessor that inherits group-level $description and $extensions to child tokens.
+ * This enables W3C Design Tokens group properties to be available on individual tokens
+ * during formatting.
+ */
+export declare const inheritGroupProperties: Preprocessor;

package/dist/build/preprocessors/inheritGroupProperties.js

@@ -0,0 +1,70 @@
+/**
+ * Recursively walks tokens and inherits group-level properties to child tokens.
+ * Group properties ($description, $extensions at group level) are merged into child tokens
+ * that don't have their own values for those properties.
+ *
+ * Per W3C Design Tokens spec: https://www.designtokens.org/tr/drafts/format/#group-properties
+ */
+function inheritProperties(tokens, inheritedProps = {}) {
+    var _a;
+    const result = {};
+    // Extract group-level properties from current level
+    const currentGroupProps = {};
+    if (typeof tokens.$description === 'string') {
+        currentGroupProps.$description = tokens.$description;
+    }
+    if (tokens.$extensions && typeof tokens.$extensions === 'object') {
+        currentGroupProps.$extensions = tokens.$extensions;
+    }
+    // Merge inherited with current (current takes precedence)
+    const mergedProps = Object.assign(Object.assign({}, inheritedProps), currentGroupProps);
+    // Merge $extensions deeply
+    if (inheritedProps.$extensions || currentGroupProps.$extensions) {
+        mergedProps.$extensions = Object.assign(Object.assign({}, inheritedProps.$extensions), currentGroupProps.$extensions);
+    }
+    for (const [key, value] of Object.entries(tokens)) {
+        // Skip group-level properties (they're inherited, not copied)
+        if (key === '$description' || key === '$extensions') {
+            continue;
+        }
+        if (typeof value !== 'object' || value === null) {
+            result[key] = value;
+            continue;
+        }
+        const tokenValue = value;
+        // Check if this is a design token (has $value or value)
+        if ('$value' in tokenValue || 'value' in tokenValue) {
+            // It's a token - merge inherited properties
+            const token = tokenValue;
+            // Only inherit $description if token doesn't have its own
+            const inheritedDescription = !token.$description && mergedProps.$description ? mergedProps.$description : undefined;
+            // Merge $extensions (token-level takes precedence over inherited)
+            let mergedExtensions = token.$extensions;
+            if (mergedProps.$extensions) {
+                const inheritedLlm = mergedProps.$extensions['org.primer.llm'];
+                const tokenLlm = (_a = token.$extensions) === null || _a === void 0 ? void 0 : _a['org.primer.llm'];
+                if (inheritedLlm && !tokenLlm) {
+                    // Token has no LLM extension, inherit from group
+                    mergedExtensions = Object.assign(Object.assign({}, token.$extensions), { 'org.primer.llm': inheritedLlm });
+                }
+            }
+            result[key] = Object.assign(Object.assign(Object.assign({}, token), (inheritedDescription ? { $description: inheritedDescription } : {})), (mergedExtensions ? { $extensions: mergedExtensions } : {}));
+        }
+        else {
+            // It's a nested group - recurse with merged properties
+            result[key] = inheritProperties(tokenValue, mergedProps);
+        }
+    }
+    return result;
+}
+/**
+ * Preprocessor that inherits group-level $description and $extensions to child tokens.
+ * This enables W3C Design Tokens group properties to be available on individual tokens
+ * during formatting.
+ */
+export const inheritGroupProperties = {
+    name: 'inheritGroupProperties',
+    preprocessor: (dictionary) => {
+        return inheritProperties(dictionary);
+    },
+};

package/dist/build/primerStyleDictionary.js

@@ -2,6 +2,7 @@ import StyleDictionary from 'style-dictionary';
 import { borderToCss, colorToRgbAlpha, colorToHex, colorToRgbaFloat, cubicBezierToCss, dimensionToRem, dimensionToPixelUnitless, durationToCss, figmaAttributes, fontFamilyToCss, fontFamilyToFigma, fontWeightToNumber, gradientToCss, jsonDeprecated, namePathToDotNotation, namePathToCamelCase, namePathToPascalCase, namePathToKebabCase, namePathToSlashNotation, namePathToFigma, shadowToCss, typographyToCss, dimensionToRemPxArray, floatToPixel, floatToPixelUnitless, transitionToCss, } from './transformers/index.js';
 import { javascriptCommonJs, javascriptEsm, typescriptExportDefinition, jsonNestedPrefixed, cssCustomMedia, jsonOneDimensional, jsonPostCssFallback, cssAdvanced, jsonFigma, markdownLlmGuidelines, } from './formats/index.js';
 import { themeOverrides } from './preprocessors/themeOverrides.js';
+import { inheritGroupProperties } from './preprocessors/inheritGroupProperties.js';
 import { colorAlphaToCss } from './transformers/colorAlphaToCss.js';
 /**
  * @name {@link PrimerStyleDictionary}
@@ -92,3 +93,4 @@ PrimerStyleDictionary.registerTransform(fontFamilyToCss);
 PrimerStyleDictionary.registerTransform(fontFamilyToFigma);
 PrimerStyleDictionary.registerTransform(gradientToCss);
 PrimerStyleDictionary.registerPreprocessor(themeOverrides);
+PrimerStyleDictionary.registerPreprocessor(inheritGroupProperties);

package/dist/build/schemas/designToken.d.ts

@@ -1,2 +1,2 @@
 import { z } from 'zod';
-export declare const designToken: z.ZodRecord<z.ZodString, z.ZodLazy<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>>;
+export declare const designToken: z.ZodType<unknown>;

package/dist/build/schemas/designToken.js

@@ -14,26 +14,118 @@ import { durationToken } from './durationToken.js';
 import { cubicBezierToken } from './cubicBezierToken.js';
 import { gradientToken } from './gradientToken.js';
 import { transitionToken } from './transitionToken.js';
+import { llmExtension } from './llmExtension.js';
+/**
+ * Group-level extensions schema (W3C Design Tokens spec)
+ * https://www.designtokens.org/tr/drafts/format/#group-properties
+ */
+const groupExtensions = z
+    .object({
+    'org.primer.llm': llmExtension,
+})
+    .passthrough();
+/**
+ * All valid token types with $type discriminator
+ */
+const tokenTypes = z.discriminatedUnion('$type', [
+    colorToken,
+    cubicBezierToken,
+    dimensionToken,
+    shadowToken,
+    borderToken,
+    fontFamilyToken,
+    fontWeightToken,
+    gradientToken,
+    typographyToken,
+    viewportRangeToken,
+    numberToken,
+    durationToken,
+    stringToken,
+    transitionToken,
+]);
+/**
+ * Validates a record allowing both token names and group properties ($description, $extensions)
+ * Recursively validates nested groups
+ */
+const createDesignTokenSchema = () => {
+    return z.record(z.string(), z.unknown()).superRefine((obj, ctx) => {
+        for (const [key, value] of Object.entries(obj)) {
+            if (key === '$description') {
+                // Group-level $description must be a string
+                if (typeof value !== 'string') {
+                    ctx.addIssue({
+                        code: z.ZodIssueCode.custom,
+                        message: `$description must be a string, got ${typeof value}`,
+                        path: [key],
+                    });
+                }
+            }
+            else if (key === '$extensions') {
+                // Group-level $extensions must be an object
+                if (typeof value !== 'object' || value === null) {
+                    ctx.addIssue({
+                        code: z.ZodIssueCode.custom,
+                        message: `$extensions must be an object`,
+                        path: [key],
+                    });
+                }
+                else {
+                    const result = groupExtensions.safeParse(value);
+                    if (!result.success) {
+                        for (const issue of result.error.issues) {
+                            ctx.addIssue(Object.assign(Object.assign({}, issue), { path: [key, ...issue.path] }));
+                        }
+                    }
+                }
+            }
+            else if (key.startsWith('$')) {
+                // Unknown $-prefixed keys at group level are not allowed
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: `Unknown group property: ${key}. Only $description and $extensions are allowed.`,
+                    path: [key],
+                });
+            }
+            else {
+                // Validate token name
+                const nameResult = tokenName.safeParse(key);
+                if (!nameResult.success) {
+                    for (const issue of nameResult.error.issues) {
+                        ctx.addIssue(Object.assign(Object.assign({}, issue), { path: [key] }));
+                    }
+                }
+                // Validate value as either a token or nested group
+                if (typeof value === 'object' && value !== null) {
+                    // Check if it's a token (has $type) or a nested group
+                    if ('$type' in value) {
+                        const tokenResult = tokenTypes.safeParse(value);
+                        if (!tokenResult.success) {
+                            for (const issue of tokenResult.error.issues) {
+                                ctx.addIssue(Object.assign(Object.assign({}, issue), { path: [key, ...issue.path] }));
+                            }
+                        }
+                    }
+                    else {
+                        // Recursively validate nested group
+                        const nestedResult = designToken.safeParse(value);
+                        if (!nestedResult.success) {
+                            for (const issue of nestedResult.error.issues) {
+                                ctx.addIssue(Object.assign(Object.assign({}, issue), { path: [key, ...issue.path] }));
+                            }
+                        }
+                    }
+                }
+                else {
+                    ctx.addIssue({
+                        code: z.ZodIssueCode.custom,
+                        message: `Expected token or group object, got ${typeof value}`,
+                        path: [key],
+                    });
+                }
+            }
+        }
+    });
+};
 // eslint-disable-next-line @typescript-eslint/ban-ts-comment
 // @ts-ignore: TODO: fix this
-export const designToken = z.record(tokenName, z.lazy(() => {
-    return z.union([
-        z.discriminatedUnion('$type', [
-            colorToken,
-            cubicBezierToken,
-            dimensionToken,
-            shadowToken,
-            borderToken,
-            fontFamilyToken,
-            fontWeightToken,
-            gradientToken,
-            typographyToken,
-            viewportRangeToken,
-            numberToken,
-            durationToken,
-            stringToken,
-            transitionToken,
-        ]),
-        designToken,
-    ]);
-}));
+export const designToken = createDesignTokenSchema();

package/dist/build/schemas/dimensionToken.d.ts

@@ -5,11 +5,11 @@ export declare const dimensionToken: z.ZodObject<{
     $value: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<"0">, z.ZodLiteral<0>]>, z.ZodString]>;
     $type: z.ZodLiteral<"string" | "number" | "border" | "color" | "fontFamily" | "fontWeight" | "transition" | "dimension" | "duration" | "gradient" | "shadow" | "typography" | "cubicBezier" | "custom-viewportRange">;
     $extensions: z.ZodOptional<z.ZodObject<{
-        'org.primer.figma': z.ZodObject<{
+        'org.primer.figma': z.ZodOptional<z.ZodObject<{
             collection: z.ZodString;
             scopes: z.ZodArray<z.ZodString>;
             group: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>;
+        }, z.core.$strip>>;
         'org.primer.llm': z.ZodOptional<z.ZodObject<{
             usage: z.ZodOptional<z.ZodArray<z.ZodString>>;
             rules: z.ZodOptional<z.ZodString>;

package/dist/build/schemas/dimensionToken.js

@@ -12,7 +12,8 @@ export const dimensionToken = baseToken
     $type: tokenType('dimension'),
     $extensions: z
         .object({
-        'org.primer.figma': z.object({
+        'org.primer.figma': z
+            .object({
             collection: collection(['base/size', 'base/typography', 'functional/size', 'pattern/size', 'typography']),
             scopes: scopes([
                 'all',
@@ -29,7 +30,8 @@ export const dimensionToken = baseToken
                 'paragraphIndent',
             ]),
             group: z.string().optional(),
-        }),
+        })
+            .optional(),
         'org.primer.llm': llmExtension,
     })
         .optional(),

package/dist/build/schemas/validTokenType.d.ts

@@ -1,5 +1,9 @@
 import { z } from 'zod';
 declare const validTypes: readonly ["color", "cubicBezier", "typography", "dimension", "duration", "border", "shadow", "fontFamily", "fontWeight", "gradient", "number", "string", "transition", "custom-viewportRange"];
 export type TokenType = (typeof validTypes)[number];
-export declare const validateType: z.ZodRecord<z.ZodString, z.ZodLazy<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>>;
+/**
+ * Recursively validates $type properties in token structure
+ * Allows group-level properties ($description, $extensions) per W3C Design Tokens spec
+ */
+export declare const validateType: z.ZodType<unknown>;
 export {};

package/dist/build/schemas/validTokenType.js

@@ -16,23 +16,77 @@ const validTypes = [
     'transition',
     'custom-viewportRange',
 ];
+/**
+ * Token schema that validates $type property
+ */
+const tokenWithType = z
+    .object({
+    $value: z.any(),
+    $type: z.string().superRefine((value, ctx) => {
+        if (!validTypes.includes(value)) {
+            ctx.addIssue({
+                code: 'custom',
+                message: schemaErrorMessage(`Invalid token $type: "${value}"`, `Must be one of the following: ${joinFriendly([...validTypes], 'or')}`),
+            });
+        }
+    }),
+})
+    .required();
+/**
+ * Recursively validates $type properties in token structure
+ * Allows group-level properties ($description, $extensions) per W3C Design Tokens spec
+ */
 // eslint-disable-next-line @typescript-eslint/ban-ts-comment
 // @ts-ignore: TODO: fix this
-export const validateType = z.record(z.string(), z.lazy(() => {
-    return z.union([
-        z
-            .object({
-            $value: z.any(),
-            $type: z.string().superRefine((value, ctx) => {
-                if (!validTypes.includes(value)) {
-                    ctx.addIssue({
-                        code: 'custom',
-                        message: schemaErrorMessage(`Invalid token $type: "${value}"`, `Must be one of the following: ${joinFriendly([...validTypes], 'or')}`),
-                    });
+export const validateType = z.record(z.string(), z.unknown()).superRefine((obj, ctx) => {
+    for (const [key, value] of Object.entries(obj)) {
+        if (key === '$description') {
+            // Group-level $description must be a string
+            if (typeof value !== 'string') {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: `$description must be a string`,
+                    path: [key],
+                });
+            }
+        }
+        else if (key === '$extensions') {
+            // Group-level $extensions must be an object
+            if (typeof value !== 'object' || value === null) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: `$extensions must be an object`,
+                    path: [key],
+                });
+            }
+        }
+        else if (key.startsWith('$')) {
+            // Unknown $-prefixed keys are not allowed
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `Unknown group property: ${key}`,
+                path: [key],
+            });
+        }
+        else if (typeof value === 'object' && value !== null) {
+            // Check if it's a token (has $type) or a nested group
+            if ('$type' in value) {
+                const result = tokenWithType.safeParse(value);
+                if (!result.success) {
+                    for (const issue of result.error.issues) {
+                        ctx.addIssue(Object.assign(Object.assign({}, issue), { path: [key, ...issue.path] }));
+                    }
                 }
-            }),
-        })
-            .required(),
-        validateType,
-    ]);
-}));
+            }
+            else {
+                // Recursively validate nested group
+                const result = validateType.safeParse(value);
+                if (!result.success) {
+                    for (const issue of result.error.issues) {
+                        ctx.addIssue(Object.assign(Object.assign({}, issue), { path: [key, ...issue.path] }));
+                    }
+                }
+            }
+        }
+    }
+});

package/dist/css/functional/size/size-coarse.css

@@ -1,7 +1,7 @@
 @media (pointer: coarse) {
   :root {
-    --control-minTarget-auto: 2.75rem;
-    --controlStack-medium-gap-auto: 0.75rem;
-    --controlStack-small-gap-auto: 1rem;
+    --control-minTarget-auto: 2.75rem; /** Minimum touch target size for coarse pointer devices (touch screens) */
+    --controlStack-medium-gap-auto: 0.75rem; /** Gap between stacked controls in medium density layouts for touch devices */
+    --controlStack-small-gap-auto: 1rem; /** Gap between stacked controls in small density layouts for touch devices */
   }
 }

package/dist/css/functional/size/size-fine.css

@@ -1,7 +1,7 @@
 @media (pointer: fine) {
   :root {
-    --control-minTarget-auto: 1rem;
-    --controlStack-medium-gap-auto: 0.5rem;
-    --controlStack-small-gap-auto: 0.5rem;
+    --control-minTarget-auto: 1rem; /** Minimum target size for fine pointer devices (mouse) */
+    --controlStack-medium-gap-auto: 0.5rem; /** Gap between stacked controls in medium density layouts for mouse interfaces */
+    --controlStack-small-gap-auto: 0.5rem; /** Gap between stacked controls in small density layouts for mouse interfaces */
   }
 }

package/dist/css/functional/themes/dark-colorblind-high-contrast.css

@@ -759,7 +759,7 @@
   --fgColor-onEmphasis: #ffffff; /** Text color for use on emphasis backgrounds */
   --fgColor-onInverse: #010409; /** Text color for use on inverse backgrounds */
   --fgColor-white: #ffffff; /** Pure white text */
-  --focus-outlineColor: var(--borderColor-accent-emphasis);
+  --focus-outlineColor: var(--borderColor-accent-emphasis); /** Outline color for focus states on interactive elements */
   --header-fgColor-default: #ffffffb3;
   --label-auburn-borderColor: var(--label-auburn-fgColor-rest);
   --label-blue-borderColor: var(--label-blue-fgColor-rest);
@@ -791,7 +791,7 @@
   --progressBar-bgColor-success: var(--bgColor-success-emphasis);
   --reactionButton-selected-fgColor-rest: var(--fgColor-link);
   --selectMenu-borderColor: var(--borderColor-default);
-  --selection-bgColor: #194fb1b3;
+  --selection-bgColor: #194fb1b3; /** Background color for text selection highlights */
   --shadow-floating-legacy: 0px 6px 12px -3px #01040966, 0px 6px 18px 0px #01040966;
   --shadow-inset: inset 0px 1px 0px 0px #0104093d;
   --shadow-resting-medium: 0px 1px 1px 0px #01040966, 0px 3px 6px 0px #010409cc;
@@ -1656,7 +1656,7 @@
     --fgColor-onEmphasis: #ffffff; /** Text color for use on emphasis backgrounds */
     --fgColor-onInverse: #010409; /** Text color for use on inverse backgrounds */
     --fgColor-white: #ffffff; /** Pure white text */
-    --focus-outlineColor: var(--borderColor-accent-emphasis);
+    --focus-outlineColor: var(--borderColor-accent-emphasis); /** Outline color for focus states on interactive elements */
     --header-fgColor-default: #ffffffb3;
     --label-auburn-borderColor: var(--label-auburn-fgColor-rest);
     --label-blue-borderColor: var(--label-blue-fgColor-rest);
@@ -1688,7 +1688,7 @@
     --progressBar-bgColor-success: var(--bgColor-success-emphasis);
     --reactionButton-selected-fgColor-rest: var(--fgColor-link);
     --selectMenu-borderColor: var(--borderColor-default);
-    --selection-bgColor: #194fb1b3;
+    --selection-bgColor: #194fb1b3; /** Background color for text selection highlights */
     --shadow-floating-legacy: 0px 6px 12px -3px #01040966, 0px 6px 18px 0px #01040966;
     --shadow-inset: inset 0px 1px 0px 0px #0104093d;
     --shadow-resting-medium: 0px 1px 1px 0px #01040966, 0px 3px 6px 0px #010409cc;

package/dist/css/functional/themes/dark-colorblind.css

@@ -799,7 +799,7 @@
   --fgColor-onInverse: #010409; /** Text color for use on inverse backgrounds */
   --fgColor-upsell: var(--fgColor-done); /** Text color for upsell and promotional content */
   --fgColor-white: #ffffff; /** Pure white text */
-  --focus-outlineColor: var(--borderColor-accent-emphasis);
+  --focus-outlineColor: var(--borderColor-accent-emphasis); /** Outline color for focus states on interactive elements */
   --header-fgColor-default: #ffffffb3;
   --overlay-bgColor: #010409;
   --page-header-bgColor: var(--bgColor-default);
@@ -814,7 +814,7 @@
   --progressBar-track-bgColor: var(--borderColor-default);
   --reactionButton-selected-fgColor-rest: var(--fgColor-link);
   --selectMenu-borderColor: var(--borderColor-default);
-  --selection-bgColor: #1f6febb3;
+  --selection-bgColor: #1f6febb3; /** Background color for text selection highlights */
   --shadow-floating-legacy: 0px 6px 12px -3px #01040966, 0px 6px 18px 0px #01040966;
   --shadow-inset: inset 0px 1px 0px 0px #0104093d;
   --shadow-resting-medium: 0px 1px 1px 0px #01040966, 0px 3px 6px 0px #010409cc;
@@ -1696,7 +1696,7 @@
     --fgColor-onInverse: #010409; /** Text color for use on inverse backgrounds */
     --fgColor-upsell: var(--fgColor-done); /** Text color for upsell and promotional content */
     --fgColor-white: #ffffff; /** Pure white text */
-    --focus-outlineColor: var(--borderColor-accent-emphasis);
+    --focus-outlineColor: var(--borderColor-accent-emphasis); /** Outline color for focus states on interactive elements */
     --header-fgColor-default: #ffffffb3;
     --overlay-bgColor: #010409;
     --page-header-bgColor: var(--bgColor-default);
@@ -1711,7 +1711,7 @@
     --progressBar-track-bgColor: var(--borderColor-default);
     --reactionButton-selected-fgColor-rest: var(--fgColor-link);
     --selectMenu-borderColor: var(--borderColor-default);
-    --selection-bgColor: #1f6febb3;
+    --selection-bgColor: #1f6febb3; /** Background color for text selection highlights */
     --shadow-floating-legacy: 0px 6px 12px -3px #01040966, 0px 6px 18px 0px #01040966;
     --shadow-inset: inset 0px 1px 0px 0px #0104093d;
     --shadow-resting-medium: 0px 1px 1px 0px #01040966, 0px 3px 6px 0px #010409cc;

package/dist/css/functional/themes/dark-dimmed-high-contrast.css

@@ -791,7 +791,7 @@
   --fgColor-open: var(--fgColor-success); /** Text color for open state indicators (issues, PRs) */
   --fgColor-upsell: var(--fgColor-done); /** Text color for upsell and promotional content */
   --fgColor-white: #cdd9e5; /** Pure white text */
-  --focus-outlineColor: var(--borderColor-accent-emphasis);
+  --focus-outlineColor: var(--borderColor-accent-emphasis); /** Outline color for focus states on interactive elements */
   --header-fgColor-default: #cdd9e5b3;
   --label-auburn-borderColor: var(--label-auburn-fgColor-rest);
   --label-blue-borderColor: var(--label-blue-fgColor-rest);
@@ -822,7 +822,7 @@
   --progressBar-bgColor-sponsors: var(--bgColor-sponsors-emphasis);
   --progressBar-bgColor-success: var(--bgColor-success-emphasis);
   --selectMenu-borderColor: var(--borderColor-default);
-  --selection-bgColor: #1b4b91b3;
+  --selection-bgColor: #1b4b91b3; /** Background color for text selection highlights */
   --shadow-floating-legacy: 0px 6px 12px -3px #01040966, 0px 6px 18px 0px #01040966;
   --shadow-inset: inset 0px 1px 0px 0px #0104093d;
   --shadow-resting-medium: 0px 1px 1px 0px #01040966, 0px 3px 6px 0px #010409cc;
@@ -1688,7 +1688,7 @@
     --fgColor-open: var(--fgColor-success); /** Text color for open state indicators (issues, PRs) */
     --fgColor-upsell: var(--fgColor-done); /** Text color for upsell and promotional content */
     --fgColor-white: #cdd9e5; /** Pure white text */
-    --focus-outlineColor: var(--borderColor-accent-emphasis);
+    --focus-outlineColor: var(--borderColor-accent-emphasis); /** Outline color for focus states on interactive elements */
     --header-fgColor-default: #cdd9e5b3;
     --label-auburn-borderColor: var(--label-auburn-fgColor-rest);
     --label-blue-borderColor: var(--label-blue-fgColor-rest);
@@ -1719,7 +1719,7 @@
     --progressBar-bgColor-sponsors: var(--bgColor-sponsors-emphasis);
     --progressBar-bgColor-success: var(--bgColor-success-emphasis);
     --selectMenu-borderColor: var(--borderColor-default);
-    --selection-bgColor: #1b4b91b3;
+    --selection-bgColor: #1b4b91b3; /** Background color for text selection highlights */
     --shadow-floating-legacy: 0px 6px 12px -3px #01040966, 0px 6px 18px 0px #01040966;
     --shadow-inset: inset 0px 1px 0px 0px #0104093d;
     --shadow-resting-medium: 0px 1px 1px 0px #01040966, 0px 3px 6px 0px #010409cc;