docs: 📝 readme
This commit is contained in:
Lucas Colombo
parent
a033ccd313
commit
1b9f97cf37
2
.vscode/settings.json
vendored
2
.vscode/settings.json
vendored
@ -18,7 +18,7 @@
|
||||
".prettierignore": true,
|
||||
|
||||
// 📝 readmes
|
||||
"**/**/README.md": true,
|
||||
// "**/**/README.md": true,
|
||||
"LICENSE": true,
|
||||
|
||||
// 🗑️
|
||||
|
||||
267
README.md
267
README.md
@ -1,255 +1,44 @@
|
||||
<p align="center"><img src="https://raw.githubusercontent.com/lucas-labs/lui-micro/HEAD/logo.svg" height="80"></p>
|
||||
<h1 align="center">
|
||||
<code>lucaslabs</code> › <a href="https://gitea.io">Gitea</a> theme
|
||||
</h1>
|
||||
|
||||
<p align="center">
|
||||
<strong>
|
||||
🎨 <code>lucas-labs/lui-micro</code> > A lightweight scss library for building themed UIs 🤏.
|
||||
</strong>
|
||||
</p>
|
||||
*Theme for `lucaslabs` internal gitea server.*
|
||||
|
||||
<br/>
|
||||
<br/>
|
||||
## `dark`
|
||||
|
||||
## 📄 Documentation
|
||||
|
||||
|
||||
### 📦 Install
|
||||
## `light`
|
||||
|
||||
Download with NPM/PNPM/YARN:
|
||||
|
||||
|
||||
* `pnpm i @lucas-labs/lui-micro`
|
||||
* `npm i @lucas-labs/lui-micro`
|
||||
* `yarn add @lucas-labs/lui-micro`
|
||||
## Usage
|
||||
|
||||
Then import it in your `.scss` file:
|
||||
1. Clone this repo
|
||||
2. Place the files in the `dist` folder in your `$GITEA_CUSTOM` directory.
|
||||
3. Append the themes in your `app.ini` file:
|
||||
|
||||
```scss
|
||||
@use '~@lucas-labs/lui-micro' as lui;
|
||||
@include lui.init();
|
||||
```ini
|
||||
[ui]
|
||||
THEMES=...,dark,light
|
||||
DEFAULT_THEME=dark # optional
|
||||
```
|
||||
|
||||
### ⚙️ Options
|
||||
The `lui.init` mixin can receive several params:
|
||||
> 💡 You can change the names of the themes by changing the name of the theme files in `public/css/theme-{name}.css` and in the `app.ini` file, accordingly.
|
||||
|
||||
* `$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`
|
||||
4. Restart `gitea`.
|
||||
|
||||
> 💡 All parameters are optional! (defaults will be used)
|
||||
> 🗒️ **Note**\
|
||||
> Works with `gitea` version `v1.20`.
|
||||
|
||||
### 🎨 Theme / Customization
|
||||
## Credits
|
||||
|
||||
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`.
|
||||
- [`catppuccin/gitea`](https://github.com/catppuccin/gitea), these themes are based on them.
|
||||
|
||||
#### Breakpoints
|
||||
To set the breakpoints, you need to pass a map to the $breakpoints parameter in the `lui.init` mixin:
|
||||
## Dev
|
||||
|
||||
```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 <html> tag:
|
||||
|
||||
```html
|
||||
<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
|
||||
<html theme="light">
|
||||
...
|
||||
</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');
|
||||
}
|
||||
```
|
||||
### build
|
||||
```bash
|
||||
$ npm install
|
||||
$ npm run build
|
||||
```
|
||||
BIN
figs/dark.png
Normal file
BIN
figs/dark.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 194 KiB |
BIN
figs/light.png
Normal file
BIN
figs/light.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 171 KiB |
Loading…
x
Reference in New Issue
Block a user