1.0 Theme migration guide

Overview

Obsidian 1.0 introduces a new default theme, a new theme versioning system, and several important new features. We expect that most themes and plugins will need some tweaks.

• Migrating your theme to the new versioning system
• How to design themes for v1.0+
• New v1.0 features and modes to consider
• Design guidelines

Migrating your theme to the new versioning system

Because v1.0 contains a lot of breaking changes, we are taking this time to reset our theme gallery and improve how themes are loaded in Obsidian going forward.

Themes that are not compatible with v1.0 have been flagged in the community-css-themes.json file as "legacy." Legacy themes are hidden from the gallery until the theme author updates the theme opts to have the flag removed.

Even if your theme made the cut to the new list, we still recommend you take the following steps to prepare your theme for the new version of Obsidian:

1. Create a copy of your obsidian.css file and rename it to theme.css. Keep the obsidian.css file in your repository so that older versions of Obsidian can continue to download your theme. If you have any preprocessing tools that output the obsidian.css file, make sure to update those as well.
2. Test your theme on Obsidian 1.0 and apply any issues to theme.css.
3. Create a manifest.json file in your repository. This file specifies the minAppVersion for your theme, meaning: versions of Obsidian that are older than the version you specify will not be able to install your theme.

Sample Manifest.json

{  
   "name": "Sample Theme",  
   "version": "1.0.0",  
   "minAppVersion": "1.0.0",  
   "author": "Obsidian",  
   "authorUrl": "https://obsidian.md"  
}

4. Optional: Update your screenshot thumbnail. This should be 16:9 aspect ratio and the recommend size is 512 by 288px.
5. Update your theme’s README file. Clicking on the theme in the Theme Gallery will now the README file from Github. This means you have more space to promote your theme and can load additional screenshots to showcase different features.
6. Create a Pull Request on the obsidian-releases repo and remove "legacy": true from your theme entry in community-themes.json.

How to design themes for v1.0+

TLDR: Obsidian 1.0 introduces over 400 new CSS variables that help you style almost every aspect of the Obsidian UI. This enables themes to remove complex selectors and let variables do the heavy lifting.

With the release of Obsidian v1.0 we’ve made it much easier to create custom themes and snippets.

Previously, many of Obsidian’s UI elements could only be targeted by writing complex CSS selectors with high specificity. Several selectors were typically required to target the same element across Reading mode and Live Preview.

With v1.0 we have abstracted most UI elements into CSS variables applied to the body element. You can find an alphabetized list of all the CSS variables at the top of the app.css file. These variables are also designed to provide parity across Reading mode and Live Preview.

Our goal was to make it possible to create highly expressive themes with less specificity in your CSS selectors. Most themes should be able to completely customize the interface by simply targeting body for interface styling, and .theme-light/.theme-dark for colors.

We expect these changes to significantly reduce the number of lines of code in advanced themes. This should reduce maintainance work and make your code more future-proof.

If you are working on a complex theme, consider simplifying your selectors and using the new CSS variables to do the heavy lifting. The new CSS variables should also make it easier to create styles that are responsive to conditional CSS classes.

Summary:

• Explore the new variables in CSS by looking at app.css and using the Developer Tools
• Try to use the lowest specificity selectors you can. You may be able to only use body, .theme-light and .theme-dark

New 1.0 features and modes to consider

Obsidian 1.0 contains new features and modes that you should consider in your theme.

Accent color

Users can now customize their accent color. Dynamic variables for accent HSL values --accent-h, --accent-s, --accent-l are provided which can be modified with the CSS calc() function.

If you define these variables in your theme, the user will see your default accent color, and resetting to default will return the user to your specified default accent color.

Title bar style

In Settings > Appearance users can now choose between three different title bar styles:

• Hidden: no titlebar is displayed, only the the top row of tabs, default in 1.0+
• Custom: displays a custom titlebar element that can be styled with CSS (previously the default in versions 0.15 and older)
• Native: displays the native operating system titlebar

Top row of tabs and .mod-top

The top area of the application which includes both the custom titlebar (if enabled) and the top row of tabs is considered a single UI area. The default theme uses a single background color for this top area.

The .mod-top modifier class is added to the top row of tabs in sidebars and panes. Tab containers inside of .mod-top use the --titlebar-background variables rather than --tab-container-background variable.

Sidebars and sidebar buttons

Note: the right ribbon has been removed

Sidebar toggle buttons have moved into the top row of tabs. Depending on the user’s operating system, the window buttons (minimize, maximize, close) may be on the left or right side of the application. When the user set title bar to Hidden, this means the position of the sidebar buttons needs to be accounted for.

Consider the following scenarios, particularly when titlebar is hidden, on macOS vs. Windows:

• Left sidebar closed
• Right sidebar closed
• Popout widow does not have sidebars
• Fullscreen does not have window buttons

View header

The view header is now disabled by default and the view-header-icon has been removed

Users can re-enable the view header in Appearance settings.

Design guidelines

Starting with 1.0, the default Obsidian experience is designed to be consistent with operating system design guidelines and best practices. Our intention is to make Obsidian feel familiar to new users, and create cohesiveness across the screens and modes of the application.

We encourage plugin developers to follow these design guidelines so that users have a cohesive experience when using the default theme.

Padding, margins and spacing

Obsidian uses a 4 pixel grid. The 4 pixel grid is chosen because it enables the interface to scale up and down across high/low DPI screens, and also provides convenient ratios for layouts.

UI elements use multiples of 4 for padding and spacing throughout the app. We recommend using the --size CSS variables to define all dimensions throughout your plugin.

Each size variable contains two numbers which represent the base and the multiple, for example:

• --size-4-1 represents 4*1 = 4px
• --size-4-2 represents 4*2 = 8px
• --size-4-4 represents 4*4 = 16px

A few --size-2-x variables are available for small spaces where fractions of 4 can be useful, e.g. --size-2-1 represents 2*1 = 2px

Cursor

Obsidian follows operating system conventions for cursors. This means that the pointer cursor is only used when hovering over links. Avoid using the pointer cursor for buttons and interactive elements.

• Use --cursor variable to follow system conventions
• Use --cursor-link for links

Icons

Important: In a future update to Obsidian, we will provide a new way for themes to replace icons. For now you should avoid replacing icons via CSS

Obsidian includes the Lucide icon library, which has over 800 icons that you can use for your plugin.

If you are looking to use an icon that is not available in the Lucide library, you can create your own. For best compatibility and cohesiveness with Obsidian, your icons should follow Lucide’s guidelines

• Icons must be designed on a 24 by 24 pixels canvas
• Icons must have at least 1 pixel padding within the canvas
• Icons must have a stroke width of 2 pixels
• Icons must use round joins
• Icons must use round caps
• Icons must use centered strokes
• Shapes (such as rectangles) in icons must have border radius of 2 pixels
• Distinct elements must have 2 pixels of spacing between each other

Lucide also provides templates and guides for vector editors such as Illustrator, Figma, and Inkscape.