Tokens v2 migration

A project made before tokens v2 is on tokens v1: the original variable names (--space-0 … 7, --surface, --text, --radius-pill, --elevation-1 … 3, --density). Tokens v2 renames spacing, surfaces, text, radius and shadows, and adds motion. The Migrate card at the top of Studio › Design system › Properties moves a project over. Everything runs in the console, through the same reads and writes as any other edit. There is no separate migration API.

Take a backup first (Settings › Backups, parts project, web, content, files). It is the way back if you don't like the result.

A stylesheet already written in v2#

A project poured from a repository can carry a stylesheet that already uses the v2 names — --space-unit, --color-surface, --shadow-sm, the --space-N = N × unit ladder — while the project itself is still flagged v1. The card recognises that and shows Adopt tokens v2 instead of the scan and the switch. Do not look for a way to run the switch there: it would read every --space-N in your templates as the old index name and shift it a step, and it would recalculate values your stylesheet sets by hand.

Adopting changes nothing on the site. It flips the flag, reads the seeds from the stylesheet (the grid unit, the faces and their fallback stack, the weights, the base size, the container, the columns, the border width, the scheme) and pins every generated token the stylesheet defines differently — the ramp stops, the acting colours, surfaces and shadows, the type scale, line heights and tracking, the type roles, the radii, the section space, the motion values — so Properties shows the stylesheet's real values, each marked pinned. The stylesheet stays byte for byte. The card lists the few tokens it cannot pin because the generator writes them in a fixed form (the unit in px, the quoting of the font stacks, --color-text-on-primary): they keep the stylesheet's value as written and are rewritten to the generator's form only when you change that seed later.

After adopting, a Properties save changes only the seed you edited, in place — nothing else in the stylesheet moves. There is no frozen block to remove.

The scan#

Scan reads every place the project keeps code and lists where the old names are used:

• the newest template version of each schema (HTML, CSS, JS), the one documents without a pinned version render,
• the project's own elements,
• the site's head and footer tags,
• the project's own stylesheets under the site/css and kit folders in Media,
• and, listed separately, module content: the elements a module's kit mounted and the module's own runtime stylesheet.

Each row names the file, the old names it uses and how many times. Four counters sum up the project's own content: templates, elements, stylesheets, and line-height uses to check by hand. The last one is different: --leading-body, --leading-headline and the other --leading-{role} names exist in both vocabularies but changed unit, pixels in v1 and a unitless ratio in v2. They can be neither renamed nor frozen. Read each use and decide: line-height: var(--leading-body) keeps working, height: var(--leading-body) does not.

On a v1 project the scan also runs a dry run of the rewrite: it says how many texts the switch will rewrite, and Show changes lists the first twenty with their renames. A scan writes nothing.

What the switch does#

Rewrite and switch to v2 is for project managers. It does three things:

1. Rewrites the project's own files onto the new names: the templates, the project's own elements, the head and footer tags and the stylesheets. Every rename keeps the value:

   Old	New
   --space-1, --space-3, --space-4, --space-5, --space-6, --space-7	--space-1, --space-2, --space-3, --space-4, --space-6, --space-8
   var(--space-0), var(--space-2) (the half steps)	calc(var(--space-unit) * 0.5), calc(var(--space-unit) * 1.5)
   --surface, --surface-card, --surface-muted	--color-surface, --color-surface-card, --color-surface-alt
   --text (as var(--text)), --text-muted, --border-subtle	--color-text, --color-text-muted, --color-border
   --radius-pill	--radius-full
   --elevation-1, -2, -3; box-shadow: var(--elevation-0)	--shadow-sm, --shadow-md, --shadow-lg; none

   A custom token whose name v2 reserves (for example brand-gradient, since brand- is now taken) is renamed custom-{name}, and its uses follow. --leading-* and --density are not rewritten.

2. Switches the design to the v2 values. The grid unit becomes the project's old effective unit: the v1 unit times its density (compact 0.75, regular 1, comfortable 1.25), rounded to a whole pixel between 2 and 10. The card shows the value before you click. A project on 8 px × comfortable gets 10 px, so the rewritten --space-N names keep their pixel values. Everything else is calculated the v2 way from the same colours, fonts and choices: the colour ramps, each role's pairs, the surfaces, the fluid type scale with unitless line heights, the radius and the shadows. Shades, heading sizes and line heights change, and Properties shows the new values. Nothing is pinned to imitate v1; pins you set yourself on ramp stops and radius carry over.

3. Writes a frozen block for the few names v2 does not have, at the exact values they had that day: --space-7 in px, --surface → var(--color-surface) and the other aliases, --radius-pill → var(--radius-full), --elevation-0 … 3 → the shadows, --density.

Module and platform content. It is not rewritten. A module ships its own CSS and updates it in its own releases. Where that CSS already uses v2 names, it changes once those names start to resolve. A card that asked for var(--color-surface, #fff) was white on v1, where the name did not exist, and turns to the page colour. A kit spaced with --space-N meaning N units follows the project's unit. The cookie bar's buttons take the brand colour. Look at the module rows of the scan before you switch, and at the live site after.

Finishing#

After the switch, the card shows the frozen block and what is left: uses of the frozen names, in the project's content and in module content, plus the line-height hazards. The scan now counts only the frozen names, since --space-1 … 6 are ordinary v2 names from here on. Move what is left onto the new names, then Scan again.

Remove frozen names unlocks when a scan finds zero uses of the frozen names anywhere, module content included. The hazards don't block it; they are yours to judge. It runs a fresh scan, deletes the frozen block and regenerates the sheet. From then on the project is a plain v2 project. The full token list is in Site CSS & tokens.

Needs the web capability to see. The writes are for project managers.