Typography

Typography is arguably the essential part of a website. When we think about the content of a web page, we think about words. In this article, we’ll take a look at how to set a typography system in CSS.

Setting the Typography system using CSS Variables

Designing a typography system means making decisions about:

1. The typeface (font-family) you want to use.

2. Type (modular) scale.

3. Responsiveness of the text (size unit and breakpoints).

4. Spacing and vertical rhythm.

5. Colors (theming).

Let’s start with point one and two. Picking the right typeface is probably one of the first steps when you create a design system. Let’s assume you’ve browsed hundreds of font families and found the one you love (for now!); in your global/_typography.scss file, you can set your font-families as variables.

:root {
    --font-primary: sans-serif;
    --font-secondary: serif;
    /* set base values */
    --text-base-size: 1em;
    --text-scale-ratio: 1.2;
}
body {
    font-size: var(--text-base-size);
    font-family: var(--font-primary);
    color: var(--color-text);
}

The primary font, in this case, is the “most used” font; or the body font. The secondary font can be applied, for example, to a heading element. This approach is arbitrary, of course.

Along with the typeface, we’ve defined two variables: the — text-base-size and the — text-scale-ratio. The value of the text base size is 1em, while the — text-scale-ratio is used to generate the type scale.

When applied to the (we’re assuming no font-size is applied to the element), 1em equals to 16px in most modern browsers. Since our framework is mobile-first, we’re saying: on small devices, I want the body text size to be ~16px (the font-size of the body is equal to the — text-base-size).

And yes, after a long debate, we’ve opted for the em unit. The reasons behind this choice are explained later, in the Spacing section of the article.

The modular scale is a set of values obtained from a base value (in our case, 1em) and a ratio, or multiplier ( — text-scale-ratio). You can apply the scale to any measurable element (margin, paddings, etc.). Here’s how you create a type scale taking advantage of the CSS calc() function*:

:root {
    --font-primary: sans-serif;
    --font-secondary: serif;
    /* set base values */
    --text-base-size: 1em;
    --text-scale-ratio: 1.2;
    /* type scale */
    --text-xs: calc(1em / (var(--text-scale-ratio) * var(--text-scale-ratio)));
    --text-sm: calc(1em / var(--text-scale-ratio));
    --text-md: calc(1em * var(--text-scale-ratio));
    --text-lg: calc(1em * var(--text-scale-ratio) * var(--text-scale-ratio));
    --text-xl: calc(1em * var(--text-scale-ratio) * var(--text-scale-ratio) * var(--text-scale-ratio));
    --text-xxl: calc(1em * var(--text-scale-ratio) * var(--text-scale-ratio) * var(--text-scale-ratio) * var(--text-scale-ratio));
    --text-xxxl: calc(1em * var(--text-scale-ratio) * var(--text-scale-ratio) * var(--text-scale-ratio) * var(--text-scale-ratio) * var(--text-scale-ratio));
}
body {
    font-size: var(--text-base-size);
    font-family: var(--font-primary);
    color: var(--color-text);
}
h1, h2, h3, h4, form legend {
    color: var(--color-text-heading);
    margin-bottom: var(--space-xxs);
    line-height: var(--heading-line-height);
}
/* text size */
.text--xxxl {
    font-size: var(--text-xxxl);
}
h1, .text--xxl {
    font-size: var(--text-xxl);
}
h2, .text--xl {
    font-size: var(--text-xl);
}
h3, .text--lg {
    font-size: var(--text-lg);
}
h4, .text--md {
    font-size: var(--text-md);
}
.text--sm, small {
    font-size: var(--text-sm);
}
.text--xs {
    font-size: var(--text-xs);
}
p {
    line-height: var(--body-line-height);
}

We could have simplified the code by replacing the parts where we repeat — text-scale-ratio with variables (e.g., — text-lg: calc(1em var( — text-md));), but we had issues with how the postcss-css-variables gulp plugin compiles nested calc() function and CSS Variables.

The reason why a modular scale is useful when applied to anything in a design system is that it generates a harmonious set of values, as opposed to setting each value independently (maybe obtaining them from a .sketch file).

Note that in defining each text size variable we multiply 1em by the — text-scale-ratio. That 1em is not the —text-base-size value. You could set a — text-base-size different from 1em (while you shouldn’t change the 1m in the calc() function).

Since the em unit is a relative unit equal to the current font size, if we update the — text-base-size variable at a specific media query, we update the font-size of the body, and, as a result, all the text size variables. The whole typography is affected.

The paragraph element inherits the base font size, while we set a specific font size for each heading element. Besides, we create some utility classes in case, for example, we want to apply the — text-xxl font size to an element that is not an

.

Why including the type scale in your CSS? In one word: control.

Say we want to increase the body font size at a specific media query; for example, we increase the — text-base-size to 1.25em past 1024px. The heading elements are all affected by the change (the 1em in the calc() function is no longer ~16px, but ~20px), therefore they all become bigger. Let’s suppose we feel like increasing the size of the

element even more. How do we do that?

One option would be increasing the — text-base-size value, but it’s not ideal. The body text is big enough, I just want to target the

. Here’s the advantage of storing the — text-scale-ratio in a variable. We can edit it and affect everything but the body text:

:root {
    /* set base values */
    --text-base-size: 1em;
    --text-scale-ratio: 1.2;
    /* type scale */
    --text-xs: calc(1em / (var(--text-scale-ratio) * var(--text-scale-ratio)));
    --text-sm: calc(1em / var(--text-scale-ratio));
    --text-md: calc(1em * var(--text-scale-ratio));
    --text-lg: calc(1em * var(--text-scale-ratio) * var(--text-scale-ratio));
    --text-xl: calc(1em * var(--text-scale-ratio) * var(--text-scale-ratio) * var(--text-scale-ratio));
    --text-xxl: calc(1em * var(--text-scale-ratio) * var(--text-scale-ratio) * var(--text-scale-ratio) * var(--text-scale-ratio));
    --text-xxxl: calc(1em * var(--text-scale-ratio) * var(--text-scale-ratio) * var(--text-scale-ratio) * var(--text-scale-ratio) * var(--text-scale-ratio));
}
@include breakpoint(md) {
    :root {
        // you can manage typography editing only these 2 variables
        --text-base-size: 1.25em;
        --text-scale-ratio: 1.25;
    }
}

With this technique, you can manage the size of all your text elements by editing only two variables. Not just that, you can take advantage of the em unit and modify all margins, paddings, and spacing in general by editing the — text-base-size at a root level.

This method is not just a time-saver IMO, it’s a powerful approach to making text responsive. Both designers and developers can benefit from it. All we need is setting a demo-typography.html file with some text elements plus some components. The designer can jump in and tweak the typography directly in coding.

So…what’s the catch? When you use the Developer Tools to inspect the font size, you won’t see numeric values, but variable names; which don’t provide much info. But does it matter? Is it critical to know that a font-size is 28px as opposed to 29.4560px? Your call! 😉

Spacing

Now that sizing is sorted out, we need to deal with spacing. What is the ideal margin-bottom of an

element? What about paragraphs? One option to deal with spacing is setting another scale to manage the vertical rhythm.

This is how it works:

1. Set a base value, or baseline -> e.g., 24px

2. Generate a set of values that are multiples of the baseline

3. Use these values to generate consistent spacing between elements

:root {
    --baseline: 24px;
    /* spacing values */
    --space-sm:   calc(var(--baseline)/2);
    --space-md:   var(--baseline);
    --space-lg:   calc(var(--baseline)*2);
    --space-xl:   calc(var(--baseline)*3);
}
h1 {
  margin-bottom: var(--space-lg);
}
h2 {
  margin-bottom: var(--space-md);
}
p {
  margin-bottom: var(--space-sm);
}

The advantage of this method is that it creates a harmonious vertical spacing, that makes the user feels “safe”. Read more about why vertical rhythm is a good practice in this great article by Zell Liew.

That said, we opted for something different! Since we use the em unit for the font-size, we should set spacing in px or rem values if we want to preserve vertical rhythm (otherwise spacing would be affected by the em unit of the font size). As a result, if we change the font-size of the

, we may want to tweak the margin-bottom as well (e.g., set a media query and increase the margin-bottom to — space-xl); otherwise the margin could look too small now that the

is bigger than before.

Even though setting a media query to tweak the margin is not a big deal, we decided to rely entirely on the elasticity of em units. If you set your margins in em, chances are you won’t need to edit them.

Just my 2 cents: we often adopt in web design concepts originated in print design (e.g., vertical rhythm). We can break these rules, for the sake of simplicity, if doing so does not affect the user experience.

Here’s an example of how to set a spacing system using em units:

:root {
    /* spacing values */
    --space-xxxs: 0.25em;
    --space-xxs:  0.375em;
    --space-xs:   0.5em;
    --space-sm:   0.75em;
    --space-md:   1.25em;
    --space-lg:   2em;
    --space-xl:   3.25em;
    --space-xxl:  5.25em;
    --space-xxxl: 8.5em;
}
h1, h2, h3, h4, form legend {
    margin-bottom: var(--space-xxs);
    line-height: var(--heading-line-height);
}
.text-container {
    h2, h3, h4 {
        margin-top: var(--space-sm);
    }
    ul, ol, p {
        margin-bottom: var(--space-md);
    }
}

I generally separate spacing (_spacing.scss) from typography (_typography.scss), but this is up to you.

The reason why margins of lists and paragraphs descend from the .text-container class is to separate blocks of text from all the other places where a paragraph or an unordered list can be used. Optionally, you can target the

element.

Editing text size and spacing on a component level

The system we’re exploring makes sense as long as all text elements change accordingly with the two main text variables ( — text-base-size and — text-scale-ratio). How do we edit text size on a component level?

Option 1 would be targeting the component:

.component {
    font-size: 1.2em;
}

This change will affect the whole component, in all media queries. It’s like saying: “I want all text elements of this component to be 120% of what they would normally be”.

If you want to target a specific element inside the component, you have the following options:

.component h1 { 
    font-size: 3em; // the size is no longer affected by the --text-scale-ratio
    font-size: calc(var(--text-base-size) * 3); // use base size to create new value - off scale
    font-size: calc(var(--text-xxl) - 0.8em); // use original font size to create new value - off scale
    font-size: var(--text-xl); // update the value of the font size using a different variable
}

The first option allows you to set the size of the

as multiple of the — text-base-size (in this example x3); probably not ideal, because the size of the

is no longer affected by the — text-scale-ratio variable. The second option sets a new size based on the — text-base-size. Not a fan of this option either, because it generates a value that is most probably off the scale, and it’s not affected by the — text-scale-ratio.

Of the other two options, the last one is my favorite (reassigning the variable), because the new value obtained still belongs to the type scale.

Colors

Theming is part of a more complicated topic worth exploring in a different article. To complete our typography exploration though, let’s see how to set the primary colors*:

:root {
    /* typography */
    --color-text: var(--gray-10);
    --color-text-heading: var(--black);
    --color-text-subtle: var(--gray-6);
    --color-link: var(--color-primary);
    --color-link-visited: var(--color-primary-dark);
}
body {
    color: var(--color-text);
}
h1, h2, h3, h4, form legend {
    color: var(--color-text-heading);
}
a {
    color: var(--color-link);
    &:visited {
        color: var(--color-link-visited);
    }
}

I generally prefer to store all the color variables in a separate file (_colors.scss).

The style above can be used to set some basic rules. Chances are we need to create variations of these colors. Soon, we’ll be able to do so by updating the variable values. Unfortunately, updating a CSS Variable using a class is not supported in all modern browser (and gulp plugins). For the time being, we need to change the variable entirely!

Putting all together

Let’s put all the pieces together! This is how we’ve set typography so far in our framework. It’s not necessarily the final version. We will review everything before publishing the library on Github. Oh and any feedback is welcome! Let us hear what you think and what could be done better.

/* -------------------------------- 
Typography
-------------------------------- */
:root {
    --font-primary: sans-serif;
    --font-secondary: serif;
    /* set base values */
    --text-base-size: 1em;
    --text-scale-ratio: 1.2;
    /* type scale */
    --text-xs: calc(1em / (var(--text-scale-ratio) * var(--text-scale-ratio)));
    --text-sm: calc(1em / var(--text-scale-ratio));
    --text-md: calc(1em * var(--text-scale-ratio));
    --text-lg: calc(1em * var(--text-scale-ratio) * var(--text-scale-ratio));
    --text-xl: calc(1em * var(--text-scale-ratio) * var(--text-scale-ratio) * var(--text-scale-ratio));
    --text-xxl: calc(1em * var(--text-scale-ratio) * var(--text-scale-ratio) * var(--text-scale-ratio) * var(--text-scale-ratio));
    --text-xxxl: calc(1em * var(--text-scale-ratio) * var(--text-scale-ratio) * var(--text-scale-ratio) * var(--text-scale-ratio) * var(--text-scale-ratio));
    /* line-height */
    --heading-line-height: 1.2;
    --body-line-height: 1.4;
}
@include breakpoint(md) {
    :root {
        --text-base-size: 1.25em;
        --text-scale-ratio: 1.25;
    }
}
body {
    font-size: var(--text-base-size);
    font-family: var(--font-primary);
    color: var(--color-text);
}
h1, h2, h3, h4, form legend {
    color: var(--color-text-heading);
    margin-bottom: var(--space-xxs);
    line-height: var(--heading-line-height);
}
/* text size */
.text--xxxl {
    font-size: var(--text-xxxl);
}
h1, .text--xxl {
    font-size: var(--text-xxl);
}
h2, .text--xl {
    font-size: var(--text-xl);
}
h3, .text--lg {
    font-size: var(--text-lg);
}
h4, .text--md {
    font-size: var(--text-md);
}
.text--sm, small {
    font-size: var(--text-sm);
}
.text--xs {
    font-size: var(--text-xs);
}
p {
    line-height: var(--body-line-height);
}
a {
    color: var(--color-link);
    &:visited {
        color: var(--color-link-visited);
    }
}
b, strong {
    font-weight: bold;
}
.text-container {
    h2, h3, h4 {
        margin-top: var(--space-sm);
    }
    ul, ol, p {
        margin-bottom: var(--space-md);
    }
    ul, ol {
        list-style-position: outside;
        padding-left: 24px;
    }
    ul {
        list-style-type: disc;
    }
    ol {
        list-style-type: decimal;
    }
    ul li, ol li {
        line-height: var(--body-line-height);
    }
    em {
        font-style: italic;
    }
    u {
        text-decoration: underline;
    }
}
/* utility classes */
.truncate {
    // truncate text if it exceeds parent
    overflow: hidden;
    text-overflow: ellipsis;
    white-space: nowrap;
}

I hope you enjoyed the article! For more web design nuggets

Grid & Layout

Choosing how to handle layouts and content positioning is probably one of the first decision you’re going to make when building a design system.

Defining the grid means creating the system to structure your content, whether it’s a single component or a page layout.

1.  Layout with an auto-generated number of columns

Let’s say you have a gallery of products you want to lay out in a grid: all your items need to have the same width (they are instances of the same ‘product’ component, so they have the same dimension) and have a minimum width so that the design does not break; assume you want, at different screen sizes, the maximum number of items per row; something like the CodyHouse library(resize the page to see the change in number of items).

It would be ideal to find a way to automatically determine this maximum number of items without having to add new CSS code at different media queries.

This can be done using CSS Grid.

Let’s start by creating a grid mixin (we’ll be reusing it also for the layouts 3 and 4).

$gap-horizontal: 10px;
$gap-vertical: $gap-horizontal;
@mixin grid {
  @supports(grid-area: auto) {
    display: grid;
    grid-column-gap: $gap-horizontal;
    grid-row-gap: $gap-vertical;
  }
}

This mixin is used to initialize the grid container (with display grid) and set the grid gap (which is the free space between two adjacent items).

We have included the CSS Grid code inside a @supports rule to target browsers that support the Grid (leaving out also the browsers that support the old CSS Grid specification, like IE 11).

Now we can define the mixin that will create our gallery; the min-width of the items will be the only argument of this mixin:

@mixin gridAuto($min-width) {
  @supports(grid-area: auto) {
    grid-template-columns: repeat(auto-fit, minmax($min-width, 1fr));
  }
}

The minmax function allows us to set a min-width for our elements, while the repeat() function takes care of actually creating the grid.

We can now use these mixins like that:

.gallery-grid {
  @include grid;
  @include gridAuto(260px);
}

And here’s an example of these mixins in action: link

The mixins we defined above won’t work in IE and older versions of Edge (<= 15). Your gallery would still be accessible, but your items would show up one per row (100% width).

If you need to provide a better fallback, then you can use the float property to recreate your gallery, but you won’t be able to change the number of items per row at different screen sizes: you’ll need to set a fixed number of items per row (this number will be passed as the second argument to the gridAuto() mixin).

Here’s what the grid mixin becomes with the fallback addition:

$gap-horizontal: 10px;
$gap-vertical: $gap-horizontal;
@mixin grid {
  // fallback for IE
  &::before, &::after {
    content: '';
    display: table;
  }
  &::after {
    clear: both;
  }
  > * {
    float: left;
    margin-right: $gap-horizontal;
    margin-bottom: $gap-vertical;
  }
  @supports(grid-area: auto) {
    //CSS Grid style
    display: grid;
    grid-column-gap: $gap-horizontal;
    grid-row-gap: $gap-vertical;
    &::after, &::before {
      content: none;
    }
    > * {
      margin-right: 0;
      margin-bottom: 0;
    }
  }
}

The CSS properties defined inside the @supports rule are the ones applied when the browser supports CSS Grid (the new specification); while the properties defined outside the @supports are applied in all browsers (and this is why, inside the @supports rule, we had to add some additional style to overwrite those properties).

The gridAuto() mixin becomes:

@mixin gridAuto($min-width, $fallback: 3) {
  > * {
    float: left;
    width: calc(100%/#{$fallback} - #{$gap-horizontal});
    &:nth-child(#{$fallback}n + 1) {
      clear: both;
    }
  }
  @supports(grid-area: auto) {
    grid-template-columns: repeat(auto-fit, minmax($min-width, 1fr));
    > * {
      width: auto;
      margin: 0;
    }
  }
}

The mixin now accepts two arguments: the first one is the minimum width of the items in the gallery (the same as before — it will be used only if the browsers support CSS Grid), the second (which is optional — default value is 3) is the number of items per row on browsers that do not support CSS Grid (where the fallback is applied).

2. One-dimensional layout

This is probably the easiest layout we can create: we have items we want to arrange in columns, with the option of customizing their width and still being able to distribute the space among them equally.

There are few techniques we can use to implement this kind of layout. We are going to use Flexbox in combo with utility classes to customize the items width.

This approach has been around for a long time. It’s handy, but if you don’t want to use utility classes in your HTML (something like col — 1, col — 5, …), then a different method is the one I describe in section 3, where we create the same layout using CSS Grid.

Before defining our grid classes, let’s set a variable that we will use as grid gap:

:root {
  --grid-gap: 10px;
}

Let’s define a class for our grid container:

.flex-grid {
  display: flex;
  flex-wrap: wrap;
  margin: calc(var(--grid-gap) * -1) 0 0 calc(var(--grid-gap) * -1);
}

We initialize our flex container (using display flex) and allow the children to wrap on multiple lines if needed (using the flex-wrap property).
The negative margins are added to balance the padding we use to create the grid gap (see .col class definition below) so that no empty space is left between the .flex-grid element and its container.

Our grid items will have a .col class:

.col {
  padding: calc(var(--grid-gap)) 0 0 calc(var(--grid-gap));
  background-clip: content-box;
  flex-basis: 100%;
}

We use the padding to create the gap between elements and the background-clip so that the background-color/image of the .col element is not applied to the padding (leaving the gap visible).

You don’t need to use the background-clip property if you are not planning on adding a background-color/image to your .col element (or if the .col element has a child you can apply this background style to).

By default, all .col items have a 100% width (flex-basis 100%). We can use classes to change that width value:

$grid-columns: 12;
@for $i from 1 through $grid-columns {
  .col--#{$i} {
    flex-basis: round-width($i);
    max-width: round-width($i); 
  }
}

The round-width function is used to round the columns width to a number with 2 decimal places (this prevents the layout from breaking in IE).

@function round-width ($i) {
  $width : floor(100 * $i * 100/ $grid-columns) / 100;
  @return $width#{"%"};
}

This creates the classes .col — 1 up to .col — 12 (you can change the value of the $grid-columns variable if you are not using a 12 unit-grid).

If you want to create a layout with two elements, the first taking up 9 of the 12 available columns and the latter the remaining 3, you can use something like:

<ul class="flex-grid">
  <li class="col col--9">1</li>
  <li class="col col--3">2</li>
</ul>

You can also define different classes for different media queries if you want to change the width of your elements at different screen sizes. Something like:

@media only screen and (min-width: 600px) {
  @for $i from 1 through $grid-columns {
    .col--md-#{$i} {
      flex-basis: round-width($i);
      max-width: round-width($i); 
    }
  }
}

Here’s an example of the flex classes in action: link

We’ve decided to include this grid system in our library, because of its ease of use. It’s optional though, you can use the method described next (which does not rely on utility classes) if you prefer.

3.  Two-dimensional layout

In layout 2, we considered the case where we needed to control the width of the elements in our row. We didn’t consider the height of the elements at all.

If we want to create a two-dimensional layout where we can control the height of our elements as well, then CSS Grid is probably the best solution.

Here’s an example of a layout you can create using this technique:

We’ll be reusing the grid mixin (defined in section 1) and we’ll be adding a second gridLayout() mixin.
This new mixin will accept, as argument, a list of pairs of numbers:

.grid {
  @include gridLayout(
    (7, 2), //item 1
    (5, 1), //item 2
    (5, 1), //item 3
    (12, 1) //item 4
  );
}

For each element in your layout, you’ll have to pass a pair of numbers (in the example above, I’m passing 4 pairs which means our layout is composed of 4 elements). For each couple of numbers, the first will be the number of columns the element has to occupy, the second the number of rows.

In the code above, we are saying: the first element in the layout has to take up 7 columns and 2 rows; the second element 5 columns and 1 row; the same for the third element; the last one 12 columns (100% width) and 1 row.

Let’s see what the mixin looks like:

@mixin gridLayout($cols...) {
  @supports(grid-area: auto) {
    grid-template-columns: repeat($grid-columns, 1fr);
    $i: 1;
    @each $col in $cols {
      > :nth-of-type(#{$i}) {
        grid-column-end: span nth($col,1);
        @if length($col) > 1 {
          grid-row-end: span nth($col,2);
        }
      }
      $i: $i + 1;
    }
  }
}

First, we use grid-template-columns to define our grid of columns; this will create a template of 12 columns, all having the same width.

Notice we haven’t defined the grid-template-rows (or grid-auto-rows). This is mostly because the row height depends on the type of content you want to show: you can decide to have rows of a fixed height, rows that are a percentage of the viewport or just leave your content determine the height. You can specify this in your class when calling the mixin.

The ‘each’ loop is where the items are allocated: for each one of the pairs passed to the mixin, we take the corresponding element (using the :nth-of-type selector) and place it in our grid (using the span keyword).

Here’s an example of the mixin in action: Link

Note: the second number in each pair is not required (in the mixin, we check if the second value is passed before setting the grid-row-end property).

Passing just one number per item will allow you to create a one-dimensional layout; this is an alternative to the method described in section 2 (Flexbox + utility classes).

We can modify the gridLayout() mixin to add a fallback for browsers that do not support CSS Grid. Just keep in mind that, with the fallback, you won’t be able to control the height of your items.

@mixin gridLayout($cols...) {
  $i: 1;
  @each $col in $cols {
    > :nth-of-type(#{$i}) {
      width: calc( #{round-width(nth($col,1))} - #{$gap-horizontal});
    }
    $i: $i + 1;
  }
  @supports(grid-area: auto) {
    grid-template-columns: repeat($grid-columns, 1fr);
    $i: 1;
    @each $col in $cols {
      > :nth-of-type(#{$i}) {
        grid-column-end: span nth($col,1);
        @if length($col) > 1 {
          grid-row-end: span nth($col,2);
        }
      }
      $i: $i + 1;
    }
    > :nth-child(n) {
      width: auto;
      margin: 0;
    }
  }
}

4.  Two-dimensional layout with overlapping elements

This is quite a specific layout case: let’s say you want to create a two-dimensional layout (as we did with case 3 where you can set both width and height of your items) but you want to control the start/end position of your elements as well (so that they can overlap).

With the gridLayout() mixin, the items are automatically placed in the grid with no overlapping. You won’t be able to create something like this:

We can create a new gridAdvanced() mixin which will bring our layout a step further; here’s how we’re going to use it:

.grid {
  @include gridAdvanced(
    (1, 8, 1, 3), //item 1
    (1, 8, 3, 5), //item 2
    (5, -1, 2, 4) //item 3
  );
}

This time, we’ll need to pass, for each element in our layout, four numbers: the first two are the item’s start and end position within the grid columns, while the last two the row start and end position.

In the example above, we have 3 elements: the first one starts at column 1 and ends at column 8 (which means, it takes up 7 columns in our layout -> remember column 8 marks the end of the element, so it is not included) and starts at row 1 and ends at row 3 (2 rows); the second one takes the same columns but it starts at row 3 and ends at row 5 (2 rows); the third one starts at column 5 and takes up all the remaining columns (-1 means go till column 12 but include it as well) and starts at row 2 and ends at row 4 (2 rows).

Here’s our mixin:

@mixin gridAdvanced($cols...) {
  @supports(grid-area: auto) {
    grid-template-columns: repeat($grid-columns, 1fr);
    $i: 1;
    @each $col in $cols {
      > :nth-of-type(#{$i}) {
        grid-column-start: nth($col,1);
        grid-column-end: nth($col,2);
        grid-row-start: nth($col,3);
        grid-row-end: nth($col,4);
      }
      $i: $i + 1;
    }
  }
}

This is quite similar to the gridLayout() one; this time, though, we are using the grid-column(/row)-start/end to specify the position of our elements.

Here’s an example of the mixin in action: Link

We can provide a fallback for this mixin as well; keep in mind that you won’t be able to create the overlapping effect, as well as customize the items’ height.

@mixin gridAdvanced($cols...) {
  $i: 1;
  $span: 0;
  @each $col in $cols {
    > :nth-of-type(#{$i}) {
      @if nth($col,2) == -1 {
        $span: $grid-columns - nth($col,2) - nth($col,1);
      } @else {
        $span: nth($col,2) - nth($col,1);
      }
      width: calc( #{$span}*((100% - #{$gap-horizontal}*#{$grid-columns})/#{$grid-columns}) + (#{nth($col,1)} - 1)*#{$gap-horizontal} - 1px);
      min-width: 0px;
    }
    $i: $i + 1;
  }
  @supports(grid-area: auto) {
    grid-template-columns: repeat($grid-columns, 1fr);
    $i: 1;
    @each $col in $cols {
      > :nth-of-type(#{$i}) {
        grid-column-start: nth($col,1);
        grid-column-end: nth($col,2);
        grid-row-start: nth($col,3);
        grid-row-end: nth($col,4);
      }
      $i: $i + 1;
    }
    > :nth-child(n) {
      width: auto;
      margin: 0;
    }
  }
}

That is all I have to share on how we’re setting the grid system for the CodyHouse library. As usual, we’re open to suggestions! Any feedback is welcome. 🙂

Colors

In this article, we’ll take a look at how to set a color system in CSS, and what are the best practices to make sure the system is easy to use and maintain.

Color Variables 101

Unlike other CSS globals, creating a color system is 10% about coding and 90% about semantics. While working on your _colors.scss file, you want to keep in mind the following goals:

1. The color variables have to be easy to remember → You don’t want to check the global file anytime you have to pick a color.

2. The system has to be easy to update → You will add, remove, and rename colors. Make sure doing so is not complicated.

3. The system should include only the essential colors → we’ve heard this one so many times…yet we always end up with more colors than we need! The real success key of a design system is removing all that is not necessary (colors included).

Semantic vs Declarative colors

When it comes to setting the color variables, there are two main approaches: semantic and declarative colors.

The semantic approach looks like:

:root {
    --color-primary: #4D84F4;
    --color-secondary: #f5414f;
    --color-text: #2e2e31;
    --color-border: #d1d0d2;
    --color-success: #88c459;
    --color-error: #f5414f;
    --color-warning: #ffd137;
}

While here’s an example of a declarative approach:

:root {
    --blue: #4D84F4;
    --red-brand: #f5414f;
    --black: #2e2e31;
    --gray: #d1d0d2;
    --green: #88c459;
    --red: #f94747;
    --yellow: #ffd137;
}

Neither of them is wrong. Picking the one that meets your needs depends on so many factors (e.g., project size, branding colors relevance, etc.).

While working on the _colors.scss file of our framework, I had to take into account users were going to edit it (100%). That means that even if the declarative approach was the easiest to use, I had to mix it with the semantic approach to get a system that was also easy to maintain.

The essential color palette

Step number one was declaring the minimum number of colors needed to create the web components. In general, the essential color palette is composed of:

1. The main/primary color → used for the links, the button background color, etc. In general, it’s the main call-to-action color.

2. The accent color → used to highlight something important on the page. It shouldn’t be a variation of the primary color, but a complementary color.

3. A scale of neutral colors → It’s generally a scale of grayscale tones, to be used for text elements, subtle elements, borders, etc.

4. Feedback colors → success, error, warning.

Some of these colors need a variation (darker/lighter version), often used to highlight interactivity (e.g., :hover/:active states).

In CSS, this translates to:

:root {
    /* main colors */
    --color-primary: #4D84F4;
    --color-primary-light: color-mod(var(--color-primary) tint(15%));
    --color-primary-dark: color-mod(var(--color-primary) shade(15%));
    --color-primary-bg: color-mod(var(--color-primary) alpha(20%));
    --color-accent: #f5414f;
    --color-accent-light: color-mod(var(--color-accent) tint(15%));
    --color-accent-dark: color-mod(var(--color-accent) shade(10%));
    --color-accent-bg: color-mod(var(--color-accent) alpha(20%));
    // shades - generated using chroma.js - 12 steps
    --black: #1d1d21;
    --gray-10: #2e2e31;
    --gray-6: #7b7a7d;
    --gray-4: #a5a5a6;
    --gray-3: #bbbbbc;
    --gray-2: #d1d0d2;
    --gray-1: #e8e7e8;
    --white: white;
    /* feedback */
    --color-success: #88c459;
    --color-error: #f5414f;
    --color-warning: #ffd137;
}

*note: we’re using the postcss-color-mod-function plugin to translate the color functions into RGBA code compatible with all browsers.

The snippet above represents the color palette: all the colors used across the project.

The variations of the primary and accent colors are generated using color functions. This approach comes in handy if you have a demo.html file (and we do in our framework) so that you can tweak the values of the functions until you’re satisfied with the colors obtained. The shades (or neutral) colors are generated using chroma.js. In this case, using the functions was not ideal, because you generally have two opposite colors (black and white), and you need to generate a scale of values based on these two colors.

Adding semantic colors to the mix

Once the color palette is ready, we can add semantic colors. Creating semantic colors does not mean incrementing the number of colors, but distributing the colors using semantic references.

:root {
    /* main colors */
    --color-primary: #4D84F4;
    --color-primary-light: color-mod(var(--color-primary) tint(15%));
    --color-primary-dark: color-mod(var(--color-primary) shade(15%));
    --color-primary-bg: color-mod(var(--color-primary) alpha(20%));
    --color-accent: #f5414f;
    --color-accent-light: color-mod(var(--color-accent) tint(15%));
    --color-accent-dark: color-mod(var(--color-accent) shade(10%));
    --color-accent-bg: color-mod(var(--color-accent) alpha(20%));
    // shades - generated using chroma.js - 12 steps
    --black: #1d1d21;
    --gray-10: #2e2e31;
    --gray-6: #7b7a7d;
    --gray-4: #a5a5a6;
    --gray-3: #bbbbbc;
    --gray-2: #d1d0d2;
    --gray-1: #e8e7e8;
    --white: white;
    /* feedback */
    --color-success: #88c459;
    --color-error: #f5414f;
    --color-warning: #ffd137;
    /* typography */
    --color-text: var(--gray-10);
    --color-text-heading: var(--black);
    --color-text-subtle: var(--gray-6);
    --color-link: var(--color-primary);
    --color-link-visited: var(--color-primary-dark);
    --color-mark: var(--color-accent-bg);
    --color-blockquote-border: var(--gray-2);
    /* border */
    --color-border: var(--gray-2);
    /* body */
    --color-body: var(--white);
    /* forms */
    --form-element-border: var(--color-border);
    --form-element-border-focus: var(--color-primary);
    --form-element-border-error: var(--color-error);
    --form-element-bg: var(--white);
    --form-text-placeholder: var(--gray-4);
    /* buttons */
    --btn-primary-bg: var(--color-primary);
    --btn-primary-hover: var(--color-primary-light);
    --btn-primary-active: var(--color-primary-dark);
    --btn-primary-label: var(--white);
    /* icons */
    --color-icon-primary: var(--gray-4);
    --color-icon-secondary: inherit;
}

Why I think this is a good approach

First of all, this system relies on two essential colors: primary and accent colors. That means that when you need to use the color variables, it won’t be difficult for you to remember what those variables represent (even if you are not using declarative names such as “blue” and “red”).

Your system may need to include more colors (e.g., a secondary color). You’re still dealing with just three colors. Managing a system based on 10+ main colors would be difficult regardless of the approach you’re using, so you may want to consider simplifying it.

The grayscale colors use a different naming convention: the higher is the number at the end of the variable, the darker is the color.
This approach becomes handy when you’re not sure which neutral color you want to apply. If gray-2 looks too subtle, you can try gray-3. You may have noticed some shades are missing (e.g., gray-5). They were not essential in our case (we never used them while creating the web components), so we removed them from the color palette.

Semantic colors are added to the mix for three main reasons:

1. The _colors.scss file becomes the source of truth anytime you need to modify a color. Do you feel the text heading elements should be darker? Open the _colors.scss file and edit the color-text-heading variable.

2. If you define a color-border, for example, then you won’t need to look up which gray color you’ve been using in other components the next time you create a border element. The same concept applies to many elements, not just borders.

3. It makes it a piece of cake to create and maintain different themes.

Theming

As soon as we can use CSS variables without having to rely on plugins or polyfill, creating color themes will be super simple*! Does that mean we can’t create themes today? No, we can. We have two options.

*in our framework, we use the postcss-css-variables plugin to compile CSS variables. It currently does not support updating variables in a CSS class.

Option 1 is updating CSS variables anyway. Browsers that don’t support variables will show the “default” color theme. This is not an issue, as long as the content is accessible.

For example, you have a default color theme → white background and black text color, and a .theme-dark → black background and white text color. Then you create two components, one with the default theme, the other with the .dark-theme. If having both components with the default theme does not affect the user experience, then you can consider the .dark-theme as an enhancement (optional). In this case, it makes sense to update the variables to create different themes even if they’re not supported everywhere.

This is how you create a new theme updating some key CSS variables:

@supports(--css: variables) {  
    .theme--dark {
        --component-background: var(--black);
        --color-border: var(--gray-6);
        --color-text: var(--gray-4);
        --color-text-heading: var(--white);
    }
}

I love this solution because it abstracts the color correction, and it allows you to keep your color themes in a single file. By doing so, we can potentially change the state of each component (from theme-a to theme-b) simply by applying a CSS class.

Option 2 would be targeting all elements whose appearance is affected by the theme. The advantage of this method is that it’s supported by all browsers. However, it’s not as easy to maintain compared to the one based entirely on CSS variables.

Here’s an example of option 2 in action:

.theme--dark {
    color: var(--gray-1);
    h1, h2, h3, h4 {
        color: var(--white);
    }
    .text--subtle {
        color: var(--gray-4);
    }
    a {
        color: var(--color-accent);
    }
}

Now you know how we’re planning to handle colors in our framework!

Spacing

In this section we’ll take a look at how to set a spacing system in CSS, and how to take advantage of relative units to handle responsiveness.

Setting the Spacing system using CSS Variables

Step one of setting a spacing system is creating a scale of (spacing) values. To create a scale of non-linear values you need 1) a unit or base value and 2) a multiplier. We’ve already talked about creating a modular scale in our article on web typography.

A basic approach to spacing would look like this:

:root {
    --space-xxs:  4px;
    --space-xs:   8px;
    --space-sm:   12px;
    --space-md:   20px;
    --space-lg:   32px;
    --space-xl:   52px;
    --space-xxl:  84px;
}

The snippet above describes a spacing system based on the Fibonacci sequence (each value is found by adding up the two numbers before it).

Note: The first time I read about applying the Fibonacci sequence to a scale of spacing values was in this excellent article by The Scenery.

The downside of a basic approach is that, well…it’s basic. If we want to change a single spacing value, we have to do the math and update all other values manually.

Let’s try to bring some control over the system. We can introduce a variable to define the unit number, and use the calc() function to obtain the spacing values.

:root {
    --space-unit: 16px;
    --space-xxs:  calc(0.25 * var(--space-unit)); // 4px
    --space-xs:   calc(0.5 * var(--space-unit));  // 8px
    --space-sm:   calc(0.75 * var(--space-unit)); // 12px
    --space-md:   calc(1.25 * var(--space-unit)); // 20px
    --space-lg:   calc(2 * var(--space-unit));    // 32px
    --space-xl:   calc(3.25 * var(--space-unit)); // 52px
    --space-xxl:  calc(5.25 * var(--space-unit)); // 84px
}

We’re getting closer! In the example above, we’ve defined each spacing value by multiplying the unit number by a multiplier. Note that the Fibonacci sequence is still applied to the multipliers. Now if we want to update the whole system, we can edit the unit value.

Next, let’s get rid of the absolute unit and replace it with the em unit. To do so, we can replace 16px with 1em:

:root {
    --space-unit: 1em;
    --space-xxs:  calc(0.25 * var(--space-unit));
    --space-xs:   calc(0.5 * var(--space-unit));
    --space-sm:   calc(0.75 * var(--space-unit));
    --space-md:   calc(1.25 * var(--space-unit));
    --space-lg:   calc(2 * var(--space-unit));
    --space-xl:   calc(3.25 * var(--space-unit));
    --space-xxl:  calc(5.25 * var(--space-unit));
}

What looks like a small tweak, actually changes a lot! The em unit is a relative unit equal to the current font size. In most browsers, the default font-size (before CSS styling is applied) is 16 pixels. Therefore we can assume 1em = 16px. However, if you edit the font-size of an element, 1em is no longer 16px (for that element), but it’s equal to the new font-size. What appears like a lack of control, is a powerful responsiveness shortcut. Let me show you why.

If you’ve been following this series on design systems, you know we‘ve created a typography system where all font sizes are intertwined and obtained by multiplying a text-base-size variable (equal to 1em) by a ratio. That means that the text-base-size variable is the controller of the whole type system. If you increase the text-base-size at a specific media query, all the text size variables change accordingly.

@include breakpoint(md) {
    :root {
        --text-base-size: 1.25em;
    }
}

By updating just one variable, you get this:

Not just that! Since the spacing unit is equal to 1em, and all other spacing values are multipliers of the unit value, when we update the text-base-size variable, we affect the spacing as well. 💪

Look how this method affects typography and spacing at the same time:

We’re still updating a single variable (text-base-size). No additional media queries needed so far! All you have to do to take advantage of this powerful approach to responsiveness is using the spacing variables to set paddings and margins on a component level:

.header__top {
    background: var(--black);
    padding: var(--space-sm);
    text-align: center;
    a {
        color: var(--white);
        @include fontSmooth;
    }
}
.header__main {
    border-bottom: 1px solid var(--color-border);
    padding-top: var(--space-sm);
    padding-bottom: var(--space-sm);
    background: var(--white);
}
.header__nav {
    ul {
        display: flex;
    }
    li {
        margin-right: var(--space-md);
        &:last-child {
            margin-right: 0;
        }
    }
}

What if you want to update all spacing values at once, without having to change the text-base-size variable? Just update the space-unit variable:

:root {
    --space-unit: 1em;
    --space-xxs:  calc(0.25 * var(--space-unit));
    --space-xs:   calc(0.5 * var(--space-unit));
    --space-sm:   calc(0.75 * var(--space-unit));
    --space-md:   calc(1.25 * var(--space-unit));
    --space-lg:   calc(2 * var(--space-unit));
    --space-xl:   calc(3.25 * var(--space-unit));
    --space-xxl:  calc(5.25 * var(--space-unit));
}
@include breakpoint(md) {
    :root {
        --space-unit: 1.25em;
    }
}

It is true that by embracing a method like this one you lose some of your “visual” control, but it’s in favor of simplicity and maintainability. It is true that you won’t be able to set pixel-perfect values, but you will deal with responsiveness to a whole new level: most of the work will be setting a robust scale of values for spacing and typography. Then you can edit 2–3 variables at specific media queries to create a cascade effect, as opposed to tweaking all components and sub-elements.

How to set a default padding for all components

There will be cases where you need different components to have the same padding. Setting a variable for the default padding of the components is a trick I’ve learned after a lot of time spent looking for a padding value hidden somewhere in my CSS files. 😓

To be clear, I’m referring to those blocky, “container-like” components.

Here’s an example:

Getting back to our _spacing.scss file, let’s include the component padding variable:

:root {
    --space-unit: 1em;
    --space-xxs:  calc(0.25 * var(--space-unit));
    --space-xs:   calc(0.5 * var(--space-unit));
    --space-sm:   calc(0.75 * var(--space-unit));
    --space-md:   calc(1.25 * var(--space-unit));
    --space-lg:   calc(2 * var(--space-unit));
    --space-xl:   calc(3.25 * var(--space-unit));
    --space-xxl:  calc(5.25 * var(--space-unit));
  /* components padding */
    --component-padding: var(--space-sm);
}
.component {
  padding-top: var(--component-padding);
}

By doing so, you create another “dev shortcut”: if you need to apply padding to a component, you don’t need to check which spacing variable has been used in other similar cases. Just use the component-padding variable.

Margin utility classes

While it’s safe to include padding directly in your component CSS, including margins can cause layout issues. Once again, we’re referring to the main components, those blocks that define your main layout (not a component, but a

element).

If we imagine these components as blocks distributed in layouts, then information about margins and position should be stored in the abstract layout element, not the component. For example, you may end up using the same component in two different layouts, in one case you need to apply a margin-bottom, in another you don’t. You can see why including the margin-bottom in the component CSS may not be a good idea in this case.

For these reasons, it can be handy to have utility classes for the margins:

.margin-top, .margin-top--md {
    margin-top: var(--space-md);
}
.margin-top--sm {
    margin-top: var(--space-sm);
}
.margin-top--lg {
    margin-top: var(--space-lg);
}
.margin-top--xl {
    margin-top: var(--space-xl);
}
.margin-top--xxl {
    margin-top: var(--space-xxl);
}
.margin-bottom, .margin-bottom--md {
    margin-bottom: var(--space-md);
}
.margin-bottom--sm {
    margin-bottom: var(--space-sm);
}
.margin-bottom--lg {
    margin-bottom: var(--space-lg);
}
.margin-bottom--xl {
    margin-bottom: var(--space-xl);
}
.margin-bottom--xxl {
    margin-bottom: var(--space-xxl);
}

Optionally, you can update the margin values at a specific breakpoint, to automatically increase distances when the viewport is bigger.

@include breakpoint(md) {
    .margin-top, .margin-top--md {
        margin-top: var(--space-lg);
    }
    .margin-top--sm {
        margin-top: var(--space-md);
    }
    .margin-top--lg {
        margin-top: var(--space-xl);
    }
    .margin-top--xl {
        margin-top: var(--space-xxl);
    }
    .margin-top--xxl {
        margin-top: var(--space-xxxl);
    }
    .margin-bottom, .margin-bottom--md {
        margin-bottom: var(--space-lg);
    }
    .margin-bottom--sm {
        margin-bottom: var(--space-md);
    }
    .margin-bottom--lg {
        margin-bottom: var(--space-xl);
    }
    .margin-bottom--xl {
        margin-bottom: var(--space-xxl);
    }
    .margin-bottom--xxl {
        margin-bottom: var(--space-xxxl);
    }
}

Custom spacing values

What if you’re setting a margin on an element, and space-sm looks too small, while space-md is too big? Working with a set of predefined variables means that sometimes you have to compromise (for the sake of the system maintainability).

BUT! If you do need to use a spacing value that is not included in your spacing scale, and you don’t want to edit or break the system, you can take advantage of the CSS calc function:

.nav__item {
  margin-right: calc(var(--space-sm) * 1.1);
}

By doing so, you’re introducing a new spacing value, but you’re still making sure this new value is “controlled” by the same system.

Fixed spacing values

The spacing system we’ve introduced implies that all margins, paddings (and typography elements) are updated simultaneously using a couple of variables. As powerful as this can be, there are cases when you don’t want a spacing value to change, regardless of the viewport size.

To do so, you need to define spacing using a different unit: rem. Unlike em, rem is relative to the html (root) font-size. Therefore it’s not affected when you edit the body font size (updating the text-base-size variable).

To be clear, I’m not suggesting to replace em with rem, but to combine them.

The easiest way to set a “fixed” spacing value would be:

.nav__item {
  margin-right: 0.5rem;
}

However, that would mean introducing a bunch of custom, out-of-the-system, spacing values. If we think about a real case scenario: a new developer joins your team, they open a CSS file and notice you’ve set a 0.5rem margin on an element. In an ideal dev world, you’ve informed your new colleague of the spacing system, or the project has (up-to-date) CSS guidelines, or the colleague asks for more info on how spacing is handled in the project. In the real dev world, chances are the new teammate will assume spacing is set using custom rem values.

To avoid confusion, it would be ideal to use variables. If we do so, the colleague is forced to check the _spacing.scss file, where they’ll find (100%! 😇) your helpful comments.

Here’s an example of how you can (optionally) set a scale of “fixed” spacing values in addition to the responsive ones:

:root {
    /* spacing values */
    --space-unit: 1em;
    --space-xxs:  calc(0.25 * var(--space-unit));
    --space-xs:   calc(0.5 * var(--space-unit));
    --space-sm:   calc(0.75 * var(--space-unit));
    --space-md:   calc(1.25 * var(--space-unit));
    --space-lg:   calc(2 * var(--space-unit));
    --space-xl:   calc(3.25 * var(--space-unit));
    --space-xxl:  calc(5.25 * var(--space-unit));
    /* fixed values - not affected by --space-unit or --text-base-size */
    --space-unit-fixed: 1rem;
    --space-xxs-fixed:  calc(0.25 * var(--space-unit-fixed));
    --space-xs-fixed:   calc(0.5 * var(--space-unit-fixed));
    --space-sm-fixed:   calc(0.75 * var(--space-unit-fixed));
    --space-md-fixed:   calc(1.25 * var(--space-unit-fixed));
    --space-lg-fixed:   calc(2 * var(--space-unit-fixed));
    --space-xl-fixed:   calc(3.25 * var(--space-unit-fixed));
    --space-xxl-fixed:  calc(5.25 * var(--space-unit-fixed));
}

_spacing.scss

Putting it all together, here’s our _spacing.scss file:

/* -------------------------------- 
Spacing
-------------------------------- */
:root {
    /* spacing values */
    --space-unit: 1em;
    --space-xxxs: calc(0.25 * var(--space-unit));
    --space-xxs:  calc(0.375 * var(--space-unit));
    --space-xs:   calc(0.5 * var(--space-unit));
    --space-sm:   calc(0.75 * var(--space-unit));
    --space-md:   calc(1.25 * var(--space-unit));
    --space-lg:   calc(2 * var(--space-unit));
    --space-xl:   calc(3.25 * var(--space-unit));
    --space-xxl:  calc(5.25 * var(--space-unit));
    --space-xxxl: calc(8.5 * var(--space-unit));
    /* components padding */
    --component-padding: var(--space-sm);
}
// optional - edit space unit and padding of all components at a specific breakpoint
@include breakpoint(md) {
    :root {
        --space-unit: 1.25em;
        --component-padding: var(--space-md);
    }
}
/* vertical margins */
.margin-top, .margin-top--md {
    margin-top: var(--space-md);
}
.margin-top--sm {
    margin-top: var(--space-sm);
}
.margin-top--lg {
    margin-top: var(--space-lg);
}
.margin-top--xl {
    margin-top: var(--space-xl);
}
.margin-top--xxl {
    margin-top: var(--space-xxl);
}
.margin-bottom, .margin-bottom--md {
    margin-bottom: var(--space-md);
}
.margin-bottom--sm {
    margin-bottom: var(--space-sm);
}
.margin-bottom--lg {
    margin-bottom: var(--space-lg);
}
.margin-bottom--xl {
    margin-bottom: var(--space-xl);
}
.margin-bottom--xxl {
    margin-bottom: var(--space-xxl);
}
@include breakpoint(md) {
    .margin-top, .margin-top--md {
        margin-top: var(--space-lg);
    }
    .margin-top--sm {
        margin-top: var(--space-md);
    }
    .margin-top--lg {
        margin-top: var(--space-xl);
    }
    .margin-top--xl {
        margin-top: var(--space-xxl);
    }
    .margin-top--xxl {
        margin-top: var(--space-xxxl);
    }
    .margin-bottom, .margin-bottom--md {
        margin-bottom: var(--space-lg);
    }
    .margin-bottom--sm {
        margin-bottom: var(--space-md);
    }
    .margin-bottom--lg {
        margin-bottom: var(--space-xl);
    }
    .margin-bottom--xl {
        margin-bottom: var(--space-xxl);
    }
    .margin-bottom--xxl {
        margin-bottom: var(--space-xxxl);
    }
}

Here’s where we are with the spacing system so far!

Icons

In this section, we’ll take a look at how to include icons in your design system, with some additional CSS techniques to customize them according to your needs.

Here’s what we will cover:

• Integrating icons into your design system;

• Classes for icon sizes;

• Icon style variations;

• Aligning icons to text;

Integrating icons in your design system

There are multiple options when it comes to integrating icons into your design system; for our library of components, we opted for the SVG Symbols, mostly for the ease of use as well as the high level of icon customization it allows.

I won’t be going into details about SVG Symbols. If you are not familiar with the technique, you could take a look at this guide on integrating icons in design systems where you can find some useful info about SVG Symbols and alternative methods you can use.

Note: throughout the article, I will be using SVG Symbols only. Nonetheless, the CSS code and classes we provide can be used for SVG inline icons and icon fonts as well.

The first step is to import your SVG Symbols at the top of the page (right after the tag) to reference the SVG inline:

<body>
  {% include "icons.svg" %}
  <svg class="icon"><use href="#icon-rugby" xlink:href="#icon-rugby"/></svg>  
</body>

Note: the ‘include’ syntax I have been using is the one of Nunjucks; you can replace it with the syntax of the templating language you are using (or you can directly include the complete SVG code).

The .icon class is used to add some basic style:

.icon {
  display: inline-block;
  color: var(--color-icon-primary);
  height: 1em;
  width: 1em;
  line-height: 1;
}

It sets a display for all our icons and a dimension (for consistency among browsers).

Note: if you are using an icon font, make sure to include the font-family declaration in the .icon class (e.g., font-family: ‘MyFont’).

Utility classes for icon sizes

By default, all icons have height and width equal to 1em (defined inside the .icon class).

There are times when you need to change the icon size, in particular for standalone icons (e.g., icons with no text).
We decided it could be useful to have some utility classes to set specific dimensions to the icons, as well as to create a consistent icon grid system throughout the website.

Here’s what we have included so far:

:root {
  --icon-xs: 16px;
  --icon-sm: 24px;
  --icon-md: 32px;
  --icon-lg: 48px;
  --icon-xl: 64px;
}
/* icon size */
.icon--xs {
  font-size: var(--icon-xs);
}
.icon--sm {
  font-size: var(--icon-sm);
}
.icon--md {
  font-size: var(--icon-md);
}
.icon--lg {
  font-size: var(--icon-lg);
}
.icon--xl {
  font-size: var(--icon-xl);
}

Since the height and width of the icons are set to 1em, changing the font size will automatically update the icon dimension (1em is equal to the current font-size value).

We decided to use an absolute unit (px) rather than a relative one (e.g., em) so that we could preserve the dimension of the icons at different viewport sizes.
Note: if you use a Typography system like the one described in the first articleof this series, then the em size is going to change at different media queries (and so would your icon size if you were to use relative units, like em, for the font-size).

Icon style variations

We use a css variable to define the default color for all our icons:

.icon {
  color: var(--color-icon-primary);
}

Note: the color variables are all included into a separate _colors.scss file.

This is quite useful if you need to create color variations for your icons.

For example, let’s assume the --color-icon-primary is the default color we use for icons on a light background.

If we have a dark background component with a class .theme--dark, we can use that class to change the icon color (as well as other relevant color variables). We’ll have something like:

@supports(--css: variables) {
  .theme--dark {
    --component-background: var(--black);
    --color-text: var(--gray-4);
    --color-icon-primary: #fff;
    //..other relevant css variables
  }
}

The idea behind this approach is that you do not have to target the .icon class (or all the other element classes affected by the theming) to modify their style. Instead, you can keep all your color variations in one single place (the .theme--dark class definition) and be able to change the state of the component by just adding/removing that class.

If you want to know more about how we are planning on handling theming (and IE support) for our library of web components, then take a look at the Colors article of this series.

Aligning icons to text

By default, icons have width and height equal to 1em (defined inside the .icon class). This assures they have the same size of the text element in which they are inserted.

This is not enough for the alignment, though. Luckily, Flexbox can help with that!

Here’s the class we use for the alignment (make sure to add this class to the container of the text + icon).

/* add this class to parent element that contains icon + text */
.icon-text-aligner {
  display: flex;
  align-items: center;
  > *:nth-child(2) {
    margin-left: var(--space-xxs);
  }
  .icon {
    color: inherit;
    flex-shrink: 0;
  }
}

The above class uses the align-items property of Flexbox to center its children (text and icon) along the y-axis.
Additionally, the class is used to change the color of the icon so that it inherits the text color.

Here’s how you would use that class:

<p class="icon-text-aligner">
  <svg class="icon"><use href="#icon-dog" xlink:href="#icon-dog"/></svg>
  <em>This is some text here</em>
</p>

And here’s an example of the icon classes/style in action: Link

That is all for now on the icon system for the CodyHouse library of components. We may need to add some additional classes while we build our components, but this should be a solid starting point. Feedback or suggestions are welcome! 🙂

Buttons

Buttons are the most important interactive components used by the users to perform actions. Designing buttons means creating a toolkit that allows interaction with an interface.

In this final section of our series on design systems, we’ll take a look at how to design a system of buttons in CSS.

Setting the basic button style

The starting point of designing buttons in CSS is defining a basic style that can be applied to all our button components:

:root {
    --btn-font-size: 1em;
    --btn-radius: 0.25em;
}
.btn {
    display: inline-flex;
    position: relative;
    white-space: nowrap;
    text-decoration: none;
    line-height: 1;
    padding: var(--space-xs) var(--space-sm);
    border-radius: var(--btn-radius);
    font-size: var(--btn-font-size);
    color: var(--color-link);
}

The basic style includes those properties that you don’t plan on overwriting while creating button variations later on, as well as reset style to prevent common style issues. For example:

• position: relative; is used in case you want to create interactive icons where an icon replaces the text label.

• white-space: nowrap; prevents the text label from wrapping to the next line.

• text-decoration: none; removes the text decoration in case you’re applying the .btn class to a link.

Abstracting the font-size and border radius is particularly helpful in the early stages of creating a design system, when changes are frequent. Padding values are defined according to our spacing system, so that they are automatically responsive.

Style variations

Style variations are different styles used to convey meaning to buttons. They generally include:

• .btn--primary → the main call-to-action button style.

• .btn--secondary → a subtle style version, used for secondary actions or in combo with the primary/accent button.

• .btn--accent → used to draw particular attention to the button (e.g., destructive actions).

• .btn[disabled] → used for feedback, to identify a button that is disabled.

In CSS:

/* themes */
.btn--primary {
    // main button
    background-color: var(--btn-primary-bg);
    color: var(--btn-primary-label);
    @include fontSmooth;
    &:visited {
        color: var(--btn-primary-label);
    }
    &:hover {
        background-color: var(--btn-primary-hover);
    }
    &:active {
        background-color: var(--btn-primary-active);
    }
}
.btn--secondary {
    // subtle version, used for secondary actions or in combo with primary/accent button
    background-color: var(--btn-secondary-bg);
    color: var(--btn-secondary-label);
    &:visited {
        color: var(--btn-secondary-label);
    }
    &:active {
        background-color: var(--btn-secondary-active);
    }
}
.btn--accent {
    // used to draw special attention to the button (e.g. destructive actions)
    background-color: var(--btn-accent-bg);
    color: var(--btn-accent-label);
    @include fontSmooth;
    &:visited {
        color: var(--btn-accent-label);
    }
    &:hover {
        background-color: var(--btn-accent-hover);
    }
    &:active {
        background-color: var(--btn-accent-active);
    }
}
/* feedback */
.btn[disabled] {
    cursor: not-allowed;
    background-color: var(--btn-disabled-bg);
    color: var(--btn-disabled-label);
    box-shadow: none;
    opacity: 0.6;
    &:visited {
        color: var(--btn-disabled-label);
    }
}

A few important notes: first of all, all the colors are defined in a separate _colors.scss file. While working on our framework, we decided to have a single source of truth storing all the colors and themes. For more information, you can check our article on this topic.

Here is a peek at how button colors are defined in our _colors.scss file:

/* --------------------------------
Colors
-------------------------------- */
:root {
    /* main colors */
    --color-primary: #286bf4;
    --color-primary-light: color-mod(var(--color-primary) tint(15%));
    --color-primary-dark: color-mod(var(--color-primary) shade(15%));
    --color-primary-bg: color-mod(var(--color-primary) alpha(20%));
    --color-accent: #f5414f;
    --color-accent-light: color-mod(var(--color-accent) tint(15%));
    --color-accent-dark: color-mod(var(--color-accent) shade(10%));
    --color-accent-bg: color-mod(var(--color-accent) alpha(20%));
    /* shades - generated using chroma.js - 12 steps */
    --black: #1d1d21;
    --gray-10: #2e2e31;
    --gray-6: #7b7a7d;
    --gray-4: #a5a5a6;
    --gray-3: #bbbbbc;
    --gray-2: #d1d0d2;
    --gray-1: #e8e7e8;
    --white: white;
    /* buttons */
    --btn-primary-bg: var(--color-primary);
    --btn-primary-hover: var(--color-primary-light);
    --btn-primary-active: var(--color-primary-dark);
    --btn-primary-label: var(--white);
    --btn-secondary-bg: var(--gray-1);
    --btn-secondary-active: var(--gray-2);
    --btn-secondary-label: var(--gray-10);
    --btn-accent-bg: var(--color-accent);
    --btn-accent-hover: var(--color-accent-light);
    --btn-accent-active: var(--color-accent-dark);
    --btn-accent-label: var(--white);
    --btn-disabled-bg: var(--gray-2);
    --btn-disabled-label: var(--gray-10);
}

The fontSmooth mixin is used to improve font rendering when a light text is used on a dark background. It’s quite common to see this style applied to all HTML elements these days. After doing some research, we opted for creating a mixin to target specific elements, rather than including this style in our global _reset.scss file.

// edit font rendering -> tip: use for light text on dark backgrounds
@mixin fontSmooth {
    -webkit-font-smoothing: antialiased;
    -moz-osx-font-smoothing: grayscale;
}

Since our framework is supposed to be a customizable starting point for web projects of any kind, I tried not to include any non-essential style. For example, I didn’t include shadows, or :focus effects, because they will differ in each project. Providing a default style would force our framework adopters to search and overwrite things, as opposed to having the freedom to build upon things.

Size variations

In addition to style variations, a buttons system should also include size variations. To be clear: I’m not referring to responsive buttons that adopt at different breakpoints, but to having utility classes to create buttons with different sizes regardless of the viewport size.

A good approach to creating such variations is defining size variables (using the CSS calc() function), and then applying these variables to the size utility classes:

:root {
    --btn-font-size: 1em;
    --btn-sm: calc(var(--btn-font-size) - 0.2em);
    --btn-md: calc(var(--btn-font-size) + 0.2em);
    --btn-lg: calc(var(--btn-font-size) + 0.4em);
    --btn-radius: var(--radius);
}
/* button size */
.btn--sm {
    font-size: var(--btn-sm);
}
.btn--md {
    font-size: var(--btn-md);
}
.btn--lg {
    font-size: var(--btn-lg);
}
.btn--full-width {
    display: flex;
    width: 100%;
    justify-content: center;
}

Using icons within buttons

In our article on icons in a design system, we explain how to align icons and text. We can use the same .icon-text-aligner class to align text labels and icons within buttons:

<button class="btn btn--primary icon-text-aligner">
    <span>Button</span>
    <svg class="icon"><use href="#icon-arrow-right" xlink:href="#icon-arrow-right"/></svg>
</button>

Since we may have a button that does not include text but only an icon, it’s a good idea to target the .icon inside the basic .btn class, and make sure the icon inherits the default color of the button label (even if the label is not there):

.btn {
    display: inline-flex;
    position: relative;
    white-space: nowrap;
    text-decoration: none;
    line-height: 1;
    padding: var(--space-xs) var(--space-sm);
    border-radius: var(--btn-radius);
    font-size: var(--btn-font-size);
    color: var(--color-link);
    transition: .2s;
    &:active {
        transition: none;
    }
    .icon {
        /* icon inherits color of button label */
        color: inherit;
        flex-shrink: 0;
    }
}

Button groups

Another classic use case worth including in a global CSS file is a button group. Luckily, Flexbox makes it easy to lay buttons in a simple one-dimensional layout:

/* buttons group */
.btns {
    display: flex;
    flex-wrap: wrap;
    margin-bottom: calc(-1 * var(--space-xs));
    > * {
        margin-right: var(--space-xs);
        margin-bottom: var(--space-xs);
        &:last-of-type {
            margin-right: 0;
        }
    }
}

Responsive buttons

If you’ve been following our series on design systems so far, you know our responsive approach relies on two CSS variables: --text-base-size and --space-unit. Updating these variables using media queries creates a cascade effect that affects the entire design system, including buttons.

In our framework, button components, like all other components, are based on em relative units. The current font-size is updated with the --text-base-size variable. Therefore our buttons are already responsive, with no need to create a single media query within the _buttons.scss file.

_buttons.scss

Putting it all together, here’s our global SCSS file for our buttons:

/* -------------------------------- 
Buttons
-------------------------------- */
:root {
    --btn-font-size: 1em;
    --btn-sm: calc(var(--btn-font-size) - 0.2em);
    --btn-md: calc(var(--btn-font-size) + 0.2em);
    --btn-lg: calc(var(--btn-font-size) + 0.4em);
    --btn-radius: var(--radius);
}
.btn {
    display: inline-flex;
    position: relative;
    white-space: nowrap;
    text-decoration: none;
    line-height: 1;
    padding: var(--space-xs) var(--space-sm);
    border-radius: var(--btn-radius);
    font-size: var(--btn-font-size);
    color: var(--color-link);
    transition: .2s;
    &:active {
        transition: none;
    }
    .icon {
        /* icon inherits color of button label */
        color: inherit;
        flex-shrink: 0;
    }
}
/* themes */
.btn--primary {
    // main button
    background-color: var(--btn-primary-bg);
    color: var(--btn-primary-label);
    @include fontSmooth;
    &:visited {
        color: var(--btn-primary-label);
    }
    &:hover {
        background-color: var(--btn-primary-hover);
    }
    &:active {
        background-color: var(--btn-primary-active);
    }
}
.btn--secondary {
    // subtle version, used for secondary actions or in combo with primary/accent button
    background-color: var(--btn-secondary-bg);
    color: var(--btn-secondary-label);
    &:visited {
        color: var(--btn-secondary-label);
    }
    &:active {
        background-color: var(--btn-secondary-active);
    }
}
.btn--accent {
    // used to draw special attention to the button (e.g. destructive actions)
    background-color: var(--btn-accent-bg);
    color: var(--btn-accent-label);
    @include fontSmooth;
    &:visited {
        color: var(--btn-accent-label);
    }
    &:hover {
        background-color: var(--btn-accent-hover);
    }
    &:active {
        background-color: var(--btn-accent-active);
    }
}
/* feedback */
.btn[disabled] {
    cursor: not-allowed;
    background-color: var(--btn-disabled-bg);
    color: var(--btn-disabled-label);
    box-shadow: none;
    opacity: 0.6;
    &:visited {
        color: var(--btn-disabled-label);
    }
}
/* button size */
.btn--sm {
    font-size: var(--btn-sm);
}
.btn--md {
    font-size: var(--btn-md);
}
.btn--lg {
    font-size: var(--btn-lg);
}
.btn--full-width {
    display: flex;
    width: 100%;
    justify-content: center;
}
/* buttons group */
.btns {
    display: flex;
    flex-wrap: wrap;
    margin-bottom: calc(-1 * var(--space-xs));
    > * {
        margin-right: var(--space-xs);
        margin-bottom: var(--space-xs);
        &:last-of-type {
            margin-right: 0;
        }
    }
}

Conclusion

This article marks the end of our CSS-focused series on design systems! All the globals we’ve been writing about will be bundled into a repository and made available for download on Github soon! Together, they represent our first attempt at creating a framework.

Next, we’re going to code a collection of components compatible with the framework. The idea is to provide an arsenal of ready-to-use web modules that developers can copy and paste into their projects.

The original Article Series:
- Part 1: Typography
- Part 2: Grid & Layout
- Part 3: Colors
- Part 4: Spacing
- Part 5: Icons
- Part 6: Buttons