opaline 0.4.1

A token-based theme engine for Rust applications
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

# Theme System

Opaline's theme system is built around a **three-layer resolution pipeline** that transforms raw hex colors into fully composed styles.

## The Resolution Pipeline

```mermaid
graph TD
    TOML["TOML File"] --> Parse["ThemeFile (serde)"]
    Parse --> Resolve["Resolver"]
    Resolve --> Palette["Palette<br/>Raw hex → OpalineColor"]
    Resolve --> Tokens["Tokens<br/>Semantic names → colors"]
    Resolve --> Styles["Styles<br/>fg + bg + modifiers"]
    Resolve --> Gradients["Gradients<br/>Multi-stop interpolation"]
    Palette --> Theme["Theme"]
    Tokens --> Theme
    Styles --> Theme
    Gradients --> Theme

    style TOML fill:#e135ff,color:#fff
    style Theme fill:#80ffea,color:#121218
```

### Layer 1: Palette

Raw named colors. These are the building blocks: hex values with human-readable names.

```toml
[palette]
purple = "#e135ff"
cyan = "#80ffea"
coral = "#ff6ac1"
bg_dark = "#121218"
```

### Layer 2: Tokens

Semantic references that point to palette colors. This is where meaning lives:

```toml
[tokens]
"accent.primary" = "purple"      # resolves to #e135ff
"accent.secondary" = "cyan"      # resolves to #80ffea
"bg.base" = "bg_dark"            # resolves to #121218
```

Tokens can reference other tokens. The resolver handles transitive lookups with cycle detection.

### Layer 3: Styles

Composed styles that combine a foreground color, background color, and text modifiers:

```toml
[styles]
keyword = { fg = "accent.primary", bold = true }
selected = { fg = "accent.secondary", bg = "bg.highlight" }
error_style = { fg = "error" }
```

Style `fg` and `bg` values reference tokens, which reference palette colors. Change the palette and everything downstream updates.

## Theme Structure

A complete Opaline theme TOML file has four 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...
```

## Loading Themes

```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();
```

## Strict Resolution

The resolver is intentionally strict. If a token references a palette color that doesn't exist, or a style references an undefined token, you get a clear error, not a silent fallback.

```rust
// This will error if "nonexistent" isn't in the palette
// "accent.primary" = "nonexistent"
// → OpalineError::UnresolvedToken { token: "accent.primary", reference: "nonexistent" }
```

Circular references are also detected:

```rust
// "a" = "b", "b" = "a"
// → OpalineError::CircularReference { chain: ["a", "b", "a"] }
```

## Variant Helpers

Every theme declares whether it's dark or light:

```rust
let theme = Theme::default();
assert!(theme.is_dark());

let latte = opaline::load_by_name("catppuccin-latte").unwrap();
assert!(latte.is_light());
```

This is useful for adapting UI elements that need variant-aware rendering (like borders or shadows).