theme

Documentation

Overview

Package theme holds the colour palette shared by the markdown renderer and the TUI chrome. Colours live here rather than being scattered as hex literals so that light and dark terminals can be served from one definition.

Index

• type Palette
  • func Dark() Palette
  • func Detect() Palette
  • func Light() Palette

Types

type Palette

type Palette struct {
	// Dark reports whether this palette targets a dark terminal background.
	// Renderers use it for the handful of decisions that cannot be expressed
	// as a colour, such as how far to tint a zebra stripe.
	Dark bool

	// Document body.
	Text  string // default prose
	Muted string // de-emphasised prose: URLs, captions, completed tasks
	Faint string // barely-there furniture: rules, table borders

	// Headings. Hierarchy is carried by weight and rules, so H1 and H2 share
	// Heading and only the accompanying rule differs; deeper levels step down
	// through HeadingSub to avoid a rainbow of competing hues.
	Heading    string
	HeadingSub string
	Rule       string // horizontal rules and heading underlines

	// Inline and block code.
	Code       string // inline code foreground
	CodeBg     string // inline code background pill
	CodeBlock  string // code block foreground fallback
	CodeFrame  string // code block border
	CodeLabel  string // language label in the code block frame
	CodeGutter string // line numbers

	// Syntax highlighting. These drive the chroma style, so that code colours
	// come from the same palette as everything else rather than from a
	// separately-tuned upstream theme that would drift from the document.
	SynKeyword  string
	SynType     string
	SynFunc     string
	SynString   string
	SynNumber   string
	SynComment  string
	SynVar      string
	SynConst    string
	SynOperator string
	SynPunct    string
	SynError    string

	// Links.
	Link    string // link label
	LinkURL string // raw URL when it has to be shown

	// Structure.
	Bullet      string // unordered list markers
	Number      string // ordered list markers
	TaskDone    string // ticked checkbox
	TaskTodo    string // unticked checkbox
	QuoteBar    string // blockquote left rule
	QuoteText   string // blockquote body
	TableHead   string // table header text
	TableBrd    string // table borders
	TableStripe string // zebra tint, empty to disable

	// Alert callouts, keyed to the GFM alert kinds.
	Note      string
	Tip       string
	Important string
	Warning   string
	Caution   string

	// TUI chrome.
	Accent            string // focus colour: active pane, selection, cursor
	Bg                string // content pane background, empty to inherit terminal
	SidebarBg         string
	HeaderBg          string
	Border            string
	SelBg             string // sidebar selection background
	SearchBg          string // search match background
	SearchFg          string // search match foreground
	CurrentBg         string // current search match background
	ScrollBg          string
	ScrollThumb       string
	ScrollThumbActive string
	Success           string // copy confirmation
	Error             string
}

Palette is the full set of colours used to paint a document and its chrome.

The fields are grouped by role, not by hue. Renderers should reach for the role they mean ("this is a heading rule") rather than picking a colour that happens to look right, so that a second palette can be swapped in without auditing every call site.

func Dark

func Dark() Palette

Dark is the default palette, tuned for dark terminals. The hues follow the One Dark family that the TUI chrome already used, with headings pulled onto a single warm accent so that depth reads as weight rather than colour.

func Detect

func Detect() Palette

Detect picks a palette for the current terminal.

TERMD_THEME (dark|light) wins when set, because background probing is unreliable over SSH and inside multiplexers that swallow the OSC 11 reply. Otherwise termenv is asked, which falls back to assuming dark when it cannot tell — the safer guess, since dark terminals are the common case and a dark palette on a light background merely looks washed out rather than vanishing.

func Light

func Light() Palette

Light is the counterpart for light terminals. It is not a mechanical inversion of Dark: contrast ratios on white need darker, less saturated foregrounds than a straight flip would give.