Spacing and Sizing

Apply consistent sizes across your application.

Using spacing scale

The spacing and sizing system is constructed using a base unit of 4 pixels. For visual consistency, you can use the multiplier unit x to apply spacing with the same scale.

<div class="m:1x">4px, margin: 0.25rem</div>
<div class="p:2x">8px, padding: 0.5rem</div>
<div class="w:8x">32px, width: 2rem</div>
<div class="gap:3x">12px, gap: 0.75rem</div>
<div class="size:6x">24px, width: 1.5rem; height: 1.5rem</div>

For other common sizes, 0, 1, 2, ..., we tend to use unitless tokens:

<div class="m:0">0px, margin: 0rem</div>
<div class="p:1">1px, padding: 0.0625rem</div>
<div class="w:2">2px, width: 0.125rem</div>

It's no longer necessary to define the spacing scale one by one as in the traditional way.

export default {
    variables: {
        spacing: {
            '1x': 4,
            '2x': 8,
            ...,
            '100x': 400
        }
    }
}

Basic usage

Add a spacing

Customize your spacing variables, in xs~xl.

export default {
    variables: {
        spacing: {
            md: 20
        }
    }
}

Apply the defined spacing variables using the inherited rules margin-left, margin-right, margin-top, margin-bottom, margin-x, margin-y, margin, margin-inline-start, margin-inline-end, margin-inline, padding-left, padding-right, padding-top, padding-bottom, padding-x, padding-y, padding, padding-inline-start, padding-inline-end, padding-inline, text-underline-offset, top, bottom, left, right, inset, transform, stroke-dashoffset, x, y, cx, cy, column-gap, row-gap, gap, outline-offset, scroll-margin-left, scroll-margin-right, scroll-margin-top, scroll-margin-bottom, scroll-margin-x, scroll-margin-y, scroll-margin, scroll-padding-left, scroll-padding-right, scroll-padding-top, scroll-padding-bottom, scroll-padding-x, scroll-padding-y, scroll-padding, shape-margin.

<div class="mt:md p:md">…</div>

it('should be able to access custom spacing variables using inherited rules', () => {
    const css = new MasterCSS({
        variables: {
            spacing: {
                md: 20
            }
        }
    })
    expect(css.create('mt:md')?.declarations).toStrictEqual({ 'margin-top': '1.25rem' })
    expect(css.create('p:md')?.declarations).toStrictEqual({ 'padding': '1.25rem' })
})

It's recommended to use 4x instead of the custom token md.

<div class="mt:4x p:4x">…</div>

Do not use numerical values as tokens.

export default {
    variables: {
        spacing: {
            1: 4,
            2: 8
        }
    }
}

It can be confused with the unitless values.