### Initial Setup for Seelen UI

Source: https://github.com/eythaann/seelen-ui/blob/master/AGENTS.md

Run this command to install dependencies and start the frontend development server.

```bash
npm install && npm run dev
```

--------------------------------

### Frontend Development Workflow

Source: https://github.com/eythaann/seelen-ui/blob/master/AGENTS.md

Starts the frontend development server for iterative UI work.

```bash
npm run dev
```

--------------------------------

### Install Seelen UI Library via NPM

Source: https://github.com/eythaann/seelen-ui/blob/master/libs/core/readme.md

Use this command to install the Seelen UI library to your project from npm.

```sh
npm install @seelen-ui/lib
```

--------------------------------

### Theme Metadata Configuration

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/theme_guidelines.md

Example `metadata.yml` file demonstrating how to include SCSS and CSS files for different Seelen UI components.

```yaml
# metadata.yml
styles:
  "@seelen/fancy-toolbar": !include styles/toolbar.scss
  "@seelen/weg": !include styles/weg.css
sharedStyles: !include shared/index.scss
```

--------------------------------

### Resource ID Examples

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/resource_guidelines.md

Examples of valid resource IDs. Ensure usernames and resource names adhere to the specified character and format rules.

```plaintext
@johndoe/my-dark-theme
@johndoe/weather-widget
@acme/corporate-icons
```

--------------------------------

### Install Seelen UI using Winget

Source: https://github.com/eythaann/seelen-ui/blob/master/README.md

Use this command to install Seelen UI directly from your terminal via the Winget package manager. Ensure Winget is available on your system.

```pwsh
winget install --id Seelen.SeelenUI
```

--------------------------------

### Run UI Build with Development Server

Source: https://github.com/eythaann/seelen-ui/blob/master/scripts/build/README.md

Starts the UI build process and launches a development server with watch mode enabled. This is useful for real-time updates during development.

```bash
npm run build:ui -- --serve
```

--------------------------------

### Switch Setting Example

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/widget_guidelines.md

A toggle switch for boolean values. 'defaultValue' sets the initial state.

```yaml
- type: switch
  key: show-seconds
  label: Show seconds
  defaultValue: true
```

--------------------------------

### System CSS Variables Example

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/theme_guidelines.md

List of system-provided CSS variables for Windows accent colors. These can be used directly in stylesheets without declaration.

```css
--system-accent-color          /* main accent */
--system-accent-light-color    /* light variant */
--system-accent-lighter-color  /* lighter variant */
--system-accent-lightest-color /* lightest variant */
--system-accent-dark-color     /* dark variant */
--system-accent-darker-color   /* darker variant */
--system-accent-darkest-color  /* darkest variant */
```

--------------------------------

### Unload Resource CLI Command

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/resource_guidelines.md

Use this command to remove a resource from the Seelen UI registry. This command uses the same path that was used to load the resource. Loaded resources are only registered for the current session and will need to be reloaded or installed permanently after restarting Seelen UI.

```bash
slu resource unload <kind> <path>
```

```bash
slu resource unload theme ./my-dark-theme
```

--------------------------------

### Typical Resource Folder Structure

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/resource_guidelines.md

Illustrates a common layout for Seelen UI resource folders, highlighting the mandatory entrypoint file and optional subdirectories for internationalization and styles.

```bash
my-dark-theme/
├── metadata.yml          ← entrypoint: id, metadata, kind-specific fields
├── i18n/
│   ├── display_name.yml  ← translations for the name
│   └── description.yml   ← translations for the description
└── styles/
    ├── toolbar.scss       ← styles referenced with !include
    └── weg.scss
```

--------------------------------

### Build UI Bundles

Source: https://github.com/eythaann/seelen-ui/blob/master/AGENTS.md

Generates production-ready UI bundles for deployment.

```bash
npm run build:ui
```

--------------------------------

### Load Resource CLI Command

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/resource_guidelines.md

Use this command to load a resource into a running Seelen UI instance from any local path. The resource is registered immediately and available without restarting the application. Seelen UI must be running for this command to work.

```bash
slu resource load <kind> <path>
```

```bash
slu resource load theme ./my-dark-theme
```

```bash
slu resource load widget C:\Users\me\projects\my-clock
```

```bash
slu resource load plugin ./my-plugin/mod.yml
```

--------------------------------

### Build Core Library (Deno)

Source: https://github.com/eythaann/seelen-ui/blob/master/AGENTS.md

Builds the core library using Deno tasks.

```bash
deno task build
```

--------------------------------

### Seelen UI CLI: Resource Management

Source: https://github.com/eythaann/seelen-ui/blob/master/AGENTS.md

Commands for loading, unloading, and bundling resources like themes and widgets using the `slu` CLI. Ensure Seelen UI is running before executing these commands.

```bash
slu resource load theme ./my-theme     # live-load without bundling
```

```bash
slu resource load widget ./my-widget
```

```bash
slu resource unload theme ./my-theme
```

```bash
slu resource bundle theme ./my-theme   # produce .yaml for marketplace
```

--------------------------------

### Bundle Seelen UI Resource

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/resource_guidelines.md

Use this command to bundle a Seelen UI resource. Specify the resource kind and its path. The output is a self-contained YAML file ready for upload.

```bash
slu resource bundle <kind> <path>
```

```bash
slu resource bundle theme ./my-dark-theme
```

```bash
slu resource bundle widget C:\Users\me\projects\my-clock
```

```bash
slu resource bundle plugin ./my-plugin/mod.yml
```

--------------------------------

### HTML Entry Point for Svelte Applications

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/widget_guidelines.md

For Svelte applications, the HTML entry point typically consists of a single div element that serves as the mount point for the Svelte app.

```html
<div id="app"></div>
```

--------------------------------

### Run Tauri in Development Mode

Source: https://github.com/eythaann/seelen-ui/blob/master/AGENTS.md

Launches the Tauri application with development tools enabled.

```bash
npm run tauri dev
```

--------------------------------

### HTML Entry Point for Framework SPAs

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/widget_guidelines.md

The HTML file for a widget should contain only the mount point for your framework's application. No HTML, head, or body tags are needed.

```html
<!-- index.html -->
<div id="root"></div>
```

--------------------------------

### Add Seelen UI Library via JSR

Source: https://github.com/eythaann/seelen-ui/blob/master/libs/core/readme.md

Use this command to add the Seelen UI library to your Deno project from JSR.

```sh
deno add @seelen-ui/lib
```

--------------------------------

### Deno Formatting

Source: https://github.com/eythaann/seelen-ui/blob/master/AGENTS.md

Formats code according to Deno's standard style guidelines.

```bash
deno fmt
```

--------------------------------

### Run Project Tests

Source: https://github.com/eythaann/seelen-ui/blob/master/AGENTS.md

Executes the project's test suite.

```bash
npm run test
```

--------------------------------

### Run UI Build in Development

Source: https://github.com/eythaann/seelen-ui/blob/master/scripts/build/README.md

Executes the UI build process in development mode. This command is used for local development and testing.

```bash
npm run build:ui
```

--------------------------------

### Select Setting - Dropdown

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/widget_guidelines.md

A dropdown list for selecting one value from a predefined set. 'options' define the available choices.

```yaml
# Dropdown (default)
- type: select
  key: clock-format
  label: Time format
  defaultValue: "12h"
  options:
    - value: "12h"
      label: 12-hour
    - value: "24h"
      label: 24-hour
```

--------------------------------

### Color Setting

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/widget_guidelines.md

A color picker input. 'allowAlpha: true' enables the transparency channel.

```yaml
- type: color
  key: accent-color
  label: Accent color
  defaultValue: "#6c63ff"
  allowAlpha: true
```

--------------------------------

### Run UI Build in Production Mode

Source: https://github.com/eythaann/seelen-ui/blob/master/scripts/build/README.md

Executes the UI build process in production mode, enabling optimizations like minification and disabling sourcemaps. This command is used for creating production-ready builds.

```bash
npm run build:ui -- --production
```

--------------------------------

### Defining a Color Setting with Description and Tooltip

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/theme_guidelines.md

Exposes a color picker for users to customize a theme's accent color, including optional description and tooltip for clarity.

```yaml
- syntax: <color>
  name: --my-accent
  label: Accent color
  description: Used for highlights and interactive elements.
  tip: Supports transparency.
  initialValue: "#6c63ff"

```

--------------------------------

### Widget Configuration with metadata.yml

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/widget_guidelines.md

The metadata.yml file defines essential widget properties such as ID, display name, icon, window behavior presets, instance limits, and source file paths.

```yaml
id: "@yourname/my-widget"

metadata:
  displayName: My Widget
  description: A short description.
  tags:
    - clock
    - minimal

# Icon shown in the Seelen UI settings panel.
# Must be a valid react-icons name (https://react-icons.github.io/react-icons/).
icon: PiClockFill

# Window behavior preset (see section 4)
preset: Overlay

# How many instances users can create (see section 4)
instances: Single

# If true, the widget window is not created until it is explicitly triggered.
lazy: false

# Widget source files (required)
html: !include index.html
js: !include index.js
css: !include index.css

# User-configurable settings (see section 5)
settings: []
```

--------------------------------

### Translate Resource File using slu CLI

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/resource_guidelines.md

Uses the Seelen UI CLI to automatically translate a resource file to all supported languages. The source language defaults to English.

```bash
slu resource translate <path/to/file.yml>
```

--------------------------------

### Build Core Library for NPM

Source: https://github.com/eythaann/seelen-ui/blob/master/AGENTS.md

Builds the core library specifically for distribution via npm.

```bash
deno task build:npm
```

--------------------------------

### Length/Percentage Input Configuration

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/theme_guidelines.md

Configure a length or percentage input allowing users to select units like px, %, em, rem, vw. Use this for flexible unit choices.

```yaml
- syntax: <length>
  name: --item-size
  label: Item size
  initialValue: 40
  initialValueUnit: px
```

--------------------------------

### URL Input Configuration

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/theme_guidelines.md

Configure a URL input for file pickers. The selected path is stored as a CSS `url()` value. `initialValue` is ignored.

```yaml
- syntax: <url>
  name: --custom-background-image
  label: Background image
  initialValue: ""
```

--------------------------------

### String Input Configuration

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/theme_guidelines.md

Configure a string input for text values like font families. Use min and max to enforce length limits.

```yaml
- syntax: <string>
  name: --custom-font
  label: Font family
  initialValue: "Segoe UI"
  max: 80
```

--------------------------------

### Translate Resource File with Explicit Source Language

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/resource_guidelines.md

Uses the Seelen UI CLI to translate a resource file, specifying a non-English source language.

```bash
slu resource translate i18n/display_name.yml es
```

--------------------------------

### Applying Font Setting in CSS

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/widget_guidelines.md

Demonstrates how to apply a selected font family to widget elements using CSS variables.

```javascript
document.documentElement.style.setProperty("--widget-font", settings["widget-font"]);
```

```css
.my-widget {
  font-family: var(--widget-font, "Segoe UI");
}
```

--------------------------------

### Splitting Translations using !extend

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/resource_guidelines.md

Demonstrates splitting translation strings into separate YAML files using the !extend tag. The main metadata.yml references these extended files.

```yaml
# metadata.yml
metadata:
  displayName: !extend i18n/display_name.yml
  description: !extend i18n/description.yml
```

```yaml
# i18n/display_name.yml
en: My Dark Theme
es: Mi Tema Oscuro
de: Mein Dunkles Theme
```

--------------------------------

### Resource Metadata Structure

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/resource_guidelines.md

The metadata block describes the resource for the marketplace and Seelen UI settings. Required fields are 'displayName' and 'description'.

```yaml
metadata:
  # Name shown in the UI (required)
  displayName: My Dark Theme

  # Short description (required)
  description: A clean dark theme for all widgets.

  # Keywords that help users find your resource
  tags:
    - dark
    - minimal
    - toolbar

  # Square preview image — 1:1 aspect ratio (optional)
  # portrait: uploaded via the Seelen website (see note below)

  # Wide promotional banner — 21:9 aspect ratio (optional)
  # banner: uploaded via the Seelen website (see note below)

  # Screenshots — 16:9 aspect ratio, as many as you want (optional)
  # screenshots: uploaded via the Seelen website (see note below)

  # Oldest Seelen UI version your resource is compatible with (optional)
  appTargetVersion: [1, 11, 0]
```

--------------------------------

### Widget Folder Structure

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/widget_guidelines.md

The standard folder structure for a widget project. Ensure all resources are referenced in metadata.yml.

```yaml
my-widget/
├── metadata.yml   ← resource definition (references all other files)
├── index.html     ← HTML body content
├── index.js       ← bundled JavaScript
├── index.css      ← bundled CSS
└── i18n/          ← translations (optional)
    ├── display_name.yml
    └── description.yml
```

--------------------------------

### InputText Setting - Multiline

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/widget_guidelines.md

A textarea for multi-line text input. Set 'multiline: true' to enable.

```yaml
- type: text
  key: custom-css
  label: Custom CSS
  defaultValue: ""
  multiline: true
```

--------------------------------

### Applying Shared Styles with Data Attributes

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/theme_guidelines.md

Demonstrates how to apply shared styles to elements that opt-in using `data-skin` attributes, avoiding global overrides.

```css
/* OK — targets only elements that explicitly opt in */
button[data-skin="solid"] {
  background: var(--slu-std-ui-color);
}
button[data-skin="default"] {
  border: 1px solid var(--slu-std-ui-color);
}
button[data-skin="transparent"] {
  background: transparent;
}

input[type="checkbox"][data-skin="switch"] {
  /* toggle switch */
}
input[type="range"][data-skin="flat"] {
  /* flat slider */
}
select[data-skin="default"] {
  /* styled select */
}

/* OK — targets a specific component class */
.slu-std-popover {
  background: var(--color-gray-50);
}

/* Avoid — overrides every button everywhere */
button {
  background: red;
}

```

--------------------------------

### Number Input Configuration

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/theme_guidelines.md

Configure number inputs for plain values, sliders, or dropdowns. Use min, max, and step for range and slider behavior. Options create a dropdown.

```yaml
# Plain input
- syntax: <number>
  name: --toolbar-opacity
  label: Toolbar opacity
  initialValue: 90
  min: 0
  max: 100
```

```yaml
# Slider (step enables the slider UI)
- syntax: <number>
  name: --border-radius
  label: Corner radius
  initialValue: 8
  min: 0
  max: 24
  step: 1
```

```yaml
# Dropdown
- syntax: <number>
  name: --font-size
  label: Font size
  initialValue: 13
  options:
    - 11
    - 13
    - 15
    - 17
```

--------------------------------

### Defining a Color Setting

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/theme_guidelines.md

Exposes a color picker for users to customize a theme's background color via CSS variables.

```yaml
- syntax: <color>
  name: --my-background
  label: Background color
  initialValue: "#1e1e2e"

```

--------------------------------

### Simple Display Name (English Only)

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/resource_guidelines.md

Defines a display name for a resource using only English.

```yaml
displayName: My Dark Theme
```

--------------------------------

### InputText Setting - Single Line

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/widget_guidelines.md

A standard text input field. 'maxLength' limits the input length.

```yaml
- type: text
  key: greeting
  label: Greeting message
  defaultValue: "Hello"
  maxLength: 100
```

--------------------------------

### Resource ID Format

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/resource_guidelines.md

Resource IDs must follow the '@your-username/resource-name' format. This is used when creating and referencing resources within Seelen UI.

```plaintext
@your-username/resource-name
```

--------------------------------

### Deno Linting

Source: https://github.com/eythaann/seelen-ui/blob/master/AGENTS.md

Applies Deno's built-in linter to enforce code style and catch potential issues.

```bash
deno lint
```

--------------------------------

### Grouping Settings Configuration

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/theme_guidelines.md

Organize settings into collapsible sections using the `group` property. Groups can be nested to create hierarchical settings.

```yaml
settings:
  - syntax: <color>
    name: --toolbar-bg
    label: Toolbar background
    initialValue: "#1e1e2e"

  - group:
      header: Dock settings
      items:
        - syntax: <color>
          name: --dock-bg
          label: Dock background
          initialValue: "#313244"

        - syntax: <number>
          name: --dock-item-size
          label: Item size
          initialValue: 40
          min: 24
          max: 72
          step: 2

        - group:
            header: Dock border
            items:
              - syntax: <color>
                name: --dock-border-color
                label: Border color
                initialValue: "#45475a"
              - syntax: <number>
                name: --dock-border-width
                label: Border width
                initialValue: 1
                min: 0
                max: 4
                step: 1
```

--------------------------------

### Rust Command Declaration for Core Library

Source: https://github.com/eythaann/seelen-ui/blob/master/AGENTS.md

This macro usage in `libs/core/src/handlers/commands.rs` declares a new Tauri command, linking it to its Rust implementation and defining its return type.

```rust
slu_commands_declaration! {
    GetYourData = get_your_data() -> Vec<YourType>,
}
```

--------------------------------

### Include SCSS/SASS Files

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/resource_guidelines.md

Embeds SCSS or SASS files, which are automatically compiled to CSS before insertion. Other file types are inserted as plain text.

```yaml
# A theme inserting its stylesheets
styles:
  "@seelen/fancy-toolbar": !include styles/toolbar.scss
  "@seelen/weg": !include styles/weg.css

# A plugin inserting its JavaScript
plugin:
  template: !include plugin/template.js
  tooltip: !include plugin/tooltip.js
```

--------------------------------

### Select Setting - Inline Buttons

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/widget_guidelines.md

Configures a select setting to use inline buttons instead of a dropdown. 'subtype: Inline' enables this.

```yaml
# Inline buttons (subtype: Inline)
- type: select
  key: position
  label: Position
  defaultValue: left
  subtype: Inline
  options:
    - value: left
      label: Left
    - value: center
      label: Center
    - value: right
      label: Right
```

--------------------------------

### Debug Rust Build

Source: https://github.com/eythaann/seelen-ui/blob/master/AGENTS.md

Compiles the Rust project in debug mode, useful for creating a binary for testing.

```bash
cargo build
```

--------------------------------

### Rust Backend Module Infrastructure

Source: https://github.com/eythaann/seelen-ui/blob/master/AGENTS.md

This Rust code defines the infrastructure side of a backend module, handling Tauri commands and bridging internal events to webviews. It uses `std::sync::Once` for lazy initialization of the manager.

```rust
use std::sync::Once;
use seelen_core::handlers::SeelenEvent;
use crate::{app::emit_to_webviews, error::Result};
use super::{YourEvent, YourManager};

fn get_manager() -> &'static YourManager {
    static REGISTER: Once = Once::new();
    REGISTER.call_once(|| {
        YourManager::subscribe(|_event: YourEvent| {
            // Keep this small and side-effect focused.
            if let Ok(data) = get_your_data() {
                emit_to_webviews(SeelenEvent::YourDataChanged, data);
            }
        });
    });
    YourManager::instance()
}

#[tauri::command(async)]
pub fn get_your_data() -> Result<Vec<YourType>> {
    let manager = get_manager();
    Ok(manager.get_data())
}
```

--------------------------------

### CSS Usage for URL Inputs

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/theme_guidelines.md

Apply CSS variables configured as URLs, typically for background images, using the `var()` function.

```css
.ft-bar::before {
  content: "";
  background-image: var(--custom-background-image);
}
```

--------------------------------

### Rust Backend Module Application

Source: https://github.com/eythaann/seelen-ui/blob/master/AGENTS.md

This Rust code defines the application side of a backend module, including the manager's singleton instance and event handling. It uses `LazyLock` for thread-safe lazy initialization.

```rust
use std::sync::LazyLock;

pub struct YourManager {
    // fields
}

#[derive(Debug, Clone)]
pub enum YourEvent {
    DataChanged,
}

event_manager!(YourManager, YourEvent);

impl YourManager {
    fn new() -> Self {
        Self { /* init */ }
    }

    pub fn instance() -> &'static Self {
        static MANAGER: LazyLock<YourManager> = LazyLock::new(|| {
            let mut m = YourManager::new();
            m.init().log_error();
            m
        });
        &MANAGER
    }

    fn init(&mut self) -> Result<()> {
        self.setup_listeners()?;
        Ok(())
    }

    fn setup_listeners(&mut self) -> Result<()> {
        // Listen to OS signals; emit internal YourEvent::* (not webview events)
        Ok(())
    }

    pub fn get_data(&self) -> Vec<YourType> {
        // return data
        vec![]
    }
}
```

--------------------------------

### Including External Data in Plugin Payload

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/plugin_guidelines.md

Demonstrates how to include external data files directly within the plugin's data payload using the `!include` directive. This is useful for organizing complex plugin data.

```yaml
plugin:
  template: !include plugin/template.js
  tooltip: !include plugin/tooltip.js
  scopes:
    - Power
```

--------------------------------

### Font Setting

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/widget_guidelines.md

A font picker for selecting system fonts. The stored value is a font family name string.

```yaml
- type: font
  key: widget-font
  label: Font
  defaultValue: "Segoe UI"
```

--------------------------------

### Splashscreen CSS Styling

Source: https://github.com/eythaann/seelen-ui/blob/master/src/ui/react/settings/public/index.html

Defines the styles for the splashscreen, including its fixed position, transition effects for opacity, and nested styles for hiding and vanishing states. Use this for implementing a loading or initial screen.

```css
#splashscreen {
  position: fixed;
  top: 0;
  left: 0;
  width: 100vw;
  height: 100vh;
  z-index: 1000;
  will-change: contents;
  background-color: var(--color-gray-50);
  transition: opacity 300ms linear;
  opacity: 1;
  &.hidden {
    display: none;
  }
  &.vanish {
    opacity: 0;
  }
  .splashscreen-image {
    width: 100%;
    height: 100%;
    object-fit: cover;
  }
}
```

--------------------------------

### InputNumber Setting

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/widget_guidelines.md

A numeric input field with optional minimum, maximum, and step constraints. 'min', 'max', and 'step' control the input range and increments.

```yaml
- type: number
  key: refresh-rate
  label: Refresh rate (ms)
  defaultValue: 1000
  min: 100
  max: 60000
  step: 100
```

--------------------------------

### Common Setting Fields

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/widget_guidelines.md

These fields are shared across all setting types. 'key' and 'label' are required. 'dependencies' specify conditions for the setting to be active.

```yaml
key: my-setting # Unique identifier (required)
label: My Setting # Label shown in the settings panel (required)
description: Some help. # Extra text shown under the label (optional)
tip: A tooltip. # Tooltip shown on an icon next to the label (optional)
allowSetByMonitor: false # If true, the user can set different values per monitor
dependencies: # Keys that must be truthy for this setting to be active
  - some-other-key
```

--------------------------------

### Localized Display Name

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/resource_guidelines.md

Provides localized display names for a resource in multiple languages. Always include 'en' as a fallback.

```yaml
displayName:
  en: My Dark Theme
  es: Mi Tema Oscuro
  de: Mein Dunkles Theme
  fr: Mon Thème Sombre
  pt-BR: Meu Tema Escuro
```

--------------------------------

### Using CSS Variables in Styles

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/theme_guidelines.md

Applies user-configurable CSS variables for background and accent colors to theme elements.

```css
.toolbar {
  background-color: var(--my-background);
  color: var(--my-accent);
}

```

--------------------------------

### Targeting Specific Widgets in Styles

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/theme_guidelines.md

Maps widget IDs to their respective SCSS or CSS files within the theme's metadata.yml.

```yaml
styles:
  # Local / community widget (friendly ID)
  "@seelen/fancy-toolbar": !include styles/toolbar.scss

  # Another creator's widget
  "@someone/custom-clock": !include styles/custom-clock.scss

  # Downloaded widget identified by UUID
  "550e8400-e29b-41d4-a716-446655440000": !include styles/downloaded-widget.scss

```

--------------------------------

### Include Plain Text File

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/resource_guidelines.md

Embeds the content of a file as a plain text string within a YAML resource. The path is relative to the metadata.yml file.

```yaml
key: !include path/to/file.ext
```

--------------------------------

### Plugin Structure in metadata.yml

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/plugin_guidelines.md

Defines the essential fields for a Seelen UI plugin, including its ID, metadata, target widget, and the plugin-specific data payload. The `plugin` field can contain any valid YAML structure.

```yaml
id: "@yourname/my-plugin"

metadata:
  displayName: My Plugin
  description: A short description of what this plugin adds.
  tags:
    - toolbar

# Icon shown in the Seelen UI settings panel.
# Must be a valid react-icons name (https://react-icons.github.io/react-icons/).
# Defaults to PiPuzzlePieceDuotone if omitted.
icon: PiPuzzlePieceDuotone

# The widget this plugin is for
target: "@someuser/some-widget"

# The plugin data — structure depends entirely on the target widget
plugin:
  someField: someValue
```

--------------------------------

### Range Setting

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/widget_guidelines.md

A slider for selecting a numeric value within a defined range. 'min', 'max', and 'step' configure the slider's behavior.

```yaml
- type: range
  key: opacity
  label: Opacity
  defaultValue: 100
  min: 10
  max: 100
  step: 5
```

--------------------------------

### Use Global CSS Classes for Widgets

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/widget_guidelines.md

Use stable, global class names in your HTML and CSS to ensure themes can reliably target your widget's elements. Avoid CSS Modules or any build-time class name scoping.

```html
<div class="my-widget-toolbar">
  <button class="my-widget-btn">Click</button>
</div>
```

```css
.my-widget-toolbar {
  display: flex;
}
.my-widget-btn {
  border-radius: 6px;
}
```

```html
<div class="toolbar_xK92a">
  <button class="btn_mP3z1">Click</button>
</div>
```

--------------------------------

### CSS Usage for Length/Percentage Inputs

Source: https://github.com/eythaann/seelen-ui/blob/master/documentation/theme_guidelines.md

Apply CSS variables configured with length or percentage inputs directly. The unit is handled by the input component.

```css
.weg-item {
  width: var(--item-size);
  height: var(--item-size);
}
```