Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(lab): XDSChartColors — palette accessor for data visualization (#1388)

Cindy Zhangbaed9b061699
diff --git a/apps/storybook/stories/ChartColors.stories.tsx b/apps/storybook/stories/ChartColors.stories.tsx
new file mode 100644
index 0000000000..ee2a92dde6
--- /dev/null
+++ b/apps/storybook/stories/ChartColors.stories.tsx
@@ -0,0 +1,123 @@
+import type {Meta, StoryObj} from '@storybook/react';
+import {XDSChartColors, type SequentialHue} from '@xds/lab';
+import {XDSStack, XDSText} from '@xds/core';
+import {XDSHeading} from '@xds/core/Text';
+
+const meta: Meta = {
+ title: 'Lab/XDSChartColors',
+};
+
+export default meta;
+
+function Swatches({colors, label}: {colors: string[]; label: string}) {
+ return (
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="label">{label}</XDSText>
+ <XDSStack direction="horizontal" gap={0.5}>
+ {colors.map((color, i) => (
+ <div
+ key={i}
+ title={color}
+ style={{
+ width: 48,
+ height: 32,
+ borderRadius: 4,
+ backgroundColor: color,
+ }}
+ />
+ ))}
+ </XDSStack>
+ </XDSStack>
+ );
+}
+
+export const Categorical: StoryObj = {
+ render: () => (
+ <XDSStack direction="vertical" gap={6}>
+ <XDSHeading level={3}>Categorical Palettes</XDSHeading>
+ <XDSStack direction="vertical" gap={4}>
+ <Swatches
+ colors={XDSChartColors.categorical(5)}
+ label="categorical(5)"
+ />
+ <Swatches
+ colors={XDSChartColors.categorical(10)}
+ label="categorical(10)"
+ />
+ </XDSStack>
+ </XDSStack>
+ ),
+};
+
+export const Sequential: StoryObj = {
+ render: () => {
+ const hues: SequentialHue[] = [
+ 'blue',
+ 'shamrock',
+ 'orange',
+ 'pink',
+ 'purple',
+ 'red',
+ 'teal',
+ 'yellow',
+ 'gray',
+ ];
+ return (
+ <XDSStack direction="vertical" gap={6}>
+ <XDSHeading level={3}>Sequential Ramps</XDSHeading>
+ <XDSStack direction="vertical" gap={4}>
+ {hues.map(hue => (
+ <Swatches
+ key={hue}
+ colors={XDSChartColors.sequential[hue](5)}
+ label={`sequential.${hue}(5)`}
+ />
+ ))}
+ </XDSStack>
+ </XDSStack>
+ );
+ },
+};
+
+export const Diverging: StoryObj = {
+ render: () => (
+ <XDSStack direction="vertical" gap={6}>
+ <XDSHeading level={3}>Diverging Palettes</XDSHeading>
+ <XDSStack direction="vertical" gap={4}>
+ <Swatches
+ colors={XDSChartColors.diverging.positiveNegative(5)}
+ label="diverging.positiveNegative(5)"
+ />
+ <Swatches
+ colors={XDSChartColors.diverging.positiveNegative(11)}
+ label="diverging.positiveNegative(11)"
+ />
+ <Swatches
+ colors={XDSChartColors.diverging.coldHot(7)}
+ label="diverging.coldHot(7)"
+ />
+ <Swatches
+ colors={XDSChartColors.diverging.custom('blue', 'orange', 7)}
+ label="diverging.custom('blue', 'orange', 7)"
+ />
+ </XDSStack>
+ </XDSStack>
+ ),
+};
+
+export const Semantic: StoryObj = {
+ render: () => (
+ <XDSStack direction="vertical" gap={6}>
+ <XDSHeading level={3}>Semantic Colors</XDSHeading>
+ <Swatches
+ colors={[
+ XDSChartColors.semantic.positive,
+ XDSChartColors.semantic.negative,
+ XDSChartColors.semantic.warning,
+ XDSChartColors.semantic.neutral,
+ ]}
+ label="positive, negative, warning, neutral"
+ />
+ </XDSStack>
+ ),
+};
diff --git a/packages/core/src/theme/index.ts b/packages/core/src/theme/index.ts
index b9e80b563d..f742132dec 100644
--- a/packages/core/src/theme/index.ts
+++ b/packages/core/src/theme/index.ts
@@ -38,16 +38,20 @@ export type {
XDSStyleOverrides,
} from './defineTheme';
-export type {SyntaxTokenName, DomainTokenName} from './domainTokens';
+export type {
+ SyntaxTokenName,
+ DomainTokenName,
+ DataTokenName,
+} from './domainTokens';
-export {syntaxTokenDefaults, domainTokenDefaults} from './domainTokens';
+export {
+ syntaxTokenDefaults,
+ domainTokenDefaults,
+ dataTokenDefaults,
+} from './domainTokens';
// Syntax theme API
-export {
- defineSyntaxTheme,
- syntaxThemeStyle,
- syntaxThemeToCSS,
-} from './syntax';
+export {defineSyntaxTheme, syntaxThemeStyle, syntaxThemeToCSS} from './syntax';
export type {
SyntaxTheme,
SyntaxThemeInput,
diff --git a/packages/lab/src/ChartColors/XDSChartColors.test.ts b/packages/lab/src/ChartColors/XDSChartColors.test.ts
new file mode 100644
index 0000000000..8a1a60b327
--- /dev/null
+++ b/packages/lab/src/ChartColors/XDSChartColors.test.ts
@@ -0,0 +1,126 @@
+import {describe, it, expect} from 'vitest';
+import {XDSChartColors} from './XDSChartColors';
+
+describe('XDSChartColors', () => {
+ describe('categorical', () => {
+ it('returns empty for n=0', () => {
+ expect(XDSChartColors.categorical(0)).toEqual([]);
+ });
+
+ it('returns curated colors for small n', () => {
+ const colors = XDSChartColors.categorical(3);
+ expect(colors).toHaveLength(3);
+ expect(colors[0]).toBe('#0171E3');
+ expect(colors[1]).toBe('#EB6E00');
+ expect(colors[2]).toBe('#6B1EFD');
+ });
+
+ it('returns all 10 curated colors', () => {
+ const colors = XDSChartColors.categorical(10);
+ expect(colors).toHaveLength(10);
+ colors.forEach(c => expect(c).toMatch(/^#[0-9A-Fa-f]{6}$/));
+ });
+
+ it('caps at 10', () => {
+ expect(XDSChartColors.categorical(20)).toHaveLength(10);
+ });
+ });
+
+ describe('sequential', () => {
+ it('returns single midpoint for n=1', () => {
+ const colors = XDSChartColors.sequential.blue(1);
+ expect(colors).toHaveLength(1);
+ expect(colors[0]).toBe('#2694FE'); // blue-3
+ });
+
+ it('returns 2-stop ramp (darkest + lightest)', () => {
+ const colors = XDSChartColors.sequential.blue(2);
+ expect(colors).toHaveLength(2);
+ expect(colors[0]).toBe('#02165E');
+ expect(colors[1]).toBe('#DBECFF');
+ });
+
+ it('returns full 5-step ramp', () => {
+ const colors = XDSChartColors.sequential.blue(5);
+ expect(colors).toHaveLength(5);
+ expect(colors[0]).toBe('#02165E');
+ expect(colors[4]).toBe('#DBECFF');
+ });
+
+ it('caps at 5', () => {
+ expect(XDSChartColors.sequential.blue(10)).toHaveLength(5);
+ });
+
+ it('all hues are available', () => {
+ const hues = [
+ 'blue',
+ 'shamrock',
+ 'orange',
+ 'pink',
+ 'purple',
+ 'red',
+ 'teal',
+ 'yellow',
+ 'gray',
+ ] as const;
+ hues.forEach(hue => {
+ const colors = XDSChartColors.sequential[hue](3);
+ expect(colors).toHaveLength(3);
+ colors.forEach(c => expect(c).toMatch(/^#[0-9A-Fa-f]{6}$/));
+ });
+ });
+ });
+
+ describe('diverging', () => {
+ it('positiveNegative returns correct size', () => {
+ const colors = XDSChartColors.diverging.positiveNegative(5);
+ expect(colors).toHaveLength(5);
+ // Center is gray-1
+ expect(colors[2]).toBe('#F1F4F7');
+ });
+
+ it('coldHot returns correct size', () => {
+ const colors = XDSChartColors.diverging.coldHot(7);
+ expect(colors).toHaveLength(7);
+ expect(colors[3]).toBe('#F1F4F7');
+ });
+
+ it('custom allows different hues', () => {
+ const colors = XDSChartColors.diverging.custom('blue', 'orange', 5);
+ expect(colors).toHaveLength(5);
+ expect(colors[2]).toBe('#F1F4F7');
+ });
+
+ it('custom allows custom midpoint', () => {
+ const colors = XDSChartColors.diverging.custom(
+ 'blue',
+ 'orange',
+ 5,
+ '#ffffff',
+ );
+ expect(colors).toHaveLength(5);
+ expect(colors[2]).toBe('#ffffff');
+ });
+
+ it('returns midpoint for n=1', () => {
+ const colors = XDSChartColors.diverging.positiveNegative(1);
+ expect(colors).toEqual(['#F1F4F7']);
+ });
+
+ it('even n has no center', () => {
+ const colors = XDSChartColors.diverging.positiveNegative(4);
+ expect(colors).toHaveLength(4);
+ // No gray-1 in the middle
+ expect(colors).not.toContain('#F1F4F7');
+ });
+ });
+
+ describe('semantic', () => {
+ it('has all four semantic colors', () => {
+ expect(XDSChartColors.semantic.positive).toMatch(/^#[0-9A-Fa-f]{6}$/);
+ expect(XDSChartColors.semantic.negative).toMatch(/^#[0-9A-Fa-f]{6}$/);
+ expect(XDSChartColors.semantic.warning).toMatch(/^#[0-9A-Fa-f]{6}$/);
+ expect(XDSChartColors.semantic.neutral).toMatch(/^#[0-9A-Fa-f]{6}$/);
+ });
+ });
+});
diff --git a/packages/lab/src/ChartColors/XDSChartColors.ts b/packages/lab/src/ChartColors/XDSChartColors.ts
new file mode 100644
index 0000000000..c178f69494
--- /dev/null
+++ b/packages/lab/src/ChartColors/XDSChartColors.ts
@@ -0,0 +1,224 @@
+/**
+ * @file XDSChartColors.ts
+ * @input dataTokenDefaults from core theme tokens
+ * @output XDSChartColors — palette accessor for categorical, sequential, and diverging colors
+ * @position Lab utility; consumed by chart components and any data-visualization surface
+ *
+ * Provides a typed, discoverable API over the raw --color-data-* CSS custom properties.
+ * Returns curated token values from the XDS data visualization palette.
+ */
+
+import {dataTokenDefaults} from '@xds/core/theme';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/** Hue names available in the sequential ramps */
+export type SequentialHue =
+ | 'blue'
+ | 'shamrock'
+ | 'orange'
+ | 'pink'
+ | 'purple'
+ | 'red'
+ | 'teal'
+ | 'yellow'
+ | 'gray';
+
+// =============================================================================
+// Internals
+// =============================================================================
+
+/**
+ * Resolve a token default to its light-mode hex value.
+ * dataTokenDefaults stores values as 'light-dark(#hex, #hex)'.
+ */
+function resolve(token: string): string {
+ const match = token.match(/#[0-9A-Fa-f]{6}/);
+ return match ? match[0] : token;
+}
+
+/** The 10 curated categorical colors in token order */
+const CATEGORICAL = [
+ 'blue',
+ 'orange',
+ 'purple',
+ 'green',
+ 'pink',
+ 'cyan',
+ 'red',
+ 'teal',
+ 'brown',
+ 'indigo',
+].map(name =>
+ resolve(
+ dataTokenDefaults[
+ `--color-data-categorical-${name}` as keyof typeof dataTokenDefaults
+ ],
+ ),
+);
+
+const SEQUENTIAL_HUES: SequentialHue[] = [
+ 'blue',
+ 'shamrock',
+ 'orange',
+ 'pink',
+ 'purple',
+ 'red',
+ 'teal',
+ 'yellow',
+ 'gray',
+];
+
+/** Default diverging midpoint — gray-1 per design specs */
+const GRAY_1 = resolve(dataTokenDefaults['--color-data-gray-1']);
+
+/** 5-step ramp for a hue: darkest (5) → lightest (1) */
+function ramp(hue: SequentialHue): string[] {
+ return [5, 4, 3, 2, 1].map(step =>
+ resolve(
+ dataTokenDefaults[
+ `--color-data-${hue}-${step}` as keyof typeof dataTokenDefaults
+ ],
+ ),
+ );
+}
+
+/** Pick n evenly spaced items from a 5-stop ramp */
+function pickFromRamp(stops: string[], n: number): string[] {
+ if (n >= 5) return stops;
+ if (n === 1) return [stops[2]]; // midpoint
+ return Array.from(
+ {length: n},
+ (_, i) => stops[Math.round((i * 4) / (n - 1))],
+ );
+}
+
+/**
+ * Build a diverging palette from two hues and a midpoint.
+ * Picks stops from each hue's ramp (darkest → lightest) with midpoint between.
+ * Max meaningful size is 11 (5 negative + midpoint + 5 positive).
+ */
+function buildDiverging(
+ negativeHue: SequentialHue,
+ positiveHue: SequentialHue,
+ n: number,
+ midpoint: string = GRAY_1,
+): string[] {
+ if (n <= 0) return [];
+ if (n === 1) return [midpoint];
+
+ const neg = ramp(negativeHue);
+ const pos = ramp(positiveHue);
+
+ const half = Math.floor(n / 2);
+ const hasCenter = n % 2 === 1;
+
+ const negSide = pickFromRamp(neg, half);
+ const posSide = pickFromRamp(pos, half).reverse(); // lightest → darkest
+
+ if (hasCenter) {
+ return [...negSide, midpoint, ...posSide];
+ }
+ return [...negSide, ...posSide];
+}
+
+// =============================================================================
+// Public API
+// =============================================================================
+
+/**
+ * XDS Chart Colors — typed palette accessor for data visualization.
+ *
+ * All methods return resolved hex strings usable in SVG fill/stroke,
+ * CSS, canvas, or any rendering context.
+ *
+ * @example
+ * ```
+ * XDSChartColors.categorical(5)
+ * XDSChartColors.sequential.blue(3)
+ * XDSChartColors.diverging.positiveNegative(5)
+ * XDSChartColors.diverging.coldHot(7)
+ * XDSChartColors.diverging.custom('blue', 'orange', 7)
+ * XDSChartColors.semantic.positive
+ * ```
+ */
+export const XDSChartColors = {
+ /**
+ * Categorical palette — distinct colors for unrelated series.
+ * Returns up to 10 curated colors from the XDS data token palette.
+ */
+ categorical(n: number): string[] {
+ if (n <= 0) return [];
+ return CATEGORICAL.slice(0, Math.min(n, CATEGORICAL.length));
+ },
+
+ /**
+ * Sequential ramps — ordered colors within a single hue.
+ * Returns up to 5 curated stops (darkest → lightest).
+ */
+ sequential: Object.fromEntries(
+ SEQUENTIAL_HUES.map(hue => [
+ hue,
+ (n: number): string[] => {
+ if (n <= 0) return [];
+ return pickFromRamp(ramp(hue), n);
+ },
+ ]),
+ ) as Record<SequentialHue, (n: number) => string[]>,
+
+ /**
+ * Diverging palettes — two sequential hues meeting at a neutral midpoint.
+ *
+ * Presets match design specs (gray-1 midpoint):
+ * - `positiveNegative` — shamrock → gray-1 → red
+ * - `coldHot` — blue → gray-1 → red
+ *
+ * Use `custom` for any hue combination or a custom midpoint.
+ */
+ diverging: {
+ /** shamrock → gray-1 → red (gain/loss, positive/negative) */
+ positiveNegative(n: number): string[] {
+ return buildDiverging('shamrock', 'red', n);
+ },
+
+ /** blue → gray-1 → red (cold/hot, low/high) */
+ coldHot(n: number): string[] {
+ return buildDiverging('blue', 'red', n);
+ },
+
+ /**
+ * Custom diverging palette from any two hues.
+ * Default midpoint is gray-1; pass a hex string to override.
+ */
+ custom(
+ negativeHue: SequentialHue,
+ positiveHue: SequentialHue,
+ n: number,
+ midpoint?: string,
+ ): string[] {
+ return buildDiverging(negativeHue, positiveHue, n, midpoint);
+ },
+ },
+
+ /** Semantic colors — fixed-meaning data values */
+ semantic: {
+ positive: resolve(
+ dataTokenDefaults[
+ '--color-data-categorical-green' as keyof typeof dataTokenDefaults
+ ],
+ ),
+ negative: resolve(
+ dataTokenDefaults[
+ '--color-data-categorical-red' as keyof typeof dataTokenDefaults
+ ],
+ ),
+ warning: resolve(
+ dataTokenDefaults[
+ '--color-data-categorical-orange' as keyof typeof dataTokenDefaults
+ ],
+ ),
+ neutral: resolve(dataTokenDefaults['--color-data-neutral']),
+ },
+} as const;
diff --git a/packages/lab/src/ChartColors/index.ts b/packages/lab/src/ChartColors/index.ts
new file mode 100644
index 0000000000..cc3ee8f542
--- /dev/null
+++ b/packages/lab/src/ChartColors/index.ts
@@ -0,0 +1 @@
+export {XDSChartColors, type SequentialHue} from './XDSChartColors';
diff --git a/packages/lab/src/index.ts b/packages/lab/src/index.ts
index e474a455e5..128381ec58 100644
--- a/packages/lab/src/index.ts
+++ b/packages/lab/src/index.ts
@@ -54,3 +54,6 @@ export {
lockIcon,
starterIcons,
} from './SVGIcon';
+
+// Chart colors — palette accessor for data visualization
+export {XDSChartColors, type SequentialHue} from './ChartColors';