@drivenets/design-system 0.13.0 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drivenets/design-system",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "license": "Apache-2.0",
   "type": "module",
   "types": "./dist/index.d.cts",
@@ -36,21 +36,20 @@
     "directory": "/packages/design-system"
   },
   "dependencies": {
-    "@ark-ui/react": "^5.36.1",
+    "@ark-ui/react": "^5.37.2",
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/modifiers": "^9.0.0",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
-    "@radix-ui/react-collapsible": "^1.1.12",
-    "@radix-ui/react-dialog": "^1.1.15",
-    "@radix-ui/react-dropdown-menu": "^2.1.16",
-    "@radix-ui/react-popover": "^1.1.15",
-    "@radix-ui/react-tooltip": "^1.2.8",
-    "@radix-ui/react-visually-hidden": "^1.2.4",
+    "@radix-ui/react-collapsible": "^1.1.13",
+    "@radix-ui/react-dialog": "^1.1.16",
+    "@radix-ui/react-dropdown-menu": "^2.1.17",
+    "@radix-ui/react-tooltip": "^1.2.9",
+    "@radix-ui/react-visually-hidden": "^1.2.5",
     "@tanstack/react-table": "^8.21.3",
-    "@tanstack/react-virtual": "^3.13.24",
-    "@zag-js/react": "^1.40.0",
-    "@zag-js/steps": "^1.40.0",
+    "@tanstack/react-virtual": "^3.14.2",
+    "@zag-js/react": "^1.41.2",
+    "@zag-js/steps": "^1.41.2",
     "classnames": "^2.5.1",
     "csstype": "^3.2.3"
   },
@@ -64,6 +63,8 @@
     "@arethetypeswrong/cli": "^0.18.2",
     "@eslint/compat": "^2.1.0",
     "@faker-js/faker": "^10.3.0",
+    "@figma/code-connect": "^1.4.8",
+    "@github-ui/storybook-addon-performance-panel": "^1.1.4",
     "@hookform/resolvers": "^5.4.0",
     "@rolldown/plugin-babel": "^0.2.3",
     "@storybook/addon-a11y": "^10.4.1",
@@ -104,8 +105,8 @@
     "vitest": "^4.1.7",
     "vitest-browser-react": "^2.1.0",
     "zod": "^4.4.3",
-    "@drivenets/eslint-plugin-internal": "0.0.0",
-    "@drivenets/vite-plugin-design-system": "0.0.9"
+    "@drivenets/vite-plugin-design-system": "0.0.10",
+    "@drivenets/eslint-plugin-internal": "0.0.0"
   },
   "scripts": {
     "start": "storybook dev -p 6006",
@@ -116,6 +117,8 @@
     "lint:build": "publint && attw --pack",
     "typecheck": "pnpm generate-scss-dts && tsgo; EXIT_CODE=$?; rm -rf .scss-dts; exit $EXIT_CODE",
     "generate-scss-dts": "typed-scss-modules ./src -o ./.scss-dts --nameFormat all --exportType default > /dev/null 2>&1",
+    "figma:lint": "figma connect parse --exit-on-unreadable-files",
+    "figma:publish": "figma connect publish --exit-on-unreadable-files",
     "test": "vitest --project=\"!requires-build\"",
     "test:coverage": "pnpm test --coverage",
     "test:unit": "vitest --project=unit",

package/src/components/ds-button-v3/ds-button-v3.figma.ts

@@ -0,0 +1,99 @@
+// url=https://www.figma.com/design/nha3m67y7S57cHCSuQO2gp/DAP-Design-System-1.2?node-id=31065-2352
+// source=https://github.com/drivenets/design-system/tree/main/packages/design-system/src/components/ds-button-v3
+// component=DsButtonV3
+import figma from 'figma';
+
+const instance = figma.selectedInstance;
+
+const variant = instance.getEnum('Variant', {
+	primary: 'primary',
+	secondary: 'secondary',
+	tertiary: 'tertiary',
+});
+const size = instance.getEnum('Size', {
+	tiny: 'tiny',
+	small: 'small',
+	medium: 'medium',
+	large: 'large',
+});
+const colorVariant = instance.getEnum('Color', { default: 'default', error: 'error' });
+const isLight = instance.getEnum('light', { true: true, false: false });
+const color = isLight ? 'light' : colorVariant;
+const disabled = instance.getEnum('State', {
+	default: false,
+	hover: false,
+	focus: false,
+	active: false,
+	disabled: true,
+});
+const iconOnly = instance.getEnum('Icon', { 'icon-only': true, text: false });
+
+const structure = instance.findInstance('.button-structure', { traverseInstances: true });
+const showIcon = structure.type === 'INSTANCE' ? structure.getBoolean('Show icon') : false;
+
+// `DsButtonV3.icon` is an icon-name string. Swapped icons keep the placeholder layer
+// name (e.g. `DAP_GM_O_check_circle`), so resolve via Code Connect ID or metadata.
+const toIconName = (name: string): string =>
+	name
+		.replace(/^DAP_DAP_/, 'DAP_')
+		.replace(/^DAP_GM_[OS]_/, '')
+		.replace(/^DAP_outline_icon\//, '')
+		.replace(/^DAP_/, '')
+		.replace(/^\/+/, '')
+		.replace(/[\s/]+/g, '_')
+		.toLowerCase();
+
+const iconNameFromCodeConnectId = (id: string | null): string | undefined => {
+	if (!id) {
+		return undefined;
+	}
+	if (id.startsWith('ds-icon-o-')) {
+		return id.slice('ds-icon-o-'.length);
+	}
+	if (id.startsWith('ds-icon-s-')) {
+		return id.slice('ds-icon-s-'.length);
+	}
+	return undefined;
+};
+
+const resolveIcon = (iconInstance: figma.InstanceHandle): string | undefined => {
+	const fromCcId = iconNameFromCodeConnectId(iconInstance.codeConnectId());
+	if (fromCcId) {
+		return fromCcId;
+	}
+
+	const iconFromMetadata = iconInstance.executeTemplate().metadata?.props?.icon;
+	if (typeof iconFromMetadata === 'string') {
+		return iconFromMetadata;
+	}
+
+	return toIconName(iconInstance.name);
+};
+
+const leadingIcon = structure.type === 'INSTANCE' ? structure.getInstanceSwap('Leading icon') : undefined;
+const iconFromSwap = leadingIcon?.type === 'INSTANCE' ? resolveIcon(leadingIcon) : undefined;
+const iconFromChild =
+	structure.type === 'INSTANCE'
+		? structure
+				.findConnectedInstances((node) => node.codeConnectId()?.startsWith('ds-icon-') ?? false, {
+					traverseInstances: true,
+				})
+				.find((node): node is figma.InstanceHandle => node.type === 'INSTANCE')
+		: undefined;
+const icon = iconFromSwap ?? (iconFromChild ? resolveIcon(iconFromChild) : undefined);
+
+const labelNode = instance.findText('Button', { traverseInstances: true });
+const label = labelNode.type === 'TEXT' ? labelNode.textContent : 'Button';
+
+const iconProp = icon ? figma.code` icon="${icon}"` : '';
+
+export default {
+	example: iconOnly
+		? figma.code`<DsButtonV3 variant="${variant}" color="${color}" size="${size}" ${disabled ? 'disabled' : ''}${iconProp} aria-label="${label}" />`
+		: showIcon && icon
+			? figma.code`<DsButtonV3 variant="${variant}" color="${color}" size="${size}" ${disabled ? 'disabled' : ''} icon="${icon}">${label}</DsButtonV3>`
+			: figma.code`<DsButtonV3 variant="${variant}" color="${color}" size="${size}" ${disabled ? 'disabled' : ''}>${label}</DsButtonV3>`,
+	imports: ["import { DsButtonV3 } from '@drivenets/design-system'"],
+	id: 'ds-button-v3',
+	metadata: { nestable: true },
+};

package/src/components/ds-button-v3/ds-button-v3.module.scss

@@ -293,66 +293,66 @@ $focus-ring-width: 2px;
 }
 
 .root[data-color='light'][data-variant='primary'] {
-	background-color: var(--background-ondark-primary);
+	background-color: var(--background-light-primary);
 	color: var(--font-on-action);
 	border-color: transparent;
 
 	&:hover:not(:disabled):not(:active):not([data-selected='true']) {
-		background-color: var(--background-ondark-primary-hover);
+		background-color: var(--background-light-primary-hover);
 	}
 
 	&:active:not(:disabled) {
-		background-color: var(--background-ondark-primary-selected);
+		background-color: var(--background-light-primary-selected);
 	}
 
 	&:focus-visible {
-		@include focus-ring(var(--outline-outline-inverse));
+		@include focus-ring(var(--outline-inverse));
 
-		background-color: var(--background-ondark-primary-hover);
+		background-color: var(--background-light-primary-hover);
 		border-color: var(--border-action-secondary);
 	}
 
 	&[data-selected='true'] {
-		background-color: var(--background-ondark-primary-selected);
+		background-color: var(--background-light-primary-selected);
 	}
 
 	&:disabled:not([data-loading]) {
-		background-color: var(--background-ondark-disabled);
-		color: var(--font-disabled);
+		background-color: var(--background-light-disabled);
+		color: var(--font-light-disabled);
 	}
 }
 
 .root[data-color='light'][data-variant='secondary'] {
 	background-color: transparent;
 	color: var(--font-on-action);
-	border-color: var(--border-ondark-secondary);
+	border-color: var(--border-light-secondary);
 
 	&:hover:not(:disabled):not(:active):not([data-selected='true']) {
-		background-color: var(--background-ondark-secondary-hover);
+		background-color: var(--light-buttons-secondary-background);
 		color: var(--font-on-action);
 	}
 
 	&:active:not(:disabled) {
-		background-color: var(--background-ondark-secondary-selected);
+		background-color: var(--background-light-secondary-selected);
 		color: var(--font-on-action);
 	}
 
 	&:focus-visible {
-		@include focus-ring(var(--outline-outline-inverse));
+		@include focus-ring(var(--outline-inverse));
 
-		background-color: var(--background-ondark-secondary-hover);
+		background-color: var(--light-buttons-secondary-background);
 		border-color: var(--border-action-secondary);
 		color: var(--font-on-action);
 	}
 
 	&[data-selected='true'] {
-		background-color: var(--background-ondark-secondary-selected);
+		background-color: var(--background-light-secondary-selected);
 	}
 
 	&:disabled:not([data-loading]) {
 		background-color: transparent;
-		color: var(--font-ondark-disabled);
-		border-color: var(--background-ondark-disabled);
+		color: var(--font-light-disabled);
+		border-color: var(--border-light-disabled);
 	}
 }
 
@@ -362,29 +362,29 @@ $focus-ring-width: 2px;
 	border-color: transparent;
 
 	&:hover:not(:disabled):not(:active):not([data-selected='true']) {
-		background-color: var(--background-ondark-secondary-hover);
+		background-color: var(--light-buttons-secondary-background);
 		color: var(--font-on-action);
 	}
 
 	&:active:not(:disabled) {
-		background-color: var(--background-ondark-secondary-selected);
+		background-color: var(--background-light-secondary-selected);
 		color: var(--font-on-action);
 	}
 
 	&:focus-visible {
-		@include focus-ring(var(--outline-outline-inverse));
+		@include focus-ring(var(--outline-inverse));
 
-		background-color: var(--background-ondark-secondary-hover);
+		background-color: var(--light-buttons-secondary-background);
 		border-color: var(--border-action-secondary);
 		color: var(--font-on-action);
 	}
 
 	&[data-selected='true'] {
-		background-color: var(--background-ondark-secondary-selected);
+		background-color: var(--background-light-secondary-selected);
 	}
 
 	&:disabled:not([data-loading]) {
 		background-color: transparent;
-		color: var(--font-ondark-disabled);
+		color: var(--font-light-disabled);
 	}
 }

package/src/components/ds-card/figma/ds-card-content.figma.ts

@@ -0,0 +1,15 @@
+// url=https://www.figma.com/design/nha3m67y7S57cHCSuQO2gp/DAP-Design-System-1.2?node-id=28122-12357
+// source=https://github.com/drivenets/design-system/tree/main/packages/design-system/src/components/ds-card
+// component=DsCard.Body
+//
+// `card content` maps to `DsCard.Body`. The section exposes no named slot — its
+// content is a freeform `DAP_Content placeholder_v01` marker — so the children are
+// a static placeholder. Expose a Figma slot on the section to forward real content.
+import figma from 'figma';
+
+export default {
+	example: figma.code`<DsCard.Body>Card content</DsCard.Body>`,
+	imports: ["import { DsCard } from '@drivenets/design-system'"],
+	id: 'ds-card-content',
+	metadata: { nestable: true },
+};

package/src/components/ds-card/figma/ds-card-footer.figma.ts

@@ -0,0 +1,15 @@
+// url=https://www.figma.com/design/nha3m67y7S57cHCSuQO2gp/DAP-Design-System-1.2?node-id=28122-12361
+// source=https://github.com/drivenets/design-system/tree/main/packages/design-system/src/components/ds-card
+// component=DsCard.Footer
+//
+// `card footer` maps to `DsCard.Footer`. The section exposes no named slot — its
+// content is a freeform `DAP_Content placeholder_v01` marker — so the children are
+// a static placeholder. Expose a Figma slot on the section to forward real content.
+import figma from 'figma';
+
+export default {
+	example: figma.code`<DsCard.Footer>Card footer</DsCard.Footer>`,
+	imports: ["import { DsCard } from '@drivenets/design-system'"],
+	id: 'ds-card-footer',
+	metadata: { nestable: true },
+};

package/src/components/ds-card/figma/ds-card-header.figma.ts

@@ -0,0 +1,15 @@
+// url=https://www.figma.com/design/nha3m67y7S57cHCSuQO2gp/DAP-Design-System-1.2?node-id=28122-12353
+// source=https://github.com/drivenets/design-system/tree/main/packages/design-system/src/components/ds-card
+// component=DsCard.Header
+//
+// `card header` maps to `DsCard.Header`. The section exposes no named slot — its
+// content is a freeform `DAP_Content placeholder_v01` marker — so the children are
+// a static placeholder. Expose a Figma slot on the section to forward real content.
+import figma from 'figma';
+
+export default {
+	example: figma.code`<DsCard.Header>Card title</DsCard.Header>`,
+	imports: ["import { DsCard } from '@drivenets/design-system'"],
+	id: 'ds-card-header',
+	metadata: { nestable: true },
+};

package/src/components/ds-card/figma/ds-card.figma.ts

@@ -0,0 +1,72 @@
+// url=https://www.figma.com/design/nha3m67y7S57cHCSuQO2gp/DAP-Design-System-1.2?node-id=25703-1142
+// source=https://github.com/drivenets/design-system/tree/main/packages/design-system/src/components/ds-card
+// component=DsCard
+//
+// `DAP_Card_v01` is the compound card. It maps to the composed `DsCard.Root` and
+// resolves its `card header` / `card content` / `card footer` sections dynamically
+// via their own Code Connect templates, so a section that is removed or restyled
+// stays in sync. Sections are always present in the current design, but resolving
+// them keeps a single source of truth for each slot.
+import figma from 'figma';
+
+const instance = figma.selectedInstance;
+
+const size =
+	instance.getEnum('Size', {
+		Large: 'large',
+		Medium: 'medium',
+		Small: 'small',
+	}) ?? 'medium';
+
+const state = instance.getEnum('State', {
+	default: 'default',
+	hover: 'default',
+	focus: 'default',
+	selected: 'selected',
+	'selected blue': 'highlighted',
+	disabled: 'disabled',
+});
+
+const selected = state === 'selected' || state === 'highlighted';
+const highlightSelected = state === 'highlighted';
+const disabled = state === 'disabled';
+
+// A card is only selectable when it carries a selection state. Disabled is an
+// independent modifier, so it must not imply `selectable` on its own.
+const selectable = selected;
+
+const flags = [
+	selectable && 'selectable',
+	selected && 'selected',
+	highlightSelected && 'highlightSelected',
+	disabled && 'disabled',
+]
+	.filter(Boolean)
+	.join(' ');
+
+const flagsAttr = flags ? ` ${flags}` : '';
+
+const header = instance.findInstance('card header', { traverseInstances: true });
+let headerCode: figma.ResultSection[] | undefined;
+if (header.type === 'INSTANCE') {
+	headerCode = header.executeTemplate().example;
+}
+
+const content = instance.findInstance('card content', { traverseInstances: true });
+let contentCode: figma.ResultSection[] | undefined;
+if (content.type === 'INSTANCE') {
+	contentCode = content.executeTemplate().example;
+}
+
+const footer = instance.findInstance('card footer', { traverseInstances: true });
+let footerCode: figma.ResultSection[] | undefined;
+if (footer.type === 'INSTANCE') {
+	footerCode = footer.executeTemplate().example;
+}
+
+export default {
+	example: figma.code`<DsCard.Root size="${size}"${flagsAttr}>${headerCode}${contentCode}${footerCode}</DsCard.Root>`,
+	imports: ["import { DsCard } from '@drivenets/design-system'"],
+	id: 'ds-card',
+	metadata: { nestable: false },
+};

package/src/components/ds-date-picker/ds-date-picker.figma.ts

@@ -0,0 +1,19 @@
+// url=https://www.figma.com/design/nha3m67y7S57cHCSuQO2gp/DAP-Design-System-1.2?node-id=30063-134227
+// source=https://github.com/drivenets/design-system/tree/main/packages/design-system/src/components/ds-date-picker
+// component=DsDatePicker
+//
+// `DAP_Date picker_v1.1` only exposes a `type` variant (day/month/year calendar view),
+// which is internal UI state with no code-prop equivalent. The snippet is therefore an
+// illustrative controlled-usage starter (props are not derived from Figma) showing the
+// idiomatic `useState` + `value`/`onChange` pattern. `fcMember`/`fcProps` are surfaced so
+// a parent `DsFormControl` template can render `<DsFormControl.DatePicker />`.
+import figma from 'figma';
+
+export default {
+	example: figma.code`const [value, setValue] = useState<Date | null>(null);
+
+<DsDatePicker value={value} onChange={setValue} withTime placeholder="mm/dd/yyyy, hh:mm AM/PM" />`,
+	imports: ["import { useState } from 'react'", "import { DsDatePicker } from '@drivenets/design-system'"],
+	id: 'ds-date-picker',
+	metadata: { nestable: true, props: { fcMember: 'DatePicker', fcProps: '' } },
+};

package/src/components/ds-drawer/ds-drawer.module.scss

@@ -56,6 +56,20 @@
 		transform 0.2s ease,
 		width 0.2s ease;
 
+	// A closed (or closing) drawer is invisible but stays mounted and transformed.
+	// Without this it still hit-tests and can swallow clicks on neighboring UI when
+	// docked at a non-zero offset. Keep it click-through whenever it is not open.
+	//
+	// `!important` is required: when this drawer is stacked with other open Ark
+	// dialogs (e.g. a non-modal drawer opened over another dialog), Ark's layer
+	// management writes an inline `pointer-events: auto` onto the content, which
+	// would otherwise win over this rule and let the closed drawer keep eating
+	// clicks. Overriding a third-party inline style is the canonical use of
+	// `!important`, and a closed drawer must never be a pointer target.
+	&[data-state='closed'] {
+		pointer-events: none !important;
+	}
+
 	&.position-end {
 		right: 0;
 		transform-origin: 100% 50%;

package/src/components/ds-drawer/ds-drawer.tsx

@@ -1,5 +1,5 @@
 import { type CSSProperties, type ReactNode, Fragment } from 'react';
-import { Dialog } from '@ark-ui/react/dialog';
+import { Dialog, type DialogRootProps } from '@ark-ui/react/dialog';
 import { Portal } from '@ark-ui/react/portal';
 import classNames from 'classnames';
 import type { DsDrawerProps } from './ds-drawer.types';
@@ -12,6 +12,7 @@ import { useResponsiveValue } from '../../utils/responsive';
 const DsDrawer = ({
 	open,
 	onOpenChange,
+	onOpenAutoFocus,
 	columns = 4,
 	position = 'end',
 	backdrop = false,
@@ -29,6 +30,23 @@ const DsDrawer = ({
 		onOpenChange(details.open);
 	};
 
+	// Mirrors Radix's `onOpenAutoFocus`. Ark reads `initialFocusEl` when the drawer
+	// opens to decide what to focus. To honor `preventDefault()`, we point initial
+	// focus back at the element that was focused when the drawer opened (e.g. the
+	// input that triggered it), so the caret stays put. Returning `undefined` keeps
+	// Ark's default of focusing the first element inside the drawer. The cast covers
+	// the `undefined` branch, which sits outside Ark's `MaybeElement` return type.
+	const initialFocusEl = (
+		onOpenAutoFocus
+			? () => {
+					const event = new Event('openAutoFocus', { cancelable: true });
+					onOpenAutoFocus(event);
+
+					return event.defaultPrevented ? (document.activeElement as HTMLElement | null) : undefined;
+				}
+			: undefined
+	) as DialogRootProps['initialFocusEl'];
+
 	const Wrapper = portal ? Portal : Fragment;
 
 	return (
@@ -39,6 +57,7 @@ const DsDrawer = ({
 			closeOnEscape={closeOnEscape}
 			closeOnInteractOutside={closeOnInteractOutside}
 			preventScroll={backdrop}
+			initialFocusEl={initialFocusEl}
 		>
 			<Wrapper>
 				{backdrop && <Dialog.Backdrop className={styles.backdrop} />}

package/src/components/ds-drawer/ds-drawer.types.ts

@@ -20,6 +20,13 @@ export interface DsDrawerProps extends Pick<DialogProps, 'closeOnEscape' | 'clos
 	 * Callback when the drawer open state changes
 	 */
 	onOpenChange: (open: boolean) => void;
+	/**
+	 * Called when focus is about to move into the drawer as it opens.
+	 * Call `event.preventDefault()` to stop the drawer from stealing focus,
+	 * keeping the caret where it was (e.g. in a text input that triggered the
+	 * drawer). Useful for type-ahead / popover patterns.
+	 */
+	onOpenAutoFocus?: (event: Event) => void;
 	/**
 	 * Number of grid columns the drawer should span (1-12).
 	 * Accepts a responsive value, e.g. `{ lg: 4, md: 6 }`.

package/src/components/ds-file-upload/hooks/use-file-upload.ts

@@ -224,6 +224,13 @@ export function useFileUpload({
 			updateFileProgress(fileId, 100);
 			onFileUploadComplete?.(fileId, result);
 		} catch (error) {
+			// A fired abort signal means the upload was cancelled or removed by the
+			// user. Adapters reject with a (retryable) error on abort, but that must
+			// not overwrite the terminal status owned by cancelUpload/removeFile.
+			if (abortController.signal.aborted) {
+				return;
+			}
+
 			const errorMessage = error instanceof Error ? error.message : 'Upload failed';
 			// Determine status based on error type
 			// Unknown errors are treated as retryable (network errors, etc.)

package/src/components/ds-form-control/ds-form-control.figma.ts

@@ -0,0 +1,76 @@
+// url=https://www.figma.com/design/nha3m67y7S57cHCSuQO2gp/DAP-Design-System-1.2?node-id=13484-17388
+// source=https://github.com/drivenets/design-system/tree/main/packages/design-system/src/components/ds-form-control
+// component=DsFormControl
+//
+// The Figma component `DAP_input/ input form unit/ vertical_v01` is the generic form-unit
+// wrapper that owns the label, description and caption. Its `Swap Input to Select` slot
+// holds the actual control (select, text/number/password input, ...), which is resolved
+// dynamically. Inner templates that expose `metadata.props.fcMember` are linked as the
+// idiomatic `DsFormControl.<member>` compound; anything else falls back to its bare snippet.
+import figma from 'figma';
+
+const instance = figma.selectedInstance;
+
+const showLabel = instance.getBoolean('Show Label');
+const showCaption = instance.getBoolean('Show Caption');
+const showDescription = instance.getBoolean('Show Description');
+const descriptionText = instance.getString('Description Text');
+
+const labelInstance = instance.findInstance('input label', { traverseInstances: true });
+const required = labelInstance.type === 'INSTANCE' ? labelInstance.getBoolean('Required') : false;
+
+const labelText = instance.findText('Input label', { traverseInstances: true });
+const label = labelText.type === 'TEXT' ? labelText.textContent : 'Label';
+
+const captionInstance = instance.findInstance('inputs/ Input Caption', { traverseInstances: true });
+const status =
+	captionInstance.type === 'INSTANCE'
+		? (captionInstance.getEnum('Status', {
+				Default: 'info',
+				Success: 'success',
+				Error: 'error',
+				Warning: 'warning',
+			}) ?? 'info')
+		: 'info';
+
+// The caption text isn't bound to a component property, so read the first text layer
+// inside the caption instance and pass it through as the `message` value.
+const captionText =
+	captionInstance.type === 'INSTANCE'
+		? captionInstance.findLayers((node) => node.type === 'TEXT', { traverseInstances: true })[0]
+		: undefined;
+const message = captionText?.type === 'TEXT' ? captionText.textContent : 'Caption';
+
+// Resolve the swapped control and build the `DsFormControl.<member>` child from its
+// surfaced metadata. Fall back to the bare snippet when no `fcMember` is exposed.
+const inner = instance.getInstanceSwap('Swap Input to Select');
+
+let child;
+if (inner && inner.type === 'INSTANCE') {
+	const { example, metadata } = inner.executeTemplate();
+	const fcMember = metadata?.props?.fcMember;
+	const fcProps = metadata?.props?.fcProps ?? '';
+
+	child = fcMember ? figma.code`<DsFormControl.${fcMember} ${fcProps} />` : example;
+}
+
+const description = showDescription
+	? figma.code`<DsFormControl.Description>${descriptionText}</DsFormControl.Description>`
+	: '';
+
+const labelAttr = `label="${label}"`;
+const requiredAttr = required ? 'required' : '';
+const hideLabelAttr = showLabel ? '' : 'hideLabel';
+const statusAttr = status !== 'info' ? `status="${status}"` : '';
+const messageAttr = showCaption ? `message="${message}"` : '';
+
+const formControlAttrs = [labelAttr, requiredAttr, hideLabelAttr, statusAttr, messageAttr]
+	.filter(Boolean)
+	.join(' ');
+
+export default {
+	example: figma.code`<DsFormControl ${formControlAttrs}>${description}${child}</DsFormControl>`,
+	imports: ["import { DsFormControl } from '@drivenets/design-system'"],
+	id: 'ds-form-control',
+	metadata: { nestable: false },
+};

package/src/components/ds-icon/figma/ds-icon-material.figma.batch.ts

@@ -0,0 +1,10 @@
+import figma from 'figma';
+
+const batch = figma.batch as { icon: string; filled: boolean; id: string };
+
+export default {
+	example: figma.code`<DsIcon icon="${batch.icon}"${batch.filled ? ' filled' : ''} />`,
+	imports: ["import { DsIcon } from '@drivenets/design-system'"],
+	id: batch.id,
+	metadata: { nestable: true, props: { icon: batch.icon } },
+};

package/src/components/ds-icon/figma/ds-icon-special.figma.batch.ts

@@ -0,0 +1,18 @@
+import figma from 'figma';
+
+// Batch template for Figma special icon component sets (`special-*` icons),
+// where a single `type` variant selects the icon. Variants without a `DsIcon`
+// equivalent are absent from `typeMap`, so `getEnum` returns undefined for them.
+const instance = figma.selectedInstance;
+const batch = figma.batch as { id: string; variantProp: string; typeMap: Record<string, string> };
+
+const icon = instance.getEnum(batch.variantProp, batch.typeMap);
+
+export default {
+	example: icon
+		? figma.code`<DsIcon icon="${icon}" />`
+		: figma.code`{/* This icon is not available in @drivenets/design-system */}`,
+	imports: ["import { DsIcon } from '@drivenets/design-system'"],
+	id: batch.id,
+	metadata: { nestable: true, props: { icon } },
+};