Development

Development

Requirements

• Neovim 0.12 or newer
• StyLua
• Git

Format and test

Run the same checks used by CI from the repository root:

stylua --check .
./tests/run.sh

Apply Lua formatting with:

stylua .

The test runner starts a clean headless Neovim process for every file under tests/spec/.

CI coverage

CI runs:

• StyLua formatting validation
• The full test suite on Neovim 0.12.0
• The full test suite on Neovim stable
• An advisory full test run on Neovim nightly

Nightly failures do not block changes but can reveal upcoming compatibility work.

Repository areas

Path	Work type
lua/neotheme/themes/	Built-in palettes and transforms
lua/neotheme/highlights/	Core, Tree-sitter, LSP, and terminal behavior
lua/neotheme/integrations/	Optional plugin highlights
lua/neotheme/browser.lua	Family-first browser, transactions, layout, and lifecycle
lua/neotheme/commands.lua	User commands, output, validation, and completion
lua/neotheme/config.lua	Public options and defaults
lua/neotheme/palette.lua	Complete semantic schema and validation
tests/spec/	Behavioral contracts
docs/themes/	Checked-in family inventories, previews, and matrices
docs/vhs/	Reproducible live browser recording
assets/scripts/	Portable documentation asset tools

See Architecture for the runtime flow.

Theme changes

• Keep raw colors in theme definitions.
• Use semantic roles everywhere outside theme definitions.
• Supply every complete role, directly or through a transform.
• Register each public name with correct background metadata.
• Test palette completeness and selection, not exact curated hex values.

See Theme Authoring for the simplified model.

Highlight changes

• Put core, Tree-sitter, LSP, and terminal behavior under lua/neotheme/highlights/.
• Consume semantic palette roles rather than family-specific colors.
• Keep user typography options effective where the existing semantic category uses them.
• Add behavior-focused tests for important mapping and attributes.

See Highlight Groups for current coverage.

Integration changes

To add an integration:

1. Create a focused module under lua/neotheme/integrations/.
2. Add its key to NeothemeIntegrationOptions.
3. Add the default, set to false.
4. Add the key to the configuration validation schema.
5. Add the module name to the integration loader.
6. Test that enabling it defines representative groups without loading the plugin module.
7. Document the integration in the README and Integrations.

Test design

Prefer contracts that protect:

• Public registry and API behavior
• Palette completeness and validation
• Copy and mutation isolation
• Semantic role selection
• Typography options
• Highlight coverage for important categories
• Integration opt-in behavior
• Lualine palette refresh behavior
• Baseline, override, reset, reload, and exact-restoration transactions
• Browser navigation, cancellation, resource cleanup, and resize behavior

Avoid snapshots and per-theme exact color assertions unless a value itself is the public contract.

Documentation assets

The repository includes a portable family-asset pipeline:

./assets/scripts/generate-theme-assets.sh

Read assets/scripts/README.md for arguments, dependencies, check mode, regular-config capture behavior, and platform requirements.

The live browser recording uses the checked-in docs/vhs/neotheme-browser.tape and the alsi-lawr/vhs WebP capture fork.

Contributions

• Keep commits focused and use conventional commit messages.
• Explain user-visible behavior and compatibility effects.
• Report the exact commands used for verification.
• Keep unrelated formatting, renames, and cleanup out of a change.

The repository's CONTRIBUTING.md is the canonical contribution guide.