@bethinkpl/design-system 37.1.0 → 38.0.0

package/dist/lib/js/components/Buttons/Button/Button.consts.d.ts

@@ -18,6 +18,7 @@ export declare const BUTTON_COLORS: {
     readonly DANGER: "danger";
     readonly SUCCESS: "success";
     readonly INVERTED: "inverted";
+    readonly MAGIC: "magic";
 };
 export type ButtonColor = Value<typeof BUTTON_COLORS>;
 export declare const BUTTON_RADIUSES: {

package/dist/lib/js/components/Buttons/Button/useMagicGradient.d.ts

@@ -0,0 +1,5 @@
+import { MaybeRefOrGetter } from 'vue';
+
+export declare const GRADIENT_MAGIC_ICON_ID = "ds-gradient-magic-icon";
+export declare const GRADIENT_MAGIC_ICON_DISABLED_ID = "ds-gradient-magic-icon-disabled";
+export declare function useMagicGradient(enabled: MaybeRefOrGetter<boolean>): void;

package/dist/lib/js/components/Buttons/IconButton/IconButton.consts.d.ts

@@ -29,6 +29,7 @@ export declare const ICON_BUTTON_COLORS: {
     readonly INVERTED: "inverted";
     readonly WARNING: "warning";
     readonly INFO: "info";
+    readonly MAGIC: "magic";
 };
 export type IconButtonColor = Value<typeof ICON_BUTTON_COLORS>;
 export declare const ICON_BUTTON_STATES: {

package/dist/lib/js/components/Buttons/IconButton/IconButton.vue.d.ts

@@ -1,5 +1,5 @@
-import { ButtonElevation, ButtonRadius } from '../Button';
-import { ICON_BUTTON_STATES, IconButtonColor, IconButtonColorScheme, IconButtonSize, IconButtonType } from './IconButton.consts';
+import { ButtonElevation, ButtonRadius, ButtonState } from '../Button';
+import { ICON_BUTTON_STATES, IconButtonColor, IconButtonColorScheme, IconButtonSize, IconButtonState, IconButtonType } from './IconButton.consts';
 import { Value } from '../../../utils/type.utils';
 
 declare const _default: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
@@ -48,6 +48,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
         validator(value: Value<typeof ICON_BUTTON_STATES>): boolean;
     };
 }>, {
+    ICON_BUTTON_STATE_MAP: Record<IconButtonState, ButtonState>;
     isHovered: import('vue').Ref<boolean>;
     mouseOver: () => void;
     mouseLeave: () => void;
@@ -371,6 +372,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
         readonly INVERTED: "inverted";
         readonly WARNING: "warning";
         readonly INFO: "info";
+        readonly MAGIC: "magic";
     }>;
     BUTTON_COLORS: Readonly<{
         readonly PRIMARY: "primary";
@@ -378,6 +380,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
         readonly DANGER: "danger";
         readonly SUCCESS: "success";
         readonly INVERTED: "inverted";
+        readonly MAGIC: "magic";
     }>;
 }, {
     iconSize(): string;

package/dist/lib/js/components/Drawer/DrawerHeader/DrawerHeader.vue.d.ts

@@ -693,6 +693,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
             validator(value: import('../../../utils/type.utils').Value<typeof import('../../Buttons/IconButton').ICON_BUTTON_STATES>): boolean;
         };
     }>, {
+        ICON_BUTTON_STATE_MAP: Record<import('../../Buttons/IconButton').IconButtonState, import('../../Buttons/Button').ButtonState>;
         isHovered: import('vue').Ref<boolean>;
         mouseOver: () => void;
         mouseLeave: () => void;
@@ -1016,6 +1017,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
             readonly INVERTED: "inverted";
             readonly WARNING: "warning";
             readonly INFO: "info";
+            readonly MAGIC: "magic";
         }>;
         BUTTON_COLORS: Readonly<{
             readonly PRIMARY: "primary";
@@ -1023,6 +1025,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
             readonly DANGER: "danger";
             readonly SUCCESS: "success";
             readonly INVERTED: "inverted";
+            readonly MAGIC: "magic";
         }>;
     }, {
         iconSize(): string;

package/dist/lib/js/components/Drawer/DrawerSection/DrawerSection.vue.d.ts

@@ -70,6 +70,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
         readonly INVERTED: "inverted";
         readonly WARNING: "warning";
         readonly INFO: "info";
+        readonly MAGIC: "magic";
     };
     ICON_BUTTON_SIZES: {
         readonly XX_SMALL: "xx-small";
@@ -806,6 +807,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
             readonly INVERTED: "inverted";
             readonly WARNING: "warning";
             readonly INFO: "info";
+            readonly MAGIC: "magic";
         }>;
         SECTION_HEADER_MOBILE_LAYOUTS: Readonly<{
             readonly VERTICAL: "vertical";
@@ -1027,6 +1029,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
                 validator(value: import('../../../utils/type.utils').Value<typeof import('../../Buttons/IconButton').ICON_BUTTON_STATES>): boolean;
             };
         }>, {
+            ICON_BUTTON_STATE_MAP: Record<import('../../Buttons/IconButton').IconButtonState, import('../../..').ButtonState>;
             isHovered: import('vue').Ref<boolean>;
             mouseOver: () => void;
             mouseLeave: () => void;
@@ -1350,6 +1353,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
                 readonly INVERTED: "inverted";
                 readonly WARNING: "warning";
                 readonly INFO: "info";
+                readonly MAGIC: "magic";
             }>;
             BUTTON_COLORS: Readonly<{
                 readonly PRIMARY: "primary";
@@ -1357,6 +1361,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
                 readonly DANGER: "danger";
                 readonly SUCCESS: "success";
                 readonly INVERTED: "inverted";
+                readonly MAGIC: "magic";
             }>;
         }, {
             iconSize(): string;

package/dist/lib/js/components/Headers/OverlayHeader/OverlayHeader.vue.d.ts

@@ -58,6 +58,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
         readonly INVERTED: "inverted";
         readonly WARNING: "warning";
         readonly INFO: "info";
+        readonly MAGIC: "magic";
     }>;
     ICON_BUTTON_STATES: Readonly<{
         readonly DEFAULT: "default";
@@ -469,6 +470,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
             validator(value: Value<typeof ICON_BUTTON_STATES>): boolean;
         };
     }>, {
+        ICON_BUTTON_STATE_MAP: Record<import('../../Buttons/IconButton').IconButtonState, import('../../..').ButtonState>;
         isHovered: import('vue').Ref<boolean>;
         mouseOver: () => void;
         mouseLeave: () => void;
@@ -792,6 +794,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
             readonly INVERTED: "inverted";
             readonly WARNING: "warning";
             readonly INFO: "info";
+            readonly MAGIC: "magic";
         }>;
         BUTTON_COLORS: Readonly<{
             readonly PRIMARY: "primary";
@@ -799,6 +802,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
             readonly DANGER: "danger";
             readonly SUCCESS: "success";
             readonly INVERTED: "inverted";
+            readonly MAGIC: "magic";
         }>;
     }, {
         iconSize(): string;

package/dist/lib/js/components/Headers/SectionHeader/SectionHeader.vue.d.ts

@@ -370,6 +370,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
         readonly INVERTED: "inverted";
         readonly WARNING: "warning";
         readonly INFO: "info";
+        readonly MAGIC: "magic";
     }>;
     SECTION_HEADER_MOBILE_LAYOUTS: Readonly<{
         readonly VERTICAL: "vertical";
@@ -591,6 +592,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
             validator(value: import('../../../utils/type.utils').Value<typeof import('../../Buttons/IconButton').ICON_BUTTON_STATES>): boolean;
         };
     }>, {
+        ICON_BUTTON_STATE_MAP: Record<import('../../Buttons/IconButton').IconButtonState, import('../../..').ButtonState>;
         isHovered: import('vue').Ref<boolean>;
         mouseOver: () => void;
         mouseLeave: () => void;
@@ -914,6 +916,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
             readonly INVERTED: "inverted";
             readonly WARNING: "warning";
             readonly INFO: "info";
+            readonly MAGIC: "magic";
         }>;
         BUTTON_COLORS: Readonly<{
             readonly PRIMARY: "primary";
@@ -921,6 +924,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
             readonly DANGER: "danger";
             readonly SUCCESS: "success";
             readonly INVERTED: "inverted";
+            readonly MAGIC: "magic";
         }>;
     }, {
         iconSize(): string;

package/dist/lib/js/components/Modals/Modal/Modal.vue.d.ts

@@ -104,6 +104,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
         readonly DANGER: "danger";
         readonly SUCCESS: "success";
         readonly INVERTED: "inverted";
+        readonly MAGIC: "magic";
     };
     BUTTON_ELEVATIONS: {
         readonly NONE: "none";
@@ -399,6 +400,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
         readonly INVERTED: "inverted";
         readonly WARNING: "warning";
         readonly INFO: "info";
+        readonly MAGIC: "magic";
     };
     ICON_SIZES: {
         XXX_SMALL: string;
@@ -721,6 +723,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
             validator(value: import('../../../utils/type.utils').Value<typeof import('../../Buttons/IconButton').ICON_BUTTON_STATES>): boolean;
         };
     }>, {
+        ICON_BUTTON_STATE_MAP: Record<import('../../Buttons/IconButton').IconButtonState, ButtonState>;
         isHovered: import('vue').Ref<boolean>;
         mouseOver: () => void;
         mouseLeave: () => void;
@@ -1044,6 +1047,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
             readonly INVERTED: "inverted";
             readonly WARNING: "warning";
             readonly INFO: "info";
+            readonly MAGIC: "magic";
         }>;
         BUTTON_COLORS: Readonly<{
             readonly PRIMARY: "primary";
@@ -1051,6 +1055,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
             readonly DANGER: "danger";
             readonly SUCCESS: "success";
             readonly INVERTED: "inverted";
+            readonly MAGIC: "magic";
         }>;
     }, {
         iconSize(): string;

package/dist/lib/js/components/Modals/ModalDialog/ModalDialog.vue.d.ts

@@ -239,6 +239,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
             readonly DANGER: "danger";
             readonly SUCCESS: "success";
             readonly INVERTED: "inverted";
+            readonly MAGIC: "magic";
         };
         BUTTON_ELEVATIONS: {
             readonly NONE: "none";
@@ -534,6 +535,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
             readonly INVERTED: "inverted";
             readonly WARNING: "warning";
             readonly INFO: "info";
+            readonly MAGIC: "magic";
         };
         ICON_SIZES: {
             XXX_SMALL: string;
@@ -856,6 +858,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
                 validator(value: import('../../../utils/type.utils').Value<typeof import('../../..').ICON_BUTTON_STATES>): boolean;
             };
         }>, {
+            ICON_BUTTON_STATE_MAP: Record<import('../../..').IconButtonState, ButtonState>;
             isHovered: import('vue').Ref<boolean>;
             mouseOver: () => void;
             mouseLeave: () => void;
@@ -1179,6 +1182,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
                 readonly INVERTED: "inverted";
                 readonly WARNING: "warning";
                 readonly INFO: "info";
+                readonly MAGIC: "magic";
             }>;
             BUTTON_COLORS: Readonly<{
                 readonly PRIMARY: "primary";
@@ -1186,6 +1190,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
                 readonly DANGER: "danger";
                 readonly SUCCESS: "success";
                 readonly INVERTED: "inverted";
+                readonly MAGIC: "magic";
             }>;
         }, {
             iconSize(): string;

package/dist/lib/js/components/Pagination/Pagination.vue.d.ts

@@ -52,6 +52,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
         readonly INVERTED: "inverted";
         readonly WARNING: "warning";
         readonly INFO: "info";
+        readonly MAGIC: "magic";
     }>;
     ICON_BUTTON_STATES: Readonly<{
         readonly DEFAULT: "default";
@@ -423,6 +424,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
             validator(value: import('../../utils/type.utils').Value<typeof ICON_BUTTON_STATES>): boolean;
         };
     }>, {
+        ICON_BUTTON_STATE_MAP: Record<import('../Buttons/IconButton').IconButtonState, import('../..').ButtonState>;
         isHovered: import('vue').Ref<boolean>;
         mouseOver: () => void;
         mouseLeave: () => void;
@@ -746,6 +748,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
             readonly INVERTED: "inverted";
             readonly WARNING: "warning";
             readonly INFO: "info";
+            readonly MAGIC: "magic";
         }>;
         BUTTON_COLORS: Readonly<{
             readonly PRIMARY: "primary";
@@ -753,6 +756,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
             readonly DANGER: "danger";
             readonly SUCCESS: "success";
             readonly INVERTED: "inverted";
+            readonly MAGIC: "magic";
         }>;
     }, {
         iconSize(): string;

package/dist/lib/js/components/SurveyQuestions/SurveyQuestionOpenEnded/SurveyQuestionOpenEnded.vue.d.ts

@@ -307,6 +307,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
         readonly INVERTED: "inverted";
         readonly WARNING: "warning";
         readonly INFO: "info";
+        readonly MAGIC: "magic";
     }>;
     ICON_SIZES: Readonly<{
         XXX_SMALL: string;
@@ -687,6 +688,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
             validator(value: import('../../../utils/type.utils').Value<typeof import('../../Buttons/IconButton').ICON_BUTTON_STATES>): boolean;
         };
     }>, {
+        ICON_BUTTON_STATE_MAP: Record<import('../../Buttons/IconButton').IconButtonState, import('../../Buttons/Button').ButtonState>;
         isHovered: import('vue').Ref<boolean>;
         mouseOver: () => void;
         mouseLeave: () => void;
@@ -1010,6 +1012,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
             readonly INVERTED: "inverted";
             readonly WARNING: "warning";
             readonly INFO: "info";
+            readonly MAGIC: "magic";
         }>;
         BUTTON_COLORS: Readonly<{
             readonly PRIMARY: "primary";
@@ -1017,6 +1020,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
             readonly DANGER: "danger";
             readonly SUCCESS: "success";
             readonly INVERTED: "inverted";
+            readonly MAGIC: "magic";
         }>;
     }, {
         iconSize(): string;

package/dist/lib/js/components/SurveyQuestions/SurveyQuestionScale/SurveyQuestionScale.vue.d.ts

@@ -336,6 +336,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
         readonly INVERTED: "inverted";
         readonly WARNING: "warning";
         readonly INFO: "info";
+        readonly MAGIC: "magic";
     }>;
     BUTTON_TYPES: Readonly<{
         readonly FILLED: "filled";
@@ -659,6 +660,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
             validator(value: import('../../../utils/type.utils').Value<typeof import('../../Buttons/IconButton').ICON_BUTTON_STATES>): boolean;
         };
     }>, {
+        ICON_BUTTON_STATE_MAP: Record<import('../../Buttons/IconButton').IconButtonState, import('../../Buttons/Button').ButtonState>;
         isHovered: import('vue').Ref<boolean>;
         mouseOver: () => void;
         mouseLeave: () => void;
@@ -982,6 +984,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
             readonly INVERTED: "inverted";
             readonly WARNING: "warning";
             readonly INFO: "info";
+            readonly MAGIC: "magic";
         }>;
         BUTTON_COLORS: Readonly<{
             readonly PRIMARY: "primary";
@@ -989,6 +992,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
             readonly DANGER: "danger";
             readonly SUCCESS: "success";
             readonly INVERTED: "inverted";
+            readonly MAGIC: "magic";
         }>;
     }, {
         iconSize(): string;

package/dist/lib/js/components/Toast/Toast.vue.d.ts

@@ -55,6 +55,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
         readonly DANGER: "danger";
         readonly SUCCESS: "success";
         readonly INVERTED: "inverted";
+        readonly MAGIC: "magic";
     }>;
     BUTTON_RADIUSES: Readonly<{
         readonly CAPSULE: "capsule";

package/lib/js/components/Buttons/Button/Button.consts.ts

@@ -22,6 +22,7 @@ export const BUTTON_COLORS = {
 	DANGER: 'danger',
 	SUCCESS: 'success',
 	INVERTED: 'inverted',
+	MAGIC: 'magic',
 } as const;
 
 export type ButtonColor = Value<typeof BUTTON_COLORS>;

package/lib/js/components/Buttons/Button/Button.spec.ts

@@ -9,6 +9,7 @@ import {
 	BUTTON_STATES,
 	BUTTON_TYPES,
 } from './Button.consts';
+import { GRADIENT_MAGIC_ICON_DISABLED_ID, GRADIENT_MAGIC_ICON_ID } from './useMagicGradient';
 import Icon, { ICONS } from '../../Icons/Icon';
 
 describe('Button', () => {
@@ -35,6 +36,12 @@ describe('Button', () => {
 		[{ props: { color: BUTTON_COLORS.PRIMARY }, expectedClass: '-ds-color-primary' }],
 		[{ props: { color: BUTTON_COLORS.DANGER }, expectedClass: '-ds-color-danger' }],
 		[{ props: { color: BUTTON_COLORS.SUCCESS }, expectedClass: '-ds-color-success' }],
+		[
+			{
+				props: { color: BUTTON_COLORS.MAGIC, type: BUTTON_TYPES.OUTLINED },
+				expectedClass: '-ds-color-magic',
+			},
+		],
 		[{ props: { radius: BUTTON_RADIUSES.ROUNDED }, expectedClass: '-ds-rounded' }],
 		[{ props: { state: BUTTON_STATES.HOVERED }, expectedClass: '-ds-hovered' }],
 		[{ props: { state: BUTTON_STATES.FOCUSED }, expectedClass: '-ds-focused' }],
@@ -45,6 +52,34 @@ describe('Button', () => {
 		expect(outlinedButton.classes()).toContain(expectedClass);
 	});
 
+	it('magic button fills with the magic gradient', () => {
+		const component = createComponent({ color: BUTTON_COLORS.MAGIC });
+
+		expect(component.element.style.getPropertyValue('--ds-magic-fill')).toBe(
+			`url(#${GRADIENT_MAGIC_ICON_ID})`,
+		);
+	});
+
+	it('disabled magic button fills with the disabled magic gradient', () => {
+		const component = createComponent({
+			color: BUTTON_COLORS.MAGIC,
+			state: BUTTON_STATES.DISABLED,
+		});
+
+		expect(component.element.style.getPropertyValue('--ds-magic-fill')).toBe(
+			`url(#${GRADIENT_MAGIC_ICON_DISABLED_ID})`,
+		);
+	});
+
+	it('non-magic button has no magic fill style', () => {
+		const component = createComponent({
+			color: BUTTON_COLORS.PRIMARY,
+			state: BUTTON_STATES.DISABLED,
+		});
+
+		expect(component.element.style.getPropertyValue('--ds-magic-fill')).toBe('');
+	});
+
 	it('loading should have correct text container and loading icon', () => {
 		const component = createComponent({ state: BUTTON_STATES.LOADING });
 

package/lib/js/components/Buttons/Button/Button.vue

@@ -21,6 +21,17 @@
 			'-ds-elevation-x-small': elevation === BUTTON_ELEVATIONS.X_SMALL,
 			'-ds-elevation-small': elevation === BUTTON_ELEVATIONS.SMALL,
 		}"
+		:style="
+			color === BUTTON_COLORS.MAGIC
+				? {
+						'--ds-magic-fill': `url(#${
+							state === BUTTON_STATES.DISABLED
+								? GRADIENT_MAGIC_ICON_DISABLED_ID
+								: GRADIENT_MAGIC_ICON_ID
+						})`,
+					}
+				: undefined
+		"
 	>
 		<span class="ds-button__content">
 			<wnl-icon
@@ -65,6 +76,11 @@ import {
 	ButtonElevation,
 } from './Button.consts';
 import { computed } from 'vue';
+import {
+	GRADIENT_MAGIC_ICON_DISABLED_ID,
+	GRADIENT_MAGIC_ICON_ID,
+	useMagicGradient,
+} from './useMagicGradient';
 
 const {
 	size = BUTTON_SIZES.MEDIUM,
@@ -100,6 +116,9 @@ const colorClassName = computed((): string => {
 	return `-ds-color-${color}`;
 });
 
+// The loading spinner's icon fills via `url(#MAGIC_GRADIENT_ID)`; ensure that def exists.
+useMagicGradient(() => color === BUTTON_COLORS.MAGIC);
+
 const loadingIconSize = computed((): IconSize => {
 	if (size === BUTTON_SIZES.LARGE) {
 		return ICON_SIZES.MEDIUM;

package/lib/js/components/Buttons/Button/useMagicGradient.spec.ts

@@ -0,0 +1,47 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { ref } from 'vue';
+
+import { GRADIENT_MAGIC_ICON_ID, useMagicGradient } from './useMagicGradient';
+
+describe('useMagicGradient', () => {
+	beforeEach(() => {
+		document.getElementById(GRADIENT_MAGIC_ICON_ID)?.remove();
+	});
+	afterEach(() => {
+		document.getElementById(GRADIENT_MAGIC_ICON_ID)?.remove();
+	});
+
+	it('injects a single linearGradient with the hardcoded id when enabled', () => {
+		useMagicGradient(true);
+
+		const gradient = document.getElementById(GRADIENT_MAGIC_ICON_ID);
+		expect(gradient).not.toBeNull();
+		expect(gradient?.tagName.toLowerCase()).toBe('lineargradient');
+	});
+
+	it('does not inject the def when disabled', () => {
+		useMagicGradient(false);
+
+		expect(document.getElementById(GRADIENT_MAGIC_ICON_ID)).toBeNull();
+	});
+
+	it('injects the def when the reactive source becomes enabled', async () => {
+		const enabled = ref(false);
+		useMagicGradient(enabled);
+
+		expect(document.getElementById(GRADIENT_MAGIC_ICON_ID)).toBeNull();
+
+		enabled.value = true;
+		await Promise.resolve();
+
+		expect(document.getElementById(GRADIENT_MAGIC_ICON_ID)).not.toBeNull();
+	});
+
+	it('is idempotent — multiple enabled consumers leave exactly one def', () => {
+		useMagicGradient(true);
+		useMagicGradient(() => true);
+		useMagicGradient(ref(true));
+
+		expect(document.querySelectorAll(`#${GRADIENT_MAGIC_ICON_ID}`)).toHaveLength(1);
+	});
+});

package/lib/js/components/Buttons/Button/useMagicGradient.ts

@@ -0,0 +1,50 @@
+import { toValue, watch, type MaybeRefOrGetter } from 'vue';
+
+export const GRADIENT_MAGIC_ICON_ID = 'ds-gradient-magic-icon';
+export const GRADIENT_MAGIC_ICON_DISABLED_ID = 'ds-gradient-magic-icon-disabled';
+
+// SVG icons (the loading spinner) fill with the magic gradient via `fill: url(#...)`, which
+// CSS gradients can't do. The gradient is identical for every magic button, so a single
+// shared def is injected into <body> once and left for the page lifetime (invisible, 0×0).
+function ensureMagicGradientDef(): void {
+	if (typeof document === 'undefined') {
+		return; // SSR guard
+	}
+	if (document.getElementById(GRADIENT_MAGIC_ICON_ID)) {
+		return; // already injected
+	}
+	// `var()` works in the `style` property but not in the `stop-color` presentation
+	// attribute, so stop colors are set inline.
+	document.body.insertAdjacentHTML(
+		'beforeend',
+		`<svg aria-hidden="true" width="0" height="0" style="position:absolute">
+			<defs>
+				<linearGradient id="${GRADIENT_MAGIC_ICON_ID}" x1="0" y1="0" x2="1" y2="0.17">
+					<stop offset="7%" style="stop-color:var(--gradient-magic-color-1)"/>
+					<stop offset="36%" style="stop-color:var(--gradient-magic-color-2)"/>
+					<stop offset="65%" style="stop-color:var(--gradient-magic-color-3)"/>
+					<stop offset="95%" style="stop-color:var(--gradient-magic-color-4)"/>
+				</linearGradient>
+				<linearGradient id="${GRADIENT_MAGIC_ICON_DISABLED_ID}" x1="0" y1="0" x2="1" y2="0.17">
+					<stop offset="7.16%" style="stop-color:rgba(var(--gradient-magic-color-1-rgb), 0.3)"/>
+					<stop offset="36.18%" style="stop-color:rgba(var(--gradient-magic-color-2-rgb), 0.3)"/>
+					<stop offset="65.19%" style="stop-color:rgba(var(--gradient-magic-color-3-rgb), 0.3)"/>
+					<stop offset="95.08%" style="stop-color:rgba(var(--gradient-magic-color-4-rgb), 0.3)"/>
+				</linearGradient>
+			</defs>
+		</svg>`,
+	);
+}
+
+// Injects the shared magic-gradient def once `enabled` becomes truthy (immediate + reactive).
+export function useMagicGradient(enabled: MaybeRefOrGetter<boolean>): void {
+	watch(
+		() => toValue(enabled),
+		(isEnabled) => {
+			if (isEnabled) {
+				ensureMagicGradientDef();
+			}
+		},
+		{ immediate: true },
+	);
+}

package/lib/js/components/Buttons/IconButton/IconButton.consts.ts

@@ -36,6 +36,7 @@ export const ICON_BUTTON_COLORS = {
 	INVERTED: 'inverted',
 	WARNING: 'warning',
 	INFO: 'info',
+	MAGIC: 'magic',
 } as const;
 
 export type IconButtonColor = Value<typeof ICON_BUTTON_COLORS>;