Customization

Configuration

Implement your design system using the configuration API.

npm create @master/css@rc

If you don't have a configuration file, create one first.

Options

`.animations`

Customizing animation animations for your design system.

export default {
    animations: {
        'slide-in-up': {
            from: {
                transform: 'translateY(100%)'
            },
            to: {
                transform: 'translateY(0)'
            }
        }
    }
}

Apply the custom animation using animation syntax:

<div class="@slide-in-up|.5s"></div>

`.functions`

Customizing functions for your design system.

export default {
    functions: {
        translate: { unit: 'rem' }
    }
}

Apply your custom functions:

<div class="translate(2rem)">…</div>
<div class="translate(32)">…</div>

`.at`

Customizing at-rules for your design system.

export default {
    at: {
        landscape: 'media (orientation:landscape)' // @landscape
    }
}

You wouldn't want to write full media queries within the markup.

<div class="aspect:2/1@media(orientation:landscape)">…</div>

Employ concise yet semantically meaningful markup.

<img class="aspect:2/1@landscape" … />

Generated CSS

@media (orientation:landscape) {
    .aspect\:2\/1\@landscape {
        aspect-ratio: 2/1
    }
}

`.syntaxes`

Customizing syntaxes for your design system.

export default {
    syntaxes: {
        foo: {
            matcher: /^foo:./,
            unit: 'rem',
            declare(value, unit) {
                return {
                    width: value + unit
                }
            }
        }
    }
}

Use your custom syntax:

<div class="foo:32"></div>

Generated CSS:

.foo\:32 {
    width: 2rem;
}

`.selectors`

Customizing selectors for your design system.

export default {
    selectors: {
        _headings: '_:where(h1,h2,h3,h4,h5,h6)'
    }
}

Simplify your existing markup in HTML:

<article class="font:bold_:where(h1,h2,h3,h4,h5,h6)">…</article>
<article class="font:bold_headings">…</article>

`.utilities`

Customizing utility classes for your design system.

export default {
    utilities: {
        show: {
            display: 'block'
        },
        'hide-text': {
            'font-size': 0
        }
    }
}

Apply your custom utilities:

<div class="show hide-text" hidden></div>

`.styles`

Customizing abstract styles for your design system.

export default {
    styles: {
        btn: '… inline-flex h:10x'
    }
}

Apply the btn style to the button element:

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

Generated CSS

.inline-flex,
.btn {
    display: inline-flex
}
 
.h\:10x,
.btn {
    height: 2.5rem
}

`.variables`

Customizing variables for your design tokens.

import { variables } from '@master/css'
 
export default {
    variables: {
        'font-family': {
            sans: 'Inter'
         },
        screen: { desktop: 1280 },
        spacing: { sm: 10 },
        primary: '
#000000'
    }
}

Apply custom variables using ambiguous shorthand:

<div class="font:sans max-w:screen-desktop m:sm bg:primary">…</div>

`.extends`

Extend custom or external configuration.

Type	`any[]`

export default {
    extends: [
        require('@master/ui'),
        require('./styles/btn.css'),
        …
    ]
}

`.important`

Make all generated CSS declarations !important.

Default	`false`
Type	`boolean`

Using important: true should be considered as a last option, as it's a compromise.

export default {
    important: true
}

Generated CSS:

.hidden {
    display: none !important;
}
 
.full {
    width: 100% !important;
    height: 100% !important;
}

`.override`

Customize your configuration to override all default configuration, default false to extend.

Default	`false`
Type	`boolean`

export default {
    override: true
}

We've carefully preset some configurations to enhance the syntax; usually, you'll extend it.

`.rootSize`

Specify the conversion factor for rem and em.

Default	`16`
Type	`number`

Here's a common use case with rootSize: 10:

export default {
    rootSize: 10
}

Generated CSS rules:

.font\:16 {
    font-size: 1rem;   /* rootSize: 16 */
    font-size: 1.6rem; /* rootSize: 10 */
}

And you will set the font size of the root to 62.5%:

<html class="font:62.5%">

`.baseUnit`

This base unit determines the size scale and ensures visual consistency across products.

Default	`4`
Type	`number`

For example, with the default baseUnit: 4, the size scale 1x, 2x, … will be 4, 8, ….

<div class="m:4x"></div>

Generated CSS:

.m\:4x {
    margin: 1rem; /* 4x = 4*4 = 16px, 16px / 16 = 1rem */
}

`.scope`

Limit the generated CSS rules to a specific scope with CSS selectors.

Default	`''`
Type	`string`

Don't make it part of your coding style, but as a last resort to solve problems.

export default {
    scope: '#app'
}

All Master CSS syntax will only be applied if the .

<html>
<body id="app">
    <div class="mt:1 text:center"></div>
</body>
</html>

Generated CSS:

#app .mt\:1 {
    margin-top: 0.0625rem
}
 
#app .text\:center {
    text-align: center
}

`.defaultMode`

The mode is to be applied by default when no mode is specified.

Default	`'light'`
Type	`'light'` `'dark'` `string` `boolean`

Default light mode

export default {
    defaultMode: 'light'
}

Generated CSS:

.light, :root {
    --primary: 0 0 0;
}

No default mode

export default {
    defaultMode: false
}

Generated CSS:

.light {
    --primary: 0 0 0;
}

`.modes`

Sets how the theme should drive and generate CSS rules.

Default	`{"dark":"class","light":"class"}`
Type	`{ [key: string]: 'class' \| 'media' \| 'host' \| false }`

<div class="bg:black@dark">

Drive theme styles through CSS classes

export default {
    modes: {
        dark: 'class'
    }
}

Generated CSS:

.dark .bg\:#000000 { background-color: #000000 }

Drive theme styles through media queries

export default {
    modes: {
        dark: 'media'
    }
}

Generated CSS:

@media (prefers-color-scheme: dark) { .bg\:#000000 { background-color: #000000 } }

Drive theme styles through shadow DOM's host

export default {
    modes: {
        dark: 'host'
    }
}

Generated CSS:

:host(.dark) .bg\:#000000 { background-color: #000000 }