stnd.build

Creating a Theme

The 3-file recipe for authoring a Standard theme — tokens.yaml seeds, OKLCH derivation, multi-target codegen, and automated WCAG conformance tests.

Standard ships with calibrated Swiss-analog defaults out of the box, and lets you customize or create themes at three progressive levels — without ever needing to fork the framework source code.

Level Where it lives Best for
1. Frontmatter Tokens Root index.md or any Markdown note Personal sites, digital gardens, and per-note art direction with zero CSS files.
2. App-Local Module ./modules/<my-theme>/ in your Astro app Standalone apps (npm install @stnd/core), custom brand themes, and private/commercial fonts.
3. Multi-Target Core Theme packages/themes/<name>/tokens.yaml Official themes compiled simultaneously for Web, Obsidian, Zed, VS Code, and macOS.

Level 1: Zero-File Frontmatter Tokens (Vault & Notes)

If you publish from an Obsidian vault or Markdown folder (via @stnd/press or Standard Garden), you do not need to create a theme package at all. Any design token placed in the YAML frontmatter of your root index.md cascades across your entire site as its default identity (and any individual note can override them for a single page):

---
title: My Personal Site
color-light-background: "#FFFCF0"
color-light-foreground: "#4D3A0B"
color-light-accent: "#AD8301"
color-dark-background: "oklch(0.23 0.002 67)"
color-dark-foreground: "oklch(0.77 0.023 96)"
font-text: "Instrument Sans"
font-header: "Inter"
font-header-weight: 900
font-header-letter-spacing: "-0.05em"
ratio: 1.25
density: 1.45
reading-width: "40rem"
---

From just color-light-background and color-light-foreground, @stnd/styles computes all elevated surfaces, hairline borders, and semantic hues automatically.


Level 2: App-Local Theme & Font Modules (./modules/)

When building an application after npm install @stnd/core, you can add your own themes and private/commercial fonts directly inside your project’s ./modules/ folder (or a private workspace package). @stnd/core auto-discovers every *.module.js file at build time and layers your styles after @stnd/styles.

my-app/
└── modules/
    ├── private-fonts/
    │   ├── index.module.js    # Registers your licensed .woff2 fonts locally
    │   └── diatype.css
    └── brand-theme/
        ├── index.module.js    # Registers [data-theme="brand"]
        └── brand.scss
// modules/brand-theme/index.module.js
export default {
  id: "theme-brand",
  name: "Brand Theme",
  meta: { type: "theme", themeId: "brand", label: "Brand" },
  styles: ["./brand.scss"],
  dependencies: ["font-private"], // ensures your local font module loads first
};
// modules/brand-theme/brand.scss
:root[data-theme="brand"],
[data-theme="brand"] {
  --color-light-background: #f7f3ee;
  --color-light-foreground: #3a2a18;
  --color-light-accent: #c83e2b;
  --font-text: "Cargo Diatype", var(--font-sans);
}

Activate it site-wide by setting theme: "brand" in your app’s modules/core/index.module.js (or astro.config.mjs).


Level 3: Multi-Target Core Theme (tokens.yaml)

Core themes in packages/themes/<theme-name>/ are driven by a single source of truth (tokens.yaml) that compiles to SCSS plus cross-platform targets (Zed, VS Code, Obsidian, Swift).

# 1. Copy a reference theme
cp -R packages/themes/international packages/themes/my-theme

# 2. Edit packages/themes/my-theme/tokens.yaml (set id, label, and seeds)
# 3. Compile tokens into SCSS + cross-platform targets
node packages/themes/_scripts/build.js my-theme

# 4. Verify WCAG contrast (>7:1) and monotonic surface ladder
pnpm test:styles

The 3-File Core Theme Anatomy

Every theme folder in packages/themes/<name>/ consists of three files:

packages/themes/my-theme/
├── tokens.yaml          # 1. Single source of truth (seeds, fonts, rhythm hooks)
├── index.module.js      # 2. Module manifest & @stnd/fonts dependencies
└── my-theme.scss        # 3. Spliced token block + optional structural CSS rules

File 1: tokens.yaml

Define the metadata, font dependencies, and seed tokens. Only override tokens that differ from the framework defaults (our conformance test fails if a theme sets a token to the value the framework already gives it):

meta:
  id: my-theme
  label: My Theme
  selector: |-
    :root[data-theme="my-theme"],
    [data-theme="my-theme"]
  fonts:
    - "@stnd/fonts/inter"
    - "@stnd/fonts/berkeley-mono"
tokens:
  # Primary Light Seeds (Required)
  color-light-background: "#faf8f5"
  color-light-foreground: "#1e1e1c"

  # Brand Accent
  color-accent: "#c83e2b"

  # Typography & Rhythm Hooks (Optional)
  font-text: '"Inter", sans-serif'
  font-header: '"Inter", sans-serif'
  font-monospace: '"Berkeley Mono", monospace'
  ratio: "var(--ratio-silver)"
  radius: "0.25rem"

File 2: my-theme.scss

Start the file with the TOKENS.YAML ADAPTER marker pair. Running node packages/themes/_scripts/build.js my-theme splices the generated --token: value; declarations between those markers. Place any web-specific structural rules below END:

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

[data-theme="my-theme"] {
  h1, h2 {
    letter-spacing: -0.02em;
  }
}

File 3: index.module.js

Registers the theme as a Standard module and declares its @stnd/fonts/* dependencies so Astro bundles them automatically:

export default {
  id: "theme-my-theme",
  name: "Stnd :: Theme :: My Theme",
  description: "Registers the My Theme temperament.",
  meta: { type: "theme", themeId: "my-theme", label: "My Theme" },
  styles: ["./my-theme.scss"],
  dependencies: [
    "@stnd/fonts/inter",
    "@stnd/fonts/berkeley-mono",
  ],
};

Finally, add "@stnd/themes/my-theme" to the dependencies array in packages/modules/themes/index.module.js so it is registered workspace-wide.


3. Theme-Authoring Token Hooks (The Master Seeds)

These are the primary seed tokens an author sets in tokens.yaml or a note’s frontmatter. All downstream tokens are computed automatically by the @stnd/styles mathematical engine:

Token in tokens.yaml CSS Variable Default Role & Systemic Cascade Effect
color-light-background --color-light-background #faf8f2 Primary light paper seed. Derives 5 monotonic elevation surfaces.
color-light-foreground --color-light-foreground #221f1c Primary light ink seed ($\ge 7:1$ contrast). Derives dark seeds and chromatic rotation.
color-accent --color-accent Framework accent Interactive focus, active states, and links across both light/dark schemes.
ratio --ratio 1.414 (Silver) The Typographic Engine: Computes --scale-d5 through --scale-8 via $pow(ratio, n)$.
ratio-mobile --ratio-mobile 1.272 (Halfstep) The Mobile Compression Hook: Contracts optical ratio on viewports $\le 768px$.
density --density --optical-ratio The Spatial Rhythm Engine: Sets --line-height and 1rlh (--baseline). Drives base --space and all 24 spacing units (--space-d12 .. --space-12).
font-text-size --font-text-size 1rem (16px) Root body font size (--base-size). Drives fluid growth beyond 1440px.
reading-width --reading-width 42rem Optimal reading column width (--prose-width). Anchors grid breakout tracks.
radius --radius var(--trim) (~2px) Base corner radius (--radius). Sets button, input, card, and dialog curvature.
page-padding --page-padding clamp(1rem, 6vw, 4rem) Fluid outer margin preventing content from touching device bezels.
page-padding-small --page-padding-small var(--space-d2) Viewport outer padding on small screens. Rhythm-aligned to prevent bezel collision.
font-text --font-text var(--font-sans) Body reading font stack.
font-header --font-header var(--font-sans) Heading and title font stack.
font-monospace --font-monospace var(--font-mono) Code block, tabular data, and spec font stack.

4. The 7 Golden Tokens: Maximum Leverage with Minimal Declarations

Standard is designed around an essential architectural principle: never write 100 CSS rules when 6 declarative tokens will achieve the goal through cascading mathematics.

Here are three complete, production-grade theme recipes that create radically distinct visual universes using only the 7 Golden Tokens in tokens.yaml:

Recipe A: Swiss Architectural (Strict Grid, Archival, Disciplined)

Best for technical documentation, design manuals, and precision tooling.

meta:
  id: swiss
  label: Swiss Architectural
tokens:
  # 1. Archival paper & carbon ink seeds
  color-light-background: "#fbfaf7"
  color-light-foreground: "#1a1917"
  color-accent: "#e03131"
  
  # 2. Strict Silver ratio (clean √2 jumps)
  ratio: "1.414"
  ratio-mobile: "1.272"
  
  # 3. Compact line cadence: tightens every margin, gap, and padding across the UI
  density: "1.35"
  
  # 4. Sharp, unrounded edges across all cards, dialogs, and buttons
  radius: "0px"
  
  # 5. Disciplined reading column
  reading-width: "42rem"
  
  font-text: '"Inter", sans-serif'
  font-header: '"Inter", sans-serif'

Recipe B: Warm Literary (Book, Generous Rhythm, Intimate Reading)

Best for personal essays, editorial magazines, and digital gardens.

meta:
  id: literary
  label: Warm Literary
tokens:
  # 1. Warm cream paper & deep espresso ink
  color-light-background: "#faf6ee"
  color-light-foreground: "#2c2520"
  color-accent: "#ad4a3b"
  
  # 2. Major Third ratio: gradual, elegant typographic steps without aggressive leaps
  ratio: "1.25"
  
  # 3. Generous reading density: expands line-height, paragraphs, and card margins
  density: "1.65"
  
  # 4. Subtle, paper-like corner softening
  radius: "3px"
  
  # 5. Classic book column measure (60 characters per line)
  reading-width: "38rem"
  
  font-text: '"Newsreader", serif'
  font-header: '"Newsreader", serif'

Recipe C: Modern Software (SaaS Dashboard, Squircles, Clean Interactivity)

Best for applications, dashboards, account settings, and interactive tools.

meta:
  id: modern-app
  label: Modern Software
tokens:
  # 1. Neutral cool slate background & crisp dark ink
  color-light-background: "#f8fafc"
  color-light-foreground: "#0f172a"
  color-accent: "#2563eb"
  
  # 2. Perfect Fourth ratio: clear hierarchy between labels and page titles
  ratio: "1.333"
  
  # 3. Balanced interface line height and component padding
  density: "1.45"
  
  # 4. Friendly modern squircle / rounded corners
  radius: "10px"
  
  # 5. Wider reading column for data density
  reading-width: "48rem"
  
  font-text: '"Plus Jakarta Sans", sans-serif'
  font-header: '"Plus Jakarta Sans", sans-serif'

Notice what is absent in all three recipes: there are zero custom classes, zero @media queries, and zero component overrides. Simply tuning the 7 dials transforms the typography scale, spacing grid, line height, corner geometry, and color surfaces across every page, button, dialog, and card automatically.


5. Using & Scoping Themes

Site-wide in astro.config.mjs

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

export default defineConfig({
  integrations: [
    standard({
      moduleLoad: ["@stnd/themes/my-theme"],
    }),
  ],
});

Scoped to a DOM Subtree or Mode

<!-- Apply theme to a specific section -->
<section data-theme="my-theme" class="bg-background text-primary p-2">
  <h2>Scoped Theme Preview</h2>
</section>

<!-- Force dark or light color mode on any container -->
<div data-color-mode="dark" class="bg-background text-primary p-2">
  Forced dark mode subtree
</div>

6. Conformance Laws Verified by pnpm test:styles

Every theme in @stnd/themes is automatically audited against these invariants on every test run and git push:

  1. Monotonic Surface Ladder: Lightness must strictly progress (sunken <= background <= surface <= raised <= overlay).
  2. Achromatic Stage: --color-stage must have chroma $\approx 0$ and lightness $\le$ background.
  3. AAA Contrast: --color-foreground on --color-background must exceed 7:1 contrast in both light and dark modes.
  4. Zero Redundant Overrides: A theme must never set a token to the exact default value @stnd/styles already provides.
  5. Forced-Mode Attribute: [data-color-mode="light"|"dark"] is the sole forced-mode selector (data-theme-mode is forbidden).