@figma-vars/hooks 1.3.1 → 1.3.3

package/README.md

@@ -1,11 +1,16 @@
 # @figma-vars/hooks
 
+<p align="left">
+  <img src="assets/figma-vars-tagline-light.png" alt="FigmaVars Logo" width="700px" />
+</p>
+
 A fast, typed React 19 hooks library for the Figma Variables API: fetch, update, and manage design tokens via the official [Figma REST API](https://www.figma.com/developers/api#variables).
 
 Built for the modern web, this library provides a suite of hooks to fetch, manage, and mutate your design tokens, making it easy to sync them between Figma and your React applications, Storybooks, or design system dashboards.
 
 ![Status](https://img.shields.io/badge/status-stable-brightgreen)
 ![CI](https://github.com/marklearst/figma-vars-hooks/actions/workflows/publish.yml/badge.svg)
+[![codecov](https://codecov.io/gh/marklearst/figma-vars-hooks/branch/main/graph/badge.svg)](https://codecov.io/gh/marklearst/figma-vars-hooks)
 ![License](https://img.shields.io/github/license/marklearst/figma-vars-hooks)
 ![GitHub last commit](https://img.shields.io/github/last-commit/marklearst/figma-vars-hooks)
 ![GitHub code size](https://img.shields.io/github/languages/code-size/marklearst/figma-vars-hooks)
@@ -196,5 +201,5 @@ PRs and issues are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for gu
 
 ## 📝 License
 
-This project is licensed under the [MIT License](LICENSE).  
+This project is licensed under the [MIT License](LICENSE).
 © 2024–2025 Mark Learst

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { JSX as JSX_2 } from 'react/jsx-runtime';
-import { MutationResult as MutationResult_2 } from '..';
+import { MutationResult as MutationResult_2 } from '../types/mutations';
+import { MutationResult as MutationResult_3 } from '..';
 import { ReactNode } from 'react';
 
 /**
@@ -8,7 +9,7 @@ import { ReactNode } from 'react';
  * This corresponds to the `POST /v1/files/:file_key/variables` endpoint.
  * Note: Figma has deprecated this complex endpoint in favor of simpler, more granular ones.
  * This type is kept for legacy purposes but its usage is not recommended.
- *
+ * 
  * @typedef {Object} BulkUpdatePayload
  * @memberof Types
  * @since 1.0.0
@@ -20,18 +21,45 @@ import { ReactNode } from 'react';
  */
 export declare interface BulkUpdatePayload {
     /** A list of changes to variable collections. */
-    variableCollections?: VariableCollectionChange[];
+    variableCollections?: VariableCollectionChange[]
     /** A list of changes to variable modes. */
-    variableModes?: VariableModeChange[];
+    variableModes?: VariableModeChange[]
     /** A list of changes to variables. */
-    variables?: VariableChange[];
+    variables?: VariableChange[]
     /** A list of changes to variable values in specific modes. */
-    variableModeValues?: VariableModeValue[];
+    variableModeValues?: VariableModeValue[]
 }
 
 /**
- * The response object returned by the `bulkUpdateVariables` function.
+ * The payload for the `bulkUpdateVariables` function.
+ * Allows creating, updating, and deleting multiple variables, collections, and modes in one call.
+ * This corresponds to the `POST /v1/files/:file_key/variables` endpoint.
+ * Note: Figma has deprecated this complex endpoint in favor of simpler, more granular ones.
+ * This type is kept for legacy purposes but its usage is not recommended.
  *
+ * @typedef {Object} BulkUpdatePayload
+ * @memberof Types
+ * @since 1.0.0
+ * @see {@link https://www.figma.com/developers/api#post-variables|Figma API - Bulk Update Variables}
+ * @property {VariableCollectionChange[]} [variableCollections] A list of changes to variable collections.
+ * @property {VariableModeChange[]} [variableModes] A list of changes to variable modes.
+ * @property {VariableChange[]} [variables] A list of changes to variables.
+ * @property {VariableModeValue[]} [variableModeValues] A list of changes to variable values in specific modes.
+ */
+declare interface BulkUpdatePayload_2 {
+    /** A list of changes to variable collections. */
+    variableCollections?: VariableCollectionChange_2[];
+    /** A list of changes to variable modes. */
+    variableModes?: VariableModeChange_2[];
+    /** A list of changes to variables. */
+    variables?: VariableChange_2[];
+    /** A list of changes to variable values in specific modes. */
+    variableModeValues?: VariableModeValue_2[];
+}
+
+/**
+ * The response object returned by the `bulkUpdateVariables` function.
+ * 
  * @typedef {Object} BulkUpdateResponse
  * @memberof Types
  * @since 1.0.0
@@ -43,17 +71,17 @@ export declare interface BulkUpdatePayload {
  * @property {Record<string, string>} [meta.tempIdToRealId] A mapping of temporary IDs to real IDs for created variables.
  */
 export declare interface BulkUpdateResponse {
-    error: boolean;
-    status: number;
-    message?: string;
+    error: boolean
+    status: number
+    message?: string
     meta?: {
-        tempIdToRealId: Record<string, string>;
-    };
+        tempIdToRealId: Record<string, string>
+    }
 }
 
 /**
  * Represents a color in RGBA format.
- *
+ * 
  * @typedef {Object} Color
  * @memberof Types
  * @since 1.0.0
@@ -64,6 +92,29 @@ export declare interface BulkUpdateResponse {
  * @property {number} a The alpha (opacity) channel value (0-1).
  */
 export declare interface Color {
+    /** The red channel value (0-1). */
+    r: number
+    /** The green channel value (0-1). */
+    g: number
+    /** The blue channel value (0-1). */
+    b: number
+    /** The alpha (opacity) channel value (0-1). */
+    a: number
+}
+
+/**
+ * Represents a color in RGBA format.
+ *
+ * @typedef {Object} Color
+ * @memberof Types
+ * @since 1.0.0
+ * @see {@link https://www.figma.com/developers/api#color-object|Figma Color Object}
+ * @property {number} r The red channel value (0-1).
+ * @property {number} g The green channel value (0-1).
+ * @property {number} b The blue channel value (0-1).
+ * @property {number} a The alpha (opacity) channel value (0-1).
+ */
+declare interface Color_2 {
     /** The red channel value (0-1). */
     r: number;
     /** The green channel value (0-1). */
@@ -77,7 +128,7 @@ export declare interface Color {
 /**
  * The payload for the `createVariable` function.
  * Defines the properties for a new variable.
- *
+ * 
  * @typedef {Object} CreateVariablePayload
  * @memberof Types
  * @since 1.0.0
@@ -92,25 +143,59 @@ export declare interface Color {
  * @property {Record<string, VariableValue>} [valuesByMode] Initial values for the variable by mode ID.
  */
 export declare interface CreateVariablePayload {
+    /** The name of the new variable. */
+    name: string
+    /** The ID of the collection the new variable should be added to. */
+    variableCollectionId: string
+    /** The underlying data type for the new variable. */
+    resolvedType: ResolvedType
+    /** An optional description for the new variable. */
+    description?: string
+    /** Whether the new variable should be hidden when publishing. Defaults to `false`. */
+    hiddenFromPublishing?: boolean
+    /** The scopes in which this variable can be used. */
+    scopes?: VariableScope[]
+    /** Platform-specific code syntax for this variable. */
+    codeSyntax?: Record<string, string>
+}
+
+/**
+ * The payload for the `createVariable` function.
+ * Defines the properties for a new variable.
+ *
+ * @typedef {Object} CreateVariablePayload
+ * @memberof Types
+ * @since 1.0.0
+ * @see {@link https://www.figma.com/developers/api#post-variables|Figma API - Create Variable}
+ * @property {string} name The name of the new variable.
+ * @property {string} variableCollectionId The ID of the collection the new variable should be added to.
+ * @property {ResolvedType} resolvedType The underlying data type for the new variable.
+ * @property {string} [description] An optional description for the new variable.
+ * @property {boolean} [hiddenFromPublishing] Whether the new variable should be hidden when publishing. Defaults to `false`.
+ * @property {VariableScope[]} [scopes] The scopes in which this variable can be used.
+ * @property {Record<string, string>} [codeSyntax] Platform-specific code syntax for this variable.
+ * @property {Record<string, VariableValue>} [valuesByMode] Initial values for the variable by mode ID.
+ */
+declare interface CreateVariablePayload_2 {
     /** The name of the new variable. */
     name: string;
     /** The ID of the collection the new variable should be added to. */
     variableCollectionId: string;
     /** The underlying data type for the new variable. */
-    resolvedType: ResolvedType;
+    resolvedType: ResolvedType_2;
     /** An optional description for the new variable. */
     description?: string;
     /** Whether the new variable should be hidden when publishing. Defaults to `false`. */
     hiddenFromPublishing?: boolean;
     /** The scopes in which this variable can be used. */
-    scopes?: VariableScope[];
+    scopes?: VariableScope_2[];
     /** Platform-specific code syntax for this variable. */
     codeSyntax?: Record<string, string>;
 }
 
 /**
  * Represents a collection of Figma variables, which can contain multiple modes.
- *
+ * 
  * @typedef {Object} FigmaCollection
  * @memberof Types
  * @since 1.0.0
@@ -125,24 +210,24 @@ export declare interface CreateVariablePayload {
  */
 export declare interface FigmaCollection {
     /** The unique identifier for the collection. */
-    id: string;
+    id: string
     /** The name of the collection (e.g., "Brand Colors"). */
-    name: string;
+    name: string
     /** An array of modes available in this collection. */
-    modes: VariableMode[];
+    modes: VariableMode[]
     /** The ID of the default mode for this collection. */
-    defaultModeId: string;
+    defaultModeId: string
     /** An array of variable IDs that belong to this collection. */
-    variableIds: string[];
+    variableIds: string[]
     /** Whether the collection is hidden when publishing the library. */
-    hiddenFromPublishing: boolean;
+    hiddenFromPublishing: boolean
     /** The timestamp of the last update. */
-    updatedAt: string;
+    updatedAt: string
 }
 
 /**
  * A generic error shape for failed Figma API requests.
- *
+ * 
  * @typedef {Object} FigmaError
  * @memberof Types
  * @since 1.0.0
@@ -152,16 +237,16 @@ export declare interface FigmaCollection {
  */
 export declare interface FigmaError {
     /** The HTTP status code of the error. */
-    statusCode: number;
+    statusCode: number
     /** The error message from the API. */
-    message: string;
+    message: string
 }
 
 /* Excluded from this release type: FigmaTokenContextType */
 
 /**
  * Represents a single Figma variable.
- *
+ * 
  * @typedef {Object} FigmaVariable
  * @memberof Types
  * @since 1.0.0
@@ -179,25 +264,25 @@ export declare interface FigmaError {
  */
 export declare interface FigmaVariable {
     /** The unique identifier for the variable. */
-    id: string;
+    id: string
     /** The name of the variable. */
-    name: string;
+    name: string
     /** The ID of the collection this variable belongs to. */
-    variableCollectionId: string;
+    variableCollectionId: string
     /** The underlying data type of the variable. */
-    resolvedType: ResolvedType;
+    resolvedType: ResolvedType
     /** A map of mode IDs to the variable's value in that mode. */
-    valuesByMode: Record<string, VariableValue>;
+    valuesByMode: Record<string, VariableValue>
     /** The description of the variable, as set in Figma. */
-    description: string;
+    description: string
     /** Whether the variable is hidden when publishing the library. */
-    hiddenFromPublishing: boolean;
+    hiddenFromPublishing: boolean
     /** The scopes in which this variable can be used. */
-    scopes: VariableScope[];
+    scopes: VariableScope[]
     /** Platform-specific code syntax for this variable (e.g., for Web, iOS, Android). */
-    codeSyntax: Record<string, string>;
+    codeSyntax: Record<string, string>
     /** The timestamp of the last update. */
-    updatedAt: string;
+    updatedAt: string
 }
 
 /**
@@ -249,11 +334,11 @@ export declare interface FigmaVariable {
  * }
  * ```
  */
-export declare const FigmaVarsProvider: ({ children, token, fileKey, }: FigmaVarsProviderProps) => JSX_2.Element;
+export declare const FigmaVarsProvider: ({ children, token, fileKey, }: FigmaVarsProviderProps_2) => JSX_2.Element;
 
 /**
  * Props for the `FigmaVarsProvider` component.
- *
+ * 
  * @typedef {Object} FigmaVarsProviderProps
  * @memberof Types
  * @since 1.0.0
@@ -262,6 +347,31 @@ export declare const FigmaVarsProvider: ({ children, token, fileKey, }: FigmaVar
  * @property {string | null} fileKey The Figma file key extracted from the file URL.
  */
 export declare interface FigmaVarsProviderProps {
+    /** The child components that will have access to the context. */
+    children: ReactNode
+    /**
+     * Your Figma Personal Access Token.
+     * @see https://www.figma.com/developers/api#authentication
+     */
+    token: string | null
+    /**
+     * The unique identifier of the Figma file you want to access.
+     * You can get this from the file's URL.
+     */
+    fileKey: string | null
+}
+
+/**
+ * Props for the `FigmaVarsProvider` component.
+ *
+ * @typedef {Object} FigmaVarsProviderProps
+ * @memberof Types
+ * @since 1.0.0
+ * @property {ReactNode} children The child components that will have access to the context.
+ * @property {string | null} token The Figma Personal Access Token for API authentication.
+ * @property {string | null} fileKey The Figma file key extracted from the file URL.
+ */
+declare interface FigmaVarsProviderProps_2 {
     /** The child components that will have access to the context. */
     children: ReactNode;
     /**
@@ -349,7 +459,7 @@ export declare function filterVariables(variables: FigmaVariable[], criteria: {
 
 /**
  * The structure of the successful response from the Figma API's `/v1/files/{file_key}/variables/local` endpoint.
- *
+ * 
  * @typedef {Object} LocalVariablesResponse
  * @memberof Types
  * @since 1.0.0
@@ -362,17 +472,17 @@ export declare interface LocalVariablesResponse {
     /** Contains the metadata about the variables and collections. */
     meta: {
         /** A map of collection IDs to `FigmaCollection` objects. */
-        variableCollections: Record<string, FigmaCollection>;
+        variableCollections: Record<string, FigmaCollection>
         /** A map of variable IDs to `FigmaVariable` objects. */
-        variables: Record<string, FigmaVariable>;
-    };
+        variables: Record<string, FigmaVariable>
+    }
 }
 
 /**
  * The result object returned by the `useMutation` hook.
  * @template TData The type of data returned by the mutation.
  * @template TPayload The type of the payload passed to the mutate function.
- *
+ * 
  * @typedef {Object} MutationResult
  * @memberof Types
  * @since 1.0.0
@@ -385,20 +495,20 @@ export declare interface LocalVariablesResponse {
  * @property {boolean} isError Whether the mutation resulted in an error.
  */
 export declare interface MutationResult<TData, TPayload> {
-    mutate: (payload: TPayload) => Promise<TData | undefined>;
-    status: 'idle' | 'loading' | 'success' | 'error';
-    data: TData | null;
-    error: Error | null;
-    isLoading: boolean;
-    isSuccess: boolean;
-    isError: boolean;
+    mutate: (payload: TPayload) => Promise<TData | undefined>
+    status: 'idle' | 'loading' | 'success' | 'error'
+    data: TData | null
+    error: Error | null
+    isLoading: boolean
+    isSuccess: boolean
+    isError: boolean
 }
 
 /**
  * Represents the state of a mutation operation.
  * @template TData The type of data returned by the mutation.
  * @template TError The type of error returned by the mutation.
- *
+ * 
  * @typedef {Object} MutationState
  * @memberof Types
  * @since 1.0.0
@@ -407,11 +517,29 @@ export declare interface MutationResult<TData, TPayload> {
  * @property {Error | null} error The error returned by the mutation, or null if the mutation was successful.
  */
 export declare interface MutationState<TData> {
-    status: 'idle' | 'loading' | 'success' | 'error';
-    data: TData | null;
-    error: Error | null;
+    status: 'idle' | 'loading' | 'success' | 'error'
+    data: TData | null
+    error: Error | null
 }
 
+/**
+ * @fileoverview TypeScript type definitions for the Figma Variables REST API.
+ * These types match the official Figma API specification for variables, collections, and modes.
+ * @see {@link https://www.figma.com/developers/api#variables|Figma Variables API Documentation}
+ * @since 1.0.0
+ */
+
+/**
+ * The resolved type of a Figma variable.
+ * Determines what kind of value the variable can hold.
+ * 
+ * @typedef {string} ResolvedType
+ * @memberof Types
+ * @since 1.0.0
+ * @see {@link https://www.figma.com/developers/api#variable-object|Figma Variable Object}
+ */
+export declare type ResolvedType = 'BOOLEAN' | 'FLOAT' | 'STRING' | 'COLOR'
+
 /**
  * @fileoverview TypeScript type definitions for the Figma Variables REST API.
  * These types match the official Figma API specification for variables, collections, and modes.
@@ -427,17 +555,17 @@ export declare interface MutationState<TData> {
  * @since 1.0.0
  * @see {@link https://www.figma.com/developers/api#variable-object|Figma Variable Object}
  */
-export declare type ResolvedType = 'BOOLEAN' | 'FLOAT' | 'STRING' | 'COLOR';
+declare type ResolvedType_2 = 'BOOLEAN' | 'FLOAT' | 'STRING' | 'COLOR';
 
 declare type UpdateVariableArgs = {
     variableId: string;
-    payload: UpdateVariablePayload;
+    payload: UpdateVariablePayload_2;
 };
 
 /**
  * The payload for the `updateVariable` function.
  * All properties are optional.
- *
+ * 
  * @typedef {Object} UpdateVariablePayload
  * @memberof Types
  * @since 1.0.0
@@ -450,6 +578,34 @@ declare type UpdateVariableArgs = {
  * @property {Record<string, VariableValue>} [valuesByMode] New values for the variable by mode ID.
  */
 export declare interface UpdateVariablePayload {
+    /** The new name for the variable. */
+    name?: string
+    /** The new description for the variable. */
+    description?: string
+    /** The new hidden status for the variable. */
+    hiddenFromPublishing?: boolean
+    /** The new scopes for the variable. */
+    scopes?: VariableScope[]
+    /** The new code syntax for the variable. */
+    codeSyntax?: Record<string, string>
+}
+
+/**
+ * The payload for the `updateVariable` function.
+ * All properties are optional.
+ *
+ * @typedef {Object} UpdateVariablePayload
+ * @memberof Types
+ * @since 1.0.0
+ * @see {@link https://www.figma.com/developers/api#patch-variables|Figma API - Update Variable}
+ * @property {string} [name] The new name for the variable.
+ * @property {string} [description] The new description for the variable.
+ * @property {boolean} [hiddenFromPublishing] The new hidden status for the variable.
+ * @property {VariableScope[]} [scopes] The new scopes for the variable.
+ * @property {Record<string, string>} [codeSyntax] The new code syntax for the variable.
+ * @property {Record<string, VariableValue>} [valuesByMode] New values for the variable by mode ID.
+ */
+declare interface UpdateVariablePayload_2 {
     /** The new name for the variable. */
     name?: string;
     /** The new description for the variable. */
@@ -457,7 +613,7 @@ export declare interface UpdateVariablePayload {
     /** The new hidden status for the variable. */
     hiddenFromPublishing?: boolean;
     /** The new scopes for the variable. */
-    scopes?: VariableScope[];
+    scopes?: VariableScope_2[];
     /** The new code syntax for the variable. */
     codeSyntax?: Record<string, string>;
 }
@@ -530,7 +686,7 @@ export declare interface UpdateVariablePayload {
  * });
  * ```
  */
-export declare const useBulkUpdateVariables: () => MutationResult_2<any, BulkUpdatePayload>;
+export declare const useBulkUpdateVariables: () => MutationResult_2<any, BulkUpdatePayload_2>;
 
 /**
  * Creates a new variable in the Figma file.
@@ -588,7 +744,7 @@ export declare const useBulkUpdateVariables: () => MutationResult_2<any, BulkUpd
  * });
  * ```
  */
-export declare const useCreateVariable: () => MutationResult_2<any, CreateVariablePayload>;
+export declare const useCreateVariable: () => MutationResult_2<any, CreateVariablePayload_2>;
 
 /**
  * Deletes a variable from the Figma file by its ID.
@@ -605,7 +761,7 @@ export declare const useCreateVariable: () => MutationResult_2<any, CreateVariab
  *
  * @example
  * ```tsx
- * import { useDeleteVariable } from './useDeleteVariable';
+ * import { useDeleteVariable } from '@figma-vars/hooks';
  *
  * function VariableDeleter({ variableId }) {
  *   const { mutate, isLoading, isSuccess, error } = useDeleteVariable();
@@ -637,7 +793,7 @@ export declare const useCreateVariable: () => MutationResult_2<any, CreateVariab
  * deleteVariable('VariableID:123:456');
  * ```
  */
-export declare const useDeleteVariable: () => MutationResult_2<any, string>;
+export declare const useDeleteVariable: () => MutationResult_3<any, string>;
 
 /**
  * Retrieves the Figma API token from the FigmaVarsProvider.
@@ -652,7 +808,7 @@ export declare const useDeleteVariable: () => MutationResult_2<any, string>;
  *
  * @example
  * ```tsx
- * import { useFigmaToken } from './useFigmaToken';
+ * import { useFigmaToken } from '@figma-vars/hooks';
  *
  * function CustomAPIComponent() {
  *   const figmaToken = useFigmaToken();
@@ -796,12 +952,12 @@ export declare const useVariableCollections: () => {
  * return <div>Mode: {lightMode.name}</div>
  * ```
  */
-export declare const useVariableModes: () => UseVariableModesResult;
+export declare const useVariableModes: () => UseVariableModesResult_2;
 
 /**
  * The return type for the `useVariableModes` hook.
  * Provides multiple ways to access and organize variable modes from Figma collections.
- *
+ * 
  * @typedef {Object} UseVariableModesResult
  * @memberof Types
  * @since 1.0.0
@@ -812,11 +968,32 @@ export declare const useVariableModes: () => UseVariableModesResult;
  */
 export declare interface UseVariableModesResult {
     /** A flat array of all modes across all collections. */
-    modes: VariableMode[];
+    modes: VariableMode[]
+    /** A map of collection IDs to an array of modes belonging to that collection. */
+    modesByCollectionId: Record<string, VariableMode[]>
+    /** A map of mode IDs to the corresponding mode object for quick lookups. */
+    modesById: Record<string, VariableMode>
+}
+
+/**
+ * The return type for the `useVariableModes` hook.
+ * Provides multiple ways to access and organize variable modes from Figma collections.
+ *
+ * @typedef {Object} UseVariableModesResult
+ * @memberof Types
+ * @since 1.0.0
+ * @see {@link useVariableModes} - The hook that returns this type
+ * @property {VariableMode[]} modes A flat array of all modes across all collections.
+ * @property {Record<string, VariableMode[]>} modesByCollectionId A map of collection IDs to an array of modes belonging to that collection.
+ * @property {Record<string, VariableMode>} modesById A map of mode IDs to the corresponding mode object for quick lookups.
+ */
+declare interface UseVariableModesResult_2 {
+    /** A flat array of all modes across all collections. */
+    modes: VariableMode_2[];
     /** A map of collection IDs to an array of modes belonging to that collection. */
-    modesByCollectionId: Record<string, VariableMode[]>;
+    modesByCollectionId: Record<string, VariableMode_2[]>;
     /** A map of mode IDs to the corresponding mode object for quick lookups. */
-    modesById: Record<string, VariableMode>;
+    modesById: Record<string, VariableMode_2>;
 }
 
 /**
@@ -850,10 +1027,12 @@ export declare const useVariables: () => {
 
 /* Excluded from this release type: VariableAction */
 
+/* Excluded from this release type: VariableAction_2 */
+
 /**
  * Represents an alias to another Figma variable.
  * This is used when a variable's value is set to reference another variable.
- *
+ * 
  * @typedef {Object} VariableAlias
  * @memberof Types
  * @since 1.0.0
@@ -862,6 +1041,24 @@ export declare const useVariables: () => {
  * @property {string} id The ID of the variable being referenced.
  */
 export declare interface VariableAlias {
+    /** The type of the value, indicating it's a variable alias. */
+    type: 'VARIABLE_ALIAS'
+    /** The ID of the variable being referenced. */
+    id: string
+}
+
+/**
+ * Represents an alias to another Figma variable.
+ * This is used when a variable's value is set to reference another variable.
+ *
+ * @typedef {Object} VariableAlias
+ * @memberof Types
+ * @since 1.0.0
+ * @see {@link https://www.figma.com/developers/api#variable-object|Figma Variable Object}
+ * @property {string} type The type of the value, indicating it's a variable alias.
+ * @property {string} id The ID of the variable being referenced.
+ */
+declare interface VariableAlias_2 {
     /** The type of the value, indicating it's a variable alias. */
     type: 'VARIABLE_ALIAS';
     /** The ID of the variable being referenced. */
@@ -870,11 +1067,15 @@ export declare interface VariableAlias {
 
 /* Excluded from this release type: VariableChange */
 
+/* Excluded from this release type: VariableChange_2 */
+
 /* Excluded from this release type: VariableCollectionChange */
 
+/* Excluded from this release type: VariableCollectionChange_2 */
+
 /**
  * Represents a single mode within a variable collection.
- *
+ * 
  * @typedef {Object} VariableMode
  * @memberof Types
  * @since 1.0.0
@@ -883,6 +1084,23 @@ export declare interface VariableAlias {
  * @property {string} name The name of the mode (e.g., "Light", "Dark").
  */
 export declare interface VariableMode {
+    /** The unique identifier for the mode. */
+    modeId: string
+    /** The name of the mode (e.g., "Light", "Dark"). */
+    name: string
+}
+
+/**
+ * Represents a single mode within a variable collection.
+ *
+ * @typedef {Object} VariableMode
+ * @memberof Types
+ * @since 1.0.0
+ * @see {@link https://www.figma.com/developers/api#variable-collection-object|Figma Variable Collection Object}
+ * @property {string} modeId The unique identifier for the mode.
+ * @property {string} name The name of the mode (e.g., "Light", "Dark").
+ */
+declare interface VariableMode_2 {
     /** The unique identifier for the mode. */
     modeId: string;
     /** The name of the mode (e.g., "Light", "Dark"). */
@@ -891,9 +1109,11 @@ export declare interface VariableMode {
 
 /* Excluded from this release type: VariableModeChange */
 
+/* Excluded from this release type: VariableModeChange_2 */
+
 /**
  * A change to a variable's value in a specific mode in a bulk update.
- *
+ * 
  * @typedef {Object} VariableModeValue
  * @memberof Types
  * @since 1.0.0
@@ -903,14 +1123,68 @@ export declare interface VariableMode {
  * @property {VariableValue} value The new value for the variable in this mode.
  */
 export declare interface VariableModeValue {
+    /** The ID of the variable to update. */
+    variableId: string
+    /** The ID of the mode to update. */
+    modeId: string
+    /** The new value for the variable in this mode. */
+    value: VariableValue
+}
+
+/**
+ * A change to a variable's value in a specific mode in a bulk update.
+ *
+ * @typedef {Object} VariableModeValue
+ * @memberof Types
+ * @since 1.0.0
+ * @see {@link https://www.figma.com/developers/api#patch-variables|Figma API - Update Variable Value}
+ * @property {string} variableId The ID of the variable to update.
+ * @property {string} modeId The ID of the mode to update.
+ * @property {VariableValue} value The new value for the variable in this mode.
+ */
+declare interface VariableModeValue_2 {
     /** The ID of the variable to update. */
     variableId: string;
     /** The ID of the mode to update. */
     modeId: string;
     /** The new value for the variable in this mode. */
-    value: VariableValue;
+    value: VariableValue_2;
 }
 
+/**
+ * The scopes where a Figma variable can be applied.
+ * `ALL_SCOPES` is a general-purpose scope. Other values restrict the variable to specific properties.
+ * 
+ * @typedef {string} VariableScope
+ * @memberof Types
+ * @since 1.0.0
+ * @see {@link https://www.figma.com/developers/api#variable-object|Figma Variable Object}
+ */
+export declare type VariableScope =
+| 'ALL_SCOPES'
+| 'TEXT_CONTENT'
+| 'CORNER_RADIUS'
+| 'WIDTH_HEIGHT'
+| 'GAP'
+| 'STROKE_FLOAT'
+| 'OPACITY'
+| 'EFFECT_FLOAT'
+| 'FONT_WEIGHT'
+| 'FONT_SIZE'
+| 'LINE_HEIGHT'
+| 'LETTER_SPACING'
+| 'PARAGRAPH_SPACING'
+| 'PARAGRAPH_INDENT'
+| 'FONT_FAMILY'
+| 'FONT_STYLE'
+| 'FONT_VARIATIONS'
+| 'ALL_FILLS'
+| 'FRAME_FILL'
+| 'SHAPE_FILL'
+| 'TEXT_FILL'
+| 'STROKE_COLOR'
+| 'EFFECT_COLOR'
+
 /**
  * The scopes where a Figma variable can be applied.
  * `ALL_SCOPES` is a general-purpose scope. Other values restrict the variable to specific properties.
@@ -920,7 +1194,18 @@ export declare interface VariableModeValue {
  * @since 1.0.0
  * @see {@link https://www.figma.com/developers/api#variable-object|Figma Variable Object}
  */
-export declare type VariableScope = 'ALL_SCOPES' | 'TEXT_CONTENT' | 'CORNER_RADIUS' | 'WIDTH_HEIGHT' | 'GAP' | 'STROKE_FLOAT' | 'OPACITY' | 'EFFECT_FLOAT' | 'FONT_WEIGHT' | 'FONT_SIZE' | 'LINE_HEIGHT' | 'LETTER_SPACING' | 'PARAGRAPH_SPACING' | 'PARAGRAPH_INDENT' | 'FONT_FAMILY' | 'FONT_STYLE' | 'FONT_VARIATIONS' | 'ALL_FILLS' | 'FRAME_FILL' | 'SHAPE_FILL' | 'TEXT_FILL' | 'STROKE_COLOR' | 'EFFECT_COLOR';
+declare type VariableScope_2 = 'ALL_SCOPES' | 'TEXT_CONTENT' | 'CORNER_RADIUS' | 'WIDTH_HEIGHT' | 'GAP' | 'STROKE_FLOAT' | 'OPACITY' | 'EFFECT_FLOAT' | 'FONT_WEIGHT' | 'FONT_SIZE' | 'LINE_HEIGHT' | 'LETTER_SPACING' | 'PARAGRAPH_SPACING' | 'PARAGRAPH_INDENT' | 'FONT_FAMILY' | 'FONT_STYLE' | 'FONT_VARIATIONS' | 'ALL_FILLS' | 'FRAME_FILL' | 'SHAPE_FILL' | 'TEXT_FILL' | 'STROKE_COLOR' | 'EFFECT_COLOR';
+
+/**
+ * The possible value types for a variable in a specific mode.
+ * It can be a primitive value, a color object, or an alias to another variable.
+ * 
+ * @typedef {(string|boolean|number|Color|VariableAlias)} VariableValue
+ * @memberof Types
+ * @since 1.0.0
+ * @see {@link https://www.figma.com/developers/api#variable-object|Figma Variable Object}
+ */
+export declare type VariableValue = string | boolean | number | Color | VariableAlias
 
 /**
  * The possible value types for a variable in a specific mode.
@@ -931,6 +1216,6 @@ export declare type VariableScope = 'ALL_SCOPES' | 'TEXT_CONTENT' | 'CORNER_RADI
  * @since 1.0.0
  * @see {@link https://www.figma.com/developers/api#variable-object|Figma Variable Object}
  */
-export declare type VariableValue = string | boolean | number | Color | VariableAlias;
+declare type VariableValue_2 = string | boolean | number | Color_2 | VariableAlias_2;
 
 export { }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@figma-vars/hooks",
-  "version": "1.3.1",
+  "version": "1.3.3",
   "description": "Typed React hooks for managing Figma Variables, modes, tokens, and bindings via API.",
   "author": "Mark Learst",
   "license": "MIT",
@@ -59,6 +59,7 @@
     "@types/react-dom": "^18.3.0",
     "@vitejs/plugin-react": "^4.5.2",
     "@vitest/coverage-v8": "^2.0.5",
+    "@vitest/ui": "2.1.9",
     "jsdom": "^26.1.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
@@ -77,9 +78,12 @@
   "scripts": {
     "dev": "vite",
     "build": "tsc && vite build",
-    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
+    "lint": "npx eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
     "preview": "vite preview",
     "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest watch",
     "postversion": "git push && git push --tags"
   }
 }