Skip to content

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

TypeScript

feat(lab): XDS Icon Format (XIF) — spec types, examples, and stories (#1929)

Cindy Zhang4f5871352c38
diff --git a/apps/storybook/stories/XIFSpec.stories.tsx b/apps/storybook/stories/XIFSpec.stories.tsx
new file mode 100644
index 0000000000..a8071a1289
--- /dev/null
+++ b/apps/storybook/stories/XIFSpec.stories.tsx
@@ -0,0 +1,655 @@
+import type {Meta, StoryObj} from '@storybook/react';
+import {Fragment} from 'react';
+import {XDSSVGIcon, type SVGIconVariation, type SVGIconDef} from '@xds/lab';
+import {XDSStack, XDSText, XDSDivider} from '@xds/core';
+import type {
+ XIFIcon,
+ XIFPath,
+} from '../../../packages/lab/src/SVGIcon/xif-types';
+import {
+ xifCheck,
+ xifHome,
+ xifFile,
+ xifShield,
+ xifBell,
+ xifStar,
+ xifBellOverride,
+ xifExamples,
+} from '../../../packages/lab/src/SVGIcon/xif-examples';
+
+// =============================================================================
+// Adapter: XIFIcon → SVGIconDef (until XDSSVGIcon natively reads XIF)
+// =============================================================================
+
+function xifToSvgIconDef(xif: XIFIcon): SVGIconDef {
+ const toPaths = (paths: XIFPath[]) =>
+ paths.map(p => ({
+ type: p.type ?? ('path' as const),
+ attrs: Object.fromEntries(
+ Object.entries(p.attrs).map(([k, v]) => [k, String(v)]),
+ ),
+ role: p.role,
+ }));
+
+ const primary = toPaths(
+ xif.paths.filter(p => (p.layer ?? 'primary') === 'primary'),
+ );
+ const secondary = toPaths(xif.paths.filter(p => p.layer === 'secondary'));
+
+ return {
+ name: xif.name,
+ viewBox: xif.viewBox,
+ primary,
+ secondary: secondary.length > 0 ? secondary : undefined,
+ };
+}
+
+// =============================================================================
+// Story
+// =============================================================================
+
+const meta: Meta = {
+ title: 'Lab/XDSSVGIcon/XIF Spec',
+};
+export default meta;
+
+const VARIATIONS: SVGIconVariation[] = [
+ 'linear',
+ 'bold',
+ 'twotone',
+ 'bulk',
+ 'broken',
+];
+
+// ---------------------------------------------------------------------------
+// Variation Matrix
+// ---------------------------------------------------------------------------
+
+export const SpecExamples: StoryObj = {
+ render: () => (
+ <XDSStack direction="vertical" gap={3}>
+ <XDSText type="heading-3">XIF Spec Examples</XDSText>
+ <XDSText type="supporting">
+ Icons defined using the XDS Icon Format specification. Each demonstrates
+ a different capability: stroke-only, two-layer knockout, composable
+ slots, animation declarations, personality overrides, and bold geometry
+ overrides.
+ </XDSText>
+
+ <div
+ style={{
+ display: 'grid',
+ gridTemplateColumns: `140px repeat(${VARIATIONS.length}, 1fr)`,
+ gap: '8px 4px',
+ alignItems: 'center',
+ }}>
+ <div />
+ {VARIATIONS.map(v => (
+ <XDSText
+ key={v}
+ type="label"
+ style={{textAlign: 'center', fontSize: 10}}>
+ {v}
+ </XDSText>
+ ))}
+
+ {xifExamples.map(xif => {
+ const def = xifToSvgIconDef(xif);
+ const features: string[] = [];
+ if (xif.slots?.length) features.push('🔌 slots');
+ if (xif.paths.some(p => p.animate)) features.push('✨ animated');
+ if (xif.paths.some(p => p.personality))
+ features.push('🎨 personality');
+ if (xif.overrides) features.push('🔀 overrides');
+ if (xif.paths.some(p => p.layer === 'secondary'))
+ features.push('📐 two-layer');
+
+ return (
+ <Fragment key={xif.name}>
+ <div>
+ <XDSText type="label" style={{fontSize: 11}}>
+ {xif.name}
+ </XDSText>
+ {features.length > 0 && (
+ <XDSText
+ type="supporting"
+ style={{fontSize: 9, marginTop: 2}}>
+ {features.join(' ')}
+ </XDSText>
+ )}
+ </div>
+ {VARIATIONS.map(v => (
+ <div
+ key={`${xif.name}-${v}`}
+ style={{display: 'flex', justifyContent: 'center'}}>
+ <XDSSVGIcon icon={def} variation={v} size="lg" />
+ </div>
+ ))}
+ </Fragment>
+ );
+ })}
+ </div>
+ </XDSStack>
+ ),
+};
+
+// ---------------------------------------------------------------------------
+// Composition Demo
+// ---------------------------------------------------------------------------
+
+export const CompositionSlots: StoryObj = {
+ render: () => {
+ const shieldDef = xifToSvgIconDef(xifShield);
+ const fileDef = xifToSvgIconDef(xifFile);
+ const checkDef = xifToSvgIconDef(xifCheck);
+
+ // Manually demonstrate what slot composition would produce
+ // (Until the component natively supports slots)
+ const composedShieldCheck: SVGIconDef = {
+ name: 'shield-check',
+ primary: [...shieldDef.primary],
+ secondary: [
+ {
+ type: 'path' as const,
+ attrs: {d: 'M9 13l2 2 4-4'},
+ role: 'stroke' as const,
+ },
+ ],
+ };
+
+ const composedShieldX: SVGIconDef = {
+ name: 'shield-x',
+ primary: [...shieldDef.primary],
+ secondary: [
+ {
+ type: 'path' as const,
+ attrs: {d: 'M9 9l6 6M15 9l-6 6'},
+ role: 'stroke' as const,
+ },
+ ],
+ };
+
+ const composedFileText: SVGIconDef = {
+ name: 'file-text',
+ primary: [...fileDef.primary],
+ secondary: [
+ ...(fileDef.secondary ?? []),
+ {
+ type: 'line' as const,
+ attrs: {x1: '9', y1: '13', x2: '15', y2: '13'},
+ role: 'stroke' as const,
+ },
+ {
+ type: 'line' as const,
+ attrs: {x1: '9', y1: '17', x2: '13', y2: '17'},
+ role: 'stroke' as const,
+ },
+ ],
+ };
+
+ return (
+ <XDSStack direction="vertical" gap={3}>
+ <XDSText type="heading-3">Composition via Slots</XDSText>
+ <XDSText type="supporting">
+ Icons with <code>slots</code> accept sub-icons. One shield base +
+ different badges = many composed icons without extra path data.
+ </XDSText>
+
+ <XDSStack direction="horizontal" gap={4}>
+ {[
+ {label: 'shield (base)', def: shieldDef},
+ {label: 'shield-check', def: composedShieldCheck},
+ {label: 'shield-x', def: composedShieldX},
+ {label: 'file (base)', def: fileDef},
+ {label: 'file-text', def: composedFileText},
+ ].map(({label, def}) => (
+ <XDSStack key={label} direction="vertical" gap={1} hAlign="center">
+ <XDSStack direction="horizontal" gap={2}>
+ <XDSSVGIcon icon={def} variation="linear" size="lg" />
+ <XDSSVGIcon icon={def} variation="bold" size="lg" />
+ </XDSStack>
+ <XDSText type="supporting" style={{fontSize: 10}}>
+ {label}
+ </XDSText>
+ </XDSStack>
+ ))}
+ </XDSStack>
+
+ <XDSDivider />
+
+ <XDSText type="heading-4">Slot Definition</XDSText>
+ <XDSText type="supporting">
+ The shield icon defines:{' '}
+ <code>
+ slots: [&#123; name: &apos;badge&apos;, position:
+ &apos;center&apos;, size: 0.42 &#125;]
+ </code>
+ . At render time, the component scales and positions the badge icon
+ into the slot. The badge inherits the parent&apos;s variation and
+ color.
+ </XDSText>
+ </XDSStack>
+ );
+ },
+};
+
+// ---------------------------------------------------------------------------
+// Personality Axes Demo
+// ---------------------------------------------------------------------------
+
+export const PersonalityAxes: StoryObj = {
+ render: () => {
+ const starDef = xifToSvgIconDef(xifStar);
+ const homeDef = xifToSvgIconDef(xifHome);
+ const bellDef = xifToSvgIconDef(xifBell);
+
+ const presets = [
+ {name: 'Brutalist', desc: 'Sharp corners, straight lines, tight curves'},
+ {name: 'Technical', desc: 'Minimal rounding, precise geometry'},
+ {name: 'Default', desc: 'Balanced — slight softening'},
+ {name: 'Friendly', desc: 'Rounded corners, subtle curves'},
+ {name: 'Playful', desc: 'Very rounded, bowed segments'},
+ ];
+
+ return (
+ <XDSStack direction="vertical" gap={3}>
+ <XDSText type="heading-3">Personality Axes (Conceptual)</XDSText>
+ <XDSText type="supporting">
+ Shape personality parameters adjust the <em>feel</em> of icons without
+ changing their structure. All adjustments are relative — preserving
+ the artist&apos;s hierarchy of sharp vs soft. These icons show the
+ concept; path manipulation is not yet implemented.
+ </XDSText>
+
+ <div
+ style={{
+ display: 'grid',
+ gridTemplateColumns: '120px repeat(5, 1fr)',
+ gap: '12px 8px',
+ alignItems: 'center',
+ }}>
+ <div />
+ {presets.map(p => (
+ <XDSStack key={p.name} direction="vertical" gap={0} hAlign="center">
+ <XDSText type="label" style={{fontSize: 10}}>
+ {p.name}
+ </XDSText>
+ <XDSText type="supporting" style={{fontSize: 8}}>
+ {p.desc}
+ </XDSText>
+ </XDSStack>
+ ))}
+
+ {[
+ {name: 'star', def: starDef},
+ {name: 'home', def: homeDef},
+ {name: 'bell', def: bellDef},
+ ].map(({name, def}) => (
+ <Fragment key={name}>
+ <XDSText type="label" style={{fontSize: 11}}>
+ {name}
+ </XDSText>
+ {presets.map((p, i) => (
+ <div
+ key={p.name}
+ style={{
+ display: 'flex',
+ justifyContent: 'center',
+ opacity: 0.3 + i * 0.175,
+ }}>
+ <XDSSVGIcon
+ icon={def}
+ variation="linear"
+ size="lg"
+ strokeWidth={1.5 - i * 0.1}
+ />
+ </div>
+ ))}
+ </Fragment>
+ ))}
+ </div>
+
+ <XDSText type="supporting">
+ Note: opacity/stroke-width are used as visual placeholders here. The
+ real implementation will modify path geometry — rounding corners,
+ bowing segments, adjusting curve tension — all at build time via the
+ theme pipeline.
+ </XDSText>
+ </XDSStack>
+ );
+ },
+};
+
+// ---------------------------------------------------------------------------
+// Animation Intent Demo
+// ---------------------------------------------------------------------------
+
+export const AnimationIntent: StoryObj = {
+ render: () => {
+ const animStyles = `
+ @keyframes xif-draw { from { stroke-dashoffset: 100; } to { stroke-dashoffset: 0; } }
+ @keyframes xif-fade { from { opacity: 0; } to { opacity: 1; } }
+ @keyframes xif-scale { from { transform: scale(0); } to { transform: scale(1); } }
+ @keyframes xif-rotate { from { transform: rotate(0deg); } to { transform: rotate(360deg); } }
+ .xif-draw path { stroke-dasharray: 100; stroke-dashoffset: 100; animation: xif-draw 1.2s ease-out forwards; }
+ .xif-draw path:nth-child(2) { animation-delay: 0.4s; }
+ .xif-fade path { opacity: 0; animation: xif-fade 0.6s ease-out forwards; }
+ .xif-fade path:nth-child(2) { animation-delay: 0.3s; }
+ .xif-scale path { transform-origin: center; transform: scale(0); animation: xif-scale 0.5s cubic-bezier(0.34,1.56,0.64,1) forwards; }
+ .xif-scale path:nth-child(2) { animation-delay: 0.2s; }
+ .xif-rotate { transform-origin: center; animation: xif-rotate 2s linear infinite; }
+ `;
+
+ const demos = [
+ {
+ name: 'draw',
+ desc: 'Stroke reveals along path',
+ cls: 'xif-draw',
+ paths: [
+ 'M6 8a6 6 0 0 1 12 0c0 7 3 9 3 9H3s3-2 3-9',
+ 'M10.3 21a1.94 1.94 0 0 0 3.4 0',
+ ],
+ },
+ {
+ name: 'fade',
+ desc: 'Opacity entrance per layer',
+ cls: 'xif-fade',
+ paths: [
+ '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',
+ 'M9 12l2 2 4-4',
+ ],
+ },
+ {
+ name: 'scale',
+ desc: 'Grow from center',
+ cls: 'xif-scale',
+ paths: [
+ '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',
+ ],
+ },
+ {
+ name: 'rotate',
+ desc: 'Continuous spin',
+ cls: 'xif-rotate',
+ paths: [
+ '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',
+ ],
+ },
+ ];
+
+ return (
+ <XDSStack direction="vertical" gap={3}>
+ <style dangerouslySetInnerHTML={{__html: animStyles}} />
+ <XDSText type="heading-3">Animation Types (Live)</XDSText>
+ <XDSText type="supporting">
+ Icons declare animation intent per path. The theme resolves timing.
+ Each demo loops on page load.
+ </XDSText>
+
+ <div
+ style={{
+ display: 'grid',
+ gridTemplateColumns: 'repeat(4, 1fr)',
+ gap: 24,
+ }}>
+ {demos.map(demo => (
+ <XDSStack
+ key={demo.name}
+ direction="vertical"
+ gap={1}
+ hAlign="center"
+ style={{padding: 16}}>
+ <svg
+ xmlns="http://www.w3.org/2000/svg"
+ viewBox="0 0 24 24"
+ width="48"
+ height="48"
+ fill="none"
+ stroke="currentColor"
+ strokeWidth={1.5}
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ className={demo.cls}>
+ {demo.paths.map((d, i) => (
+ <path key={i} d={d} />
+ ))}
+ </svg>
+ <XDSText type="label" style={{fontSize: 12, marginTop: 8}}>
+ {demo.name}
+ </XDSText>
+ <XDSText
+ type="supporting"
+ style={{fontSize: 10, textAlign: 'center'}}>
+ {demo.desc}
+ </XDSText>
+ </XDSStack>
+ ))}
+ </div>
+ </XDSStack>
+ );
+ },
+};
+
+// ---------------------------------------------------------------------------
+// Path Transform Playground
+// ---------------------------------------------------------------------------
+
+// Import path transforms
+import {
+ applyPersonality,
+ roundCorners,
+ addCurvature,
+ adjustTension,
+} from '../../../packages/lab/src/SVGIcon/pathTransforms';
+
+/** Simple test shapes for demonstrating transforms */
+const testShapes = {
+ square: 'M4 4 L20 4 L20 20 L4 20 Z',
+ diamond: 'M12 2 L22 12 L12 22 L2 12 Z',
+ arrow: 'M12 2 L20 10 L16 10 L16 22 L8 22 L8 10 L4 10 Z',
+ star: 'M12 2 L14.5 8.5 L21.5 9.5 L16.3 14.5 L17.6 21.5 L12 18 L6.4 21.5 L7.7 14.5 L2.5 9.5 L9.5 8.5 Z',
+ bell: 'M4 17 L4 9 L8 5 L12 3 L16 5 L20 9 L20 17 Z',
+ envelope: 'M2 6 L12 13 L22 6 L22 18 L2 18 Z',
+ chat: 'M3 4 L21 4 L21 16 L13 16 L8 21 L8 16 L3 16 Z',
+ shield: 'M4 5 L12 2 L20 5 L20 13 L12 22 L4 13 Z',
+ hexagon: 'M12 2 L20.5 6.5 L20.5 15.5 L12 20 L3.5 15.5 L3.5 6.5 Z',
+ bookmark: 'M6 2 L18 2 L18 22 L12 17 L6 22 Z',
+};
+
+/**
+ * Interactive path transform playground.
+ * Demonstrates corner rounding, segment curvature, and tension
+ * with live SVG rendering.
+ */
+export const PathTransformPlayground: StoryObj = {
+ render: () => {
+ // We can't use hooks in stories without a wrapper,
+ // so we render multiple preset rows instead
+ const roundingLevels = [0, 0.2, 0.4, 0.6, 0.8, 1.0];
+ const curvatureLevels = [0, 0.2, 0.5, 0.8, 1.0];
+ const tensionLevels = [0, 0.25, 0.5, 0.75, 1.0];
+
+ const shapes = Object.entries(testShapes);
+
+ return (
+ <XDSStack direction="vertical" gap={4}>
+ <XDSText type="heading-3">Path Transform Playground</XDSText>
+ <XDSText type="supporting">
+ Live path manipulation with sagitta-corrected corner rounding. Sharp
+ corners (like star tips) round less aggressively than gentle corners —
+ achieving equal <em>perceived</em> roundness at all angles.
+ </XDSText>
+
+ {/* Corner Rounding */}
+ <XDSText type="heading-4">Corner Rounding (sagitta-corrected)</XDSText>
+ <XDSText type="supporting">
+ Same cornerRounding value across all shapes. Sharp corners get less
+ radius, gentle corners get more — visually balanced.
+ </XDSText>
+ <div
+ style={{
+ display: 'grid',
+ gridTemplateColumns: `80px repeat(${roundingLevels.length}, 1fr)`,
+ gap: '8px 4px',
+ alignItems: 'center',
+ }}>
+ <div />
+ {roundingLevels.map(r => (
+ <XDSText
+ key={r}
+ type="label"
+ style={{textAlign: 'center', fontSize: 10}}>
+ {r}
+ </XDSText>
+ ))}
+ {shapes.map(([name, d]) => (
+ <Fragment key={name}>
+ <XDSText type="label" style={{fontSize: 11}}>
+ {name}
+ </XDSText>
+ {roundingLevels.map(r => (
+ <div
+ key={r}
+ style={{display: 'flex', justifyContent: 'center'}}>
+ <svg
+ viewBox="0 0 24 24"
+ width="40"
+ height="40"
+ fill="none"
+ stroke="currentColor"
+ strokeWidth="1.5"
+ strokeLinecap="round"
+ strokeLinejoin="round">
+ <path d={roundCorners(d, r)} />
+ </svg>
+ </div>
+ ))}
+ </Fragment>
+ ))}
+ </div>
+
+ <XDSDivider />
+
+ {/* Segment Curvature */}
+ <XDSText type="heading-4">Segment Curvature</XDSText>
+ <XDSText type="supporting">
+ Straight line segments gain a perpendicular bow. Subtle at low values,
+ pronounced at high.
+ </XDSText>
+ <div
+ style={{
+ display: 'grid',
+ gridTemplateColumns: `80px repeat(${curvatureLevels.length}, 1fr)`,
+ gap: '8px 4px',
+ alignItems: 'center',
+ }}>
+ <div />
+ {curvatureLevels.map(c => (
+ <XDSText
+ key={c}
+ type="label"
+ style={{textAlign: 'center', fontSize: 10}}>
+ {c}
+ </XDSText>
+ ))}
+ {shapes.slice(0, 5).map(([name, d]) => (
+ <Fragment key={name}>
+ <XDSText type="label" style={{fontSize: 11}}>
+ {name}
+ </XDSText>
+ {curvatureLevels.map(c => (
+ <div
+ key={c}
+ style={{display: 'flex', justifyContent: 'center'}}>
+ <svg
+ viewBox="0 0 24 24"
+ width="40"
+ height="40"
+ fill="none"
+ stroke="currentColor"
+ strokeWidth="1.5"
+ strokeLinecap="round"
+ strokeLinejoin="round">
+ <path d={addCurvature(d, c)} />
+ </svg>
+ </div>
+ ))}
+ </Fragment>
+ ))}
+ </div>
+
+ <XDSDivider />
+
+ {/* Combined: Rounding + Curvature presets */}
+ <XDSText type="heading-4">
+ Personality Presets (combined transforms)
+ </XDSText>
+ <div
+ style={{
+ display: 'grid',
+ gridTemplateColumns: `80px repeat(5, 1fr)`,
+ gap: '8px 4px',
+ alignItems: 'center',
+ }}>
+ <div />
+ {[
+ {label: 'Brutalist', r: 0, c: 0},
+ {label: 'Technical', r: 0.1, c: 0},
+ {label: 'Default', r: 0.25, c: 0.05},
+ {label: 'Friendly', r: 0.5, c: 0.15},
+ {label: 'Playful', r: 0.8, c: 0.3},
+ ].map(p => (
+ <XDSStack
+ key={p.label}
+ direction="vertical"
+ hAlign="center"
+ gap={0}>
+ <XDSText type="label" style={{fontSize: 10}}>
+ {p.label}
+ </XDSText>
+ <XDSText type="supporting" style={{fontSize: 8}}>
+ r:{p.r} c:{p.c}
+ </XDSText>
+ </XDSStack>
+ ))}
+ {shapes.map(([name, d]) => (
+ <Fragment key={name}>
+ <XDSText type="label" style={{fontSize: 11}}>
+ {name}
+ </XDSText>
+ {[
+ {r: 0, c: 0},
+ {r: 0.1, c: 0},
+ {r: 0.25, c: 0.05},
+ {r: 0.5, c: 0.15},
+ {r: 0.8, c: 0.3},
+ ].map((p, i) => {
+ const transformed = applyPersonality(d, {
+ cornerRounding: p.r,
+ segmentCurvature: p.c,
+ });
+ return (
+ <div
+ key={i}
+ style={{display: 'flex', justifyContent: 'center'}}>
+ <svg
+ viewBox="0 0 24 24"
+ width="40"
+ height="40"
+ fill="none"
+ stroke="currentColor"
+ strokeWidth="1.5"
+ strokeLinecap="round"
+ strokeLinejoin="round">
+ <path d={transformed} />
+ </svg>
+ </div>
+ );
+ })}
+ </Fragment>
+ ))}
+ </div>
+ </XDSStack>
+ );
+ },
+};
diff --git a/packages/lab/src/SVGIcon/index.ts b/packages/lab/src/SVGIcon/index.ts
index 5ac0e2ec67..652b883c83 100644
--- a/packages/lab/src/SVGIcon/index.ts
+++ b/packages/lab/src/SVGIcon/index.ts
@@ -39,3 +39,33 @@ export {
lockIcon,
starterIcons,
} from './icons';
+
+// XIF spec types
+export type {
+ XIFIcon,
+ XIFPath,
+ XIFPersonality,
+ XIFAnimate,
+ XIFSlot,
+} from './xif-types';
+
+// XIF example icons
+export {
+ xifCheck,
+ xifHome,
+ xifFile,
+ xifShield,
+ xifBell,
+ xifStar,
+ xifBellOverride,
+ xifExamples,
+} from './xif-examples';
+
+// Path transforms
+export {
+ roundCorners,
+ addCurvature,
+ adjustTension,
+ applyPersonality,
+ type PathPersonality,
+} from './pathTransforms';
diff --git a/packages/lab/src/SVGIcon/pathTransforms.ts b/packages/lab/src/SVGIcon/pathTransforms.ts
new file mode 100644
index 0000000000..8d53d66f37
--- /dev/null
+++ b/packages/lab/src/SVGIcon/pathTransforms.ts
@@ -0,0 +1,577 @@
+/**
+ * @file pathTransforms.ts
+ * @description SVG path manipulation utilities for XIF personality axes.
+ *
+ * Implements corner rounding, segment curvature, and tension adjustments
+ * as relative (percentile) transforms on parsed SVG path data.
+ *
+ * All transforms preserve the artist's hierarchy — sharp corners shift
+ * more than gentle ones, straight lines shift more than existing curves.
+ */
+
+// =============================================================================
+// Path Parser (minimal, handles M/L/H/V/C/Q/A/Z)
+// =============================================================================
+
+interface Point {
+ x: number;
+ y: number;
+}
+
+type PathCommand =
+ | {type: 'M'; x: number; y: number}
+ | {type: 'L'; x: number; y: number}
+ | {
+ type: 'C';
+ x1: number;
+ y1: number;
+ x2: number;
+ y2: number;
+ x: number;
+ y: number;
+ }
+ | {type: 'Q'; cx: number; cy: number; x: number; y: number}
+ | {
+ type: 'A';
+ rx: number;
+ ry: number;
+ rotation: number;
+ large: number;
+ sweep: number;
+ x: number;
+ y: number;
+ }
+ | {type: 'Z'};
+
+/**
+ * Parse an SVG path d-string into an array of absolute commands.
+ * Normalizes H/V → L for uniform processing.
+ */
+function parsePath(d: string): PathCommand[] {
+ const commands: PathCommand[] = [];
+ // Match command letter + all following numbers (including negatives and decimals)
+ const re = /([MmLlHhVvCcSsQqTtAaZz])([^MmLlHhVvCcSsQqTtAaZz]*)/g;
+ let match: RegExpExecArray | null;
+ let cx = 0,
+ cy = 0; // current position
+ let sx = 0,
+ sy = 0; // subpath start
+
+ while ((match = re.exec(d)) !== null) {
+ const cmd = match[1];
+ const args = (match[2].match(/-?[\d.]+(?:e[+-]?\d+)?/gi) || []).map(Number);
+
+ switch (cmd) {
+ case 'M':
+ cx = args[0];
+ cy = args[1];
+ sx = cx;
+ sy = cy;
+ commands.push({type: 'M', x: cx, y: cy});
+ // Implicit L for additional coordinate pairs
+ for (let i = 2; i < args.length; i += 2) {
+ cx = args[i];
+ cy = args[i + 1];
+ commands.push({type: 'L', x: cx, y: cy});
+ }
+ break;
+ case 'm':
+ cx += args[0];
+ cy += args[1];
+ sx = cx;
+ sy = cy;
+ commands.push({type: 'M', x: cx, y: cy});
+ for (let i = 2; i < args.length; i += 2) {
+ cx += args[i];
+ cy += args[i + 1];
+ commands.push({type: 'L', x: cx, y: cy});
+ }
+ break;
+ case 'L':
+ for (let i = 0; i < args.length; i += 2) {
+ cx = args[i];
+ cy = args[i + 1];
+ commands.push({type: 'L', x: cx, y: cy});
+ }
+ break;
+ case 'l':
+ for (let i = 0; i < args.length; i += 2) {
+ cx += args[i];
+ cy += args[i + 1];
+ commands.push({type: 'L', x: cx, y: cy});
+ }
+ break;
+ case 'H':
+ for (let i = 0; i < args.length; i++) {
+ cx = args[i];
+ commands.push({type: 'L', x: cx, y: cy});
+ }
+ break;
+ case 'h':
+ for (let i = 0; i < args.length; i++) {
+ cx += args[i];
+ commands.push({type: 'L', x: cx, y: cy});
+ }
+ break;
+ case 'V':
+ for (let i = 0; i < args.length; i++) {
+ cy = args[i];
+ commands.push({type: 'L', x: cx, y: cy});
+ }
+ break;
+ case 'v':
+ for (let i = 0; i < args.length; i++) {
+ cy += args[i];
+ commands.push({type: 'L', x: cx, y: cy});
+ }
+ break;
+ case 'C':
+ for (let i = 0; i < args.length; i += 6) {
+ commands.push({
+ type: 'C',
+ x1: args[i],
+ y1: args[i + 1],
+ x2: args[i + 2],
+ y2: args[i + 3],
+ x: args[i + 4],
+ y: args[i + 5],
+ });
+ cx = args[i + 4];
+ cy = args[i + 5];
+ }
+ break;
+ case 'c':
+ for (let i = 0; i < args.length; i += 6) {
+ commands.push({
+ type: 'C',
+ x1: cx + args[i],
+ y1: cy + args[i + 1],
+ x2: cx + args[i + 2],
+ y2: cy + args[i + 3],
+ x: cx + args[i + 4],
+ y: cy + args[i + 5],
+ });
+ cx += args[i + 4];
+ cy += args[i + 5];
+ }
+ break;
+ case 'Q':
+ for (let i = 0; i < args.length; i += 4) {
+ commands.push({
+ type: 'Q',
+ cx: args[i],
+ cy: args[i + 1],
+ x: args[i + 2],
+ y: args[i + 3],
+ });
+ cx = args[i + 2];
+ cy = args[i + 3];
+ }
+ break;
+ case 'q':
+ for (let i = 0; i < args.length; i += 4) {
+ commands.push({
+ type: 'Q',
+ cx: cx + args[i],
+ cy: cy + args[i + 1],
+ x: cx + args[i + 2],
+ y: cy + args[i + 3],
+ });
+ cx += args[i + 2];
+ cy += args[i + 3];
+ }
+ break;
+ case 'A':
+ case 'a': {
+ const rel = cmd === 'a';
+ for (let i = 0; i < args.length; i += 7) {
+ const nx = rel ? cx + args[i + 5] : args[i + 5];
+ const ny = rel ? cy + args[i + 6] : args[i + 6];
+ commands.push({
+ type: 'A',
+ rx: args[i],
+ ry: args[i + 1],
+ rotation: args[i + 2],
+ large: args[i + 3],
+ sweep: args[i + 4],
+ x: nx,
+ y: ny,
+ });
+ cx = nx;
+ cy = ny;
+ }
+ break;
+ }
+ case 'S':
+ case 's':
+ // Smooth cubic — convert to C (simplified: treat as C with reflected control point)
+ // For our purposes, pass through as-is since we mainly transform L→L corners
+ break;
+ case 'T':
+ case 't':
+ // Smooth quadratic — similar, pass through
+ break;
+ case 'Z':
+ case 'z':
+ commands.push({type: 'Z'});
+ cx = sx;
+ cy = sy;
+ break;
+ }
+ }
+
+ return commands;
+}
+
+// =============================================================================
+// Utilities
+// =============================================================================
+
+function dist(a: Point, b: Point): number {
+ return Math.sqrt((b.x - a.x) ** 2 + (b.y - a.y) ** 2);
+}
+
+function lerp(a: Point, b: Point, t: number): Point {
+ return {x: a.x + (b.x - a.x) * t, y: a.y + (b.y - a.y) * t};
+}
+
+function angleBetween(v1: Point, v2: Point): number {
+ const dot = v1.x * v2.x + v1.y * v2.y;
+ const mag1 = Math.sqrt(v1.x ** 2 + v1.y ** 2);
+ const mag2 = Math.sqrt(v2.x ** 2 + v2.y ** 2);
+ if (mag1 === 0 || mag2 === 0) return Math.PI;
+ return Math.acos(Math.max(-1, Math.min(1, dot / (mag1 * mag2))));
+}
+
+function getEndpoint(cmd: PathCommand): Point | null {
+ if (cmd.type === 'Z') return null;
+ return {x: cmd.x, y: cmd.y};
+}
+
+// =============================================================================
+// Corner Rounding
+// =============================================================================
+
+/**
+ * Round corners at L→L junctions by inserting quadratic bezier curves.
+ *
+ * @param d - SVG path d-string
+ * @param cornerRounding - 0-1 percentile. 0 = sharp (no change). 1 = max rounding.
+ * @returns Modified d-string with rounded corners
+ */
+export function roundCorners(d: string, cornerRounding: number): string {
+ if (cornerRounding <= 0) return d;
+ cornerRounding = Math.min(1, cornerRounding);
+
+ const cmds = parsePath(d);
+ const result: PathCommand[] = [];
+
+ // Pre-pass: find the last L before each Z to handle closed path corners
+ // We need to round: last-L → Z → M (the closing corner)
+ // and also: M → first-L (the opening corner, if preceded by Z-closed path)
+
+ for (let i = 0; i < cmds.length; i++) {
+ const prev = i > 0 ? cmds[i - 1] : null;
+ const curr = cmds[i];
+ const next = i < cmds.length - 1 ? cmds[i + 1] : null;
+
+ // Handle Z: insert rounding for the closing corner
+ // The corner is: last point → subpath start (M) → first L after M
+ if (curr.type === 'Z' && prev && (prev.type === 'L' || prev.type === 'Q')) {
+ // Find the M that started this subpath
+ let mIdx = i - 1;
+ while (mIdx >= 0 && cmds[mIdx].type !== 'M') mIdx--;
+ if (mIdx >= 0) {
+ const mCmd = cmds[mIdx];
+ const mPt = getEndpoint(mCmd)!;
+ const prevPt = getEndpoint(prev)!;
+ // Find the first L after M
+ let firstL = mIdx + 1;
+ while (firstL < cmds.length && cmds[firstL].type !== 'L') firstL++;
+ if (firstL < cmds.length) {
+ const firstLPt = getEndpoint(cmds[firstL])!;
+
+ const d1 = dist(prevPt, mPt);
+ const d2 = dist(mPt, firstLPt);
+ const maxR = Math.min(d1, d2) / 2;
+
+ const v1: Point = {x: prevPt.x - mPt.x, y: prevPt.y - mPt.y};
+ const v2: Point = {x: firstLPt.x - mPt.x, y: firstLPt.y - mPt.y};
+ const ang = angleBetween(v1, v2);
+ const sharp = 1 - ang / Math.PI;
+ const r = maxR * cornerRounding * sharp * 0.85;
+
+ if (r >= 0.1) {
+ const t1 = r / d1;
+ const t2 = r / d2;
+ const pb1 = lerp(mPt, prevPt, t1);
+ const pb2 = lerp(mPt, firstLPt, t2);
+
+ // Insert L to pull-back, Q through M, then Z
+ result.push({type: 'L', x: pb1.x, y: pb1.y});
+ result.push({type: 'Q', cx: mPt.x, cy: mPt.y, x: pb2.x, y: pb2.y});
+ result.push({type: 'Z'});
+ continue;
+ }
+ }
+ }
+ result.push(curr);
+ continue;
+ }
+
+ // Only round L commands that have L or M before and L or Z after
+ if (
+ curr.type === 'L' &&
+ prev &&
+ (prev.type === 'L' || prev.type === 'M' || prev.type === 'Q') &&
+ next &&
+ (next.type === 'L' || next.type === 'Z')
+ ) {
+ const prevPt = getEndpoint(prev)!;
+ const cornerPt: Point = {x: curr.x, y: curr.y};
+ const nextPt =
+ next.type === 'Z'
+ ? getEndpoint(cmds.find(c => c.type === 'M')!)!
+ : getEndpoint(next)!;
+
+ const d1 = dist(prevPt, cornerPt);
+ const d2 = dist(cornerPt, nextPt);
+ const maxRadius = Math.min(d1, d2) / 2;
+
+ // Compute angle to determine sharpness
+ const v1: Point = {x: prevPt.x - cornerPt.x, y: prevPt.y - cornerPt.y};
+ const v2: Point = {x: nextPt.x - cornerPt.x, y: nextPt.y - cornerPt.y};
+ const angle = angleBetween(v1, v2);
+
+ // Proportional rounding: sharper corners round MORE, gentle corners round LESS.
+ //
+ // Sharpness = 1 - (angle / π). Range: 0 (flat/180°) to 1 (fully acute/0°).
+ // Linear scaling with sharpness — at cornerRounding=1, a 90° corner
+ // uses 50% of maxRadius. Gentler corners get proportionally less.
+ // The 0.85 multiplier prevents full radius (which would make very
+ // short segments disappear) while still being visually bold.
+ const sharpness = 1 - angle / Math.PI;
+ const radius = maxRadius * cornerRounding * sharpness * 0.85;
+
+ if (radius < 0.1) {
+ // Too small to round, keep original
+ result.push(curr);
+ continue;
+ }
+
+ // Pull back from corner along each segment
+ const t1 = radius / d1;
+ const t2 = radius / d2;
+ const pullBack1 = lerp(cornerPt, prevPt, t1);
+ const pullBack2 = lerp(cornerPt, nextPt, t2);
+
+ // L to the pull-back point, then Q through the corner to the other pull-back
+ result.push({type: 'L', x: pullBack1.x, y: pullBack1.y});
+ result.push({
+ type: 'Q',
+ cx: cornerPt.x,
+ cy: cornerPt.y,
+ x: pullBack2.x,
+ y: pullBack2.y,
+ });
+ } else {
+ result.push(curr);
+ }
+ }
+
+ return serializePath(result);
+}
+
+// =============================================================================
+// Segment Curvature
+// =============================================================================
+
+/**
+ * Bow straight line segments by replacing L with Q.
+ *
+ * @param d - SVG path d-string
+ * @param curvature - 0-1 percentile. 0 = straight. 1 = max bow.
+ * @returns Modified d-string with curved segments
+ */
+export function addCurvature(d: string, curvature: number): string {
+ if (curvature <= 0) return d;
+ curvature = Math.min(1, curvature);
+
+ const cmds = parsePath(d);
+ const result: PathCommand[] = [];
+
+ for (let i = 0; i < cmds.length; i++) {
+ const prev = i > 0 ? cmds[i - 1] : null;
+ const curr = cmds[i];
+
+ if (curr.type === 'L' && prev) {
+ const prevPt = getEndpoint(prev);
+ if (!prevPt) {
+ result.push(curr);
+ continue;
+ }
+
+ const endPt: Point = {x: curr.x, y: curr.y};
+ const segLen = dist(prevPt, endPt);
+
+ // Only bow segments longer than a threshold
+ if (segLen < 2) {
+ result.push(curr);
+ continue;
+ }
+
+ // Midpoint
+ const mid = lerp(prevPt, endPt, 0.5);
+
+ // Perpendicular direction
+ const dx = endPt.x - prevPt.x;
+ const dy = endPt.y - prevPt.y;
+ const perpX = -dy / segLen;
+ const perpY = dx / segLen;
+
+ // Offset = segment length × curvature × scale factor
+ const offset = segLen * curvature * 0.25;
+
+ // Control point offset perpendicular to the line
+ const cp: Point = {
+ x: mid.x + perpX * offset,
+ y: mid.y + perpY * offset,
+ };
+
+ result.push({type: 'Q', cx: cp.x, cy: cp.y, x: endPt.x, y: endPt.y});
+ } else {
+ result.push(curr);
+ }
+ }
+
+ return serializePath(result);
+}
+
+// =============================================================================
+// Tension
+// =============================================================================
+
+/**
+ * Adjust tension on existing bezier curves.
+ *
+ * @param d - SVG path d-string
+ * @param tension - 0-1. 0 = loose (curves balloon). 0.5 = unchanged. 1 = tight.
+ * @returns Modified d-string
+ */
+export function adjustTension(d: string, tension: number): string {
+ if (tension === 0.5) return d;
+
+ const cmds = parsePath(d);
+ const result: PathCommand[] = [];
+ // Scale factor: tension 0 → 1.5 (looser), tension 0.5 → 1.0, tension 1 → 0.5 (tighter)
+ const scale = 1.5 - tension;
+
+ for (let i = 0; i < cmds.length; i++) {
+ const prev = i > 0 ? cmds[i - 1] : null;
+ const curr = cmds[i];
+
+ if (curr.type === 'C' && prev) {
+ const start = getEndpoint(prev) || {x: 0, y: 0};
+ const end: Point = {x: curr.x, y: curr.y};
+
+ // Scale control points relative to their anchor
+ const cp1: Point = {
+ x: start.x + (curr.x1 - start.x) * scale,
+ y: start.y + (curr.y1 - start.y) * scale,
+ };
+ const cp2: Point = {
+ x: end.x + (curr.x2 - end.x) * scale,
+ y: end.y + (curr.y2 - end.y) * scale,
+ };
+
+ result.push({
+ type: 'C',
+ x1: cp1.x,
+ y1: cp1.y,
+ x2: cp2.x,
+ y2: cp2.y,
+ x: end.x,
+ y: end.y,
+ });
+ } else if (curr.type === 'Q' && prev) {
+ const start = getEndpoint(prev) || {x: 0, y: 0};
+ const end: Point = {x: curr.x, y: curr.y};
+ const mid = lerp(start, end, 0.5);
+
+ // Scale control point relative to the midpoint of the chord
+ const cp: Point = {
+ x: mid.x + (curr.cx - mid.x) * scale,
+ y: mid.y + (curr.cy - mid.y) * scale,
+ };
+
+ result.push({type: 'Q', cx: cp.x, cy: cp.y, x: end.x, y: end.y});
+ } else {
+ result.push(curr);
+ }
+ }
+
+ return serializePath(result);
+}
+
+// =============================================================================
+// Combined Transform
+// =============================================================================
+
+export interface PathPersonality {
+ cornerRounding?: number;
+ segmentCurvature?: number;
+ tension?: number;
+}
+
+/**
+ * Apply all personality transforms to a path d-string.
+ * Order: corner rounding → segment curvature → tension.
+ */
+export function applyPersonality(
+ d: string,
+ personality: PathPersonality,
+): string {
+ let result = d;
+ if (personality.cornerRounding != null && personality.cornerRounding > 0) {
+ result = roundCorners(result, personality.cornerRounding);
+ }
+ if (
+ personality.segmentCurvature != null &&
+ personality.segmentCurvature > 0
+ ) {
+ result = addCurvature(result, personality.segmentCurvature);
+ }
+ if (personality.tension != null && personality.tension !== 0.5) {
+ result = adjustTension(result, personality.tension);
+ }
+ return result;
+}
+
+// =============================================================================
+// Serializer
+// =============================================================================
+
+function n(v: number): string {
+ return Number(v.toFixed(3)).toString();
+}
+
+function serializePath(cmds: PathCommand[]): string {
+ return cmds
+ .map(cmd => {
+ switch (cmd.type) {
+ case 'M':
+ return `M${n(cmd.x)} ${n(cmd.y)}`;
+ case 'L':
+ return `L${n(cmd.x)} ${n(cmd.y)}`;
+ case 'C':
+ return `C${n(cmd.x1)} ${n(cmd.y1)} ${n(cmd.x2)} ${n(cmd.y2)} ${n(cmd.x)} ${n(cmd.y)}`;
+ case 'Q':
+ return `Q${n(cmd.cx)} ${n(cmd.cy)} ${n(cmd.x)} ${n(cmd.y)}`;
+ case 'A':
+ return `A${n(cmd.rx)} ${n(cmd.ry)} ${n(cmd.rotation)} ${cmd.large} ${cmd.sweep} ${n(cmd.x)} ${n(cmd.y)}`;
+ case 'Z':
+ return 'Z';
+ }
+ })
+ .join(' ');
+}
diff --git a/packages/lab/src/SVGIcon/xif-examples.ts b/packages/lab/src/SVGIcon/xif-examples.ts
new file mode 100644
index 0000000000..cc82a3581f
--- /dev/null
+++ b/packages/lab/src/SVGIcon/xif-examples.ts
@@ -0,0 +1,189 @@
+/**
+ * @file xif-examples.ts
+ * @description Example icons demonstrating XIF spec features
+ *
+ * Each example showcases a different capability:
+ * - Simple stroke-only (check)
+ * - Two-layer with bold knockout (home)
+ * - Composable with slots (file, shield)
+ * - Animated (bell)
+ * - Personality override (star)
+ * - Bold geometry override (bell-override)
+ */
+
+import type {XIFIcon} from './xif-types';
+
+// =============================================================================
+// Simple stroke-only
+// =============================================================================
+
+export const xifCheck: XIFIcon = {
+ name: 'check',
+ paths: [{type: 'path', attrs: {d: 'M5 13l4 4L19 7'}, role: 'stroke'}],
+ tags: ['action', 'confirm'],
+};
+
+// =============================================================================
+// Two-layer with bold knockout
+// =============================================================================
+
+export const xifHome: XIFIcon = {
+ name: 'home',
+ paths: [
+ {
+ 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',
+ layer: 'primary',
+ },
+ {
+ type: 'path',
+ attrs: {d: 'M15 21v-8a1 1 0 0 0-1-1h-4a1 1 0 0 0-1 1v8'},
+ role: 'fill',
+ layer: 'secondary',
+ },
+ ],
+ tags: ['navigation'],
+};
+
+// =============================================================================
+// Composable icon with slot
+// =============================================================================
+
+export const xifFile: XIFIcon = {
+ name: 'file',
+ paths: [
+ {
+ type: 'path',
+ attrs: {
+ d: 'M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z',
+ },
+ role: 'fill',
+ layer: 'primary',
+ },
+ {
+ type: 'path',
+ attrs: {d: 'M14 2v4a2 2 0 0 0 2 2h4'},
+ role: 'stroke',
+ layer: 'secondary',
+ },
+ ],
+ slots: [{name: 'badge', position: {x: 0.5, y: 0.65}, size: 0.35}],
+ tags: ['file', 'document'],
+};
+
+export const xifShield: XIFIcon = {
+ name: 'shield',
+ paths: [
+ {
+ 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',
+ layer: 'primary',
+ },
+ ],
+ slots: [{name: 'badge', position: 'center', size: 0.42}],
+ tags: ['security', 'protection'],
+};
+
+// =============================================================================
+// Animated icon
+// =============================================================================
+
+export const xifBell: XIFIcon = {
+ name: 'bell',
+ paths: [
+ {
+ type: 'path',
+ attrs: {d: 'M6 8a6 6 0 0 1 12 0c0 7 3 9 3 9H3s3-2 3-9'},
+ role: 'fill',
+ layer: 'primary',
+ animate: {type: 'scale', sequence: 1},
+ },
+ {
+ type: 'path',
+ attrs: {d: 'M10.3 21a1.94 1.94 0 0 0 3.4 0'},
+ role: 'stroke',
+ layer: 'secondary',
+ animate: {type: 'draw', sequence: 2},
+ },
+ ],
+ tags: ['notification', 'alert'],
+};
+
+// =============================================================================
+// Personality override — star keeps sharp points
+// =============================================================================
+
+export const xifStar: XIFIcon = {
+ name: 'star',
+ paths: [
+ {
+ 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',
+ layer: 'primary',
+ personality: {cornerRounding: 0},
+ },
+ ],
+ tags: ['rating', 'favorite'],
+};
+
+// =============================================================================
+// Bold geometry override
+// =============================================================================
+
+export const xifBellOverride: XIFIcon = {
+ name: 'bell-override',
+ paths: [
+ {
+ type: 'path',
+ attrs: {d: 'M6 8a6 6 0 0 1 12 0c0 7 3 9 3 9H3s3-2 3-9'},
+ role: 'fill',
+ layer: 'primary',
+ },
+ {
+ type: 'path',
+ attrs: {d: 'M10.3 21a1.94 1.94 0 0 0 3.4 0'},
+ role: 'stroke',
+ layer: 'secondary',
+ },
+ ],
+ overrides: {
+ bold: [
+ {
+ type: 'path',
+ attrs: {d: 'M6 8a6 6 0 0 1 12 0c0 7 3 9 3 9H3s3-2 3-9'},
+ role: 'fill',
+ layer: 'primary',
+ },
+ {
+ type: 'path',
+ attrs: {d: 'M10.3 21a1.94 1.94 0 0 0 3.4 0'},
+ role: 'fill',
+ layer: 'secondary',
+ },
+ ],
+ },
+ tags: ['notification'],
+};
+
+// =============================================================================
+// All examples
+// =============================================================================
+
+export const xifExamples: XIFIcon[] = [
+ xifCheck,
+ xifHome,
+ xifFile,
+ xifShield,
+ xifBell,
+ xifStar,
+ xifBellOverride,
+];
diff --git a/packages/lab/src/SVGIcon/xif-types.ts b/packages/lab/src/SVGIcon/xif-types.ts
new file mode 100644
index 0000000000..8b29878686
--- /dev/null
+++ b/packages/lab/src/SVGIcon/xif-types.ts
@@ -0,0 +1,179 @@
+/**
+ * @file xif-types.ts
+ * @description XDS Icon Format (XIF) type definitions — v0.1.0 draft
+ *
+ * Icons are pure structure — zero visual values. The theme resolves
+ * all visual properties (color, weight, rounding, timing).
+ *
+ * This file defines the SOURCE format types. The resolved/build output
+ * uses a simpler pre-computed format (see theme build pipeline).
+ */
+
+// =============================================================================
+// Personality
+// =============================================================================
+
+/**
+ * Percentile adjustment parameters for shape personality.
+ * All values 0-1. 0 = artist's original. 1 = maximum shift.
+ * Adjustments are RELATIVE — they preserve the artist's hierarchy
+ * of sharp vs soft, straight vs curved.
+ */
+export interface XIFPersonality {
+ /**
+ * Shift corners toward rounded.
+ * A sharp 90° corner shifts more than an already-gentle 150° corner.
+ * Formula: adjustedR = baseR + (maxR - baseR) × cornerRounding
+ */
+ cornerRounding?: number;
+
+ /**
+ * Shift straight segments toward curved.
+ * A straight line gains a bow; an existing curve barely changes.
+ * Formula: adjusted = original + (1 - original) × segmentCurvature
+ */
+ segmentCurvature?: number;
+
+ /**
+ * How tightly curves hug their control points.
+ * 0 = loose (curves balloon). 0.5 = neutral. 1 = tight (near-straight).
+ */
+ tension?: number;
+}
+
+// =============================================================================
+// Animation
+// =============================================================================
+
+/**
+ * Animation intent for a path element.
+ * Declares WHAT animates and in WHAT ORDER — not timing or easing.
+ * The theme resolves all visual animation properties.
+ */
+export interface XIFAnimate {
+ /**
+ * Semantic animation type.
+ * - draw: stroke reveals along path (dasharray/dashoffset)
+ * - fade: opacity entrance
+ * - scale: grow from center
+ * - rotate: continuous spin (loaders)
+ * - morph: interpolate between variation states
+ */
+ type: 'draw' | 'fade' | 'scale' | 'rotate' | 'morph';
+
+ /**
+ * Stagger order. Lower numbers animate first.
+ * Paths with the same sequence animate simultaneously.
+ */
+ sequence?: number;
+}
+
+// =============================================================================
+// Slots (Composition)
+// =============================================================================
+
+/**
+ * A named position where a sub-icon can be injected.
+ * The theme resolves position/size to actual viewBox coordinates.
+ */
+export interface XIFSlot {
+ /** Slot identifier — used in component props */
+ name: string;
+
+ /** Semantic position. Theme resolves to coordinates. */
+ position:
+ | 'center'
+ | 'top-left'
+ | 'top-right'
+ | 'bottom-left'
+ | 'bottom-right'
+ | {x: number; y: number}; // normalized 0-1 relative to viewBox
+
+ /**
+ * Size of the injected icon relative to parent.
+ * 'content' = auto-sized by theme. number = fraction of parent.
+ */
+ size?: 'content' | number;
+}
+
+// =============================================================================
+// Path Entry
+// =============================================================================
+
+/**
+ * A single shape element within an icon.
+ * Contains geometry + semantic metadata. Zero visual values.
+ */
+export interface XIFPath {
+ /** SVG element type. Default: 'path' */
+ type?:
+ | 'path'
+ | 'circle'
+ | 'rect'
+ | 'line'
+ | 'polyline'
+ | 'ellipse'
+ | 'polygon';
+
+ /** SVG geometry attributes (d, cx, cy, r, x, y, width, height, etc.) */
+ attrs: Record<string, string | number>;
+
+ /**
+ * Rendering behavior across variations.
+ * - 'fill': Closed shape — stroked in linear, filled in bold.
+ * - 'stroke': Line/detail — always rendered as a stroke.
+ * Default: 'fill'
+ */
+ role?: 'fill' | 'stroke';
+
+ /**
+ * Visual hierarchy for twotone/bulk and bold knockouts.
+ * - 'primary': Full opacity. In bold, rendered as solid fill.
+ * - 'secondary': Reduced opacity in twotone/bulk. Knocked out in bold.
+ * Default: 'primary'
+ */
+ layer?: 'primary' | 'secondary';
+
+ /** Per-path personality overrides (shift from theme/icon defaults) */
+ personality?: XIFPersonality;
+
+ /** Animation intent */
+ animate?: XIFAnimate;
+}
+
+// =============================================================================
+// Icon Definition
+// =============================================================================
+
+/**
+ * Root type for an XDS Icon Format definition.
+ * Pure structure — no visual values.
+ */
+export interface XIFIcon {
+ /** Unique identifier */
+ name: string;
+
+ /** ViewBox dimensions. Default: '0 0 24 24' */
+ viewBox?: string;
+
+ /** Shape elements that compose the icon */
+ paths: XIFPath[];
+
+ /**
+ * Per-variation geometry overrides.
+ * Rendered in DOM alongside default paths; CSS toggles visibility.
+ */
+ overrides?: {
+ bold?: XIFPath[];
+ broken?: XIFPath[];
+ };
+
+ /** Named slots for sub-icon composition */
+ slots?: XIFSlot[];
+
+ /** Icon-level personality overrides */
+ personality?: XIFPersonality;
+
+ /** Tags for search and categorization */
+ tags?: string[];
+}