@automattic/charts 3.1.1 → 3.2.0

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() );

package/src/types.ts

@@ -108,13 +108,31 @@ export type ChartType =
 
 export type OrientationType = ValueOf< typeof Orientation >;
 
+/**
+ * Annotation styling.
+ *
+ * Each color member is deprecated on its own rather than the field it sits in: `radius`, `stroke` widths and the label geometry alongside them have no catalog role behind them and still apply.
+ */
 export type AnnotationStyles = {
-	circleSubject?: Omit< CircleSubjectProps, 'x' | 'y' > & { fill?: string };
+	circleSubject?: Omit< CircleSubjectProps, 'x' | 'y' | 'fill' > & {
+		/** @deprecated Set the `--a8c-charts-color-annotation` custom property inside the provider tree instead. See `TOKENS.md`. */
+		fill?: string;
+	};
 	lineSubject?: Omit< LineSubjectProps, 'x' | 'y' >;
-	connector?: Omit< ConnectorProps, 'x' | 'y' | 'dx' | 'dy' >;
-	label?: Omit< LabelProps, 'title' | 'subtitle' | 'x' | 'y' > & {
+	connector?: Omit< ConnectorProps, 'x' | 'y' | 'dx' | 'dy' | 'stroke' > & {
+		/** @deprecated Set the `--a8c-charts-color-annotation` custom property inside the provider tree instead. See `TOKENS.md`. */
+		stroke?: ConnectorProps[ 'stroke' ];
+	};
+	label?: Omit<
+		LabelProps,
+		'title' | 'subtitle' | 'x' | 'y' | 'anchorLineStroke' | 'backgroundFill'
+	> & {
 		x?: number | 'start' | 'end';
 		y?: number | 'start' | 'end';
+		/** @deprecated Set the `--a8c-charts-color-annotation` custom property inside the provider tree instead. See `TOKENS.md`. */
+		anchorLineStroke?: LabelProps[ 'anchorLineStroke' ];
+		/** @deprecated Set the `--a8c-charts-color-surface` custom property inside the provider tree instead. See `TOKENS.md`. */
+		backgroundFill?: LabelProps[ 'backgroundFill' ];
 	};
 };
 
@@ -305,7 +323,7 @@ export type DataPointPercentage = {
 	 */
 	valueDisplay?: string;
 	/**
-	 * Color code for the segment, by default colours are taken from the theme but this property can overrides it
+	 * Color code for the segment, by default colors are taken from the theme but this property can overrides it
 	 */
 	color?: string;
 	/**
@@ -329,26 +347,67 @@ export type DataPointPercentageCalculated = DataPointPercentage & {
  * Base theme configuration for chart components with optional properties
  */
 export type ChartTheme = {
-	/** Background color for chart components */
-	backgroundColor: string;
-	/** Background color for labels */
+	/**
+	 * Background color for chart components.
+	 *
+	 * Still resolved in JS — gradient stops, the glyph stroke and `GeoChart`'s Google Charts config each need a concrete string — but that is about where the value is *consumed*, not where it is *set*. `withCatalogPointers` parks a consumer's value in the catalog role and restores the pointer, so the field is only ever a carrier for `--a8c-charts-color-background`, and setting the role directly does the same job.
+	 *
+	 * Optional so the deprecation is actionable: a consumer writing a full theme literal can now stop setting it. `CompleteChartTheme` is `Required< ChartTheme >`, so `defaultTheme` must still carry one.
+	 *
+	 * @deprecated Set the `--a8c-charts-color-background` custom property inside the provider tree instead. See `TOKENS.md`.
+	 */
+	backgroundColor?: string;
+	/**
+	 * Background color for labels.
+	 *
+	 * @deprecated Set the `--a8c-charts-color-label-background` custom property inside the provider tree instead. See `TOKENS.md`.
+	 */
 	labelBackgroundColor?: string;
-	/** Text color for labels */
+	/**
+	 * Text color for labels.
+	 *
+	 * @deprecated Set the `--a8c-charts-color-label-on-fill` custom property inside the provider tree instead. See `TOKENS.md`.
+	 */
 	labelTextColor?: string;
-	/** Array of colors used for data visualization */
-	colors: string[];
-	/** Optional CSS styles for grid lines */
-	gridStyles?: GridStyles;
+	/**
+	 * Series palette seeds. Entry N publishes `--a8c-charts-color-series-{N+1}`; entries past the fifth are ignored.
+	 *
+	 * Optional so the deprecation is actionable: a consumer writing a full theme literal can now stop setting it. `CompleteChartTheme` is `Required< ChartTheme >`, so `defaultTheme` must still carry one.
+	 *
+	 * @deprecated Set the `--a8c-charts-color-series-1` … `-5` custom properties inside the provider tree instead, or `options.stroke` on a series for a single one. See `TOKENS.md`.
+	 */
+	colors?: string[];
+	/**
+	 * Optional CSS styles for grid lines.
+	 *
+	 * `stroke` is deprecated on its own, not the whole field: `strokeWidth` has no CSS role behind it and still applies. The same shape is used for the other fields whose color moved to CSS — annotating the field itself would strike through the half that stays.
+	 */
+	gridStyles?: Omit< GridStyles, 'stroke' > & {
+		/** @deprecated Set the `--a8c-charts-color-grid` custom property inside the provider tree instead. See `TOKENS.md`. */
+		stroke?: GridStyles[ 'stroke' ];
+	};
 	/** Length of axis ticks in pixels */
 	tickLength: number;
-	/** Color of the grid lines */
-	gridColor: string;
-	/** Color of the grid lines in dark mode */
-	gridColorDark: string;
+	/**
+	 * Set `--a8c-charts-color-grid` for the gridlines.
+	 *
+	 * @deprecated Do not drop this field without replacing it. Nothing in this package consults it, but `buildChartTheme` seeds `y.left/right.axisLine.stroke` and `y.*.tickLine.stroke` from it, and `defaultTheme`'s empty string is the only thing leaving the y axis unpainted — deleting the field hands those a black `#222` instead. CHARTS-263 replaces it with visx's own `yAxisLineStyles`/`yTickLineStyles` and a pair of catalog roles.
+	 */
+	gridColor?: string;
+	/**
+	 * @deprecated Paints nothing, and unlike `gridColor` is safe to delete: `buildChartTheme` seeds `x.*.axisLine.stroke` from it, but spreads `xAxisLineStyles` over the top and `defaultTheme` always carries that stroke. Charts follow the host's theme through the catalog rather than a dark-mode field of their own.
+	 */
+	gridColorDark?: string;
 	/** Styles for x-axis tick lines */
-	xTickLineStyles?: LineStyles;
+	xTickLineStyles?: Omit< LineStyles, 'stroke' > & {
+		/** @deprecated Set the `--a8c-charts-color-tick` custom property inside the provider tree instead. See `TOKENS.md`. */
+		stroke?: LineStyles[ 'stroke' ];
+	};
 	/** Styles for x-axis line */
-	xAxisLineStyles?: LineStyles;
+	xAxisLineStyles?: Omit< LineStyles, 'stroke' > & {
+		/** @deprecated Set the `--a8c-charts-color-axis` custom property inside the provider tree instead. See `TOKENS.md`. */
+		stroke?: LineStyles[ 'stroke' ];
+	};
 	/** Styles for series lines */
 	seriesLineStyles?: LineStyles[];
 	/** Array of render functions for glyphs */
@@ -357,19 +416,37 @@ export type ChartTheme = {
 	legend?: {
 		/** Styles for legend shapes */
 		shapeStyles?: Record< string, unknown >[];
-		/** Styles for legend labels */
-		labelStyles?: CSSProperties;
+		/**
+		 * Styles for legend labels.
+		 *
+		 * `color` is deprecated on its own, not the whole field: everything else a consumer sets here — font size, weight, spacing — has no catalog role behind it and still applies.
+		 */
+		labelStyles?: Omit< CSSProperties, 'color' > & {
+			/** @deprecated Set the `--a8c-charts-color-label` custom property inside the provider tree instead. See `TOKENS.md`. */
+			color?: CSSProperties[ 'color' ];
+		};
 		/** Styles for legend container */
 		containerStyles?: CSSProperties;
 	};
-	/** Styles for small SVG text (eg. axis tick labels), passed through to the XYChart theme. */
-	svgLabelSmall?: TextProps;
+	/**
+	 * Styles for small SVG text (eg. axis tick labels), passed through to the XYChart theme.
+	 *
+	 * `fontFamily: 'inherit'` is load-bearing here — it overrides the font stack `buildChartTheme` injects inline on SVG `<text>` — so only `fill` is deprecated.
+	 */
+	svgLabelSmall?: Omit< TextProps, 'fill' > & {
+		/** @deprecated Set the `--a8c-charts-color-label-axis` custom property inside the provider tree instead, or `--a8c-charts-color-label` to move every label at once. See `TOKENS.md`. */
+		fill?: TextProps[ 'fill' ];
+	};
 	/** Styles for large SVG text (eg. axis titles), passed through to the XYChart theme. */
 	svgLabelBig?: TextProps;
 	annotationStyles?: AnnotationStyles;
 	/** GeoChart specific settings */
 	geoChart?: {
-		/** Default fill color for a geo chart feature (e.g. country) with no data */
+		/**
+		 * Default fill color for a geo chart feature (e.g. country) with no data.
+		 *
+		 * @deprecated Set the `--a8c-charts-color-surface-secondary` custom property inside the provider tree instead. Google Charts still takes a resolved hex, but the value is read from the role. See `TOKENS.md`.
+		 */
 		featureFillColor?: string;
 	};
 	/** LeaderboardChart specific settings */
@@ -380,22 +457,50 @@ export type ChartTheme = {
 		columnGap?: number;
 		/** Spacing between label and progress bars */
 		labelSpacing?: GapSize;
-		/** Primary color for current period bars */
+		/**
+		 * Primary color for current period bars.
+		 *
+		 * @deprecated Use the `primaryColor` prop on `LeaderboardChart` for one chart, or set `--a8c-charts-color-series-1` to move the palette this falls back to. See `TOKENS.md`.
+		 */
 		primaryColor?: string;
-		/** Secondary color for comparison period bars */
+		/**
+		 * Secondary color for comparison period bars.
+		 *
+		 * @deprecated Use the `secondaryColor` prop on `LeaderboardChart` for one chart, or set `--a8c-charts-color-series-2` to move the palette this falls back to. See `TOKENS.md`.
+		 */
 		secondaryColor?: string;
-		/** Delta colors: [negative, neutral, positive] */
+		/**
+		 * Delta colors: [negative, neutral, positive].
+		 *
+		 * @deprecated Set the `--a8c-charts-color-trend-down`, `-trend-neutral` and `-trend-up` custom properties inside the provider tree instead. See `TOKENS.md`.
+		 */
 		deltaColors?: [ string, string, string ];
 	};
 	/** ConversionFunnelChart specific settings */
 	conversionFunnelChart?: {
-		/** Primary color for funnel bars */
+		/**
+		 * Primary color for funnel bars.
+		 *
+		 * @deprecated Set `--a8c-charts-color-series-1` to move the palette this falls back to. See `TOKENS.md`.
+		 */
 		primaryColor?: string;
-		/** Background color for chart container */
+		/**
+		 * Background color for chart container.
+		 *
+		 * @deprecated Set the `--a8c-charts-color-surface-secondary` custom property inside the provider tree instead. See `TOKENS.md`.
+		 */
 		backgroundColor?: string;
-		/** Color for positive change indicators */
+		/**
+		 * Color for positive change indicators.
+		 *
+		 * @deprecated Set the `--a8c-charts-color-trend-up` custom property inside the provider tree instead. See `TOKENS.md`.
+		 */
 		positiveChangeColor?: string;
-		/** Color for negative change indicators */
+		/**
+		 * Color for negative change indicators.
+		 *
+		 * @deprecated Set the `--a8c-charts-color-trend-down` custom property inside the provider tree instead. See `TOKENS.md`.
+		 */
 		negativeChangeColor?: string;
 	};
 	lineChart?: {
@@ -424,6 +529,8 @@ export type ChartTheme = {
 		/**
 		 * Color the cell scale interpolates toward at the highest value (prop > this >
 		 * palette `colors[0]`), fed to CSS `color-mix`. Omit to use the palette color.
+		 *
+		 * @deprecated Use the `primaryColor` prop on `HeatmapChart` for one chart, or set `--a8c-charts-color-series-1` to move the palette this falls back to. See `TOKENS.md`.
 		 */
 		primaryColor?: string;
 		/** Gap in px between cells in compact mode */
@@ -626,7 +733,7 @@ export type ChartLegendConfig< T = DataPoint | DataPointDate | LeaderboardEntry
 /**
  * Legend config for charts built from `SeriesData` (line, bar, area). Adds `collapseGroups` on top
  * of the shared config. It is intentionally absent from the base `ChartLegendConfig` so point-based
- * charts (pie, semi-circle pie) — whose data points carry `group` only to coordinate colours — can't
+ * charts (pie, semi-circle pie) — whose data points carry `group` only to coordinate colors — can't
  * set it.
  */
 export type SeriesChartLegendConfig = ChartLegendConfig< SeriesData[] > & {
@@ -706,6 +813,16 @@ export type BaseChartProps< T = DataPoint | DataPointDate | LeaderboardEntry > =
 	 * Callback function for pointer out event
 	 */
 	onPointerOut?: ( event: PointerEvent< Element > ) => void;
+	/**
+	 * Callback for Enter or Space on the point keyboard navigation has selected:
+	 * the keyboard counterpart of a click. `index` is the point's position in its
+	 * series and `key` the series label.
+	 */
+	onDatumActivate?: ( params: {
+		datum: DataPoint | DataPointDate;
+		index: number;
+		key: string;
+	} ) => void;
 	/**
 	 * Whether to show tooltips on hover. False by default.
 	 */