Caution
⚠️ Breaking Changes
This is a major version update. All previous Style Settings configurations will be reset when upgrading to v3.0.0. The entire settings schema has been redesigned from the ground up. Custom snippets that referenced Retroma's internal CSS variables (--background-paper, --chroma, --lightness-accent, etc.) will also break and must be updated. See the Migration Guide below.
v3.0.0 is the largest and most significant update to Retroma since its first release. The theme has been completely reconstructed - not just visually, but architecturally. The CSS token system, the customization schema, the 3D button engine, the workspace layout model, and virtually every component have been rewritten from scratch to be more robust, more flexible, and significantly easier to maintain and extend going forward. This update fixes style and color inconsistencies, and the theme now fully adapts to whichever color accents you are using.
Important
Retroma v3 is now primarily designed for the Style Manager plugin. Style Manager replaces Style Settings as the recommended way to customize the theme, and unlocks additional features like preset importing, scheduled style switching, and a shared locker system. The classic Style Settings plugin is still fully supported - all settings remain compatible with it.
🔴 Why This Update Breaks Things
The previous architecture had a fundamental problem: Obsidian's own CSS variables were being overridden directly in :root, .theme-light, and .theme-dark, making it impossible to cleanly separate the theme's logic from Obsidian's internals. This led to cascading conflicts, unpredictable specificity issues, and increasingly messy patches to keep things working.
v3.0.0 introduces a dedicated rtm- token namespace. All of Retroma's internal design tokens are now prefixed with --rtm-, completely decoupled from Obsidian's own variables. Obsidian's variables are then mapped onto rtm- tokens once, in a single controlled location. This makes the theme far more stable across Obsidian updates and opens the door for proper per-component overrides.
Removed Variables (V2.7 to v3.0)
The following CSS variables have been removed or renamed. If you use any of these in custom snippets, you must update them.
| v2.7 Variable | v3.0 Replacement |
|---|---|
--background-paper |
--rtm-bg-paper |
--chroma |
--rtm-c-txt |
--chroma-folder |
--rtm-c-folder |
--chroma-accent |
--rtm-c-accent |
--lightness |
--rtm-l-txt |
--lightness-accent |
--rtm-l-accent |
--box-shadow |
--rtm-btn-3d-normal |
--box-shadow-active |
--rtm-btn-3d-active |
--box-shadow-sm |
Removed (use --rtm-btn-3d-normal) |
--button-active |
--rtm-bg-btn-active |
--bases-cards-background |
--rtm-bases-cards-bg |
Removed Style Settings Keys (V2.7 to v3.0)
The following Style Settings IDs have been removed. Any saved settings using these keys will be silently ignored. You must re-configure your preferences after updating.
| Removed ID | Notes |
|---|---|
retroma-obsidian-theme |
Replaced by workspace-color-scheme |
color-scheme |
Replaced by workspace-color-scheme |
chroma |
Split into rtm-chroma-lightmode-accent / rtm-chroma-darkmode-accent |
lightness-accent |
Replaced by rtm-l-accent |
button-border-radius |
Replaced by rtm-interface-radius |
heading-colors, h1-color … h6-color |
Now under the new Headings section |
folder-color-1 … folder-color-15 |
Renamed to rtm-folder-color-1 … rtm-folder-color-15 |
plugin-integration-toggle |
Plugin settings are now always inline |
image-tuner, img-border-* |
Under the new Image and video section with new IDs |
link-color, link-external-color |
Under the new Links section |
retroma-canvas-* |
Replaced by rtm-canvas-* IDs under the Canvas section |
canvas-settings |
Replaced by canvas |
disable-table-border |
Replaced by per-column and row outline controls |
enable-alternative-checkboxes |
Renamed to rtm-ss-alternative-checkbox |
✨ What's New
🏗️ Rebuilt Architecture and Token System
The entire CSS foundation has been rewritten. All theme internals now live under the --rtm-* namespace. The body-level token map centralises all Obsidian variable overrides in one place, making the theme far more predictable and easier to customise via snippets.
🚫 Goodbye !important - Proper CSS Cascade
Every single !important declaration has been removed from the theme. In v2.7, !important was used extensively as a patch to force overrides - a symptom of the old architecture where Obsidian's variables and Retroma's own tokens were tangled together.
The rewritten --rtm-* token system means the theme now relies entirely on CSS specificity and the natural cascade to apply styles. Selectors are deliberately ordered and scoped so that each rule wins by virtue of its selector weight and source order, not brute force.
The practical benefit for you: custom snippets no longer need !important to win. A simple, correctly scoped selector in your snippet file will override Retroma's styles as intended, without a fight.
📖 Built-in README and Terminology Guide
A new README section is now embedded directly inside the Style Manager / Style Settings panel. It explains why Retroma uses OKLCH over HSL or RGB, and provides a plain-English glossary covering: Tuner, L (Lightness), C (Chroma), H (Hue), Desktop-only settings, Global settings, Normal/Hover/Active states, Padding vs. Margin, and Vertical vs. Horizontal spacing.
🎛️ Redesigned 3D Button Engine
The 3D button effect has been completely rewritten using trigonometric CSS functions (cos(), sin()). Instead of hardcoded shadow/highlight directions, the engine now takes a light angle parameter and mathematically derives the correct highlight and shadow positions for any direction.
New controls:
- Light angle - sets the direction the virtual light comes from, affecting all buttons, toggles, sliders, and inputs simultaneously
- Shadow and highlight thickness - normal and active states controlled independently
- Shadow and highlight lightness, opacity, and blur - fine-tune the 3D depth for each state
- Separate dark mode 3D tuner with its own shadow/highlight properties for normal and active states
- Color overrides - override the default, hover, and active button backgrounds, icon color, and border color independently
🖌️ Redesigned Workspace and Pane System
The workspace layout system has been completely rearchitected.
New controls:
- Border-radius - global interface corner radius
- Simple pane header - removes borders and backgrounds from pane headers (does not affect the Markdown editor, file navigation, or PDF viewer panes)
- Simple workspace panes - removes extra borders and backgrounds around individual panes
- Hide vault profile container (desktop) - hides the vault name, settings, and help icons at the bottom left
- Pane outer-spacing (desktop / tablet) - controls the gap between panes
- Pane inner-spacing (desktop / tablet) - controls padding inside each pane
- Workspace primary-outline style and thickness - for the outer workspace frame and pane headers
- Workspace secondary-outline style and thickness - for inner panes, menus, modals, and popups
- Background and foreground color overrides - manually override workspace background, pane background, pane content background, pane header background, pane header title color, and outline colors for both primary and secondary outlines
🎨 LCH Color Tuners
The LCH tuner is now split into two dedicated sections:
- LCH tuner (backgrounds) - adjust light mode chroma, dark mode chroma, and dark mode lightness for background colors
- LCH tuner (texts) - adjust chroma and lightness for text colors independently in light and dark mode
🗂️ Redesigned Folder and File Section
The Folder and files section has been rebuilt. Individual folder color slots (rtm-folder-color-1 through rtm-folder-color-15) are still present and configurable. New folder styling controls include:
- Type - choose between different folder layout styles
- Icon - choose the folder icon style
- Outline style, outline thickness, left outline thickness, and opened folder outline thickness
- Indentation line style and indentation line thickness
- Vertical spacing between folders
- Remove rainbow colors toggle
- Background color and collapsed background color
- Text color and collapsed text color
A dedicated File subsection has also been added with its own styling controls.
📝 Redesigned Markdown Editor Section
The Markdown editor section is now its own top-level category with the following controls:
- Markdown editor font
- Markdown editor background color
- Markdown editor font size
- Simple markdown editor header toggle
- Simple markdown editor container toggle (desktop)
- Readable line length override
Editor pattern subsection:
- Toggle pattern on/off
- Pattern type (Dot or Grid)
- Zoom (scale)
- Thickness
📐 Expanded Typography Controls
Headings:
- Per-heading color (H1–H6)
- Per-heading size (H1–H6)
- Per-heading weight (H1–H6)
- Per-heading line height (H1–H6)
- Per-heading font (H1–H6)
- Heading underline subsection per heading level: show/hide toggle, style, thickness, offset, and color
- Hashtag rendering toggle, opacity, and size
Paragraph:
- Text color
- Line height
- Paragraph spacing
- First line indentation
Text emphasis:
- Bold color and font
- Italic color and font
- Bold + italic color and font
- Strikethrough color and decoration color
Links:
- Internal link: font, weight, color, underline style, thickness, offset, color, hide toggle
- External link: font, weight, color, underline style, thickness, offset, color, hide toggle
List:
- Indent guide color and thickness
- Marker color and collapsed marker color
- Indent spacing
- Numbered list style
- Item spacing
- Bullet size and bullet border-radius
🎭 Retro Callouts - 79 Custom Callout Types
A full suite of 79 custom callout types has been added, themed around vintage stationery, retro media hardware, photography, and academic materials. Every callout supports three width sizes by appending -s (small, 320px), -m (medium, 520px), or -l (large, full-width) to its name. Callouts are also foldable using + (open) or - (closed) after the name.
Use the standard Obsidian callout syntax:
> [!callout-name] Optional Title
> Your content goes here.
Categories:
| Category | Callout Types |
|---|---|
| 📷 Photo-Film | polaroid-1, polaroid-2, film, filmstrip, negative, photoalbum, photoslide, photomount |
| 📼 Media-Hardware | floppy, cassette-1, cassette-2, vinyl, reeltoreel, radio, transistor, eurorack, walkietalkie, calculator, pager-1, pager-2, pagerunit, terminal, matrixstream, pcbboard, tamagotchi, punchedtape, marquee, arcademarquee, highscore |
| 📝 Office-Stationery | notepad, postcard-1, postcard-2, touristcard, artpostcard, ticketstub, scrapbook, receipt-1, receipt-2, matchbook, mailbox, indexcard, filingtab, luggagetag, krafttag, duedate, visastamp, museumtag, toploader, stickynote-{color}, legalpad, gridnotebook, clipboard, dailycalendar, indextab, kraftpaper, graphmemo, library, news |
| 🎓 Academics-Journaling | compbook, chalkboard, ruler, librarycard, flashcard, labnotebook, blueprint, fieldnote, typewriter, inspection |
| 🔖 Vintage-Tactile | typewriter-page, vintage-ticket, passport-stamp, cardboard-cutout-shape |
The stickynote callout comes in seven colors: red, orange, yellow, green, blue, indigo, violet - combine with a size suffix for full control (e.g. stickynote-red-s).
🎨 Style Manager Integration and Presets
Retroma v3 is built around the Style Manager plugin. In addition to all the customization controls, Style Manager unlocks a Presets system that lets you snapshot your entire configuration and switch between styles instantly - or on a schedule.
Official Retroma presets are available as a downloadable retroma-presets.json bundle. To import:
- Open Style Manager in Obsidian.
- Click the ⋮ More Actions menu in the top toolbar.
- Select Import preset… and choose the
.jsonfile. - Go to the Presets tab and click any preset to apply it.
You can also save your own configurations using Create preset → Select modified → Save preset.
Tip
Style Manager supports scheduled style switching - set your vault to use a light preset during the day and switch automatically to a dark retro arcade style at night.
🔲 Canvas Improvements
The floating UI elements in Canvas now automatically hide when panning or actively editing card content. The Canvas section has been rebuilt with new controls:
- Simple canvas floating UI - hides the background and borders of floating elements
- Canvas font - change the font used inside Canvas
- Canvas controls position - choose where the floating controls appear
- Canvas background color (light and dark mode)
- Dot pattern color
- Floating UI fade-out delay - delay before UI hides when panning, editing, or dragging nodes
- Floating UI fade-in delay - delay before UI reappears after touch release, scrolling, or losing focus
- Floating UI fade speed - duration of the opacity transition
- Cards subsection: border-radius and outline thickness
📊 Rebuilt Bases Section
The Bases section now has dedicated subsections:
- Table view - header background, hover row background, active cell background, selected cell background, active cell outline color and thickness, header icon display, column and row border width, row height, header font size, data font size, simple pill toggle
- Cards view - outline color, background color, cover color, outline hover color, border-radius, corner shape, outline style, outline thickness
- Maps view - note popup background color
✅ Checkbox and Alternative Checkboxes
- Border-radius control for checkboxes
- Remove strikethrough on completed checkboxes toggle
- Toggle alternative checkboxes - enables custom symbols (
[!],[?], etc.) - Colored text toggle - applies custom colors to the entire line instead of just the icon
- Individual color controls for all 24 alternative checkbox types
🎞️ Filters
Modify the visual appearance of your screen with custom overlay effects and focus states:
- Retro 8-bit pixelated icons - gives icons a blocky retro look
- CRT screen effect - includes options for scanline thickness and vignette colors
- CRT text glow - adds a phosphor screen text glow
- Grayscale toggles - force backgrounds, text, folder colors, images, or videos into black and white
- Zen Mode (desktop) - focus on writing by automatically fading surrounding workspace elements
🖥️ Desktop Specific Settings
A dedicated Desktop specific settings top-level section now collects all desktop-only controls:
- Tabs - border-radius, outline color, hide tab group header in lower sidebar pane
- Title bar - focused and unfocused background and text colors
- Statusbar - height, background color, text color
- Scrollbar (desktop) - thickness and thumb border-radius
📱 Mobile Specific Settings
A dedicated Mobile specific settings section includes:
- Simple mobile bottom navbar toggle
- Mobile toolbar background color
- Sidebar width - controls how much of the screen the sidebar occupies when it slides open
- File navigation buttons position (phone) - top or bottom of the folder tree
- Scrollbar (mobile) - thickness and thumb border-radius
🔗 Backlink and Search Pane
New dedicated section for backlink and search styling:
- Header container background color
- Container background color
- Result header background color
- Result header text color
- Result body background color
🛠️ Migration Guide
Because the settings schema has been completely redesigned and rebuilt from scratch, saved settings and presets from version 2.x are not compatible with version 3.0. You will need to reconfigure your settings once after upgrading.
- Update the theme via Obsidian's appearance settings or by manually replacing
theme.css. - Install Style Manager from the community plugins (recommended for the best customization experience).
- Manually re-apply your preferences using the new settings categories.
- Save a new preset: Once you have customized the settings to your liking, go to Style Manager's Presets tab, click Create preset, name it, and save it so you can easily backup, restore, or schedule your design state in the future.
- Update any custom CSS snippets using the CSS variable rename table above.
To see the full customizations, please update or install the Style Manager plugin. Alternatively, you can simply use the theme as-is.
☕️ Support
If Retroma is making your vault look great, consider donating. It'll help me pay the bills, stay sane, and spoil my cat 🐱 Thanks for the support!