Design Language

Railscasts is a port, not a reinterpretation. Its goal is to preserve the Railscasts/TextMate hierarchy while giving modern Neovim concepts—Tree-sitter, LSP tokens, diagnostics, completion, and plugin UI—a coherent role in that language.

Character

• Surface first: quiet charcoal provides a stable stage for code.
• Readable text: warm cream is the default reading color, not pure white.
• Muted context: earthy brown comments and metadata remain subordinate to code.
• Focused accents: saturated colors identify syntax, change state, diagnostics, and the active editing mode.

The theme deliberately avoids treating every category as equally bright. Bright accents signal an action, state, or code role; large accent backgrounds are reserved for selections and active mode segments.

Semantic hierarchy

Role	Meaning	Railscasts treatment
Primary text	Ordinary reading, punctuation, variables	warm cream
Strong text	Titles and emphasis	near-white
Muted text	Comments, dates, metadata	light brown
Functions	Calls, methods, tags	light orange
Keywords	Control flow and directives	dark orange
Strings	Literal text and paths	light green
Numbers	Numeric literals	moss green
Booleans	Boolean and built-in constants	blue
Properties, members, and labels	Object keys, fields, symbols, and labels	soft lavender (purple)
Types and constants	Named types and constant identifiers	red
Added/changed/deleted	Git and diff state	green / cyan / red
Diagnostics	Error/warning/info/hint	red / orange / blue / cream

New integrations should link their groups to these existing roles rather than introducing a plugin-specific color. This keeps a picker, file explorer, Git view, and core editor readable as one system.

Modes and states

The active Lualine segment uses black text on a mode accent. Adjacent mode segments invert the relationship with an accent foreground on black.

Mode	Accent	Why
Normal	light green	calm default editing state
Insert	dark orange	active text entry
Visual	cyan	selection and transformation
Replace	yellow	high-attention overwrite state
Command	red	explicit command state

Search is yellow on the base background. Completion and selected list items use light green on black. These are intentional high-attention states, not general surfaces.

Modern Neovim mapping

Classic Vim groups provide the semantic base. Tree-sitter captures and LSP semantic tokens link back to that base: for example, @function and @lsp.type.function use the Function role, while @string and @lsp.type.string use the String role. This avoids language-server and parser output drifting away from ordinary syntax highlighting.

Properties and object keys

Tree-sitter @property, @variable.member, and legacy @field captures use the existing lavender purple token (#D0D0FF). LSP @lsp.type.property follows the same role, including TypeScript interface keys. This keeps keys visually separate from red types and constants, orange keywords/functions, and green string values without adding a palette color.

Language-specific key styling remains intentional: JSON @label.json stays green, while YAML and existing schema/configuration field overrides retain their established function color.

FzfLua's live-search prompt and current-buffer marker use the Function role; the alternate-buffer marker uses Comment. This keeps these interactive indicators within the palette while making the current buffer more prominent.

Accessibility and fidelity

The default palette favors the historical Railscasts character. The opt-in high-contrast option brightens muted text and active dark-green surfaces while preserving every role's meaning. See Accessibility for the contrast rationale and Palette for exact values.