stnd.build

@stnd/themes

Circle 1 — Core Framework (Inviolable Pillar) · Stable · Load-Bearing

Role: 34 native design temperaments driven by tokens.yaml and compiled across Web CSS, Obsidian, and Zed.

When to use: Load a prebuilt theme in astro.config.mjs or author a custom theme from 2 OKLCH seeds (see Creating a Theme).

Quick Start (TL;DR)

// astro.config.mjs
standard({ moduleLoad: ["@stnd/themes/editorial"] });

Temperaments and design variations for the Standard Ecosystem.

ELI5

A theme is a personality you can put on a site: colors, fonts, mood. Each one lives in its own folder with one file that holds all its actual values (tokens.yaml) — edit that file, run one command, and every format that theme ships in (web CSS, the Obsidian vault note, Zed/VS Code editor themes, even Reveal’s Swift code) regenerates from it. You never hand-edit a generated file.

Use an existing theme on your site:

// astro.config.mjs
standard({ moduleLoad: ["@stnd/themes/editorial"] });

Make a new theme: copy an existing theme folder, edit tokens.yaml, run node packages/themes/_scripts/build.js <theme-name>. See “Creating a Theme” below for the 3-file recipe.

Overview

@stnd/themes provides a collection of complete design systems, each with its own typographic context, color palette, and emotional register. These themes are built as Standard modules and can be swapped instantly to change the entire look and feel of an application.

Features

Available Themes

Usage

In your astro.config.mjs:

import { defineConfig } from "astro/config";
import standard from "@stnd/core";

export default defineConfig({
  integrations: [
    standard({
      moduleLoad: [
        "@stnd/themes/editorial"
      ]
    })
  ]
});

To apply a theme to a specific element:

<div data-theme="garden">
  <!-- Content will use the Garden theme -->
</div>

Creating a Theme

To add a new theme to the Standard Ecosystem, create a new directory under packages/themes/<theme-name> and follow these steps:

1. Structure of a Theme Folder

Every working theme ships with 3 core files (register.js and actions.js are optional extension points not required by standard themes):

packages/themes/<theme-name>/
├── tokens.yaml              # Canonical design token values (Single Source of Truth)
├── index.module.js          # Module registration and dependencies
└── <theme-name>.scss        # Generated token block (spliced in by the build script)
                              #   + web-only layout overrides below it

2. File Specifications

tokens.yaml

Specifies metadata and token values. Web-only structural CSS must stay in the .scss file.

meta:
  id: reveal
  label: Reveal
  selector: |-
    :root[data-theme="reveal"],
    [data-theme="reveal"]
  fonts:
    - "@stnd/fonts/din-condensed"
    - "@stnd/fonts/inter"
tokens:
  color-light-background: "#fdfdfc"
  color-light-foreground: "#212121"
  color-accent: "#d6202c"
  font-text: '"Inter", sans-serif'
  font-header: '"DIN Condensed", sans-serif'
  line-height: "1.2"

After creating or updating tokens.yaml, run the theme compiler from packages/themes/:

node _scripts/build.js <theme-name>

Running this script performs two operations automatically:

  1. In-place SCSS splice: Injects the generated --token: value; declarations directly into <theme-name>.scss between the /* TOKENS.YAML ADAPTER BEGIN/END */ markers (no separate _tokens.generated.scss file or @use statement required).
  2. Multi-target export: Writes cross-platform theme artifacts into <theme-name>/generated/ (Obsidian note, VS Code theme, Zed theme, Reveal Swift, and Home Assistant YAML).

<theme-name>.scss

Start the file with just the empty marker pair — the build script fills it in. Everything after the END marker is yours: layout overrides, theme-specific aesthetics, component-level rules scoped to the theme’s own selector.

/* TOKENS.YAML ADAPTER BEGIN */
/* TOKENS.YAML ADAPTER END */

[data-theme="reveal"] {
  background: var(--color-background);
  h1 {
    font-family: var(--font-header);
    text-transform: uppercase;
  }
}

index.module.js

The module declaration. Defines styles and registers the font packages as dependencies so the loader loads them automatically.

export default {
  id: "theme-<theme-name>",
  name: "Stnd :: Theme :: <Label>",
  description: "Registers the <Label> theme.",
  meta: { type: "theme", themeId: "<theme-name>", label: "<Label>" },
  styles: ["./<theme-name>.scss"],
  dependencies: [
    "@stnd/fonts/<font-package-name>"
  ],
};

register.js (optional — not yet used by any shipped theme)

Exposes metadata used by the editor/UI theme dropdowns.

export default () => ({
  id: "<theme-name>",
  name: "<Label>",
  description: "<Short description of the theme's mood>",
});

actions.js (optional — not yet used by any shipped theme)

Registers a command palette action to apply and persist the theme (e.g. trigger ::theme-<theme-name>).

import Log from "@stnd/log";
import { saveVisitorPreferences } from "../../garden/Visitor";

const log = Log({ scope: "CompassTheme<Label>" });

export default [{
  trigger: "::theme-<theme-name>",
  meta: {
    title: "<Label> Theme",
    desc: "<Description>",
    icon: "palette",
  },
  action: async () => {
    if (typeof document !== "undefined") {
      document.documentElement.setAttribute("data-theme", "<theme-name>");
    }
    await saveVisitorPreferences({ theme: "<theme-name>" });
    window.toast("Theme applied", "success");
  },
}];

3. Registering the Theme in the Ecosystem

To make the theme available in the loader and workspace, you must add it to the dependencies list of the central themes module in packages/modules/themes/index.module.js:

  dependencies: [
    ...
    "@stnd/themes/<theme-name>",
  ]

Source of truth & the sync tools

<theme>/tokens.yaml is the ONE source of token values. packages/themes/_scripts/build.js splices generated CSS variables into <theme>.scss and exports multi-target artifacts. Both web and Obsidian consumers sit downstream: the web uses @stnd/themes directly, and the Obsidian plugin bundles themes.generated.js (built from these same stylesheets by apps/stnd-obsidian/build.js). Edit tokens.yaml, never a generated block.

Bidirectional Synchronization Tools

The historical design drift between Francis’s hand-maintained vault notes at Kernel/Themes/* and the package’s canonical codebase has been resolved. Two powerful automation scripts have been added under packages/themes/tools/ to enable seamless bidirectional syncing:

1. Export package themes to your vault

To populate your vault’s Kernel/Themes/ folder with themes from the package (without overwriting any of your existing custom vault themes):

node packages/themes/tools/convert-themes-to-vault.js

This parses each package’s tokens.yaml and .scss overrides, generates clean Obsidian-friendly theme notes with frontmatter metadata, embeds, and nesting, and writes them into your vault.

2. Import vault modifications back to the package

If you edited design tokens or custom styling rules directly inside your Obsidian vault and want to merge those changes back into the package (centralizing them in git):

node packages/themes/tools/sync-vault-to-packages.js

This tool:

The _scripts/build.js pipeline — multi-target theme codegen

packages/themes/_scripts/build.js turns every theme’s tokens.yaml into both web SCSS and non-web target formats via a modular adapter-per-target system. Same rule as everywhere else in this package — tokens.yaml is the one source of truth; every file under a theme’s generated/ folder is overwritten on the next run, never hand-edited.

node packages/themes/_scripts/build.js            # every theme, every adapter
node packages/themes/_scripts/build.js reveal      # just one theme (all its adapters)

For each theme, this writes into <theme>/generated/<adapter-name>/:

Adapter Output Consumer
reveal Theme.swift (Palette/Typo/Rhythm) apps/reveal — see below
zed a Zed editor theme JSON Zed’s theme picker
vscode a VS Code theme extension VS Code’s theme picker
obsidian an Obsidian-flavoured theme note the vault
homeassistant a Home Assistant theme YAML Home Assistant

Adding a target = adding one file to scripts/adapters/<name>.js exporting a build(config, options) function — build.js discovers and runs every adapter against every theme automatically, no registration step.

Native App Integration (apps/reveal)

After running either tool, simply rebuild the Obsidian plugin to package the latest themes:

# In apps/stnd-obsidian
pnpm run build