🎨 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:
```scss
@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:
```scss
@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:
```scss
@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](./demo/style.scss).
- Using theme-creation utility:
```scss
@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.
```scss
@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
...
```
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
...
```
### Mixins
#### Vars and colors
The library includes some mixins that can be used to access the theme variables and colors
```scss
@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);
// dots instead of slashes can be used too
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.
```scss
@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.
```scss
@use '@lucas-labs/lui-micro/typo';
.my-div {
@include typo.typography('heading/h7');
}
```