@scalepad/ui 0.1.0

package/src/index.ts

@@ -0,0 +1,483 @@
+// UI package public API - Explicit named exports only
+
+// Type augmentations - imported for side effects
+// oxlint-disable-next-line import/no-unassigned-import
+import './types/tanstack-table.d.ts';
+// oxlint-disable-next-line import/no-unassigned-import
+import './types/mantine-theme.d.ts';
+
+// Theme
+export { mantineVars } from './theme/mantineVars';
+export { tokens } from './theme/themeContract.css';
+export { toCssVar } from './theme/themeVars';
+export type {
+  BackgroundColorVar,
+  IconColorVar,
+  StrokeColorVar,
+  TextColorVar,
+} from './theme/themeVars';
+export { ThemeProvider } from './ThemeProvider';
+export type { ThemeProviderProps } from './ThemeProvider';
+export { toZIndexVar, zIndex } from './tokens';
+export type { ZIndexKey } from './tokens';
+
+// Components
+export { ActionCard } from './components/ActionCard';
+export type { ActionCardProps } from './components/ActionCard';
+export { AppliedFiltersManagerBar } from './components/AppliedFiltersManagerBar';
+export type {
+  AppliedFiltersManagerBarProps,
+  FilterCategory,
+} from './components/AppliedFiltersManagerBar';
+export { Anchor } from './components/Anchor';
+export type { AnchorProps } from './components/Anchor';
+export { Badge } from './components/Badge';
+export type { BadgeProps } from './components/Badge';
+export { BulkActionBar } from './components/BulkActionBar';
+export type { BulkActionBarProps } from './components/BulkActionBar';
+export { Button } from './components/Button';
+export type { ButtonProps } from './components/Button';
+export { CodePanel } from './components/CodePanel';
+export type { CodePanelProps, CodePanelTab } from './components/CodePanel';
+export { ConfirmationModal } from './components/ConfirmationModal';
+export type { ConfirmationModalProps } from './components/ConfirmationModal';
+export { ConfirmationTooltip } from './components/ConfirmationTooltip';
+export type { ConfirmationTooltipProps } from './components/ConfirmationTooltip';
+export {
+  createActionsColumn,
+  DataTable,
+  RowExpandToggle,
+  RowGroupHeader,
+} from './components/DataTable';
+export type {
+  CreateActionsColumnOptions,
+  DataTableColumnConfigurator,
+  DataTableColumnConfiguratorItem,
+  DataTableColumnMeta,
+  DataTableProps,
+  RowExpandToggleProps,
+  RowGroupHeaderAggregate,
+  RowGroupHeaderProps,
+} from './components/DataTable';
+export { Details } from './components/Details';
+export type { DetailsProps } from './components/Details';
+
+export { notifications } from '@mantine/notifications';
+export { DataDialog } from './components/DataDialog';
+export type { DataDialogProps } from './components/DataDialog';
+export { DateInput, DateNavigator, DatePicker } from './components/DatePicker';
+export type {
+  DateInputProps,
+  DateNavigatorProps,
+  DatePickerGranularity,
+  DatePickerProps,
+  DateRange,
+} from './components/DatePicker';
+export { DownloadCard } from './components/DownloadCard';
+export type { DownloadCardProps } from './components/DownloadCard';
+export { Drawer } from './components/Drawer/Drawer';
+export type { DrawerProps } from './components/Drawer/Drawer';
+export { EmptyState } from './components/EmptyState';
+export type {
+  EmptyStateAction,
+  EmptyStateProps,
+} from './components/EmptyState';
+export { ErrorBoundary } from './components/ErrorBoundary';
+export type { ErrorBoundaryProps } from './components/ErrorBoundary';
+export { ErrorState } from './components/ErrorState';
+export type {
+  ErrorStateAction,
+  ErrorStateProps,
+} from './components/ErrorState';
+export { FeatureCard } from './components/FeatureCard';
+export type { FeatureCardProps } from './components/FeatureCard';
+export { FilterMenu } from './components/FilterMenu';
+export type { FilterItem, FilterMenuProps } from './components/FilterMenu';
+export type {
+  FilterSchema,
+  FilterValue,
+  SearchableFilterItemsController,
+  SearchableFilterItemsStatus,
+} from './components/FilterMenu/types';
+export { InfiniteScrollSentinel } from './components/InfiniteScrollSentinel';
+export type { InfiniteScrollSentinelProps } from './components/InfiniteScrollSentinel';
+export { InfiniteScrollTrigger } from './components/InfiniteScrollTrigger';
+export type {
+  InfiniteScrollState,
+  InfiniteScrollTriggerProps,
+} from './components/InfiniteScrollTrigger';
+export { InfoCard } from './components/InfoCard';
+export type { InfoCardProps } from './components/InfoCard';
+export { KbdHint } from './components/KbdHint';
+export type { KbdHintProps } from './components/KbdHint';
+export { LabeledField } from './components/LabeledField';
+export type { LabeledFieldProps } from './components/LabeledField';
+export { MessageBox } from './components/MessageBox';
+export type { MessageBoxProps } from './components/MessageBox';
+export {
+  Notifications,
+  showErrorToast,
+  showSuccessToast,
+} from './components/Notifications';
+export type {
+  ShowToastAction,
+  ShowToastOptions,
+} from './components/Notifications';
+export type {
+  SearchableListAsyncProps,
+  SearchableListSearchMode,
+} from './components/SearchableList/types';
+export {
+  DayView,
+  DEFAULT_SCHEDULE_LABELS,
+  getLabel,
+  MobileMonthView,
+  MonthView,
+  Schedule,
+  ScheduleEvent,
+  ScheduleHeader,
+  WeekView,
+  YearView,
+} from './components/Schedule/Schedule';
+export type {
+  DateStringValue,
+  DateTimeStringValue,
+  DayViewProps,
+  MonthViewProps,
+  RenderEventBody,
+  ScheduleEventData,
+  ScheduleLabels,
+  ScheduleLabelsOverride,
+  ScheduleLayout,
+  ScheduleMode,
+  ScheduleProps,
+  ScheduleRecurrenceData,
+  ScheduleViewLevel,
+  WeekViewProps,
+  YearViewProps,
+} from './components/Schedule/Schedule';
+export { SearchableSubMenu } from './components/SearchableSubMenu';
+export type { SearchableSubMenuProps } from './components/SearchableSubMenu';
+export { SettingsCard } from './components/SettingsCard';
+export type { SettingsCardProps } from './components/SettingsCard';
+export { SimpleList } from './components/SimpleList';
+export type {
+  SimpleListItemProps,
+  SimpleListProps,
+} from './components/SimpleList';
+export { SimpleTable } from './components/SimpleTable';
+export type {
+  SimpleTableColumn,
+  SimpleTableProps,
+} from './components/SimpleTable';
+export {
+  getStatusVariant,
+  StatusIndicator,
+} from './components/StatusIndicator';
+export type {
+  DeploymentStatus,
+  DeviceStatus,
+  StatusIndicatorProps,
+} from './components/StatusIndicator';
+export { SuspenseLoader } from './components/SuspenseLoader';
+export { SortableColumnHeader, TableSkeletonRows } from './components/Table';
+export type {
+  SkeletonColumnConfig,
+  SortableColumnHeaderProps,
+  TableSkeletonRowsProps,
+} from './components/Table';
+export { TableActionsMenu } from './components/TableActionsMenu';
+export type { TableActionsMenuProps } from './components/TableActionsMenu';
+export { TableCard } from './components/TableCard';
+export type { TableCardProps } from './components/TableCard';
+export { TableContainer } from './components/TableContainer';
+export type { TableContainerProps } from './components/TableContainer';
+export {
+  TableControlBar,
+  TableSelectionButton,
+  useTableControlBar,
+} from './components/TableControlBar';
+export type {
+  TableControlBarProps,
+  TableSelectionButtonProps,
+  UseTableControlBarProps,
+  UseTableControlBarReturn,
+} from './components/TableControlBar';
+export {
+  SelectAllCheckbox,
+  SelectionCheckbox,
+} from './components/TableSelection';
+export type {
+  SelectAllCheckboxProps,
+  SelectionCheckboxProps,
+} from './components/TableSelection';
+export { Sidebar } from './components/Sidebar';
+export type {
+  SidebarGroupLabelProps,
+  SidebarItemProps,
+} from './components/Sidebar';
+export { SubNavigation } from './components/SubNavigation';
+export type { SubNavigationProps } from './components/SubNavigation';
+export { Tabs } from './components/Tabs';
+export type {
+  TabsListProps,
+  TabsPanelProps,
+  TabsProps,
+  TabsTabProps,
+} from './components/Tabs';
+export { ThemeSwitcher } from './components/ThemeSwitcher';
+export type { ThemeSwitcherProps } from './components/ThemeSwitcher';
+export { TruncatedText } from './components/TruncatedText';
+export type { TruncatedTextProps } from './components/TruncatedText';
+export { PropertyRow } from './components/PropertyRow';
+export type { PropertyRowProps } from './components/PropertyRow';
+export { RadioTile } from './components/RadioTile';
+export type { RadioTileProps } from './components/RadioTile';
+export { RichTextEditor } from './components/RichTextEditor';
+export type { RichTextEditorProps } from './components/RichTextEditor';
+export {
+  SlashRichTextEditor,
+  SlashSuggestionExtension,
+} from './components/SlashRichTextEditor';
+export type {
+  SlashCommand,
+  SlashRichTextEditorHandle,
+  SlashRichTextEditorProps,
+  SlashSuggestionState,
+} from './components/SlashRichTextEditor';
+export { RichTextView } from './components/RichTextView';
+export type { RichTextViewProps } from './components/RichTextView';
+export { RichTextInline } from './components/RichText/RichTextInline';
+export type { RichTextInlineProps } from './components/RichText/RichTextInline';
+export { EditableRichText } from './components/EditableRichText';
+export type { EditableRichTextProps } from './components/EditableRichText';
+// Shared rich-text foundation. Every editor/viewer above is a thin chrome
+// wrapper around `RichText`'s extensions + toolbar + helpers, so consumers
+// that need to extend or compose the toolbar (custom slash commands,
+// custom formatting set) reach for the symbols below.
+export {
+  BLOCKS_ONLY_FORMATTING_COMMANDS,
+  DEFAULT_RICH_TEXT_IMAGE_MAX_BYTES,
+  FormattingToolbar,
+  getRichTextExtensions,
+  installRichTextImageHandlers,
+  isDocEmpty,
+  plainTextFromDoc,
+  resolveFormattingCommands,
+  RICH_TEXT_FILE_ID_ATTRIBUTE,
+  RICH_TEXT_IMAGE_CLASS,
+  richTextDocFromPlainText,
+  STANDARD_FORMATTING_COMMANDS,
+  useRichTextImageLoader,
+  useRichTextImageUploader,
+} from './components/RichText';
+export type {
+  FormattingToolbarCommand,
+  FormattingToolbarProps,
+  FormattingToolbarVariant,
+  GetRichTextExtensionsOptions,
+  RichTextImageEditorConfig,
+  RichTextImageLoaderConfig,
+  RichTextImageLoaderHandle,
+  RichTextImageUploadConfig,
+  RichTextImageUploadError,
+  RichTextImageUploadResponse,
+  RichTextImageUploadResult,
+} from './components/RichText';
+export type { JSONContent } from '@tiptap/react';
+
+// Input components with Figma design specifications
+export { CommentComposer } from './components/CommentComposer';
+export type { CommentComposerProps } from './components/CommentComposer';
+export { MultiSelect } from './components/MultiSelect';
+export type { MultiSelectProps } from './components/MultiSelect';
+export { Select } from './components/Select';
+export type { SelectProps } from './components/Select';
+export { SelectCreatable } from './components/SelectCreatable';
+export type { SelectCreatableProps } from './components/SelectCreatable';
+export { LookupSelect } from './components/LookupSelect';
+export type {
+  LookupSelectOption,
+  LookupSelectProps,
+} from './components/LookupSelect';
+export { SearchTextInput, TextInput } from './components/TextInput';
+export type {
+  SearchTextInputProps,
+  TextInputProps,
+} from './components/TextInput';
+export { EditableText } from './components/EditableText';
+export type {
+  EditableTextHandle,
+  EditableTextProps,
+} from './components/EditableText';
+export { EditableSelect } from './components/EditableSelect';
+export type { EditableSelectProps } from './components/EditableSelect';
+export { SchedulePicker } from './components/SchedulePicker';
+export type {
+  FiscalQuarterValue,
+  SchedulePickerProps,
+} from './components/SchedulePicker';
+
+// StatCard component for displaying dashboard metrics
+export { StatCard } from './components/StatCard';
+export type { StatCardProps } from './components/StatCard';
+
+export { StatusBadge } from './components/StatusBadge';
+export type {
+  StatusBadgeProps,
+  StatusBadgeTone,
+} from './components/StatusBadge';
+export { TrendBadge } from './components/TrendBadge';
+export type { TrendBadgeProps, TrendDirection } from './components/TrendBadge';
+
+// IconButton component with Figma design specifications
+export { IconButton } from './components/IconButton';
+export type {
+  IconButtonProps,
+  IconButtonVariant,
+} from './components/IconButton';
+
+// MetricDisplay component for consistent metric/KPI display
+export { MetricDisplay } from './components/MetricDisplay';
+export type { MetricDisplayProps } from './components/MetricDisplay';
+
+// Typography components with variant-driven styling from Figma text-style tokens
+export { Text, Title } from './components/Typography';
+export type { TextProps, TitleProps } from './components/Typography';
+export type {
+  BodyVariant,
+  HeadingVariant,
+  TextStyleVariant,
+} from './tokens/text-styles';
+
+// Chart components are in a separate entry point to avoid pulling recharts
+// into the main bundle. Import from '@scalepad/ui/charts' instead.
+
+// Hooks
+export { useFilters } from './hooks/useFilters';
+export type { UseFiltersOptions, UseFiltersReturn } from './hooks/useFilters';
+export { useDetailDrawer } from './components/Drawer/hooks/useDetailDrawer';
+export type {
+  DetailDrawerSearch,
+  UseDetailDrawerOptions,
+  UseDetailDrawerReturn,
+} from './components/Drawer/hooks/useDetailDrawer';
+export { useDetailDrawerNavigation } from './components/Drawer/hooks/useDetailDrawerNavigation';
+export type {
+  UseDetailDrawerNavigationOptions,
+  UseDetailDrawerNavigationReturn,
+} from './components/Drawer/hooks/useDetailDrawerNavigation';
+export { useDetailDrawerNavigationContext } from './components/Drawer/hooks/useDetailDrawerNavigationContext';
+export type {
+  DetailDrawerNavigationContext,
+  UseDetailDrawerNavigationContextOptions,
+} from './components/Drawer/hooks/useDetailDrawerNavigationContext';
+export { useInfiniteScroll } from './hooks/useInfiniteScroll';
+export type { UseInfiniteScrollOptions } from './hooks/useInfiniteScroll';
+export { useServerTable } from './hooks/useServerTable';
+export type {
+  ListResponse,
+  UseServerTableOptions,
+  UseServerTableReturn,
+} from './hooks/useServerTable';
+export { useTableSelection } from './hooks/useTableSelection';
+export type { UseTableSelectionReturn } from './hooks/useTableSelection';
+export { useTableSort } from './hooks/useTableSort';
+export type {
+  UseTableSortOptions,
+  UseTableSortReturn,
+} from './hooks/useTableSort';
+export { usePlatform } from './hooks/usePlatform';
+
+// Utils
+export {
+  AVATAR_PALETTE,
+  clientInitial,
+  colorForKey,
+  initials,
+} from './utils/avatar';
+export type { AvatarColor } from './utils/avatar';
+export { resolveColorToken } from './utils/color-props';
+export type {
+  BackgroundColor,
+  BackgroundColorProp,
+  ComponentColorProp,
+  DesignSystemColorProps,
+  IconColor,
+  SemanticColor,
+  StrokeColor,
+  StrokeColorProp,
+  TextColor,
+  TextColorProp,
+} from './utils/color-props';
+export { nestFlatRows } from './utils/nestFlatRows';
+export type { NestFlatRowsOptions, WithSubRows } from './utils/nestFlatRows';
+
+// Design system primitives - wrapped Mantine components with typed color props
+// These replace direct Mantine re-exports for components where color enforcement matters
+export {
+  Alert,
+  Avatar,
+  Box,
+  Card,
+  Center,
+  Container,
+  Divider,
+  Flex,
+  FluidGrid,
+  Grid,
+  Group,
+  Loader,
+  Menu,
+  NavLink,
+  Paper,
+  SimpleGrid,
+  Stack,
+  Switch,
+} from './components/DesignSystemPrimitives';
+export type {
+  AlertProps,
+  AvatarProps,
+  BoxProps,
+  CardProps,
+  CenterProps,
+  ContainerProps,
+  DividerProps,
+  FlexProps,
+  FluidGridProps,
+  GridProps,
+  GroupProps,
+  LoaderProps,
+  MenuItemProps,
+  MenuItemVariant,
+  NavLinkProps,
+  PaperProps,
+  SimpleGridProps,
+  StackProps,
+  SwitchProps,
+} from './components/DesignSystemPrimitives';
+
+// Raw Mantine pass-throughs.
+// Prefer `@scalepad/ui/mantine` for new imports when no wrapped primitive exists.
+export {
+  AppShell,
+  Burger,
+  Checkbox,
+  Code,
+  Modal,
+  NativeSelect,
+  PasswordInput,
+  Popover,
+  Progress,
+  SegmentedControl,
+  Skeleton,
+  Table,
+  Textarea,
+  Tooltip,
+  UnstyledButton,
+} from './mantine';
+export type {
+  PopoverProps,
+  ProgressProps,
+  UnstyledButtonProps,
+} from './mantine';

package/src/mantine.ts

@@ -0,0 +1,25 @@
+// Raw Mantine pass-through exports.
+// Prefer wrapped design-system primitives from `@scalepad/ui` when available.
+
+export {
+  AppShell,
+  Burger,
+  Checkbox,
+  Code,
+  Modal,
+  NativeSelect,
+  PasswordInput,
+  Popover,
+  Progress,
+  SegmentedControl,
+  Skeleton,
+  Table,
+  Textarea,
+  Tooltip,
+  UnstyledButton,
+} from '@mantine/core';
+export type {
+  PopoverProps,
+  ProgressProps,
+  UnstyledButtonProps,
+} from '@mantine/core';

package/src/theme/mantineVars.ts

@@ -0,0 +1,12 @@
+/**
+ * Mantine theme as typed CSS variable references for vanilla-extract.
+ * Use mantineVars for theme tokens, breakpoints, light/dark selectors, RTL.
+ * Values are provided by MantineProvider; this file only exposes references.
+ * (Plain .ts so we can export themeToVars result which includes functions; use in .css.ts via import.)
+ */
+
+import { themeToVars } from '@mantine/vanilla-extract';
+
+import { mantineTheme } from '../theme';
+
+export const mantineVars = themeToVars(mantineTheme);

package/src/theme/themeContract.css.ts

@@ -0,0 +1,131 @@
+/**
+ * AUTO-GENERATED - DO NOT EDIT
+ * Generated from: packages/figma-tokens (semantic-colors, border-radius, spacing, shadows)
+ * Theme contract for vanilla-extract: typed references to CSS variables injected by ThemeProvider.
+ */
+
+import { createGlobalThemeContract } from '@vanilla-extract/css';
+
+export const tokens = createGlobalThemeContract({
+  color: {
+    text: {
+      title: 'color-text-title',
+      dangerDefault: 'color-text-danger-default',
+      link: 'color-text-link',
+      default: 'color-text-default',
+      disabledDefault: 'color-text-disabled-default',
+      subduedDefault: 'color-text-subdued-default',
+      primaryDefault: 'color-text-primary-default',
+      primaryLight: 'color-text-primary-light',
+      warningDefault: 'color-text-warning-default',
+      successDefault: 'color-text-success-default',
+      dangerDisabled: 'color-text-danger-disabled',
+      informationDefault: 'color-text-information-default',
+      dangerStrong: 'color-text-danger-strong',
+      warningStrong: 'color-text-warning-strong',
+      successStrong: 'color-text-success-strong',
+      informationStrong: 'color-text-information-strong',
+      subduedStrong: 'color-text-subdued-strong',
+      inverse: 'color-text-inverse',
+    },
+    background: {
+      default: 'color-background-default',
+      defaultHover: 'color-background-default-hover',
+      body: 'color-background-body',
+      disabledDefault: 'color-background-disabled-default',
+      transparent: 'color-background-transparent',
+      primaryFilled: 'color-background-primary-filled',
+      primaryFilledHover: 'color-background-primary-filled-hover',
+      warningFilled: 'color-background-warning-filled',
+      successFilled: 'color-background-success-filled',
+      subduedLight: 'color-background-subdued-light',
+      subduedUltralight: 'color-background-subdued-ultralight',
+      dangerFilled: 'color-background-danger-filled',
+      subduedFilled: 'color-background-subdued-filled',
+      warningFilledHover: 'color-background-warning-filled-hover',
+      successFilledHover: 'color-background-success-filled-hover',
+      dangerFilledHover: 'color-background-danger-filled-hover',
+      subduedFilledHover: 'color-background-subdued-filled-hover',
+      dangerLight: 'color-background-danger-light',
+      primaryLight: 'color-background-primary-light',
+      warningLight: 'color-background-warning-light',
+      successLight: 'color-background-success-light',
+      primaryLightHover: 'color-background-primary-light-hover',
+      warningLightHover: 'color-background-warning-light-hover',
+      successLightHover: 'color-background-success-light-hover',
+      dangerLightHover: 'color-background-danger-light-hover',
+      subduedLightHover: 'color-background-subdued-light-hover',
+      informationFilled: 'color-background-information-filled',
+      informationFilledHover: 'color-background-information-filled-hover',
+      informationLight: 'color-background-information-light',
+      informationLightHover: 'color-background-information-light-hover',
+      inverseFilled: 'color-background-inverse-filled',
+      inverseFilledHover: 'color-background-inverse-filled-hover',
+      input: 'color-background-input',
+      backdrop: 'color-background-backdrop',
+    },
+    stroke: {
+      default: 'color-stroke-default',
+      light: 'color-stroke-light',
+      primaryDefault: 'color-stroke-primary-default',
+      successDefault: 'color-stroke-success-default',
+      dangerDefault: 'color-stroke-danger-default',
+      subduedStrong: 'color-stroke-subdued-strong',
+      warningDefault: 'color-stroke-warning-default',
+      informationDefault: 'color-stroke-information-default',
+      focusDefault: 'color-stroke-focus-default',
+      inverse: 'color-stroke-inverse',
+      subduedDefault: 'color-stroke-subdued-default',
+      strong: 'color-stroke-strong',
+      icon: 'color-stroke-icon',
+      focusStrong: 'color-stroke-focus-strong',
+    },
+    icon: {
+      light: 'color-icon-light',
+      dangerDefault: 'color-icon-danger-default',
+      dangerDisabled: 'color-icon-danger-disabled',
+      warningDefault: 'color-icon-warning-default',
+      warningStrong: 'color-icon-warning-strong',
+      dangerStrong: 'color-icon-danger-strong',
+      informationDefault: 'color-icon-information-default',
+      informationStrong: 'color-icon-information-strong',
+      successDefault: 'color-icon-success-default',
+      successStrong: 'color-icon-success-strong',
+      default: 'color-icon-default',
+      inverse: 'color-icon-inverse',
+      primaryDefault: 'color-icon-primary-default',
+      primaryStrong: 'color-icon-primary-strong',
+      medium: 'color-icon-medium',
+    },
+  },
+  radius: {
+    xs: 'radius-xs',
+    lg: 'radius-lg',
+    xl: 'radius-xl',
+    md: 'radius-md',
+    sm: 'radius-sm',
+    full: 'radius-full',
+    '2xl': 'radius-2xl',
+    '3xl': 'radius-3xl',
+    default: 'radius-default',
+  },
+  spacing: {
+    '3xs': 'spacing-3xs',
+    '2xs': 'spacing-2xs',
+    xs: 'spacing-xs',
+    md: 'spacing-md',
+    lg: 'spacing-lg',
+    xl: 'spacing-xl',
+    '2xl': 'spacing-2xl',
+    '3xl': 'spacing-3xl',
+    '4xl': 'spacing-4xl',
+    '5xl': 'spacing-5xl',
+    sm: 'spacing-sm',
+  },
+  shadow: {
+    sm: 'shadow-sm',
+    md: 'shadow-md',
+    lg: 'shadow-lg',
+    xl: 'shadow-xl',
+  },
+});

package/src/theme/themeVars.ts

@@ -0,0 +1,31 @@
+/**
+ * Theme contract value types and helper for use in React (inline styles, Mantine props).
+ * Contract values are variable names (e.g. 'color-background-primary-light'); use toCssVar()
+ * when you need a full CSS value for style or bg.
+ */
+
+import type { tokens } from './themeContract.css';
+
+/** Union of background color variable names from the theme contract */
+export type BackgroundColorVar =
+  (typeof tokens.color.background)[keyof typeof tokens.color.background];
+
+/** Union of text color variable names from the theme contract */
+export type TextColorVar =
+  (typeof tokens.color.text)[keyof typeof tokens.color.text];
+
+/** Union of stroke/border color variable names from the theme contract */
+export type StrokeColorVar =
+  (typeof tokens.color.stroke)[keyof typeof tokens.color.stroke];
+
+/** Union of icon color variable names from the theme contract */
+export type IconColorVar =
+  (typeof tokens.color.icon)[keyof typeof tokens.color.icon];
+
+/**
+ * Convert a theme contract variable name to a CSS var() value.
+ * Use when passing a contract value into style or Mantine props (e.g. bg, backgroundColor).
+ */
+export function toCssVar(varName: string): string {
+  return `var(--${varName})`;
+}