https://github.com/komplettio/themed
All you need for SCSS-based theming
https://github.com/komplettio/themed
css-themes scss theming
Last synced: 11 months ago
JSON representation
All you need for SCSS-based theming
- Host: GitHub
- URL: https://github.com/komplettio/themed
- Owner: komplettio
- Created: 2025-01-29T19:08:21.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2025-02-11T12:18:56.000Z (11 months ago)
- Last Synced: 2025-02-11T12:27:54.614Z (11 months ago)
- Topics: css-themes, scss, theming
- Language: SCSS
- Homepage: https://themed.komplett.io
- Size: 399 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
@komplett/themed: SCSS-native themes made simple
`@komplett/themed` is a customizable SCSS utility to add theming to your website as easily and safely as possible. It also offers utility methods for javascript/typescript (and react via `@komplett/react-themed`).
> [!WARNING]
> This is in early development. Expect things to break and change before it hits 1.0.0
**Visit our [Documentation](https://themed.komplett.io)**
---
## Features:
- 🔒 **Type-checking** themes for validity, checking all values exist etc.
- 🌐 Produces nice **SCSS AND CSS** variables, so you can use all SCSS features with theming.
- 🖌 **Multi-theme**: You can either use classic dark/light themes, or define as many as you want!
- 🚀 **Extra features** like JS/TS methods for interactivity built in.
- 🎭 **Customizable**: Adjust nearly every aspect of how you use themes.
- 🌈 Prints **human-readable** errors when doing something wrong.
- First class **React support** with `@komplett/react-themed`.
---
## Usage:
It's as easy as:
```scss
@use '@komplett/themed' as *;
// Define themes in a map
$themes: (
'dark': (
'text': #212529,
'background': #fafafa,
// ...
),
'light': (
'text': #fafafa,
'background': #212529,
// ...
),
);
// Register the themes. They will be checked for validity, uniformity etc.
@include themes($theme-map);
// Use the themed function to get type-checked theming!
body {
color: themed('text');
background-color: themed('background');
}
```
Using SCSS' meta package and error/type checking. you get nice error hints!
```bash
[sass] "'grey-29' is not defined in your themes."
╷
22 │ background-color: themed("grey-29");
│ ^^^^^^^^^^^^^^^^^
╵
src/styles/main.scss 22:21 root stylesheet
```
---
## Installation:
One way is to just copy the stuff in `./packages/themed/src/index.scss` and put them into your app.
Alternatively, use `npm install -D @komplett/themed` and follow the example above, or look at one of the examples in the `examples` folder.
### React
For react, install `@komplett/react-themed` and place a at the app level of your app. You can then use the `useTheme` hook to retrieve/update it. All utility methods are also exported from `@komplett/react-themed/utils`.
---
## Questions
**Q: Why not just use CSS variables?**
1. Using SCSS builtins like `color.adjust` and `color.change` will not work with CSS variables. If you need transparency, or want to generate shades of a color with SCSS, it's tough
2. Ugly theme definitions. Defining all those variables in plain CSS is weird. You would probably use SCSS to define maps of themes anyways, and then convert them to SCSS variables.
**Q: Can I use this with tailwind?**
A: Probably not? Tailwind probably has it's own thing going on. This is as raw as SCSS gets.
**Q: What dependencies does this have?**
A: None, except for SCSS. We do suggest to use tools like Vite though, just to make your life a bit easier.
**Q: And what about build tools, bundling and CSS output. Anything to be aware of?**
A: Yes, good that you ask. We use global SCSS variables to keep track of the registered themes. Those SCSS variables are lexically scoped to modules, so you will only be able to use the "themed" function in the same scope.
Meaning, if you want to use themed functions in multiple files, make sure that they all `@use` a file that defines the themes. See the `vite-vanilla-extended` or `vite-react` examples for this, they define a `global.scss` file.
This is, of course, only needed on compile time. The CSS output will always be the same.
## Developing
We use `pnpm` and `pnpm workspaces` to maintain themed. You must have PNPM installed. Clone the repo, install all packages with `pnpm install` and build them, for example using `pnpm run build:watch` in the root folder.
You can also run the examples with, for example `pnpm run example:vanilla`. Any code change you now make should instantly be reflected (after a quick rebuild). Initially, you might see errors in the console, because the react and the vanilla
package try to build in parallel.