### Verify Opaline Installation

Source: https://hyperb1iss.github.io/opaline/getting-started/installation.html

A simple Rust program to load the default theme and print its name and type (dark/light). This confirms that Opaline is correctly installed and functional.

```rust
use opaline::Theme;

fn main() {
    let theme = Theme::default();
    println!("Loaded: {} ({})", theme.meta.name,
        if theme.is_dark() { "dark" } else { "light" });
}
```

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

### Integrate Theme Selector into Ratatui App

Source: https://hyperb1iss.github.io/opaline/guide/theme-selector.html

A minimal integration example for a Ratatui app, demonstrating how to handle key presses to open, select, and cancel the theme picker. The original theme is automatically restored on cancel.

```rust
use crossterm::event::{self, KeyCode};
use opaline::{ThemeSelector, ThemeSelectorAction, ThemeSelectorState};

struct App {
    theme_picker: Option<ThemeSelectorState>,
}

impl App {
    fn handle_key(&mut self, key: crossterm::event::KeyEvent) {
        if let Some(picker) = &mut self.theme_picker {
            match picker.handle_key(key) {
                ThemeSelectorAction::Select(id) => {
                    // Theme is already applied; persist the choice
                    self.save_theme_preference(&id);
                    self.theme_picker = None;
                }
                ThemeSelectorAction::Cancel => {
                    // Original theme was restored automatically
                    self.theme_picker = None;
                }
                _ => {}
            }
        } else if key.code == KeyCode::Char('t') {
            // Open theme picker
            self.theme_picker = Some(
                ThemeSelectorState::with_current_selected()
            );
        }
    }

    fn render(&mut self, frame: &mut ratatui::Frame) {
        if let Some(state) = &mut self.theme_picker {
            frame.render_stateful_widget(
                ThemeSelector::new(),
                frame.area(),
                state,
            );
        }
    }
}
```

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

### Theme Discovery Directories

Source: https://hyperb1iss.github.io/opaline/guide/custom-themes.html

Shows how to get standard theme directories for your application and list available themes. Opaline can scan these directories to discover user-provided themes.

```rust
// Get theme directories for your app
let dirs = opaline::app_theme_dirs("myapp");
// → ~/.config/myapp/themes/

// List discoverable themes for a specific app
let themes = opaline::builtins::list_available_themes_for_app("myapp");

// Scan all theme directories
let dirs = opaline::theme_dirs();

```

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

### Theme Discovery Directories

Source: https://hyperb1iss.github.io/opaline/reference/api.html

Requires the `discovery` feature. Get the default directories for application-specific themes or system-wide themes.

```rust
use opaline::{app_theme_dirs, theme_dirs};

let dirs = app_theme_dirs("myapp");             // Vec<PathBuf>
let dirs = theme_dirs();                        // Vec<PathBuf>
```

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

### Render Themed Widgets in Ratatui

Source: https://hyperb1iss.github.io/opaline/guide/ratatui.html

Example of rendering a themed `Block` and `Paragraph` within a Ratatui render function, utilizing Opaline's styling.

```rust
use opaline::{Theme, gradient_bar};
use ratatui::widgets::{Block, Borders, Paragraph};

fn render(frame: &mut ratatui::Frame, theme: &Theme) {
    let area = frame.area();

    // Themed block: OpalineStyle works via Into<Style>
    let block = Block::default()
        .borders(Borders::ALL)
        .border_style(theme.style("focused_border"))
        .title_style(theme.style("keyword"));

    // Themed paragraph
    let text = theme.text("keyword", "Hello, Opaline!");
    let paragraph = Paragraph::new(text).block(block);

    frame.render_widget(paragraph, area);
}
```

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

### Configure Opaline Feature Flags

Source: https://hyperb1iss.github.io/opaline/getting-started/installation.html

Manage Opaline's features using Cargo.toml to include only necessary functionalities, keeping the dependency tree lean. Examples show default, minimal, and specific feature combinations.

```toml
[dependencies]
# Default: builtins + gradients + ratatui adapter
opaline = "0.4"

# Minimal: just the core theme engine
opaline = { version = "0.4", default-features = false }

# With CLI colored output
opaline = { version = "0.4", features = ["cli"] }

# With global theme singleton
opaline = { version = "0.4", features = ["global-state"] }

# Everything
opaline = { version = "0.4", features = [
    "builtin-themes", "gradients", "ratatui",
    "cli", "crossterm", "owo-colors", "css",
    "syntect", "egui",
    "global-state", "discovery", "widgets"
] }
```

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

### Get RGB Tuple and Colored String with ThemeCliExt

Source: https://hyperb1iss.github.io/opaline/guide/cli.html

Use `ThemeCliExt` to retrieve an RGB tuple for manual coloring or apply a token color directly to a string for terminal output.

```rust
use opaline::{Theme, ThemeCliExt};

let theme = Theme::default();

// Get an RGB tuple for manual coloring
let rgb = theme.cli_rgb("accent.primary");
println!("{rgb:?}");

// Apply a token color to a string
let colored_text = theme.cli_colored("important text", "accent.primary");
println!("{colored_text}");
```

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

### CLI Theme Integration

Source: https://hyperb1iss.github.io/opaline/reference/api.html

Requires the `cli` feature. The `ThemeCliExt` trait provides methods to get RGB tuples, colored strings, and gradient strings from the theme.

```rust
use opaline::{Theme, ThemeCliExt};

let theme = Theme::default();
let rgb = theme.cli_rgb("token");              // (u8, u8, u8)
let colored = theme.cli_colored("text", "token"); // ColoredString
let rainbow = theme.cli_gradient("text", "aurora"); // String
```

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

### Token Resolution with Palette Mapping

Source: https://hyperb1iss.github.io/opaline/guide/tokens.html

Shows how Opaline tokens are resolved by mapping them to specific color keys in the TOML palette. This example demonstrates direct mapping and transitive resolution where one token references another.

```toml
[palette]
electric_purple = "#e135ff"

[tokens]
"accent.primary" = "electric_purple"  # → OpalineColor(225, 53, 255)

[tokens]
"accent.primary" = "electric_purple"
"code.keyword" = "accent.primary"     # → also resolves to #e135ff
```

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

### Build Themes Programmatically with Opaline

Source: https://hyperb1iss.github.io/opaline/getting-started/quick-start.html

Shows how to construct a custom theme using `ThemeBuilder`, defining tokens, styles, and metadata programmatically without needing a TOML file.

```rust
use opaline::{Theme, OpalineColor, OpalineStyle};

let theme = Theme::builder("My Custom Theme")
    .author("me")
    .variant(opaline::ThemeVariant::Dark)
    .token("accent.primary", OpalineColor::new(255, 100, 200))
    .token("bg.base", OpalineColor::new(18, 18, 24))
    .style("keyword", OpalineStyle::fg(OpalineColor::new(255, 100, 200)).bold())
    .build();
```

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

### Load Opaline Themes

Source: https://hyperb1iss.github.io/opaline/getting-started/quick-start.html

Demonstrates how to load a theme using default settings, by name, or from a TOML file. Ensure the theme file exists if loading from a file.

```rust
use opaline::Theme;

// Default theme (SilkCircuit Neon)
let theme = Theme::default();

// Or pick a specific builtin
let theme = opaline::load_by_name("catppuccin-mocha").unwrap();

// Or load from a TOML file
let theme = opaline::load_from_file("my-theme.toml").unwrap();
```

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

### Use Opaline Gradients

Source: https://hyperb1iss.github.io/opaline/getting-started/quick-start.html

Demonstrates how to sample colors from gradients and create gradient-colored text or progress bars. Ensure the gradient name exists in the theme.

```rust
use opaline::{Theme, gradient_bar};

let theme = Theme::default();

// Sample a single color from a gradient
let color = theme.gradient("primary", 0.5); // midpoint of primary gradient

// High-level: gradient-colored text as a Line
let line = theme.gradient_text("aurora", "Hello, Opaline!");

// Low-level: gradient progress bar from a &Gradient
let grad = theme.get_gradient("primary").unwrap();
let bar = gradient_bar(40, '█', grad); // 40 chars wide
```

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

### Basic Theme Construction

Source: https://hyperb1iss.github.io/opaline/guide/builder.html

Demonstrates building a basic dark theme with palette colors, semantic tokens, and composed styles. Ensure the `OpalineColor` and `OpalineStyle` types are imported.

```rust
use opaline::{Theme, OpalineColor, OpalineStyle, ThemeVariant};

let theme = Theme::builder("My Theme")
    .author("me")
    .variant(ThemeVariant::Dark)
    .version("1.0")
    .description("A custom dark theme")
    // Palette colors
    .palette("purple", OpalineColor::new(225, 53, 255))
    .palette("cyan", OpalineColor::new(128, 255, 234))
    .palette("dark_bg", OpalineColor::new(18, 18, 24))
    // Semantic tokens
    .token("accent.primary", OpalineColor::new(225, 53, 255))
    .token("accent.secondary", OpalineColor::new(128, 255, 234))
    .token("bg.base", OpalineColor::new(18, 18, 24))
    // Composed styles
    .style("keyword", OpalineStyle::fg(OpalineColor::new(225, 53, 255)).bold())
    .style("selected", OpalineStyle::new()
        .with_fg(OpalineColor::new(128, 255, 234))
        .with_bg(OpalineColor::new(30, 30, 40)))
    .build();

assert_eq!(theme.meta.name, "My Theme");
assert!(theme.is_dark());
```

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

### Theme Construction with Gradients

Source: https://hyperb1iss.github.io/opaline/guide/builder.html

Shows how to build a theme that includes gradients. This requires the `gradients` feature to be enabled. Import `Gradient` for gradient definitions.

```rust
use opaline::{Theme, OpalineColor, Gradient};

let theme = Theme::builder("Gradient Theme")
    .token("accent.primary", OpalineColor::new(225, 53, 255))
    .token("accent.secondary", OpalineColor::new(128, 255, 234))
    .gradient("primary", Gradient::new(vec![
        OpalineColor::new(225, 53, 255),
        OpalineColor::new(128, 255, 234),
    ]))
    .gradient("aurora", Gradient::new(vec![
        OpalineColor::new(225, 53, 255),
        OpalineColor::new(128, 255, 234),
        OpalineColor::new(80, 250, 123),
        OpalineColor::new(255, 106, 193),
    ]))
    .build();

assert!(theme.has_gradient("primary"));
assert!(theme.has_gradient("aurora"));
```

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

### Semantic Styling with Opaline Theme

Source: https://hyperb1iss.github.io/opaline/getting-started

Demonstrates using Opaline's `Theme` to apply semantic styles like 'keyword' and 'focused_border'. This approach centralizes styling and allows for easy theme switching.

```rust
use opaline::Theme;

let theme = Theme::default();

// Semantic: the theme decides what "keyword" looks like
let keyword = theme.style("keyword");   // works directly via Into<Style>
let border = theme.style("focused_border");
```

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

### List Available Themes in Rust

Source: https://hyperb1iss.github.io/opaline/themes

Retrieve metadata for all built-in and custom themes using `opaline::list_available_themes`. The output includes display name, author, and type (builtin/custom).

```rust
// Get all builtin theme metadata
let themes = opaline::list_available_themes();
for info in &themes {
    let author = if info.author.is_empty() { "unknown" } else { &info.author };
    println!("{} by {} ({})",
        info.display_name,
        author,
        if info.builtin { "builtin" } else { "custom" }
    );
}
```

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

### Create Opaline Styles Programmatically

Source: https://hyperb1iss.github.io/opaline/guide/styles.html

Demonstrates creating `OpalineStyle` instances for foreground color only, with modifiers, and using the full builder pattern.

```rust
use opaline::OpalineStyle;

// Foreground only
let style = OpalineStyle::fg(OpalineColor::new(225, 53, 255));

// With modifiers
let bold_keyword = OpalineStyle::fg(OpalineColor::new(225, 53, 255)).bold();

// Full builder
let fancy = OpalineStyle::new()
    .with_fg(OpalineColor::new(225, 53, 255))
    .with_bg(OpalineColor::new(18, 18, 24))
    .bold()
    .italic();
```

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

### CLI Integration

Source: https://hyperb1iss.github.io/opaline/reference/api.html

Extensions for integrating Opaline themes with command-line interfaces, including RGB conversion and colored string generation. Requires the `cli` feature.

```APIDOC
## CLI Integration 
Requires `cli` feature.
### `ThemeCliExt` Trait 
```rust
use opaline::{Theme, ThemeCliExt};

let theme = Theme::default();
let rgb = theme.cli_rgb("token");              // (u8, u8, u8)
let colored = theme.cli_colored("text", "token"); // ColoredString
let rainbow = theme.cli_gradient("text", "aurora"); // String
```

### `ColoredExt` Trait 
```rust
use opaline::{ColoredExt, OpalineColor, OpalineStyle};

let color = OpalineColor::new(225, 53, 255);
let style = OpalineStyle::fg(color).bold();

"text".theme_fg(color)              // ColoredString
"text".theme_bg(color)              // ColoredString
"text".theme_style(&style)          // ColoredString
```

### Gradient String 
Requires `cli` + `gradients` features.
```rust
use opaline::{gradient_string, Theme};

let theme = Theme::default();
let grad = theme.get_gradient("name").unwrap();
let rainbow = gradient_string("text", grad); // String
```
```

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

### Minimal Test Theme Creation

Source: https://hyperb1iss.github.io/opaline/guide/builder.html

Illustrates creating a minimal theme specifically for unit tests. This pattern helps in isolating and testing theme-related functionality.

```rust
#[cfg(test)]
mod tests {
    use opaline::*;

    fn test_theme() -> Theme {
        Theme::builder("Test")
            .token("accent.primary", OpalineColor::new(255, 0, 0))
            .token("bg.base", OpalineColor::new(0, 0, 0))
            .style("keyword", OpalineStyle::fg(OpalineColor::new(255, 0, 0)).bold())
            .build()
    }

    #[test]
    fn keyword_is_bold_red() {
        let theme = test_theme();
        let kw = theme.style("keyword");
        assert_eq!(kw.fg, Some(OpalineColor::new(255, 0, 0)));
        assert!(kw.bold);
    }
}
```

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

### Access Styles from Theme

Source: https://hyperb1iss.github.io/opaline/guide/styles.html

Illustrates how to retrieve styles from a `Theme` object, including strict and fall-back lookups, and checking for style existence.

```rust
let theme = opaline::Theme::default();

// Get a style (returns Default if missing)
let kw = theme.style("keyword");
assert!(kw.bold);

// Strict lookup
if let Some(style) = theme.try_style("keyword") {
    // ...
}

// Check existence
assert!(theme.has_style("keyword"));

// List all style names
let names = theme.style_names();
```

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

### Access Theme Colors and Styles

Source: https://hyperb1iss.github.io/opaline/getting-started/quick-start.html

Shows how to retrieve resolved colors by token name and composed styles by name. Also includes checks for token and style existence.

```rust
use opaline::Theme;

// Get a resolved color by token name
let accent = theme.color("accent.primary");
let bg = theme.color("bg.base");

// Get a composed style (fg + bg + modifiers)
let keyword_style = theme.style("keyword");
assert!(keyword_style.bold);

// Check if tokens/styles exist
assert!(theme.has_token("accent.primary"));
assert!(theme.has_style("keyword"));
```

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

### Load Theme from String, File, or Built-in

Source: https://hyperb1iss.github.io/opaline/guide/themes.html

Load themes into the `Theme` struct from a TOML string, a file path, or by name from built-in themes. A default theme is also available.

```rust
use opaline::Theme;

// From a TOML string
let theme = opaline::load_from_str(toml_string, None)?;

// From a file path
let theme = opaline::load_from_file("path/to/theme.toml")?;

// From builtins
let theme = opaline::load_by_name("dracula").unwrap();

// Default (SilkCircuit Neon)
let theme = Theme::default();

```

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

### Complete Theme Structure

Source: https://hyperb1iss.github.io/opaline/guide/themes.html

A full Opaline theme TOML file includes meta, palette, tokens, styles, and gradients sections.

```toml
[meta]
name = "My Theme"
author = "me"
variant = "dark"        # "dark" or "light"
version = "1.0"
description = "A beautiful theme"

[palette]
# Raw hex colors...

[tokens]
# Semantic token mappings...

[styles]
# Composed style definitions...

[gradients]
# Named gradient stop lists...

```

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

### Create ThemeSelector Widget Instance

Source: https://hyperb1iss.github.io/opaline/guide/theme-selector.html

Instantiate the ThemeSelector widget. You can create a basic instance or provide a custom title for the widget.

```rust
let widget = ThemeSelector::new();
let widget = ThemeSelector::new().title("Pick a Color Scheme");
```

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

### Generate Syntect Theme from Opaline Theme

Source: https://hyperb1iss.github.io/opaline/guide/syntect.html

Convert a full Opaline theme into a syntect `Theme` object. This function is essential for integrating Opaline's theming with syntect's highlighting capabilities.

```rust
use opaline::adapters::syntect::to_syntect_theme;

let theme = opaline::Theme::default();
let syntect_theme = to_syntect_theme(&theme);

// Use with syntect's highlighter
use syntect::highlighting::ThemeSet;
use syntect::parsing::SyntaxSet;
use syntect::easy::HighlightLines;

let ps = SyntaxSet::load_defaults_newlines();
let syntax = ps.find_syntax_by_extension("rs").unwrap();
let mut h = HighlightLines::new(syntax, &syntect_theme);
```

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

### Derive App-Specific Tokens from Theme

Source: https://hyperb1iss.github.io/opaline/guide/derivation.html

Load a theme, inject derived tokens, and activate it. Derived tokens are available via `theme.color()`.

```rust
opaline::load_theme_by_name_with("catppuccin-mocha", |theme| {
    let primary = theme.color("accent.primary");

    // App-specific tokens derived from the theme palette
    theme.register_default_token("sidebar.bg", primary.darken(0.85));
    theme.register_default_token("sidebar.hover", primary.darken(0.75));
    theme.register_default_token("tab.active", primary.lighten(0.1));

    // App-specific styles
    theme.register_default_style("sidebar_item", OpalineStyle::fg(primary).bold());
});
```

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

### Opaline for iced GUI Theming

Source: https://hyperb1iss.github.io/opaline/reference/features.html

This configuration enables the 'iced' feature for GUI theming with 'Color', 'Palette', and 'Custom' theme types.

```toml
[dependencies]
opaline = { version = "0.4", features = ["iced"] }
```

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

### Opaline for TUI with Theme Picker

Source: https://hyperb1iss.github.io/opaline/reference/features.html

This configuration enables the 'widgets' feature, providing a theme selector widget with live preview for TUI applications.

```toml
[dependencies]
opaline = { version = "0.4", features = ["widgets"] }
```

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

### Define Styles in TOML

Source: https://hyperb1iss.github.io/opaline/guide/styles.html

Shows how to define various styles, including foreground, background, and modifiers, using TOML configuration.

```toml
[styles]
keyword = { fg = "accent.primary", bold = true }
selected = { fg = "accent.secondary", bg = "bg.highlight" }
error_style = { fg = "error", bold = true, underline = true }
dimmed = { fg = "text.dim" }
inline_code = { fg = "success", bg = "bg.code" }
```

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

### Add Opaline Syntect Dependency

Source: https://hyperb1iss.github.io/opaline/guide/syntect.html

Include the syntect feature in your Opaline dependency to enable this adapter.

```toml
[dependencies]
opaline = { version = "0.4", features = ["syntect"] }
```

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

### Add Opaline with egui feature

Source: https://hyperb1iss.github.io/opaline/guide/egui.html

Include the opaline crate with the 'egui' feature enabled in your Cargo.toml file to use the egui adapter.

```toml
[dependencies]
opaline = { version = "0.4", features = ["egui"] }
```

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

### Load SilkCircuit Dawn Theme and Check if Light

Source: https://hyperb1iss.github.io/opaline/themes/silkcircuit.html

Loads the SilkCircuit Dawn theme, the light variant of SilkCircuit, and asserts that it is a light theme.

```rust
let theme = opaline::load_by_name("silkcircuit-dawn").unwrap();
assert!(theme.is_light());
```

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

### Initialize ThemeSelectorState

Source: https://hyperb1iss.github.io/opaline/guide/theme-selector.html

Initialize the ThemeSelectorState with different options. You can create a new state, pre-select the current theme, or provide a custom token derivation function for live previews.

```rust
// All themes, no pre-selection
let state = ThemeSelectorState::new();

// Pre-selects the currently active global theme
let state = ThemeSelectorState::with_current_selected();

// With app-level token derivation for live preview
let state = ThemeSelectorState::with_current_selected()
    .with_derive(my_app::derive_tokens);
```

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

### Load Theme by Name for App with Derivation

Source: https://hyperb1iss.github.io/opaline/guide/derivation.html

Similar to `load_theme_by_name_with`, but also searches app-specific discovery paths. Requires `global-state`, `builtin-themes`, and `discovery`.

```rust
use opaline::load_theme_by_name_for_app_with;

load_theme_by_name_for_app_with("custom-theme", "myapp", |theme| {
    // Derive app tokens here
})?;
```

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

### Opaline for User Theme Discovery

Source: https://hyperb1iss.github.io/opaline/reference/features.html

This configuration enables the 'discovery' feature for scanning user theme directories using `app_theme_dirs()` and `theme_dirs()`.

```toml
[dependencies]
opaline = { version = "0.4", features = ["discovery"] }
```

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

### Load Custom Theme from File or String

Source: https://hyperb1iss.github.io/opaline/guide/custom-themes.html

Demonstrates how to load a custom theme into your application using Opaline's Rust API. You can load themes from a specified file path or directly from a TOML string.

```rust
// From a file
let theme = opaline::load_from_file("~/.config/myapp/themes/custom.toml")?;

// From a string (e.g., embedded or fetched)
let toml_str = std::fs::read_to_string("theme.toml")?;
let theme = opaline::load_from_str(&toml_str, None)?;

```

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

### Opaline with Global State

Source: https://hyperb1iss.github.io/opaline/reference/features.html

This configuration enables the 'global-state' feature for a process-wide theme singleton, providing `current()` and `set_theme()` functions.

```toml
[dependencies]
opaline = { version = "0.4", features = ["global-state"] }
```

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

### Deriving App-Specific Tokens from Theme Colors

Source: https://hyperb1iss.github.io/opaline/guide/color-manipulation.html

Demonstrates using color manipulation to compute app-specific tokens from a theme's core palette, such as hover states or muted text colors.

```rust
opaline::load_theme_by_name_with("catppuccin-mocha", |theme| {
    let primary = theme.color("accent.primary");

    theme.register_default_token("bg.hover", primary.darken(0.8));
    theme.register_default_token("bg.selected", primary.darken(0.7));
    theme.register_default_token("text.muted", theme.color("text.primary").desaturate(0.4));
});
```

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

### Direct Color Styling in Rust

Source: https://hyperb1iss.github.io/opaline/getting-started

Illustrates the common approach of directly using `Color` types for styling in Ratatui applications. This method can lead to scattered magic color values in larger projects.

```rust
let style = Style::default().fg(Color::Rgb(225, 53, 255)).bold();
let border = Style::default().fg(Color::Rgb(128, 255, 234));
```

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

### Accessing Opaline Tokens in Rust

Source: https://hyperb1iss.github.io/opaline/guide/tokens.html

Demonstrates how to retrieve token colors, perform strict lookups, check for token existence, and list all available token names using the Opaline Theme object.

```rust
let theme = opaline::Theme::default();

// Get a resolved color (falls back to magenta if missing)
let color = theme.color("accent.primary");

// Strict lookup: None if missing
let color = theme.try_color("accent.primary");

// Check existence
if theme.has_token("accent.primary") {
    // ...
}

// List all token names
let names = theme.token_names();
```

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

### Switch egui Theme at Runtime

Source: https://hyperb1iss.github.io/opaline/guide/egui.html

Dynamically switch the active egui theme by loading a theme by name and applying its generated visuals. This function handles loading and setting the visuals.

```rust
use opaline::adapters::egui::to_egui_visuals;

fn switch_theme(ctx: &egui::Context, theme_name: &str) {
    let theme = opaline::load_by_name(theme_name).expect("valid theme");
    ctx.set_visuals(to_egui_visuals(&theme));
}
```

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

### Render with Ratatui using Opaline

Source: https://hyperb1iss.github.io/opaline/getting-started/quick-start.html

Illustrates seamless integration with Ratatui by creating styled spans and lines directly from a theme. Note that explicit trait imports are not needed for these types.

```rust
use opaline::Theme;
use ratatui::text::{Span, Line};

let theme = Theme::default();

// Create styled ratatui types directly, no trait import needed
let styled_span = theme.span("keyword", "fn");
let styled_line = theme.line("keyword", "let x = 42;");

// theme.style() works directly with widget methods via Into<Style>
let block = ratatui::widgets::Block::bordered()
    .style(theme.style("keyword"));

// For Style::fg()/bg(), convert colors explicitly
let color: ratatui::style::Color = theme.color("accent.primary").into();
```

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

### Generate egui Visuals from Opaline Theme

Source: https://hyperb1iss.github.io/opaline/guide/egui.html

Convert a full Opaline theme into egui's Visuals struct using the `to_egui_visuals` function. This function overrides color properties while retaining default non-color properties.

```rust
use opaline::adapters::egui::to_egui_visuals;

let theme = opaline::Theme::default();
let visuals = to_egui_visuals(&theme);

// Apply in your egui app
ctx.set_visuals(visuals);
```

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

### Using Opaline Token Name Constants

Source: https://hyperb1iss.github.io/opaline/guide/tokens.html

Illustrates using predefined constants from the `opaline::names` module for type-safe and autocomplete-friendly access to tokens, styles, and gradients.

```rust
use opaline::names::{tokens, styles, gradients};

let accent = theme.color(tokens::ACCENT_PRIMARY);
let bg = theme.color(tokens::BG_BASE);
let kw = theme.style(styles::KEYWORD);
let has_aurora = theme.has_gradient(gradients::AURORA);
```

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

### Create Gradient Text Line with Theme

Source: https://hyperb1iss.github.io/opaline/guide/ratatui.html

Generate a Ratatui `Line` with per-character gradient coloring using the `theme.gradient_text` method.

```rust
// Per-character gradient coloring → Line
let line = theme.gradient_text("aurora", "Rainbow text!");
```

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

### Opaline with All Features

Source: https://hyperb1iss.github.io/opaline/reference/features.html

This configuration enables all available features for Opaline, including built-in themes, gradients, adapters for various libraries, global state, and discovery.

```toml
[dependencies]
opaline = { version = "0.4", features = [
    "builtin-themes", "gradients", "ratatui",
    "cli", "crossterm", "owo-colors", "css",
    "syntect", "egui", "iced",
    "global-state", "discovery", "widgets"
] }
```

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

### Generate Gradient Strings with owo-colors

Source: https://hyperb1iss.github.io/opaline/guide/owo-colors.html

Create gradient strings using the `gradient_string` function, which requires a `Theme` and a gradient name.

```rust
use opaline::adapters::owo_colors::gradient_string;

let theme = opaline::Theme::default();
if let Some(gradient) = theme.get_gradient("aurora") {
    let output = gradient_string("Rainbow gradient text!", gradient);
    println!("{output}");
}
```

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

### Construct and Use OpalineColor

Source: https://hyperb1iss.github.io/opaline/reference/api.html

Create OpalineColor instances using various constructors, access RGB components, perform color interpolation, and format colors as hex strings. Includes predefined constants for common colors.

```rust
use opaline::OpalineColor;

// Construction
let color = OpalineColor::new(225, 53, 255);
let color = OpalineColor::from_hex("#e135ff")?;
let color = OpalineColor::from((225, 53, 255));
let color = OpalineColor::from([225, 53, 255]);

// Access
let (r, g, b) = (color.r, color.g, color.b);

// Interpolation
let mid = OpalineColor::lerp(&start, &end, 0.5);

// Display
assert_eq!(format!({"color"}), "#e135ff");

// Constants
OpalineColor::BLACK              // pure black
OpalineColor::WHITE              // pure white
OpalineColor::FALLBACK           // neutral gray (128, 128, 128)

// Color manipulation
color.darken(0.3)                // mix 30% toward black
color.lighten(0.2)               // mix 20% toward white
color.desaturate(0.5)            // mix 50% toward luminance gray
```

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

### Add Opaline to Project

Source: https://hyperb1iss.github.io/opaline/getting-started/installation.html

Use Cargo to add Opaline as a dependency. This command enables the default features: `builtin-themes`, `gradients`, and `ratatui`.

```bash
cargo add opaline
```

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

### Discovery

Source: https://hyperb1iss.github.io/opaline/reference/api.html

Utilities for discovering theme directories, both application-specific and general. Requires the `discovery` feature.

```APIDOC
## Discovery 
Requires `discovery` feature.
```rust
use opaline::{app_theme_dirs, theme_dirs};

let dirs = app_theme_dirs("myapp");             // Vec<PathBuf>
let dirs = theme_dirs();                        // Vec<PathBuf>
```
```

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

### Create Ratatui Text Elements with Theme

Source: https://hyperb1iss.github.io/opaline/guide/ratatui.html

Use the `Theme` object to create Ratatui's `Span`, `Line`, and `Text` types directly from theme keys.

```rust
use opaline::Theme;

let theme = Theme::default();

// Create styled text elements directly
let span: ratatui::text::Span = theme.span("keyword", "fn");
let line: ratatui::text::Line = theme.line("keyword", "let x = 42;");
let text: ratatui::text::Text = theme.text("keyword", "multi\nline\ntext");

// Gradient-colored text (requires `gradients` feature)
let grad: ratatui::text::Line = theme.gradient_text("aurora", "✦ Opaline");
```

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

### Ratatui Integration

Source: https://hyperb1iss.github.io/opaline/reference/api.html

Methods for integrating Opaline themes with Ratatui widgets. These methods are inherent on the `Theme` struct and require the `ratatui` feature.

```APIDOC
## Ratatui Integration 
Requires `ratatui` feature (default). No trait import needed; methods are inherent on `Theme`.
### Theme Methods 
```rust
// Colors/styles use Into conversions
let color: ratatui::style::Color = theme.color("token").into();
let style: ratatui::style::Style = theme.style("name").into();

// Or pass theme.style() directly to widget methods (via Into<Style>)
Block::bordered().style(theme.style("keyword"));

// Text type builders
theme.span("name", "text")             // ratatui::text::Span
theme.line("name", "text")             // ratatui::text::Line
theme.text("name", "text")             // ratatui::text::Text
theme.gradient_text("name", "text")    // ratatui::text::Line (gradients feature)
```

### Gradient Helpers 
Requires `ratatui` + `gradients` features. Low-level free functions take a `&Gradient` directly:
```rust
use opaline::{gradient_spans, gradient_text_line, gradient_bar, gradient_line};

let grad = theme.get_gradient("name").unwrap();

gradient_spans("text", &grad)               // Vec<Span>
gradient_text_line("text", &grad)            // Line
gradient_bar(width, '█', &grad)              // Line (block chars)
gradient_line(width, '─', &grad)             // Vec<Span>
```
```

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

### Ratatui Theme Integration

Source: https://hyperb1iss.github.io/opaline/reference/api.html

Use theme methods to convert tokens into Ratatui Colors and Styles. Pass styles directly to widget methods. Text type builders create various Ratatui text components.

```rust
let color: ratatui::style::Color = theme.color("token").into();
let style: ratatui::style::Style = theme.style("name").into();

Block::bordered().style(theme.style("keyword"));

theme.span("name", "text")             // ratatui::text::Span
theme.line("name", "text")             // ratatui::text::Line
theme.text("name", "text")             // ratatui::text::Text
theme.gradient_text("name", "text")    // ratatui::text::Line (gradients feature)
```

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

### Built-in Theme Loading and Listing

Source: https://hyperb1iss.github.io/opaline/reference/api.html

Requires the `builtin-themes` feature. Load themes by name or list all available built-in themes with their information.

```rust
use opaline::{load_by_name, list_available_themes, ThemeInfo};

let theme = load_by_name("nord").expect("builtin exists");
let themes: Vec<ThemeInfo> = list_available_themes();
```

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

### Generate Gradient Spans, Line, and Bar

Source: https://hyperb1iss.github.io/opaline/guide/ratatui.html

Utilize free functions like `gradient_spans`, `gradient_text_line`, and `gradient_bar` for low-level gradient control with Ratatui.

```rust
use opaline::{gradient_spans, gradient_text_line, gradient_bar};

let gradient = theme.get_gradient("primary").unwrap();

// Vec<Span>: each character colored along the gradient
let spans = gradient_spans("Hello!", gradient);

// Line: gradient-colored text
let line = gradient_text_line("Status: Online", gradient);

// Line: repeated block characters for progress bars
let bar = gradient_bar(40, '█', gradient);
```

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

### Programmatically Build a Theme

Source: https://hyperb1iss.github.io/opaline/reference/api.html

Construct a Theme object programmatically using the ThemeBuilder, specifying metadata, palettes, tokens, and styles.

```rust
use opaline::{OpalineColor, OpalineStyle, Theme, ThemeVariant};

let accent = OpalineColor::new(225, 53, 255);
let style = OpalineStyle::fg(accent).bold();

Theme::builder("name")
    .author("author")
    .variant(ThemeVariant::Dark)
    .version("1.0")
    .description("desc")
    .palette("accent", accent)
    .token("accent.primary", accent)
    .style("keyword", style)
    .build()                          // -> Theme
```

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

### Add owo-colors Dependency

Source: https://hyperb1iss.github.io/opaline/guide/owo-colors.html

Include the 'owo-colors' feature in your Opaline dependency to enable this adapter.

```toml
[dependencies]
opaline = { version = "0.4", features = ["owo-colors"] }
```

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

### Opaline with Gradients Only

Source: https://hyperb1iss.github.io/opaline/reference/features.html

This configuration enables only the core engine and gradient support, useful for non-Ratatui applications.

```toml
[dependencies]
opaline = { version = "0.4", default-features = false, features = ["gradients"] }
```

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

### Minimal Opaline Configuration

Source: https://hyperb1iss.github.io/opaline/reference/features.html

This configuration disables all default features, allowing you to explicitly select only the core engine functionality.

```toml
[dependencies]
opaline = { version = "0.4", default-features = false }
```

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

### Integrate CSS Generation into Build Process (Leptos/Yew/Dioxus)

Source: https://hyperb1iss.github.io/opaline/guide/css.html

Generate the CSS stylesheet during the build process and write it to a file, which can then be included in your web application.

```rust
// build.rs
let theme = opaline::Theme::default();
let css = opaline::generate_stylesheet(&theme);
std::fs::write("style/theme.css", css).unwrap();
```

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

### Global State Management

Source: https://hyperb1iss.github.io/opaline/reference/api.html

Functions for managing the global Opaline theme state, including loading, setting, and accessing the current theme. Requires the `global-state` feature.

```APIDOC
## Global State 
Requires `global-state` feature.
```rust
use opaline::{current, load_theme, load_theme_by_name, set_theme, Theme};

let theme = current();                          // Arc<Theme>
set_theme(Theme::default());                    // replace global theme
load_theme(path)?;
load_theme_by_name("dracula")?;                 // load builtin + set

// With app-level derivation callback
use opaline::load_theme_by_name_with;
load_theme_by_name_with("dracula", |theme| {    // load + derive + set
    theme.register_default_token("nav.bg", theme.color("bg.base").darken(0.1));
})?;

// App-specific discovery paths (requires `discovery` too)
use opaline::{
    load_theme_by_name_for_app,
    load_theme_by_name_for_app_with,
    load_theme_by_name_in_dirs,
};
load_theme_by_name_for_app("custom", "myapp")?;
load_theme_by_name_for_app_with("custom", "myapp", |theme| {
    theme.register_default_token("nav.bg", theme.color("bg.panel"));
})?;
load_theme_by_name_in_dirs("custom", [std::path::PathBuf::from("/tmp/themes")])?;
```
```

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

### ThemeSelector Widget with Derivation Callback

Source: https://hyperb1iss.github.io/opaline/guide/derivation.html

Configure the `ThemeSelectorState` with a derivation callback to include app-specific tokens in live theme previews.

```rust
let state = ThemeSelectorState::with_current_selected()
    .with_derive(derive_tokens);
```

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

### Load Ayu Themes in Rust

Source: https://hyperb1iss.github.io/opaline/themes/community.html

Loads the three variants of the Ayu theme: dark, mirage, and light. These themes are clean and focused, featuring warm accent tones.

```rust
let dark = opaline::load_by_name("ayu-dark").unwrap();
let mirage = opaline::load_by_name("ayu-mirage").unwrap();
let light = opaline::load_by_name("ayu-light").unwrap();
```

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

### Integrate OpalineStyle with Ratatui Widgets

Source: https://hyperb1iss.github.io/opaline/guide/ratatui.html

OpalineStyle implements `Into<Style>`, allowing direct use with Ratatui widget methods that accept `impl Into<Style>`.

```rust
use ratatui::widgets::Block;

// Works directly, no conversion needed
Block::bordered()
    .style(theme.style("keyword"))
    .border_style(theme.style("focused_border"));

// For Style::fg() / Style::bg(), use .into() on colors
use ratatui::style::Style;
let bg = Style::default().bg(theme.color("bg.base").into());
```

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

### Load Theme by Name with Derivation

Source: https://hyperb1iss.github.io/opaline/guide/derivation.html

Loads a builtin or discovered theme, runs a derivation callback, and sets it as the active global theme. Requires `global-state` and `builtin-themes`.

```rust
use opaline::load_theme_by_name_with;

load_theme_by_name_with("dracula", |theme| {
    // Derive app tokens here
})?;
```

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

### Render Gradient Text with Theme Method

Source: https://hyperb1iss.github.io/opaline/guide/gradients.html

The `theme.gradient_text()` method provides a high-level way to color text characters along a specified gradient, requiring no extra imports.

```rust
let theme = opaline::Theme::default();

// Per-character gradient coloring → Line
let line = theme.gradient_text("aurora", "Hello, Opaline!");
```

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

### Load Catppuccin Themes in Rust

Source: https://hyperb1iss.github.io/opaline/themes/community.html

Loads the four variants of the Catppuccin theme: Mocha, Macchiato, Frappé, and Latte. Use these for a soothing pastel aesthetic.

```rust
let mocha = opaline::load_by_name("catppuccin-mocha").unwrap();
let macchiato = opaline::load_by_name("catppuccin-macchiato").unwrap();
let frappe = opaline::load_by_name("catppuccin-frappe").unwrap();
let latte = opaline::load_by_name("catppuccin-latte").unwrap();
```

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

### Load Theme by Name in Rust

Source: https://hyperb1iss.github.io/opaline/themes

Use `opaline::load_by_name` to load a theme by its kebab-case identifier. 'default' is an alias for 'SilkCircuit Neon'.

```rust
let theme = opaline::load_by_name("catppuccin-mocha").unwrap();
let theme = opaline::load_by_name("rose-pine").unwrap();
let theme = opaline::load_by_name("tokyo-night-storm").unwrap();

// "default" is an alias for SilkCircuit Neon
let theme = opaline::load_by_name("default").unwrap();
```

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

### Names Module

Source: https://hyperb1iss.github.io/opaline/reference/api.html

Provides autocomplete-friendly constants for the standard theme contract, reducing the risk of typos.

```APIDOC
## Names Module

### Description
Autocomplete-friendly constants for the standard theme contract. Use these instead of raw strings for typo prevention.

### Usage
Import constants from `opaline::names::tokens`, `opaline::names::styles`, and `opaline::names::gradients`.

### Example
```rust
use opaline::names::{tokens, styles, gradients};

theme.color(tokens::ACCENT_PRIMARY)
theme.style(styles::KEYWORD)
theme.has_gradient(gradients::AURORA)
```

### Available Modules
- `names::tokens` (26 required constants)
- `names::styles` (13 required constants)
- `names::gradients` (5 constants)
```

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

### Load Monokai Pro Theme in Rust

Source: https://hyperb1iss.github.io/opaline/themes/community.html

Loads the Monokai Pro theme, famous for its dark appearance with hot pink keywords and green strings. Provides a vibrant coding experience.

```rust
let theme = opaline::load_by_name("monokai-pro").unwrap();
```

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

### Load and Access Theme Data

Source: https://hyperb1iss.github.io/opaline/reference/api.html

Load themes from various sources (default, string, file, name) and access colors, styles, and gradients by token or name. Supports checking for token existence and retrieving metadata.

```rust
use opaline::Theme;

// Construction
let theme = Theme::default();
let theme = Theme::builder("name").build();
let theme = opaline::load_from_str(toml, None)?;
let theme = opaline::load_from_file("path.toml")?;
let theme = opaline::load_by_name("dracula").expect("theme exists");

// Color access
theme.color("token.name")           // OpalineColor (fallback on miss)
theme.try_color("token.name")       // Option<OpalineColor>
theme.has_token("token.name")       // bool
theme.token_names()                 // Vec<&str>
theme.palette_names()               // Vec<&str>

// Style access
theme.style("name")                 // OpalineStyle (default on miss)
theme.try_style("name")             // Option<&OpalineStyle>
theme.has_style("name")             // bool
theme.style_names()                 // Vec<&str>

// Gradient access (requires `gradients` feature)
theme.gradient("name", 0.5)         // OpalineColor (fallback on miss)
theme.try_gradient("name", 0.5)     // Option<OpalineColor>
theme.get_gradient("name")          // Option<&Gradient>
theme.has_gradient("name")          // bool
theme.gradient_names()              // Vec<&str>

// Metadata
theme.meta.name                     // String
theme.meta.author                   // Option<String>
theme.meta.variant                  // ThemeVariant
theme.is_dark()                     // bool
theme.is_light()                    // bool

// Token injection (app-level derivation)
theme.register_default_token("name", color)   // insert if absent (TOML wins)
theme.register_token("name", color)           // unconditional overwrite
theme.register_default_style("name", style)   // insert if absent
theme.register_style("name", style)           // unconditional overwrite
```

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

### Default Opaline Configuration

Source: https://hyperb1iss.github.io/opaline/reference/features.html

This configuration enables the default features for Opaline, including built-in themes, gradients, and Ratatui support.

```toml
[dependencies]
opaline = "0.4"
```

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

### Apply Opaline Colors with ColoredExt

Source: https://hyperb1iss.github.io/opaline/guide/cli.html

Utilize `ColoredExt` to apply Opaline colors directly to strings, setting either the foreground or background color.

```rust
use opaline::{OpalineColor, ColoredExt};

let color = OpalineColor::new(225, 53, 255);
let fg_text = "electric purple".theme_fg(color);
let bg_text = "electric purple".theme_bg(color);
println!("{fg_text}");
println!("{bg_text}");
```

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

### Build Gradients Programmatically

Source: https://hyperb1iss.github.io/opaline/guide/gradients.html

Gradients can be constructed programmatically from a `Vec` of `OpalineColor`s. The `try_new` function allows for fallible construction, returning an `Err` for invalid inputs (e.g., an empty color vector).

```rust
use opaline::{Gradient, OpalineColor};

// From a Vec of colors
let gradient = Gradient::new(vec![
    OpalineColor::new(225, 53, 255),
    OpalineColor::new(128, 255, 234),
    OpalineColor::new(80, 250, 123),
]);

// Fallible construction
let result = Gradient::try_new(vec![]); // returns Err
```

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

### Inject Generated CSS via WebView (Tauri)

Source: https://hyperb1iss.github.io/opaline/guide/css.html

Generate the CSS stylesheet and inject it into the webview using `window.eval`. This method is suitable for Tauri applications.

```rust
let css = opaline::generate_stylesheet(&theme);
window.eval(&format!("
    const style = document.createElement('style');
    style.textContent = `{css}`;
    document.head.appendChild(style);
"))?;
```