fix(tokens): show gradient value and hex in color token docs (#1931)

* fix(tokens): show gradient value and hex in color token docs

The Tokens/Color Storybook docs read getComputedStyle().backgroundColor,
which is rgba(0, 0, 0, 0) for gradient tokens since they are painted via
background-image. Read background-image for gradients and display the
gradient definition instead of the meaningless transparent value.

Also derive and show a hex value for solid color tokens, keeping the
rgba string alongside it for backwards compatibility.

* test(tokens): cover color token value rendering

Extract the token value formatting into a testable colorTokens module and
add unit tests verifying that solid colors show both hex and the original
rgba (kept for backwards compatibility) and that gradient tokens show the
gradient definition instead of the transparent rgba(0, 0, 0, 0) fallback.

Anchor the rgb->hex regex so it only parses bare color strings.

* feat(tokens): split color token docs into Hex and rgba columns

Show the hex and rgba values in separate columns in the Tokens/Color
Storybook docs. Gradient tokens show the gradient definition in the rgba
column and a dash in the hex column. Add an empty changeset since this is
a Storybook-only change with no published package impact.

* fix(tokens): show rgba (with alpha) in color token docs

Address review feedback: the rgba column displayed rgb() for opaque colors
since getComputedStyle omits the alpha channel. Normalize solid color values
to the rgba() form with an explicit alpha so the column matches its label.

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>

Author: hsadhvani

.changeset/tangy-aliens-hammer.md

@@ -0,0 +1,2 @@
+---
+---

packages/tokens/__tests__/colorTokens.spec.tsx

@@ -0,0 +1,86 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { getTokenHex, getTokenValue, rgbToHex, TokenCode, toRgba } from '../stories/colorTokens';
+
+const GRADIENT = 'linear-gradient(136deg, rgb(61, 214, 245) 22.68%, rgb(64, 91, 255) 127.6%)';
+
+describe('rgbToHex', () => {
+	it('converts an opaque rgb() string to 6-digit hex', () => {
+		expect(rgbToHex('rgb(61, 214, 245)')).toBe('#3DD6F5');
+	});
+
+	it('converts a translucent rgba() string to 8-digit hex', () => {
+		expect(rgbToHex('rgba(0, 0, 0, 0.5)')).toBe('#00000080');
+	});
+
+	it('omits the alpha channel when fully opaque', () => {
+		expect(rgbToHex('rgba(255, 53, 162, 1)')).toBe('#FF35A2');
+	});
+
+	it('supports the space/slash-separated syntax', () => {
+		expect(rgbToHex('rgb(61 214 245 / 0.5)')).toBe('#3DD6F580');
+	});
+
+	it('returns null for non-color values such as gradients', () => {
+		expect(rgbToHex(GRADIENT)).toBeNull();
+	});
+});
+
+describe('getTokenHex', () => {
+	it('returns the hex for a solid color', () => {
+		expect(getTokenHex({ color: 'rgb(61, 214, 245)', image: 'none' })).toBe('#3DD6F5');
+	});
+
+	it('returns null for a gradient token', () => {
+		expect(getTokenHex({ color: 'rgba(0, 0, 0, 0)', image: GRADIENT })).toBeNull();
+	});
+
+	it('returns null when the value is not yet computed', () => {
+		expect(getTokenHex(undefined)).toBeNull();
+	});
+});
+
+describe('toRgba', () => {
+	it('adds an explicit alpha to opaque rgb() values', () => {
+		expect(toRgba('rgb(61, 214, 245)')).toBe('rgba(61, 214, 245, 1)');
+	});
+
+	it('preserves an existing alpha channel', () => {
+		expect(toRgba('rgba(0, 0, 0, 0.5)')).toBe('rgba(0, 0, 0, 0.5)');
+	});
+
+	it('leaves non-color values untouched', () => {
+		expect(toRgba(GRADIENT)).toBe(GRADIENT);
+	});
+});
+
+describe('getTokenValue', () => {
+	it('returns the rgba string for a solid color (kept for backwards compatibility)', () => {
+		expect(getTokenValue({ color: 'rgb(61, 214, 245)', image: 'none' })).toBe(
+			'rgba(61, 214, 245, 1)',
+		);
+	});
+
+	it('returns the gradient definition instead of the transparent fallback', () => {
+		expect(getTokenValue({ color: 'rgba(0, 0, 0, 0)', image: GRADIENT })).toBe(GRADIENT);
+	});
+
+	it('returns null when the value is not yet computed', () => {
+		expect(getTokenValue(undefined)).toBeNull();
+	});
+});
+
+describe('TokenCode', () => {
+	it('renders its content', () => {
+		render(<TokenCode>#3DD6F5</TokenCode>);
+
+		expect(screen.getByText('#3DD6F5')).toBeInTheDocument();
+	});
+
+	it('renders nothing when there is no content', () => {
+		const { container } = render(<TokenCode>{null}</TokenCode>);
+
+		expect(container).toBeEmptyDOMElement();
+	});
+});

packages/tokens/stories/color.stories.tsx

@@ -4,6 +4,7 @@ import { useEffect, useRef, useState } from 'react';
 import { Button } from '../../components/src/Button';
 import { ToastRegion, toastQueue } from '../../components/src/Toast';
 import { Tooltip, TooltipTrigger } from '../../components/src/Tooltip';
+import { type ComputedValue, getTokenHex, getTokenValue, TokenCode } from './colorTokens';
 
 export default {
 	title: 'Tokens/Color',
@@ -35,11 +36,18 @@ const flatten = (obj: Record<string, unknown>) => {
 
 const TokenTable = ({ tokens }: { tokens: Record<string, string> }) => {
 	const itemEls = useRef<Record<string, HTMLDivElement | null>>({});
-	const [colors, setColors] = useState<Record<string, string>>({});
+	const [colors, setColors] = useState<Record<string, ComputedValue>>({});
 
 	useEffect(() => {
 		for (const [key, value] of Object.entries(itemEls.current)) {
-			const item = { [key]: getComputedStyle(value as Element).backgroundColor };
+			if (!value) {
+				continue;
+			}
+
+			const styles = getComputedStyle(value);
+			const item = {
+				[key]: { color: styles.backgroundColor, image: styles.backgroundImage },
+			};
 			setColors((c) => ({ ...c, ...item }));
 		}
 	}, []);
@@ -51,11 +59,15 @@ const TokenTable = ({ tokens }: { tokens: Record<string, string> }) => {
 					<tr>
 						<th />
 						<th style={{ textAlign: 'left' }}>Name</th>
-						<th style={{ textAlign: 'left' }}>Value</th>
+						<th style={{ textAlign: 'left' }}>Hex</th>
+						<th style={{ textAlign: 'left' }}>rgba</th>
 					</tr>
 				</thead>
 				<tbody>
 					{Object.entries(tokens).map(([key, value]) => {
+						const computed = colors[key];
+						const hex = getTokenHex(computed);
+
 						return (
 							<tr key={key}>
 								<td>
@@ -88,7 +100,14 @@ const TokenTable = ({ tokens }: { tokens: Record<string, string> }) => {
 										<Tooltip placement="bottom">Copy to clipboard</Tooltip>
 									</TooltipTrigger>
 								</td>
-								<td>{colors[key]}</td>
+								<td>
+									{/* Gradients have no single hex value. */}
+									<TokenCode>{hex ?? (computed ? '—' : null)}</TokenCode>
+								</td>
+								<td>
+									{/* rgba is kept for backwards compatibility now that hex is shown. */}
+									<TokenCode muted={Boolean(hex)}>{getTokenValue(computed)}</TokenCode>
+								</td>
 							</tr>
 						);
 					})}

packages/tokens/stories/colorTokens.tsx

@@ -0,0 +1,102 @@
+import type { ReactNode } from 'react';
+
+export type ComputedValue = { color: string; image: string };
+
+// Converts a computed `rgb()`/`rgba()` string to an uppercase hex string.
+// Handles both comma-separated (`rgb(61, 214, 245)`) and space/slash-separated
+// (`rgb(61 214 245 / 0.5)`) syntaxes returned by `getComputedStyle`. Alpha is
+// appended as an 8-digit hex only when the color is not fully opaque.
+export const rgbToHex = (rgb: string): string | null => {
+	const match = rgb.trim().match(/^rgba?\(([^)]+)\)$/);
+
+	if (!match) {
+		return null;
+	}
+
+	const parts = match[1]
+		.split(/[\s,/]+/)
+		.map((part) => part.trim())
+		.filter(Boolean);
+	const [r, g, b] = parts.map((part) => Number.parseFloat(part));
+
+	if ([r, g, b].some((channel) => Number.isNaN(channel))) {
+		return null;
+	}
+
+	const toHex = (channel: number) => Math.round(channel).toString(16).padStart(2, '0');
+	let hex = `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+
+	const alpha = parts[3] !== undefined ? Number.parseFloat(parts[3]) : 1;
+
+	if (!Number.isNaN(alpha) && alpha < 1) {
+		hex += toHex(alpha * 255);
+	}
+
+	return hex.toUpperCase();
+};
+
+const isGradient = (computed: ComputedValue) =>
+	Boolean(computed.image && computed.image !== 'none');
+
+// Normalizes a computed `rgb()`/`rgba()` string to the `rgba()` form. Opaque
+// colors come back from `getComputedStyle` as `rgb(...)`, so add an explicit
+// alpha of `1` to keep the displayed value consistently rgba.
+export const toRgba = (color: string): string => {
+	const match = color.trim().match(/^rgba?\(([^)]+)\)$/);
+
+	if (!match) {
+		return color;
+	}
+
+	const parts = match[1]
+		.split(/[\s,/]+/)
+		.map((part) => part.trim())
+		.filter(Boolean);
+
+	if (parts.length < 3) {
+		return color;
+	}
+
+	const [r, g, b] = parts;
+	const alpha = parts[3] ?? '1';
+
+	return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+};
+
+// Hex value for solid color tokens. Gradient tokens have no single hex value.
+export const getTokenHex = (computed?: ComputedValue): string | null => {
+	if (!computed || isGradient(computed)) {
+		return null;
+	}
+
+	return rgbToHex(computed.color);
+};
+
+// The raw value, kept for backwards compatibility: the gradient definition for
+// gradient tokens, otherwise the computed rgba string. Gradients are painted via
+// `background-image`, so their `background-color` is the meaningless transparent
+// default (`rgba(0, 0, 0, 0)`), which we intentionally avoid surfacing.
+export const getTokenValue = (computed?: ComputedValue): string | null => {
+	if (!computed) {
+		return null;
+	}
+
+	return isGradient(computed) ? computed.image : toRgba(computed.color);
+};
+
+export const TokenCode = ({ children, muted }: { children: ReactNode; muted?: boolean }) => {
+	if (children == null) {
+		return null;
+	}
+
+	return (
+		<span
+			style={{
+				font: 'var(--lp-text-code-1-regular)',
+				...(muted ? { color: 'var(--lp-color-text-ui-secondary)' } : {}),
+			}}
+		>
+			{children}
+		</span>
+	);
+};