How to Theme Seelen UI - K-Ivy/Seelen-UI-Resources GitHub Wiki
Seelen UI theming is done via CSS/SCSS structure. This guide will walk you through the basics of how it works, how to create your own themes and how to edit themes.
↳ But, FIRST, note that a theme is NOT a plugin! Many use the word "plugin" as the umbrella term for everything but in the case of Seelen UI, do not do so (especially when asking for help). Everything is categorized specifically as they are not the same.
↳ Second, be aware that seelen has a special debug version! This version lets you:
➙ Inspect elements just like a web page
↳ When installed and launched, focus on either the toolbar or dock and do Ctrl+Shift+I
➙ See live HTML/CSS changes
➙ Test theme modifications instantly
➙ Debug styling issues easily✦ Download it from the latest Nightly Release on GitHub (file ending with -debug.exe). Also, if your curious, Click Here to learn more about nightly builds.
◈ Think of Seelen UI themes like layers of paint. You can apply multiple themes at once, and just like painting, the order matters!
↳ With that in mind, there are three ways themes can be and are packaged:
1. Single Theme File (.yml - This is the way we'll go through and what you should submit to the site).
2. Theme Folder (Series of bundled files - refer to the folder structure below).
3. Compressed Theme (.slu - Seelen UI format. You'll notice downloads from the site are in this form. The site converts to .slu upon upload. Users are not meant to do it themselves).
「 Folder Structure 」
├── YourThemeFolder # the name of the folder doesn't matter
│ ├── theme.yml # Theme metadata file
│ └── seelen # creator's username of widgets inside
│ ├── fancy-toolbar.css # resource's name + css extension
│ └── window-manager.scss # supports SCSS too!
├── CompactTheme.yml # Theme metadata file with styles inside
└── CompressedTheme.slu # Seelen UI's own file format➙ C:\Users{YOUR_USERNAME}\AppData\Roaming\com.seelen.seelen-ui\themes - This is where all your themes should go.
◈ As all great things, you do not need to start from scratch. Before looking through the below guide, take note of these:
↳ Reference Seelen's Default Themes to get and learn most of the available classnames you can use when creating your theme without having to install the debug version of seelen.
↳ Reference User Uploaded Themes on the site for inspiration and look through there codes to learn and understand more advanced usage - how you can look through these .slu will be covered in the how to edit themes section.
1. To start, create a .yml file in the themes folder (or wherever you'd like) and open it up with your preferred text/code editor.
↳ Now define the metadata as shown below:
「 Theme Metadata 」
id: "@yourname/theme-id"
metadata:
displayName: "Your Theme Name"
description: "What your theme does"
author: "Your Name"
tags: ['weg', 'toolbar']
appTargetVersion:
- 2
- 3
- 8↪ ID is your theme's Friendly Identifier. Make it unique.
↪ Displayname / Description can be set as above or if you want to add language translations, like so:
...
displayName:
en: Your Theme Name
eu: Your Theme Name Translated
description:
en: What your theme does
ko: What your theme does translated
cs: >-
What your theme does
translated.
...✦ Note: You dont have to do this manually. The Resource Creator Tool can add mtl translations for you.
↪ Tags allow for easier identification. weg here is the dock, and toolbar is the topbar.
↪ AppTargetVersion should be set to the latest Seelen UI version at the time of creating.
➙ The relevant metadata you define here will be overriden by what you set on the site if/when uploading.
2. After metadata, comes settings. This is optional, but what it allows is making your theme customizable from within Seelen Settings without you or users of your theme having to touch the theme file. Of course, this is something you build up as you are writing the code for your theme, but note this early.
↳ So how does it work? Simply, instead of hardcoding values, you define variables whose values you'll have be the snippets of code you want to be changeable.
↪ Available Syntax Types:
-
<string>- Most flexible. Can be used for any plain text or value. -
<number>- For numeric values, without units. -
<length>- For numeric values, with units (px, em, rem, etc.) -
<color>- For css valid colors.
↳ Here's how they are defined:
「 Theme Settings 」
...
appTargetVersion:
- 2
- 3
- 8
settings:
- syntax: <color>
label:
en: "Example Color"
name: '--example-color-var'
initialValue: '#def8ffdc'
- syntax: <length>
label:
en: "Example Length"
name: '--example-length-var'
initialValue: 2
initialValueUnit: 'px'
- syntax: <number>
label:
en: "Example Number"
name: '--example-number-var'
initialValue: 600
- syntax: <string>
label:
en: "Example String"
name: '--example-string-var'
initialValue: 'grayscale(0%) opacity(1.0) saturate(1.0)'↳ Usage examples:
.taskbar {
...
.taskbar-bg-layer-2 {
background-color: var(--example-color-var); /* Dock's main BG */
border: var(--example-length-var) solid var(--example-secondary-color-var); /* Adds border around dock */
}
}
...
.ft-bar-item {
font-weight: var(--example-number-var); /* Font line thickness */
}
...
.weg-item {
.weg-item-icon {
filter: var(--example-string-var, grayscale(0%) opacity(1.0) saturate(1.0));
}
}✦ Note: For "string" variables, adding a fallback as shown above is good. Everything after the "," is considered part of the fallback, so just put the code snippet like so. This way, if when changing the value in Seelen Settings, the code snippet becomes invalid, it doesn't break and instead uses this fallback.
3. Now we're onto writing the actual code for the theme. With that, note:
↳ PROPER and CONSISTENT SPACING and INDENTATION, is crucial, as it for the above that we went through!!! This is the most likely first cause of themes not working.
↪ Style Scopes:
-
weg- This target's the seelen Dock. -
toolbar- This target's the seelen Topbar. -
wm- This target's the seelen Window Manager. -
launcher- This targets the seelen App Launcher.
↳ Here's how they are defined:
「 Styles 」
...
appTargetVersion:
- 2
- 3
- 8
settings:
...
styles:
weg: |
/* Selectors */
...
toolbar: |
/* Selectors */
...
wm: |
/* Selectors */
...
launcher: |
/* Selectors */
...↳ As shown, each scope gets it's own indented block.
✦ Before going further, note that Seelen UI automatically picks up your Windows Accent color and makes it available for use in different shades via variables (usage as shown in step 2).
Regular: --config-accent-color - The pure color (like #ffbbaa)
↳ --config-accent-color-rgb
Light: --config-accent-light-color
↳ --config-accent-light-color-rgb
Lighter: --config-accent-lighter-color
↳ --config-accent-lighter-color-rgb
Lightest: --config-accent-lightest-color
↳ --config-accent-lightest-color-rgb
Dark: --config-accent-dark-color
↳ --config-accent-dark-color-rgb
Darker: --config-accent-darker-color
↳ --config-accent-darker-color-rgb
Darkest: --config-accent-darkest-color
↳ --config-accent-darkest-color-rgb↳ The -rgb are the same color, just in RGB (255, 255, 255) format, useful for creating gradients and other color effects.
➙ Background color with opacity example: "background-color: rbga(var(--config-accent-darkest-color-rgb), 0.5);"
✦ Also, Seelen exposes dozens of additional system colors. Check this Reference.
✦ Okay, now lets go through the coding process itself. First going back up, note that colors can be in any valid form. EX: Hex Code, RGB, RGBA.
↳ Now, lets say we want to customize the seelen Dock. First, under styles, add the weg scope as shown and have your references open on the side. Like Seelen's Default Themes as noted.
↳ Line by line, go through, get your relevant classnames, and at your own pace start to add options and override existing ones with your own.
✦ As a reminder, it is all CSS, so anything CSS applies!
...
settings:
- syntax: <color>
label:
en: "Dock Background Color"
name: '--example-color-var'
initialValue: '#def8ffdc'
- syntax: <length>
label:
en: "Dock Border Thickness"
name: '--example-length-var'
initialValue: 2
initialValueUnit: 'px'
styles:
weg: |
/* Seelen DOCK */
.taskbar { /* This is a main selector */
.taskbar-bg-layer-1 { /* This is a sub selector of the above */
display: none; /* In this example, we are hiding this layer for consistency. Otherwise, if bg-layer-2 has added transparency, bg-layer-1 will be shown under */
}
.taskbar-bg-layer-2 {
background-color: var(--example-color-var); /* Setting dock's background via variable so it is customizable from within Seelen settings. */
border: var(--example-length-var) solid #acdae6; /* Adding a border around the dock, the thickness set via a variable so it is customizable as above. */
border-radius: 15px; /* Setting the corner rounding amount for the dock */
}
}
✦ Now at this point, you should understand how to theme and how it all works. So instead of going section by section, for each of the scopes, I will let you explore the Demo Theme I made for this guide which includes all the scopes (Dock, Toolbar, Window Manager, App Launcher). It is fully commented and has some extra things to help you on your way.
↳ Download the .yml and test it firsthand if you wish: https://github.com/K-Ivy/Seelen-UI-Resources/blob/main/Themes%20for%20Resources/example-theme.yml
id: "@k-ivy/faq-demo-theme"
metadata:
displayName: "Example theme for the FAQ"
description: "- Make sure you properly look through references to learn!"
author: "IriKay (@K-Ivy on Git)"
tags: ['weg', 'toolbar']
appTargetVersion:
- 2
- 3
- 8
settings:
- syntax: <color>
label:
en: "Dock and Toolbar Background Color"
name: '--example-color-var'
initialValue: '#def8ffdc'
- syntax: <length>
label:
en: "Dock and Toolbar Border Thickness"
name: '--example-length-var'
initialValue: 2
initialValueUnit: 'px'
- syntax: <number>
label:
en: "Toolbar Font Thickness"
name: '--example-number-var'
initialValue: 600
- syntax: <string>
label:
en: "Icon Filters"
name: '--example-string-var'
initialValue: 'blur(0px) brightness(1.0) contrast(1.0) grayscale(0%) hue-rotate(0deg) invert(0%) opacity(1.0) saturate(1.0) sepia(0%)'
styles:
weg: |
/* Main DOCK */
.taskbar { /* This is a main selector */
.taskbar-bg-layer-1 { /* This is a sub selector of the above */
/* In this example, we are hiding this layer for consistency. Otherwise, if bg-layer-2 has added transparency, bg-layer-1 will be shown under */
display: none;
}
.taskbar-bg-layer-2 {
background-color: var(--example-color-var); /* Setting dock's background via variable so it is customizable from within Seelen settings. */
border: var(--example-length-var) solid #acdae6; /* Adding a border around the dock, the thickness set via a variable so it is customizable as above. */
border-radius: 15px; /* Setting the corner rounding amount for the dock */
}
}
/* Dock Apps */
.weg-item {
.bg-layer-1 {
display: none; /* Same reason as previous */
}
.bg-layer-2 {
background-color: rgba(132, 161, 187, 0.438);
border-radius: 10px;
}
/* If a app is focused or you hover over another app's icon, the respective backgrounds will change color */
&:has(.weg-item-open-sign-focused) .bg-layer-2,
&:hover .bg-layer-2 {
background-color: rgb(198, 211, 236);
}
/* This is what you want to play with if you wish to adjust icons through filters as an example. The single dock color themes on the site use these filters to achieve what they do. */
.weg-item-icon {
filter: var(--example-string-var, blur(0px) brightness(1.0) contrast(1.0) grayscale(0%) hue-rotate(0deg) invert(0%) opacity(1.0) saturate(1.0) sepia(0%)); /* Everything after the "," is considered a fallback. This is used if when changing it in settings, you make the code invalid. This way, you dont break it. */
&.weg-item-start-icon { /* This is how you'd manually change the start menu icon's size */
width: 100%;
height: 100%;
}
}
toolbar: |
/* The toolbar as it stretches all the way to the edges, needs to be specially adjusted at the root if you wish to shrink it not just viusally, but actually so that you can mouse click, select, etc. */
#root {
/* These two work togather to center the toolbar so whatever width you choose, it's not off */
left: 50%;
transform: translate(-50%);
/* Moves the toolbar down */
margin-top: 4px;
/* Actual width */
width: 98.5% !important;
}
/* Main Toolbar */
.ft-bar {
.bg-layer-1 {
display: none; /* Same reason as previous */
}
.bg-layer-2 {
background-color: var(--example-color-var);
border: var(--example-length-var) solid #acdae6;
border-radius: 15px;
}
}
/* A small but important thing you may miss so I'm including: This removes default white hover bg and prevents white-ish edges on module hover if a custom hover bg is set. */
.ft-bar-item-clickable:hover {
backdrop-filter: none;
}
/* Toolbar Modules */
.ft-bar-item {
/* Custom Font styling */
font-family: Ink Free; /* Full name of font */
font-weight: var(--example-number-var); /* This sets how thick the lines are. Range: 100-900, 400 = normal */
font-style: normal; /* Opts: normal | italic | oblique */
color: rgb(86, 126, 133); /* Text color */
/* Adjustments */
padding-right: 5px; /* Extra space to the right of modules */
padding-left: 5px; /* Extra space to the left of modules */
height: 20px; /* Height of modules */
background-color: rgba(122, 149, 173, 0.486);
border: 2px solid #acdae6;
border-radius: 8px;
}
wm: |
.wm-leaf {
border: 2px solid #acdae6; /* Changing the border color when a window is focused */
}
launcher: |
.launcher {
background-color: rgba(122, 149, 173, 0.486);
border: 2px solid #acdae6;
}
.launcher-item {
&:nth-child(2n) { /* This means that every other item should have their background be what you set */
background-color: transparent;
}
&:hover {
background-color: #acdae656;
}
&:focus,
&:focus-visible {
outline: none;
}
}◈ To EDIT a Theme (or any adjacent resource) you downloaded from the Seelen UI website in some way, follow these steps:
↳ 1. Enable Developer Tools in seelen settings extras tab and afterwards, go to resources tab > themes.
↳ 2. You'll see a new button on themes. Click it to export it for editing.
↳ 3. Go to C:\Users{YOUR_USERNAME}\AppData\Roaming\com.seelen.seelen-ui\themes and remove/move the .slu version (Go to the seelen site and get it's ID) or just disable it in seelen settings, if you do this, ensure when on the next step, to change the displayname and id to something diffrent!
↳ 4. Now move in your .yml that you got and open it up. Find what you want to edit and change as needed. After, save and just enable it in seelen settings.