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

# Tokens

Tokens are the **semantic layer** between raw palette colors and composed styles. They give meaning to colors: `accent.primary` means "the main accent color" regardless of whether it's purple, blue, or green.

## Token Namespaces

Opaline's core token contract defines 26 tokens across 6 namespaces:

### Text

| Token            | Purpose             |
| ---------------- | ------------------- |
| `text.primary`   | Main body text      |
| `text.secondary` | Less prominent text |
| `text.muted`     | De-emphasized text  |
| `text.dim`       | Very subtle text    |

### Background

| Token          | Purpose                     |
| -------------- | --------------------------- |
| `bg.base`      | Main background             |
| `bg.panel`     | Panel/sidebar background    |
| `bg.code`      | Code block background       |
| `bg.highlight` | Highlighted line background |
| `bg.selection` | Selection background        |

### Accent

| Token              | Purpose                                |
| ------------------ | -------------------------------------- |
| `accent.primary`   | Main accent (keywords, active states)  |
| `accent.secondary` | Secondary accent (functions, links)    |
| `accent.tertiary`  | Third accent (types, special elements) |
| `accent.deep`      | Deep/saturated accent for emphasis     |

### Status

| Token     | Purpose              |
| --------- | -------------------- |
| `success` | Success states       |
| `error`   | Error states         |
| `warning` | Warning states       |
| `info`    | Informational states |

### Border

| Token              | Purpose                |
| ------------------ | ---------------------- |
| `border.focused`   | Focused panel border   |
| `border.unfocused` | Unfocused panel border |

### Code

| Token              | Purpose           |
| ------------------ | ----------------- |
| `code.keyword`     | Language keywords |
| `code.function`    | Function names    |
| `code.string`      | String literals   |
| `code.number`      | Numeric literals  |
| `code.comment`     | Comments          |
| `code.type`        | Type names        |
| `code.line_number` | Line numbers      |

## Accessing Tokens

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

### Name Constants

Use the `names` module for autocomplete-friendly constants instead of raw strings:

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

All 26 required tokens, 13 required styles, and 5 required gradients have corresponding constants.

## App-Specific Tokens

Git status colors, diff colors, mode indicators, file path/hash colors, and similar domain-specific semantics are intentionally **not** part of Opaline's core contract. Consumer apps should derive those from the generic token set with `register_default_token()` / `register_default_style()`.

## Token Resolution

Tokens resolve through the palette. A token value is a palette key:

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

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

Tokens can also reference other tokens (transitive resolution):

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

The resolver detects circular references and reports them as errors.