Everything for variants in one place: enabling stacking on the collection, adding variants to a token, the collection page where you manage variant tokens and build reusable action templates, and what the holder sees when they run the action. A variant is a different version of the same token with a different name and asset — everything else about the token stays the same.
Supersedes and consolidates variants-states-gallery-2026-06-29.html, token-variant-authoring-states-gallery-2026-07-16.html, and variant-reveal-states-gallery-2026-07-07.html. Source: Design Documentation/WIP/token-state-design.md. Related: Token draft · My Tokens.
Setup · creator
01What a variant isDeveloper reference — not a screen. The model in four rules; every frame below follows them.
The model
A variant = a different version of the same token
It has a different name and a different asset. Everything else about the token stays the same. The creator sets rules for what has to happen for the token to switch to a particular variant.
The Original Token is always the default variant
The token's name and main asset are the Original Token — the default variant. There is never a time when the default isn't set, and only the default variant can be minted.
First iteration: switch by a user action only
The only way a token moves from one variant to another is a user action the creator sets up (e.g. an “Open” button). An action can be reversible or permanent.
Coming later (not in the launch candidate)
A future version will let an action require a payment or the burning of another token before it runs. Recorded in the design docs; not built for launch.
02Collection · Supply — enable stackingStacking must be turned on here for any stacking options — including variants — to be available on the collection's tokens. It locks when the collection goes live.
Collection-wide supply settings. Turn stacking on to unlock stacking options on your tokens.
Lets identical copies stack, and unlocks token variants. Locks when the collection goes live.
With stacking on, each token can add variants (frame 03). With it off, the Variants tab tells the creator to enable stacking first.
Frozen when the collection went live — can't be changed.
On · locked
03Token · Variants tab — no variants yetA new tab on the token editor, so a creator who isn't using variants never sees the options. The tab opens with a plain explanation, shows the Original Token as the default, and — if there are no other variants — a short message and one button.
Edit token · Variants Draft
Variants are different versions of the same token that have a different name and different asset. Everything else about the token stays the same. You can set rules to determine what needs to happen for the token to switch to a particular variant.
Dollar Wallet
Original Token · the default · the only one that mints
Default
This token does not have any variants. If you do not wish to add any, there is nothing more to do here.
04Add a variantAdding a variant needs two things: an asset (uploaded, or picked from the collection's existing assets — the standard image picker) and a name. Nothing else about the token changes.
Add variant
05Token · Variants tab — with variantsEach variant shows its asset and name, with edit and delete. The Original Token stays pinned as the default and can't be deleted. Editing a variant lets you overwrite the asset and change the name.
Edit token · Variants Draft
Variants are different versions of the same token that have a different name and different asset. Everything else stays the same.
Dollar Wallet
Original Token · the default · the only one that mints
Default
Opened Wallet
Variant
Golden Wallet
Variant
The action that switches between these variants is set on the collection's Variant tokens page (frame 07) — so the same wording can be reused across tokens.
06Edit a variantThe same two fields as adding — overwrite the asset, change the name. (The Original Token / default is edited from the token's Details & Assets tabs, like any token.)
Edit variant · Opened Wallet
Actions & templates · creator
07Collection · Variant tokensA page in the collection listing the tokens that have variants. Here the creator builds reusable action templates and applies them to tokens — so the same action name, button wording and warning can be shared across many tokens.
Tokens that have variants, and the action that switches between them. Manage the reusable templates here.
Token
Variants
Action template
Edit
Dollar Wallet
Opened Wallet · Golden Wallet
Open (permanent)
Relic
Forged Relic
Open (permanent)
Seedling
Sprout · Bloom
None yet
08Manage templatesOpened from “Manage templates” on the Variant tokens page. The collection's reusable action templates in one list — each can be applied to many tokens. “New template” (and Edit) open the template editor (frame 09).
Reusable action wording you can apply to any token with variants.
Template
Button wording
Reversible
Used by
Actions
Open (permanent)
Open
No
2 tokens
Reveal (permanent)
Reveal
No
1 token
Evolve (reversible)
Evolve
Yes
0 tokens
09Variant action templateThe reusable part: a named template holding the wording and behaviour of the switch. In the first iteration the switch is always a user action. The which-variant mapping is chosen per token (frame 10), so one template fits many tokens.
Action template
Internal — how you'll find this template in the list.
What this action is called in your studio.
Suggested: “Open”.
If yes, the holder can change it back — you pick the variant it reverts to when you apply this to a token.
Coming later: requiring a payment or the burning of another token before the action runs. Not part of the launch candidate.
10Apply an action to a tokenEditing a token with variants: pick a template from the dropdown (or create a new one), then choose which variant the Original Token changes to. If the template is reversible, choose the variant it reverts to — the Original Token is always an option.
Dollar Wallet · action
With a reversible template this offers each variant plus the Original Token.
The holder mints the Original Token and taps Open to change it to the chosen variant. Only the Original Token can be minted.
Holder · wallet
11In your walletA token with an action shows the creator's button (here, “Open”), only when it's yours, active, and not listed. The card shows the token's current name and asset — there's no variant-state label on it.
Dollar Wallet
Paper Trail
Dollar Wallet
#042
Limited edition
Opened Wallet
Paper Trail
Opened Wallet
#017
Limited edition
Left: still the Original Token, so the Open action shows. Right: already changed to the Opened Wallet variant — the action has run, so it just shows the token as it now is (no “nothing to do here” copy).
12The prompt · in the creator's wordsBefore the action runs, the holder sees the creator's warning and confirms. Amber caution — this changes the token, it doesn't delete it. Two examples: a permanent action and a reversible one.
Open this token?
✕
Warning — you're about to Open this token. This change is permanent and can't be undone.
Are you sure?
Evolve this token?
✕
Warning — you're about to Evolve this token. This change is reversible — you can change it back to the Original Token later.
Are you sure?
13After the actionThe token now shows the variant's name and asset. Left: a permanent action — the token simply is the new variant now. Right: a reversible action offers the way back, using the button and target variant the creator chose.