Smoothie 🍹

A deliciously scalable and adaptable stylesheet methodology

Note: This methodology is still in its early days and may be subject to big changes

The current CSS landscape is thriving and overflowing with new concepts and tools, but this often leads to two scenarios:

1. Where on earth do I start?
2. How can I regularly experiment with new tools without having to completely refactor my existing project styles?

Smoothie's high-level 3-layered architecture gives you the freedom to easily build and experiment with the CSS tool/s that you want to use.

Contents

1. Why?
2. Architecture
   1. Tokens
   2. Global
   3. Components
3. Recipes
4. Standards
5. Tools
6. Built with Smoothie
7. Resources

Why? 🤷‍

The passionate debate around latest CSS tools/techniques can at times feel hostile and overwhelming. Certain methods may offer more advanced features but it mostly boils down to a matter of preference.

Smoothie came about after feeling fed up with being told what is "right" or "wrong" when it comes to using CSS tools. Just because one method feels right for your project, it doesn't justify putting down the solutions of others.

What I hope to bring with Smoothie is a middle-ground; the freedom and encouragement to experiment with tools/techniques to figure out what's right for you.

Architecture 🏗

Smoothie splits your design into 3 key layers, imported in the following cascade order:

1. Tokens
2. Global
3. Components

Let's break that down into more detail…

1. Tokens

Tokens, or "Design Tokens" are an intrinsic collection of values that define your project/Design System's visual language. This could include information such as:

• Colours
• Spacing
• Typography - e.g. font-size, line-height, scale
• Animation - e.g. speed, easing
• Breakpoints
• etc…

Tokens are preferably platform-agnostic and human-readable, stored in YAML/JSON.

However, for smaller projects, if you'd prefer to store your tokens in a single format that compliments your build process, that's totally fine. For example; if you're using SCSS you could use traditional variables/maps (just be careful when it comes to CSS variables), or if you're using a CSS-in-JS library you could store in a JS module. Choose a solution that works best for your needs.

If you're stumped on build processes, check out the recipes.

Examples

• Polaris Tokens - @Shopify
• Design Tokens - @opentable
• Photon Design Tokens - @FirefoxUX

2. Global

CSS is heavily criticised for its global scope—with common pain points including clashing selectors and specificity battles—but is it actually that bad?

Smoothie's recommended global architecture borrows from Harry Roberts's successful ITCSS, with some minor adjustments.

Note: Don't necessarily feel obligated to use this specific strategy, the best strategy is to have one.

This layer should be kept as slim as possible and treated as critical CSS; defined through a single inline <style> tag at the very top of your document.

So, consider grouping your global styles and defining in the following order:

1. Settings Config (Optional)
   • If you're using any third-party packages, this is where you'll want to tie any variables to your previously-defined Tokens. If you're not using any third-party packages you can discard this layer.
   • For example - for example, you may want to tie breakpoints in your Tokens to a Sass-powered media query library such as Sass MQ.
2. Tools
   • Mixins, Functions etc.
3. Generic
   • The first layer that actually outputs CSS, containing high-level styling.
   • For example - Resets, Normalize etc.
4. Elements
   • Base styling for your HTML elements.
   • For example - Page, Basic Links, Tables etc.
5. Objects
   • Common structural and non-cosmetic design patterns.
   • For example - your grid system, media object, flag object, lists etc.
   • Implementation
     • Objects should use class selectors for complete markup flexibility.
     • Consider prefixing your object classes with .o- for extra clarity.
6. Trumps Utilities
   • Helper classes that have the power to override any other styles.
   • For example - spacing, typography, hiding content etc.
   • Implementation
     • Utilities have a narrower focus and carry higher specificity thanks to its use of !important. For this reason, ITCSS refers to the layer as "Trumps", but with recent updates to the political climate, it felt best to be agnostic.
     • Consider prefixing your utility classes with .u- for extra clarity.

Examples

If you're still stuck, check out these great ITCSS examples:

• Toolkit - @sky-uk*
• Supercell - @sky-uk
• Pantsuit (Medium Article) - hillaryclinton.com
• inuitcss - @inuitcss
• Blaze - @blaze-ui

* Shameless self-promotion of previous work.

Just remember, in Smoothie the "settings" and "components" layer are handled differently (as described above).

3. Components

By definition, components are the individual building blocks that form your user-interface; such as buttons, forms, user icons and so much more.

There is a growing need–especially in large-scale web apps–to create components that are fully encapsulated and less susceptible to leaking CSS; in other words, components that can be lifted and shifted anywhere with ease.

What are the options?

Now that your components are kept separate from your tokens and global styles, you have complete freedom to explore a range of options to build them! H*ck, you could even test different tools for different components.

The choice is yours.

You could use:

• CSS
  • Contrary to popular belief, you can still write component styles in a standard stylesheet. You could even use a processor to make your life a little easier.
  • Similarly to the Global layer, have a strategy to ensure consistency and prevent clashing selectors.

    ProTip: Use BEM, and prefix your component classes with .c- for extra clarity.

• CSS-in-JS
• Shadow DOM
  • Defining your styles inside the Shadow DOM will scope them to the Shadow Root and fully encapsulate your component styles.

Recipes 📖

Unsure where to start? Check out some of these example projects:

1. JSON, SCSS and Emotion (WIP)
2. JSON, SCSS and Styled Components - Live Demo
3. SCSS - Live Demo (Project Docs)

Want to run these recipes locally? See the recipes/README.

Standards ✍️

Linting

Kick-start your project's stylesheet linting with Smoothie's Stylelint configs:

• @smoothie-css/stylelint-config
• @smoothie-css/stylelint-scss-config

Linting is a great way to automate maintaining coding standards and readability, with Stylelint being one of the most well-known tools.

As always, feel free to customise/extend these or use your own project's config to meet your specific needs.

Tools 🛠

Token Tools

• Theo - @salesforce-ux

  A tool that transforms Design Tokens into a huge range of different consumable formats.

Build Tools

There are a bunch of great tools to make your life even easier when it comes to writing CSS:

• Pre-processors (Ideal for Global, Components)

  • Less
  • Sass
  • Stylus

• Post-processors (Ideal for Global, Components)

  • PostCSS

• CSS Modules (Ideal for Components)

• CSS-in-JS (Ideal for Components).

  • Emotion
  • Styled Components

  Note: Some libraries offer an injectGlobal feature but this is discouraged and can often cause issues with the cascade

Built with Smoothie 🍹

• LADbible (WIP)

Using Smoothie in your project? Feel free to raise a PR and add yourself to this list.

Resources 📚

Tokens

• "Design Tokens for Dummies" - @chuckn0risk
• "Tokens in Design Systems" - @nathanacurtis
• "Creating Themeable Design Systems" - @bradfrost

Global

• "Managing CSS Projects with ITCSS" - @csswizardry
• "Object Oriented CSS" - @stubbornella

Components

• "A Unified Styling Language" - @markdalgleish
  • CSSconf EU 2017 Talk (YouTube)
  • Article (Medium)
• "All You Need to Know About CSS-in-JS" - @wesharehoodies

License ©

Licensed under the Apache 2.0 License, Copyright © 2018-Present Joe Bell.

See LICENSE for more information.