samos

Samos is utility suite for SCSS and has a lot of opinioated and unopinionated helpers + defaults.

For mixins with multiple optional parameters, you can use named parameters. So for example, if you want to reset the last of the three parameters of the transition mixin, you can use:

@include transition(height, $will-change: false);

Reset + Base

Reset is an unopinionated global reset, that resets all stylings to be as neutral as possible.

Base is an opinionated base styling, that integrates with some of Becklyn’s tools and global classes.

@import "~samos/base";
@import "~samos/reset";

New in version 2.4.0: The base import was added in version 2.4.0.

Mixins

The following chapter lists all types of mixins that are included with samos. You can either include each file individually, or just all of them:

// in your helpers/_mixins.scss
@import "~samos/mixins";

Clearfix

clearfix

@include clearfix;

Includes the clearfix hack.

This element creates an ::after element, so don’t use it on elements that define their own ::after element.

Colors

shade

color: shade($color, $percentage);
parameters
nametypedescription
$colorColorThe color that should be shaded.
$percentageNumberPercentage between 0% and 100%.
return value
typedescription
ColorThe shaded color.

Shades the color (mixes it towards black).

tint

color: tint($color, $percentage);
parameters
nametypedescription
$colorColorThe color that should be tinted.
$percentageNumberPercentage between 0% and 100%.
return value
typedescription
ColorThe tinted color.

Tints the color (mixes it towards white).

Container

centered-container

@include centered-container($max-width, $min-margin);
parameters
nametypedescription
$max-widthNumberThe maximum width of the container
$min-marginNumberThe margin that is applied to the sides, if the viewport is smaller than the $max-width.

This mixin centers a container if the viewport is wider than a max width. If the screen is more narrow, it will have a margin on both sides to the edge of the viewport.

Content

content

@include content($margin);
parameters
nametypedescription
$marginNumberThe base margin.

The content mixin applies relative margins to every elements. It automatically styles

  • generic margins
  • margins related to headline classes (.h1 - .h6)
  • buttons (.button)
  • lists (ul and ol)

All these margins are relative to the base margin, you can provide to mixin. This ensures that there is consistent spacing in the content elements.

Fonts

responsive-font

@include responsive-font(3vw, 16px, 64px);
parameters
nametypedescription
$relative-sizeNumberThe relative size of the font (in vh / vw) unit.
$minNumberThe minimum font-size (in px).
$maxNumberThe maximum font-size (in px, optional).

Generates a responsive font size. The font size will scale with browser width (if using vw) or browser height (vh). You must define a minimum font size, so that the font never gets too small.

You can optionally also define a maximum font size.

emoji-fonts

@include emoji-fonts("Font Family 1", "Font Family 2");
parameters
nametypedescription
$custom-fonts...StringThe font families of the app, that should be used.

This mixin appends the different font families, that provide native support for emojis on all operating systems.

system-fonts

@include system-fonts("Font Family 1", "Font Family 2");
parameters
nametypedescription
$custom-fonts...StringThe font families of the app, that should be used.

This mixins appends the default font families for all operating systems, so that the fallback is as close to the native look as possible.

This mixin already includes emoji-fonts, so no need to add it yourself.

You should use this mixin on all global font family definitions.

import-fonts

New in version 2.2.0: This mixin was added in version 2.2.0.

@include import-fonts(
    $path-prefix,
    $font-family,
    $font-weights,
    $font-styles: (normal italic),
    $types: (woff2 woff)
);
parameters
nametypedescription
$path-prefixStringThe relative path from your (compiled) CSS file to the directory containing the font files.
$font-familyStringThe name of the font family.
$font-weightsMap<label, Number>The supported font-weights, as mapping from the label to the numeric weight.
$font-stylesNumber[]The supported font styles.
$typesLabel[]The supported font types.

This mixins generates the @font-face definitions for all supported fonts.

Example:

$font-weights: (light: 300, bold: 700);

@include import-fonts(
    "../font/neue-helvetica",
    "Neue Helvetica",
    $font-weights
);

Forms

text-inputs

@include text-blocks {
    @content;
}

This mixin targets all input + textarea elements except of radio buttons and checkboxes.

Deprecated since version 2.5.0: This mixin is deprecated, use inputs with explicit classes instead.

Interaction

on-interaction

New in version 2.4.0: This mixin was added in version 2.4.0.

@include on-interaction {
    @content;
}

Wraps the content in all typical interaction states (:hover, :focus and :active).

Media Queries

normalize-to-px

width: normalize-to-px($value);
parameters
nametypedescription
$valueSize

Normalizes a value to px, according to a base font-size of 10px. Supported units: px, rem.

on-max-width

@include on-max-width($max-width) {
    @content;
}
parameters
nametypedescription
$max-widthSize

Mixin to set a max-width mixin.

on-min-width

@include on-min-width($min-width) {
    @content;
}
parameters
nametypedescription
$min-widthSize

Mixin to set a min-width mixin.

Positioning

center-element

@include center-element;

Centers an element using position: absolute and transform.

center-children

@include center-children;

Centers all children using flexbox.

fullscreen

@include fullscreen;

Stretches an element to fill at least the whole screen (can be longer if the content is too long).

fill-parent

@include fill-parent;

Fills the parent element using position: absolute.

flex-fill-width

@include flex-fill-width;

Fills the remaining width of a flexbox container.

flex-fill-height

@include flex-fill-height;

Fills the remaining height of a flexbox container.

fixed-flex-width

@include fixed-flex-width($width: null);
parameters
nametypedescription
$widthSize|Null

Disables resizing of the flex element, and optionally sets it to a fixed size.

fixed-flex-height

@include fixed-flex-height($height: null);
parameters
nametypedescription
$heightSize|Null

Disables resizing of the flex element, and optionally sets it to a fixed size.

fixed-flex-item

@include fixed-flex-item($width: null);
parameters
nametypedescription
$widthSize|Null

Disables resizing of the flex element, and optionally sets it to a fixed size.

Deprecated since version 1.2.0: This mixin is a deprecated alias for fixed-flex-width. Use the non-deprecated mixin instead.

flex-equal-columns

New in version 2.3.0: This mixin was added in version 2.3.0.

@include flex-equal-columns;

If set on all children of a flexbox element, the children will have equal width.

Scroll

smooth-scroll

New in version 2.3.0: This mixin was added in version 2.3.0.

@include smooth-scroll;

This mixin enables smooth (= momentum) scrolling on mobile devices.

On desktop devices, this mixin will lead to an always visible scrollbar. If that isn’t desired, you should only apply it on small screens / media queries.

Sizing

aspect-ratio

New in version 2.4.0: This mixin was added in version 2.4.0.

@include aspect-ratio($width, $height);
parameters
nametypedescription
$widthNumberThe relative width
$heightNumberThe relative height

Uses the padding-bottom trick to set the aspect ratio of the element.

Example implementation of a fully responsive video container:

.video-container {
    // set the aspect ratio to 16:9
    @include aspect-ratio(16, 9);
    position: relative;

    .video-player {
        @include fill-parent;
    }
}

square

New in version 2.4.0: This mixin was added in version 2.4.0.

@include square($size);
parameters
nametypedescription
$sizeSize

Sets the width and height of an element to the same value.

SVG

color-svg

@include color-svg($color);
parameters
nametypedescription
$colorColor

Sets the styling as fill + stroke color, according to our predefined SVG classes.

inline-svg

New in version 2.4.0: This mixin was added in version 2.4.0.

background-image: inline-svg('<svg ...>...</svg>');
parameters
nametypedescription
$svgStringThe SVG content

URL-encodes the inline svg and returns it as a data url embedded in an url().

svg-child

New in version 2.4.0: This mixin was added in version 2.4.0.

@include svg-child;

Sets the default styling for all SVG children, namely display: block and width + height to 100%. This should be the default, as you can set the width + height on the container around the SVG. This is the most robust way to size inline SVGs.

Text

text-overflow

@include text-overflow;

This mixin disables text wrapping, cuts the text off and adds ellipsis at the end. Use it for single line texts that are external input, but only allow for a limited width.

Deprecated since version 2.5.0: Deprecated alias of text-overflow-ellipsis.

Transition

transition

@include transition(
    $properties,
    $duration: .15s,
    $easing: ease-in-out,
    $will-change: true
);
parameters
nametypedescription
$propertiesLabel[]The list of properties to transition.
$durationNumber
$easingLabel
$will-changeBooleanWhether to add the will-change declaration as well.

This mixin eases definitions of transitions. The default values are already optimized for all purposes, so try to stay with them (and use the values (especially duration and easing) consistency throughout your app).

Example:

@include transition(height width top);

// with custom duration:
@include transition(height width top, .5s);

Utilities

These are internally used functions, that possibly aren’t very useful outside of samos’ internals.

str-replace

$replacements: ("a": "b", "c": "d");
content: str-replace($some-variable, $replacements);
parameters
nametypedescription
$some-variableStringThe string where the occurrences should be replaced.
$replacementsMap<String,String>The map of search -> replacement.

Replaces all occurences of all search strings with their respective replacements.

url-encode

@include url-encode($string);
parameters
nametypedescription
$stringStringThe string that should be encoded.

URL-encodes the given string.

Visibility

hide-text

@include hide-text($absolute: false);
parameters
nametypedescription
$absoluteBooleanWhether to use relative (%) or absolute (vw) units.

This mixin hides text accessibly, so that it is still readable via screen readers.

text-overflow-ellipsis

@include text-overflow-ellipsis;

This mixin disables text wrapping, cuts the text off and adds ellipsis at the end. Use it for single line texts that are external input, but only allow for a limited width.