Minimal CSS with Carbon
If you haven’t heard of the Carbon Design System before, check us out! We’re the design system for IBM, shipping open-source styles and components in Vanilla, React, Angular, and Vue for anyone building on the web.
When adding Carbon to a project, one of the first things you’ll tackle is how to include CSS for components you want to use. If you’ve followed along with our Getting started guide, or any of our Up & Running posts, we offer some tips for how to add Carbon quickly to your project.
What about the next step though? If you’re a team into optimizing every part of their UI, you might be curious how you can shrink the amount of CSS you’re shipping that comes from Carbon. Turns out, we can help.
First, let’s take a look at some of the ways you might be including styles in your project. After that, we’ll look at how you can optimize how you’re using Carbon today 😎
Using unpkg as a CDN
If you’ve followed along with Carbon’s getting started guide for developers, you might have seen a section where we call out using a CDN. Since we publish Carbon Components as a package on NPM, we are able to use a service called Unpkg as a quick way to serve files distributed via the carbon-components package.
This makes it easier to include Carbon’s CSS in any HTML page because you can use the <link> tag to include the whole stylesheet, for example:
<link rel="stylesheet" href="//unpkg.com/carbon-components@9.90.0/css/carbon-components.min.css">This approach is absolutely amazing for prototypes, getting started, creating reproducible bug reports, and more. When getting started quickly is what you’re after, this method is perfect 💯
When we start to consider the performance of this approach, however, it becomes clear that this will include every single bit of CSS that Carbon outputs. Sometimes, you totally need everything that the project provides, but for a good number of teams you may find yourself using only a subset of our components.
If we take a look at the directory listing for carbon-components's CSS folder, you can see that the overall size of the carbon-components.min.css file is 213kB.
Thankfully, if we included this in a project you might notice a number that is considerably smaller:
What we learn from this is that the uncompressed size of Carbon’s CC is around 213kB, but if we use a file compression format like gzip that number drops dramatically to 26.4kB.
For some teams, this number might fall well within their performance budget. However, if you’re a team using precompiled CSS from Carbon you might be wondering how do you make use of aspects of our design system like theming.
Unfortunately, when using precompiled CSS you lose out on some of the features you could get by using Sass. Most notably, this includes:
- Loss of the ability to introduce theming into your project through our theme tokens
- Helper functions and mixins to automate tasks or styling while building components
- Ability to try out new features through our feature flag system
So, if using the precompiled CSS isn’t ideal, what are some other options?
Building Carbon using Sass
If you have Sass setup in your project, you can use the sass files that Carbon ships to include styles in a similar way to the unpkg CDN. To start off, make sure you’ve installed the carbon-components package. You can do this by running:
npm install carbon-components --saveIf you prefer Yarn, you can run:
yarn add carbon-componentsIn your sass files, you include the following import to include all of the styles for Carbon:
@import 'carbon-components/scss/globals/scss/styles.scss';Note: this import path may change depending on how your project is setup, for a full guide checkout our getting started guide for styles.
Including this file will give you the same output as the unpkg example, but it also gives you full access to all the variables, helpers, feature flags, and mixins that we offer to make building on top of Carbon even easier. If you’re looking for a good place to start learning more about these tokens, checkout our color guidelines!
Ok, now we have the same CSS output as the unpkg link above. So how do we use this Sass approach to optimize our CSS?
Importing Components
If you take a look at the source file for our Sass import above, you’ll notice a block that shows how we’re importing all of the components to be included in the CSS output.
Each of these import paths correspond to all the styles that each component will need in order to render correctly on the screen. If you want to replicate the same structure in your project, you can update the @import ‘carbon-components/scss/globals/scss/styles.scss’ import to the following:
// Include some flags that are used to control the CSS output
// of things like resets, font families, and resets
$css--font-face: true;
$css--helpers: true;
$css--body: true;
$css--use-layer: true;
$css--reset: true;
$css--typography: true;
$css--plex: true;// Include each component as you start using it in your project
@import 'carbon-components/scss/components/button/button';
Each component-specific import will follow this same structure, where the component name is used to identify the folder and partial name. If you are looking to make use of tokens or helper mixins in your code, you can follow a similar strategy to include those by importing the following files:
// Provides color variables for use in your project, these come
// from the IBM Design Language
@import 'carbon-components/scss/globals/scss/colors';// Bring in color theme tokens
@import 'carbon-components/scss/globals/scss/theme';// Imports spacing tokens for you to use
@import 'carbon-components/scss/globals/scss/spacing';// And much, much more!
Setting your project up in this way allows you to better control your CSS bundle. If we compare this one example where we are only including button, then we see that the output bundle size is goes from 26kB gzipped to 2.4kB!
Although this number can be surprising since we’re only using one component, it’s important to remember that behind the scenes we also enabled things like CSS Resets and other tools that help with our final CSS artifact.
If you want to go for an even smaller CSS artifact, then messing around with the $css- flags provided above would be a great start!
Wrapping up
Using Carbon’s Sass files is a great way to improve how you author components. It also opens up the opportunity to fine tune your application to guarantee your users the best experience possible.
If you have other tips for reducing the load-time cost of including Carbon, let us know! We’d love to hear from you here or on Twitter and Slack 🎉
We want (need) your feedback
Run into any issues or have feedback for us? Please make an issue on our project over on GitHub and we’ll make sure to get back to you as soon as possible!
The Carbon Design System is the open-source design system for IBM. It is a series of individual styles, components, and guidelines for creating unified User Interfaces. We’re always looking for contributors for our projects, if you’re interested please check out one of our projects on GitHub.
Have any questions or concerns about the Carbon Design System? Please reach out to carbon@us.ibm.com.
