Grimley Spectrum

Grimley Spectrum v0.5.1 combines a Midnight Violet VS Code interface with distinct language palettes and an offline Color Studio. The extension keeps the original developermp.grimley-spectrum identifier and Grimley Spectrum Dark theme. MIT licensed, with no telemetry, runtime dependencies or network requests.

Install

Requires VS Code desktop 1.85 or later. Install the local VSIX, then choose Preferences: Color Theme → Grimley Spectrum Dark:

code --install-extension ./grimley-spectrum-0.5.1.vsix --force

To build from source (Node.js 22 or later):

npm ci
npm test
npm run validate
npm run package

Build dependencies require network access on first installation; the installed extension works offline. Packaging never publishes the extension.

Color Studio

Run Grimley Spectrum: Open Color Studio from the Command Palette. Select a language, then edit its hexadecimal RGB fields (#RRGGBB) or color pickers. Invalid fields show feedback and disable Save, Apply and Export. Reset beside a category restores its selected preset color.

The compact Midnight Violet layout places configuration beside a sticky preview on wide panels. Categories and code scroll independently; narrow panels use natural vertical scrolling. Search filters category names without changing draft colors, including hidden edits. The preview toolbar can wrap long lines. Category descriptions and preset defaults are available to assistive technology and through label tooltips.

The sample and color legend update immediately. The preview uses a small approximate lexical highlighter, not VS Code's TextMate grammars or semantic engine. Some examples, especially HTML and CSS, illustrate only a subset of categories; the legend displays every configurable color. Use Open Sample in Editor to open the selected language’s bundled sample beside Studio and inspect the authoritative highlighting. React, SCSS, Less and JSONC selections share the existing base-language sample; the file’s native language mode applies.

• Apply to editor updates global, theme-specific token settings. It does not save Studio preferences.
• Save preferences persists the current palette in extension globalState. It does not apply editor changes.
• Discard edits reloads saved preferences. It does not undo an earlier Apply; apply the restored preferences to do that.
• Balanced, Vibrant and Minimal preview different saturation and emphasis, preserving language identities. Preset replacement requires confirmation and changes only the draft until Save or Apply.
• Reset Current Language and Reset All Defaults replace draft colors after confirmation. Reset all selects Balanced. Use Save and Apply separately to persist and render the result.
• Remove applied rules removes only unchanged extension-managed rules and keeps saved palettes. Other user theme settings remain.
• Export writes the valid current draft to JSON using a native file dialog.
• Import validates a JSON file, summarizes its preset/language count and asks before replacing the draft. Save and Apply remain explicit actions.

The primary action is Apply to Editor, followed by Save Preferences. Undo, Redo and Discard Changes remain directly accessible. The native Advanced actions disclosure groups Export/Import above destructive resets and removal. Destructive draft replacement uses confirmation dialogs.

Undo/Redo retain up to 100 draft snapshots across language switches. Repeated valid input events coalesce until focus leaves that input. Category resets, language resets, all-default resets, presets and import previews are undoable. New edits clear Redo. Save and Apply do not clear history or become undoable settings operations. Discard clears history and reloads saved preferences. Switching Syntax Colors / VS Code UI preserves the complete draft. Webview state can restore a validated draft when VS Code retains the panel; a new panel loads saved preferences. History starts fresh on panel restoration. Save before closing a panel.

Use Tab/Shift+Tab to navigate labels, controls and focusable scroll regions; Enter/Space opens Advanced actions and activates buttons. Undo uses Ctrl+Z (Cmd+Z on macOS); Redo uses Ctrl+Shift+Z/Cmd+Shift+Z or Ctrl+Y. These shortcuts operate only inside the webview, and focused text/color inputs retain native editing shortcuts. Undo/Redo buttons are available while editing inputs. Focus rings, input validation announcements and live status text support keyboard and assistive technology workflows. Reduced-motion preferences are respected.

The header independently reports Saved / Unsaved Changes and Applied / Not Applied. Applying, Conflict Detected and Error describe in-progress or failed operations. Saving never means applied; applying never means saved. Reopening verifies owned settings against the persisted receipt. External changes reverify ownership: unrelated changes retain Applied; modified managed rules produce Conflict Detected. Detailed notices appear below the actions. Applied means the draft matches verified global managed rules; workspace overrides, other selectors and the active theme can still affect actual rendering. Apply warns about workspace customization settings.

UI Studio

Color Studio has two compact navigation buttons: Syntax Colors and VS Code UI. The existing command grimleySpectrum.openColorStudio, language palettes, syntax presets, previews and settings remain compatible. Navigation preserves unsaved edits. Save Preferences and Export include both sections; Apply to Editor applies only the currently selected section. Apply each section separately when importing a complete configuration.

VS Code UI offers 89 documented color identifiers in nine searchable, collapsible groups: Editor, Sidebar and Explorer, Activity Bar, Tabs, Status Bar, Terminal (including 16 ANSI colors), IntelliSense, Panels and Menus, and Search and Diagnostics. Each entry has a labeled native picker, an RGB/RGBA hex field (#RRGGBB or #RRGGBBAA), a swatch and Theme Default reset. Empty fields mean no Studio override. The picker preserves an existing alpha suffix; edit hex to change transparency. Labels show identifiers as tooltips, and help text distinguishes explicit drafts, known global user overrides, bundled theme defaults and unknown defaults with simulation fallbacks. Some transparent selection/search colors should retain alpha to keep decorations visible.

The lightweight HTML/CSS workbench simulation includes activity icons, an Explorer file tree, tabs, an editor, selection/cursor, suggestions, a terminal and status bar. Representative surfaces respond immediately to draft edits. It is an illustrative simulation, not the actual workbench; menus, diagnostics, debug/warning states and every ANSI color are not all rendered simultaneously. No Monaco, remote assets or frontend framework is used.

Choose Midnight Violet, Deep Ocean or Obsidian to preview a coherent UI mapping after confirmation. Presets and group resets affect UI drafts only; syntax presets and resets affect syntax drafts only. Reset UI to Preset restores the selected preset, while Use Theme Defaults clears draft overrides. These changes enter the shared bounded Undo/Redo history and require explicit Apply and Save.

UI Apply safely merges into global User workbench.colorCustomizations under [Grimley Spectrum Dark]. It preserves global entries, other theme blocks and unrelated keys in the Grimley block. It never changes the active theme or writes workspace settings. Workspace/folder overrides trigger a warning because they may prevent global values from taking effect. Select Grimley Spectrum Dark to see the applied colors.

Remove Applied UI Colors removes only values that still match the extension's ownership receipt. It does not remove syntax rules or saved preferences. Removal refuses to delete externally changed values. Release UI Ownership leaves settings untouched and stops managing them. A subsequent explicit Apply can replace these retained values through the overwrite workflow below.

UI writes maintain a separate recovery journal for settings and ownership receipts. Failed operations attempt conditional rollback; failed rollback retains the journal. Reopening a new Studio panel attempts recovery only when current settings equal the recorded before or after object. Later edits remain untouched and pending operations block new Apply/removal. These multi-step operations are best effort, not atomic; VS Code has no compare-and-swap API and simultaneous manual edits can still race.

Complete exports use schemaVersion 2, preserving the original activePreset and languages fields and adding ui: { preset, colors }. Only allowlisted color keys and valid hex values are accepted, with a 1 MiB import limit. Schema 1 files remain importable, fill missing syntax entries from their selected syntax preset, and preserve the current UI draft. Schema 2 imports replace both draft sections after confirmation. Import never changes saved preferences or settings until Save/Apply. Empty UI colors intentionally mean theme/user defaults. Existing schema 1 stored preferences load without being rewritten until Save.

UI limitations and verification

The public API exposes configured settings, not fully resolved effective theme colors. Studio does not claim to resolve theme inheritance, wildcard theme overrides, workspace overrides or all platform-specific rendering. Known global values and bundled defaults inform the simulation; unknown defaults are labeled. Native menus/window chrome, icon shapes, layout and font choices are outside this color editor; some identifiers affect only particular states or VS Code versions. The official VS Code theme color reference describes identifier scope and platform limitations. The extension remains compatible with VS Code 1.85; newer optional rendering behavior is not required.

Automated tests cover UI validation, presets, schema migration/round trips, preview resolution, shared history/resets, syntax/UI isolation, theme-scoped merges, external conflicts, workspace warnings, write/state failures, rollback failure and interrupted recovery. These tests use pure state operations and a mocked configuration API. Manual VS Code verification remains necessary for visual layout at different panel sizes, keyboard/screen-reader behavior, native color pickers, real settings precedence, and Extension Development Host rendering.

Replacing existing colors and restoring settings

Clicking Apply to Editor authorizes replacement of the requested colors, including previous user preferences and manually changed managed colors. Existing unrelated colors, other theme blocks, unrelated syntax rules and settings remain intact. There is no need to clean settings.json manually. Syntax Apply submits the complete language palette; UI Apply submits the UI draft. Draft resets, previews, Save and import do not write editor settings.

grimleySpectrum.confirmColorOverrides defaults to true. When requested colors conflict with existing values, one native modal lists the affected properties/scopes and values before replacement. Replace colors proceeds; Cancel leaves settings and snapshots untouched. Set it to false to apply immediately. New values, unchanged colors and routine updates to unchanged Studio-owned colors need no overwrite dialog. Settings that have been deleted externally are recreated without an overwrite prompt. Removal of externally modified values remains protected.

Use Advanced actions → Restore Previous UI Settings or Restore Previous Syntax Settings to restore the most recent successful settings-changing operation in that section. Snapshots persist locally in extension globalState and record affected setting paths, previous/applied values, Global configuration scope, [Grimley Spectrum Dark], a timestamp and the previous management receipt. They are separate from draft Undo/Redo and saved preferences. An unchanged Apply retains the existing snapshot. Restoration consumes the snapshot; this is a single previous operation per section, not a complete settings backup or a history browser.

Restoration verifies every affected value before writing and merges previous values into current settings, preserving later edits to unrelated object properties and other themes. If an affected value changed externally, restoration reports a conflict and makes no changes. TextMate arrays are guarded as a whole because ordering affects highlighting: any later edit to that array blocks automatic restoration, including adding an unrelated rule. Preserve/export your current settings and reconcile that array manually in that case. Snapshots do not capture workspace settings, theme defaults, settings from other profiles/machines or every historical preference. Removing applied colors deletes managed overrides; use Restore to recover the preferences replaced by the latest Apply.

All writes use the official VS Code configuration API at Global/User scope. Workspace and workspace-folder settings are inspected for warnings and never written; they can override global colors, so Applied confirms the global receipt rather than effective rendering. Choose Grimley Spectrum Dark to see theme-scoped changes. Writes are checked after completion and unchanged settings are not rewritten. Multi-setting application and restoration use best-effort conditional rollback and persisted recovery journals; they are not atomic. Reopening Studio attempts safe recovery, while later conflicting edits are preserved and leave recovery pending. Concurrent edits can race because VS Code provides no compare-and-swap settings API.

Languages and mappings

Python, JavaScript, JavaScript React, TypeScript, TypeScript React, Rust, Go, PHP, C, C++, Java, HTML, CSS, SCSS, Less, JSON and JSON with Comments (JSONC) each have a separate palette using real VS Code language IDs. TextMate root scopes and leaf scope families were inspected in the installed VS Code grammars; tests/grammar-evidence.json records their locations. src/colorStudio/catalog.json is the mapping and sample catalog.

Programming languages expose grammar-backed categories and semantic categories such as declarations, classes, interfaces, structs, parameters and properties. Semantic-only categories are labeled Semantic provider required. The presence of a selector does not guarantee a language provider emits it: for example PHP does not expose a struct token in typical providers. No language is claimed to have complete category coverage. Rust macros and C/C++ preprocessor directives have specific grammar mappings.

HTML uses tags, attributes, strings, entities, comments and punctuation. CSS uses selectors, properties, values, functions, units, variables, strings, numbers, comments and punctuation where present in each grammar. JSON uses keys, strings, numbers, literals, and punctuation. The bundled JSON grammar assigns the same constant.language scope to booleans and null, so they intentionally share a color; independent boolean/null colors are unavailable through these public settings. Strict JSON has no comment category; JSONC does.

The restored Balanced theme uses blue/gold/lavender/teal in Python, violet/gold/cyan/green in JavaScript, copper/gold/lavender/teal in Rust, violet/gold/lavender/cyan/green in PHP, and distinct C and C++ accents. Punctuation stays neutral and comments remain readable. User-selected colors are unrestricted; their contrast is the user's choice.

VS Code limitations and configuration safety

Semantic selectors target language IDs (function.declaration:typescript, for example). They require enabled semantic highlighting and a provider that emits those token types/modifiers. Studio does not install language servers or override the user's semantic-highlighting enablement. Semantic rules take precedence over grammar colors when available.

TextMate selectors target grammar scope ancestry, not arbitrary language IDs. The catalog uses specific roots and subtracts known derived roots to separate JavaScript/JSX, CSS/SCSS/Less and JSON/JSONC. Alternative grammars and embedded regions can use different scopes; snippets/JSONL are excluded from JSON customization. Unidentified expressions, calls, attributes or types cannot be independently colored. Use Developer: Inspect Editor Tokens and Scopes to investigate actual coverage. The extension never adds unsupported language override settings.

Apply uses editor.tokenColorCustomizations and editor.semanticTokenColorCustomizations inside [Grimley Spectrum Dark], preserving other themes, top-level settings and unrelated rules. Explicit Apply can replace existing foregrounds for exact requested TextMate scopes and language-qualified semantic selectors. Mixed-scope rules retain their unrelated scopes, and font styles/semantic metadata are preserved. Python selectors do not target JavaScript or PHP. Broader selectors and wildcard theme blocks may still affect rendering without being detectable as direct collisions. Removal stays conservative and refuses to delete modified managed rules.

Syntax settings writes are two separate public API operations. A journal and conditional rollback protect interrupted updates; reopening attempts recovery only when affected objects still match the recorded before/after values. VS Code provides no atomic compare-and-swap settings transaction, so simultaneous settings edits are a remaining limitation. Back up settings before manually resolving a journal conflict. Workspace and folder settings are never written. Saved preferences are authoritative in globalState; ownership and applied-state records describe editor settings, not a second editable palette store. Schema version 1 imports allow partial language/category objects, fill missing colors from the selected preset, and reject unknown fields, IDs, versions and invalid RGB values. Corrupt stored palettes load Balanced without silently overwriting storage.

Development and validation

The command activates the extension on demand. There is no startup palette application. Vanilla TypeScript, local CSS, nonce-based scripts, restrictive CSP and validated messages keep the webview small. Inline style attributes are allowed only for color swatches/token spans; scripts prohibit inline execution without the nonce, unsafe-eval and network resources. Untrusted strings are rendered with textContent.

npm test compiles both host and webview and exercises bounded/coalesced history, undo/redo branches, draft/saved/applied statuses, input normalization, category filtering, import/discard boundaries, failed-write rollback, external ownership verification, validation, preset serialization, malformed recovery, mappings, settings merging, reset, ownership conflicts and message validation. npm run validate checks theme structure, duplicate JSON keys, colors and selectors. Host integration tests use a mocked VS Code API; they do not represent visual or full Extension Development Host tests.

Open the project and press F5, choose the theme, invoke Color Studio, and compare applied colors with samples/. Visual integration has not been verified in a running VS Code Extension Development Host.

License

MIT. See the included LICENSE file.

PHP modifiers (final, abstract, public, private, protected, static, readonly) belong to Keywords. The installed PHP grammar gives them storage.modifier.php ancestry (with inheritance, visibility, static or readonly leaf scopes), matched by source.php storage.modifier. Balanced uses #C4A5EA; editing Keywords updates the preview, and Apply writes this scoped TextMate rule plus keyword:php. Semantic readonly selectors describe readonly variables/properties, not the readonly keyword. Providers that classify a modifier differently, more specific user rules, and workspace settings can override Keywords. The lexical preview does not reproduce grammar context, interpolation or semantic precedence.