infrastructure/gitea-custom
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 📝 readme

Browse Source
This commit is contained in:
Lucas Colombo 2023-07-02 19:47:07 -03:00
parent a033ccd313
commit 1b9f97cf37
4 changed files with 29 additions and 240 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.vscode/settings.json vendored
View File

@ -18,7 +18,7 @@
".prettierignore": true, ".prettierignore": true,
// 📝 readmes // 📝 readmes
"**/**/README.md": true, // "**/**/README.md": true,
"LICENSE": true, "LICENSE": true,
// 🗑️ // 🗑️

265
README.md
View File

@ -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"> *Theme for `lucaslabs` internal gitea server.*
<strong>
🎨 <code>lucas-labs/lui-micro</code> > A lightweight scss library for building themed UIs 🤏.
</strong>
</p>
<br/> ## `dark`
<br/>
## 📄 Documentation ![dark theme](figs/dark.png)
### 📦 Install ## `light`
Download with NPM/PNPM/YARN: ![light theme](figs/light.png)
* `pnpm i @lucas-labs/lui-micro` ## Usage
* `npm i @lucas-labs/lui-micro`
* `yarn add @lucas-labs/lui-micro`
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 ```ini
@use '~@lucas-labs/lui-micro' as lui; [ui]
@include lui.init(); THEMES=...,dark,light
DEFAULT_THEME=dark # optional
``` ```
### ⚙️ Options > 💡 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.
The `lui.init` mixin can receive several params:
* `$theme`: default theme configuration map 4. Restart `gitea`.
* `$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) > 🗒️ **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 ## Dev
To set the breakpoints, you need to pass a map to the $breakpoints parameter in the `lui.init` mixin:
```scss ### build
@use '~@lucas-labs/lui-micro' as lui; ```bash
@include lui.init( $ npm install
// this is also the default breakpoint map, $ npm run build
// 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');
}
``` ```

BIN
figs/dark.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 194 KiB

BIN
figs/light.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 171 KiB