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.tsxnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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';