Your CSS is part of your writing.
Theme files live in the vault's ordinary themes/ directory, not in disposable .skald/ state. That means they survive app-state deletion, sync like other vault files, and can be shared as files.
├── themes/
│ ├── field-journal.css
│ └── quiet.css
├── Sources/
│ └── Mechanical watches.md
└── .skald/
--- type: Source style: field-journal --- # Mechanical watches The note chooses a theme by name.
Specific wins. Missing never breaks the note.
A note can name its own style. Otherwise Skald checks the note's schema default, then the vault default, then falls back to the built-in reading surface. Missing or unknown themes fail safely.
style:→schema default→vault default→Skald surfaceA theme styles meaning, not coordinates.
The same aside can become a technical inset, literary interruption, or field annotation because the Markdown describes what the block is and CSS decides how that meaning is expressed.
Observations
Body text stays unchanged.
Rendered as a restrained technical inset.
Observations
Body text stays unchanged.
Rendered as a quieter literary interruption.
Observations
Body text stays unchanged.
Rendered as a field annotation.
:::aside This source is identical in all three examples. :::
Theme against Skald's skin, not its organs.
Internal renderer classes are private and may change. Theme authors target the stable .sk-* classes and --note-* tokens instead, so renderer refactors do not turn old themes into archaeological artifacts.
.sk-note {
--skald-theme: 1;
--note-font-body: "Newsreader", Georgia, serif;
--note-font-heading: var(--font-ui);
--note-measure: 68ch;
--note-space-block: 1.1em;
--note-accent: var(--sy-orange);
}
.sk-container--aside {
/* semantic container styling */
}Tier 1 · tokens
Best for most themes. Change typography, measure, spacing, backgrounds, text colors, code surfaces, quote borders, link colors and task-state accents.
Tier 2 · classes
Use the versioned .sk-* classes for deliberate element-specific styling when tokens are not enough.
Most visual identity does not need selectors.
Theme tokens inherit from app-level design tokens, so a restrained note theme can continue to behave sensibly across Midnight, Slate and Daybreak.
| Token | Controls |
|---|---|
| --note-font-body | Body and list typography |
| --note-font-heading | Heading typography |
| --note-measure | Readable content width |
| --note-space-block | Paragraph/list rhythm |
| --note-bg | Note surface background |
| --note-tx | Body text |
| --note-tx-heading | Heading text |
| --note-accent | Markers and semantic accents |
| --note-code-bg | Code surfaces |
| --note-quote-border | Blockquote edge |
| --note-link | Resolved links |
| --note-link-missing | Missing wikilinks |
The engine exists before the nice management UI.
The theming system is functional, but Skald does not yet have a dedicated visual theme picker/editor or a polished UI for surfaced CSS rejection details. For now, theme files and mappings are driven directly.
Reference when you need the whole API.
The visual guide explains the mental model. The Markdown reference remains the exhaustive source for contract versioning, every token, every public class, safety rules and implementation details.