variantProperties API
variantProperties
can be used when importing in Advanced mode
or directly in your stories’ code.
variantProperties
can be one of the following 3 types:
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:
Story arg name | Story arg type | Figma variant property name | Figma variant property values | |
---|---|---|---|---|
size | s , m , l | → | size | s , m , l |
disabled | true, false | → | disabled | true , false |
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:
Story arg name | Story arg type | Figma variant property name | Figma variant property values | |
---|---|---|---|---|
size | s , m , l | → | Size | Small , Medium , Large |
disabled | true, false | → | State | OFF , ON |
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:
Story arg name | Story arg type | Figma variant property name | Figma variant property values | |
---|---|---|---|---|
min | number | → | N/A | N/A |
max | number | → | N/A | N/A |
value | number | → | Progress | 0% , 25% , 50% , 100% |
size | s , m , l | → | Size | Small , Medium , Large |
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.