supple-kit / supple-css

In browser (S)CSS framework; Fluid, Variable, supple if you will

Supple (S)CSS framework

Introduction

Supple CSS is a reliable and testable Sass framework in its truest sense. It's based on the ITCSS methodology and is suited very well for component-based UI development. Supple CSS plays well with React, Angular, Vue, Svelte, and every other component-based approach to UI development.

Table of contents

• Why use Supple
• Features
• Browser support
• Installation
• Getting started

Why use Supple

It is a small but powerful (S)CSS framework designed especially with modern browsers in mind. The framework is made with an eye on the future. It uses new CSS webstandards like custom properties, Grid layout, Flexbox, logical properties.

Supple provides little to no design. This means that the style and design of your site are left entirely up to you. Because Supple gives you lots of customizable foundations you only need to add the final layer: UI.

Features

A grasp of Supple's features:

• Sensible, powerful CSS reset for web applications.
• Suite of functions and mixins for speedy development.
• CSS Grid & Flexbox objects for creating layouts.
• Objects for reusable solutions to common features.
• Variety of utility classes for the most common needs like visually hiding, spacing, and more.

Size

The framework including all modules weighs less than 1.6kB (GZIP-ed). With this small payload, you have the power to build an entire website without even writing a single line of CSS. You can reduce the payload even further by only including the modules you need, and configure those modules to your needs.

Browser support

Supple supports all major browsers which can render the following features:

• CSS Variables (Custom Properties)
• CSS Logical Properties
• CSS Grid Layout
• CSS Flexible Box Layout (Flexbox)

Basically that comes down to:

• Chromium-based browsers (Chrome, Edge, Brave, Opera)
• WebKit-based browsers (Safari, iOS Safari)
• Firefox (Gecko)

Note: Internet Explorer is not supported. Supple relies mostly on CSS Custom Properties, which are not supported and cannot be polyfilled.

Installation

Prerequisites

Supple is built with the latest version of Sass so your build-pipeline must be equipped with Dart Sass.

Install

• npm: npm install @supple-kit/supple-css

Getting started

Supple is built using the Sass module system and it is advised to structure your application the same way.

Below are some examples of how to use and structure the framework:

With 1 manifest file, eg. styles.scss

// styles.scss
@use 'settings/your-own-vars';
@use 'node_modules/@supple-kit/supple-css/objects/mesh';
@use 'components/your-own-component';
@use 'node_modules/@supple-kit/supple-css/utilities/colspan';

// settings/_your-own-vars.scss
@use 'node_modules/@supple-kit/supple-css/settings/defaults' with (
  $font-size: 20px,
  $columns: 10,
  $breakpoints: (
    lap: 320px,
    desk: 960px,
  )
);

@use 'node_modules/@supple-kit/supple-css/objects/mesh/variables' with (
  $columns: 24
);

// components/_your-own-component.scss
@use 'node_modules/@supple-kit/supple-css/settings/defaults';
@use 'node_modules/@supple-kit/supple-css/tools/space';
@use 'settings/your-own-vars';

.your-own-component {
  margin-inline-start: space.get('base');
  transition-timing-function: your-own-vars.$animation-timing-function;
  font-size: defaults.$font-size;
}

In a component-based setup like React, Vue, Svelte, etc.

// settings/_your-own-vars.scss
@use 'node_modules/@supple-kit/supple-css/settings/defaults' with (
  $font-size: 20px,
  $columns: 10,
  $breakpoints: (
    lap: 320px,
    desk: 960px,
  )
);

// components/your-own-component/index.js
import './index.scss';

// rest of your javascript code

// components/your-own-component/index.scss
@use 'settings/your-own-vars';
@use 'node_modules/@supple-kit/supple-css/tools/space';

.your-own-component {
  margin-inline-start: space.get('base');
  transition-timing-function: your-own-vars.$animation-timing-function;
}

Available modules

All Supple's modules are created based on the ITCSS methodology. It is advised you to read ITCSS documentation to fully grasp the ideas about the methodology.

Settings

This layer is the first layer and holds any global settings for your project. It should only house settings that need to be accessed from anywhere.

• settings/defaults, Supple's core settings.

Note: Any variable that does not need to be accessed globally should belong in the module to which it relates.

Tools

The tools layer houses your globally available tooling, mixins, and functions.

• tools.

Note: Any mixin or function that does not need to be accessed globally should belong in the module template to which it relates.

Generic

It contains ground-zero styles like global box-sizing rules, CSS resets, and so on.

• generic/reset, a reset of sensible defaults suitable for web applications.

Elements

These are bare, unclassed HTML elements. The Elements layer binds onto HTML element (or 'type') selectors only.

Elements are most likely the last layer in which we'd find element-based selectors, and is very rarely added to or changed after initial setup. Once we have defined element-level styles, all additions and deviations should be implemented using classes.

Note: Because Supple is a design-free framework this layer is empty.

Objects

This layer is concerned with styling non-cosmetic design patterns, or 'objects'.

• objects/list-clean, strip appearance from lists by removing their bullets and indents
• objects/retain, page-level constraining and wrapping elements
• objects/layout, arrange items horizontally on the inline-axis with flexbox.
• objects/mesh, fluid & extensible grid system based on CSS grid.
• objects/aspect-ratio, retain a specific aspect ratio but adapt to elements of variable widths
• objects/flow, create flow and rhythm between elements.

All Objects are prefixed with o-.

Components

This layer contains our recognizable components, chunks of UI.

All Components are prefixed with c-.

Note: Because Supple is a design-free framework this layer is empty. You can add your own components to your project.

Utilities

This layer contains some handy helpers & overrides. This is the most specific layer of the application which overrides everything defined before.

• utilities/columns, provides a columns custom property for use in objects or components.
• utilities/colspan, provides a colspan custom property for use in objects or components.
• utilities/colstart, provides a column start custom property for use in objects or components.
• utilities/offset, provides a offset custom property for use in objects or components.
• utilities/clearfix, clears floats.
• utilities/spacing, utility classes to put specific spacing values onto elements.
• utilities/visually-hidden, hides an element visually while still allowing the content to be accessible.
• utilities/hidden, completely remove from the flow and hide it from screenreaders.

All Utilities are prefixed with u-.

Browserstack

Every feature in Supple is extensively tested in Browserstack:

Credits

Supple is derived from the ideas of many other developers:

• Harry Roberts for his awesome ideas with ITCSS and numerous other CSS stuff.
• Nicole Sullivan for her work on OOCSS.
• Jonathan Snook for his work on SMACSS.
• Nicolas Gallagher for his work on numerous CSS things.
• Machiel Hulsbosch for the supple logo.
• Joris Hulsbosch for general advice and in-field testing.

And probably more…

supple-css's Issues

Option to write media queries to Custom Media Queries

https://cssdb.org/#custom-media-queries

Move `o-retain--text` to seperate object or utility

questioned by @nadiavanleur in PR #10:

But then the question arises if a text retain needs to live in the retain object. Both are trying to solve different problems. Mayb it is better to move the text retain to a new utility or something.

Rewrite build step to accommodate multiple CSS files

Rewrite file structure to be able to export to CSS files

Can't generate u-hidden and u-visually-hidden from/until - lap/desk classes

I'd like to generate multiple classes:
u-hidden@from-lap
u-hidden@until-lap
u-hidden@from-desk
u-hidden@until-desk

This can't be done right now, by using:
$supple-breakpoint-has-hidden: (from: lap, until: lap, from: desk, until: desk);, SASS doesn't allow duplicate keys.

More a feature request than a bug I think ;)

`responsive.lock` mixin doesn't work on the HTML element if you use use a global font size other than 16px

Describe The Bug:
The responsive.lock utility and typography.font-size don't play nicely together, if you use a global font size other than 16px. Fonts get big if default font-size is set really low.

To Reproduce:
Add

@use 'node_modules/@supple-kit/supple-css/settings/defaults' with (
  $font-size: 12px,
}

html {
  font-size: responsive.lock(vars.$font-size, vars.$font-size + 4px, desk, tv);
}

.some-element {
  @include typography.font-size(vars.$milli);
}

Expected behavior:
It all scales proportionally.

Environment:
MacOS

• Supple CSS Version: 5.1.0
• Node.js Version: 16.13.1
• NPM Version: 8.1.2
• Browser: Firefox

Split up layout into 2 separate concerns

Split layout into grid & arrange modules

Layout module: cells are not 100% wide by default in legacy browsers

Result
In browsers that do not support css custom properties, layout cells are not 100% wide by default.

Expected result
Cells are always 100% wide by default in legacy browsers.

Default $mq-breakpoints setting can't be overwritten

https://github.com/supple-css/supple/blob/82d5829b6863715e0dd2cade0a94e0fca52f9f41/lib/settings/_responsive.scss#L16
Should contain !default;: this variable can't be overwritten from vars - which is included first in the entry.

Rewrite every supple variable to CSS variable

Breakpoints cannot be overwritten from `settings/_responsive.scss`