Migrating from Master CSS 1.0

A guide to upgrading Master CSS from v1 to v2.

Setup changes

Rendering on browser

The Master CSS Runtime has been separated from the @master/css package and is now available as @master/css-runtime.

General installation

import { init } from '@master/css';
import { initCSSRuntime } from '@master/css-runtime'
import config from './master.css' // your custom master css config
 
init()
initCSSRuntime(config)

To fully step in, check out the General Installation documentation.

Using CDNs

<script src="https://cdn.master.co/css"></script>
<script src="https://cdn.master.co/css-runtime@rc"></script>

To fully step in, check out the Using CDNs documentation.

Pre-rendering on server

The Master CSS Renderer has been separated from the @master/css package and is now available as @master/css-server.

import * as express from 'express'
import { Style, StyleSheet } from '@master/css'
import { render } from '@master/css/render'
import { render } from '@master/css-server'
 
app.get('/', function(req, res) {
    res.render('index.html', (error, html) => {
        if (err) console.log(err)
        return render(html, { StyleSheet }).html
        return render(html).html
    })
})

Learn how to enable Master CSS progressive rendering in frameworks with guides.

Introducing configuration

Using new custom variables

Deprecate extended colors and values in favor of the new config.variables.

import { Style } from '@master/css'
 
Style.extend('colors', {
   primary: '
#000000'
})
 
Style.extend('values', {
   'spacing-md': 20
})
 
export default {
    variables: {
        primary: '
#000000',
        spacing: {
            md: 20
        }
    }
}

Apply the variables:

<div class="fg:primary mt:md"></div>

To learn more, check out the custom variables.

Using new custom animations

In v2, you can apply the default animations out of the box:

<div class="@ping|1s|infinite"></div>

We built in commonly used animations, and the @master/keyframes.css package is deprecated.

@import '@master/keyframes.css';

To customize keyframes, check out the Animations documentation.

Using abstract styles

Deprecate extended classes in favor of config.styles.

import { Style } from '@master/css'
 
Style.extend('classes', {
   btn: '…'
})
 
export default {
    styles: {
        btn: '…'
    }
}

Apply the style:

<button class="btn"></button>

To learn more, check out the Styles documentation.

Merging media queries

Deprecate extended breakpoints and queries in favor of config.at.

import { Style } from '@master/css'
 
Style.extend('breakpoints', {
   laptop: '1024px'
})
 
Style.extend('queries', {
   watch: '(max-device-width:42mm) and (min-device-width:38mm)'
})
 
export default {
    at: {
        laptop: 1024,
        watch: '(max-device-width:42mm) and (min-device-width:38mm)'
    }
}

To learn more, check out the at-rules documentation.

Unknown tokens as themes

Deprecated colorSchemes and considered unknown media query tokens as themes.

import { Style } from '@master/css'
 
Style.colorSchemes.push('ocean');

Apply a custom ocean theme:

<div class="bg:cyan-50@ocean"></div>

Syntax changes

Renamed `font:color` to `fg:color`

The color property in CSS generally refers to the foreground color of elements such as text and borders. It is more appropriate to use color: or the acronym fg: for this purpose.

<p class="font:blue-60"></p>
<p class="fg:blue-60"></p>

Default colors are based on themes

In v1, the default value for color was linked to color-50. In v2, the default colors have been updated to align with the Master Design System theme colors, which are determined by variable themes like light or dark.

<p class="fg:blue"></p>
<div class="light">
    <p class="fg:blue">No longer equal to `blue-50`.</p>
</div>

To learn more, check out:

Color for text and foreground colors
Colors for default colors and color variables

Accessing variables

In v1, $(key) equals var(--key).

<div class="content:$(key)">var(--key)</div>

In v2, $(key) accesses config.variables.key and falls back to var(--key) if not found.

export default {
    variables: {
        key: '"`"'
    }
}

<div class="content:$(key)">"`"</div>

If you want to access native CSS variables, use var(--key).

<div class="content:var(--key)">var(--key)</div>

Major changes

Removed color mid-values

v2 no longer supports 1 to 99 shades for each color.

<div class="bg:blue-2"></div>
<div class="bg:blue-4"></div>
<div class="bg:blue-5"></div>
...
<div class="bg:blue-10"></div>
...
<div class="bg:blue-20"></div>
...
<div class="bg:blue-98"></div>

Initially, we wanted to support a wide range of colors through the LAB color model to provide flexibility, but its color gamut was limited.

The good news is that this significantly improves runtime performance, as the number of colors per color is reduced from 99 (1~99) to 11 (5-95).

Refactoring colors

Following the above, we found that each color had to rely on visual adjustments after going through the design system and component construction.

See the Colors documentation.

Also, we inverted the colors, which was probably the most painful change from v1 to v2.

<div class="bg:blue-60"></div>
<div class="bg:blue-40"></div>

Compatibility

Using v1 colors

For those who prefer v1 colors, we separated colors from @master/css and created a new package @master/colors to allow you to continue using v1 colors.

Since the structure exported by Master Colors v1 and v2 is the same, you can override the dependent @master/colors@2 version in @master/css@2 to v1 by specifying the overrides field in package.json.

{
    "overrides": {
        "@master/colors": "^1.0.0"
    }
}

In this way, the color system used by @master/css will be @master/colors@1.