Stylament 0.23.2

CSS Custom Properties

This layer defines the system’s global (assigned to :root) CSS custom properties. As a CSS-specific design token implementation they are generated from the global configuration and are being applied in the higher layers of the system.

Prop I/O: Read and Write Properties

On CSS level it can be helpful to adhere to naming conventions for custom properties in order to keep a better overview of their respective origin and purpose. Stylament allows you to define a custom prefix to brand all its system properties and provides shortcuts to reference properties in a prefix-agnostic way.

$-prefix [private]

scss 
$-prefix: "s-" !default;

Configurable prefix for system CSS variables.

Stylament defines a prefix for its system (hence s-) custom properties by default. This can be replaced by any valid identifier part when @use-ing this file:

Examples

scss Add custom prefix to all system CSS custom properties 
@use "stylament/css/axioms/properties/io" with ($-prefix: "myBrand-");
scss Keep all system CSS custom properties un-prefixed 
@use "stylament/css/axioms/properties/io" with ($-prefix: "");
scss Use a fancy prefix 
@use "stylament/css/axioms/properties/io" with ($-prefix: "💅");

$🌱

scss 
$🌱: --#{$-prefix};

Shortcut for system CSS variable prefix.

Related

Credits: Pico CSS [external]

@function svar()

Shortcut for system CSS variable reference.

Parameters & Return

$name: (string)

The un-prefixed variable name.

$fallback: (string)

The custom property’s fallback value. Same as in var().

@return (string)

A standard CSS var() reference.

Mixins for Property Generation

@mixin literal-properties()

List CSS custom properties.

Parameters & Output

$group: (String)

Property group name.

$properties: (Map)

Map of properties with simple literal values.

{CSS output} (code block)

A list of --<prefix><group>-* custom properties with their respective values.

Used By

@mixin configured-properties()

@mixin mapped-properties()

Map CSS custom properties via a given function.

Parameters & Output

$group: (String)

Property group name.

$mapping: (Map)

Mapping configuration.

{CSS output} (code block)

A list of --<prefix><group>-* custom properties with their respective calculated values.

Requires

@function map-function()

Used By

@mixin configured-properties()

@mixin logical-properties()

Map logical to basic CSS custom properties.

Parameters & Output

$group: (String)

Property group name.

$properties: (Map)

Map of logical properties.

{CSS output} (code block)

A list of --<prefix><group>-* custom properties referring to others.

Requires

@function svar()

Used By

@mixin configured-properties()

@mixin configured-properties()

Generate all configured CSS custom properties.

Parameters & Output

$group: (String)

Property group name.

$conf: (Map)

Configuration map for this set of properties.

{CSS output} (code block)

A list of mapped, literal, and logical --<prefix><group>-* custom properties.

Requires

@mixin mapped-properties()

@mixin literal-properties()

@mixin logical-properties()

@function svar()

Used By

@mixin -traverse-config() [private]

Color Palettes

Dynamically Generated CSS Custom Properties

By default Stylament generates CSS custom properties from the configuration map. This is done for every property map that is not explicitly excluded from and contains at least one of the keys literal, logical, or mapped.

$exclude (List)

scss 
$exclude: () !default;

Config paths to exclude from property generation. The dash (-) is used as path separator.

Used By

@mixin -traverse-config() [private]

$root-trim (Number)

scss 
$root-trim: 2 !default;

Number of top-level token path levels to exclude from property names. By default the root level and the first categorization level (“layout”, “typography”, etc.) are skipped.

@mixin -traverse-config() [private]

Traverse the configuration tree recursively to generate properties.

Parameters

$config: (Map)

The configuration (sub-)tree to traverse.

$group: (String)

The token group name for the current subtree.

$trim: (Number)

The number of token path levels to exclude from property names.

Requires

$exclude (List)

@mixin configured-properties()

Requires

$merged (Map)

Specifically Defined CSS Custom Properties

Coloring

Coloring Mixins

@mixin palette()

Generate a color palette for a given hue.

Parameters & Output

$name: (String)

The color name.

$hue: (Number)

The color hue (of HSL).

$s-curve: (List)

The polynomial coefficients defining the curve described by cartesian coordinates of palette step and saturation (of HSL).

$l-curve: (List)

The polynomial coefficients defining the curve described by cartesian coordinates of palette step and lightness (of HSL).

$sl-curve: (List)

The control points defining a cubic Bézier in a cartesian coordinate system of saturation and lightness (of HSL). If this is definded the other two curves are ignored.

$range: (Map)

Start, end, and step-size of the palette.

$group: (String)

Property group name.

$suffix: (Map)

Property name suffix (factor: , inverse: ).

{CSS output} (code block)

A list of --<prefix><group>-* custom properties containing the color values of the palette:

--s-color-red-100: hsl(0deg, 100%, 95%);
--s-color-red-300: hsl(0deg, 95%, 75%);
--s-color-red-500: hsl(0deg, 76%, 57%);
--s-color-red-700: hsl(0deg, 61%, 48%);
--s-color-red-900: hsl(0deg, 50%, 29%);

Requires

@function cubic-2d()

@function polynomial()

Used By

Color Palettes

Color Palettes

scss 
:root {
  @each $name, $pal in map.get(cfg.$merged, coloring, palettes) {
    @include coloring.palette($name, $pal...);
  }
}

Requires

$merged (Map)

@mixin palette()

@mixin configured-properties()

Layout

$sizes@container (Map)

scss 
$sizes: config.map-config(map.get(cfg.$merged, layout, container));

Container sizes for preprocessing.

We need this preprocessor variable map because the corresponding CSS variables cannot be used in media query declarations.

Requires

$merged (Map)

Typography

Line Heights

scss 
:root {
  $scale: map.get(cfg.$merged, typography, font, size);
  $line: map.get(cfg.$merged, typography, line);
  $rlh: map.get($line, rlh);

  #{$🌱}line-root: #{map.get($line, root)};
  #{$🌱}line-root-abs: #{$rlh};

  @for $i
    from map.get($scale, mapped, range, start)
    through map.get($scale, mapped, range, end)
  {
    $font-size: meta.call-conditional(
      map.get($scale, mapped, function),
      $i,
      map.get($scale, mapped, params)
    );
    #{$🌱}line-#{$i}: #{rhythm.grid-line(
        $font-size,
        $rlh,
        map.get($line, min),
        map.get($line, sub)
      )};
  }
}

Line heights supporting the vertical rhythm at every step of the scale.

Requires

$merged (Map)