Kingdom CSS

A CSS framework, written in Sass, for consistent spacing, sizing and typography.

Kingdom is still under development, we're not at version 1.0 yet, so expect everything to be in a state of flux! You can check the release history and any comments or suggestions are most welcome!

The main task of Kingdom is to put a solid base styling on your common semantic HTML—that doesn't necessarily have any classes—like you would expect to be input by a somewhat tech-savvy content editor, or perhaps generated from Markdown. The pages of this documentation is a living example—go on, inspect its elements in your browser's dev-tools!

Kingdom doesn't provide ready-made components or widgets like cards or navbars. It's not for bootstrapping your site with someone else's design. Instead, Kingdom is a foundation with sensible defaults for building your own custom design (system).

With proper semantic HTML, Kingdom can help you implement Brutalist Web Design. The basic styling of Kingdom doesn't go against what is considered standard behaviour of web pages, for example that links are underlined and buttons look like buttons.

Much like Tailwind, Kingdom is utility-first—meaning it has CSS classes that can be combined on your HTML elements to quickly create more complex looks. Like the following <blockquote>, that just has a bunch of utility-classes (text-4-block border-l space-inside color-primary) applied to style it:

If content is king, context is the kingdom

Then, when the need arises, you can create your own CSS components—with your own structure and naming system—that encapsulate those behaviours for reuse. For example, you might combine the above into your own BEM-style component that you apply to elements wherever this particular pattern is needed. Or perhaps you want this opinionated style on every <blockquote> element? You're free to do that too!

When it comes to this, Kingdom has plenty of Sass mixins, functions, and placeholders to support you in keeping everything consistent throughout your design system.

There's also a point in having a limited, but carefully selected, set of building blocks—it helps you make decisions faster. Do you need some padding inside a bordered element so that its text content doesn't lay tight on the border? Just extend .space-inside or include space-inside() and you're set. There's no need to think about how many pixels or other length units you need for every specific case—you've already made that decision in one central place!

Installation via npm

npm install kingdom-css

Demos

The demo pages are set up with no options at all, meaning they even generate a random primary color. To see an example of all four levels of Kingdom side by side, you can visit the demo page. The form extension can be seen in action on the forms demo page.

Not for the faint of heart

Kingdom CSS embraces the cascade, is utility-first, has no namespacing, extensively extends CSS classes, and does all kinds of other things that might seem scary and are sometimes even frowned upon. Not everyone will like it, and there are certainly situations where its not the best fit. But there is a thought behind it all, and I hope this documentation will eventually convey both the why and how of each realm within the Kingdom.

Constitution

Kingdom CSS consists of four levels to choose from, where each level adds some functionality on top of the previous. After selecting a level by importing its file, there are some optional utilities (providing classes for styling elements) and extensions (that directly affect element styles) available to include. Every import has default options, configurable with Sass variables.

This webpage is displayed using Level 3, with all utilities of Kingdom included. Only one configuration variable, the primary color, is set before the Kingdom level is included. Everything else is default, and additional colors are automatically derived from the primary color.

Most everything in Kingdom relies on Sass mixins and functions from the modules. But they're not just for internal use—you can benefit from using them in your own Sass.

The four levels

You'll find each level's Sass file in node_modules/kingdom-css/src/ and you should pick and import only one.

The 1st level is an opinionated CSS reset, laying a foundation for the other levels.
The 2nd level applies consistent spacing between blocks and a scale for sizing text elements.
The 3rd level adds a vertical rhythm, helping blocks to line up across columns by keeping line heights consistent.
The 4th level makes every line of text go on a common baseline, making individual lines of text line up across columns, even if they're in different font sizes.

Utilities

These files provide utility classes that you can put directly on your HTML elements. You'll find them in node_modules/kingdom-css/src/utilities/ and you may import any one you'd need, in any order.

Extensions

Some things affect the default styling of standard HTML elements in such an opinionated way that they're best kept in their own "package" for optional inclusion. The extensions are located in node_modules/kingdom-css/src/extensions/ and you may "scope" an extension by importing it within a selector.

Modules

Some of the modules are just a single function or mixin for a specific task, but most consists of many mixins and functions providing related functionality. You'll find the modules in node_modules/kingdom-css/src/modules/ and they can be included wherever you need some functionality within.

Most of the modules are already imported and can be implicitly used, but it doesn't hurt doing an explicit import in the Sass file where you're using them.

Testing

We're using Browserstack for testing across web browsers, please check out their amazing services!