| :warning: | PRE-ALPHA | |-----------|:----------|

StandardKit Styles

SCSS Framework for the StandardKit Design & Component System

Principles

The idea of StandardKit is based on a collection of thoughts and issues with the state of SCSS Frameworks, Component Libraries & UI Kits. To name a few:

• It should be easy to use
• It should look good by default
• It should take into account accessibility & other web-standards
• I want to customize variables like colors, margins or corners
• I want to add my own custom flavors
• I should be able to easily override anything (without !important)
• I should be able to extend it and add my own behaviour
• I should be able to solve problems in my or my teams way of working
• It should guide me in the right direction
• I do not want to repeat myself
• HTML should be clean & simple to use
• I don't want any boilerplate code, I just want exactly what I need in my bundle
• I want good documentation where I can find specifically what EVERYTHING does
• I should be able to quickly build something with it
• Different parts of the framework should work as they do elsewhere

All of this is meant to put the developer first. You should be able to quickly & easily design & build quality applications for your users.

This makes StandardKit a great fit for Rapid Prototyping but also prepared for expansion.

These ideas distill into the four main principles to which we validate our framework.

Defaults & Standards

Everything should look & work simply by default. It uses standards to give you multiple way of doing things while remaining consistent & straight-forward.

Easy way to style a button:

<button class="button">
    Click
</button>

An example of standards: Modifiers work the same across components.

<!--A button with modified margin-->
<button class="button margin--xl">
    Click
</button>

<!--An alert with modified padding-->
<div class="alert padding--xl">
    Message
</div>

Just an example, it is possible with configuration to set padding--xl for all alerts by default

Multi-Path Solutions

There are no one-way solutions. Instead, we provide utilities for different strategies.

If you find a strategy, perspective or solution that is missing, let us know!

Cascading Configuration

Everything should be configurable and cascade on multiple levels.

// configuration.scss
$components: (
  button: (
    default-color: primary,
    save: (default-color: success, default-fill: outline),
    cancel: (extend: save, default-color: error)
  )
);

<!--page.html-->
<button class="button">Button</button>
<button class="button--save">Save</button>
<button class="button--cancel">Cancel</button>

Here, the cancel button extends and overwrites the save button, which overwrite the default button.

Built-to-Extend

Everything should be easily extendable, we even expect you to add your own customizations.

// Adding a custom color
$colors: (
  custom: #abcdef
);

// Extending the button and adding behaviour
@extend .button--custom
{
  border-radius: 1rem;
  transition: background-color 2s ease-out;
}

Modifiers, Flavors, Components & Types

Modifiers

A modifier is a characteristic that can be modified. Something that you can change. Examples are:

• color
• fill
• margin

Example selection, please check the documentation website for a full list.

All modifiers work the same from the outside. For example to apply a different padding to a component, you would say:

<div class="padding--xl">
    A div with padding 'xl'
</div>

As you can probably tell, we use two hyphens (BEM-style) to select an alternative.

Flavors

Modifiers can have a number of flavors defined. For example:

$color: (
  error: red,
  warning: orange,
  info: blue,
  success: green
);

This is a simplified example. Check the theme for the actual values.

Custom Flavors

There are two types of modifiers; static & configurable.

Static Modifiers

An example of a static modifier is:

• case (lowercase, uppercase capitalized).

Since there is a limited / hardcoded number of options here, it doesn't make sense to expand.

Configurable Modifiers

Most modifiers are configurable. This means that you can add your own flavors, as well as override pre-defined ones. For example:

// Override the error color to 'purple' and adding our own 'custom' color
$colors: (
  error: purple,
  custom: hotpink
);

Now you could use this the following way:

<div class="color--custom">
    My custom colored div
</div>

Components

A component (e.g. alert or button) usually has a number of modifiers available. For instance, let's look at the button component.

<button class="button color--primary margin--xl padding--xs">
    Click me
</button>

Next to the modifiers that you can see are being set here, like padding--xs, the component also has a number of default modifiers. As you might have expected from StandardKit, you can override / configure this. For example:

$components: (
  button: (
    default-color: primary,
    default-margin: xl,
    default-padding: xs
  )
);

Now, you can just use:

<button class="button">
    I am a configured button
</button>

This becomes useful when you have more buttons scattered through-out your application.

Types

Most of the time, applications tend to have multiple definitions of a button. For example, we might have a cta-button, a save-button and a cancel-button. Using just the component configuration, you can only optimize for one situation. With types, we don't have to.

Types are a compound component definition that combines multiple modifiers on top of the default modifiers

For example:

$components: (
  button: (
    default-color: primary,
    cta: (default-color: custom, default-margin: xl),
    save: (default-padding: xs),
    cancel: (default-color: error)
  )
);

To now use these three buttons, I can just:

<button class="button--cta">Call-to-Action</button>

<button class="button--save">Save</button>

<button class="button--cancel">Cancel</button>

Very simple yet powerful.

Special Cases

A couple of modifiers are special.

Color & Fill Combo

This is relevant because color depends on fill. For instance, with a fill: 'fill' the text color is the contrast color and the background is the main color.
See Color Generation for more information about colors and their (generated) subsets.

Complex Modifiers

Some modifiers can be configured a little bit more than others. For example:

// Colors
$colors: (
  primary: #fff,
  secondary: (main: #fff, complement: #f00, contrast: #000, complement-contrast: #0ff)
);

// Elevation
$elevation: (
  high: 20,
  custom: () // TODO : Implement 
);

In this case all values are optional, but you need at least main or complement to generate the others.

Breakpoints

Breakpoints are configurable modifiers, you can add or change them to your liking. By default it's using em but feel free to change to what you want.

However, sometimes you want to change the behaviour of other modifiers based on the viewport. For example:

$margins: (
  custom: (start: square, s: 3rem, l: round)
)

As you can see, something weird is going on. I'm using round which is one of the flavors, but I'm also specifying 3rem, an actual value. This always looks for the flavor first. So it would be unwise to call a flavor by one of the values.

StandardKit uses the start keyword to distinguish if this is a breakpoint-scenario. This is only needed in case of complex modifiers, like color or elevation.

This means that StandardKit is 'mobile-first'

Configuration

Theme Options

A list of the default theme options.

$options: (
  prefer-dark-colors: false, 
  exclude-default-theme-selector: false,
  contrast-threshold: 42%,
  contrast-value-percentage: 2%,
  complement-value-percentage: 7%,
  brightness-weights: (
    red: .229,
    green: .576,
    blue: .119
  ),
  include-fonts : true or false, // default: true
  merge-modifiers: 'replace' or 'merge', // default: merge
  modifier-sets: 'none' or 'minimal' or 'basic' or 'all' // default: all
)

Modifier Options

$configuration: (
  color-options: (
    set: 'none' or 'minimal' or 'basic' or 'all',
    exclude: [],
    include: [],
    merge: 'merge' or 'replace'
  )
)

Modifiers

Below is a list of all modifiers and their default flavors. The values in the format are placeholders, check the theme reference for actual values.

Configurable Modifiers

Complex ( e.g. #fff or (main: #fff, contrast: #000) )

• color
• fill
• elevation
• breakpoint
• animation

Dynamic ( value based e.g. 1rem )

• corner
• border
• font
• font-import
• margin
• padding
• size
• width

State ( combines other modifiers on state e.g. different fill on hover )

• active
• disabled
• focus
• hover

Static

For these modifiers you can not add your own flavors. However, you can of course still in- or exclude certain sets or individual standard flavors.

• alignment
• case
• highlight
• position
• vertical-alignment

Complex Modifiers

| Modifier | Format | Description | |---|---|---|  |                                                 |  color | #fff, red (main: #fff,complement: #fff,contrast: #fff,complement-contrast: #fff) | A single color or a color map. all values of the map are optional, but it needs at least a main or a complement to generate the rest. fill | (text: main,border: contrast,background: complement) | The way color is used to fill elements. elevation |

Components

• alert
• button