Tokens are at the core of your visual language. They define the colors, type sizes, spacing and overall layout parameters of your design.

und-css let’s you configure your visual language using SASS variables and transforms your tokens into CSS custom properties, you can access them in your own stylesheets without depending on a preprocessor.

Tokens serve as modifiers for objects and can also be turned into utility styles.

As already said und-css serves as a meta-framework. So you have full flexiblity over the configuration, with as little conventions imposed as possible. Just need one color? No problem! Have 1.000 of spacing modifier – sure, whatever makes you happy.

The following documents how you can set your tokens.

Default Colors

To get started quickly, und-css will set your background-color to white and your text color to black. If you want to change this, you can do so via the two default-color variables.

$colors--default-background: #000000; // available as var(--color--default-background)
$colors--default-text: #ffffff;       // available as var(--color--default-text)

These colors are globally available as var(--color--default-background) and var(--color--default-text).

Named colors

Chances are, you will want to add more colors to your visual language. und-css let’s you add as many colors as you want, as long as you provide meaningful (read: meaningful to you and your design and dev-team) keys for them. This is what we call named colors.

To define named colors add them to the $color--named-colors map-variable.

$colors--named-colors: (
  accent: #0000ff, // will become var(--color--accent)
  muted: #f1f1f1,  // will become var(--color--muted)
  …
);

Named colors are exposed globally as var(--color--), as shown in the comments above.

To make your live with various breakpoints easier und-css allows you to keep track of your breakpoints. The settings offer you two variables to set.

Fluid Type and Spacing Scales

und-css features fluid type and spacing values, where you set optimal size or spacing values for your smallest and your biggest viewport. und-css will generate a clamp statement for you and have your sizes scale smoothly in between min and max viewports. No more media queries needed for text sizes.

See Utopia for more information on this approach.

$responsive--smallest-screen: 320px;
$responsive--biggest-screen: 1400px;

Breakpoints

und-css allows you the add as many widths as you like as named breakpoints. The width provided for a named breakpoint is the min-width for this breakpoint. As und-css seeks to encourage intrinsic layouts breakpoints are kept as simple as possible.

As of version 0.2.0 breakpoints are designed to work mutually exclusive, as this makes life with responsive utilities easier and prevents specificity issues. This means that any breakpoint will cover the range from its given size to 1px less than the breakpoint above.

By default und-css sets up three breakpoints for you: sm, md and lg. These can be configured using the following variables in your settings.scss.

$responsive--small-screen: 400px; // will be mapped to sm ranging from 400 to 919
$responsive--medium-screen: 920px; // will be mapped to md ranging from 920 to 1399
$responsive--biggest-screen: 1400px; // 1400 and above

// Default Breakpoints are available by their key
@include respond-to(md) {
  // Styles you want to apply above 920px and below 1399px viewport width
}

If you need more, or more specific breakpoints you can also override und-css' internal $responsive--breakpoints variable. But keep in mind to formulate your breakpoints in a mutually exclusive manner, to prevent specifity issues with responsive utilities.

$responsive--breakpoints: (
  custom: '(min-width: 100rem) and (max-width: 200rem)',
);

// Breakpoint will be available as 'custom'
@include respond-to(custom) {
  // Between 100 and 200rem viewport width
}

Named breakpoints are also used to generate responsive variants of your utilities.

<aside class="md:u-w-8/12 lg:u-w-6/12">
  <!-- this will 66.6666% wide on viewports bigger than 920px and 50% from 1400px upwards -->
</aside>

On of the most common headaches of writing CSS scale is to keep consistent spacing across all your components.

und-css let’s you manage your spacing sizes as – you guessed it by now – named spacing sizes.

Base spacing size

By default the base spacing size is set to 1rem. You will probably want to keep this value as it’s a good idea to relate your spacing to your main copy font size.

$layout-spacing--default: 1rem; // Available as var(--layout-spacing--default)

Spacing Ratio

By default und-css uses a ratio of 1.5 to calculate spacing sizes based on the base spacing size. The ratio is used in a fibonacci fashion to calculate each spacing value by mulitplying (or dividing) its adjacent value with the ratio.

The easiest way to change your spacing, is to change the spacing ratio. und-css will then auto generate new named spacing from xxxxs to xxxxl for your.

$layout-spacing--ratio: 1.5;

Default Spacings

By default und-css is set up to generate spacing-tokens ranging from xxxxs to xxxxl based on the ratio and the base spacing size. Available default values are:

Custom named spacings

If you want to create your custom spacing you can also defined the named spaces yourself. As with colors, these are provided as a map of names and values.

$layout-spacing--variants: (
  flush: 0,                               // var(--layout-spacing--flush)
  tiny: $layout-spacing--default * 0.25,  // var(--layout-spacing--tiny)
  small: $layout-spacing--default * 0.5,  // var(--layout-spacing--small)
  medium: $layout-spacing--default,       // var(--layout-spacing--medium)
  …
);

Named spaces are exposed globally as var(--layout-spacing--name), as shown in the comments above.

und-css provides to approaches to widht: Measure and Grid-widths. Both can be set as custom variables in your settings.

Measures

A measure is the maximum line of a length of text (typically expressed in characters). und-css allows you to set named measures, that can act as max-width of your container elements.

Ideally you would set your measures in font-relative units like em (not rem) or ch, so it adapts to the font-size of its content.

As they are linked closely to typography measures can be defined under the $typography namespace.

$typography--measures: (
  narrow: 30ch,
  medium: 60ch,
  wide: 90ch,
);

<div class="o-stack">
  <div class="u-measure-narrow">
    Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.
  </div>
  <div class="u-measure-medium">
    Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.
  </div>
  <div class="u-measure-wide">
    Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.
  </div>
</div>

Measures are used in the media object and can be accessed using custom properties or utility styles.

Grid Widths

und-css gives you access to a simple 12 column grid using – you guessed it – named grid widths. By default the widths are named like fractions, so you can easily access them in modifiers and utility classes.

$layout--widths: (
  '1\\/12': percentage(1 / 12),
  '2\\/12': percentage(2 / 12),
  '3\\/12': percentage(3 / 12),
  '4\\/12': percentage(4 / 12),
  '5\\/12': percentage(5 / 12),
  '6\\/12': percentage(6 / 12),
  '7\\/12': percentage(7 / 12),
  '8\\/12': percentage(8 / 12),
  '9\\/12': percentage(9 / 12),
  '10\\/12': percentage(10 / 12),
  '11\\/12': percentage(11 / 12),
  '12\\/12': percentage(12 / 12),
);

Grid widths are used in the media object and can be accessed in utility. We currently do not generate custom attributes for grid widths.

<ol class="o-grid">
  <li class="u-w-4/12">
    <div class="o-box u-bg-white">4 / 12</div>
  </li> 
  <li class="u-w-4/12">
    <div class="o-box u-bg-white">4 /12 </div>
  </li> 
  <li class="u-w-4/12">
    <div class="o-box u-bg-white">4 / 12</div>
  </li> 
</ol>

Also see the Grid Object for more information on how to work with grids.

'align': (
  'items': (
    'left': 'left',
    'center': 'center',
    'right': 'right',
  ),
  'property': 'text-align',
),

Will generate the following css

.u-align-left {
  text-align: left;
}

.u-align-center {
  text-align: center;
}

.u-align-right {
  text-align: right;
}