DuskGrove

A modular, elegant dark & light VS Code color theme family inspired by twilight forest canopies.

Overview

DuskGrove is an atmospheric, deeply legible VS Code theme family inspired by twilight falling over evergreen woodland canopies. Designed with low eye fatigue and high semantic distinction in mind, it combines rich forest shadows with soft botanical and twilight tones.

DuskGrove ships 7 curated theme variants spanning dark, seamless, and daylight workspaces:

1. 🌲 DuskGrove - Forest — The flagship twilight canopy with distinct editor and sidebar surfaces.
2. 🍃 DuskGrove - Forest (Seamless) — Continuous deep forest canvas for borderless focus.
3. 🌊 DuskGrove - Ocean — Midnight abyssal blue depths with woodland syntax clarity.
4. 🐋 DuskGrove - Ocean (Seamless) — Seamless ocean floor canvas.
5. 🪻 DuskGrove - Lavender — Deep heather violet nightfall with calibrated brightened syntax.
6. 🔮 DuskGrove - Lavender (Seamless) — Seamless heather dusk canvas with unified paneling.
7. ☀️ DuskGrove - Forest Light — A soothing daytime woodland palette with high contrast and zero glare.

Visual Showcase

DuskGrove - Forest (Flagship)

Deep mossy forest shadows (#121810), pine bark sidebar (#1A2116), warm amber active highlights (#BE9E5F), and sage canopy text.

DuskGrove - Forest (Seamless)

Seamless canvas unifying the editor and sidebar for a distraction-free, borderless aesthetic.

DuskGrove - Forest Light (Day Mode)

Calibrated daylight palette with soft mint and lichen undertones (#DFE4DD), pine tree greens, and warm earth accents.

DuskGrove - Lavender & Lavender (Seamless)

Twilight violet shadows (#131018) paired with brightened heather syntax.

Theme Collection

Palette & Design Philosophy

DuskGrove uses a two-family syntax strategy that avoids random rainbow coloring:

• Warm Orange Family (#E2A06E keywords, #C97D46 tags, #D9B98A attributes) for declarative and structural constructs.
• Sage / Teal / Steel Family (#72B5A0 functions, #8FC9B8 types/classes, #82A6C0 strings, #C2CBA0 numbers) for referential and value-bearing tokens.
• Warm Neutral Slate (#A2A096) for variables, ensuring high identifier density reads naturally without overwhelming green saturation.
• Warm Amber Gold Accent (#BE9E5F) for workbench focus indicators, cursor, active tab borders, and split panel sashes.

Flagship Forest Palette Tokens

Optional: Italic Keywords, Types & Attributes

By default, DuskGrove strictly reserves fontStyle: "italic" for comments to maximize visual calm and avoid reading fatigue across primary code constructs. Rather than duplicating theme variants for cosmetic font styles, VS Code provides a native customization mechanism via editor.tokenColorCustomizations.

This is an optional, recommended addition to your personal settings.json if you prefer cursive/italic styling for declaration keywords, type definitions, and attributes.

Recommended settings.json Snippet

Add the following to your user settings.json (Cmd/Ctrl + Shift + P -> Preferences: Open User Settings (JSON)):

"editor.tokenColorCustomizations": {
  "textMateRules": [
    {
      "scope": [
        "storage",
        "storage.type",
        "storage.modifier",
        "keyword.other.import",
        "keyword.other.package"
      ],
      "settings": { "fontStyle": "italic" }
    },
    {
      "scope": [
        "entity.name.type",
        "entity.name.type.class",
        "support.type"
      ],
      "settings": { "fontStyle": "italic" }
    },
    {
      "scope": "entity.other.attribute-name",
      "settings": { "fontStyle": "italic" }
    }
  ]
}

Font Rendering & Cursive Comments

VS Code's TextMate rules only support fontStyle: "italic" | "bold" | "underline" | "strikethrough". Applying italic in VS Code renders whatever italic glyph design is built into your active editor font.

• Victor Mono (free, open source) features dedicated cursive script letterforms designed specifically for code comments and keywords.
• JetBrains Mono and Cascadia Code feature clean synthetic italic slants that pair seamlessly with DuskGrove.

Recommended Font Configuration (Victor Mono)

"editor.fontFamily": "Victor Mono, JetBrains Mono, monospace",
"editor.fontLigatures": true,
"editor.fontWeight": "500"

Architecture & Scalability

DuskGrove is structured so that color values exist in exactly one place: src/tokens/.

The build compiler (src/build/) transforms semantic tokens into:

1. Workbench UI colors (colors in themes/*.json) via uiMapping.ts.
2. TextMate syntax scopes (tokenColors in themes/*.json) via syntaxMapping.ts.
3. LSP semantic highlights (semanticTokenColors in themes/*.json) via semanticTokenMapping.ts.

src/
├── tokens/                     # SOURCE OF TRUTH (one file per variant)
│   ├── types.ts                # Strict ColorTokenSet TypeScript interface
│   ├── DuskGrove-dark.ts       # Flagship Forest palette
│   ├── DuskGrove-forest-light.ts# Forest Light palette
│   ├── DuskGrove-ocean.ts      # Ocean palette
│   ├── lavender.ts             # Lavender palette
│   └── index.ts                # Central variant registry array
├── build/                      # PURE COMPILER & MAPPING RULES
│   ├── colorUtils.ts           # HSL lighten/darken & alpha calculation
│   ├── uiMapping.ts            # Maps tokens to VS Code workbench colors
│   ├── syntaxMapping.ts        # Maps tokens to TextMate scopes
│   ├── semanticTokenMapping.ts # Maps tokens to LSP semantic tokens
│   ├── buildTheme.ts           # Assembles the full theme JSON
│   └── generate.ts             # CLI builder: compiles themes & updates package.json
└── validate/                   # QUALITY GATES
    ├── schema.ts               # Zod validation matching VS Code theme schema
    └── contrast.ts             # WCAG 2.1 relative luminance & contrast checks

Local Development

# 1. Install dependencies
npm install

# 2. Compile all theme variants deterministically
npm run build:themes

# 3. Run automated tests (compiler, schema, contrast)
npm test

# 4. Typecheck and lint
npm run typecheck
npm run lint
npm run format:check

# 5. Package extension (.vsix)
npm run package

Accessibility & WCAG Compliance

DuskGrove is engineered from the ground up for high readability and low eye strain:

• WCAG 2.1 AA Compliant: All body text maintains $\ge 4.5:1$ contrast against the editor background.
• De-emphasized Roles: Comments and UI chrome maintain $\ge 3.0:1$ non-text contrast.
• Automated Contrast Testing: Contrast ratios are continuously verified by mathematical tests in test/contrast.test.ts.

Security & Trust Properties

1. Zero Runtime Code: DuskGrove ships only static JSON theme definitions. No extension host JavaScript/TypeScript is executed at runtime.
2. Minimal Surface Area: All dependencies are devDependencies only and completely excluded from packaging via .vscodeignore.
3. Reproducible Builds: Themes are deterministically compiled from token definitions.

Documentation & Contributing

• 📖 Contributing Guide: Guidelines for contributing code, reporting issues, and authoring new variants.
• 📋 Production Release Checklist: Pre-flight checklist for releases and marketplace publication.
• 📝 Changelog: History of releases and notable updates following Keep a Changelog.
• 🤝 Code of Conduct: Community standards and expectations.

License

MIT © DuskGrove Contributors