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

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:

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:

[palette]
electric_purple = "#e135ff"

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

Tokens can also reference other tokens (transitive resolution):

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

The resolver detects circular references and reports them as errors.