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.tsxnew file mode 100644index 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: [{ name: 'badge', position:+ 'center', size: 0.42 }]+ </code>+ . At render time, the component scales and positions the badge icon+ into the slot. The badge inherits the parent'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'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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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[];+}