@automattic/charts 2.0.1 → 3.0.0

package/src/charts/leaderboard-chart/leaderboard-chart.module.scss

@@ -60,20 +60,26 @@
 		// row's fixed-pixel hover inset from collapsing a narrow bar to nothing.
 		min-width: var(--wpds-dimension-size-5xs, 4px);
 
-		border-radius: var(--a8c-charts-border-radius-leaderboard-bar, var(--a8c--charts--leaderboard--bar--border-radius, 9999px));
+		border-radius: var(--a8c-charts-border-radius-leaderboard-bar);
 		z-index: -1; /* places it behind the label */
 
+		// Keep the collapsed state in `from` and never on the element: a dropped
+		// animation then fails visible. `both`, not `forwards`, for the
+		// backwards fill.
 		&--animated {
 			transform-origin: left;
 			transform-box: fill-box;
-			transform: scaleX(0);
 			animation:
-				stretch var(--wpds-motion-duration-xl, 400ms)
-				var(--wpds-motion-easing-expressive, cubic-bezier(0.25, 0, 0, 1)) forwards;
+				stretch var(--a8c-charts-motion-duration-entrance)
+				var(--a8c-charts-motion-easing-entrance) both;
 		}
 
 		@keyframes stretch {
 
+			from {
+				transform: scaleX(0);
+			}
+
 			to {
 				transform: scaleX(1);
 			}
@@ -104,7 +110,7 @@
 .emptyState {
 	padding: var(--wpds-dimension-padding-3xl, 32px) var(--wpds-dimension-padding-lg, 16px);
 	text-align: center;
-	color: var(--a8c-charts-color-label-secondary, var(--wpds-color-foreground-content-neutral-weak, #707070));
+	color: var(--a8c-charts-color-label-secondary);
 	font-size: var(--wpds-typography-font-size-md, 13px);
 	font-style: italic;
 }
@@ -205,7 +211,7 @@ $focus-ring-width: var(--wpds-border-width-focus, var(--wp-admin-border-width-fo
 		border-radius: var(--wpds-border-radius-sm, 2px);
 		outline:
 			$focus-ring-width solid
-			var(--a8c-charts-color-focus, var(--wpds-color-stroke-focus, var(--wp-admin-theme-color, #3858e9)));
+			var(--wpds-color-stroke-focus, var(--wp-admin-theme-color, #3858e9));
 		// Inset by its own width so the outer edge hugs the row boundary: the
 		// outline then sits in the shared row padding, clear of the bar, and stays
 		// inside the overflow:auto container that would clip an outset ring.
@@ -220,7 +226,7 @@ $focus-ring-width: var(--wpds-border-width-focus, var(--wp-admin-border-width-fo
 	bottom: 0;
 	margin-block: auto;
 	opacity: 0;
-	color: var(--a8c-charts-color-label-secondary, var(--wpds-color-foreground-content-neutral-weak, #707070));
+	color: var(--a8c-charts-color-label-secondary);
 	transition:
 		opacity var(--wpds-motion-duration-sm, 100ms)
 		var(--wpds-motion-easing-subtle, cubic-bezier(0.15, 0, 0.15, 1));

package/src/charts/leaderboard-chart/types.ts

@@ -65,8 +65,6 @@ export interface LeaderboardChartProps
 	 */
 	style?: React.CSSProperties & {
 		'--a8c-charts-border-radius-leaderboard-bar'?: string;
-		/** @deprecated Use `--a8c-charts-border-radius-leaderboard-bar`. */
-		'--a8c--charts--leaderboard--bar--border-radius'?: string;
 	};
 
 	/**

package/src/charts/line-chart/line-chart.module.scss

@@ -1,14 +1,15 @@
 .line-chart {
 	position: relative;
 
+	// Keep the collapsed state in `from` and never on the element: a dropped
+	// animation then fails visible. `both`, not `forwards`, for backwards fill.
 	&--animated {
 
 		path {
 			transform-origin: 0 95%;
-			transform: scaleY(0);
 			animation:
-				rise var(--wpds-motion-duration-xl, 400ms)
-				var(--wpds-motion-easing-expressive, cubic-bezier(0.25, 0, 0, 1)) forwards;
+				rise var(--a8c-charts-motion-duration-entrance)
+				var(--a8c-charts-motion-easing-entrance) both;
 		}
 	}
 
@@ -18,8 +19,8 @@
 
 	&__tooltip,
 	&__annotation-label-popover {
-		background: var(--a8c-charts-color-background, var(--wpds-color-background-surface-neutral-strong, #fff));
-		color: var(--a8c-charts-color-label, var(--wpds-color-foreground-content-neutral, #1e1e1e));
+		background: var(--a8c-charts-color-surface);
+		color: var(--a8c-charts-color-label);
 		padding: var(--wpds-dimension-padding-sm, 8px);
 	}
 
@@ -110,6 +111,10 @@
 
 @keyframes rise {
 
+	from {
+		transform: scaleY(0);
+	}
+
 	to {
 		transform: scaleY(1);
 	}

package/src/charts/line-chart/line-chart.tsx

@@ -193,7 +193,7 @@ const LineChartInternal = forwardRef< SingleChartRef, LineChartProps >(
 
 		const providerTheme = useGlobalChartsTheme();
 		const theme = useXYChartTheme( data );
-		// Gradient stops apply this as an SVG attribute, where CSS var() cannot resolve. useXYChartTheme has already resolved the same role inside its memo, so read it back rather than paying another getComputedStyle on every render.
+		// Gradient stops apply this as an SVG attribute, where CSS var() cannot resolve. useXYChartTheme has already resolved the same role inside its memo, against the chart's scope element, so read it back rather than paying another getComputedStyle on every render.
 		const resolvedBackgroundColor = theme.backgroundColor ?? providerTheme.backgroundColor;
 		const chartId = useChartId( providedChartId );
 		const chartRef = useRef< HTMLDivElement >( null );

package/src/charts/line-chart/private/line-chart-annotation.tsx

@@ -9,7 +9,7 @@ import {
 import { DataContext } from '@visx/xychart';
 import merge from 'deepmerge';
 import { useContext, useRef, useEffect, useState, useMemo } from 'react';
-import { useGlobalChartsTheme } from '../../../providers';
+import { useChartScopeElement, useGlobalChartsTheme } from '../../../providers';
 import { isSafari, resolveCssVariable } from '../../../utils';
 import LineChartAnnotationLabelWithPopover, {
 	POPOVER_BUTTON_SIZE,
@@ -152,6 +152,7 @@ const LineChartAnnotation: FC< LineChartAnnotationProps > = ( {
 	renderLabelPopover,
 } ) => {
 	const providerTheme = useGlobalChartsTheme();
+	const scopeElement = useChartScopeElement();
 	const { xScale, yScale } = useContext( DataContext ) || {};
 	const labelRef = useRef< SVGGElement >( null );
 	const [ height, setHeight ] = useState< number | null >( null );
@@ -159,10 +160,9 @@ const LineChartAnnotation: FC< LineChartAnnotationProps > = ( {
 	// Deep merge styles to preserve nested object properties
 	const styles = merge( providerTheme.annotationStyles ?? {}, datumStyles ?? {} );
 
-	// visx annotation parts apply these colors as SVG presentation attributes,
-	// where CSS var() cannot resolve. Resolve WPDS tokens to concrete values first.
+	// visx annotation parts apply these colours as SVG presentation attributes, where CSS var() cannot resolve. Resolve against the chart's scope element, never :root.
 	const resolveColor = ( value?: string ): string | undefined =>
-		value ? resolveCssVariable( value ) ?? value : value;
+		value ? resolveCssVariable( value, scopeElement ) ?? value : value;
 
 	// Measure the label height once after initial render
 	useEffect( () => {

package/src/charts/pie-chart/pie-chart.tsx

@@ -19,6 +19,7 @@ import {
 	useGlobalChartsTheme,
 	GlobalChartsContext,
 } from '../../providers';
+import { CHART_SCOPE_CLASS } from '../../styles/chart-scope-class';
 import { attachSubComponents, resolveFontSize } from '../../utils';
 import { getStringWidth } from '../../visx/text';
 import { Center } from '../private/center';
@@ -328,7 +329,9 @@ const PieChartInternal = ( {
 					<>
 						{ withTooltips && tooltipOpen && tooltipData && (
 							<TooltipInPortal top={ tooltipTop || 0 } left={ tooltipLeft || 0 }>
-								<div role="tooltip">{ renderTooltip( { tooltipData } ) }</div>
+								<div className={ CHART_SCOPE_CLASS } role="tooltip">
+									{ renderTooltip( { tooltipData } ) }
+								</div>
 							</TooltipInPortal>
 						) }
 						{ htmlChildren }

package/src/charts/pie-semi-circle-chart/pie-semi-circle-chart.tsx

@@ -19,6 +19,7 @@ import {
 	useGlobalChartsContext,
 	GlobalChartsContext,
 } from '../../providers';
+import { CHART_SCOPE_CLASS } from '../../styles/chart-scope-class';
 import { attachSubComponents } from '../../utils';
 import { Center } from '../private/center';
 import { ChartSVG, ChartHTML, useChartChildren } from '../private/chart-composition';
@@ -375,7 +376,9 @@ const PieSemiCircleChartInternal: FC< PieSemiCircleChartProps > = ( {
 					<>
 						{ withTooltips && tooltipOpen && tooltipData && (
 							<TooltipInPortal top={ tooltipTop || 0 } left={ tooltipLeft || 0 }>
-								<div role="tooltip">{ renderTooltip( { tooltipData } ) }</div>
+								<div className={ CHART_SCOPE_CLASS } role="tooltip">
+									{ renderTooltip( { tooltipData } ) }
+								</div>
 							</TooltipInPortal>
 						) }
 						{ htmlChildren }

package/src/charts/private/svg-empty-state/svg-empty-state.module.scss

@@ -1,5 +1,5 @@
 .svg-empty-state {
 	text-align: center;
 	font-size: var(--wpds-typography-font-size-md, 13px);
-	color: var(--a8c-charts-color-label-secondary, var(--wpds-color-foreground-content-neutral-weak, #707070));
+	color: var(--a8c-charts-color-label-secondary);
 }

package/src/charts/private/with-responsive/test/with-responsive.test.tsx

@@ -1,4 +1,6 @@
 import { render, screen } from '@testing-library/react';
+import { useContext } from 'react';
+import { ChartScopeContext } from '../../../../providers/chart-scope';
 import { withResponsive } from '../index';
 import type { BaseChartProps } from '../../../../types';
 
@@ -311,4 +313,18 @@ describe( 'withResponsive', () => {
 			expect( screen.getByTestId( 'responsive-container' ) ).toBeInTheDocument();
 		} );
 	} );
+
+	it( 'publishes the responsive wrapper element as the chart scope', () => {
+		// The catalog is declared on the GlobalChartsProvider wrapper (or a standalone component's own element), not on every chart root, so this wrapper doesn't carry a scope class itself — but it must still be the element the JS bridge resolves scoped CSS variables against, via ChartScopeContext, so it picks up any override set inside the provider tree the same way a CSS-painted sibling would.
+		const ScopeProbe = () => {
+			const scopeNode = useContext( ChartScopeContext );
+			return <span data-testid="scope-probe">{ scopeNode?.dataset.testid }</span>;
+		};
+		const Chart: ( props: BaseChartProps ) => JSX.Element = () => <ScopeProbe />;
+		const Wrapped = withResponsive( Chart );
+
+		render( <Wrapped data={ [] } /> );
+
+		expect( screen.getByTestId( 'scope-probe' ) ).toHaveTextContent( 'responsive-wrapper' );
+	} );
 } );

package/src/charts/private/with-responsive/with-responsive.tsx

@@ -1,6 +1,7 @@
 import { useParentSize } from '@visx/responsive';
 import clsx from 'clsx';
 import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { ChartScopeContext } from '../../../providers/chart-scope';
 import styles from './with-responsive.module.scss';
 import type { BaseChartProps } from '../../../types';
 import type { ComponentType } from 'react';
@@ -66,6 +67,9 @@ export function withResponsive< T extends Exclude< BaseChartProps< unknown >, 'o
 
 		const hasAspectRatio = aspectRatio !== undefined && aspectRatio > 0;
 
+		// The context needs a re-render when the node attaches; wrapperRef alone cannot provide that, so mirror the node into state from the same callback ref.
+		const [ scopeNode, setScopeNode ] = useState< HTMLDivElement | null >( null );
+
 		// Keep our own handle on the wrapper so we can read its live height below, and
 		// still hand the node to useParentSize's ref (a callback ref in practice; guard
 		// the object-ref shape too).
@@ -73,6 +77,7 @@ export function withResponsive< T extends Exclude< BaseChartProps< unknown >, 'o
 		const setWrapperRef = useCallback(
 			( node: HTMLDivElement | null ) => {
 				wrapperRef.current = node;
+				setScopeNode( node );
 				if ( typeof parentRef === 'function' ) {
 					parentRef( node );
 				} else if ( parentRef ) {
@@ -160,17 +165,19 @@ export function withResponsive< T extends Exclude< BaseChartProps< unknown >, 'o
 					...( height !== undefined ? { height } : null ),
 				} }
 			>
-				{ hasAspectRatio ? (
-					<div
-						data-testid="responsive-content"
-						className={ styles.content }
-						style={ { width: boxWidth, height: boxHeight } }
-					>
-						{ wrappedComponent }
-					</div>
-				) : (
-					wrappedComponent
-				) }
+				<ChartScopeContext.Provider value={ scopeNode }>
+					{ hasAspectRatio ? (
+						<div
+							data-testid="responsive-content"
+							className={ styles.content }
+							style={ { width: boxWidth, height: boxHeight } }
+						>
+							{ wrappedComponent }
+						</div>
+					) : (
+						wrappedComponent
+					) }
+				</ChartScopeContext.Provider>
 			</div>
 		);
 	};

package/src/charts/private/x-zoom/x-zoom.module.scss

@@ -3,9 +3,9 @@
 	// The selection's translucency lives in the SVG opacity properties so
 	// the colors themselves can come straight from WPDS tokens.
 	&__selection {
-		fill: var(--a8c-charts-color-zoom-selection, var(--wpds-color-background-interactive-brand-strong, #3858e9));
+		fill: var(--a8c-charts-color-zoom-selection);
 		fill-opacity: 0.16;
-		stroke: var(--a8c-charts-color-zoom-selection-stroke, var(--wpds-color-stroke-interactive-brand, #3858e9));
+		stroke: var(--a8c-charts-color-zoom-selection-stroke);
 		stroke-opacity: 0.65;
 		stroke-width: var(--wpds-border-width-xs, 1px);
 		pointer-events: none;
@@ -29,7 +29,7 @@
 		// through it. Scoped to the rest state so the WPDS
 		// hover/active/focus backgrounds still apply.
 		&:not(:hover, :active, :focus) {
-			background-color: var(--a8c-charts-color-background, var(--wpds-color-background-surface-neutral-strong, #fff));
+			background-color: var(--a8c-charts-color-surface);
 		}
 	}
 }

package/src/components/legend/private/base-legend.tsx

@@ -13,6 +13,7 @@ import {
 } from 'react';
 import { useTextTruncation } from '../../../hooks';
 import { GlobalChartsContext, useGlobalChartsTheme } from '../../../providers';
+import { useStandaloneScopeClass } from '../../../providers/chart-scope';
 import { valueOrIdentity, valueOrIdentityString, labelTransformFactory } from '../utils';
 import styles from './base-legend.module.scss';
 import type { BaseLegendProps } from '../types';
@@ -102,6 +103,7 @@ export const BaseLegend: ForwardRefExoticComponent<
 
 		const theme = useGlobalChartsTheme();
 		const context = useContext( GlobalChartsContext );
+		const standaloneScopeClass = useStandaloneScopeClass();
 
 		const legendScale = scaleOrdinal( {
 			domain: items.map( item => item.label ),
@@ -189,7 +191,7 @@ export const BaseLegend: ForwardRefExoticComponent<
 						wrap={ orientation === 'horizontal' ? 'wrap' : undefined }
 						role="list"
 						data-testid={ `legend-${ orientation }` }
-						className={ clsx( styles.legend, className ) }
+						className={ clsx( standaloneScopeClass, styles.legend, className ) }
 						style={ theme.legend?.containerStyles }
 					>
 						{ labels.map( ( label, i ) => {

package/src/components/tooltip/accessible-tooltip.tsx

@@ -1,5 +1,7 @@
 import { Tooltip, TooltipContext } from '@visx/xychart';
+import clsx from 'clsx';
 import { useContext, useEffect, useCallback, useMemo } from 'react';
+import { CHART_SCOPE_CLASS } from '../../styles/chart-scope-class';
 import type { SeriesData, DataPointDate } from '../../types';
 import type { RenderTooltipParams, XyChartTooltipProps } from '../../visx/types';
 import type { ReactNode } from 'react';
@@ -128,7 +130,7 @@ export const AccessibleTooltip: React.FC< AccessibleTooltipProps > = ( {
 						tabIndex={ -1 }
 						role="tooltip"
 						aria-atomic="true"
-						className={ keyboardFocusedClassName }
+						className={ clsx( CHART_SCOPE_CLASS, keyboardFocusedClassName ) }
 						data-testid={ `chart-tooltip-${ selectedIndex }` }
 						key={ `chart-tooltip-${ selectedIndex }` }
 					>
@@ -138,7 +140,7 @@ export const AccessibleTooltip: React.FC< AccessibleTooltipProps > = ( {
 			}
 
 			return (
-				<div role="tooltip" aria-live="polite">
+				<div className={ CHART_SCOPE_CLASS } role="tooltip" aria-live="polite">
 					{ tooltipContent }
 				</div>
 			);

package/src/components/tooltip/base-tooltip.tsx

@@ -1,4 +1,6 @@
 import { formatNumber } from '@automattic/number-formatters';
+import clsx from 'clsx';
+import { useStandaloneScopeClass } from '../../providers/chart-scope';
 import styles from './base-tooltip.module.scss';
 import type { CSSProperties, ComponentType, ReactNode } from 'react';
 
@@ -57,13 +59,18 @@ export const BaseTooltip = ( {
 	renderContainer = true,
 }: BaseTooltipProps ) => {
 	const content = children || ( data && <Component data={ data } className={ className } /> );
+	const standaloneScopeClass = useStandaloneScopeClass();
 
 	if ( ! renderContainer ) {
 		return content;
 	}
 
 	return (
-		<div className={ styles.tooltip } style={ { top, left, ...style } } role="tooltip">
+		<div
+			className={ clsx( standaloneScopeClass, styles.tooltip ) }
+			style={ { top, left, ...style } }
+			role="tooltip"
+		>
 			{ content }
 		</div>
 	);

package/src/components/trend-indicator/test/trend-indicator.test.tsx

@@ -1,4 +1,6 @@
 import { render, screen } from '@testing-library/react';
+import { GlobalChartsProvider } from '../../../providers/chart-context/global-charts-provider';
+import { CHART_SCOPE_CLASS } from '../../../styles/chart-scope-class';
 import { TrendIndicator } from '../trend-indicator';
 
 describe( 'TrendIndicator', () => {
@@ -79,6 +81,24 @@ describe( 'TrendIndicator', () => {
 		expect( container.firstChild ).toHaveStyle( { fontSize: '32px' } );
 	} );
 
+	describe( 'chart scope class', () => {
+		it( 'carries the scope class when rendered with no provider above it', () => {
+			render( <TrendIndicator direction="up" value="+10%" /> );
+
+			expect( screen.getByLabelText( 'Increase: +10%' ) ).toHaveClass( CHART_SCOPE_CLASS );
+		} );
+
+		it( 'does not carry the scope class when rendered inside a GlobalChartsProvider', () => {
+			render(
+				<GlobalChartsProvider>
+					<TrendIndicator direction="up" value="+10%" />
+				</GlobalChartsProvider>
+			);
+
+			expect( screen.getByLabelText( 'Increase: +10%' ) ).not.toHaveClass( CHART_SCOPE_CLASS );
+		} );
+	} );
+
 	describe( 'accessibility', () => {
 		it( 'provides aria-label for up trend', () => {
 			const { container } = render( <TrendIndicator direction="up" value="+14%" /> );

package/src/components/trend-indicator/trend-indicator.module.scss

@@ -6,19 +6,16 @@
 	font-weight: var(--wpds-typography-font-weight-emphasis, 499);
 	line-height: 1;
 
-	// Trend colours use the --a8c-charts-color-trend-* catalog roles, falling back
-	// to the deprecated --charts-trend-*-color override API and then to the
-	// accessible WPDS semantic tokens.
 	&--up {
-		color: var(--a8c-charts-color-trend-up, var(--charts-trend-up-color, var(--wpds-color-foreground-content-success-weak, #008030)));
+		color: var(--a8c-charts-color-trend-up);
 	}
 
 	&--down {
-		color: var(--a8c-charts-color-trend-down, var(--charts-trend-down-color, var(--wpds-color-foreground-content-error-weak, #cc1818)));
+		color: var(--a8c-charts-color-trend-down);
 	}
 
 	&--neutral {
-		color: var(--a8c-charts-color-trend-neutral, var(--charts-trend-neutral-color, var(--wpds-color-foreground-content-neutral-weak, #707070)));
+		color: var(--a8c-charts-color-trend-neutral);
 	}
 
 	&__icon {

package/src/components/trend-indicator/trend-indicator.tsx

@@ -1,4 +1,5 @@
 import clsx from 'clsx';
+import { useStandaloneScopeClass } from '../../providers/chart-scope';
 import styles from './trend-indicator.module.scss';
 import type { TrendIndicatorProps, TrendDirection } from './types';
 
@@ -47,10 +48,12 @@ export function TrendIndicator( {
 	showIcon = true,
 }: TrendIndicatorProps ) {
 	const ariaLabel = `${ DIRECTION_LABELS[ direction ] }: ${ value }`;
+	const standaloneScopeClass = useStandaloneScopeClass();
 
 	return (
 		<span
 			className={ clsx(
+				standaloneScopeClass,
 				styles[ 'trend-indicator' ],
 				styles[ `trend-indicator--${ direction }` ],
 				className

package/src/hooks/test/use-xychart-theme-provider-override.test.tsx

@@ -0,0 +1,28 @@
+import { renderHook } from '@testing-library/react';
+import { GlobalChartsProvider } from '../../providers/chart-context/global-charts-provider';
+import { ChartScopeContext } from '../../providers/chart-scope';
+import { useXYChartTheme } from '../use-xychart-theme';
+import type { ReactNode } from 'react';
+
+// A `theme` prop override reaches CSS-painted elements through the inline `--a8c-charts-*` var GlobalChartsProvider writes on its wrapper, and reaches visx (SVG presentation attributes) through `providerTheme`. Before the fix, `providerTheme` carried the override's literal directly, so an element-level `--a8c-charts-color-grid` override set inside the provider tree had no effect on the JS-resolved value — the two paths could disagree. After the fix, `providerTheme` carries the catalog pointer for an overridden role, so both paths resolve through the same CSS cascade and the nearer element wins.
+describe( 'useXYChartTheme resolves a theme prop override through the CSS cascade', () => {
+	it( "an element override set inside the provider tree beats the provider's theme prop literal", () => {
+		const nestedOverride = document.createElement( 'div' );
+		nestedOverride.style.setProperty( '--a8c-charts-color-grid', '#00ff00' );
+		document.body.appendChild( nestedOverride );
+
+		const wrapper = ( { children }: { children: ReactNode } ) => (
+			<GlobalChartsProvider theme={ { gridStyles: { stroke: 'rgb(255,0,0)' } } }>
+				<ChartScopeContext.Provider value={ nestedOverride }>
+					{ children }
+				</ChartScopeContext.Provider>
+			</GlobalChartsProvider>
+		);
+
+		const { result } = renderHook( () => useXYChartTheme( [] ), { wrapper } );
+
+		expect( result.current.gridStyles.stroke ).toBe( '#00ff00' );
+
+		document.body.removeChild( nestedOverride );
+	} );
+} );

package/src/hooks/test/use-xychart-theme-style-reads.test.tsx

@@ -1,35 +1,41 @@
 import { renderHook } from '@testing-library/react';
+import { ChartScopeContext } from '../../providers/chart-scope';
 import { useXYChartTheme } from '../use-xychart-theme';
 import type { SeriesData } from '../../types';
+import type { ReactNode } from 'react';
 
-// The theme resolves five catalog roles — background, grid, axis, tick and axis label. Each `getComputedStyle` call can force the browser to flush pending style, and this memo re-runs whenever `data` changes identity, so a dashboard mounting N charts pays the count below N times over.
+// The theme resolves five catalog roles — background, grid, axis, tick and axis label. Each `getComputedStyle` call can force the browser to flush pending style, and this memo re-runs only when the scope element attaches or a series colour changes, so a dashboard mounting N charts pays the count below N times over.
 const STABLE_DATA: SeriesData[] = [];
 
 describe( 'useXYChartTheme style reads', () => {
+	let scope: HTMLElement;
 	let getComputedStyleSpy: jest.SpyInstance;
 
 	beforeEach( () => {
-		document.documentElement.style.setProperty( '--a8c-charts-color-grid', '#00ff00' );
+		scope = document.createElement( 'div' );
+		scope.style.setProperty( '--a8c-charts-color-grid', '#00ff00' );
+		document.body.appendChild( scope );
 		getComputedStyleSpy = jest.spyOn( window, 'getComputedStyle' );
 	} );
 
 	afterEach( () => {
 		getComputedStyleSpy.mockRestore();
-		document.documentElement.style.removeProperty( '--a8c-charts-color-grid' );
-		document.documentElement.style.removeProperty( '--a8c-charts-color-background' );
-		document.documentElement.style.removeProperty( '--a8c-charts-color-axis' );
+		scope.remove();
 	} );
 
-	const renderTheme = ( data: SeriesData[] = STABLE_DATA ) =>
+	const renderWithScope = ( data: SeriesData[] = STABLE_DATA ) =>
 		renderHook( ( { series }: { series: SeriesData[] } ) => useXYChartTheme( series ), {
 			initialProps: { series: data },
+			wrapper: ( { children }: { children: ReactNode } ) => (
+				<ChartScopeContext.Provider value={ scope }>{ children }</ChartScopeContext.Provider>
+			),
 		} );
 
 	it( 'reads every role from one computed-style snapshot, not one per role', () => {
-		document.documentElement.style.setProperty( '--a8c-charts-color-background', '#111111' );
-		document.documentElement.style.setProperty( '--a8c-charts-color-axis', '#222222' );
+		scope.style.setProperty( '--a8c-charts-color-background', '#111111' );
+		scope.style.setProperty( '--a8c-charts-color-axis', '#222222' );
 
-		const { result } = renderTheme();
+		const { result } = renderWithScope();
 
 		expect( getComputedStyleSpy ).toHaveBeenCalledTimes( 1 );
 		expect( result.current.backgroundColor ).toBe( '#111111' );
@@ -38,7 +44,7 @@ describe( 'useXYChartTheme style reads', () => {
 	} );
 
 	it( 'does not re-read styles when the hook re-renders with the same inputs', () => {
-		const { rerender } = renderTheme();
+		const { rerender } = renderWithScope();
 
 		getComputedStyleSpy.mockClear();
 		rerender( { series: STABLE_DATA } );
@@ -48,7 +54,7 @@ describe( 'useXYChartTheme style reads', () => {
 
 	// A caller passing an inline array literal — `<LineChart data={ [ … ] } />` — hands the hook a new array identity on every render. The memo keys on the series strokes instead, so the theme is not rebuilt and no style is read. Keyed on `data` this cost one query per render, and before the roles shared a snapshot it cost five.
 	it( 'does not rebuild when the caller passes a fresh data array of the same strokes', () => {
-		const { rerender } = renderTheme( [] );
+		const { rerender } = renderWithScope( [] );
 
 		getComputedStyleSpy.mockClear();
 		rerender( { series: [] } );
@@ -59,7 +65,7 @@ describe( 'useXYChartTheme style reads', () => {
 	it( 'rebuilds when a series stroke actually changes', () => {
 		const withStroke = ( stroke: string ) =>
 			[ { label: 'A', options: { stroke }, data: [] } ] as unknown as SeriesData[];
-		const { result, rerender } = renderTheme( withStroke( 'rgba(0, 0, 0, 0.5)' ) );
+		const { result, rerender } = renderWithScope( withStroke( 'rgba(0, 0, 0, 0.5)' ) );
 
 		getComputedStyleSpy.mockClear();
 		rerender( { series: withStroke( 'rebeccapurple' ) } );
@@ -70,7 +76,7 @@ describe( 'useXYChartTheme style reads', () => {
 
 	// The memo key serialises the strokes rather than joining them, so a colour containing a comma or a space survives the round-trip intact.
 	it( 'keeps a stroke that contains separators intact', () => {
-		const { result } = renderTheme( [
+		const { result } = renderWithScope( [
 			{ label: 'A', options: { stroke: 'rgba(0, 0, 0, 0.5)' }, data: [] },
 			{ label: 'B', options: { stroke: 'var(--brand, #fff)' }, data: [] },
 		] as unknown as SeriesData[] );

package/src/hooks/test/use-xychart-theme.test.tsx

@@ -0,0 +1,25 @@
+import { renderHook } from '@testing-library/react';
+import { ChartScopeContext } from '../../providers/chart-scope';
+import { useXYChartTheme } from '../use-xychart-theme';
+import type { ReactNode } from 'react';
+
+describe( 'useXYChartTheme', () => {
+	it( 'resolves grid colour against the scope element, not the document root', () => {
+		document.documentElement.style.setProperty( '--a8c-charts-color-grid', '#ff0000' );
+
+		const scope = document.createElement( 'div' );
+		scope.style.setProperty( '--a8c-charts-color-grid', '#00ff00' );
+		document.body.appendChild( scope );
+
+		const wrapper = ( { children }: { children: ReactNode } ) => (
+			<ChartScopeContext.Provider value={ scope }>{ children }</ChartScopeContext.Provider>
+		);
+
+		const { result } = renderHook( () => useXYChartTheme( [] ), { wrapper } );
+
+		expect( result.current.gridStyles.stroke ).toBe( '#00ff00' );
+
+		document.documentElement.style.removeProperty( '--a8c-charts-color-grid' );
+		document.body.removeChild( scope );
+	} );
+} );

package/src/hooks/use-xychart-theme.ts

@@ -1,11 +1,13 @@
 import { buildChartTheme } from '@visx/xychart';
 import { useMemo } from 'react';
 import { useGlobalChartsTheme } from '../providers';
+import { useChartScopeElement } from '../providers/chart-scope';
 import { createCssVariableResolver } from '../utils';
 import type { SeriesData } from '../types';
 
 export const useXYChartTheme = ( data: SeriesData[] ) => {
 	const theme = useGlobalChartsTheme();
+	const scopeElement = useChartScopeElement();
 
 	// The only thing the theme takes from `data` is the series strokes, so key the memo on those rather than on the array's identity. A caller passing an inline literal — `<LineChart data={ [ … ] } />`, which the stories and several consumers do — otherwise rebuilds the whole theme on every render. Serialised rather than joined: a stroke can be `rgba(0, 0, 0, 0.5)` or `var(--brand, #fff)`, and any separator that reads naturally inside a colour cannot round-trip.
 	const seriesColorKey = JSON.stringify(
@@ -15,10 +17,10 @@ export const useXYChartTheme = ( data: SeriesData[] ) => {
 	);
 
 	return useMemo( () => {
-		// visx applies grid, axis, and tick-label colors as SVG presentation attributes, where CSS var() cannot resolve. Resolve them to concrete values before handing the theme to buildChartTheme.
+		// visx applies grid, axis, and tick-label colours as SVG presentation attributes, where CSS var() cannot resolve. Resolve the catalog token against the chart's own scope element — never :root — so this reads any override set inside the provider tree, the same one a CSS-painted element would inherit.
 		//
-		// One resolver per theme build, so the five roles below share a single getComputedStyle call rather than taking one each.
-		const resolve = createCssVariableResolver();
+		// One resolver per theme build, so the five roles below share a single getComputedStyle call rather than taking one each: this memo re-runs only when the scope element attaches or a series colour changes, which for a dashboard of charts is the difference between two style queries per chart and ten.
+		const resolve = createCssVariableResolver( scopeElement );
 		const resolveColor = ( value?: string ): string | undefined =>
 			value ? resolve( value ) ?? value : value;
 
@@ -45,5 +47,5 @@ export const useXYChartTheme = ( data: SeriesData[] ) => {
 				fill: resolveColor( theme.svgLabelSmall.fill ),
 			},
 		} );
-	}, [ theme, seriesColorKey ] );
+	}, [ theme, seriesColorKey, scopeElement ] );
 };