Attributes & specifiers

Asterix relies in a few attributes to work.

Attributes are filled with specifiers to enable related css rules. They can be chained.

<div data-layout="--grid--items-center" data-cols="--2--l4" data-gap="--2">
    <div>Items</div>
    <div>Items</div>
    <div>Items</div>
    <div>Items</div>
    <div data-col="--2--l4">Fullwidth items</div>
</div>

Asterix provides a bunch of specifiers.

Specifiers can be added anywhere in your code. They can be set globally, locally and responsively.

When a specifier is responsive, you can use it combined with any breakpoint registered into Asterix. Just add the breakpoint key to the specifier after the -- chaining string.

For example, --mgrid will only set a --grid context for screen with a higher width than the m breakpoint value.

Built-in attributes and specifiers

All builtins specifiers are responsive

[data-layout]

Set a grid or a flex context to the element and handle positioning rules.

<div data-layout="--flex--justify-space-between">...</div>

Modifiers

--auto

--block

--flex

--grid

--none

--items-center

--items-end

--items-start

--items-stretch

--justify-center

--justify-end

--justify-space-between

--justify-start

--justify-stretch

--self-center

--self-end

--self-start

--self-stretch

[data-flex]

Handles flex-only properties, like flex-wrap.

<div data-layout="--flex" data-flex="--wrap">...</div>

Modifiers

--wrap

--nowrap

--row

--column

--none

--auto

[data-cols]

Set the columns number for a grid context

Specifiers

Loops on $asterix-conf grid-columns-number parameter and build a specifier for each number.

<div data-layout="--grid" data-cols="--2--m3--l4"></div>

[data-col]

Set the element's column spaning

Specifiers

Loops on $asterix-conf grid-columns-number parameter and build a specifier for each number.

<div data-layout="--grid" cols="--2">
    <div>item</div>
    <div>item</div>
    <div data-col="--2">Fullwidth item</div>
</div>

[data-gap], [data-hgap], [data-vgap]

Set gaps between columns, rows and flex children.

Specifiers

Loops on asterix-vars gaps group and build a specifier for each value.

<div data-layout="--grid" cols="--2" gap="--3">
    <div>item</div>
    <div>item</div>
</div>
<!-- Or -->
<div data-layout="--flex" gap="--3">
    <div>item</div>
    <div>item</div>
</div>

hgap and vgap are working exactly the same way, except they only set horizontal gap for hgap (between columns) and vertical gap for vgap (between rows) separately.

[data-spe]

Set and use your own specifiers

Adding a specifier

You can use the --spe($name[, $responsively: false, $attribute: data-spe]) mixin.

By default, all custom specifiers are attached to the [data-spe] html attribute.

Let's say you want to create a button design system.

Implementing buttons variations with --spe() provides a reliable pattern allowing unlimited chaining. This is perfect for extending a basic design system item.

It could start like this:

.btn{
    // Component internal css variables.
    --bg: transparent;
    --txt: var(--clr-light);
    --size: 1rem;
    
    // Properties.
    color: var(--txt);
    padding: 0.33em 1em;
    font-size: var(--size);
    background-color: var(--bg);
    transition: all 0.1s ease-in-out;
    
    // Specifiers.
    @include --spe(primary){
        --bg: var(--clr-primary);
        --border: var(--clr-primary);
    }
    
    @include --spe(large, true){
        --size: 1.3rem;
    }
    
    //...
}

<button class="btn">Defaults</button>
<button class="btn" data-spe="--primary">Primary</button>
<button class="btn" data-spe="--primary--large">Primary large</button>
<button class="btn" data-spe="--primary--mlarge">Responsive</button>

Optional parameters

$responsively

default: false

When set to true, asterix will add rules for each breakpoint value.

Responsive specifier naming pattern is --[breakpoint key][specifier name]. For example, a flex context starting at m will be written --mflex.

$attribute

default: data-spe

Set a different attribute used to call this specifier. When set to class, you are therefore able to call the specifier inside the class html attribute : <div class="--specifier"></div>

$local

default: true

Indicate if the required specifier has to be exclusive to the current scope or if it can be used anywhere in children elements.

body{
  // Body only specifier
  @include --spe(specifier, $local:true){...}
  // body[data-spe*="--specifier"]{...}
  
  // Specifier available in all body children
  @include --spe(specifier2, $local:false){...}
  // body [data-spe*="--specifier2"]{...}
}

When creating a top-level specifier, you'll have to set $local to false, so it does not use a parent selector.

// Generate [data-spe*="--text-center"] selector.
@include --spe(txt-center, $local:true){
    text-align:center;
}
body{
    //...
}

Create a new attribute

You design system will probably need extra values, and you want to be able to use them responsively on the HTML side.

Let's say you want to implement a basic design-system buttons layout.

First step is to implement the basic button styling. By using css variables internally, we make it simpler to extend, but you can perfectly use sass variables... Write your own rules !

[data-bt] {
  // Set CSS variables with defaults.
  --color: var(--clr-default);
  --font-size: 1rem;
  --background: var(--clr-light);
  --background-on: var(--clr-background);

  // Default button style.
  color: var(--color);
  border: none;
  outline: none;
  display: block;
  cursor: pointer;
  // Playing with em allow padding to fit button's font-size
  padding: 0.5em 1em;
  position: relative;
  font-size: var(--font-size);
  max-width: 100%;
  box-shadow: 0px 0px 0px var(--background);
  transition: all 125ms ease-in-out;
  font-weight: bold;
  white-space: nowrap;
  border-radius: 3px;
  text-overflow: ellipsis;
  letter-spacing: -0.1px;
  text-decoration: none;
  background-color: var(--background);

  &:visited {
    color: var(--color);
  }

  &:hover {
    transform: translateX(-2px) translateY(-2px);
    box-shadow: 4px 4px 0px var(--background);
    transition-duration: 70ms;
    background-color: var(--background-on);
  }
}

This makes any HTML element having data-btn as attribute a button

<button data-bt>Button</button>
<a data-bt>Link as a button</a>
<div data-bt>Div as a button (don't to that)</div>

Then, you need to extend from this basic layout to make your declinals:

// Specifiers
@include --spe(primary, $attribute: data-bt, $local: false) {
  --color: var(--clr-light);
  --background: var(--clr-primary);
  --background-on: var(--clr-primary-on);
}

@include --spe(secondary, $attribute: data-bt, $local: false) {
  --color: var(--clr-light);
  --background: var(--clr-secondary);
  --background-on: var(--clr-secondary-on);
}

@include --spe(large, $attribute: data-bt, $local: false) {
  --font-size: 1.3rem;
}

@include --spe(small, $attribute: data-bt, $local: false) {
  --font-size: 0.8rem;
}

@include --spe(disabled, $attribute: data-bt, $local: false) {
  opacity: 0.3;
  pointer-events: none;
}

Notice the use of $attribute and $local parameters into the --spe mixin.

They are mandatory to create a top level specifier. More info about --spe().

And you'll have on the html side plenty specifiers available for setting easily your buttons:

<a data-bt="--small" type="button">Button</a>
<a data-bt="--primary--small" type="button">Button</a>
<a data-bt="--secondary--small" type="button">Button</a>
<button data-bt type="button">Button</button>
<button data-bt="--primary" type="button">Button</button>
<button data-bt="--secondary" type="button">Button</button>
<button data-bt="--disabled" type="button">Button</button>
<button data-bt="--primary--disabled" type="button">Button</button>
<button data-bt="--secondary--disabled" type="button">Button</button>
<button data-bt="--large" type="button">Button</button>
<button data-bt="--primary--large" type="button">Button</button>
<button data-bt="--secondary--large" type="button">Button</button>

Buttons declinals