Customization

Components

A guide to creating abstract component styles for your design system.

Traditionally, we define components like .btn or .card by writing CSS rules. In Master CSS, we use config.components to abstract and make them more flexible.

export default {
    components: {
        btn: {
            '': '… inline-flex font:semibold',
            'sm': 'font:12 h:8x px:3x r:6',
            'md': 'font:14 h:10x px:4x r:6',
        }
    }
}

An abstract style consists of one or more syntaxes, you can provide a class name for this set of classes and reuse it anywhere.

Try making the viewport width smaller

/examples/responsive-button

You can even conditionally apply abstract styles via at-rules:

<button class="btn btn-md btn-sm@<sm …">Submit</button>

Generated CSS

@layer base, theme, preset, components, general;
 
@layer components {
    .btn-md {
        font-size: 0.875rem;
        height: 2.5rem;
        padding-left: 1rem;
        padding-right: 1rem;
        border-radius: 0.375rem
    }
 
    .btn {
        display: inline-flex;
        font-weight: 600
    }
 
    @media (max-width:833.98px) {
        .btn-sm\@\<sm {
            font-size: 0.75rem;
            height: 2rem;
            padding-left: 0.75rem;
            padding-right: 0.75rem;
            border-radius: 0.375rem
        }
    }
}

Add a style

Create an abstract style using Master CSS syntaxes.

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

Apply the btn style to the button element:

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

Generated CSS

@layer base, theme, preset, components, general;
 
@layer components {
    .btn {
        display: inline-flex;
        height: 2.5rem
    }
}

Add a style with states

Create an abstract style with state selectors and applying conditionally.

export default {
    components: {
        btn: '… outline-offset:2:focus outline:2|invert:focus'
    }
}

Try clicking the button to see the outline effect

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

Generated CSS

@layer base, theme, preset, components, general;
 
@layer theme {
 
    .light,
    :root {
        --invert: 0 0 0
    }
 
    .dark {
        --invert: 255 255 255
    }
}
 
@layer components {
    .btn:focus {
        outline-offset: 0.125rem;
        outline: 0.125rem rgb(var(--invert)) solid
    }
}

Add styles in a nested structure

Create and manage a set of abstract styles in a nested structure. Rather than repeating the same style names over and over again, you can write one style inside another. Master CSS will automatically combine the outer style’s name with the inner style’s.

export default {
    components: {
        card: {
            '': '… r:2x',             // .card
            header: '… bb:1|gray',    // .card-header
            content: '… p:5x',        // .card-content
            footer: '… bt:1|gray',    // .card-footer
        }
    }
}

Apply the components:

<div class="card">
    <div class="card-header">…</div>
    <div class="card-content">…</div>
    <div class="card-footer">…</div>
</div>

Generated CSS

@layer base, theme, preset, components, general;
 
@layer theme {
 
    .light,
    :root {
        --gray: 162 161 163
    }
 
    .dark {
        --gray: 137 136 138
    }
}
 
@layer components {
    .card-header {
        border-bottom: 0.0625rem rgb(var(--gray)) solid
    }
 
    .card {
        border-radius: 0.5rem
    }
 
    .card-footer {
        border-top: 0.0625rem rgb(var(--gray)) solid
    }
 
    .card-content {
        padding: 1.25rem
    }
}

The empty string '' represents an outer style, much like Sass's &.

Extend an existing style

Create a new abstract style by extending an existing style and adding additional syntax.

export default {
    components: {
        a: 'fg:lime',
        b: 'a text:underline'
    }
}

You can see that b inherits the text lime color of a:

<span class="a">a</span>
<span class="b">b</span>

Generated CSS

@layer base, theme, preset, components, general;
 
@layer theme {
 
    .light,
    :root {
        --text-lime: 76 141 7
    }
 
    .dark {
        --text-lime: 145 217 26
    }
}
 
@layer components {
    .b {
        color: rgb(var(--text-lime));
        -webkit-text-decoration: underline;
        text-decoration: underline
    }
 
    .a {
        color: rgb(var(--text-lime))
    }
}

Components

Overview

Add a style

Add a style with states

Add styles in a nested structure

Extend an existing style