feat: add illustration theming via applyTheme prop

.gitignore

@@ -51,9 +51,13 @@ local.properties
 .nx
 .next
 cjs/
+!packages/illustrations/src/__generated__/**/svgJs/cjs/
+!packages/illustrations/src/__generated__/**/svgJs/cjs/**
 dts/
 lib/
 esm/
+!packages/illustrations/src/__generated__/**/svgJs/esm/
+!packages/illustrations/src/__generated__/**/svgJs/esm/**
 mjs/
 *.tsbuildinfo
 /.cache-loader

apps/docs/docs/components/inputs/IconButton/_mobileStyles.mdx

@@ -0,0 +1,7 @@
+import { ComponentStylesTable } from '@site/src/components/page/ComponentStylesTable';
+
+import mobileStylesData from ':docgen/mobile/buttons/IconButton/styles-data';
+
+## Selectors
+
+<ComponentStylesTable componentName="IconButton" styles={mobileStylesData} />

apps/docs/docs/components/inputs/IconButton/_webStyles.mdx

@@ -0,0 +1,21 @@
+import { ComponentStylesTable } from '@site/src/components/page/ComponentStylesTable';
+import { StylesExplorer } from '@site/src/components/page/StylesExplorer';
+import { IconButton } from '@coinbase/cds-web/buttons';
+
+import webStylesData from ':docgen/web/buttons/IconButton/styles-data';
+
+## Explorer
+
+<StylesExplorer selectors={webStylesData.selectors}>
+  {(classNames) => (
+    <IconButton
+      accessibilityLabel="Horizontal arrows"
+      classNames={classNames}
+      name="arrowsHorizontal"
+    />
+  )}
+</StylesExplorer>
+
+## Selectors
+
+<ComponentStylesTable componentName="IconButton" styles={webStylesData} />

apps/docs/docs/components/inputs/IconButton/index.mdx

@@ -16,6 +16,8 @@ import mobilePropsToc from ':docgen/mobile/buttons/IconButton/toc-props';
 
 import WebPropsTable from './_webPropsTable.mdx';
 import MobilePropsTable from './_mobilePropsTable.mdx';
+import WebStyles, { toc as webStylesToc } from './_webStyles.mdx';
+import MobileStyles, { toc as mobileStylesToc } from './_mobileStyles.mdx';
 import MobileExamples, { toc as mobileExamplesToc } from './_mobileExamples.mdx';
 import WebExamples, { toc as webExamplesToc } from './_webExamples.mdx';
 
@@ -27,18 +29,22 @@ import mobileMetadata from './mobileMetadata.json';
     title="IconButton"
     description="A button that renders an official icon as content instead of text."
     webMetadata={webMetadata}
-    mobileMetadata={mobileMetadata} 
+    mobileMetadata={mobileMetadata}
     banner={<IconButtonBanner />}
   />
 
   <ComponentTabsContainer
     webPropsTable={<WebPropsTable />}
+    webStyles={<WebStyles />}
     webExamples={<WebExamples />}
     mobilePropsTable={<MobilePropsTable />}
+    mobileStyles={<MobileStyles />}
     mobileExamples={<MobileExamples />}
     webExamplesToc={webExamplesToc}
     mobileExamplesToc={mobileExamplesToc}
     webPropsToc={webPropsToc}
+    webStylesToc={webStylesToc}
     mobilePropsToc={mobilePropsToc}
+    mobileStylesToc={mobileStylesToc}
   />
 </VStack>

apps/docs/docs/components/media/HeroSquare/_mobileExamples.mdx

@@ -21,3 +21,31 @@ If `dimension` and `scaleMultiplier` are both provided the component will scale
 ```jsx
 <HeroSquare name="accessToAdvancedCharts" dimension="200x200" scaleMultiplier={1.5} />
 ```
+
+## Theming
+
+Use the `applyTheme` prop to enable dynamic theming. When set, the illustration is colored by the active `ThemeProvider`'s illustration palette instead of using the hardcoded light or dark variant.
+
+To apply a custom brand palette, set `lightIllustrationColor` and `darkIllustrationColor` on your theme and wrap your content in a `ThemeProvider`:
+
+```jsx
+const customTheme = {
+  ...defaultTheme,
+  lightIllustrationColor: {
+    ...defaultTheme.lightIllustrationColor,
+    primary: 'rgb(220, 38, 38)',
+    accent1: 'rgb(124, 58, 237)',
+  },
+  darkIllustrationColor: {
+    ...defaultTheme.darkIllustrationColor,
+    primary: 'rgb(248, 113, 113)',
+    accent1: 'rgb(167, 139, 250)',
+  },
+};
+
+<ThemeProvider activeColorScheme="light" theme={customTheme}>
+  <HeroSquare applyTheme name="accessToAdvancedCharts" />
+</ThemeProvider>;
+```
+
+When `applyTheme` is not set (the default), the illustration uses the standard light or dark variant with hardcoded colors — no theming overhead.

apps/docs/docs/components/media/HeroSquare/_webExamples.mdx

@@ -21,3 +21,43 @@ If `dimension` and `scaleMultiplier` are both provided the component will scale
 ```jsx live
 <HeroSquare name="accessToAdvancedCharts" dimension="200x200" scaleMultiplier={1.5} />
 ```
+
+## Theming
+
+Use the `applyTheme` prop to enable dynamic theming. When set, the illustration is inlined into the page and colored by the active `ThemeProvider`'s illustration palette instead of loading a static image from the CDN.
+
+This allows the illustration to update automatically when the active color scheme changes, and to reflect a custom brand palette when a non-default theme is provided.
+
+```jsx live
+<HeroSquare applyTheme name="accessToAdvancedCharts" />
+```
+
+To apply a custom brand palette, set `lightIllustrationColor` and `darkIllustrationColor` on your theme and wrap the illustration in a `ThemeProvider`:
+
+```jsx live
+function ThemedHeroSquare() {
+  const customTheme = {
+    ...defaultTheme,
+    lightIllustrationColor: {
+      ...defaultTheme.lightIllustrationColor,
+      primary: 'rgb(220, 38, 38)',
+      accent1: 'rgb(124, 58, 237)',
+      accent2: 'rgb(16, 185, 129)',
+    },
+    darkIllustrationColor: {
+      ...defaultTheme.darkIllustrationColor,
+      primary: 'rgb(248, 113, 113)',
+      accent1: 'rgb(167, 139, 250)',
+      accent2: 'rgb(52, 211, 153)',
+    },
+  };
+
+  return (
+    <ThemeProvider activeColorScheme="light" theme={customTheme}>
+      <HeroSquare applyTheme name="accessToAdvancedCharts" />
+    </ThemeProvider>
+  );
+}
+```
+
+When `applyTheme` is not set (the default), the illustration loads as a standard `<img>` from the CDN with hardcoded colors — no performance overhead.

apps/docs/docs/components/media/Pictogram/_mobileExamples.mdx

@@ -21,3 +21,27 @@ If `dimension` and `scaleMultiplier` are both provided the component will scale
 ```jsx
 <Pictogram name="shield" dimension="48x48" scaleMultiplier={2.5} />
 ```
+
+## Theming
+
+Use the `applyTheme` prop to enable dynamic theming. When set, the illustration is colored by the active `ThemeProvider`'s illustration palette instead of using the hardcoded light or dark variant.
+
+```jsx
+const customTheme = {
+  ...defaultTheme,
+  lightIllustrationColor: {
+    ...defaultTheme.lightIllustrationColor,
+    primary: 'rgb(220, 38, 38)',
+    accent1: 'rgb(124, 58, 237)',
+  },
+  darkIllustrationColor: {
+    ...defaultTheme.darkIllustrationColor,
+    primary: 'rgb(248, 113, 113)',
+    accent1: 'rgb(167, 139, 250)',
+  },
+};
+
+<ThemeProvider activeColorScheme="light" theme={customTheme}>
+  <Pictogram applyTheme name="shield" />
+</ThemeProvider>;
+```

apps/docs/docs/components/media/Pictogram/_webExamples.mdx

@@ -21,3 +21,37 @@ If `dimension` and `scaleMultiplier` are both provided the component will scale
 ```jsx live
 <Pictogram name="shield" dimension="48x48" scaleMultiplier={2.5} />
 ```
+
+## Theming
+
+Use the `applyTheme` prop to enable dynamic theming. When set, the illustration is inlined into the page and colored by the active `ThemeProvider`'s illustration palette.
+
+```jsx live
+<Pictogram applyTheme name="shield" />
+```
+
+To apply a custom brand palette, set `lightIllustrationColor` and `darkIllustrationColor` on your theme:
+
+```jsx live
+function ThemedPictogram() {
+  const customTheme = {
+    ...defaultTheme,
+    lightIllustrationColor: {
+      ...defaultTheme.lightIllustrationColor,
+      primary: 'rgb(220, 38, 38)',
+      accent1: 'rgb(124, 58, 237)',
+    },
+    darkIllustrationColor: {
+      ...defaultTheme.darkIllustrationColor,
+      primary: 'rgb(248, 113, 113)',
+      accent1: 'rgb(167, 139, 250)',
+    },
+  };
+
+  return (
+    <ThemeProvider activeColorScheme="light" theme={customTheme}>
+      <Pictogram applyTheme name="shield" />
+    </ThemeProvider>
+  );
+}
+```

apps/docs/docs/components/media/SpotIcon/_mobileExamples.mdx

@@ -21,3 +21,27 @@ If `dimension` and `scaleMultiplier` are both provided the component will scale
 ```jsx
 <SpotIcon name="shield" dimension="24x24" scaleMultiplier={1.5} />
 ```
+
+## Theming
+
+Use the `applyTheme` prop to enable dynamic theming. When set, the illustration is colored by the active `ThemeProvider`'s illustration palette instead of using the hardcoded light or dark variant.
+
+```jsx
+const customTheme = {
+  ...defaultTheme,
+  lightIllustrationColor: {
+    ...defaultTheme.lightIllustrationColor,
+    primary: 'rgb(220, 38, 38)',
+    accent1: 'rgb(124, 58, 237)',
+  },
+  darkIllustrationColor: {
+    ...defaultTheme.darkIllustrationColor,
+    primary: 'rgb(248, 113, 113)',
+    accent1: 'rgb(167, 139, 250)',
+  },
+};
+
+<ThemeProvider activeColorScheme="light" theme={customTheme}>
+  <SpotIcon applyTheme name="shield" dimension="32x32" />
+</ThemeProvider>;
+```

apps/docs/docs/components/media/SpotIcon/_webExamples.mdx

@@ -21,3 +21,37 @@ If `dimension` and `scaleMultiplier` are both provided the component will scale
 ```jsx live
 <SpotIcon name="shield" dimension="24x24" scaleMultiplier={1.5} />
 ```
+
+## Theming
+
+Use the `applyTheme` prop to enable dynamic theming. When set, the illustration is inlined into the page and colored by the active `ThemeProvider`'s illustration palette.
+
+```jsx live
+<SpotIcon applyTheme name="shield" dimension="32x32" />
+```
+
+To apply a custom brand palette, set `lightIllustrationColor` and `darkIllustrationColor` on your theme:
+
+```jsx live
+function ThemedSpotIcon() {
+  const customTheme = {
+    ...defaultTheme,
+    lightIllustrationColor: {
+      ...defaultTheme.lightIllustrationColor,
+      primary: 'rgb(220, 38, 38)',
+      accent1: 'rgb(124, 58, 237)',
+    },
+    darkIllustrationColor: {
+      ...defaultTheme.darkIllustrationColor,
+      primary: 'rgb(248, 113, 113)',
+      accent1: 'rgb(167, 139, 250)',
+    },
+  };
+
+  return (
+    <ThemeProvider activeColorScheme="light" theme={customTheme}>
+      <SpotIcon applyTheme name="shield" dimension="32x32" />
+    </ThemeProvider>
+  );
+}
+```

apps/docs/docs/components/media/SpotRectangle/_mobileExamples.mdx

@@ -21,3 +21,27 @@ If `dimension` and `scaleMultiplier` are both provided the component will scale
 ```jsx
 <SpotRectangle name="creditCardExcitement" dimension="240x120" scaleMultiplier={1.5} />
 ```
+
+## Theming
+
+Use the `applyTheme` prop to enable dynamic theming. When set, the illustration is colored by the active `ThemeProvider`'s illustration palette instead of using the hardcoded light or dark variant.
+
+```jsx
+const customTheme = {
+  ...defaultTheme,
+  lightIllustrationColor: {
+    ...defaultTheme.lightIllustrationColor,
+    primary: 'rgb(220, 38, 38)',
+    accent1: 'rgb(124, 58, 237)',
+  },
+  darkIllustrationColor: {
+    ...defaultTheme.darkIllustrationColor,
+    primary: 'rgb(248, 113, 113)',
+    accent1: 'rgb(167, 139, 250)',
+  },
+};
+
+<ThemeProvider activeColorScheme="light" theme={customTheme}>
+  <SpotRectangle applyTheme name="creditCardExcitement" />
+</ThemeProvider>;
+```

apps/docs/docs/components/media/SpotRectangle/_webExamples.mdx

@@ -21,3 +21,37 @@ If `dimension` and `scaleMultiplier` are both provided the component will scale
 ```jsx live
 <SpotRectangle name="creditCardExcitement" dimension="240x120" scaleMultiplier={1.5} />
 ```
+
+## Theming
+
+Use the `applyTheme` prop to enable dynamic theming. When set, the illustration is inlined into the page and colored by the active `ThemeProvider`'s illustration palette.
+
+```jsx live
+<SpotRectangle applyTheme name="creditCardExcitement" />
+```
+
+To apply a custom brand palette, set `lightIllustrationColor` and `darkIllustrationColor` on your theme:
+
+```jsx live
+function ThemedSpotRectangle() {
+  const customTheme = {
+    ...defaultTheme,
+    lightIllustrationColor: {
+      ...defaultTheme.lightIllustrationColor,
+      primary: 'rgb(220, 38, 38)',
+      accent1: 'rgb(124, 58, 237)',
+    },
+    darkIllustrationColor: {
+      ...defaultTheme.darkIllustrationColor,
+      primary: 'rgb(248, 113, 113)',
+      accent1: 'rgb(167, 139, 250)',
+    },
+  };
+
+  return (
+    <ThemeProvider activeColorScheme="light" theme={customTheme}>
+      <SpotRectangle applyTheme name="creditCardExcitement" />
+    </ThemeProvider>
+  );
+}
+```

apps/docs/docs/components/media/SpotSquare/_mobileExamples.mdx

@@ -21,3 +21,27 @@ If `dimension` and `scaleMultiplier` are both provided the component will scale
 ```jsx
 <SpotSquare name="yieldCenterUSDC" dimension="120x120" scaleMultiplier={1.5} />
 ```
+
+## Theming
+
+Use the `applyTheme` prop to enable dynamic theming. When set, the illustration is colored by the active `ThemeProvider`'s illustration palette instead of using the hardcoded light or dark variant.
+
+```jsx
+const customTheme = {
+  ...defaultTheme,
+  lightIllustrationColor: {
+    ...defaultTheme.lightIllustrationColor,
+    primary: 'rgb(220, 38, 38)',
+    accent1: 'rgb(124, 58, 237)',
+  },
+  darkIllustrationColor: {
+    ...defaultTheme.darkIllustrationColor,
+    primary: 'rgb(248, 113, 113)',
+    accent1: 'rgb(167, 139, 250)',
+  },
+};
+
+<ThemeProvider activeColorScheme="light" theme={customTheme}>
+  <SpotSquare applyTheme name="yieldCenterUSDC" />
+</ThemeProvider>;
+```