( Outdated ) Master CSS v2.0 Beta Release

[1aron]

🎉 Check out the https://beta.css.master.co/docs

Release & Changelog・Discord

Keep you all waiting! After several weeks of sprinting, the Master CSS v2.0 beta version was finally released. The purpose of the early trial is to gather everyone's reactions, feedback, and even suggestions for generality and stability.

Install the latest Master CSS Beta：

npm install @master/css@beta

Let's get a sneak peek at some of the new features with the beta notes!

On this page

• Ahead-of-time compilation
  • ✨ Webpack
  • ✨ Vite
  • ✨ Next.js
• New syntax
  • ✨ Grouping Selectors
  • ✨ An alternative fg|foreground for color
  • ✨ Support setting color transparency via percentage %
  • ✨ Shorthand for -webkit-text-fill-color (t|text):color
• New configuration and management
  • ⚙️ Extend and merge configuration
  • ⚙️ Manual Initial Master CSS
  • ⚙️ Automatic Initial Master CSS
  • ✨ config.themes greatly simplifies markup with custom themes
  • ✨ config.selectors custom selector tokens
• Built-in theme switching and synchronization
  • ✨ Switching themes
  • ✨ Accessing themes
  • ✨ Customing theme configuration
  • ✨ Implement theme switching and UI in React
• New packages, upgrades and changes
  • ✨ CSS React
  • ✨ CSS Compiler
  • ✨ CSS Vite
  • ✨ CSS Webpack
  • ⬆️ Upgrade Normal CSS
  • ⬆️ Upgrade CSS language service
  • 🔄 fade -> slate
  • 🔄 MasterStyleSheet -> MasterCSS
  • 🔄 MasterStyle -> Rule
  • 🔄 id="master-css" -> title="master"
  • 🔄 config.colorSchemes -> config.themes
• More APIs
  • render()
  • renderFromHTML()
  • renderIntoHTML()
  • fillColorScale()
  • config
• What's next?

---

Ahead-of-time compilation

Master.CSS.AOT.with.Webpack.mp4

Before introducing the precompiled mode, let's review the advantages of v1.0.

Master CSS in v1.0 focuses on creating a JIT engine that runs efficiently during runtime. The class name generation cycle only takes ~0.01ms/class, with the following characteristics:

• ⚡️ No CSS transformer —— Tailwind CSS uses postcss and autoprefixer to pre-transform CSS during build time

• ⚡️ No CSS preprocessor —— Styled Components uses css-to-react-native and stylis to preprocess CSS at runtime

• ⚡️ No hashed class names —— Styled Components hashes classes at runtime to group CSS rules

• ⚡️ Standalone rules engine container —— Most CSS-in-JS tools such as Styled Components are dependent on the rendering cycle of the framework such as React. When re-rendering, such tools are bound to sacrifice considerable rendering costs during runtime.

  The JIT of Master CSS relies on the browser's native API and is only executed when the class name changes, regardless of the framework.

• ⚡️ Performant rule engine —— The JIT of Master CSS only performs some low-cost execution behaviors, such as comparing class names, parsing class names, and Efficient operation during execution has always been the core consideration of v1.0

• ⚡️ Parsable structured syntax —— Since Master CSS is a brand new CSS language, there're consistent rules in syntax, and native CSS can be deduced through the same process, which is why it's so lightweight

In v2.0, we directly applied the fast JIT engine to the AOT compilation mode, which works by scanning the compiled .html and .js for strings or template tags (Both tailwind CSS and Windi CSS scan the source code, such as .jsx, .vue ), through the rule engine to compare whether it's the Master CSS class name and output as a CSS file.

We provide integration with mainstream build tools, and you can start Master CSS's AOT compilation mode with almost zero configuration.

✨ Webpack

https://github.com/master-co/css/tree/beta/packages/webpack

/* ⚙️ webpack.config.js */

const { MasterCSSWebpackPlugin } = require('@master/css.webpack')

module.exports = {
    plugins: [
        new MasterCSSWebpackPlugin()
    ]
};

✨ Vite

https://github.com/master-co/css/tree/beta/packages/vite

/* ⚙️ vite.config.js */

import { MasterCSSVitePlugin } from '@master/css.vite'

export default defineConfig({
    plugins: [
        MasterCSSVitePlugin()
    ]
})

✨ Next.js

https://github.com/master-co/css/tree/beta/packages/webpack

/* ⚙️ next.config.js */

const { MasterCSSWebpackPlugin } = require('@master/css.webpack')

const nextConfig = {
    webpack: (config) => {
        config.plugins.push(
            new MasterCSSWebpackPlugin()
        )
        return config
    }
}

module.exports = nextConfig

More guides for the frameworks and build tools coming with v2.0...

🥳 Now, start your development server directly, and the AOT compilation engine of Master CSS will run right away!

---

New syntax

✨ Grouping Selectors

In native CSS, you can use , to group selectors:

:before,
:after {
   /* declarations */
}

The same is now faster via the class name

- <div class="content:'`':before content:'`':after"></div>
+ <div class="content:'`':before,:after"></div>

The group syntax also supports group selectors

- <div class="{content:'`';fg:gray;mx:1}:before {content:'`';fg:gray;mx:1}:after"></div>
+ <div class="{content:'`';fg:gray;mx:1}:before,:after"></div>

✨ An alternative fg|foreground for color

Traditionally you'll see text-blue/font-blue naming style and CSS rules are usually:

.text-blue { color: blue }
.font-blue { color: blue }

However, the object set by CSS color is not only text, it also sets color-related properties such as border-color, box-shadow, so it is not strange to use text-* as the name of color ?

Even native CSS calling the foreground color is too broad, so we provide fg|foreground as an alternative name for you to set the foreground color, and the foreground also happens to echo the background bg|background :

<button class="fg:white bg:black">Submit</button>

The big change here is that we no longer support (f|font):color:

  <p class="color:blue">
- <p class="f:blue">
- <p class="font:blue">
+ <p class="fg:blue">
+ <p class="foreground:blue">

You can replace it globally in VSCode with the following Regular Expression:

?:font|f|[^-]color):(fade|slate|gray|brown|orange|gold|yellow|grass|green|beryl|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|crimson|red)

Replace as

fg:$1

⚠️ It is recommended to commit the unstaged file before execution to avoid irreversible errors during the replacement process.

✨ Support setting color transparency via percentage %

和原生相同，支援透過百分比變更色彩透明度的語法。兩種寫法皆可，因人而異。

  <div class="bg:sky-50/.75">v1.0+</div>
+ <div class="bg:sky-50/75%">v2.0+</div>

✨ Shorthand for -webkit-text-fill-color (t|text):color

A new shorthand is provided for text color:

  <div class="text-fill-color:pink-60"></div>
+ <div class="text:pink-60"></div>
+ <div class="t:pink-60"></div>

---

New configuration and management

在 v1.0 時我們提供 Style.extend 讓你自定義配置：

- import { Style } from '@master/css'
- Style.extend('classes', {
-    btn: 'font:14 text:center h:40 px:20'
- })
- ...

Many people said that this configuration is not so friendly and neat, after weeks of design and improvement, we finally have no suspense 😌

Let's take a look at the new master.css.js configuration file ✨

module.exports = {
    colors: {
        primary: '#175fe9',
    },
    classes: {
        btn: 'font:14 h:40 text:center bg:primary fg:white'
    },
    themes: {
        light: {
            colors: {
                primary: '#ebbb40',
                accent: colors.gold['70'],
                major: colors.slate['10'],
                content: colors.slate['30'],
                fade: colors.slate['55']
            }
        },
        dark: {
            colors: {
                primary: '#fbe09d',
                accent: '#fbe09d',
                major: colors.gray['80'],
                content: colors.gray['60'],
                fade: colors.gray['60']
            },
            classes: {
                btn: 'rounded'
            },
        }
    },
    values: {
        Width: {
            '2x': '2rem',
            '3x': '3rem',
        }
    },
    semantics: {
        show: 'display:block',
        'hide-text': 'font-size:0px'
    },
    breakpoints: {
        tablet: 768,
        laptop: 1024,
        desktop: 1280,
    },
    selectors: {
        '>custom': '>div>:first+button'
    },
    mediaQueries: {
        watch: '(max-device-width:42mm) and (min-device-width:38mm)'
    },
    rootSize: 16,
    Rules: []
}

You may have noticed some new configurations, which we will mention later.

⚙️ Extend and merge configuration

Often you'll want to add additional configuration in an extended way, we have built-in extend() method that allows you to extend and merge configuration while keeping the default configuration.

• Deeply merge object
• Deeply concat array
• Extended default configuration

Example: Add 'hide-text' semantic class name and 'ocean' theme to master.css.js, and keep the default values.

module.exports = {
    ...,
    semantics: {
        'hide-text': 'font-size:0px'
    },
    themes: ['ocean']
    ...
}

Import custom configuration in centrally managed master.js and initialize:

import config from './master.css'
import MasterCSS from '@master/css'
export const css = new MasterCSS({ config })

Extended configuration css.config results:

{
    ...,
    "semantics": {
+       "hide-text": "font-size:0px",
        "abs": "position:absolute",
        "rel": "position:relative",
        ...
    },
    "themes": [
        "dark",
        "light",
+       "ocean"
    ],
    ...
}

⚙️ Manual Initial Master CSS

We removed the behavior of automatic initialization of CommonJS and ESM output bundles, and instead used new MasterCSS() to manually initialize Master CSS with additional custom configuration:

// create a `./master.{js,ts}` file to manage initialization.

import config from './master.css' // your custom config file
import MasterCSS from '@master/css'
export const css = new MasterCSS({ config }) // export instance for access

Don't forget to include ./master.js at the entry point of the application, e.g. ./main.js

import './master';

⚙️ Automatic Initial Master CSS

In the IIFE browser bundle we retain the v1 auto-initialization behavior and provide a new API window.masterCSSConfig to allow you to customize the configuration directly in HTML:

...
<head>
+   <script>
+       window.masterCSSConfig = {
+           colors: { primary: '#ff0000' }
+       }
+   </script>
     <script src="https://cdn.master.co/[email protected]"></script>
</head>
...

⚠️ This is usually only for quick demonstrations in HTML.

✨ config.themes greatly simplifies markup with custom themes

Customize classes, colors according to different themes and combine and keep default values:

module.exports = {
    ...,
    colors: {
        primary: '#175fe9',
    },
    classes: {
        btn: 'font:14 h:40 text:center'
    },
    themes: {
        light: {
            colors: {
                primary: '#ebbb40',
                accent: colors.gold['70'],
                major: colors.slate['10'],
                content: colors.slate['30'],
                fade: colors.slate['55']
            },
            classes: {
                btn: 'bg:primary fg:white font:semibold'
            }
        },
        dark: {
            colors: {
                primary: '#fbe09d',
                accent: '#fbe09d',
                major: colors.gray['80'],
                content: colors.gray['60'],
                fade: colors.gray['60']
            },
            classes: {
                btn: 'bg:white fg:primary font:medium'
            }
        }
    },
    ...
}

Set the content foreground color according to light and dark:

- <div class="fg:slate-30@light fg:gray-60@dark">v1.0+</div>
+ <div class="fg:content">v2.0+</div>

## Generated CSS Rules:
- .dark .fg\:gray-60\@dark { color: #9e9da0 }
- .light .fg\:slate-30\@light { color: #323e52 }
+ .dark .fg\:content { color: #9e9da0 }
+ .light .fg\:content { color: #323e52 }

Let's look at an advanced selection, set the key foreground color according to light and dark:

- <div class="fg:slate-10_:where(strong,b,code,a,mark,del)@light fg:gray-80_:where(strong,b,code,a,mark,del)@dark">v1.0+</div>
+ <div class="fg:major_:where(strong,b,code,a,mark,del)">v2.0+</div>

✨ config.selectors custom selector tokens

Extend custom selector tokens, merge and keep defaults:

module.exports = {
    ...,
    selectors: {
        '>custom': '>div>:first+button'
    },
    ...
}

Apply it：

- <div class="hide>div>:first+button">same</div>
+ <div class="hide>custom"></div>

⚠️ The original intention of this configuration is to reasonably simplify native CSS selectors like hide:first-child -> hide:first, and it's recommended to consider the maintainability of the project while reducing.

You can also map one selector token to multiple ones, take the default vendor prefix as an example:

module.exports = {
    ...,
    selectors: {
        '::slider-thumb': ['::-webkit-slider-thumb', '::-moz-range-thumb'],
        '::slider-runnable-track': ['::-webkit-slider-runnable-track', '::-moz-range-track'],
        ...
    },
    ...
}

Apply it:

<div class="bg:red::slider-thumb">...</div>

Generated CSS rules:

.bg\:red\:\:slider-thumb::-webkit-slider-thumb {
    background-color: #d11a1e
}

.bg\:red\:\:slider-thumb::-moz-range-thumb {
    background-color: #d11a1e
}

In native CSS, as long as one selector is invalid, the entire rule will not be applied. Master CSS will automatically separate the selector containing the vendor prefix into two rules to generate.

Check out selector tokens for all presets

---

Built-in theme switching and synchronization

Since the logic of theme switching is similar and is often used, we decided to build this function in v2.0, including:

• Zero configuration enabled
• Sync system with your OS preferences
• Store user preferences, sync with localStorage
• With the setting color-scheme, for example: <html style="color-scheme: dark">
• Switch themes through class, for example: <html class="dark">

✨ Switching themes

import { css } from './master'
css.scheme = 'dark' // default: 'system'

✨ Accessing themes

import { css } from './master'
console.log(css.scheme) // default: 'light', 'dark', 'system'
console.log(css.theme) // default: 'light', 'dark'

✨ Customing theme configuration

The following configurations are all default values, where scheme.preference is the default theme scheme preference of the app.

module.exports = {
    ...,
    scheme: {
        preference: 'system', // 'system', 'dark', 'light'
        storage: {
            sync: true,
            key: 'scheme'
        }
    }
    ...
}

✨ Implement theme switching and UI in React

We provide the useScheme hook, allowing you to painlessly rely on React's rendering mechanism

import { css } from './master';
import { useEffected, useScheme } from '@master/css.react'
import { useCallback } from 'react';

export default function ThemeSchemeButton() {
    const { scheme, setScheme, theme } = useScheme(css)
    const effected = useEffected()
    const changeScheme = useCallback(({ target }) => {
        setScheme(target.value)
    }, [setScheme])
    return (
        <button className="rel">
            {effected && theme}
            <select value={scheme} onChange={changeScheme} className="abs full opacity:0 cursor:pointer" >
                <option value="light">☀️ Light</option>
                <option value="dark">🌜 'Dark</option>
                <option value="system">System</option>
            </select>
        </button>
    )
}

---

New packages, upgrades and changes

✨ CSS React

@master/css.react - React hooks for Master CSS

✨ CSS Compiler

@master/css-compiler - Compile Master CSS ahead of time with zero-configuration integration with build tools

✨ CSS Vite

@master/css.vite

✨ CSS Webpack

@master/css.webpack

⬆️ Upgrade Normal CSS

@master/normal.css - Normalize browser's styles. ~500B

npm install @master/normal.css@beta

Removed support for --font-mono, --font-sans, --font-serif

- :root {
-     --font-sans: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Helvetica Neue, Arial, Noto Sans, sans-serif, Apple Color Emoji, Segoe UI Emoji, Segoe UI Symbol, Noto Color Emoji;
-     --font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, Liberation Mono, Courier New, monospace;
-     --font-serif: ui-serif, Georgia, Cambria, Times New Roman, Times, serif;
- }

body {
-     font-family: var(--font-sans);
      ...
}

- code,
- kbd,
- samp {
-     font-family: var(--font-mono);
- }

Please use Master CSS syntax instead to preset global fonts:

<body class="font:sans font:mono_:where(code,kbd,samp)">
    ...
</body>

⬆️ Upgrade CSS language service

Please upgrade the Master CSS Language Service Extension on VSCode to v2.0

🔄 fade -> slate

Renamed fade in colors to slate lime to match common color names.

-    <p class="bg:fade ...">fade</p>
+    <p class="bg:slate ...">slate</p>

🔄 MasterStyleSheet -> MasterCSS

- import { MasterStyleSheet } from '@master/css'
+ import MasterCSS from '@master/css'

🔄 MasterStyle -> Rule

- import { MasterStyle } from '@master/css'
+ import { Rule } from '@master/css'

🔄 id="master-css" -> title="master"

<html>
<head>
-    <style id="master-css">...</style>
+    <style title="master">...</style>
</head>
</html>

🔄 config.colorSchemes -> config.themes

---

More APIs

Rendering-related APIs are mainly used for Server-side Rendering and Static-site Generation in v1.0. There are no major changes in v2.0, except for partial API optimization.

render()

Pass in an array of class names and return the resulting CSS text.

import { render } from '@master/css'
import { css } from './master'
const classes: string[] = ['text:center', 'font:32']
const result = render(classes, css)

rendered result:

.font\:32{font-size:2rem}.text\:center{text-align:center}

renderFromHTML()

Pass in HTML text, scan and return to produce CSS text.

import { renderFromHTML } from '@master/css'
import { css } from './master'
const html: string = `
    <html>
        <head></head>
        <body>
            <h1 class="text:center font:32">Hello World</h1>
        </body>
    </html>
`
const result = renderFromHTML(html, css)

rendered result:

.font\:32{font-size:2rem}.text\:center{text-align:center}

renderIntoHTML()

Pass in HTML text → scan and produce CSS text → inject into HTML <head> → return rendered HTML text result.

import { renderIntoHTML } from '@master/css'
import { css } from './master'
const html: string = `
    <html>
        <head></head>
        <body>
            <h1 class="text:center font:32">Hello World</h1>
        </body>
    </html>
`
const result = renderIntoHTML(html, css)

rendered result:

<html>
    <head>
        <style title="master">.font\:32{font-size:2rem}.text\:center{text-align:center}</style>
    </head>
    <body>
        <h1 class="text:center font:32">Hello World</h1>
    </body>
</html>

fillColorScale()

Fills undefined level values to 1,2,...99 with the average of adjacent level values.

import { fillColorScale } from '@master/css'

module.exports = {
    colors: {
        blue: fillColorScale({
            95: '001141',
            90: '001d6c',
            80: '002d9c',
            70: '0043ce',
            60: '0f62fe',
            50: '4589ff',
            40: '78a9ff',
            30: 'a6c8ff',
            20: 'd0e2ff',
            10: 'edf5ff'
        })
    }
}

In this way, you can choose not only blue-40, blue-50 but also blue-67, blue-72 and other values for better color rendering.

config

We export all the default configuration Config, you can access it by:

import { config } from '@master/css'

console.log(config.colors)
console.log(config.breakpoints)
// ...

or imported separately:

import { colors, breakpoints } from '@master/css'

console.log(colors)
console.log(breakpoints)
// ...

Check out all preset configurations

---

What's next?

1. Document docs.master.co revision: new site-wide search feautre and UI
2. Homepage css.master.co revision: In the past, we put all our energy into the research and development of the core functions of Master CSS, and many classic features have been buried in the documentation. The communication of the advantages through visual enhancement.
3. Official version v2.0: We expect to release the official version one month later
4. Master UI series: I believe many people can't wait for the Master UI series. We pay great attention to the details of the interface and the quality of the source code, which are being carefully produced. It is expected to release basic open source components such as button, card, tabs, etc. before the end of the year.

---

Feedbacks here ↓

[muco-rolle]

Amazing Job, can't wait to try it out on my new personal blog.

[muco-rolle]

@1aron any plan to support remix.run for MasterCSS v2?

[1aron]

@muco-rolle Sure!

[jet10000]

Amazing!

Add webcharm language service

[aileksandar]

Good job on the v2, I see a lot of improvements!

Tbh not really in love with the fg: i think c|color would make much more sense, since this is how you set in it css.

Is it possible to add/extend the config so I can use it like that?

Also, when you extend/add new classes to config, will that be reflected in the vs code plugin, it would be cool to have intellisense for custom classes?

[1aron]

fg and foreground are aliases for color, of course you can also keep using color:

Here is a complex configuration https://github.com/master-co/css/blob/beta/examples/vite/master.css.mjs

We're enhancing some features of VSCode https://github.com/master-co/css/issues