From site rework to a full theme

The theme started as a side effect of redesigning a personal website. Code snippets in the old design relied on Dracula Theme, which no longer fit the new look. The original goal was narrow: improve syntax highlighting so code blocks matched the rest of the site.

Research turned up the fact that Shiki, the syntax highlighter built into Astro by default, supports themes built from CSS variables — and those require only a handful of colors.

Showing the 11 CSS variables defined for the Shiki theme.

With AI assistance fleshing out a Shiki theme around those variables, the following CSS and JavaScript cover the Astro setup:

:root {
  --shiki-foreground: #eeeeee;
  --shiki-background: #333333;
  --shiki-token-constant: #660000;
  --shiki-token-string: #770000;
  --shiki-token-comment: #880000;
  --shiki-token-keyword: #990000;
  --shiki-token-parameter: #aa0000;
  --shiki-token-function: #bb0000;
  --shiki-token-string-expression: #cc0000;
  --shiki-token-punctuation: #dd0000;
  --shiki-token-link: #ee0000;
}

pre.shiki,
pre.astro-code {
  padding: 1rem;
  border-radius: 0.5rem;
  color: var(--shiki-foreground);
  background-color: var(--shiki-background);
  overflow-x: auto;
}

pre.shiki code,
pre.astro-code code {
  padding: 0;
  font-size: inherit;
  line-height: inherit;
  color: inherit;
  background: none;
}
import { createCssVariablesTheme } from 'shiki/core'

const shikiVariableTheme = createCssVariablesTheme({
  name: 'css-variables',
  variablePrefix: '--shiki-',
  fontStyle: true,
})

export default defineConfig ({
  // ...
  markdown: {
    shikiConfig: {
      theme: shikiVariableTheme
    }
  }
})

Comparing those colors against Dracula, Sarah Drasner's Night Owl and Moonlight 2 gave enough confidence to go further. CSS variables could not reach far enough, though, so the work moved to TextMate tokens for granular control over which tokens get which color. Some code blocks looked terrible without it.

Scaffolding TextMate scopes

The approach was to drive an AI through three steps: state the intent to build a custom theme, request a scaffold, and ask it to read Moonlight 2's theme files as a reference for generating TextMate scope tokens. The colors were consolidated into semantic keywords such as foreground, background and keyword, mirroring the Shiki CSS variable theme. All raw colors went into a color object, leaving a palette object with semantic names only.

const colors = {
  purple: '...',
  blue: '...',
  // ...
}

const palette = {
  foreground: '...',
  background: '...',
  // ...
}

export default {
  colors: {
    // Used for theming the text editor
  },
  displayName: 'Display Name of your Theme',
  name: 'your-theme-name',
  tokenColors: [
    {
      name: 'Scope name (optional)',
      scope: [/*scopes used*/],
      settings: {
        foreground: /* change color */,
        background: /* background of the text */,
        fontStyle: /* normal, bold or italic */,
      }
    }
  ]
}

VS Code needs JSON, so a build script converts that intermediate format into a .json file. Both the script and the rest of the setup live in the GitHub Repo.

Local debugging via the Extension Host

Testing highlighting on the website was impractical because every variable change required a manual server restart. VS Code's Extension Host solves this for local development. A .vscode/launch.json file with the contents below launches it:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Extension",
      "type": "extensionHost",
      "request": "launch",
      "args": [
        "--extensionDevelopmentPath=${workspaceFolder}"
      ]
    }
  ]
}

F5 on Windows or Fn + F5 on Mac opens a new editor window where the custom theme can be selected. That window is easy to recognize: it carries the Extension Host keyword prominently in its title, and once the theme is switched it differs from any other open editor.

Showing the following text: Extension Development host, index.astro, zellwk.com.

Theme switching in the Extension Host may also require the following in package.json:

{
  "contributes": {
    "themes": [
      {
        "label": "Your Theme Name",
        "uiTheme": "vs-dark",
        "path": "<path-to-your-theme>.json"
      }
    ]
  }
}

Reading scope inspector output

Pasting screenshots and asking AI to retune tokens to chosen colors quickly became frustrating, because either the AI picked the wrong TextMate scope or something else overrode it — and there was no way to tell which. The "Developer: Inspector Editor Tokens and Scopes" command makes the scopes visible.

VS Code control panel open and highlighting a command called Developer: Inspect Editor Tokens and Scopes.

In this mode, clicking any text opens a window with everything needed to adjust scopes:

An inspector popover in VS Code showing information for the color-purple-100 variable.
  • Foreground shows the currently active scope — variable, for example.
  • TextMate scopes lists the scopes available for that specific token.

Behavior observed through experimentation, so possibly not fully accurate:

  1. Any part of the available scopes can be used: variable, variable.prop and variable.prop.css all work.
  2. More stated properties mean higher specificity: variable.prop.css > variable.prop > variable.
  3. The higher scope beats the lower one: variable > meta.function.misc.css.
  4. Scopes can be combined like CSS selectors to override a higher scope: meta.function variable > variable.

Choosing colors under the principle of contrast

This is the most consequential part of theme work: highlighting that does not help a developer read code makes the theme pointless. Two references shaped the decisions: Sarah Drasner's "Creating a VS Code Theme" and Tonsky's "Everyone is getting syntax highlighting wrong." The takeaways:

  • Highlights should stand out.
  • Colors sharing lightness and chroma look alike and are hard to tell apart.
  • If everything is highlighted, nothing is.
  • If everything is important, nothing is.

Designing for someone who is reading led to three questions: how do I guide the eye, which elements must be seen, and which matter less.

  • Functions and methods matter, so they had to be strong: cyan, the strongest color in the palette. The export keyword is equally important because it marks an export.
  • Keywords like import and function can stay muted: purple.
  • Strings get green, which reads pleasantly across a JSON file full of text.
  • Constants get orange because it is easy to spot.
  • Variables stay white-ish, since they are the bulk of the text; coloring them produces the "Christmas Lights Diarrhea" effect Tonsky describes.
  • Properties get blue — workhorses that need differentiation without drawing too much attention.
Showing JSON configuration for a dependencies object with a list of packages used in the project to illustrate the use of syntax highlighting colors.
If text wasn’t green…this might be hard to look at.
Showing syntax highlighting for JavaScript code.

HTML/Astro/Svelte work followed after that.