variantProperties API

variantProperties can be one of the following 3 types:

• string
• S2dArgVariant
• S2dComplexVariant

The string and S2dArgVariant are shortcuts to S2dComplexVariant.

string

string should be used if you only want to map a story arg to a Figma variant property without changing any names or values. story.to.design will source values from the argTypes of the story.

"variantProperties": [
  "size",
  "disabled"
],

Example

Story:

export const Playground = {
  argTypes: {
    size: { control: 'select', options: ['s', 'm', 'l'] },
    disabled: { control: 'boolean' },
  },
  //👇 Default values
  args: {
    disabled: false,
    size: 'm',
  },
};

story.to.design set-up:

"variantProperties": [
  "size",
  "disabled"
],

Translated results:

S2dArgVariant

S2dArgVariant lets you map story args to Figma variant properties.

{
  "fromArg" : "ArgName",           // Story arg name to create variants from
  "name"    : "VariantPropName",   // Variant property name in Figma (Optional - defaults to arg name)
  "values"  : [                    // Array of variant values mapped from arg values (Optional - defaults to arg values)
      {
         "name": "VariantPropValue1",   // Value in Figma's variant property
         "argValue": "ArgValue",        // Value in select arg (fromArg)
         "excludedArgs": {},            // Optional - Combinations to exclude
      },
      ...
  ],
  "axis"    :  "x" or "y" or "split"    // On which axis to display this variant in the matrix
}

Example

story.to.design set-up:

"variantProperties": [
  {
    "fromArg": "size",
    "name": "Size",
    "values": [
      { "name": "Small", "argValue": "s" },
      { "name": "Medium", "argValue": "m" },
      { "name": "Large", "argValue": "l" }
    ]
  },
  {
    "fromArg": "disable",
    "name": "State",
    "values": [
      { "name": "ON", "argValue": false },
      { "name": "OFF", "argValue": true }
    ]
  }
],

Translated results:

S2dComplexVariant

The S2dComplexVariant is the most powerful definition of a Figma variant property. It allows to you construct each Figma variant from a specific set of args.

{
  "name"    : "VariantPropName",   // Variant property name in Figma (Mandatory)
  "values"  : [                    // Array of variant values
      {
         "name": "VariantPropValue1",            // Value in Figma's variant property
         "withArgs": { "key": value, ... },      // Args (& pseudo args) to use when generating this variant
         "excludedArgs": { "key": value, ... }  // [Optional] Combinations to exclude
      },
      ...
  ],
  "axis"    :  "x" or "y" or "split"         // On which axis to display this variant in the matrix
}

Example

story.to.design set-up:

"variantProperties": [
  {
    "name": "Progress",
    "values": [
      { "name": "0%", "withArgs": { "value": 0, "min": 0, "max": 100 } },
      { "name": "25%", "withArgs": { "value": 25, "min": 0, "max": 100 } },
      { "name": "50%", "withArgs": { "value": 50, "min": 0, "max": 100 } },
      { "name": "75%", "withArgs": { "value": 75, "min": 0, "max": 100 } },
      { "name": "100%", "withArgs": { "value": 100, "min": 0, "max": 100 } }
    ]
  },
  {
    "name": "Size",
    "values": [
      { "name": "Small", "withArgs": { "size": "s" } },
      { "name": "Medium", "withArgs": { "size": "m" } },
      { "name": "Large", "withArgs": { "size": "l" } }
    ]
  }
],

Translated results: