Variables

A guide to using variables to implement design tokens.

Overview

In Master CSS, variables are used to manage tokens in the design system, such as colors, font families, etc., even based on different theme modes.

import { variables } from '@master/css'export default {    variables: {        spacing: { sm: 10 },        primary: '#000000'    }}

Apply custom variables using ambiguous shorthand:

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

Add a string variable

Create a string variable to reuse it in your markup.

export default {    variables: {        content: {             hash: '" #"',             external: '" ↗"'         },     }}

Use the variable in your markup:

<div class="content:hash content:external">…</div>

Use custom colors

Add a color

Add the primary color using #000, oklch(0% 0 none), or hsl(0 0% 0%).

export default {    variables: {        color: {            primary: '#000'         }    }}

Apply it using color-related syntax and even change the opacity.

<div class="fg:primary bg:primary/.5">…</div>

@layer base, theme, preset, components, general;@layer general {    .bg\:primary\/\.5 {        background-color: rgb(0 0 0/0.5)    }    .fg\:primary {        color: rgb(0 0 0)    }}

If a color is used only once in all markups, you can optionally not abstract it into a token.

<button class="bg:#ceb195">Milk Tea</button>

Variables only support rgb and hsl, in the future, they will be compatible with all native CSS functions, such as rgba, hsla, lab, and others. #346

Add a color with opacity

Add color variables with opacity using #00000080, rgb(0 0 0/.5), or hsl(0 0% 0%/.5).

export default {    variables: {        primary: 'rgb(0 0 0/0.5)'     }}

Apply it using color-related syntax like fg:.

<div class="fg:primary">…</div>

@layer base, theme, preset, components, general;@layer general {    .fg\:primary {        color: rgb(0 0 0/0.5)    }}

Color variables with opacity cannot use /alpha to change the opacity.

<div class="fg:primary/.5">…</div>

Add a color alias

Create an alias for a color to link its value to an existing color.

export default {    variables: {        secondary: '$color-white' /* secondary */     }}

Apply it using color-related syntax.

<div class="fg:secondary">…</div>

@layer base, theme, preset, components, general;@layer general {    .fg\:secondary {        color: oklch(100% 0 none)    }}

For example, say you have multiple color variables referencing the same color token. If that color needs updating, you would only need to update the source instead of manually updating every instance of the color.

Add a color alias with opacity

Create an alias for a color with opacity to link its value to an existing color.

export default {    variables: {        color: {            primary: '$color-black/.5',     /*  <─┐ */             secondary: '$color-primary/.5'  /*  ──┘  linked to primary */         }    }}

Apply it using color-related syntax like fg:.

<div class="bg:primary fg:secondary">…</div>

@layer base, theme, preset, components, general;@layer general {    .bg\:primary {        background-color: oklch(0% 0 none/0.5)    }    .fg\:secondary {        color: oklch(0% 0 none/0.25)    }}

As shown above, creating an alias secondary linked to an existing alias primary with opacity /.5 is possible, and the opacity will be multiplied 0.5 * 0.5 = 0.25.

Add color shades

Sets multiple shades for a single color.

export default {    variables: {        color: {            primary: {                 '': '#1192e8', /* primary */                 10: '#e5f6ff', /* primary-10 */                 20: '#bae6ff', /* primary-20 */             }         }    }}

Apply it using color-related syntax like fill:.

<svg class="fill:primary-20 …">20</svg>

Add colors based on modes

Add color variables in different theme modes.

export default {    variables: {        color: {            primary: '#ff0000'        }    },    modes: {        light: {            color: {                primary: '#000000'             }        },        dark: {            color: {                primary: '#ffffff'             }        }    }}

Using modes for variables, you can access a single source of truth and simplify the markup.

<div class="bg:primary">…</div>

@layer base, theme, preset, components, general;@layer theme {    :root {        --color-primary: rgb(255 0 0)    }    @media (prefers-color-scheme:light) {        :root {            --color-primary: rgb(0 0 0)        }    }    @media (prefers-color-scheme:dark) {        :root {            --color-primary: rgb(255 255 255)        }    }}@layer general {    .bg\:primary {        background-color: var(--color-primary)    }}

Override default colors

Access the same key as the preset to override default colors, like blue-5 ~ blue-95.

export default {    variables: {        color: {            blue: '#4589ff'         }    }}