Utopia Core SCSS

The calculations behind Utopia.fyi. Written in SCSS. Also available in JS/TS here.

Installation

npm install utopia-core-scss

@use 'node_modules/utopia-core-scss/src/utopia' as utopia;

Documentation

Utopia Core SCSS outputs in two formats: mixins & functions. Mixins generate actual (slightly) opinionated CSS custom properties. Functions sit beneath mixins doing the real work, returning calculated values for you to write your own custom CSS. The both use identical APIs and only differ by name (generateX for mixins, calculateX for functions).

All mixins/functions default relativeTo to viewport (vi), but can be overriden to container (cqi), or viewport-width (vw).

Mixins

generateTypeScale()

Generate a fluid type scale between two widths, sizes and scales. Set the number of positive and negative steps. Custom property prefix can be overriden from step-.

Example

:root {
  // Calling this:
  @include utopia.generateTypeScale((
    "minWidth": 320,
    "maxWidth": 1240,
    "minFontSize": 18,
    "maxFontSize": 20,
    "minTypeScale": 1.2,
    "maxTypeScale": 1.25,
    "positiveSteps": 2,
    "negativeSteps": 2,
    /* Optional params */
    "relativeTo": "viewport",
    "prefix": "step-",
  ));

  // Generates this:
  --step--2: clamp(...);
  --step--1: clamp(...);
  --step-0: clamp(...);
  --step-1: clamp(...);
  --step-2: clamp(...);
}

generateSpaceScale()

Generate a set of fluid spaces from min/max width/base sizes, and a number of positive/negative multipliers. Fluid spaces & one-up pairs are automatically created, and custom pairs can be created by supplying the keys you wish to interpolate between. Pass usePx: true to separate space from browser text zoom preferences. Custom property prefix can be overriden from space-.

Example

:root {
  // Calling this:
  @include utopia.generateSpaceScale((
    "minWidth": 320,
    "maxWidth": 1240,
    "minSize": 18,
    "maxSize": 20,
    "positiveSteps": (1.5, 2),
    "negativeSteps": (0.75),
    /* Optional params */
    "customSizes": ("s-l",),
    "usePx": true,
    "relativeTo": "container",
    "prefix": "space-",
  ));

  // Generates this:
  --space-xs: clamp(...);
  --space-s: clamp(...);
  --space-m: clamp(...);
  --space-l: clamp(...);
  // One-up pairs
  --space-xs-s: clamp(...);
  --space-s-m: clamp(...);
  --space-m-l: clamp(...);
  // Custom pairs
  --space-s-l: clamp(...);
}

generateClamps()

Generate multiple clamps from a single set of min/max widths. Supply an array of number pairs to interpolate between. Pass usePx: true to separate space from browser text zoom preferences. Custom property prefix can be overriden from space-.

Example

:root {
  // Calling this:
  @include utopia.generateClamps((
    "minWidth": 320,
    "maxWidth": 1240,
    "pairs": (
      (16, 48),
      (40, 18)
    ),
    /* Optional params */
    "usePx": true,
    "relativeTo": "container",
    "prefix": "space-",
  ))

  // Generates this:
  --space-16-48: clamp(...);
  --space-40-18: clamp(...);
}

generateClamp()

Generate a single clamp custom property from a min/max width & size. Default to using rem and vi but this can be overriden to use px and cqi. Pass usePx: true to separate space from browser text zoom preferences. Custom property prefix can be overriden from space-.

Example

:root {
  // Calling this:
  @include utopia.generateClamp((
    "minWidth": 320,
    "maxWidth": 1240,
    "minSize": 16,
    "maxSize": 20,
    /* Optional params */
    "usePx": true,
    "relativeTo": "container",
    "prefix": "space-",
  ))

  // Generates this:
  --space-16-20: clamp(...);
}

Functions

calculateTypeScale()

Calculate a fluid type scale between two widths, sizes and scales. Set the number of positive and negative steps, and whether you want the scale to be relative to the viewport or the container.

Example

$typeScale: utopia.calculateTypeScale((
  "minWidth": 320,
  "maxWidth": 1240,
  "minFontSize": 18,
  "maxFontSize": 20,
  "minTypeScale": 1.2,
  "maxTypeScale": 1.25,
  "positiveSteps": 5,
  "negativeSteps": 2,
  /* Optional params */
  "relativeTo": "container",
))

// $typeScale == (
//    (
//      "step": 0,
//      "minFontSize": 18,
//      "maxFontSize": 20,
//      "clamp": clamp(...),
//    )
//  )

calculateSpaceScale()

Calculate a set of fluid spaces from min/max width/base sizes, and a number of positive/negative multipliers. Fluid spaces & one-up pairs are automatically created, and custom pairs can be created by supplying the keys you wish to interpolate between. Clamp provided in rem and px.

Example

$spaceScales: utopia.calculateSpaceScale((
  "minWidth": 320,
  "maxWidth": 1240,
  "minSize": 18,
  "maxSize": 20,
  "positiveSteps": (1.5, 2, 3, 4, 6),
  "negativeSteps": (0.75, 0.5, 0.25),
  "customSizes": ("s-l", "l-s",),
  /* Optional params */
  "relativeTo": "container",
))

// $spaceScales == (
//  "sizes": (
//    (
//      "label": "s",
//      "minSize": 18,
//      "maxSize": 20,
//      "clamp": clamp(),
//      "clampPx": clamp(),
//    ),
//  ),
//  "oneUpPairs": (),
//  "customPairs": (),
// )

calculateClamps()

Calculate multiple clamps from a single set of min/max widths. Supply an array of number pairs to interpolate between.

Example

$clamps: utopia.calculateClamps((
  "minWidth": 320,
  "maxWidth": 1240,
  "pairs": (
    (16, 48),
    (40, 18)
  ),
  /* Optional params */
  "usePx": true,
  "relativeTo": "container"
))

// $clamps == (
//    (
//      "label": "16-48",
//      "clamp": clamp(...),
//    ),
//    (
//      "label": "40-16",
//      "clamp": clamp(...),
//    )
//  )

calculateClamp()

Calculate a single clamp calculation from a min/max width & size. Default to using rem and vi but this can be overriden to use px and cqi.

Example

$clamp: utopia.calculateClamp((
  "minWidth": 320,
  "maxWidth": 1240,
  "minSize": 16,
  "maxSize": 48,
  /* Optional params */
  "usePx": true,
  "relativeTo": "container"
))

// clamp(1rem, 0.3043rem + 3.4783vi, 3rem);