Gratia Moon

A quiet, semantic dark theme for Visual Studio Code.

Gratia Moon is the VS Code adapter for the @gratiaos/tokens design-token system.

It is designed around one principle:

UI chrome should whisper.
Syntax should speak.
Errors should interrupt.

Architecture

@gratiaos/tokens          # Authoring — where design lives
      │
      │  OKLCH → Style Dictionary
      ↓
adapters/vscode.mjs      # Adaptation — token architecture into VS Code theme
      │
      ↓
moon-dark-theme.json     # Distribution — generated artifact, never hand-edited
      │
      ↓
gratia-vscode-theme      # Packaging — publishes .vsix to Marketplace
      │
      ↓
Visual Studio Code       # Consumption — your editor, your code

This repository is not the source of truth.
It is a consumer and distribution layer.

Do not edit: themes/moon-dark-theme.json

It is generated by Style Dictionary from the canonical Moon tokens.
All changes to colors, semantic roles, syntax highlighting, controls, or contrast belong in:

👉 @gratiaos/tokens/tokens/moon/

What's included

• unified nocturnal canvas — editor, sidebar, and terminal share one surface
• semantic syntax highlighting for JavaScript, TypeScript, JSX, TSX, HTML, CSS, JSON, YAML
• terminal ANSI palette mapped to Moon semantic roles
• editor controls and interaction states (hover, focus, active, selected, disabled)
• semantic error / warning / info indicators
• contrast-aware semantic surfaces (foreground validated against WCAG AA on colored backgrounds)

Moon vocabulary

Editing rules

✅ Do

• modify Moon tokens in @gratiaos/tokens/tokens/moon/
• build the generated artifact (pnpm build:tokens)
• validate the generated theme in VS Code
• test in real source files (HTML, CSS, JSX, JSON, Markdown)

❌ Don't

• edit themes/moon-dark-theme.json
• introduce arbitrary HEX values into VS Code theme file
• add one-off syntax colors without a semantic role
• use color solely for decoration — every color must speak

Development

Prerequisites

Node.js 18+ and pnpm.

# Install dependencies
cd packages/tokens && pnpm install

# (Optional) Install VS Code extensions dependency
cd gratia-vscode-theme && pnpm install

Build the theme

From packages/tokens/:

pnpm build:tokens

This generates dist/vscode/moon-dark-theme.json from the OKLCH source tokens.

Sync into gratia-vscode-theme

cd gratia-vscode-theme && pnpm prepublishOnly

This copies packages/tokens/dist/vscode/moon-dark-theme.json into themes/.

Package and install

cd gratia-vscode-theme && npm run package

This produces gratia-moon.vsix. Install locally in VS Code via:

Extensions view (⌘⇧X) → ⋯ → Install from VSIX...

Install (Marketplace)

• Marketplace: gratiaos.gratia-moon

• CLI install:

  code --install-extension gratiaos.gratia-moon
  

Once installed, choose Gratia Moon from the Color Theme picker (⌘⇧P).

Credits

Gratia Moon is built on the same philosophy as the wider GratiaOS design system:

Every information that the eye must distinguish quickly gets enough contrast.
No token is colored because we like it. Every token speaks a role in the grammar.

If you find value in this work, consider supporting GratiaOS:
github.com/sponsors/GratiaOS

© GratiaOS. Licensed under AGPL-3.0.