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"          // 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"          // 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:

Meta arguments

Meta arguments are specific to story.to.design that allow you to customize how variants are imported.

:selector

By default, story.to.design looks for elements to be imported as components under the #root div. However, in some cases, you will want to target a different element. Some examples include:

• A modal that will be rendered with a portal out of the #root div
• If your stories’ elements are decorated with other elements, such as divs with a specific background color, in which case you would not want to import those divs

The :selector is a CSS query selector. An example could be .my-provider-class :first-child.

:actionSelector

This meta argument is specific to simulated states. It indicates which element to simulate the state on. A situation where you may want it is for example a button group, where you would want to be able to choose which button story.to.design should simulate interactions on.

Similarly to the :selector meta argument, it is also a CSS query selector. For example, you could use .button-group-class :nth-child(3) to target the 3rd child of an element within the button-group-class class.

:css

This meta argument allows you to create variants based on CSS themes. Here are a couple simple examples to illustrate it:

Example: Inline CSS theming

Create 2 themes red and blue that force CSS color:

    {
      "fromArg": ":css",
      "name": "css-theme",
      "values": [
        {"name": "red", "argValue": "<style>* { color: red }</style>"},
        {"name": "blue", "argValue": "<style>* { color: blue }</style>"}
      ]
    }

Example: Stylesheet-based theming

If you have different stylesheets for different themes, you can easily create variants out of them:

    {
      "fromArg": ":css",
      "name": "theme",
      "values": [
        {"name": "dark", "argValue": "<link rel="stylesheet" href="/css/dark.css">"},
        {"name": "light", "argValue": "<link rel="stylesheet" href="/css/light.css">"}
      ]
    }

:story

In some very specific cases, you may want to import variants for a same component from different stories. This meta argument allows you to do just that.