NJF Theme
GitHub Dark's interface with expressive Primer syntax colours: yellow functions,
green classes, orange strings, pale blue variables, and purple keywords.
This is an independent custom theme. It deliberately retains the curated
legacy Primer palette used by the original editor customisations.
The editor uses GitHub charcoal #24292e, the original working syntax palette,
and purple UI accents. Each named syntax colour meets a minimum 4.5:1
contrast ratio against the normal editor background. This check does
not assess selected text, diagnostics, or every inherited workbench colour.
Try it locally
Use Node.js 22 or later. There are no build or runtime package dependencies.
npm run build
npm run check
Open the repository in VS Code and press F5. This builds the theme and
launches an Extension Development Host. In that window:
- Run Preferences: Color Theme and choose NJF Theme.
- Open
examples/highlighting.py.
- Enable Python/Pylance in that window and let its analysis finish.
Run npm run watch in the original window while adjusting colours. VS Code
reloads edited theme files.
Any older .vsix files in the working directory are historical builds.
npm run package generates the current njf-theme-0.1.5.vsix.
Install in your regular VS Code window
F5 only loads the source in the Extension Development Host. It does not
replace an old NJF Theme installed in your regular VS Code windows. To do that,
use the vsce packaging CLI and the VS Code code command:
npm run package
code --install-extension ./njf-theme-0.1.5.vsix --force
Run Developer: Reload Window, then choose NJF Theme.
The installed extension should report version 0.1.5. Rebuild and reinstall
after changing the source; selecting the same theme name alone cannot load
uninstalled changes.
How the highlighting works
The palette reserves distinct colours for useful symbol roles:
| Role |
Colour |
| Functions and methods |
Yellow |
Classes, types, and decorators (including @) |
Green |
| Strings and docstrings |
Orange |
| Regular expression text, prefixes, and quotes |
Blue |
| Regex escapes, anchors, groups, and quantifiers |
Yellow |
| Variables, parameters, and properties |
Pale blue |
| Modules and namespaces |
Coral |
| Constants, enum members, and escapes |
Stronger blue |
Keywords and word operators (and, or, not, is, in) |
Purple |
| Symbolic operators, punctuation, and brackets |
Neutral foreground |
| Comments |
Muted grey, italic |
Numbers retain pale blue. Modules have a distinct coral accent,
while brackets use a single neutral colour at every nesting level.
Regex colouring follows the grammar's regex scopes. VS Code's bundled Python
grammar treats raw strings as regexes; this is syntax highlighting, not an
inference that every raw string is used as a pattern. Ordinary strings and
their escapes keep their separate orange/blue palette.
Pylance can classify special typing forms such as ClassVar, Final, and
Protocol as variables. When it adds the typeHint modifier in an annotation,
NJF colours that use green. Bare variable tokens, including these names in
imports, remain pale blue: themes cannot distinguish them from ordinary
variables without a more specific token or modifier. A base-class reference
such as Named(Protocol) can also remain blue if Pylance emits no type modifier.
VS Code first applies grammar-based TextMate colours, then semantic colours
from the language server. This theme supports both:
- Semantic rules colour functions, methods, classes, parameters, modules,
and constants by their meaning, including imported symbols that Pylance can
resolve. Pylance-specific rules also cover
self, cls, decorators, dunder
methods, built-in constants, and punctuation.
- TextMate rules colour strings, docstrings, keywords, and other syntax,
and provide useful highlighting while semantic analysis is unavailable.
Generic semantic rules also apply to other languages. The GitHub base retains
its Markdown, diff, and other language-specific rules, with explicit NJF regex
overrides.
A theme can only style the token information a grammar/language server provides.
If an imported symbol cannot be resolved, its colour may change once Pylance
can identify it. Broad containers such as meta.function.python are deliberately
avoided: they can colour the arguments and punctuation along with a function.
To compare the fallback, temporarily disable semantic highlighting in the
development window. Restore Editor: Semantic Highlighting Enabled to
configuredByTheme afterwards. Developer: Inspect Editor Tokens and Scopes
is still useful for exceptions, rather than being the main editing workflow.
Edit the theme
| File |
Purpose |
src/colors.js |
Named Primer colours and syntax roles |
src/syntax.js |
Semantic selectors and targeted TextMate fallback rules |
src/theme.js |
Small set of UI overrides on the GitHub base |
src/generateTheme.js |
Writes the theme JSON file |
vendor/github-dark.json |
Versioned, unmodified GitHub Dark base |
themes/*.json |
Generated files loaded by VS Code; do not edit directly |
examples/highlighting.py |
Visual specimen for declarations, imports, calls, and strings |
Change a role such as function once in src/colors.js; both token systems
use it. Colours are curated literal values with provenance, so an upstream
package update cannot silently turn a pale yellow into a dark ochre.
npm run check verifies that generated files are current, includes resolve,
the base snapshot matches its recorded hash, core UI text is readable, and all
NJF syntax foregrounds meet 4.5:1 contrast on the editor background. It does
not replace a visual check with a running language server.
Update the GitHub base
Ordinary builds are offline and do not depend on another installed extension.
To deliberately refresh the base, install the official GitHub Theme extension,
then point the import command at its directory:
npm run update:base -- /path/to/github.github-vscode-theme-VERSION
npm run build
npm run check
Review the vendor diff and update the version in THIRD_PARTY_NOTICES.md before
committing. The importer selects the legacy GitHub Dark variant used by
the original customisations, copies its license, and records its version and
SHA-256. If GitHub removes that variant, choosing a replacement is an explicit
design change.
Use alongside existing settings
The old settings under editor.tokenColorCustomizations["[GitHub Dark]"] can
stay in place: they target the official GitHub theme, not NJF Theme.
Global or NJF-scoped user/workspace customisations can still override the theme.
No changes to personal settings or installed extensions are needed for F5.
When packaging with VS Code's vsce tooling, the vscode:prepublish hook builds
and checks the theme. Source scripts, examples, dependencies, temporary comparison
files, and old VSIX files are excluded; theme JSON and third-party licenses are
included. The registered Marketplace publisher is njf, giving the extension
the identifier njf.njf-theme.
Publishing
The Package and publish theme GitHub Actions workflow builds, checks, and saves
an installable VSIX on pushes to main. To publish, run the workflow manually
on main and enable its publish input. Increase package.json and
package-lock.json versions before publishing a version that already exists.
Publishing uses Marketplace Trusted Publishing, without a stored access token.
Configure this policy once under publisher njf at
Manage Publishers:
| Field |
Value |
| Policy name |
NJF Theme releases |
| Repository owner |
njf0 |
| Repository |
njf-vscode-theme |
| Workflow |
publish.yml |
| Environment |
Leave empty |
For a private repository, run publishing within 48 hours of creating the policy
to activate it. The workflow does not publish automatically on ordinary pushes.
Companion terminal themes
NJF Themes provides ready-made iTerm2 and
Windows Terminal / WSL downloads. Those terminal themes follow Primer's current
official dark ANSI palette; this VS Code theme retains its customised syntax
palette. Their colours are documented independently rather than silently synced.
References