lui-micro: A SCSS repository from lucas-labs

🎨 lucas-labs/lui-micro > A lightweight scss library for building themed UIs 🤏.

📄 Documentation

📦 Install

Download with NPM/PNPM/YARN:

pnpm i @lucas-labs/lui-micro
npm i @lucas-labs/lui-micro
yarn add @lucas-labs/lui-micro

Then import it in your .scss file:

@use '~@lucas-labs/lui-micro' as lui;
@include lui.init();

⚙️ Options

The lui.init mixin can receive several params:

$theme: default theme configuration map
$breakpoints : media-breakpoints for breakpoint utilities.
$options: map with options for the library. It can have the following keys:
- reboot: boolean. If true, the reboot will be applied. Default: true.
- basic: boolean. If true, the basic styles will be applied. Default: true.
- theme: boolean. If true, the theme will be applied. Default: true.
- merge-theme-with-prebuilt: boolean. If true, the theme will be merged with the default theme. If you choose not to merge it, you will need to provide all the necesary variables. Default: true.
- color-utilities: boolean. If true, color utilities will be created. Default: false.
- typography-utilities: boolean. If true, typography utilities will be created. Default: false.
- fg-var-name: string. Indicates the name of the variable that will be used in the theme config to set the foreground color. Default: text
- bg-var-name: string. Indicates the name of the variable that will be used in the theme config to set the background color. Default: background

💡 All parameters are optional! (defaults will be used)

🎨 Theme / Customization

You can create any number of themes, but one of them needs to be the default theme. Normally, the default theame is created when calling lui.init.

Breakpoints

To set the breakpoints, you need to pass a map to the $breakpoints parameter in the lui.init mixin:

@use '~@lucas-labs/lui-micro' as lui;
@include lui.init(
    // this is also the default breakpoint map, 
    // so if you don't pass anything, this will be used
    $breakpoints: (
        xs: 0px,
        sm: 576px,
        md: 768px,
        lg: 992px,
        xl: 1200px,
    )
);

Setting default theme

You can set a default theme by passing a map object as a parameter to the lui.init mixin or by using the theme creation utility.

Using init mixin example:

@use '~@lucas-labs/lui-micro' as lui;
@include lui.init(
    $theme: (
        colors: (
            ...
        ),
        variables: (
            ...
        ),
        typography: (
            ...
        ),
    )
);

💡 You can see an example of a more complete theme config here.

Using theme-creation utility:

@use '~@lucas-labs/lui-micro' as lui;
@use '~@lucas-labs/lui-micro/theme' as theme;

@include lui.init();
@include theme.create-theme(
    $theme: (
        ...
        colors: (
            background: ...,
            text: ...,
            primary: ...,

            // nested maps are allowed (also allowed for variables)
            grouped: (
                a-nested-color: #fff,
                even-more-nested: (
                    ...
                ),
            )
            ...
        ),
        ...
    )
    $as-default: true // set as-default as true, so lui defaults to this theme
                      // this theme will be also used as a base for when you 
                      // create a new theme
);

Setting default theme

By using the create-theme utility you can also create themes as non-default themes. This means you'll be able to change between themes at runtime. This is possible because themes are made only of css variables.

@use '~@lucas-labs/lui-micro' as lui;
@use '~@lucas-labs/lui-micro/core' as core;

// setting a deault theme called "light"
@include lui.init(
    $theme: (
        name: "light",
        ...
    )
);

// creating another theme called "dark" that will not be default
@include core.create-theme(
    $theme: (
        name: "dark"
        ...
    )
    // don't pass $as-default here, or pass it as "false"
);

Now to change themes at runtime, you'll need to set an argument in your tag:

<html theme="dark"> 
...
</html>

To change it back to de default, either you set the theme attribute to its name, or remove the theme attribute from the html tag (it will default to the default theme):

<html theme="light"> 
...
</html>

Mixins

Vars and colors

The library includes some mixins that can be used to access the theme variables and colors

@use '@lucas-labs/lui-micro/color';
@use '@lucas-labs/lui-micro/var';

.my-div {
    background-color: color.get('primary'); // background-color: var(--c-primary);
    color: color.get('primary', 'rgb'); // color: var(--c-primary-rgb);

    // it works with nested colors too
    // provided you defined your nested theme-color as 
    // colors: (
    //     my: (
    //         nested: (
    //             color: #000,
    //         )    
    //     )
    // )
    border-color: color.get('my/nested/color'); // border-color: var(--c-my_nested_color);

    // get a theme variable
    border-radius: var.get('font-family'); // border-radius: var(--v-font-family);
    
    // as with colors, it works with nested variables too
    // provided you defined your nested variable as
    // variables: (
    //     my: (
    //         nested: (
    //             variable: 10px,
    //         )
    //     )
    // )
    border-radius: var.get('my/nested/variable'); // border-radius: var(--v-my_nested_variable);
}

Breakpoints

The library includes several mixins to help you create responsive layouts and styles.

@use '@lucas-labs/lui-micro/bp';

// @use '@lucas-labs/lui-micro/bp' with (
//     $breakpoints: ( sm: 576px, ... )
// );

.my-div {
    // create a breakpoint
    @include bp.up('sm') {
        // styles for sm and up
    }

    @include bp.down('sm') {
        // styles for sm and down
    }

    @include bp.only('sm') {
        // styles for sm only
    }

    @include bp.between('sm', 'md') {
        // styles for sm and md
    }

    @include bp.not('sm') {
        // styles for everything but sm
    }

}

Typographies

The library includes a mixin to get typography styles from the theme.

@use '@lucas-labs/lui-micro/typo';

.my-div {
    @include typo.typography('heading/h7');
}