@datalayer/primer-addons 1.0.10 → 1.0.12

package/lib/theme/colors/indicatorColors.js

@@ -0,0 +1,68 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/* ── Per-theme palettes ────────────────────────────────── */
+const datalayer = {
+    neutral: '#656D76',
+    muted: '#8b949e',
+    pending: '#d29922',
+    warning: '#d29922',
+    danger: '#d1242f',
+    success: '#16A085',
+    info: '#0969da',
+    reservation: '#656D76',
+    credits: '#16A085',
+    inviteJoined: '#0969da',
+    invitePending: '#cfd3d7',
+};
+const spatial = {
+    neutral: '#8892B0',
+    muted: '#6B7394',
+    pending: '#E2B340',
+    warning: '#E2B340',
+    danger: '#FF5252',
+    success: '#4F46E5',
+    info: '#448AFF',
+    reservation: '#8892B0',
+    credits: '#4F46E5',
+    inviteJoined: '#448AFF',
+    invitePending: '#6B7394',
+};
+const lovely = {
+    neutral: '#9D7A8F',
+    muted: '#C9A2B8',
+    pending: '#FFD740',
+    warning: '#FFD740',
+    danger: '#FF1744',
+    success: '#DB2777',
+    info: '#536DFE',
+    reservation: '#9D7A8F',
+    credits: '#DB2777',
+    inviteJoined: '#536DFE',
+    invitePending: '#C9A2B8',
+};
+const matrix = {
+    neutral: '#5A6E3A',
+    muted: '#7A9A50',
+    pending: '#FFD600',
+    warning: '#FFD600',
+    danger: '#FF3D00',
+    success: '#00C853',
+    info: '#00E676',
+    reservation: '#5A6E3A',
+    credits: '#00C853',
+    inviteJoined: '#00E676',
+    invitePending: '#7A9A50',
+};
+/* ── Public map ────────────────────────────────────────── */
+export const indicatorColors = {
+    datalayer,
+    spatial,
+    lovely,
+    matrix,
+};
+/**
+ * Convenience: default indicator palette (Datalayer theme).
+ */
+export const defaultIndicatorColors = datalayer;

package/lib/theme/colors/lovelyColors.d.ts

@@ -12,4 +12,18 @@ export declare const lovelyColors: {
     roseTint: string;
     roseBright: string;
     roseHover: string;
+    brightGlow: string;
+    brightPop: string;
+    brightSpark: string;
+    brightBlaze: string;
+    brightSurge: string;
+    brightFlame: string;
+    brightGold: string;
+    brightLightGlow: string;
+    brightLightPop: string;
+    brightLightSpark: string;
+    brightLightBlaze: string;
+    brightLightSurge: string;
+    brightLightFlame: string;
+    brightLightGold: string;
 };

package/lib/theme/colors/lovelyColors.js

@@ -18,4 +18,21 @@ export const lovelyColors = {
     roseTint: '#FDF2F8', // Soft background for callouts
     roseBright: '#F472B6', // Highlights & glow on dark
     roseHover: '#831843', // Primary button hover
+    // Bright / vivid colours for SVG illustrations (OpenAI-blog style)
+    brightGlow: '#FF4081', // Hot pink — primary glow
+    brightPop: '#FF6E40', // Vivid coral — contrasting accent
+    brightSpark: '#EA80FC', // Electric fuchsia — sparkle / tertiary
+    brightBlaze: '#FF1744', // Vivid crimson — warm accent
+    brightSurge: '#536DFE', // Indigo blue — cool accent
+    // Warm vivid colours — yellow & orange accents for SVG illustrations
+    brightFlame: '#FF6E40', // Coral orange — warm blush accent
+    brightGold: '#FFD740', // Amber gold — golden warmth
+    // Vivid brights for light backgrounds — punchy, saturated, OpenAI-blog vibrancy
+    brightLightGlow: '#FF4081', // Hot pink
+    brightLightPop: '#FF6E40', // Vivid coral
+    brightLightSpark: '#EA80FC', // Electric fuchsia
+    brightLightBlaze: '#FF1744', // Vivid crimson
+    brightLightSurge: '#536DFE', // Vivid indigo
+    brightLightFlame: '#FF6E40', // Vivid coral orange
+    brightLightGold: '#FFD740', // Vivid amber gold
 };

package/lib/theme/colors/matrixColors.d.ts

@@ -17,4 +17,18 @@ export declare const matrixColors: {
     greenGlow: string;
     greenHover: string;
     greenTerminal: string;
+    brightGlow: string;
+    brightPop: string;
+    brightSpark: string;
+    brightBlaze: string;
+    brightSurge: string;
+    brightFlame: string;
+    brightGold: string;
+    brightLightGlow: string;
+    brightLightPop: string;
+    brightLightSpark: string;
+    brightLightBlaze: string;
+    brightLightSurge: string;
+    brightLightFlame: string;
+    brightLightGold: string;
 };

package/lib/theme/colors/matrixColors.js

@@ -23,4 +23,21 @@ export const matrixColors = {
     greenGlow: '#39FF14', // Neon phosphor glow — brightest accent on dark
     greenHover: '#0E6655', // Datalayer hover — primary button hover
     greenTerminal: '#003B00', // Deep terminal — dark mode subtle/canvas
+    // Bright / vivid colours for SVG illustrations (OpenAI-blog style)
+    brightGlow: '#39FF14', // Neon green — primary glow (re-stated for palette API)
+    brightPop: '#00FF88', // Phosphor cyan — contrasting accent
+    brightSpark: '#CCFF00', // Acid lime — sparkle / tertiary
+    brightBlaze: '#FF0040', // Matrix red pill — warm accent
+    brightSurge: '#00E5FF', // Electric blue — cool accent
+    // Warm vivid colours — yellow & orange accents for SVG illustrations
+    brightFlame: '#FF6D00', // Electric orange — glitch warm accent
+    brightGold: '#FFEA00', // Glitch yellow — phosphor highlight
+    // Vivid brights for light backgrounds — punchy, saturated, OpenAI-blog vibrancy
+    brightLightGlow: '#00E676', // Vivid green
+    brightLightPop: '#1DE9B6', // Vivid teal-mint
+    brightLightSpark: '#AEEA00', // Vivid lime
+    brightLightBlaze: '#FF1744', // Vivid red
+    brightLightSurge: '#00B0FF', // Vivid sky blue
+    brightLightFlame: '#FF6D00', // Vivid orange
+    brightLightGold: '#FFAB00', // Vivid amber
 };

package/lib/theme/colors/spatialColors.d.ts

@@ -12,4 +12,18 @@ export declare const spatialColors: {
     indigoTint: string;
     indigoBright: string;
     indigoHover: string;
+    brightGlow: string;
+    brightPop: string;
+    brightSpark: string;
+    brightBlaze: string;
+    brightSurge: string;
+    brightFlame: string;
+    brightGold: string;
+    brightLightGlow: string;
+    brightLightPop: string;
+    brightLightSpark: string;
+    brightLightBlaze: string;
+    brightLightSurge: string;
+    brightLightFlame: string;
+    brightLightGold: string;
 };

package/lib/theme/colors/spatialColors.js

@@ -18,4 +18,21 @@ export const spatialColors = {
     indigoTint: '#EEF2FF', // Soft background for callouts
     indigoBright: '#818CF8', // Highlights & glow on dark
     indigoHover: '#312E81', // Primary button hover
+    // Bright / vivid colours for SVG illustrations (OpenAI-blog style)
+    brightGlow: '#7C4DFF', // Electric violet — primary glow
+    brightPop: '#448AFF', // Neon blue — contrasting accent
+    brightSpark: '#E040FB', // Vivid magenta — sparkle / tertiary
+    brightBlaze: '#FF5252', // Neon red — warm accent
+    brightSurge: '#00B0FF', // Deep sky blue — cool accent
+    // Warm vivid colours — yellow & orange accents for SVG illustrations
+    brightFlame: '#FF9100', // Amber orange — warm cosmic accent
+    brightGold: '#FFEA00', // Electric yellow — star highlight
+    // Vivid brights for light backgrounds — punchy, saturated, OpenAI-blog vibrancy
+    brightLightGlow: '#7C4DFF', // Electric violet
+    brightLightPop: '#448AFF', // Neon blue
+    brightLightSpark: '#D500F9', // Vivid purple
+    brightLightBlaze: '#FF5252', // Neon red
+    brightLightSurge: '#00B0FF', // Vivid sky blue
+    brightLightFlame: '#FF9100', // Vivid amber orange
+    brightLightGold: '#FFC400', // Vivid gold
 };

package/lib/theme/index.d.ts

@@ -10,3 +10,5 @@ export * from './themes-brand/spatialBrandTheme';
 export * from './themeRegistry';
 export * from './Palette';
 export * from './useSystemColorMode';
+export * from './useThemeStore';
+export * from './ThemedProvider';

package/lib/theme/index.js

@@ -14,3 +14,5 @@ export * from './themes-brand/spatialBrandTheme';
 export * from './themeRegistry';
 export * from './Palette';
 export * from './useSystemColorMode';
+export * from './useThemeStore';
+export * from './ThemedProvider';

package/lib/theme/themeRegistry.d.ts

@@ -2,6 +2,37 @@ import { type CSSProperties } from 'react';
 import { type ColorMode } from './DatalayerBrandThemeProvider';
 /** Available theme variants. */
 export type ThemeVariant = 'datalayer' | 'spatial' | 'lovely' | 'matrix';
+/** A pair of colours for a two-stop gradient. */
+export interface GradientPair {
+    /** Start colour (brighter / brand). */
+    from: string;
+    /** End colour (deeper / hover). */
+    to: string;
+}
+/**
+ * Vivid colour triplet for SVG illustrations.
+ *
+ * Inspired by OpenAI's blog — ultra-saturated, luminous hues designed
+ * to glow and pop against both light and dark backgrounds.
+ */
+export interface BrightPalette {
+    /** Primary vivid accent — the "star" glow colour. */
+    glow: string;
+    /** Optimal text colour for content rendered on a `glow` background. */
+    onGlow: string;
+    /** Contrasting vivid colour — analogous/complement. */
+    pop: string;
+    /** Third vivid colour — sparkle / small highlights. */
+    spark: string;
+    /** Vivid red / warm accent — energy, urgency, warmth. */
+    blaze: string;
+    /** Vivid blue / cool accent — depth, trust, electricity. */
+    surge: string;
+    /** Vivid orange — warm energy, fire, dynamism. */
+    flame: string;
+    /** Vivid yellow / gold — highlights, attention, optimism. */
+    gold: string;
+}
 /**
  * Complete configuration for a theme, including the Primer theme object,
  * display metadata, and CSS custom property overrides per color mode.
@@ -22,9 +53,53 @@ export interface ThemeConfig {
         light: CSSProperties;
         dark: CSSProperties;
     };
+    /**
+     * Per-mode gradient pair for card backgrounds, banners, and other
+     * decorative surfaces that need a themed two-colour gradient.
+     */
+    cardGradient: {
+        light: GradientPair;
+        dark: GradientPair;
+    };
+    /**
+     * Vivid colour triplet for SVG illustrations — ultra-saturated,
+     * luminous hues that glow and pop on dark backgrounds (OpenAI-blog style).
+     */
+    brightPalette: BrightPalette;
+    /**
+     * Deeper / richer bright palette for light backgrounds.
+     * Same hue families as `brightPalette` but with higher contrast on
+     * light surfaces so illustrations don't appear faded.
+     */
+    brightPaletteLight: BrightPalette;
 }
 export declare const themeConfigs: Record<ThemeVariant, ThemeConfig>;
 /** All available theme variants in display order. */
 export declare const themeVariants: ThemeVariant[];
 /** Look up a theme config by variant name. */
 export declare function getThemeConfig(variant: ThemeVariant): ThemeConfig;
+/**
+ * Resolve the card gradient for a given theme variant and colour mode.
+ * Falls back to `datalayer` / `light` when values are missing.
+ */
+export declare function getCardGradient(variant?: ThemeVariant, colorMode?: 'light' | 'dark' | 'auto'): GradientPair;
+/**
+ * Get the bright (vivid / OpenAI-blog-style) palette for a given theme variant.
+ *
+ * When `colorMode` is `'light'` the vivid / saturated light-background palette
+ * is returned — these are punchy, high-saturation colours designed to keep SVG
+ * illustrations vibrant and energetic on near-white surfaces.
+ * When `colorMode` is `'auto'`, the OS preference is queried via
+ * `prefers-color-scheme` so palettes always match the effective background.
+ * Defaults to the dark-optimised neon palette for backward compatibility.
+ */
+export declare function getBrightPalette(variant?: ThemeVariant, colorMode?: 'light' | 'dark' | 'auto'): BrightPalette;
+/**
+ * Get a 5-colour avatar palette for the given theme variant and colour mode.
+ *
+ * Designed for use with the `boring-avatars` library's `colors` prop.
+ * When `colorMode` is `'auto'`, the OS preference is queried via
+ * `prefers-color-scheme` so avatars always match the effective background.
+ * Falls back to `datalayer` / `light` when values are missing.
+ */
+export declare function getAvatarColors(variant?: ThemeVariant, colorMode?: 'light' | 'dark' | 'auto'): string[];

package/lib/theme/themeRegistry.js

@@ -19,6 +19,30 @@ export const themeConfigs = {
         defaultColorMode: 'auto',
         primerTheme: datalayerTheme,
         themeStyles: datalayerThemeStyles,
+        cardGradient: {
+            light: { from: datalayerColors.greenBrand, to: datalayerColors.greenText }, // #16A085 → #117A65
+            dark: { from: datalayerColors.greenAccent, to: datalayerColors.greenBrand }, // #1ABC9C → #16A085
+        },
+        brightPalette: {
+            glow: datalayerColors.brightGlow, // #00D68F — vivid emerald
+            onGlow: '#1b1f24', // dark text on bright green
+            pop: datalayerColors.brightPop, // #00E5FF — electric cyan
+            spark: datalayerColors.brightSpark, // #76FF03 — lime neon
+            blaze: datalayerColors.brightBlaze, // #FF1744 — vivid red
+            surge: datalayerColors.brightSurge, // #2979FF — electric blue
+            flame: datalayerColors.brightFlame, // #FF6D00 — vivid orange
+            gold: datalayerColors.brightGold, // #FFD600 — vivid yellow
+        },
+        brightPaletteLight: {
+            glow: datalayerColors.brightLightGlow, // #00BFA5 — vivid aqua-green
+            onGlow: '#1b1f24', // dark text on aqua-green
+            pop: datalayerColors.brightLightPop, // #00B0FF — vivid sky blue
+            spark: datalayerColors.brightLightSpark, // #64DD17 — vivid chartreuse
+            blaze: datalayerColors.brightLightBlaze, // #FF1744 — vivid red
+            surge: datalayerColors.brightLightSurge, // #2979FF — electric blue
+            flame: datalayerColors.brightLightFlame, // #FF6D00 — vivid orange
+            gold: datalayerColors.brightLightGold, // #FFAB00 — vivid amber
+        },
     },
     spatial: {
         label: 'Spatial',
@@ -27,6 +51,30 @@ export const themeConfigs = {
         defaultColorMode: 'auto',
         primerTheme: spatialTheme,
         themeStyles: spatialThemeStyles,
+        cardGradient: {
+            light: { from: spatialColors.indigoBrand, to: spatialColors.indigoText }, // #4F46E5 → #3730A3
+            dark: { from: spatialColors.indigoAccent, to: spatialColors.indigoBrand }, // #6366F1 → #4F46E5
+        },
+        brightPalette: {
+            glow: spatialColors.brightGlow, // #7C4DFF — electric violet
+            onGlow: '#ffffff', // white text on violet
+            pop: spatialColors.brightPop, // #448AFF — neon blue
+            spark: spatialColors.brightSpark, // #E040FB — vivid magenta
+            blaze: spatialColors.brightBlaze, // #FF5252 — neon red
+            surge: spatialColors.brightSurge, // #00B0FF — deep sky blue
+            flame: spatialColors.brightFlame, // #FF9100 — amber orange
+            gold: spatialColors.brightGold, // #FFEA00 — electric yellow
+        },
+        brightPaletteLight: {
+            glow: spatialColors.brightLightGlow, // #7C4DFF — electric violet
+            onGlow: '#ffffff', // white text on violet
+            pop: spatialColors.brightLightPop, // #448AFF — neon blue
+            spark: spatialColors.brightLightSpark, // #D500F9 — vivid purple
+            blaze: spatialColors.brightLightBlaze, // #FF5252 — neon red
+            surge: spatialColors.brightLightSurge, // #00B0FF — vivid sky blue
+            flame: spatialColors.brightLightFlame, // #FF9100 — vivid amber orange
+            gold: spatialColors.brightLightGold, // #FFC400 — vivid gold
+        },
     },
     lovely: {
         label: 'Lovely',
@@ -35,6 +83,30 @@ export const themeConfigs = {
         defaultColorMode: 'auto',
         primerTheme: lovelyTheme,
         themeStyles: lovelyThemeStyles,
+        cardGradient: {
+            light: { from: lovelyColors.roseBrand, to: lovelyColors.roseText }, // #DB2777 → #9D174D
+            dark: { from: lovelyColors.roseAccent, to: lovelyColors.roseBrand }, // #EC4899 → #DB2777
+        },
+        brightPalette: {
+            glow: lovelyColors.brightGlow, // #FF4081 — hot pink
+            onGlow: '#ffffff', // white text on hot pink
+            pop: lovelyColors.brightPop, // #FF6E40 — vivid coral
+            spark: lovelyColors.brightSpark, // #EA80FC — electric fuchsia
+            blaze: lovelyColors.brightBlaze, // #FF1744 — vivid crimson
+            surge: lovelyColors.brightSurge, // #536DFE — indigo blue
+            flame: lovelyColors.brightFlame, // #FF6E40 — coral orange
+            gold: lovelyColors.brightGold, // #FFD740 — amber gold
+        },
+        brightPaletteLight: {
+            glow: lovelyColors.brightLightGlow, // #FF4081 — hot pink
+            onGlow: '#ffffff', // white text on hot pink
+            pop: lovelyColors.brightLightPop, // #FF6E40 — vivid coral
+            spark: lovelyColors.brightLightSpark, // #EA80FC — electric fuchsia
+            blaze: lovelyColors.brightLightBlaze, // #FF1744 — vivid crimson
+            surge: lovelyColors.brightLightSurge, // #536DFE — vivid indigo
+            flame: lovelyColors.brightLightFlame, // #FF6E40 — vivid coral orange
+            gold: lovelyColors.brightLightGold, // #FFD740 — vivid amber gold
+        },
     },
     matrix: {
         label: 'Matrix',
@@ -43,6 +115,30 @@ export const themeConfigs = {
         defaultColorMode: 'dark',
         primerTheme: matrixTheme,
         themeStyles: matrixThemeStyles,
+        cardGradient: {
+            light: { from: matrixColors.greenBrand, to: matrixColors.greenText }, // #16A085 → #117A65
+            dark: { from: matrixColors.greenGlow, to: matrixColors.greenHover }, // #39FF14 → #0E6655
+        },
+        brightPalette: {
+            glow: matrixColors.brightGlow, // #39FF14 — neon green
+            onGlow: '#1b1f24', // dark text on neon green
+            pop: matrixColors.brightPop, // #00FF88 — phosphor cyan
+            spark: matrixColors.brightSpark, // #CCFF00 — acid lime
+            blaze: matrixColors.brightBlaze, // #FF0040 — matrix red pill
+            surge: matrixColors.brightSurge, // #00E5FF — electric blue
+            flame: matrixColors.brightFlame, // #FF6D00 — electric orange
+            gold: matrixColors.brightGold, // #FFEA00 — glitch yellow
+        },
+        brightPaletteLight: {
+            glow: matrixColors.brightLightGlow, // #00E676 — vivid green
+            onGlow: '#1b1f24', // dark text on vivid green
+            pop: matrixColors.brightLightPop, // #1DE9B6 — vivid teal-mint
+            spark: matrixColors.brightLightSpark, // #AEEA00 — vivid lime
+            blaze: matrixColors.brightLightBlaze, // #FF1744 — vivid red
+            surge: matrixColors.brightLightSurge, // #00B0FF — vivid sky blue
+            flame: matrixColors.brightLightFlame, // #FF6D00 — vivid orange
+            gold: matrixColors.brightLightGold, // #FFAB00 — vivid amber
+        },
     },
 };
 /** All available theme variants in display order. */
@@ -51,3 +147,142 @@ export const themeVariants = ['datalayer', 'spatial', 'lovely', 'matrix'];
 export function getThemeConfig(variant) {
     return themeConfigs[variant];
 }
+/**
+ * Resolve the card gradient for a given theme variant and colour mode.
+ * Falls back to `datalayer` / `light` when values are missing.
+ */
+export function getCardGradient(variant = 'datalayer', colorMode = 'light') {
+    const mode = colorMode === 'auto' ? 'light' : colorMode;
+    return themeConfigs[variant]?.cardGradient?.[mode] ?? themeConfigs.datalayer.cardGradient.light;
+}
+/**
+ * Get the bright (vivid / OpenAI-blog-style) palette for a given theme variant.
+ *
+ * When `colorMode` is `'light'` the vivid / saturated light-background palette
+ * is returned — these are punchy, high-saturation colours designed to keep SVG
+ * illustrations vibrant and energetic on near-white surfaces.
+ * When `colorMode` is `'auto'`, the OS preference is queried via
+ * `prefers-color-scheme` so palettes always match the effective background.
+ * Defaults to the dark-optimised neon palette for backward compatibility.
+ */
+export function getBrightPalette(variant = 'datalayer', colorMode) {
+    const cfg = themeConfigs[variant] ?? themeConfigs.datalayer;
+    let resolvedMode;
+    if (colorMode === 'auto') {
+        resolvedMode =
+            typeof window !== 'undefined' &&
+                window.matchMedia('(prefers-color-scheme: dark)').matches
+                ? 'dark'
+                : 'light';
+    }
+    else if (colorMode === 'light') {
+        resolvedMode = 'light';
+    }
+    else {
+        resolvedMode = 'dark';
+    }
+    if (resolvedMode === 'light') {
+        return cfg.brightPaletteLight ?? cfg.brightPalette;
+    }
+    return cfg.brightPalette;
+}
+/**
+ * Avatar colour palettes per theme × colour mode.
+ *
+ * Each palette is a 5-colour array tuned for the `boring-avatars` library.
+ * The colours are picked from each theme's brand + bright palette so the
+ * avatar always feels native to the current theme.
+ *
+ * - **Light mode** uses the deeper / accessible colour variants so the
+ *   avatar is legible on light backgrounds.
+ * - **Dark mode** uses the brighter / glowing variants so the avatar
+ *   pops against dark surfaces.
+ */
+const avatarColorPalettes = {
+    datalayer: {
+        light: [
+            datalayerColors.greenText, // #117A65 — deep green
+            datalayerColors.greenBrand, // #16A085 — brand green
+            datalayerColors.brightLightPop, // #00B0FF — sky blue
+            datalayerColors.brightLightGold, // #FFAB00 — amber
+            datalayerColors.gray, // #59595C — neutral
+        ],
+        dark: [
+            datalayerColors.greenAccent, // #1ABC9C — bright teal
+            datalayerColors.greenBright, // #2ECC71 — bright green
+            datalayerColors.brightPop, // #00E5FF — electric cyan
+            datalayerColors.brightGold, // #FFD600 — vivid yellow
+            datalayerColors.brightFlame, // #FF6D00 — vivid orange
+        ],
+    },
+    spatial: {
+        light: [
+            spatialColors.indigoText, // #3730A3 — deep indigo
+            spatialColors.indigoBrand, // #4F46E5 — brand indigo
+            spatialColors.brightLightSpark, // #D500F9 — vivid purple
+            spatialColors.brightLightGold, // #FFC400 — vivid gold
+            spatialColors.gray, // #8892B0 — nebula gray
+        ],
+        dark: [
+            spatialColors.indigoAccent, // #6366F1 — bright indigo
+            spatialColors.indigoBright, // #818CF8 — light indigo
+            spatialColors.brightPop, // #448AFF — neon blue
+            spatialColors.brightSpark, // #E040FB — vivid magenta
+            spatialColors.brightGold, // #FFEA00 — electric yellow
+        ],
+    },
+    lovely: {
+        light: [
+            lovelyColors.roseText, // #9D174D — deep rose
+            lovelyColors.roseBrand, // #DB2777 — brand pink
+            lovelyColors.brightLightSurge, // #536DFE — vivid indigo
+            lovelyColors.brightLightGold, // #FFD740 — amber gold
+            lovelyColors.gray, // #9D7A8F — mauve gray
+        ],
+        dark: [
+            lovelyColors.roseAccent, // #EC4899 — bright pink
+            lovelyColors.roseBright, // #F472B6 — light pink
+            lovelyColors.brightPop, // #FF6E40 — vivid coral
+            lovelyColors.brightSpark, // #EA80FC — electric fuchsia
+            lovelyColors.brightGold, // #FFD740 — amber gold
+        ],
+    },
+    matrix: {
+        light: [
+            matrixColors.greenText, // #117A65 — deep green
+            matrixColors.greenBrand, // #16A085 — brand green
+            matrixColors.brightLightPop, // #1DE9B6 — vivid teal
+            matrixColors.brightLightGold, // #FFAB00 — vivid amber
+            matrixColors.gray, // #4A7856 — dim green-gray
+        ],
+        dark: [
+            matrixColors.greenPhosphor, // #00FF41 — Matrix green
+            matrixColors.greenGlow, // #39FF14 — neon phosphor
+            matrixColors.brightPop, // #00FF88 — phosphor cyan
+            matrixColors.brightSpark, // #CCFF00 — acid lime
+            matrixColors.brightSurge, // #00E5FF — electric blue
+        ],
+    },
+};
+/**
+ * Get a 5-colour avatar palette for the given theme variant and colour mode.
+ *
+ * Designed for use with the `boring-avatars` library's `colors` prop.
+ * When `colorMode` is `'auto'`, the OS preference is queried via
+ * `prefers-color-scheme` so avatars always match the effective background.
+ * Falls back to `datalayer` / `light` when values are missing.
+ */
+export function getAvatarColors(variant = 'datalayer', colorMode = 'light') {
+    let mode;
+    if (colorMode === 'auto') {
+        mode =
+            typeof window !== 'undefined' &&
+                window.matchMedia('(prefers-color-scheme: dark)').matches
+                ? 'dark'
+                : 'light';
+    }
+    else {
+        mode = colorMode;
+    }
+    return avatarColorPalettes[variant]?.[mode] ?? avatarColorPalettes.datalayer.light;
+}

package/lib/theme/themes/createThemeCSSVars.d.ts

@@ -118,6 +118,10 @@ export interface ThemeColorDefs {
  * | Outline button   | `--button-outline-fgColor-rest`        |
  * | Danger button    | `--button-danger-bgColor-hover`        |
  * | Button counters  | `--buttonCounter-primary-bgColor-rest` |
+ * | Control track    | `--controlTrack-bgColor-rest`          |
+ * | Control checked  | `--control-checked-bgColor-rest`       |
+ * | Control knob     | `--controlKnob-bgColor-rest`           |
+ * | List hover       | `--control-transparent-bgColor-hover`  |
  * | Legacy aliases   | `--color-btn-primary-bg`               |
  * | Brand (custom)   | `--brand-color-canvas-default`         |
  */
@@ -131,5 +135,14 @@ export interface ThemeStyles {
  * Build a complete `ThemeStyles` object from light / dark
  * `ThemeColorDefs`.  The result is ready to pass straight to
  * `<DatalayerThemeProvider themeStyles={…}>`.
+ *
+ * @param options.fontFamily  When supplied, the Primer font-stack
+ *   CSS custom properties (`--fontStack-sansSerif`,
+ *   `--fontStack-sansSerifDisplay`) are overridden so that every
+ *   Primer component that uses the CSS `font` shorthand (e.g.
+ *   `Blankslate`) picks up the themed font instead of the
+ *   hard-coded system-font fallback.
  */
-export declare function buildThemeStyles(light: ThemeColorDefs, dark: ThemeColorDefs): ThemeStyles;
+export declare function buildThemeStyles(light: ThemeColorDefs, dark: ThemeColorDefs, options?: {
+    fontFamily?: string;
+}): ThemeStyles;