colors

mixins

create-base-colors

@mixin create-base-colors() { ... }

Description

Create CSS custom properties from the $colors map

This is a wrapper for @mixin create-prop-from-map.

Note: Extend $colors map with @function safe-map-merge

Parameters

None.

Requires

See

create-shades

@mixin create-shades($input) { ... }

Description

Create color shades from a single color or a map of colors

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$input noneMap or Color none

Example

:root {
	@include create-shades(gray)
}

:root {
	...
	--clr-gray-10: hsl(0deg 0% 90%);
	--clr-gray-20: hsl(0deg 0% 80%);
...
}
:root {
	@include create-shades($colors)
}

:root {
	...
 --clr-green-10: hsl(120deg 100% 90%);
 --clr-green-20: hsl(120deg 100% 80%);
	...
 --clr-red-10: hsl(6deg 93% 90%);
 --clr-red-20: hsl(6deg 93% 80%);
	...
}

Requires

See

[private] _generate-shades

@mixin _generate-shades($key: null, $value) { ... }

Description

Resolves passed argument in @mixin create-shades.

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$key

Used as a base name in the custom property.

Defaults to null if @mixin create-shades is passed a singe color.

Otherwise uses key of the input map.

String or Nullnull
$value

the base color from which to generate shades

Color none

Requires

Used by

component

placeholders

button

%button { ... }

Description

Base button style using design tokens via CSS custom properties.

Note: States are designed to adapt across different contexts..

  • Layout: padding, border, radius
  • Colors: customizable bg/text/border
  • Typography: font settings
  • States: hover, focus, active

Example

.btn {
	@extend %button;
}

.btn-dark {
	@extend %button;

	--btn-bg-clr: var(--clr-dark);
	--btn-text-clr: var(--clr-light);
}

.btn-ghost-light {
	@extend %button;

	--btn-padding: #{$btn-padding-with-border};

	--btn-bg-clr: transparent;
	--btn-text-clr: var(--clr-dark);

	--btn-border-width: 4px;
	--btn-border-clr: var(--clr-dark);

	--btn-focus-outline-clr: var(--btn-text-clr, #{$clr-white});

	--btn-hover-filter-value: none;

	&:hover {
	--btn-text-clr: var(--clr-light);
	--btn-bg-clr: var(--clr-dark);
	}
}

Requires

Links

icon

%icon { ... }

Description

Utility class for base icon styles

Example

inspired by the .icon class used in the MDN footer

.icon-mask {
	@extend %icon;

	background-color: var(--icon-btn-clr, currentColor);
	mask-image: url('/send.svg');
	mask-position: left;
	mask-repeat: no-repeat;
	mask-size: cover;
}

Requires

See

fonts

mixins

font-face

@mixin font-face($typeface, $font-file, $weight, $style, $update-preferences: (true, null), $font-display: swap, $url: '/fonts/') { ... }

Description

Create font-face with automatic font registration in the $font-families via @mixin _update-font-families-map

Note: See @mixin _update-font-families-map how the $update-preferences parameter is destructured.

IMPORTANT: This mixin handles @font-face rules and font registration, but to generate CSS custom properties, use the create-prop-from-map mixin.

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$typeface

font-family

String none
$font-file

file name

String none
$weight

font-weight

Number none
$style

font-style

String none
$update-preferences

font registration tuple

List(true, null)
$font-display

font-display

Stringswap
$url

path to font files folder

String'/fonts/'

Example

Pass first typeface with (true, sans)

 @include font-face('Lato', 'lato-regular', 400, normal, (true, sans));

 @font-face {
 font-family: "lato";
	src: local("Lato"), url("/fonts/lato-regular.woff2") format ("woff2");
	font-weight: 400;
	font-style: normal
	font-display: swap;
}

/* This also updates the 'sans' key of the $font-families map. */

Pass second typeface with (false, sans)

 @include font-face('Lato', 'lato-bolditalic', 700, italic, (false, sans));

 @font-face {
	font-family: "Lato";
	src: local("Lato"), url("/fonts/lato-bolditalic.woff2") format ("woff2");
	font-weight: 700;
	font-style: italic;
	font-display: swap;
}

/* False value prevents registering the same font. */

Requires

See

[private] _update-font-families-map

@mixin _update-font-families-map($typeface, $update-preferences) { ... }

Description

Update font-families map

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$typeface

font-family

String none
$update-preferences

font update instructions

$register-font must be true to record font as a map value.

Only use when adding typeface the first time, any subsequent addition is superfluous, as the font is already registered in the $font-families map.

$register-font-as is a generic font family ('sans', 'monospace', etc)

List none

Throws

  • $font-families map already contains #{$typeface}.

  • Invalid argument:

Requires

Used by

See

[private] _set-font-families-map-key

@mixin _set-font-families-map-key($key, $value) { ... }

Description

Update font-families map key

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$key

$font-families map key

String none
$value

font value

String none

Requires

Used by

See

create-type-scale

Deprecated!

Use Utopia

@mixin create-type-scale($type-scale, $platform: null, $depth: 7) { ... }

Description

Create fluid typography

Create font-size custom properties

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$type-scale

scale key from $type-scales map

String none
$platform

optional namespace suffix

Stringnull
$depth

depth of font levels to create

Number7

Requires

See

Links

helpers

functions

round-to

@function round-to($number, $digits) { ... }

Description

Round $number to a fixed number of decimals places

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$number

the number to round

Number none
$digits

number of decimal places (default: 3)

Number none

Used by

safe-map-merge

@function safe-map-merge($source-map, $target-map) { ... }

Description

Merge maps to extend pre-defined maps

Note: See how to use it: color helpers

Note: See below pre-defined maps to extend

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$source-map

the pre-defined map

Map none
$target-map

the newly created map

Map none

Throws

  • First argument must be a map. Got #{meta.type-of($source-map)}

  • Second argument must be a map. Got #{meta.type-of($target-map)}

See

mixins

create-prop-from-map

@mixin create-prop-from-map($map, $prefix: null, $divider: null) { ... }

Description

Create CSS custom properties from a map

Note: For color-related properties, prefer using mixins from the color mixins.

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$map

source map

Map none
$prefix

optional prefix for custom properties

String or Nullnull
$divider

optional divider between prefix and key

String or Nullnull

Example

Without prefix and divider:

:root {create-prop-from-map($widths)}

:root {
	--min-width: 300px;
	--sidebar-width: 300px;
	--content-width: 1400px;
	...
}

With prefix and divider:

:root {create-prop-from-map($sizes)}

:root {
	--size-1: 0.0625em;
	--size-2: 0.125em;
	--size-3: 0.25em;
	...
}

Used by

how to override maps

variables

new-colors

$new-colors: (
	'red': salmon,
	'dark': indigo,
	'light': ghostwhite,
);

Description

Override or extend the $colors map

Note: If used on the $colors map it will alter the CSS custom properties via @mixin create-base-colors and @mixin create-shades.

Example

Override or extend color tokens

$new-colors: (
	'red': salmon,
	'dark': indigo,
);

$colors: map.merge($colors, $new-colors) !global;

 @debug $colors; // ([...], "red": salmon, [...], "dark": indigo)

:root {
	...
	--clr-red: salmon; // original red value is overwritten
	...
}

:root {
	...
	--clr-red-10: hsl(6deg 93% 90%); // hue and saturation values altered
	...
}

See

new-breakpoints

$new-breakpoints: (
	'large': 1200px,
	'largest': 87.5em,
);

Description

Override or extend the $breakpoints map

Example

Override or extend breakpoint values

$new-breakpoints: (
	'large': 1200px,
	'largest': 87.5em,
);

$breakpoints: map.merge($breakpoints, $new-breakpoints) !global;

 @debug $breakpoints; // ([...], "large": 1200px, "largest": 87.5em )

See

new-utopia-config

$new-utopia-config: (
	'minFontSize': 18,
	'maxFontSize': 22,
	'minTypeScale': map.get($type-scales, 'minor-third'),
	'prefix': fs-,
);

Description

Override $utopia-config map

Note: Use the $type-scales map to change minTypeScale and maxTypeScale key values.

Example

$new-utopia-config: (
	'minFontSize': 18,
	'maxFontSize': 22,
	'minTypeScale': map.get($type-scales, 'minor-third')
	'prefix': fs-,
);

$utopia-config: map.merge($utopia-config, $new-utopia-config);

 @debug $utopia-config; // ([...],  "minFontSize": 18, "maxFontSize": 22, "minTypeScale": 1.2, [...], "prefix": fs-)

:root {
	...
	--fs-0: clamp(1.125rem, 1.0179rem + 0.3571vi, 1.375rem); // clamping font sizes between new values
	...
}

See

Links

maps

variables

breakpoints

$breakpoints: (
	'small': 30em,	/* 480px */
	'medium': 45em, /* 720px */
	'large': 65em,  /* 1040px */
);

Description

Breakpoints

Note: Refer to the @mixin mq for how to use this mixin.

Type

Map <string, number>

Used by

  • [mixin] mq
  • [mixin] mq

See

  • [mixin] mq

type-scales

$type-scales: (
	'minor-second': 1.067,
	'major-second': 1.125,
	'minor-third': 1.2,
	'major-third': 1.25,
	'perfect-fourth': 1.333,
	'augmented-fourth': 1.414,
	'perfect-fifth': 1.5,
	'golden-ratio': 1.618,
);

Description

Map with font-scale ratios

Type

Map <string, number>

Used by

See

Links

system-ui

$system-ui: system-ui, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif,
	'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol';

Description

System-ui font stack

Type

List <string>

Links

font-weights

$font-weights: (
	'100': 100,
	'200': 200,
	'300': 300,
	'400': 400,
	'500': 500,
	'600': 600,
	'700': 700,
	'800': 800,
	'900': 900,
);

Description

Note: The $font-weight-aliases map references only three values from this set.

These are sufficient for the current linked fonts (e.g., Kanit, DM Serif), but the weights can be customized if necessary.

Type

Map <string, number>

See

font-weight-aliases

$font-weight-aliases: (
	'fw-slim': map.get($font-weights, '300'),
	'fw-normal': map.get($font-weights, '500'),
	'fw-thick': map.get($font-weights, '700'),
);

Description

Named font weights

Type

Map <string, number>

Example

:root {
	@include create-prop-from-map($font-weights);
}

:root {
	--fw-slim: 300;
	--fw-normal: 500;
	--fw-thick: 700;
}

See

font-families

$font-families: (
	'sans': sans-serif,
	'serif': serif,
);

Description

Note: The @mixin font-face uses $update-preferences to optionally register custom keys and/or values in the map.

IMPORTANT: This map is used to generate CSS custom properties (as below).

To create font-face rules and register loaded fonts use @mixin font-face with correctly set $update-preferences.

Type

Map <string, string>

Example

/* This must be present */
:root {
	@include create-prop-from-map($font-families, 'ff,);
}
:root {
	--ff-sans: sans-serif;
	--ff-serif: serif;
}
/* For this to work */
:root {
	@include font-face('Kanit', 'kanit-regular', 400, normal, (true, sans));
}
:root {
	--ff-sans: Kanit;
 	--ff-serif: serif
}

Used by

See

sizes

$sizes: (
	'1': 0.0625em,
	'2': 0.125em,
	'3': 0.25em,
	'4': 0.5em,
	'5': 0.75em,
	'6': 1em,
	'7': 1.25em,
	'8': 1.5em,
	'9': 1.75em,
	'10': 2em,
	'11': 2.5em,
	'12': 3em,
	'13': 4em,
	'14': 5em,
	'15': 6em,
	'16': 8em,
	'17': 10em,
	'18': 12em,
	'19': 14em,
);

Description

Spacing values in em units

Used for margin, padding, gap, etc.

Type

Map <number, length>

Example

:root {
	@include create-prop-from-map($sizes, 'size', '-');
}
:root {
	--size-1: 0.0625em;
	--size-2: 0.125em;
	--size-3: 0.25em;
	...
}

See

widths

$widths: (
	'min-width': 300px,
	'content-width': 1400px,
	'sidebar-width': 300px,
	'par-min-width': 25ch,
	'par-max-width': 65ch,
);

Description

Width values to constrain element sizes

Used for defining layout dimensions.

Type

Map <number, length>

Example

:root {
	@include create-prop-from-map($widths);
}
:root {
	--min-width: 300px;
	--content-width: 1400px;
	...
}

See

offsets

$offsets: (
	'punctuation-offset': -0.3em,
	'scroll-top-offset': 3ex,
);

Description

Various offsets

Type

Map <string, number>

Example

:root {
	@include create-prop-from-map($offsets);
}
:root {
	--punctuation-offset: -0.3em;
	--scroll-top-offset: 3ex;
}

See

gray-scale

$gray-scale: (
	'black-100': black,
	'white-100': #fff,
	'gray': gray,
);

Description

Grayscale colors map

Type

Map <string, string>

TODO's

  • Create shades as in _variables.scss

colors

$colors: (
	'green': green,
	'red': red,
	'blue': blue,
);

Description

Base colors map

Type

Map <string, string>

Example

:root {
	@include create-base-colors;
}
:root {
	--clr-green: green;
	--clr-red: red;
}

Used by

shadows

$shadows: (
	'small': 1px 2px 8px var(--shadow-color, hsla(0, 0%, 0%, 0.25)),
	'medium': 1px 4px 12px var(--shadow-color, hsla(0, 0%, 0%, 0.25)),
	'large': 1px 8px 20px var(--shadow-color, hsla(0, 0%, 0%, 0.25)),
	'drop-small': 1px 1px 2px var(--shadow-color, hsla(0, 0%, 0%, 0.25)),
	'drop-medium': 2px 2px 2px var(--shadow-color, hsla(0, 0%, 0%, 0.25)),
	'drop-large': 3px 3px 2px var(--shadow-color, hsla(0, 0%, 0%, 0.25)),
	'inset-small': inset 1px 1px 8px var(--shadow-color, hsla(0, 0%, 0%, 0.25)),
	'inset-medium': inset 1px 1px 12px var(--shadow-color, hsla(0, 0%, 0%, 0.25)),
	'inset-large': inset 2px 2px 16px var(--shadow-color, hsla(0, 0%, 0%, 0.25)),
);

Description

Various box-shadow declarations

Type

Map <string, string>

Example

create custom properties and/or set --shadow-color

:root {
	@include create-prop-from-map($shadows, 'shadow', '-');

 /* optionally create `--shadow-color` on root level. See $shadows map for fallback color. */
	@include create-shadow-color(blue, $alpha: -35%);
}

:root {
	--shadow-small: 1px 2px 8px var(--shadow-color, hsla(0, 0%, 0%, 0.25));
	--shadow-medium: 1px 4px 12px var(--shadow-color, hsla(0, 0%, 0%, 0.25));
	...
	--shadow-color: hsla(240, 100%, 50%, 0.65);
}

customize shadow color on selector level

.card {
	@include create-shadow-color(turquoise, $recompute-shadow-key: small);
	box-shadow: var(--shadow-small);
}

.card {
	--shadow-color: hsla(174, 72.0720720721%, 56.4705882353%, 0.25);
	--shadow-small: 1px 2px 8px var(--shadow-color, hsla(0, 0%, 0%, 0.25));
	box-shadow: var(--shadow-small);
	...
 }

Used by

media-queries

mixins

mq

@mixin mq($size) { ... }

Description

Create media queries with min-width

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$size

Breakpoint name from $breakpoints map or px value

String or Number none

Example

header {
	@include mq(1600px) {
  		color: $clr-white;
	}
}
 @media screen and (min-width: 100em) {
 	header {
  		 color: $clr-white;
 	}
}

Throws

  • Invalid parameter: expected key from $breakpoint map or a pixel value.

  • Invalid unit: only pixel values are accepted for custom sizes.

Requires

See

shadows

mixins

create-shadow-color

@mixin create-shadow-color($value, $alpha: -75%, $recompute-shadow-key: null) { ... }

Description

Create --shadow-color CSS custom property with optional override

Note: Refer to the $shadows map for how to use this mixin.

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$value

base color to compute the custom property

Color none
$alpha

alpha adjustment

Number-75%
$recompute-shadow-key

Optional key from the $shadows map.

If set, the corresponding shadow will be regenerated using the current, locally scoped --shadow-color.

Use this when a component defines a custom --shadow-color and needs its shadow to reflect that change.

String or Nullnull

Requires

See

utilities

mixins

flex-center

@mixin flex-center($dir: column, $gap: $size-6) { ... }

Description

Center content with flexbox

Justify-content and align-items are defaulting to center.

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$dir

Flex direction. If set to row adds flex-warp: wrap.

Stringcolumn
$gap

Gap. Uses $size-6 as the default gap.

Number$size-6

Requires

Used by

pseudo

@mixin pseudo($element, $display: inline-block, $pos: null, $content: '') { ... }

Description

Create pseudo-element

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$element

Must be before or after

String none
$display

display

Stringinline-block
$pos

position

Stringnull
$content

content

String''

Throws

  • Property #{$element} is incorrect. Must be either before or after.

icon-defaults

@mixin icon-defaults() { ... }

Description

Apply default styles to icons

Sets color to currentColor, block-size to 1lh, and enforces a square aspect ratio.

Parameters

None.

Used by

placeholders

flex-center

%flex-center { ... }

Description

Utility class for easy centering

Example

.flex-center {
	@extend %flex-center;
}

Requires

See

utopia

variables

[private] _utopia-min-width

$_utopia-min-width: 480;

Description

Minimum width for Utopia fluid type

[private] _utopia-max-width

$_utopia-max-width: 1600;

Description

Maximum width for Utopia fluid type

[private] _utopia-min-font-size

$_utopia-min-font-size: 16;

Description

Minimum font size for Utopia fluid type

[private] _utopia-max-font-size

$_utopia-max-font-size: 20;

Description

Maximum font size for Utopia fluid type

[private] _utopia-min-type-scale

$_utopia-min-type-scale: map.get($type-scales, 'major-second');

Description

Minimum type-scale ratio for Utopia fluid type

Requires

[private] _utopia-max-type-scale

$_utopia-max-type-scale: map.get($type-scales, 'perfect-fourth');

Description

Maximum type-scale ratio for Utopia fluid type

Requires

[private] _utopia-positive-steps

$_utopia-positive-steps: 5;

Description

Number of typographic scale steps above the base size generated by Utopia

[private] _utopia-negative-steps

$_utopia-negative-steps: 1;

Description

Number of typographic scale steps below the base size generated by Utopia base-size: from $_utopia-min-font-size to $_utopia-max-font-size

[private] _utopia-relative-to

$_utopia-relative-to: viewport;

Description

Base unit reference for fluid scaling (viewport or container)

[private] _utopia-prefix

$_utopia-prefix: null !default;

Description

Optional prefix for generated custom properties

utopia-config

$utopia-config: (
	'minWidth': $_utopia-min-width,
	'maxWidth': $_utopia-max-width,
	'minFontSize': $_utopia-min-font-size,
	'maxFontSize': $_utopia-max-font-size,
	'minTypeScale': $_utopia-min-type-scale,
	'maxTypeScale': $_utopia-max-type-scale,
	'positiveSteps': $_utopia-positive-steps,
	'negativeSteps': $_utopia-negative-steps,
	'relativeTo': $_utopia-relative-to,
	'prefix': $_utopia-prefix,
);

Description

Utopia $utopia-config

Links

variables

variables

clr-black

$clr-black: hsl(0deg 0% 0%);

Type

Color

Used by

clr-black-1

$clr-black-1: hsl(0deg 0% 1%);

Type

Color

clr-black-2

$clr-black-2: hsl(0deg 0% 2%);

Type

Color

clr-black-3

$clr-black-3: hsl(0deg 0% 4%);

Type

Color

clr-black-4

$clr-black-4: hsl(0deg 0% 6%);

Type

Color

clr-white

$clr-white: hsl(0deg 0% 100%);

Type

Color

Used by

clr-white-1

$clr-white-1: hsl(0deg 0% 99%);

Type

Color

clr-white-2

$clr-white-2: hsl(0deg 0% 98%);

Type

Color

clr-white-3

$clr-white-3: hsl(0deg 0% 96%);

Type

Color

clr-white-4

$clr-white-4: hsl(0deg 0% 94%);

Type

Color

clr-gray-10

$clr-gray-10: hsl(0deg 0% 90%);

Type

Color

clr-gray-20

$clr-gray-20: hsl(0deg 0% 80%);

Type

Color

clr-gray-30

$clr-gray-30: hsl(0deg 0% 70%);

Type

Color

clr-gray-40

$clr-gray-40: hsl(0deg 0% 60%);

Type

Color

clr-gray-50

$clr-gray-50: hsl(0deg 0% 50%);

Type

Color

clr-gray-60

$clr-gray-60: hsl(0deg 0% 40%);

Type

Color

clr-gray-70

$clr-gray-70: hsl(0deg 0% 30%);

Type

Color

clr-gray-80

$clr-gray-80: hsl(0deg 0% 20%);

Type

Color

clr-gray-90

$clr-gray-90: hsl(0deg 0% 10%);

Type

Color

clr-red

$clr-red: red;

Type

Color

clr-green

$clr-green: green;

Type

Color

clr-blue

$clr-blue: blue;

Type

Color

size-1

$size-1: 0.0625em;

Type

Number

size-2

$size-2: 0.125em;

Type

Color

size-3

$size-3: 0.25em;

Type

Color

size-4

$size-4: 0.5em;

Type

Color

size-5

$size-5: 0.75em;

Type

Color

size-6

$size-6: 1em;

Type

Color

Used by

size-7

$size-7: 1.25em;

Type

Color

size-8

$size-8: 1.5em;

Type

Color

size-9

$size-9: 1.75em;

Type

Color

size-10

$size-10: 2em;

Type

Color

size-11

$size-11: 2.5em;

Type

Color

size-12

$size-12: 3em;

Type

Color

size-13

$size-13: 4em;

Type

Color

size-14

$size-14: 5em;

Type

Color

size-15

$size-15: 6em;

Type

Color

size-16

$size-16: 8em;

Type

Color

size-17

$size-17: 10em;

Type

Color

size-18

$size-18: 12em;

Type

Color

size-19

$size-19: 14em;

Type

Color

default-min-width

$default-min-width: 320px;

Type

Number

default-sidebar-width

$default-sidebar-width: 300px;

Type

Color

default-content-width

$default-content-width: 1200px;

Type

Color

default-par-min-width

$default-par-min-width: 40ch;

Type

Color

default-par-max-width

$default-par-max-width: 80ch;

Type

Color

punctuation-offset-systemUi

$punctuation-offset-systemUi: -0.4em;

Type

Number

default-scroll-top-offset

$default-scroll-top-offset: 2ex;

Type

Color

default-btn-border-width

$default-btn-border-width: 2px;

Type

Number

Used by

btn-padding-no-border

$btn-padding-no-border: 0.75em 1.25em;

Type

Color

Used by

btn-padding-with-border

$btn-padding-with-border: calc(
		0.75em - calc(var(--btn-border-width) - $default-btn-border-width)
	)
	calc(1.25em - calc(var(--btn-border-width) - $default-btn-border-width));

Type

Color

section-dynamic-padding

$section-dynamic-padding: 10vh;

Type

Number

section-max-padding

$section-max-padding: $size-14;

Type

Color

section-padding

$section-padding: min(
	var(--section-max-padding, $section-max-padding),
	var(--section-dynamic-padding, $section-dynamic-padding)
);

Type

Color

cards-gap

$cards-gap: clamp(var(--size-7), 5vw, var(--size-10));

Type

Number

primary-light

$primary-light: map.get($colors, 'light');

Type

Color