@automattic/charts 3.1.0 → 3.2.0

package/src/providers/chart-context/private/series-palette.ts

@@ -0,0 +1,45 @@
+/**
+ * The series palette's slot manifest.
+ *
+ * Which slots exist is a fact about the catalog `chart-scope.scss` emits, not a theme value, so it
+ * is declared here rather than in `themes.ts`, which now derives `defaultTheme.colors` from it.
+ *
+ * That is as far as the separation goes, and the limit is worth knowing before the field is
+ * deleted. `GlobalChartsProvider` still resolves `providerTheme.colors`, not this manifest,
+ * because `withCatalogPointers` parks the consumer's own color in each pointer's terminal position
+ * and that literal is the palette's only carrier where `getComputedStyle` resolves nothing — SSR
+ * and jsdom. Swapping the provider onto this manifest passes in a browser and collapses every
+ * consumer palette to the catalog seed under jsdom; 24 tests say so. Removing `colors` therefore
+ * needs a different home for that literal first, not just a change of source here.
+ */
+
+/** How many series-palette slots the catalog emits. `theme.colors` entries past this are ignored. */
+export const SERIES_SLOT_COUNT = 5;
+
+/**
+ * The catalog role holding one series-palette slot.
+ *
+ * @param slot - The one-based slot number.
+ * @return The role name.
+ */
+export const seriesRole = ( slot: number ): string => `--a8c-charts-color-series-${ slot }`;
+
+/*
+ * Only slot 1 carries a terminal literal, and it is reached only where `getComputedStyle` resolves
+ * nothing — SSR and jsdom. The rest resolve to nothing until a consumer sets them, and the provider
+ * drops what resolves to nothing, so the palette compacts rather than repeating one color.
+ *
+ * The literal matches slot 1's own last-resort fallback in `chart-scope.scss`. It is deliberately
+ * the bare hex rather than that slot's full `var()` chain: this string is resolved against the DOM,
+ * where the chain has already been walked, and is only read at all when no DOM answered.
+ */
+const SERIES_SLOT_1_FALLBACK = '#3858e9';
+
+/** The catalog pointer for every slot, in slot order. */
+export const SERIES_PALETTE_POINTERS: readonly string[] = Array.from(
+	{ length: SERIES_SLOT_COUNT },
+	( _, index ) =>
+		index === 0
+			? `var(${ seriesRole( 1 ) }, ${ SERIES_SLOT_1_FALLBACK })`
+			: `var(${ seriesRole( index + 1 ) })`
+);

package/src/providers/chart-context/private/theme-override-vars.ts

@@ -1,6 +1,15 @@
+import { SERIES_SLOT_COUNT, seriesRole } from './series-palette';
 import type { ChartTheme } from '../../../types';
 
+/*
+ * `process.env.NODE_ENV` is replaced by the bundler at build time. Declare a
+ * minimal `process` locally so this file type-checks as source under `jetpack:src`.
+ */
+declare const process: { env: Record< string, string | undefined > };
+
 // The consumer theme fields that correspond to an emitted catalog role, and the role each one overrides. Each role must be read by exactly the elements its field controlled before the role existed: `svgLabelSmall.fill` maps to the narrow `--a8c-charts-color-label-axis` rather than `--a8c-charts-color-label`, because the broad role is also read by legend labels, heatmap cell values, funnel labels and the line-chart tooltip, which that field never moved.
+//
+// `theme.colors` is the one field mapped by position rather than by name: entry N publishes slot N+1, which is what makes it sugar over the five slots rather than a second palette with its own precedence.
 const ROLE_FOR_FIELD: Array< [ string, ( theme: Partial< ChartTheme > ) => string | undefined ] > =
 	[
 		[ '--a8c-charts-color-background', theme => theme.backgroundColor ],
@@ -8,8 +17,37 @@ const ROLE_FOR_FIELD: Array< [ string, ( theme: Partial< ChartTheme > ) => strin
 		[ '--a8c-charts-color-axis', theme => theme.xAxisLineStyles?.stroke ],
 		[ '--a8c-charts-color-tick', theme => theme.xTickLineStyles?.stroke ],
 		[ '--a8c-charts-color-label-axis', theme => theme.svgLabelSmall?.fill ],
+		[ '--a8c-charts-color-label-background', theme => theme.labelBackgroundColor ],
+		[ '--a8c-charts-color-label-on-fill', theme => theme.labelTextColor ],
+		...Array.from(
+			{ length: SERIES_SLOT_COUNT },
+			( _, index ): [ string, ( theme: Partial< ChartTheme > ) => string | undefined ] => [
+				seriesRole( index + 1 ),
+				theme => theme.colors?.[ index ],
+			]
+		),
 	];
 
+let warnedAboutExtraColors = false;
+
+/**
+ * Warns once when a consumer passes more colors than there are slots to publish them into.
+ *
+ * @param count - How many entries `theme.colors` holds.
+ */
+function warnOnceAboutExtraColors( count: number ): void {
+	if ( warnedAboutExtraColors || process.env.NODE_ENV === 'production' ) {
+		return;
+	}
+
+	warnedAboutExtraColors = true;
+	// eslint-disable-next-line no-console
+	console.warn(
+		`[Charts] theme.colors holds ${ count } colors and the palette has ${ SERIES_SLOT_COUNT } slots, so entries past the ${ SERIES_SLOT_COUNT }th are ignored. ` +
+			'Set a per-series color with `options.stroke` instead.'
+	);
+}
+
 /**
  * The variable a `theme` prop override is published as, one layer outside the role itself.
  *
@@ -26,7 +64,7 @@ export const THEME_LAYERED_ROLES: readonly string[] = ROLE_FOR_FIELD.map( ( [ ro
 /**
  * Whether a value reads the role it is being published for, which would make the catalog entry depend on itself.
  *
- * The dependency runs `<role>: var(<role>-theme, …)`, so a value naming `<role>` closes a cycle through the catalog entry. CSS marks every custom property in a cycle invalid at computed-value time — the role's own fallback is *not* used, so the token resolves to nothing and every chart loses that colour. Verified in Chrome: `--role-theme: var(--role, blue); --role: var(--role-theme, green)` leaves `--role` empty, not `green`.
+ * The dependency runs `<role>: var(<role>-theme, …)`, so a value naming `<role>` closes a cycle through the catalog entry. CSS marks every custom property in a cycle invalid at computed-value time — the role's own fallback is *not* used, so the token resolves to nothing and every chart loses that color. Verified in Chrome: `--role-theme: var(--role, blue); --role: var(--role-theme, green)` leaves `--role` empty, not `green`.
  *
  * Three things this has to get right, none of which a plain substring test gets:
  *
@@ -54,10 +92,12 @@ export type ThemeOverrides = {
 };
 
 /**
- * Maps a sparse consumer theme onto the theme-layer variables its overridden catalog roles read, so CSS-painted and JS-resolved colours read one source.
+ * Maps a sparse consumer theme onto the theme-layer variables its overridden catalog roles read, so CSS-painted and JS-resolved colors read one source.
  *
  * A value that reads the role it would override is left unpublished — that is the default theme's own pointer surviving `mergeThemes`, and publishing it would invalidate the role. The role is still reported in `roles`: `withCatalogPointers` restores its theme field to the catalog pointer either way, so CSS and visx agree on the catalog default rather than visx painting a literal CSS never sees.
  *
+ * `theme.colors` publishes through the same mechanism, one slot per entry, so a CSS declaration of `--a8c-charts-color-series-N` still beats it and a short array leaves the later slots unset rather than blank.
+ *
  * @param theme - The consumer's `theme` prop, before merging with the default theme.
  * @return The wrapper's custom properties, and the roles the consumer overrode.
  */
@@ -66,6 +106,10 @@ export const themeOverrideVars = ( theme?: Partial< ChartTheme > ): ThemeOverrid
 		return { vars: {}, roles: [] };
 	}
 
+	if ( Array.isArray( theme.colors ) && theme.colors.length > SERIES_SLOT_COUNT ) {
+		warnOnceAboutExtraColors( theme.colors.length );
+	}
+
 	const vars: Record< string, string > = {};
 	const roles: string[] = [];
 

package/src/providers/chart-context/private/with-catalog-pointers.ts

@@ -1,11 +1,50 @@
 import { defaultTheme } from '../themes';
+import { SERIES_PALETTE_POINTERS, SERIES_SLOT_COUNT, seriesRole } from './series-palette';
 import type { CompleteChartTheme } from '../../../types';
 
-// Restores each overridden role's mapped theme field to the catalog pointer `defaultTheme` already carries for it, so the value comes from `themes.ts` itself rather than a second, hand-copied literal.
+/**
+ * The pointer one palette slot is restored to.
+ *
+ * Unlike the other roles, this keeps the consumer's own color as the pointer's terminal literal instead of the catalog's. The literal is only ever reached where `getComputedStyle` resolves nothing — SSR and jsdom — and there the palette is the one field where falling back to the catalog default would be visible: every series would paint the same seeded blue. In a browser the slot resolves first, so a CSS declaration of it still outranks the consumer's `theme.colors`.
+ *
+ * @param index - The slot's zero-based index in `colors`.
+ * @param value - The merged theme's entry for it.
+ * @return The catalog pointer for that slot.
+ */
+const seriesPointer = ( index: number, value: string | undefined ): string => {
+	const role = seriesRole( index + 1 );
+
+	// Idempotent: `withCatalogPointers` runs this once per overridden slot, so from the second call on the array already holds pointers.
+	if ( typeof value === 'string' && value.startsWith( `var(${ role }` ) ) {
+		return value;
+	}
+
+	// A slot the consumer left empty keeps the catalog's own pointer, so a CSS declaration of it still reaches the palette.
+	if ( typeof value !== 'string' || value === '' ) {
+		return SERIES_PALETTE_POINTERS[ index ];
+	}
+
+	return `var(${ role }, ${ value })`;
+};
+
+// Restores each overridden role's mapped theme field to the catalog pointer already written for it — `defaultTheme` for the ordinary roles, `series-palette.ts` for the palette slots — so the value comes from the one place that declares it rather than a second, hand-copied literal.
+//
+// Every series slot restores the whole `colors` array, not just its own entry. `mergeThemes` replaces arrays outright, so a consumer passing two colors would otherwise leave a two-entry palette and put slots 3 to 5 out of reach of a CSS declaration that sets them.
 const CATALOG_RESTORE_FOR_ROLE: Record<
 	string,
 	( theme: CompleteChartTheme ) => Partial< CompleteChartTheme >
 > = {
+	// Each of the five entries rebuilds the whole array, so a consumer overriding every slot runs this five times. That is deliberate rather than merely tolerated: `seriesPointer` is idempotent, so every pass after the first is a no-op, and five allocations of a five-element array is not worth a special case in a map that is otherwise one entry per role.
+	...Object.fromEntries(
+		Array.from( { length: SERIES_SLOT_COUNT }, ( _, index ) => [
+			seriesRole( index + 1 ),
+			( theme: CompleteChartTheme ) => ( {
+				colors: SERIES_PALETTE_POINTERS.map( ( _pointer, slot ) =>
+					seriesPointer( slot, theme.colors?.[ slot ] )
+				),
+			} ),
+		] )
+	),
 	'--a8c-charts-color-background': () => ( { backgroundColor: defaultTheme.backgroundColor } ),
 	'--a8c-charts-color-grid': theme => ( {
 		gridStyles: { ...theme.gridStyles, stroke: defaultTheme.gridStyles.stroke },
@@ -19,6 +58,10 @@ const CATALOG_RESTORE_FOR_ROLE: Record<
 	'--a8c-charts-color-label-axis': theme => ( {
 		svgLabelSmall: { ...theme.svgLabelSmall, fill: defaultTheme.svgLabelSmall.fill },
 	} ),
+	'--a8c-charts-color-label-background': () => ( {
+		labelBackgroundColor: defaultTheme.labelBackgroundColor,
+	} ),
+	'--a8c-charts-color-label-on-fill': () => ( { labelTextColor: defaultTheme.labelTextColor } ),
 };
 
 /**
@@ -26,7 +69,7 @@ const CATALOG_RESTORE_FOR_ROLE: Record<
  *
  * This covers roles `themeOverrideVars` deliberately left unpublished as well as the ones it published. A value that reads its own role is not publishable, but leaving visx the consumer's literal is what the whole mechanism exists to prevent: `theme={ { gridStyles: { stroke: 'var(--brand, var(--a8c-charts-color-grid, red))' } } }` would have CSS paint the catalog default while visx painted `--brand`.
  *
- * Every field outside the five mapped roles is left exactly as `merged` provided it: those aren't published as theme-layer vars, so rewriting them would erase a consumer's override with no replacement carrier.
+ * Every field outside the mapped roles is left exactly as `merged` provided it: those aren't published as theme-layer vars, so rewriting them would erase a consumer's override with no replacement carrier.
  *
  * @param merged          - The consumer theme merged onto `defaultTheme` (`mergeThemes` output).
  * @param overriddenRoles - The catalog roles the consumer overrode, from `themeOverrideVars`.

package/src/providers/chart-context/test/sparse-theme.test.ts

@@ -20,16 +20,30 @@ describe( 'defaultTheme', () => {
 		expect( strings.filter( value => value.includes( '--wpds-' ) ) ).toEqual( [] );
 	} );
 
-	it( 'points every themed colour at an --a8c-charts-* catalog role', () => {
+	it( 'points every themed color at an --a8c-charts-* catalog role', () => {
 		const varStrings = strings.filter( value => value.startsWith( 'var(' ) );
 
 		expect( varStrings.length ).toBeGreaterThan( 0 );
 		expect( varStrings.every( value => value.startsWith( 'var(--a8c-charts-' ) ) ).toBe( true );
 	} );
 
+	// The palette slots past the first are the exception, below: a terminal literal there would be a color nobody chose.
 	it( 'gives every catalog pointer a terminal literal for the SSR and jsdom paths', () => {
-		const varStrings = strings.filter( value => value.startsWith( 'var(--a8c-charts-' ) );
+		const varStrings = strings
+			.filter( value => value.startsWith( 'var(--a8c-charts-' ) )
+			.filter( value => ! /^var\( *--a8c-charts-color-series-[2-9] *\)$/.test( value ) );
 
 		expect( varStrings.every( value => value.includes( ',' ) ) ).toBe( true );
 	} );
+
+	// Only slot 1 seeds a palette. The rest resolve to nothing until a consumer sets them, and the provider drops what resolves to nothing, so the palette compacts instead of repeating one color.
+	it( 'leaves the palette slots past the first with no default of their own', () => {
+		expect( defaultTheme.colors ).toEqual( [
+			'var(--a8c-charts-color-series-1, #3858e9)',
+			'var(--a8c-charts-color-series-2)',
+			'var(--a8c-charts-color-series-3)',
+			'var(--a8c-charts-color-series-4)',
+			'var(--a8c-charts-color-series-5)',
+		] );
+	} );
 } );

package/src/providers/chart-context/test/theme-override-vars.test.ts

@@ -29,6 +29,9 @@ describe( 'themeOverrideVars', () => {
 				xAxisLineStyles: { stroke: '#333' },
 				xTickLineStyles: { stroke: '#444' },
 				svgLabelSmall: { fill: '#555' },
+				labelBackgroundColor: '#556',
+				labelTextColor: '#557',
+				colors: [ '#661', '#662', '#663', '#664', '#665' ],
 			} )
 		).toEqual( {
 			vars: {
@@ -37,6 +40,13 @@ describe( 'themeOverrideVars', () => {
 				'--a8c-charts-color-axis-theme': '#333',
 				'--a8c-charts-color-tick-theme': '#444',
 				'--a8c-charts-color-label-axis-theme': '#555',
+				'--a8c-charts-color-label-background-theme': '#556',
+				'--a8c-charts-color-label-on-fill-theme': '#557',
+				'--a8c-charts-color-series-1-theme': '#661',
+				'--a8c-charts-color-series-2-theme': '#662',
+				'--a8c-charts-color-series-3-theme': '#663',
+				'--a8c-charts-color-series-4-theme': '#664',
+				'--a8c-charts-color-series-5-theme': '#665',
 			},
 			roles: [
 				'--a8c-charts-color-background',
@@ -44,6 +54,13 @@ describe( 'themeOverrideVars', () => {
 				'--a8c-charts-color-axis',
 				'--a8c-charts-color-tick',
 				'--a8c-charts-color-label-axis',
+				'--a8c-charts-color-label-background',
+				'--a8c-charts-color-label-on-fill',
+				'--a8c-charts-color-series-1',
+				'--a8c-charts-color-series-2',
+				'--a8c-charts-color-series-3',
+				'--a8c-charts-color-series-4',
+				'--a8c-charts-color-series-5',
 			],
 		} );
 	} );
@@ -55,6 +72,9 @@ describe( 'themeOverrideVars', () => {
 			xAxisLineStyles: { stroke: '#333' },
 			xTickLineStyles: { stroke: '#444' },
 			svgLabelSmall: { fill: '#555' },
+			labelBackgroundColor: '#556',
+			labelTextColor: '#557',
+			colors: [ '#661', '#662', '#663', '#664', '#665' ],
 		} );
 
 		expect( Object.keys( vars ) ).toEqual( THEME_LAYERED_ROLES.map( themeLayerVar ) );
@@ -68,6 +88,51 @@ describe( 'themeOverrideVars', () => {
 		} );
 	} );
 
+	// A short array is not padded: the later slots stay unset, so the palette compacts rather than repeating a color the consumer never chose.
+	it( 'publishes one palette slot per color and leaves the rest unset', () => {
+		expect( themeOverrideVars( { colors: [ 'red', 'blue' ] } ) ).toEqual( {
+			vars: {
+				'--a8c-charts-color-series-1-theme': 'red',
+				'--a8c-charts-color-series-2-theme': 'blue',
+			},
+			roles: [ '--a8c-charts-color-series-1', '--a8c-charts-color-series-2' ],
+		} );
+	} );
+
+	it( 'drops palette entries past the last slot', () => {
+		// Spied rather than asserted on: an over-long palette warns, and `@wordpress/jest-console` fails any test that leaves a console call unclaimed. The warning itself is covered below.
+		const warn = jest.spyOn( console, 'warn' ).mockImplementation( () => {} );
+		const { vars } = themeOverrideVars( {
+			colors: [ 'a', 'b', 'c', 'd', 'e', 'f', 'g' ],
+		} );
+
+		expect( vars[ '--a8c-charts-color-series-5-theme' ] ).toBe( 'e' );
+		expect( vars[ '--a8c-charts-color-series-6-theme' ] ).toBeUndefined();
+
+		warn.mockRestore();
+	} );
+
+	// Isolated so the warning's module-level latch starts unset — the assertion is that it warns once per module instance, not once per call.
+	it( 'warns once about the dropped entries, not once per render', () => {
+		jest.isolateModules( () => {
+			const warn = jest.spyOn( console, 'warn' ).mockImplementation( () => {} );
+			const {
+				themeOverrideVars: freshThemeOverrideVars,
+				// eslint-disable-next-line @typescript-eslint/no-require-imports -- isolateModules needs a synchronous require to get a module instance whose latch is unset.
+			} = require( '../private/theme-override-vars' ) as {
+				themeOverrideVars: typeof themeOverrideVars;
+			};
+
+			freshThemeOverrideVars( { colors: [ 'a', 'b', 'c', 'd', 'e', 'f' ] } );
+			freshThemeOverrideVars( { colors: [ 'a', 'b', 'c', 'd', 'e', 'f' ] } );
+
+			expect( warn ).toHaveBeenCalledTimes( 1 );
+			expect( warn ).toHaveBeenCalledWith( expect.stringContaining( 'holds 6 colors' ) );
+
+			warn.mockRestore();
+		} );
+	} );
+
 	it( 'ignores a value that is itself a pointer at the role it would override', () => {
 		expect(
 			themeOverrideVars( { gridStyles: { stroke: 'var(--a8c-charts-color-grid, #dbdbdb)' } } ).vars

package/src/providers/chart-context/test/use-global-charts-theme.test.tsx

@@ -27,7 +27,14 @@ describe( 'useGlobalChartsTheme', () => {
 
 			const { result } = renderHook( () => useGlobalChartsTheme(), { wrapper } );
 
-			expect( result.current.colors ).toEqual( [ '#FF0000', '#00FF00', '#0000FF' ] );
+			// `theme.colors` publishes the palette's theme layers, so the merged theme holds catalog pointers rather than the consumer's literals. Each keeps its consumer color as the pointer's terminal literal, for SSR and jsdom.
+			expect( result.current.colors ).toEqual( [
+				'var(--a8c-charts-color-series-1, #FF0000)',
+				'var(--a8c-charts-color-series-2, #00FF00)',
+				'var(--a8c-charts-color-series-3, #0000FF)',
+				'var(--a8c-charts-color-series-4)',
+				'var(--a8c-charts-color-series-5)',
+			] );
 			// Other properties should still come from default theme
 			expect( result.current.backgroundColor ).toBe( defaultTheme.backgroundColor );
 			expect( result.current.gridStyles ).toEqual( defaultTheme.gridStyles );

package/src/providers/chart-context/test/with-catalog-pointers.test.ts

@@ -11,6 +11,8 @@ describe( 'withCatalogPointers', () => {
 			xAxisLineStyles: { stroke: '#333' },
 			xTickLineStyles: { stroke: '#444' },
 			svgLabelSmall: { fill: '#555' },
+			labelBackgroundColor: '#556',
+			labelTextColor: '#557',
 		} as Partial< ChartTheme > );
 
 		const result = withCatalogPointers( merged, [
@@ -19,6 +21,8 @@ describe( 'withCatalogPointers', () => {
 			'--a8c-charts-color-axis',
 			'--a8c-charts-color-tick',
 			'--a8c-charts-color-label-axis',
+			'--a8c-charts-color-label-background',
+			'--a8c-charts-color-label-on-fill',
 		] );
 
 		expect( result.backgroundColor ).toBe( defaultTheme.backgroundColor );
@@ -26,6 +30,8 @@ describe( 'withCatalogPointers', () => {
 		expect( result.xAxisLineStyles.stroke ).toBe( defaultTheme.xAxisLineStyles.stroke );
 		expect( result.xTickLineStyles.stroke ).toBe( defaultTheme.xTickLineStyles.stroke );
 		expect( result.svgLabelSmall.fill ).toBe( defaultTheme.svgLabelSmall.fill );
+		expect( result.labelBackgroundColor ).toBe( defaultTheme.labelBackgroundColor );
+		expect( result.labelTextColor ).toBe( defaultTheme.labelTextColor );
 
 		expect( merged.backgroundColor ).toBe( '#111' );
 		expect( merged.gridStyles.stroke ).toBe( '#222' );
@@ -44,4 +50,55 @@ describe( 'withCatalogPointers', () => {
 		// Not a mapped role, so its literal survives even when other roles are being restored.
 		expect( result.leaderboardChart.deltaColors ).toEqual( [ 'red', 'grey', 'green' ] );
 	} );
+
+	// The palette is restored as a whole, so a consumer's short array cannot shorten it. `mergeThemes` replaces arrays outright, and a two-entry palette would leave slots 3 to 5 unreadable — a CSS declaration of one of them would have no entry to resolve through.
+	it( 'restores the full five-slot palette from a shorter consumer array', () => {
+		const merged = mergeThemes( defaultTheme, {
+			colors: [ '#111', '#222' ],
+		} as Partial< ChartTheme > );
+
+		const result = withCatalogPointers( merged, [
+			'--a8c-charts-color-series-1',
+			'--a8c-charts-color-series-2',
+		] );
+
+		expect( result.colors ).toEqual( [
+			'var(--a8c-charts-color-series-1, #111)',
+			'var(--a8c-charts-color-series-2, #222)',
+			'var(--a8c-charts-color-series-3)',
+			'var(--a8c-charts-color-series-4)',
+			'var(--a8c-charts-color-series-5)',
+		] );
+	} );
+
+	// Each slot's restore rewrites the whole array, so restoring five of them must not wrap the pointers five times over.
+	it( 'restores the palette idempotently across every overridden slot', () => {
+		const merged = mergeThemes( defaultTheme, {
+			colors: [ '#111', '#222', '#333', '#444', '#555' ],
+		} as Partial< ChartTheme > );
+
+		const result = withCatalogPointers( merged, [
+			'--a8c-charts-color-series-1',
+			'--a8c-charts-color-series-2',
+			'--a8c-charts-color-series-3',
+			'--a8c-charts-color-series-4',
+			'--a8c-charts-color-series-5',
+		] );
+
+		expect( result.colors ).toEqual( [
+			'var(--a8c-charts-color-series-1, #111)',
+			'var(--a8c-charts-color-series-2, #222)',
+			'var(--a8c-charts-color-series-3, #333)',
+			'var(--a8c-charts-color-series-4, #444)',
+			'var(--a8c-charts-color-series-5, #555)',
+		] );
+	} );
+
+	// The literal is only reached where getComputedStyle resolves nothing, and the palette is the one field where falling back to the catalog default would be visible: every series would paint the same seeded blue.
+	it( 'keeps the consumer color as each pointer’s terminal literal, for SSR and jsdom', () => {
+		const merged = mergeThemes( defaultTheme, { colors: [ 'red' ] } as Partial< ChartTheme > );
+		const result = withCatalogPointers( merged, [ '--a8c-charts-color-series-1' ] );
+
+		expect( result.colors[ 0 ] ).toBe( 'var(--a8c-charts-color-series-1, red)' );
+	} );
 } );

package/src/providers/chart-context/themes.ts

@@ -1,3 +1,4 @@
+import { SERIES_PALETTE_POINTERS } from './private/series-palette';
 import type { CompleteChartTheme } from '../../types';
 
 /**
@@ -5,10 +6,14 @@ import type { CompleteChartTheme } from '../../types';
  */
 const defaultTheme: CompleteChartTheme = {
 	backgroundColor: 'var(--a8c-charts-color-background, #fff)',
-	labelBackgroundColor: 'transparent', // label background color (transparent by default)
-	// White label text sits on top of arbitrary series colors, so it has no WPDS content-foreground equivalent. Every other colour here is a bare pointer at the catalog emitted by `chart-scope.scss`; the terminal literal is the last resort for the SSR and jsdom paths, where getComputedStyle resolves nothing.
+	labelBackgroundColor: 'var(--a8c-charts-color-label-background, transparent)',
+	// White label text sits on top of arbitrary series colors, so it has no WPDS content-foreground equivalent. Every other color here is a bare pointer at the catalog emitted by `chart-scope.scss`; the terminal literal is the last resort for the SSR and jsdom paths, where getComputedStyle resolves nothing.
 	labelTextColor: 'var(--a8c-charts-color-label-on-fill, #FFFFFF)',
-	colors: [ '#98C8DF', '#006DAB', '#A6DC80', '#1F9828', '#FF8C8F' ],
+	// Derived, not authored: the slot manifest lives in `private/series-palette.ts` because which
+	// slots exist describes the catalog, not the theme. The field itself is still load-bearing —
+	// see that file for why the provider reads the palette through the theme and what has to move
+	// before this can be deleted.
+	colors: [ ...SERIES_PALETTE_POINTERS ],
 	gridStyles: {
 		stroke: 'var(--a8c-charts-color-grid, #dbdbdb)',
 		strokeWidth: 1,

package/src/styles/chart-scope.scss

@@ -1,41 +1,69 @@
 // The single mapping point between the --a8c-charts-* catalog and WordPress
-// design-system tokens.
+// design-system tokens. Declares custom properties only — this stylesheet must
+// never change layout.
 
-// Declared on the GlobalChartsProvider wrapper — not at :root — because
+// Declared on the GlobalChartsProvider wrapper, not at :root, because
 // @wordpress/theme's ThemeProvider emits its generated --wpds-* ramp as inline
-// styles on its own wrapper div, not on the document root. Substituting at the
-// provider means a ThemeProvider above it is picked up; substituting at :root
-// would miss it entirely.
+// styles on its own wrapper div. Substituting at :root would miss it entirely.
 
-// :where() keeps the rule at zero specificity so any consumer rule
-// targeting the same element wins. Chart roots deliberately do NOT
-// re-declare these: an element's own declaration beats an inherited one,
-// so re-declaring lower down would shadow a consumer override set inside
-// the provider tree.
+// :where() keeps the rule at zero specificity so any consumer rule targeting
+// the same element wins. Chart roots deliberately do NOT re-declare these: an
+// element's own declaration beats an inherited one, so re-declaring lower down
+// would shadow a consumer override set inside the provider tree.
 
-// The five roles a `theme` prop field can override read a `*-theme` variable
-// first, which GlobalChartsProvider writes inline from that field. Publishing
-// the consumer's value one layer out, rather than as the role itself, is what
-// keeps the catalog default reachable: a value that is invalid at
-// computed-value time (a fallback-less `var()` naming a token nothing set,
-// which is how premium-analytics passes its grid stroke) invalidates only the
-// `*-theme` variable, and the role's own fallback still resolves the mapped
-// --wpds-* token. Written as the role directly, that same value made the role
-// guaranteed-invalid and took every bare `var(--a8c-charts-color-grid)` read
-// site with it — gridlines painted `unset` instead of the spec grey.
+// The roles a `theme` prop field can override read a `*-theme` variable first,
+// which GlobalChartsProvider writes inline from that field. Publishing the
+// consumer's value one layer out keeps the catalog default reachable: a value
+// that is invalid at computed-value time (a fallback-less `var()` naming a
+// token nothing set, which is how premium-analytics passes its grid stroke)
+// invalidates only the `*-theme` variable, leaving the role's own fallback to
+// resolve. Written as the role directly, it made the role guaranteed-invalid
+// and took every bare read site with it.
 // `src/styles/test/chart-scope.test.ts` pins which roles carry the layer.
-
-// Declares custom properties only. This stylesheet must never change layout.
 :where(.a8c-charts-scope) {
+	// The series palette. GlobalChartsProvider resolves these five slots at its
+	// wrapper and seeds ColorCache with whatever resolves; a slot that resolves
+	// to nothing is skipped, so setting only slots 1 and 3 gives a two-color
+	// palette, and charts generate accessible colors beyond the seeds. Only
+	// slot 1 carries a default.
+
+	// Slot 1 names --wp-admin-theme-color first, because that is the only leg
+	// that does not depend on someone else's runtime. The design system's brand
+	// token tracks the admin color scheme only where a WPDS root provider
+	// boots and emits its generated ramp inline; without one the token falls to
+	// the plain stylesheet rule, a static #3858e9 with no reference to the
+	// admin color. Leading with the admin color costs nothing:
+	// @wordpress/theme writes --wp-admin-theme-color from a provider's own
+	// accent as a legacy wp-admin override, so a provider accent still wins.
+
+	// DO NOT SIMPLIFY the chain below. The innermost
+	// var(--wp-admin-theme-color, #3858e9) is unreachable — the outer leg
+	// already tried that variable — and reads like a copy-paste mistake. It is
+	// the design system's own spec value for the WPDS token, which
+	// `src/styles/test/wpds-fallbacks.test.ts` compares against literally, so
+	// collapsing it to a bare hex fails that test. Reordering to put the WPDS
+	// token first passes every test and breaks only on a host with no root
+	// provider.
+
+	// That test scans this file as text, comments included, so do not write an
+	// example --wpds-* reference in a comment here — it is read as a real one.
+	--a8c-charts-color-series-1: var(--a8c-charts-color-series-1-theme, var(--wp-admin-theme-color, var(--wpds-color-foreground-interactive-brand, var(--wp-admin-theme-color, #3858e9))));
+	--a8c-charts-color-series-2: var(--a8c-charts-color-series-2-theme);
+	--a8c-charts-color-series-3: var(--a8c-charts-color-series-3-theme);
+	--a8c-charts-color-series-4: var(--a8c-charts-color-series-4-theme);
+	--a8c-charts-color-series-5: var(--a8c-charts-color-series-5-theme);
 	--a8c-charts-color-grid: var(--a8c-charts-color-grid-theme, var(--wpds-color-stroke-surface-neutral, #dbdbdb));
 	--a8c-charts-color-axis: var(--a8c-charts-color-axis-theme, var(--wpds-color-stroke-surface-neutral, #dbdbdb));
 	--a8c-charts-color-tick: var(--a8c-charts-color-tick-theme, var(--wpds-color-stroke-surface-neutral, #dbdbdb));
 	--a8c-charts-color-label: var(--wpds-color-foreground-content-neutral, #1e1e1e);
 	--a8c-charts-color-label-secondary: var(--wpds-color-foreground-content-neutral-weak, #707070);
 	--a8c-charts-color-label-inverse: var(--wpds-color-foreground-interactive-neutral-strong, #f0f0f0);
-	// White label text sits on arbitrary series colours, so it has no WPDS
+	// White label text sits on arbitrary series colors, so it has no WPDS
 	// content-foreground equivalent.
-	--a8c-charts-color-label-on-fill: #fff;
+	--a8c-charts-color-label-on-fill: var(--a8c-charts-color-label-on-fill-theme, #fff);
+	// The plate behind a pie-slice label. Transparent by default, so a label
+	// reads straight off the slice; there is no WPDS token for "no surface".
+	--a8c-charts-color-label-background: var(--a8c-charts-color-label-background-theme, transparent);
 	// The SVG axis and tick labels. `svgLabelSmall.fill` publishes THIS role, so
 	// deriving from --a8c-charts-color-label is safe and wanted: the theme field
 	// moves only these labels, while setting the broad role in CSS still moves

package/src/styles/test/chart-scope.test.ts

@@ -20,16 +20,19 @@ const normalize = ( value: string ): string => value.replace( /\s+/g, ' ' ).trim
 /**
  * Unwraps the theme layer a `theme`-prop-overridable role carries, so the tables in `TOKENS.md` keep documenting what a role ultimately resolves to — its `--wpds-*` token and spec fallback — rather than restating the override plumbing in every row. Which roles carry the layer is pinned separately below.
  *
+ * A role with no catalog default reads its layer with no fallback at all — the empty series-palette slots — and unwraps to nothing, which is what it resolves to until a consumer sets it.
+ *
  * @param name  - The declared property name.
  * @param value - Its normalized value.
- * @return The value with a leading `var(<name>-theme, … )` wrapper removed.
+ * @return The value with a leading `var(<name>-theme, … )` wrapper removed, or the empty string where that wrapper carried no fallback.
  */
 function stripThemeLayer( name: string, value: string ): string {
-	const layered = new RegExp( `^var\\(\\s*${ themeLayerVar( name ) }\\s*,\\s*(.*)\\)$`, 's' ).exec(
-		value
-	);
+	const layered = new RegExp(
+		`^var\\(\\s*${ themeLayerVar( name ) }\\s*(?:,\\s*(.*))?\\)$`,
+		's'
+	).exec( value );
 
-	return layered ? layered[ 1 ].trim() : value;
+	return layered ? ( layered[ 1 ] ?? '' ).trim() : value;
 }
 
 /**
@@ -55,6 +58,13 @@ function parseStylesheet(): Map< string, Entry > {
 
 		const name = declaration.slice( 0, separator ).trim();
 		const value = stripThemeLayer( name, normalize( declaration.slice( separator + 1 ) ) );
+
+		// A role that unwrapped to nothing maps to nothing and falls back to nothing.
+		if ( value === '' ) {
+			entries.set( name, { reads: null, fallback: null } );
+			continue;
+		}
+
 		const wrapped = /^var\(\s*(.*)\)$/s.exec( value );
 
 		if ( ! wrapped ) {
@@ -112,10 +122,13 @@ function parseTokensDoc(): Map< string, Entry > {
 		// "no mapping" before looking for a token name inside it.
 		const unmapped = mapping.startsWith( '_(none' );
 		const derives = /derives from (--[\w-]+)/.exec( mapping );
-		const wpds = /(--wpds-[\w-]+)/.exec( mapping );
+		// `--wp-*` rather than `--wpds-*`: the series palette maps to WordPress's own
+		// `--wp-admin-theme-color`, since the design system's brand token is a static
+		// hex on every admin screen and cannot carry the admin color scheme.
+		const token = /(--wp[\w-]+)/.exec( mapping );
 
 		entries.set( role, {
-			reads: unmapped ? null : derives?.[ 1 ] ?? wpds?.[ 1 ] ?? null,
+			reads: unmapped ? null : derives?.[ 1 ] ?? token?.[ 1 ] ?? null,
 			fallback: fallback === '—' ? null : normalize( fallback ),
 		} );
 	}
@@ -140,13 +153,13 @@ describe( 'chart scope catalog', () => {
 	// The layer is what keeps a `theme` prop override from being able to take its role down with it: an override that is invalid at computed-value time only invalidates `<role>-theme`, and the role's own fallback still resolves the mapped token. Drop the layer from a role and that role's overrides go back to blanking every read site.
 	it.each( THEME_LAYERED_ROLES )( 'declares %s reading its theme layer first', role => {
 		expect( stylesheet ).toMatch(
-			new RegExp( `${ role }:\\s*var\\(\\s*${ themeLayerVar( role ) }\\s*,` )
+			new RegExp( `${ role }:\\s*var\\(\\s*${ themeLayerVar( role ) }\\s*[,)]` )
 		);
 	} );
 
 	it( 'gives a theme layer to the overridable roles and to nothing else', () => {
 		const layered = [ ...declared.keys() ].filter( role =>
-			new RegExp( `${ role }:\\s*var\\(\\s*${ themeLayerVar( role ) }\\s*,` ).test( stylesheet )
+			new RegExp( `${ role }:\\s*var\\(\\s*${ themeLayerVar( role ) }\\s*[,)]` ).test( stylesheet )
 		);
 
 		expect( layered.sort() ).toEqual( [ ...THEME_LAYERED_ROLES ].sort() );