Hocus-Pocus: Building a Design-Free Sass Framework

Bartłomiej Kozal

Hocus-Pocus is a design-free Sass framework that I’m working on in my free time. The main idea behind Hocus-Pocus is to make a universal and lightweight stylesheet starter kit that focuses on the most common features. In this article, I’ll cover why I decided to build my own Sass framework and the approach I’ve taken when doing so.

Why Have I Started Working on a Sass Framework?

In short, I would say I’ve started working on a Sass framework because I wanted to save time when starting new web projects. I’ve noticed that even when I work on really custom designs, I always add the same set of tools, include the same standard packages, and implement a similar collection of basic CSS components.

The second question that follows then is — Why you don’t you use an existing, well-known and proven framework like Bootstrap?

My response to this comes down to preferences and my approach to CSS. I think libraries like Bootstrap or Foundation are great and have greatly changed how people think about CSS. However, in most cases within my own project work, I just don’t need all these features and UI components like progress bars or breadcrumbs. Instead, I prefer to have something more universal. I prefer something that I can use in any project, without needing to override framework CSS classes.

Due to the reasons above, in Hocus-Pocus you can change the look of every single component with variables. You can even disable some features or define a range of helpers. The downside of this approach is that I can’t provide a compiled CSS version of the framework as there is no reasonable way to use Hocus-Pocus without an ability to update variables.

Pre-requirements and principles


The framework is available and easy to install with two different package managers: Bower and npm. It requires Sass (minimum required version is 3.3.0) and Autoprefixer to run. Autoprefixer is used to add necessary vendor prefixes to the final compiled CSS file. I don’t worry too much about compatibility between various browsers nowadays as I personally find autoprefixing to be sufficient. Additionally, I use sass linter (scss-lint), but this is not required for running Hocus-Pocus and doing things the right way. Hocus-Pocus will work without it.

Naming Convention

The next principle is an important one for every framework — the naming convention. I prefer regular, dash style class names without BEM. I won’t complain if you are a fan of BEM and prefer to use the BEM naming convention, if it works for you — go for it. From my perspective, BEM doesn’t fix all of the responsibility problems in CSS. I also find that I approach my CSS using less class-level elements when I use BEM. Adding a new element to an existing block is just too easy.


Last but not least, I pay close attention to writing documentation and keeping the Hocus-Pocus changelog up to date. Documentation doesn’t have to be perfect, especially at the beginning, but I always try to find time to improve it. This helps newcomers learn how the tool works and allows me to keep track of framework features.

Framework Features

The following framework features are the most characteristic to Hocus-Pocus in my opinion and give the best overview of what its focus really is.

Most of the framework classes are inspired from existing projects that I’ve worked on in the past. You may also spot some similarities to other CSS frameworks that have inspired me, especially my favorites — Primer and InuitCSS.

Framework features in Hocus-Pocus include:

  1. Normalize with some enhancements like global box-sizing set to border-box or text elements without top margin.
  2. A new default color palette based on clrs.cc.
  3. A fluid grid based on flexbox with width helpers that use fractions as class names (.1/2, .1/3 and so on).
  4. Wide support for responsive web design. There is an option to choose either “mobile first” or “desktop first” as your preferred approach. You are also able to define breakpoints for each and each of them gets their own set of helpers for spacing, grid, visibility, and an individual Sass mixin.

For example:

$rwd-type: desktop-first;
$rwd-map: (
  'mobile': 680px
$spacing-map: (
  'double': double($spacing-unit)

Then in compiled CSS you’ll have access to classes like .mobile-1/2, .mobile-hidden and .mobile-padding-double.

  1. Generic default styles for text elements with vertical rhythm based on Gridlover.
  2. Extra modifiers for other HTML elements like an inline list, a menu list, a circle image or a zebra table.
  3. Various button types and three versions of forms: inline, stacked and horizontal.
  4. Essential UI components like the media object, box object, navbar, a hero element for landing pages and a sticky footer. Nothing more.

Future Hopes for Hocus-Pocus

My goal is to make Hocus-Pocus an ideal Sass starter kit no matter how complex your projects are. This way, you can focus on writing project specific UI components and defining your theme.

I don’t plan to implement any major new features. I think the features included are a reasonable amount of features and are likely to be the final ones. I’ll probably improve syntax for some components or change some single class names, but I don’t predict any compatibility breaking changes from the current version. For now, I’m more committed to fixing bugs that occur as more people give Hocus-Pocus a try.

If you think the Hocus-Pocus framework might be helpful for you in an upcoming project, you can find full documentation at hocus-pocus.io. The Hocus-Pocus code is open source and all available on GitHub. I appreciate any comments, feedback, and information about potential issues.