Variables

Asterix uses several kinds of variables. Some are scss variables used to provide data in one side and load your own values into the system on the other side. Others are css variables set to be used client-side.

Asterix's configuration is made of two parts.

$asterix-vars injects your own design system settings into Asterix ;

$asterix-conf configures the asterix's global settings. Check Configuration section for more details.

SCSS variables

Asterix uses a map variable called $asterix-vars wich contains all required and custom values.

It is used during sass compilation to write internal rules like responsive ones, but also to write css3 variables.

You can add, update or remove groups and properties.

Default settings

// /_configuration.scss - Default settings
$asterix-vars: (
  breakpoints: (
    xs: 480px,
    s: 768px,
    m: 1024px,
    l: 1200px,
  ),
  colors: (
    default: black,
  ),
  font-families: (
    default: 'sans-serif',
  ),
  gaps: (
    1: 0.5rem,
    2: 1rem,
    3: 1.5rem,
    4: 3rem,
  ),
  shapes: (
    default: 4px,
  ),
) !default;

Minimal configuration

In order to use builtins mixins, functions and layout system, you have to include those maps:

• breakpoints: ( key: value, key: value...)

• gaps: (key:value, key:value...)

Other maps are totally optional.

Retrieve $asterix-vars values

You can use the --var($group[, $property]) function to retrieve a specific value or an entire group.

// Retrieve the default font family
font-family: --var(font-families, default);

// Retrieve the whole gaps group
@each $key, $value in --var(gaps){
    // do something for each gap...
}

$group : the $asterix-vars group name to retrieve.

$property: when set, return the specific property value.

If the group doesn't exist, return an empy map ().

If the property doesn't exist, return unset.

Update $asterix-vars values

Always update between the asterix's main @import and the call of the asterix() mixin.

The mixin --update-vars($updatedVars) will merge the map you provide with the current settings.

// Your index.scss file
@import '@digivorefr/asterix-scss';

// Apply custom conf here.
@include --update-vars((
 // Use custom breakpoints names & value.
 breakpoints: (
  handset: 320px,
  tablet: 780px,
  desktop: 1280px,
 ),
 // Add a new shadow group.
 shadows: (
  default: none,
  light: 0px 5px 15px rgba(black, 0.1),
 ),
));

// Initializes Asterix
@include asterix();

// your code here...
button{
 box-shadow: --var(shadows, light);
}

Adding new groups will not write any additional css directly. You'll have to create your own specifiers or retrieve values where needed.

CSS Variables

Asterix loves css3 variables, as it uses them in its layout engine.

By using css3 variables instead of rendered scss variables, you will be able to update them client side, any time you want, at any scope you want, combinated with any css rule you want, including transitions and animations.

This can be a very powerful tool for handling, for instance, a dark mode.

Translate scss variables into css variables

Manually:

--mycustomcolor: --var(colors, default);

Or a bunch of maps at once with the --set-css-variables($variables) mixin:

body{
    // Create css variables version of asterix's colors.
    @include --set-css-variables((
        clr: --var(colors),
    ));
    
    // Then use css version instead of scss version (--var(colors,default))
    color: var(--clr-default);
}

Generated css3 variables names follow a --[groupName]-[valueName] pattern.

Because we need verbose names in sass and short ones in css, you have to manually set a css group name for each scss variables group. In the example above, the var(--colors) values will be called --clr-[valueName] in css.

You can expose variables in any scope.

About colors

When translating a sass color into a css variables, its value cannot normally be used into rgba() css rules. Here's a basic example of the issue:

// set scss variables
$red: #FF0000;

// translate it to css variable
--red: $red;

// then use a rgba with css variable
background: rgba(var(--red), 0.3);
// Outputs: rgba(#ff0000, 0.3) - Will not work

--set-css-variables will automatically detect any color provided and will create two css variables for each of them, the first containing the inital value and the second filled with the sass computed rgb value.

// set scss variable
$red: #FF0000;

// translate it to css variable
@include --set-css-variables((colors:(red:$red)));
// --colors-red is set to #FF0000,
// --colors-red-rgb is set to 255,0,0

// then use the rgb css version for rgba() css
background: rgba(var(--colors-red-rgb, 0.3);

Core css variables

Asterix is also using a few css variables for its layout engine.

While you should never have to deal with them, it is still useful to understand how Asterix works in its core.

Internal variables

  // Number of columns set in a layout scope.
  --columns: 1;
  // Gaps between columns and rows set in a layout scope.
  --hgap: unset;
  --vgap: unset;
  // Number of columns spaning for a layout item.
  --span: 1;
  // Layout properties.
  --flow: unset;
  --display: unset;
  --justify-content: unset;
  --align-items: unset;
  --align-self: unset;
// Flex specific properties.
  --wrap: unset;
  --direction: unset;
  --flex: none;

Logic

Basically, declaring an attribute will set to some properties some css variables. Values provided to the attribute will set the css variables values.

Here is a minimal example :

// Initialize a css variable, with no value.
--display: unset;

// Using data-layout will set css properties with css variables.
[data-layout]{
    display: var(--display);
}

// Attribute values will set some css variables
[data-layout*="--flex"]{
    --display: flex;
}

With this approach, the core is writing a very few code in the loops used to render columns, gap and breakpoints, and a bit more in attribute global selector. This way, code can be extended at a low byte cost.

// CSS variables initialization
--display: unset;
--justify-content: unset;

// Attribute styling declaration.
[data-layout]{
    display: var(--display);
    justify-content: var(--justify-content);
}

// Attribute specifiers.
[data-layout*="--flex"]{
    --display: flex;
}
[data-layout*="--grid"]{
    --display: grid;
}
[data-layout*="--justify-stretch"]{
    --justify-content: stretch;
}
[data-layout*="--justify-start"]{
    --justify-content: flex-start;
}
[data-layout*="--justify-center"]{
    --justify-content: center;
}
[data-layout*="--justify-end"]{
    --justify-content: flex-end;
}
...

Finally, by using css variables, the asterix's code is non-invasive as it can be manually updated in any scope level, without struggling with inheritance.

.customized-block{
    // Apply data-layout's variables and porperties.
    @include --extends(('[data-layout]'));
    // And update only one value.
    --justify-content: space-between;
}