Migrating from Master CSS v1

Upgrade a Master CSS v1 project to the current CSS-first setup by auditing packages, entries, rendering mode, theme directives, and class syntax.

Master CSS v1 projects should be upgraded as real application migrations, not as automatic string rewrites. The current documentation is CSS-first: the project CSS entry, @theme, @settings, @custom-variant, managed classes, rendering modes, linting, and language tooling are the source of truth.

This guide avoids unverified one-to-one mappings for old v1 syntax. Audit the old project, install the current packages, then convert setup, theme, and class usage in small reviewed batches.

Migration strategy

Start by making the current toolchain run beside the old setup.

1. Audit installed @master/* packages, integrations, runtime/server initialization, CSS entries, and legacy config files.
2. Choose the current rendering mode: runtime, static, or progressive.
3. Install the current integration package for the framework or build tool.
4. Import @master/css from the stylesheet the app already loads.
5. Move project settings, tokens, modes, variants, components, and utilities into CSS-first directives.
6. Review class syntax and generated CSS in small batches.
7. Remove old package imports, config files, and initialization code only after the migrated paths validate.

Do not delete the old setup until the new CSS entry can generate styles for at least one migrated route or component family.

Audit checklist

Inspect the v1 project before changing files.

Install the current setup

Use the current Installation guide for the app framework. For Vite-style projects, the current baseline is a CSS entry plus the integration plugin.

@import "@master/css";

Default source discovery is enough for ordinary app files. Add explicit source directives only when the app needs custom include, exclude, safelist, or blocklist behavior.

Choose the rendering mode before converting many classes:

Use the framework-specific installation guide for exact package names and setup code instead of carrying old initialization forward.

Move config into CSS-first directives

The current project CSS entry owns theme and manifest inputs. Move values out of legacy config shapes and into CSS directives.

@import "@master/css";@settings {    root-size: 16;    base-unit: 4;}@theme {    --color-primary: #2563eb;    --color-body: #172033;    --spacing-card: 1.5rem;    --radius-card: .75rem;    --breakpoint-dashboard: 72rem;}@custom-variant @dashboard {    @media (width >= 72rem) {        @slot;    }}

<section class="grid grid-cols:3@dashboard gap:lg p:card r:card fg:body">    ...</section>

Keep non-CSS application configuration in JavaScript or TypeScript. Move only values that are part of the styling vocabulary.

Move reusable classes into managed definitions

If the v1 project had reusable component abstractions, migrate them to @components when the name describes a product UI role.

@components {    card {        @compose grid gap:md p:card r:card bg:white b:1px|solid|base shadow:sm;    }    btn-primary {        @compose inline-flex align-items:center justify-content:center gap:xs h:10x px:md r:md bg:primary fg:white;        @compose bg:blue-70:hover opacity:.5:disabled;    }}

<article class="card">    <button class="btn-primary">Save</button></article>

Use @utilities when the reusable name is a low-level primitive rather than a component role.

@utilities {    content-auto {        content-visibility: auto;        contain-intrinsic-size: auto 32rem;    }}

Review class syntax in batches

Current Master CSS class strings should be complete, explicit, and validated by the current engine.

Use current syntax for states, conditions, native declarations, and CSS variables:

<button class="inline-flex align-items:center gap:xs px:md h:10x r:md bg:blue-60 fg:white bg:blue-70:hover opacity:.5:disabled">    Save</button>

function Progress({ value }: { value: number }) {    return (        <div className="h:2x bg:gray-10 r:full overflow:hidden">            <div                className="h:full w:$progress bg:blue-60 transition:width|fast|smooth"                style={{ '--progress': `${value}%` } as React.CSSProperties}            />        </div>    )}

For static rendering, rewrite dynamic class fragments into complete class maps before expecting the scanner to find every class.

Replace old runtime and server wiring

Old runtime or server initialization should be replaced with current integration setup, not patched in place.

• Use the current framework integration when one exists.
• Use Rendering modes to choose runtime, static, server, or progressive delivery.
• Use @master/css-runtime directly only for custom runtime integration work.
• Use @master/css-server directly only when the project owns the HTML rendering step.

After replacing setup code, remove old imports, virtual module names, config loaders, and generated assets that are no longer part of the current integration.

Validate the upgrade

• Run the formatter, linter, type check, tests, and production build after each batch.
• Use Code linting and the Language Service to catch invalid classes early.
• Compare generated CSS for migrated components where priority, cascade layers, variables, modes, or important flags matter.
• Test runtime, static, or progressive rendering in the browser depending on the chosen mode.
• Remove old v1 packages, config files, and initialization code only after the migrated app builds and visually matches.

Useful references

• Installation for current package and integration setup.
• Rendering modes for runtime, static, server, and progressive delivery.
• Style declarations for current class syntax.
• Customizing your theme for @settings, @theme, modes, tokens, and custom variants.
• CSS directives for @components, @utilities, @compose, @reference, and source exceptions.
• Scanning latent classes for static-safe complete class strings.