Themes
Theme JSON structure, color tokens, import behavior, and how Noteism, docs.noteism.app, and themes.noteism.app stay visually related.
Theme model
Noteism themes are JSON files loaded at runtime. The app ships with a built-in default theme and then discovers more themes from:
- the repository
themes/directory - the user theme directory under your config path
The loader only accepts JSON theme files. CSS themes are explicitly rejected.
Current format
The current theme format is JSON only. If you drop a .css theme into the
user theme folder, Noteism will reject it instead of pretending it knows what
to do.
Theme metadata fields
These top-level fields are used today:
| Field | Purpose |
|---|---|
id | Stable identifier used for loading and file naming |
name | Human-readable display name |
author | Theme author credit |
version | Theme version string |
date | Theme release/update date |
url | Project, author, or theme reference URL |
description | Short summary shown in theme browsers |
appearance | light or dark |
colors | The full UI and markdown token map |
Color tokens in the current schema
The app currently reads these color keys:
| Group | Tokens |
|---|---|
| Base surfaces | window_bg, surface, surface_elevated, surface_sidebar, surface_menu, surface_overlay |
| Borders and text | border, border_strong, text, text_muted, text_inverse |
| Signals | accent, accent_hover, success, warning, danger |
| Tabs and scrollbars | tab_active, tab_inactive, scrollbar_track, scrollbar_thumb |
| Markdown surfaces | markdown_bg, markdown_heading, markdown_code_bg, markdown_quote_bg, markdown_quote_border |
What theme tooling already does
Live switching
Themes apply at runtime inside the app without a rebuild.
Gallery previews
Preferences already includes preview cards for shipped and imported themes.
Search and filtering
Theme browsing supports search plus light/dark grouping.
Import support
JSON theme files can be imported into the user theme directory.
Open theme folder
The preferences UI can jump straight to the user themes directory.
Where themes live
The repo themes/ directory is scanned at runtime. This is where project-side
theme files live when they ship with the app or ride alongside development work.
Imported user themes are copied into the per-user config directory under
noteism/themes. That keeps personal themes out of the repo and out of the app binary.
themes.noteism.app is the web-side gallery and generator. It mirrors the
same schema, ships the current theme catalog, and can generate/import/export
real Noteism theme JSON.
Theme authoring advice
- Start by getting your surface and text contrast right before chasing accent color drama.
- Make sure quote, code, and heading markdown tokens still read cleanly after the base palette changes.
- Test both light and dark appearance metadata honestly. Do not mark a muddy half-light theme as dark just because the page looks cooler in screenshots.
- If you want to generate a starting point quickly, use the generator on
themes.noteism.app, then fine-tune the JSON.
A pretty accent is cheap. A theme that keeps code, tables, quotes, diagrams, and menus readable for hours is the real flex.