Stylament

A fundament for your document styling.

Designed to advocate consistency while providing a fair amount of flexibility.

What?

Stylament is

not a design system itself
but a system of tools for scaffolding design systems, think meta design system,
neither a “CSS framework” nor a “CSS methodology” intended to relieve you of the need to learn CSS
but a rather sophisticated approach to take advantage of the strengths of CSS (reusability, organizability, … The Cascade™)
not a simple theme to apply to your pages and be done, but it comes with blueprints for building well-structured and prettily-styled web pages,
simply put, a parametrized Sass stylesheet along with some suggestions on HTML patterns to use.

Why?

TL;DR

It’s all because of the CSS saga. And it’s my personal version of its continuation since 2022.

The Long and Winding Road (to Enlightenment)

I encountered CSS for the first time in the late ’90s, not much later than HTML. But it was only around 2001 when I began actively using it and started understanding that it is so much more than just another syntax to write HTML spilled with presentational features. Sites like Listamatic were eye-openers at that time. And of course, the CSS Zen Garden was the lighthouse to guide the way.

But despite the separation of presentational and structural aspects, as with any code you write, stylesheets quickly grow confusing, unless you organize them well. No matter how much I knew about certain CSS specifics and the newest features, how much CSS and rendering engines evolved – the remaining and recurring problems always revolved around organization. I could write very smart CSS rules. But I needed rules how to arrange those rules. What belongs where? Where to look if something is already defined?

Motivation

When it comes to processing amounts of information bigger than what we can crasp at a glance the following holds for most of us:

We want order.
We want structure.
We want separation of concerns.
We want confidence where to put things and where to find them.

Therefore, we design classification systems, rules and standards. And despite common goals sometimes we just need to develop the 15th standard. So did I.

Competition

Yes, I’m aware: Frameworks do exist.

Sure, I’ve seen dozens of projects relying on Bootstrap (at least half of which with a long-term TODO: “Get rid of Bootstrap”). I used to be on the Foundation side for quite some years (mainly because: a little less utility class polution). However, I was never quite contented with that kind of frameworks as they required substantial adjustments to the markup in order to work.

I was still searching for a framework that I could employ with any thoroughly marked-up document to just work out of the box. In recent years, the term classless CSS framework was coined for exactly that. And there are plenty. I really like some of them. They are a great and effortless way to give your plain HTML document a modern look. On the other hand they usually fall short when it comes to customizability.

The sheer opposite are “utility first” frameworks. I’ll spare the words and let Heydon speak. Nevertheless, what I’d like to mention in that context: Defining atoms of the design language (a.k.a. design tokens) is an essential step in setting up a design system. But they belong in the right layer. Frameworks like Open Props do that.

Apart from frameworks, there are also a lot of methodologies that come without any predefined styles but rather with naming conventions and suggestions on how to organize your CSS. Which is good. To name a few:

I like ITCSS (at least the organization aspect), because when I stumbled upon it, it perfectly reflected the way I had learned to think about the organization of CSS (or things, actually) – from general to specific. (The layer names in Stylament are obviously inspired by ITCSS.)
I like the general idea of BEM but not its redundant class names.
I like CUBE CSS. It’s a great approach to use the right tool for each job.
Did I mention, I do not like utility first?
I like Every Layout!

The Missing Piece

After looking into all those frameworks and methodologies I still hadn’t found an HTML & CSS system that really met my expectations, which were:

strong support for well-structured markup – without class garbage
clear rules defining what belongs where
mathematical tools to generate series of design tokens from a small set of configurable values

Especially the last point I couldn’t find satisfied anywhere. So, I started my own system.

How?

Rules-driven: Good style needs rules. Stylament relies on a set of rules (yes, that’s CSS DNA, you name it) that build on one another.
Consistency-first: Obey the rules! The less exceptions, the better. But if they exist, they do so to prove the rules.
Classless-first: Good mark-up can do without extra class-level specificity more often than you’d think. Although not a typical classless CSS framework per se, Stylament does a lot of heavy lifting on the element and idiom layers.
Utility-last: With the above being said, Stylament acknowledges the usefulness of utility CSS – for said legitimate but rare exceptions.

Embracing Inspiration

Stylament appreciates and is inspired by what’s in the wild:

organized in layers like ITCSS
using the best of different methodologies (the right tool for the job) like CUBE CSS
founded on axioms like Every Layout
driven by series of CSS custom properties like Open Props

Layers of Stylament

Implementation

Stylament is written in Sass. Actually, it’s just a Sass stylesheet. With a somewhat complex configurability.

Install

Essentially, clone the repository and include the Sass sources in your Sass stylesheet.

Or, if you like package managers:

npm install github:smnscp/stylament

Configure

In order to adjust the design token series that Stylament generates, define a configuration map, e. g. in custom/config.scss:

$config: (
  layout: (
    // …
  ),
  typography: (
    // …
  ),
  ui: (
    // …
  ),
  coloring: (
    // …
  ),
);

See the documentation for details.

Use

In your stylesheet entry point (e. g. index.scss) load your custom configuration and the Stylament (sub-)layers you want to include, injecting your config into the axioms layer.

@use "custom/config" as custom;

@use "stylament/css/axioms" with ($config-custom: custom.$config);
@use "stylament/css/elements";
@use "stylament/css/idioms";
@use "stylament/css/objects";
@use "stylament/css/utilities";