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

# Token Contract

Every builtin theme must define a minimum set of semantic tokens, styles, and gradients. This contract ensures that consuming applications can rely on these names existing in any theme.

## Required Tokens (26)

These tokens must be present in every builtin theme:

### Text (4)

```
text.primary
text.secondary
text.muted
text.dim
```

### Background (5)

```
bg.base
bg.panel
bg.code
bg.highlight
bg.selection
```

### Accent (4)

```
accent.primary
accent.secondary
accent.tertiary
accent.deep
```

### Status (4)

```
success
error
warning
info
```

### Border (2)

```
border.focused
border.unfocused
```

### Code (7)

```
code.keyword
code.function
code.string
code.number
code.comment
code.type
code.line_number
```

## Required Styles (13)

```
keyword
line_number
selected
active_selected
focused_border
unfocused_border
success_style
error_style
warning_style
info_style
dimmed
muted
inline_code
```

## Required Gradients (5)

```
primary
warm
success_gradient
error_gradient
aurora
```

## Name Constants

The `opaline::names` module provides compile-time constants for every required token, style, and gradient:

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

// tokens::TEXT_PRIMARY      → "text.primary"
// styles::KEYWORD           → "keyword"
// gradients::AURORA          → "aurora"
```

Use these instead of raw strings for autocomplete support and typo prevention.

## Enforcement

The contract is enforced by integration tests in `tests/builtins_tests.rs`. Every builtin theme is loaded and checked for all required tokens, styles, and gradients.

```rust
// From builtins_tests.rs
#[test]
fn all_builtins_have_required_tokens() {
    for &(id, _) in builtins::builtin_names() {
        let theme = builtins::load_by_name(id).expect("loads");
        for &token in REQUIRED_TOKENS {
            assert!(
                theme.has_token(token),
                "theme '{id}' missing required token: {token}"
            );
        }
    }
}
```

## Adding Tokens to Your Theme

If you're creating a custom theme, you don't need to satisfy the full contract; it's only enforced for builtins. However, following the contract ensures your theme works with any Opaline-powered app. Domain-specific semantics such as git status colors, diff colors, and mode indicators should be derived by the consuming app instead of being treated as core contract names.

Use the [custom themes template](../guide/custom-themes) as a starting point.