Skip to content

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

TypeScript

feat(lab): SVGIcon v2 — structural diversity + bold stroke boost (#1278)

Cindy Zhang4319f404810d
diff --git a/apps/storybook/stories/SVGIcon.stories.tsx b/apps/storybook/stories/SVGIcon.stories.tsx
index 409655f29d..b42b15c663 100644
--- a/apps/storybook/stories/SVGIcon.stories.tsx
+++ b/apps/storybook/stories/SVGIcon.stories.tsx
@@ -10,6 +10,11 @@ import {
settingsIcon,
homeIcon,
menuIcon,
+ eyeIcon,
+ searchIcon,
+ mailIcon,
+ lockIcon,
+ iconVars,
} from '@xds/lab';
import {XDSStack, XDSText, XDSDivider} from '@xds/core';
@@ -252,3 +257,178 @@ export const Colors: Story = {
</XDSStack>
),
};
+
+// =============================================================================
+// Mask Gaps on Different Backgrounds
+// =============================================================================
+
+const MASK_GAP_ICONS = [
+ homeIcon,
+ settingsIcon,
+ eyeIcon,
+ searchIcon,
+ mailIcon,
+ lockIcon,
+];
+
+export const MaskGaps: Story = {
+ render: () => (
+ <XDSStack direction="vertical" gap={3}>
+ <XDSText variant="heading-3">Mask Gaps on Different Backgrounds</XDSText>
+ <XDSText variant="body-sm" color="secondary">
+ Bold mode uses mask-based knockout gaps. Because the gap is transparent
+ (not white), it works on any background — solid colors, surfaces, and
+ gradients alike.
+ </XDSText>
+
+ {[
+ {label: 'White', bg: '#ffffff'},
+ {label: 'Surface', bg: '#f5f5f5'},
+ {label: 'Accent', bg: '#0066ff'},
+ {
+ label: 'Gradient',
+ bg: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
+ },
+ ].map(({label, bg}) => (
+ <XDSStack direction="vertical" key={label} gap={1}>
+ <XDSText variant="label-sm" color="secondary">
+ {label}
+ </XDSText>
+ <div
+ style={{
+ background: bg,
+ padding: 16,
+ borderRadius: 8,
+ display: 'flex',
+ gap: 16,
+ }}>
+ {MASK_GAP_ICONS.map(icon => (
+ <XDSSVGIcon
+ key={icon.name}
+ icon={icon}
+ variation="bold"
+ size="lg"
+ color={
+ label === 'White' || label === 'Surface'
+ ? 'primary'
+ : 'inherit'
+ }
+ style={
+ label === 'Accent' || label === 'Gradient'
+ ? {color: '#ffffff'}
+ : undefined
+ }
+ />
+ ))}
+ </div>
+ </XDSStack>
+ ))}
+ </XDSStack>
+ ),
+};
+
+// =============================================================================
+// Stroke Width Range
+// =============================================================================
+
+const STROKE_WIDTHS = [1, 1.5, 2, 2.5, 3];
+
+export const StrokeWidthRange: Story = {
+ render: () => (
+ <XDSStack direction="vertical" gap={3}>
+ <XDSText variant="heading-3">Stroke Width Range</XDSText>
+ <XDSText variant="body-sm" color="secondary">
+ Linear mode at stroke widths from 1 to 3. Thinner strokes feel lighter
+ and more refined; thicker strokes add visual weight.
+ </XDSText>
+ <div
+ style={{
+ display: 'grid',
+ gridTemplateColumns: `80px repeat(${STROKE_WIDTHS.length}, 1fr)`,
+ gap: 12,
+ alignItems: 'center',
+ }}>
+ {/* Header row */}
+ <div />
+ {STROKE_WIDTHS.map(w => (
+ <XDSText
+ key={w}
+ variant="label-sm"
+ color="secondary"
+ style={{textAlign: 'center'}}>
+ {w}
+ </XDSText>
+ ))}
+
+ {/* Icon rows — first 8 starterIcons */}
+ {starterIcons.slice(0, 8).map(icon => (
+ <Fragment key={icon.name}>
+ <XDSText variant="label-sm">{icon.name}</XDSText>
+ {STROKE_WIDTHS.map(w => (
+ <div
+ key={`${icon.name}-${w}`}
+ style={{display: 'flex', justifyContent: 'center'}}>
+ <XDSSVGIcon
+ icon={icon}
+ variation="linear"
+ size="lg"
+ strokeWidth={w}
+ />
+ </div>
+ ))}
+ </Fragment>
+ ))}
+ </div>
+ </XDSStack>
+ ),
+};
+
+// =============================================================================
+// Structural Diversity
+// =============================================================================
+
+export const StructuralDiversity: Story = {
+ render: () => (
+ <XDSStack direction="vertical" gap={3}>
+ <XDSText variant="heading-3">Structural Diversity</XDSText>
+ <XDSText variant="body-sm" color="secondary">
+ New icons with diverse structures — organic curves, complex single
+ paths, nested overlapping fills, and mixed fill+stroke roles — across
+ all five variations.
+ </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 — new icons only */}
+ {starterIcons.slice(7).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>
+ ),
+};
diff --git a/packages/lab/src/SVGIcon/XDSSVGIcon.tsx b/packages/lab/src/SVGIcon/XDSSVGIcon.tsx
index 829f8d9f6e..31b8c380e8 100644
--- a/packages/lab/src/SVGIcon/XDSSVGIcon.tsx
+++ b/packages/lab/src/SVGIcon/XDSSVGIcon.tsx
@@ -163,31 +163,40 @@ function renderShapeElement(
/** Check whether bold mode needs a mask for this layer */
function needsMask(
variation: SVGIconVariation,
- fillShapes: IconShape[],
- secondaryFillShapes: IconShape[],
+ primaryFillShapes: IconShape[],
+ secondaryShapes: IconShape[],
): boolean {
- if (variation !== 'bold' && variation !== 'bulk') return false;
- return fillShapes.length > 0 && secondaryFillShapes.length > 0;
+ if (variation !== 'bold') return false;
+ return primaryFillShapes.length > 0 && secondaryShapes.length > 0;
}
/**
- * Render mask knockout shapes — secondary fill-role elements become holes
+ * Render mask knockout shapes — secondary 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(
+ return shapes.map((shape, i) => {
+ const role = shape.role ?? 'fill';
+ // Stroke-role knockouts need wider stroke to fully cover the visible stroke + gap
+ // Fill-role knockouts just need the gap width for the border around the hole
+ const knockoutWidth =
+ role === 'stroke'
+ ? `calc(${iconVars['--icon-stroke-width'] as string} + ${iconVars['--icon-gap'] as string} * 2)`
+ : (iconVars['--icon-gap'] as string);
+
+ return renderShapeElement(
{
...shape.attrs,
- fill: 'black',
+ fill: role === 'fill' ? 'black' : 'none',
stroke: 'black',
- strokeWidth: `var(${iconVars['--icon-gap']})`,
- strokeLinejoin: `var(${iconVars['--icon-gap-linejoin']})`,
+ strokeWidth: knockoutWidth,
+ strokeLinecap: 'round',
+ strokeLinejoin: iconVars['--icon-gap-linejoin'] as string,
},
shape.type,
`knockout-${i}`,
- ),
- );
+ );
+ });
}
// =============================================================================
@@ -325,14 +334,21 @@ export function XDSSVGIcon({
? splitByRole(icon.secondary!)
: {fill: [], stroke: []};
- const useMask = needsMask(variation, primarySplit.fill, secondarySplit.fill);
+ const allSecondary = [...secondarySplit.fill, ...secondarySplit.stroke];
+ const useMask = needsMask(variation, primarySplit.fill, allSecondary);
const maskId = useMask ? `${uid}-mask` : undefined;
+ // Extract raw CSS property name from StyleX var reference: "var(--xABC)" -> "--xABC"
+ const strokeWidthProp = (iconVars['--icon-stroke-width'] as string).replace(
+ /^var\((.+)\)$/,
+ '$1',
+ );
+
const overrideStyle: CSSProperties = {
...(style as CSSProperties),
...(strokeWidth != null
? ({
- [iconVars['--icon-stroke-width'] as string]: String(strokeWidth),
+ [strokeWidthProp]: String(strokeWidth),
} as Record<string, string>)
: undefined),
};
@@ -358,7 +374,10 @@ export function XDSSVGIcon({
<defs>
<mask id={maskId}>
<rect width="24" height="24" fill="white" />
- {renderMaskKnockouts(secondarySplit.fill)}
+ {renderMaskKnockouts([
+ ...secondarySplit.fill,
+ ...secondarySplit.stroke,
+ ])}
</mask>
</defs>
)}
@@ -367,8 +386,8 @@ export function XDSSVGIcon({
{renderFillRoleShapes(primarySplit.fill, 'primary', maskId)}
{renderStrokeRoleShapes(primarySplit.stroke, 'primary')}
- {/* Secondary layer */}
- {hasSecondary && (
+ {/* Secondary layer — hidden entirely in bold+mask (all secondaries are knockouts) */}
+ {hasSecondary && !useMask && (
<>
{renderFillRoleShapes(secondarySplit.fill, 'secondary')}
{renderStrokeRoleShapes(secondarySplit.stroke, 'secondary')}
diff --git a/packages/lab/src/SVGIcon/icons.ts b/packages/lab/src/SVGIcon/icons.ts
index 5d94f25805..13264eeea5 100644
--- a/packages/lab/src/SVGIcon/icons.ts
+++ b/packages/lab/src/SVGIcon/icons.ts
@@ -143,6 +143,124 @@ export const menuIcon: SVGIconDef = {
],
};
+/** Single curved path: Heart */
+export const heartIcon: SVGIconDef = {
+ name: 'Heart',
+ primary: [
+ {
+ type: 'path',
+ attrs: {
+ d: 'M2 9.5a5.5 5.5 0 0 1 9.591-3.676.56.56 0 0 0 .818 0A5.49 5.49 0 0 1 22 9.5c0 2.29-1.5 4-3 5.5l-5.492 5.313a2 2 0 0 1-3 .019L5 15c-1.5-1.5-3-3.2-3-5.5',
+ },
+ role: 'fill',
+ },
+ ],
+};
+
+/** Nested shapes: Eye — outer shape (fill) + pupil (fill, secondary) */
+export const eyeIcon: SVGIconDef = {
+ name: 'Eye',
+ primary: [
+ {
+ type: 'path',
+ attrs: {
+ d: 'M2.062 12.348a1 1 0 0 1 0-.696 10.75 10.75 0 0 1 19.876 0 1 1 0 0 1 0 .696 10.75 10.75 0 0 1-19.876 0',
+ },
+ role: 'fill',
+ },
+ ],
+ secondary: [
+ {type: 'circle', attrs: {cx: '12', cy: '12', r: '3'}, role: 'fill'},
+ ],
+};
+
+/** Complex single path: Star */
+export const starIcon: SVGIconDef = {
+ name: 'Star',
+ primary: [
+ {
+ type: 'path',
+ attrs: {
+ d: 'M11.525 2.295a.53.53 0 0 1 .95 0l2.31 4.679a2.123 2.123 0 0 0 1.595 1.16l5.166.756a.53.53 0 0 1 .294.904l-3.736 3.638a2.123 2.123 0 0 0-.611 1.878l.882 5.14a.53.53 0 0 1-.771.56l-4.618-2.428a2.122 2.122 0 0 0-1.973 0L6.396 21.01a.53.53 0 0 1-.77-.56l.881-5.139a2.122 2.122 0 0 0-.611-1.879L2.16 9.795a.53.53 0 0 1 .294-.906l5.165-.755a2.122 2.122 0 0 0 1.597-1.16z',
+ },
+ role: 'fill',
+ },
+ ],
+};
+
+/** Single panel: Folder */
+export const folderIcon: SVGIconDef = {
+ name: 'Folder',
+ primary: [
+ {
+ type: 'path',
+ attrs: {
+ d: 'M20 20a2 2 0 0 0 2-2V8a2 2 0 0 0-2-2h-7.9a2 2 0 0 1-1.69-.9L9.6 3.9A2 2 0 0 0 7.93 3H4a2 2 0 0 0-2 2v13a2 2 0 0 0 2 2Z',
+ },
+ role: 'fill',
+ },
+ ],
+};
+
+/** Single path: Shield */
+export const shieldIcon: SVGIconDef = {
+ name: 'Shield',
+ primary: [
+ {
+ type: 'path',
+ attrs: {
+ d: 'M20 13c0 5-3.5 7.5-7.66 8.95a1 1 0 0 1-.67-.01C7.5 20.5 4 18 4 13V6a1 1 0 0 1 1-1c2 0 4.5-1.2 6.24-2.72a1.17 1.17 0 0 1 1.52 0C14.51 3.81 17 5 19 5a1 1 0 0 1 1 1z',
+ },
+ role: 'fill',
+ },
+ ],
+};
+
+/** Mixed: Search — glass (fill) + handle (stroke, secondary) */
+export const searchIcon: SVGIconDef = {
+ name: 'Search',
+ primary: [
+ {type: 'circle', attrs: {cx: '11', cy: '11', r: '8'}, role: 'stroke'},
+ {
+ type: 'path',
+ attrs: {d: 'm21 21-4.34-4.34'},
+ role: 'stroke',
+ },
+ ],
+};
+
+/** Mixed: Mail — body (fill) + flap line (stroke, secondary) */
+export const mailIcon: SVGIconDef = {
+ name: 'Mail',
+ primary: [
+ {
+ type: 'rect',
+ attrs: {x: '2', y: '4', width: '20', height: '16', rx: '2'},
+ role: 'fill',
+ },
+ ],
+ secondary: [
+ {
+ type: 'path',
+ attrs: {d: 'm22 7-8.991 5.727a2 2 0 0 1-2.009 0L2 7'},
+ role: 'stroke',
+ },
+ ],
+};
+
+/** Mixed: Lock — body (fill) + shackle (stroke) */
+export const lockIcon: SVGIconDef = {
+ name: 'Lock',
+ primary: [
+ {
+ type: 'rect',
+ attrs: {width: '18', height: '11', x: '3', y: '11', rx: '2'},
+ role: 'fill',
+ },
+ {type: 'path', attrs: {d: 'M7 11V7a5 5 0 0 1 10 0v4'}, role: 'stroke'},
+ ],
+};
+
/** All starter icons for convenience */
export const starterIcons: SVGIconDef[] = [
xIcon,
@@ -152,4 +270,12 @@ export const starterIcons: SVGIconDef[] = [
settingsIcon,
calendarIcon,
menuIcon,
+ heartIcon,
+ eyeIcon,
+ starIcon,
+ folderIcon,
+ shieldIcon,
+ searchIcon,
+ mailIcon,
+ lockIcon,
];
diff --git a/packages/lab/src/SVGIcon/index.ts b/packages/lab/src/SVGIcon/index.ts
index 2f4c75151b..5ac0e2ec67 100644
--- a/packages/lab/src/SVGIcon/index.ts
+++ b/packages/lab/src/SVGIcon/index.ts
@@ -29,5 +29,13 @@ export {
settingsIcon,
calendarIcon,
menuIcon,
+ heartIcon,
+ eyeIcon,
+ starIcon,
+ folderIcon,
+ shieldIcon,
+ searchIcon,
+ mailIcon,
+ lockIcon,
starterIcons,
} from './icons';
diff --git a/packages/lab/src/SVGIcon/tokens.stylex.ts b/packages/lab/src/SVGIcon/tokens.stylex.ts
index dfcaaa102c..714b88f31e 100644
--- a/packages/lab/src/SVGIcon/tokens.stylex.ts
+++ b/packages/lab/src/SVGIcon/tokens.stylex.ts
@@ -42,7 +42,10 @@ export const iconVars = stylex.defineVars({
'--icon-inline-offset': '0px',
'--icon-block-offset': '0px',
+ // Bold mode adjustments
+ '--icon-bold-stroke-boost': '0.5',
+
// Bold mode mask gaps
- '--icon-gap': '1.5',
+ '--icon-gap': '0.75',
'--icon-gap-linejoin': 'round',
});
diff --git a/packages/lab/src/SVGIcon/variations.stylex.ts b/packages/lab/src/SVGIcon/variations.stylex.ts
index f9fc1e3452..2b3653f634 100644
--- a/packages/lab/src/SVGIcon/variations.stylex.ts
+++ b/packages/lab/src/SVGIcon/variations.stylex.ts
@@ -46,7 +46,7 @@ export const variations = stylex.create({
[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',
+ [iconVars['--icon-layer-secondary-stroke-role-width']]: '2.5',
},
twotone: {
// Fill-role: stroked, full opacity
diff --git a/packages/lab/src/index.ts b/packages/lab/src/index.ts
index cdb3c3209c..e474a455e5 100644
--- a/packages/lab/src/index.ts
+++ b/packages/lab/src/index.ts
@@ -44,5 +44,13 @@ export {
settingsIcon,
calendarIcon,
menuIcon,
+ heartIcon,
+ eyeIcon,
+ starIcon,
+ folderIcon,
+ shieldIcon,
+ searchIcon,
+ mailIcon,
+ lockIcon,
starterIcons,
} from './SVGIcon';