Skip to content

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

TypeScript

feat(lab): CSS-variable-driven SVG icon system (#1269)

Cindy Zhang44ca6a282748
diff --git a/apps/storybook/stories/SVGIcon.stories.tsx b/apps/storybook/stories/SVGIcon.stories.tsx
new file mode 100644
index 0000000000..409655f29d
--- /dev/null
+++ b/apps/storybook/stories/SVGIcon.stories.tsx
@@ -0,0 +1,254 @@
+import type {Meta, StoryObj} from '@storybook/react';
+import {Fragment} from 'react';
+import {
+ XDSSVGIcon,
+ type SVGIconVariation,
+ type SVGIconSize,
+ type SVGIconColor,
+ starterIcons,
+ bellIcon,
+ settingsIcon,
+ homeIcon,
+ menuIcon,
+} from '@xds/lab';
+import {XDSStack, XDSText, XDSDivider} from '@xds/core';
+
+const meta: Meta<typeof XDSSVGIcon> = {
+ title: 'Lab/XDSSVGIcon',
+ component: XDSSVGIcon,
+ argTypes: {
+ variation: {
+ control: 'select',
+ options: [
+ 'linear',
+ 'bold',
+ 'twotone',
+ 'bulk',
+ 'broken',
+ ] as SVGIconVariation[],
+ },
+ size: {
+ control: 'select',
+ options: ['xsm', 'sm', 'md', 'lg'] as SVGIconSize[],
+ },
+ color: {
+ control: 'select',
+ options: [
+ 'primary',
+ 'secondary',
+ 'disabled',
+ 'accent',
+ 'positive',
+ 'negative',
+ 'warning',
+ 'inherit',
+ ] as SVGIconColor[],
+ },
+ strokeWidth: {control: {type: 'range', min: 0.5, max: 4, step: 0.25}},
+ },
+};
+
+export default meta;
+type Story = StoryObj<typeof XDSSVGIcon>;
+
+// =============================================================================
+// Basic
+// =============================================================================
+
+export const Default: Story = {
+ args: {
+ icon: bellIcon,
+ variation: 'linear',
+ size: 'lg',
+ color: 'primary',
+ },
+};
+
+// =============================================================================
+// All Icons x All Variations
+// =============================================================================
+
+const VARIATIONS: SVGIconVariation[] = [
+ 'linear',
+ 'bold',
+ 'twotone',
+ 'bulk',
+ 'broken',
+];
+
+export const VariationMatrix: Story = {
+ render: () => (
+ <XDSStack direction="vertical" gap={3}>
+ <XDSText variant="heading-3">Variation Matrix</XDSText>
+ <XDSText variant="body-sm" color="secondary">
+ Same SVG paths, different visual treatments via CSS custom properties.
+ Note how stroke-role elements (menu lines, calendar pegs, bell clapper)
+ stay as strokes even in bold/bulk mode.
+ </XDSText>
+ <div
+ style={{
+ display: 'grid',
+ gridTemplateColumns: `120px repeat(${VARIATIONS.length}, 1fr)`,
+ gap: 12,
+ alignItems: 'center',
+ }}>
+ {/* Header row */}
+ <div />
+ {VARIATIONS.map(v => (
+ <XDSText
+ key={v}
+ variant="label-sm"
+ color="secondary"
+ style={{textAlign: 'center'}}>
+ {v}
+ </XDSText>
+ ))}
+
+ {/* Icon rows */}
+ {starterIcons.map(icon => (
+ <Fragment key={icon.name}>
+ <XDSText variant="label-sm">{icon.name}</XDSText>
+ {VARIATIONS.map(v => (
+ <div
+ key={`${icon.name}-${v}`}
+ style={{display: 'flex', justifyContent: 'center'}}>
+ <XDSSVGIcon icon={icon} variation={v} size="lg" />
+ </div>
+ ))}
+ </Fragment>
+ ))}
+ </div>
+ </XDSStack>
+ ),
+};
+
+// =============================================================================
+// Role Behavior Demo
+// =============================================================================
+
+export const RoleBehavior: Story = {
+ render: () => (
+ <XDSStack direction="vertical" gap={3}>
+ <XDSText variant="heading-3">Path Roles: Fill vs Stroke</XDSText>
+ <XDSText variant="body-sm" color="secondary">
+ Stroke-role elements always stay as strokes. Fill-role elements switch
+ between stroke (linear) and fill (bold). Compare Menu (all stroke-role)
+ vs Home (fill-role body + fill-role door with mask knockout).
+ </XDSText>
+
+ <XDSStack direction="vertical" gap={2}>
+ <XDSText variant="label-sm" color="secondary">
+ Menu — all stroke-role (lines never become fills)
+ </XDSText>
+ <XDSStack direction="row" gap={3}>
+ {VARIATIONS.map(v => (
+ <XDSStack direction="vertical" key={v} gap={0.5} hAlign="center">
+ <XDSSVGIcon icon={menuIcon} variation={v} size="lg" />
+ <XDSText variant="label-sm" color="secondary">
+ {v}
+ </XDSText>
+ </XDSStack>
+ ))}
+ </XDSStack>
+
+ <XDSDivider />
+
+ <XDSText variant="label-sm" color="secondary">
+ Home — fill-role body + door (mask gap in bold)
+ </XDSText>
+ <XDSStack direction="row" gap={3}>
+ {VARIATIONS.map(v => (
+ <XDSStack direction="vertical" key={v} gap={0.5} hAlign="center">
+ <XDSSVGIcon icon={homeIcon} variation={v} size="lg" />
+ <XDSText variant="label-sm" color="secondary">
+ {v}
+ </XDSText>
+ </XDSStack>
+ ))}
+ </XDSStack>
+
+ <XDSDivider />
+
+ <XDSText variant="label-sm" color="secondary">
+ Settings — fill-role gear + circle (mask gap in bold)
+ </XDSText>
+ <XDSStack direction="row" gap={3}>
+ {VARIATIONS.map(v => (
+ <XDSStack direction="vertical" key={v} gap={0.5} hAlign="center">
+ <XDSSVGIcon icon={settingsIcon} variation={v} size="lg" />
+ <XDSText variant="label-sm" color="secondary">
+ {v}
+ </XDSText>
+ </XDSStack>
+ ))}
+ </XDSStack>
+ </XDSStack>
+ </XDSStack>
+ ),
+};
+
+// =============================================================================
+// Size Scale
+// =============================================================================
+
+const SIZES: SVGIconSize[] = ['xsm', 'sm', 'md', 'lg'];
+
+export const SizeScale: Story = {
+ render: () => (
+ <XDSStack direction="vertical" gap={2}>
+ <XDSText variant="heading-3">
+ Size Scale with Optical Compensation
+ </XDSText>
+ <XDSText variant="body-sm" color="secondary">
+ Stroke width auto-adjusts at smaller sizes for legibility.
+ </XDSText>
+ <XDSStack direction="row" gap={3} vAlign="end">
+ {SIZES.map(size => (
+ <XDSStack direction="vertical" key={size} gap={1} hAlign="center">
+ <XDSSVGIcon icon={settingsIcon} variation="linear" size={size} />
+ <XDSText variant="label-sm" color="secondary">
+ {size}
+ </XDSText>
+ </XDSStack>
+ ))}
+ </XDSStack>
+ </XDSStack>
+ ),
+};
+
+// =============================================================================
+// Color Palette
+// =============================================================================
+
+const COLORS: SVGIconColor[] = [
+ 'primary',
+ 'secondary',
+ 'disabled',
+ 'accent',
+ 'positive',
+ 'negative',
+ 'warning',
+];
+
+export const Colors: Story = {
+ render: () => (
+ <XDSStack direction="vertical" gap={2}>
+ <XDSText variant="heading-3">Semantic Colors</XDSText>
+ <XDSStack direction="row" gap={3}>
+ {COLORS.map(c => (
+ <XDSStack direction="vertical" key={c} gap={1} hAlign="center">
+ <XDSSVGIcon
+ icon={bellIcon}
+ variation="linear"
+ size="lg"
+ color={c}
+ />
+ <XDSText variant="label-sm" color="secondary">
+ {c}
+ </XDSText>
+ </XDSStack>
+ ))}
+ </XDSStack>
+ </XDSStack>
+ ),
+};
diff --git a/packages/lab/src/SVGIcon/XDSSVGIcon.tsx b/packages/lab/src/SVGIcon/XDSSVGIcon.tsx
new file mode 100644
index 0000000000..829f8d9f6e
--- /dev/null
+++ b/packages/lab/src/SVGIcon/XDSSVGIcon.tsx
@@ -0,0 +1,381 @@
+'use client';
+
+/**
+ * @file XDSSVGIcon.tsx
+ * @input SVG path data with per-element roles, variation preset, size, color
+ * @output CSS-variable-driven SVG icon with role-aware rendering and mask-based gaps
+ * @position Core implementation for the lab SVG icon system
+ *
+ * Two key concepts beyond basic CSS-var-driven icons:
+ *
+ * 1. Path roles — each element is either "fill" (closed shapes that switch between
+ * stroke and fill across variations) or "stroke" (lines that always stay stroked).
+ *
+ * 2. Mask-based gaps — in bold/filled mode, overlapping fill-role shapes get
+ * auto-generated SVG masks. Secondary fill shapes are knocked out of primary
+ * shapes with a configurable gap and corner rounding, producing clean negative
+ * space on any background.
+ */
+
+import {type CSSProperties, type SVGProps, useId} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {colorVars} from '@xds/core/theme/tokens.stylex';
+import {xdsClassName, mergeProps} from '@xds/core/utils';
+import {iconVars} from './tokens.stylex';
+import {variations, opticalSize} from './variations.stylex';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type SVGIconVariation =
+ | 'linear'
+ | 'bold'
+ | 'twotone'
+ | 'bulk'
+ | 'broken';
+export type SVGIconSize = 'xsm' | 'sm' | 'md' | 'lg';
+export type SVGIconColor =
+ | 'primary'
+ | 'secondary'
+ | 'disabled'
+ | 'accent'
+ | 'positive'
+ | 'negative'
+ | 'warning'
+ | 'inherit';
+
+/**
+ * Role determines how an element behaves across variations.
+ * - "fill": closed shapes — stroked in linear, filled in bold
+ * - "stroke": lines/detail strokes — always rendered as strokes
+ */
+export type IconShapeRole = 'fill' | 'stroke';
+
+/** Shape element within an icon layer */
+export interface IconShape {
+ /** SVG element type */
+ type: 'path' | 'circle' | 'rect' | 'line' | 'polyline' | 'polygon';
+ /** SVG attributes for this shape (d, cx, cy, r, points, x1, y1, etc.) */
+ attrs: Record<string, string>;
+ /**
+ * How this element behaves across variations.
+ * @default 'fill'
+ */
+ role?: IconShapeRole;
+}
+
+/** Definition of an SVG icon's geometry */
+export interface SVGIconDef {
+ /** Display name */
+ name: string;
+ /** ViewBox dimensions (default: "0 0 24 24") */
+ viewBox?: string;
+ /** Primary layer shapes (main outlines) */
+ primary: IconShape[];
+ /** Secondary layer shapes (detail elements) */
+ secondary?: IconShape[];
+}
+
+export interface XDSSVGIconProps extends Omit<
+ SVGProps<SVGSVGElement>,
+ 'color'
+> {
+ /** The icon definition containing path data */
+ icon: SVGIconDef;
+ /**
+ * Visual variation preset.
+ * @default 'linear'
+ */
+ variation?: SVGIconVariation;
+ /**
+ * Icon size with optical stroke compensation.
+ * @default 'md'
+ */
+ size?: SVGIconSize;
+ /**
+ * Semantic color.
+ * @default 'primary'
+ */
+ color?: SVGIconColor;
+ /** Override stroke width (bypasses optical compensation). */
+ strokeWidth?: number;
+}
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = stylex.create({
+ root: {
+ display: 'inline-flex',
+ flexShrink: 0,
+ width: iconVars['--icon-size'],
+ height: iconVars['--icon-size'],
+ paddingInlineStart: iconVars['--icon-inline-offset'],
+ paddingBlockStart: iconVars['--icon-block-offset'],
+ },
+});
+
+const colorStyles = stylex.create({
+ primary: {color: colorVars['--color-icon-primary']},
+ secondary: {color: colorVars['--color-icon-secondary']},
+ disabled: {color: colorVars['--color-icon-disabled']},
+ accent: {color: colorVars['--color-accent']},
+ positive: {color: colorVars['--color-success']},
+ negative: {color: colorVars['--color-error']},
+ warning: {color: colorVars['--color-warning']},
+ inherit: {color: 'inherit'},
+});
+
+// =============================================================================
+// Shape Renderer
+// =============================================================================
+
+function renderShapeElement(
+ attrs: Record<string, string>,
+ type: IconShape['type'],
+ key: number | string,
+) {
+ const props = {...attrs, key};
+ switch (type) {
+ case 'path':
+ return <path {...props} />;
+ case 'circle':
+ return <circle {...props} />;
+ case 'rect':
+ return <rect {...props} />;
+ case 'line':
+ return <line {...props} />;
+ case 'polyline':
+ return <polyline {...props} />;
+ case 'polygon':
+ return <polygon {...props} />;
+ default:
+ return null;
+ }
+}
+
+// =============================================================================
+// Mask Generation
+// =============================================================================
+
+/** Check whether bold mode needs a mask for this layer */
+function needsMask(
+ variation: SVGIconVariation,
+ fillShapes: IconShape[],
+ secondaryFillShapes: IconShape[],
+): boolean {
+ if (variation !== 'bold' && variation !== 'bulk') return false;
+ return fillShapes.length > 0 && secondaryFillShapes.length > 0;
+}
+
+/**
+ * Render mask knockout shapes — secondary fill-role elements become holes
+ * in the primary layer, with gap and corner rounding from CSS vars.
+ */
+function renderMaskKnockouts(shapes: IconShape[]) {
+ return shapes.map((shape, i) =>
+ renderShapeElement(
+ {
+ ...shape.attrs,
+ fill: 'black',
+ stroke: 'black',
+ strokeWidth: `var(${iconVars['--icon-gap']})`,
+ strokeLinejoin: `var(${iconVars['--icon-gap-linejoin']})`,
+ },
+ shape.type,
+ `knockout-${i}`,
+ ),
+ );
+}
+
+// =============================================================================
+// Layer Renderers
+// =============================================================================
+
+type LayerPrefix = 'primary' | 'secondary';
+
+function renderFillRoleShapes(
+ shapes: IconShape[],
+ layer: LayerPrefix,
+ maskId?: string,
+) {
+ const fillVar =
+ layer === 'primary'
+ ? iconVars['--icon-layer-primary-fill']
+ : iconVars['--icon-layer-secondary-fill'];
+ const strokeVar =
+ layer === 'primary'
+ ? iconVars['--icon-layer-primary-stroke']
+ : iconVars['--icon-layer-secondary-stroke'];
+ const opacityVar =
+ layer === 'primary'
+ ? iconVars['--icon-layer-primary-opacity']
+ : iconVars['--icon-layer-secondary-opacity'];
+
+ if (shapes.length === 0) return null;
+
+ return (
+ <g
+ style={{
+ fill: fillVar as string,
+ stroke: strokeVar as string,
+ opacity: opacityVar as string,
+ strokeWidth: iconVars['--icon-stroke-width'] as string,
+ strokeLinecap: iconVars['--icon-stroke-linecap'] as unknown as 'round',
+ strokeLinejoin: iconVars[
+ '--icon-stroke-linejoin'
+ ] as unknown as 'round',
+ }}
+ mask={maskId ? `url(#${maskId})` : undefined}>
+ {shapes.map((shape, i) =>
+ renderShapeElement(shape.attrs, shape.type, `${layer}-fill-${i}`),
+ )}
+ </g>
+ );
+}
+
+function renderStrokeRoleShapes(shapes: IconShape[], layer: LayerPrefix) {
+ const fillVar =
+ layer === 'primary'
+ ? iconVars['--icon-layer-primary-stroke-role-fill']
+ : iconVars['--icon-layer-secondary-stroke-role-fill'];
+ const strokeVar =
+ layer === 'primary'
+ ? iconVars['--icon-layer-primary-stroke-role-stroke']
+ : iconVars['--icon-layer-secondary-stroke-role-stroke'];
+ const opacityVar =
+ layer === 'primary'
+ ? iconVars['--icon-layer-primary-stroke-role-opacity']
+ : iconVars['--icon-layer-secondary-stroke-role-opacity'];
+ const widthVar =
+ layer === 'primary'
+ ? iconVars['--icon-layer-primary-stroke-role-width']
+ : iconVars['--icon-layer-secondary-stroke-role-width'];
+
+ if (shapes.length === 0) return null;
+
+ return (
+ <g
+ style={{
+ fill: fillVar as string,
+ stroke: strokeVar as string,
+ opacity: opacityVar as string,
+ strokeWidth: widthVar as string,
+ strokeLinecap: iconVars['--icon-stroke-linecap'] as unknown as 'round',
+ strokeLinejoin: iconVars[
+ '--icon-stroke-linejoin'
+ ] as unknown as 'round',
+ }}>
+ {shapes.map((shape, i) =>
+ renderShapeElement(shape.attrs, shape.type, `${layer}-stroke-${i}`),
+ )}
+ </g>
+ );
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+function splitByRole(shapes: IconShape[]): {
+ fill: IconShape[];
+ stroke: IconShape[];
+} {
+ const fill: IconShape[] = [];
+ const stroke: IconShape[] = [];
+ for (const shape of shapes) {
+ if (shape.role === 'stroke') {
+ stroke.push(shape);
+ } else {
+ fill.push(shape);
+ }
+ }
+ return {fill, stroke};
+}
+
+/**
+ * CSS-variable-driven SVG icon with role-aware rendering.
+ *
+ * Each shape element has a role ("fill" or "stroke") that determines how it
+ * behaves across variations. In bold mode, overlapping fill-role shapes get
+ * auto-generated SVG masks for clean gap subtraction.
+ *
+ * @example
+ * ```
+ * <XDSSVGIcon icon={bellIcon} variation="twotone" size="md" color="accent" />
+ * ```
+ */
+export function XDSSVGIcon({
+ icon,
+ variation = 'linear',
+ size = 'md',
+ color = 'primary',
+ strokeWidth,
+ style,
+ ...props
+}: XDSSVGIconProps) {
+ const uid = useId();
+ const viewBox = icon.viewBox ?? '0 0 24 24';
+ const hasSecondary = icon.secondary && icon.secondary.length > 0;
+
+ const primarySplit = splitByRole(icon.primary);
+ const secondarySplit = hasSecondary
+ ? splitByRole(icon.secondary!)
+ : {fill: [], stroke: []};
+
+ const useMask = needsMask(variation, primarySplit.fill, secondarySplit.fill);
+ const maskId = useMask ? `${uid}-mask` : undefined;
+
+ const overrideStyle: CSSProperties = {
+ ...(style as CSSProperties),
+ ...(strokeWidth != null
+ ? ({
+ [iconVars['--icon-stroke-width'] as string]: String(strokeWidth),
+ } as Record<string, string>)
+ : undefined),
+ };
+
+ return (
+ <svg
+ xmlns="http://www.w3.org/2000/svg"
+ viewBox={viewBox}
+ aria-hidden="true"
+ {...mergeProps(
+ xdsClassName('svg-icon', {variation, size, color}),
+ stylex.props(
+ styles.root,
+ colorStyles[color],
+ variations[variation],
+ opticalSize[size],
+ ),
+ )}
+ style={overrideStyle}
+ {...props}>
+ {/* Mask definition — knocks secondary fill shapes out of primary */}
+ {useMask && (
+ <defs>
+ <mask id={maskId}>
+ <rect width="24" height="24" fill="white" />
+ {renderMaskKnockouts(secondarySplit.fill)}
+ </mask>
+ </defs>
+ )}
+
+ {/* Primary layer */}
+ {renderFillRoleShapes(primarySplit.fill, 'primary', maskId)}
+ {renderStrokeRoleShapes(primarySplit.stroke, 'primary')}
+
+ {/* Secondary layer */}
+ {hasSecondary && (
+ <>
+ {renderFillRoleShapes(secondarySplit.fill, 'secondary')}
+ {renderStrokeRoleShapes(secondarySplit.stroke, 'secondary')}
+ </>
+ )}
+ </svg>
+ );
+}
+
+XDSSVGIcon.displayName = 'XDSSVGIcon';
diff --git a/packages/lab/src/SVGIcon/icons.ts b/packages/lab/src/SVGIcon/icons.ts
new file mode 100644
index 0000000000..5d94f25805
--- /dev/null
+++ b/packages/lab/src/SVGIcon/icons.ts
@@ -0,0 +1,155 @@
+/**
+ * @file icons.ts
+ * @input Lucide icon SVG paths
+ * @output SVGIconDef objects with per-element roles
+ * @position Icon library consumed by stories and tests
+ *
+ * Each shape has a role:
+ * - "fill": closed shapes that switch between stroke (linear) and fill (bold)
+ * - "stroke": lines/strokes that always render as strokes
+ *
+ * The role defaults to "fill" if omitted.
+ */
+
+import type {SVGIconDef} from './XDSSVGIcon';
+
+/** Simple stroke-only: X / Close — both lines are stroke-role */
+export const xIcon: SVGIconDef = {
+ name: 'X',
+ primary: [
+ {
+ type: 'line',
+ attrs: {x1: '18', y1: '6', x2: '6', y2: '18'},
+ role: 'stroke',
+ },
+ {
+ type: 'line',
+ attrs: {x1: '6', y1: '6', x2: '18', y2: '18'},
+ role: 'stroke',
+ },
+ ],
+};
+
+/** Simple stroke-only: Check */
+export const checkIcon: SVGIconDef = {
+ name: 'Check',
+ primary: [{type: 'path', attrs: {d: 'M20 6 9 17l-5-5'}, role: 'stroke'}],
+};
+
+/** Two-layer with mixed roles: Bell body is fill, clapper is stroke */
+export const bellIcon: SVGIconDef = {
+ name: 'Bell',
+ primary: [
+ {
+ type: 'path',
+ attrs: {d: 'M6 8a6 6 0 0 1 12 0c0 7 3 9 3 9H3s3-2 3-9'},
+ role: 'fill',
+ },
+ ],
+ secondary: [
+ {
+ type: 'path',
+ attrs: {d: 'M10.3 21a1.94 1.94 0 0 0 3.4 0'},
+ role: 'stroke',
+ },
+ ],
+};
+
+/**
+ * Two-layer: Home — house outline is fill, door is fill (secondary).
+ * In bold mode the door gets masked out of the house body.
+ */
+export const homeIcon: SVGIconDef = {
+ name: 'Home',
+ primary: [
+ {
+ type: 'path',
+ attrs: {
+ d: 'M3 10a2 2 0 0 1 .709-1.528l7-5.999a2 2 0 0 1 2.582 0l7 5.999A2 2 0 0 1 21 10v9a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z',
+ },
+ role: 'fill',
+ },
+ ],
+ secondary: [
+ {
+ type: 'path',
+ attrs: {d: 'M15 21v-8a1 1 0 0 0-1-1h-4a1 1 0 0 0-1 1v8'},
+ role: 'fill',
+ },
+ ],
+};
+
+/** Complex: Settings — gear body is fill, center circle is fill (secondary, masked in bold) */
+export const settingsIcon: SVGIconDef = {
+ name: 'Settings',
+ primary: [
+ {
+ type: 'path',
+ attrs: {
+ d: 'M12.22 2h-.44a2 2 0 0 0-2 2v.18a2 2 0 0 1-1 1.73l-.43.25a2 2 0 0 1-2 0l-.15-.08a2 2 0 0 0-2.73.73l-.22.38a2 2 0 0 0 .73 2.73l.15.1a2 2 0 0 1 1 1.72v.51a2 2 0 0 1-1 1.74l-.15.09a2 2 0 0 0-.73 2.73l.22.38a2 2 0 0 0 2.73.73l.15-.08a2 2 0 0 1 2 0l.43.25a2 2 0 0 1 1 1.73V20a2 2 0 0 0 2 2h.44a2 2 0 0 0 2-2v-.18a2 2 0 0 1 1-1.73l.43-.25a2 2 0 0 1 2 0l.15.08a2 2 0 0 0 2.73-.73l.22-.39a2 2 0 0 0-.73-2.73l-.15-.08a2 2 0 0 1-1-1.74v-.5a2 2 0 0 1 1-1.74l.15-.09a2 2 0 0 0 .73-2.73l-.22-.38a2 2 0 0 0-2.73-.73l-.15.08a2 2 0 0 1-2 0l-.43-.25a2 2 0 0 1-1-1.73V4a2 2 0 0 0-2-2z',
+ },
+ role: 'fill',
+ },
+ ],
+ secondary: [
+ {type: 'circle', attrs: {cx: '12', cy: '12', r: '3'}, role: 'fill'},
+ ],
+};
+
+/** Mixed roles: Calendar frame is fill, pegs are stroke, divider line is stroke */
+export const calendarIcon: SVGIconDef = {
+ name: 'Calendar',
+ primary: [
+ {
+ type: 'rect',
+ attrs: {width: '18', height: '18', x: '3', y: '4', rx: '2'},
+ role: 'fill',
+ },
+ {
+ type: 'line',
+ attrs: {x1: '16', y1: '2', x2: '16', y2: '6'},
+ role: 'stroke',
+ },
+ {type: 'line', attrs: {x1: '8', y1: '2', x2: '8', y2: '6'}, role: 'stroke'},
+ ],
+ secondary: [
+ {
+ type: 'line',
+ attrs: {x1: '3', y1: '10', x2: '21', y2: '10'},
+ role: 'stroke',
+ },
+ ],
+};
+
+/** Stroke-only: Menu / Hamburger — all lines are stroke-role */
+export const menuIcon: SVGIconDef = {
+ name: 'Menu',
+ primary: [
+ {
+ type: 'line',
+ attrs: {x1: '4', y1: '6', x2: '20', y2: '6'},
+ role: 'stroke',
+ },
+ {
+ type: 'line',
+ attrs: {x1: '4', y1: '12', x2: '20', y2: '12'},
+ role: 'stroke',
+ },
+ {
+ type: 'line',
+ attrs: {x1: '4', y1: '18', x2: '20', y2: '18'},
+ role: 'stroke',
+ },
+ ],
+};
+
+/** All starter icons for convenience */
+export const starterIcons: SVGIconDef[] = [
+ xIcon,
+ checkIcon,
+ bellIcon,
+ homeIcon,
+ settingsIcon,
+ calendarIcon,
+ menuIcon,
+];
diff --git a/packages/lab/src/SVGIcon/index.ts b/packages/lab/src/SVGIcon/index.ts
new file mode 100644
index 0000000000..2f4c75151b
--- /dev/null
+++ b/packages/lab/src/SVGIcon/index.ts
@@ -0,0 +1,33 @@
+'use client';
+
+/**
+ * @file index.ts
+ * @input SVGIcon module
+ * @output Re-exports all SVG icon system components, types, utilities, and starter icons
+ * @position Entry point for the lab SVG icon system
+ */
+
+export {XDSSVGIcon} from './XDSSVGIcon';
+export type {
+ XDSSVGIconProps,
+ SVGIconVariation,
+ SVGIconSize,
+ SVGIconColor,
+ SVGIconDef,
+ IconShape,
+ IconShapeRole,
+} from './XDSSVGIcon';
+
+export {variations, opticalSize} from './variations.stylex';
+export {iconVars} from './tokens.stylex';
+
+export {
+ xIcon,
+ checkIcon,
+ bellIcon,
+ homeIcon,
+ settingsIcon,
+ calendarIcon,
+ menuIcon,
+ starterIcons,
+} from './icons';
diff --git a/packages/lab/src/SVGIcon/tokens.stylex.ts b/packages/lab/src/SVGIcon/tokens.stylex.ts
new file mode 100644
index 0000000000..dfcaaa102c
--- /dev/null
+++ b/packages/lab/src/SVGIcon/tokens.stylex.ts
@@ -0,0 +1,48 @@
+/**
+ * @file tokens.stylex.ts
+ * @input XDS design token system
+ * @output CSS custom properties for SVG icon rendering
+ * @position Token definitions consumed by XDSSVGIcon and variation presets
+ *
+ * Two-layer system (primary/secondary) with per-role rendering (fill vs stroke).
+ * Bold mode uses mask-based gap subtraction controlled by --icon-gap tokens.
+ */
+
+import * as stylex from '@stylexjs/stylex';
+
+export const iconVars = stylex.defineVars({
+ // Primary layer — fill-role elements
+ '--icon-layer-primary-fill': 'none',
+ '--icon-layer-primary-stroke': 'currentColor',
+ '--icon-layer-primary-opacity': '1',
+
+ // Primary layer — stroke-role elements (lines that never become fills)
+ '--icon-layer-primary-stroke-role-fill': 'none',
+ '--icon-layer-primary-stroke-role-stroke': 'currentColor',
+ '--icon-layer-primary-stroke-role-opacity': '1',
+ '--icon-layer-primary-stroke-role-width': '1.5',
+
+ // Secondary layer — fill-role elements
+ '--icon-layer-secondary-fill': 'none',
+ '--icon-layer-secondary-stroke': 'currentColor',
+ '--icon-layer-secondary-opacity': '1',
+
+ // Secondary layer — stroke-role elements
+ '--icon-layer-secondary-stroke-role-fill': 'none',
+ '--icon-layer-secondary-stroke-role-stroke': 'currentColor',
+ '--icon-layer-secondary-stroke-role-opacity': '1',
+ '--icon-layer-secondary-stroke-role-width': '1.5',
+
+ // QoL adjustments
+ '--icon-size': '24px',
+ '--icon-stroke-width': '1.5',
+ '--icon-stroke-linecap': 'round',
+ '--icon-stroke-linejoin': 'round',
+ '--icon-padding': '0px',
+ '--icon-inline-offset': '0px',
+ '--icon-block-offset': '0px',
+
+ // Bold mode mask gaps
+ '--icon-gap': '1.5',
+ '--icon-gap-linejoin': 'round',
+});
diff --git a/packages/lab/src/SVGIcon/variations.stylex.ts b/packages/lab/src/SVGIcon/variations.stylex.ts
new file mode 100644
index 0000000000..f9fc1e3452
--- /dev/null
+++ b/packages/lab/src/SVGIcon/variations.stylex.ts
@@ -0,0 +1,120 @@
+/**
+ * @file variations.stylex.ts
+ * @input Icon token vars
+ * @output StyleX styles for each icon variation preset
+ * @position Consumed by XDSSVGIcon to apply variation-specific token overrides
+ *
+ * Each variation sets tokens for both fill-role and stroke-role elements
+ * per the path role system. Stroke-role elements (lines, detail strokes)
+ * never become fills — they stay as strokes across all variations.
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import {iconVars} from './tokens.stylex';
+
+export const variations = stylex.create({
+ linear: {
+ // Fill-role: stroked outlines
+ [iconVars['--icon-layer-primary-fill']]: 'none',
+ [iconVars['--icon-layer-primary-stroke']]: 'currentColor',
+ [iconVars['--icon-layer-primary-opacity']]: '1',
+ [iconVars['--icon-layer-primary-stroke-role-fill']]: 'none',
+ [iconVars['--icon-layer-primary-stroke-role-stroke']]: 'currentColor',
+ [iconVars['--icon-layer-primary-stroke-role-opacity']]: '1',
+ // Secondary
+ [iconVars['--icon-layer-secondary-fill']]: 'none',
+ [iconVars['--icon-layer-secondary-stroke']]: 'currentColor',
+ [iconVars['--icon-layer-secondary-opacity']]: '1',
+ [iconVars['--icon-layer-secondary-stroke-role-fill']]: 'none',
+ [iconVars['--icon-layer-secondary-stroke-role-stroke']]: 'currentColor',
+ [iconVars['--icon-layer-secondary-stroke-role-opacity']]: '1',
+ },
+ bold: {
+ // Fill-role: solid filled (mask handles overlaps)
+ [iconVars['--icon-layer-primary-fill']]: 'currentColor',
+ [iconVars['--icon-layer-primary-stroke']]: 'none',
+ [iconVars['--icon-layer-primary-opacity']]: '1',
+ // Stroke-role: stays stroked, thicker for visual weight
+ [iconVars['--icon-layer-primary-stroke-role-fill']]: 'none',
+ [iconVars['--icon-layer-primary-stroke-role-stroke']]: 'currentColor',
+ [iconVars['--icon-layer-primary-stroke-role-opacity']]: '1',
+ [iconVars['--icon-layer-primary-stroke-role-width']]: '2',
+ // Secondary
+ [iconVars['--icon-layer-secondary-fill']]: 'currentColor',
+ [iconVars['--icon-layer-secondary-stroke']]: 'none',
+ [iconVars['--icon-layer-secondary-opacity']]: '1',
+ [iconVars['--icon-layer-secondary-stroke-role-fill']]: 'none',
+ [iconVars['--icon-layer-secondary-stroke-role-stroke']]: 'currentColor',
+ [iconVars['--icon-layer-secondary-stroke-role-opacity']]: '1',
+ [iconVars['--icon-layer-secondary-stroke-role-width']]: '2',
+ },
+ twotone: {
+ // Fill-role: stroked, full opacity
+ [iconVars['--icon-layer-primary-fill']]: 'none',
+ [iconVars['--icon-layer-primary-stroke']]: 'currentColor',
+ [iconVars['--icon-layer-primary-opacity']]: '1',
+ // Stroke-role: stroked, reduced opacity
+ [iconVars['--icon-layer-primary-stroke-role-fill']]: 'none',
+ [iconVars['--icon-layer-primary-stroke-role-stroke']]: 'currentColor',
+ [iconVars['--icon-layer-primary-stroke-role-opacity']]: '0.4',
+ // Secondary: reduced opacity
+ [iconVars['--icon-layer-secondary-fill']]: 'none',
+ [iconVars['--icon-layer-secondary-stroke']]: 'currentColor',
+ [iconVars['--icon-layer-secondary-opacity']]: '0.4',
+ [iconVars['--icon-layer-secondary-stroke-role-fill']]: 'none',
+ [iconVars['--icon-layer-secondary-stroke-role-stroke']]: 'currentColor',
+ [iconVars['--icon-layer-secondary-stroke-role-opacity']]: '0.4',
+ },
+ bulk: {
+ // Fill-role: solid filled
+ [iconVars['--icon-layer-primary-fill']]: 'currentColor',
+ [iconVars['--icon-layer-primary-stroke']]: 'none',
+ [iconVars['--icon-layer-primary-opacity']]: '1',
+ // Stroke-role: reduced opacity
+ [iconVars['--icon-layer-primary-stroke-role-fill']]: 'none',
+ [iconVars['--icon-layer-primary-stroke-role-stroke']]: 'currentColor',
+ [iconVars['--icon-layer-primary-stroke-role-opacity']]: '0.4',
+ // Secondary: filled at reduced opacity
+ [iconVars['--icon-layer-secondary-fill']]: 'currentColor',
+ [iconVars['--icon-layer-secondary-stroke']]: 'none',
+ [iconVars['--icon-layer-secondary-opacity']]: '0.4',
+ [iconVars['--icon-layer-secondary-stroke-role-fill']]: 'none',
+ [iconVars['--icon-layer-secondary-stroke-role-stroke']]: 'currentColor',
+ [iconVars['--icon-layer-secondary-stroke-role-opacity']]: '0.4',
+ },
+ broken: {
+ [iconVars['--icon-layer-primary-fill']]: 'none',
+ [iconVars['--icon-layer-primary-stroke']]: 'currentColor',
+ [iconVars['--icon-layer-primary-opacity']]: '1',
+ [iconVars['--icon-layer-primary-stroke-role-fill']]: 'none',
+ [iconVars['--icon-layer-primary-stroke-role-stroke']]: 'currentColor',
+ [iconVars['--icon-layer-primary-stroke-role-opacity']]: '1',
+ // Secondary hidden
+ [iconVars['--icon-layer-secondary-fill']]: 'none',
+ [iconVars['--icon-layer-secondary-stroke']]: 'currentColor',
+ [iconVars['--icon-layer-secondary-opacity']]: '0',
+ [iconVars['--icon-layer-secondary-stroke-role-fill']]: 'none',
+ [iconVars['--icon-layer-secondary-stroke-role-stroke']]: 'currentColor',
+ [iconVars['--icon-layer-secondary-stroke-role-opacity']]: '0',
+ },
+});
+
+/** Optical size compensation — thicker strokes at smaller sizes */
+export const opticalSize = stylex.create({
+ xsm: {
+ [iconVars['--icon-stroke-width']]: '2',
+ [iconVars['--icon-size']]: '12px',
+ },
+ sm: {
+ [iconVars['--icon-stroke-width']]: '1.75',
+ [iconVars['--icon-size']]: '16px',
+ },
+ md: {
+ [iconVars['--icon-stroke-width']]: '1.5',
+ [iconVars['--icon-size']]: '20px',
+ },
+ lg: {
+ [iconVars['--icon-stroke-width']]: '1.5',
+ [iconVars['--icon-size']]: '24px',
+ },
+});
diff --git a/packages/lab/src/index.ts b/packages/lab/src/index.ts
index 1ab709bad8..cdb3c3209c 100644
--- a/packages/lab/src/index.ts
+++ b/packages/lab/src/index.ts
@@ -23,3 +23,26 @@ export {
XDSChatReasoning,
type XDSChatReasoningProps,
} from './ChatReasoning/XDSChatReasoning';
+
+// SVG Icon system — CSS-variable-driven multi-variation icons
+export {
+ XDSSVGIcon,
+ type XDSSVGIconProps,
+ type SVGIconVariation,
+ type SVGIconSize,
+ type SVGIconColor,
+ type SVGIconDef,
+ type IconShape,
+ type IconShapeRole,
+ iconVars,
+ variations,
+ opticalSize,
+ xIcon,
+ checkIcon,
+ bellIcon,
+ homeIcon,
+ settingsIcon,
+ calendarIcon,
+ menuIcon,
+ starterIcons,
+} from './SVGIcon';