gapmiss/obsidian-plugin-skill / .agents/skills/obsidian
obsidian
VerifiedComprehensive guidelines for Obsidian.md plugin development including ESLint rules from eslint-plugin-obsidianmd v0.6.0, TypeScript best practices, memory management, API usage (requestUrl vs fetch), UI/UX standards, popout window compatibility, community.obsidian.md submission process, and Scorecard optimization. Use when working with Obsidian plugins, main.ts files, manifest.json, Plugin class, MarkdownView, TFile, vault operations, or any Obsidian API development.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 22.0 KB |
| reference/accessibility.md | markdown | 8.0 KB |
| reference/code-quality.md | markdown | 21.9 KB |
| reference/community-scanner.md | markdown | 10.8 KB |
| reference/css-styling.md | markdown | 10.7 KB |
| reference/eslint-setup.md | markdown | 72.3 KB |
| reference/file-operations.md | markdown | 6.1 KB |
| reference/memory-management.md | markdown | 6.3 KB |
| reference/submission.md | markdown | 5.2 KB |
| reference/type-safety.md | markdown | 1.5 KB |
| reference/ui-ux.md | markdown | 29.0 KB |
reference/css-styling.md
View on GitHub# CSS Styling Best Practices
Proper CSS styling ensures your plugin respects user themes and provides a native Obsidian experience.
## Table of Contents
- [Avoid Inline Styles](#avoid-inline-styles)
- [Use Obsidian CSS Variables](#use-obsidian-css-variables)
- [Avoid `!important`](#avoid-important)
- [Avoid `:has` Selector](#avoid-has-selector)
- [Scope Plugin Styles](#scope-plugin-styles)
- [Theme Support](#theme-support)
- [Spacing and Layout](#spacing-and-layout)
- [Complete Examples](#complete-examples)
---
## Avoid Inline Styles
### Avoid Inline Styles
Rule: `obsidianmd/no-static-styles-assignment`
❌ **INCORRECT**:
```typescript
element.style.color = 'red';
element.style.fontSize = '14px';
element.setAttribute('style', 'margin: 10px;');
element.setCssStyles({ color: 'red' }); // fixed value — reported since v0.5.0
```
✅ **CORRECT**:
```typescript
// Add class in TypeScript
element.addClass('my-custom-element');
// Values that change at runtime: set a CSS variable, consume it in styles.css
element.setCssProps({ '--my-width': `${width}px` }); // needs minAppVersion 1.1.7
// Computed values and clearing a style are not reported (v0.5.1)
element.setCssStyles({ top: `${y}px` });
element.style.color = '';
// Define styles in styles.css using Obsidian CSS variables
.my-custom-element {
color: var(--text-error);
font-size: var(--font-ui-small);
margin: var(--size-4-2);
}
```
Rationale: Move all styles to CSS for better theme/snippet adaptability. Use Obsidian's CSS variables for theme consistency. This rule is an `error` and, for new submissions, a hard error in the scanner. v0.5.0 checks `setCssStyles()`/`setCssProps()` too. Since v0.5.1 it reports only properties with a fixed value (a computed value like `` `${y}px` `` is allowed), reports at that property rather than at the call — move an `eslint-disable-next-line` above a multi-line call to the property — and allows `style.setProperty('--name', …)` with any value. `setCssStyles()` and `setCssProps()` need `minAppVersion` 1.1.7, which `no-unsupported-api` checks since v0.5.1. Since v0.6.0, with type information, it reports a `style` object only when its type is an element's `CSSStyleDeclaration` (or can't be told, such as `any`) — a plugin's own `settings.style.theme = 'compact'` is not reported.
---
### Don't Create `<link>` or `<style>` Elements
Rule: `obsidianmd/no-forbidden-elements`
❌ **INCORRECT**:
```typescript
// Don't manually create and append stylesheets
const styleSheet = document.createElement('link');
styleSheet.rel = 'stylesheet';
styleSheet.href = 'path/to/styles.css';
document.head.appendChild(styleSheet);
// Don't create inline style elements
const style = document.createElement('style');
style.textContent = 'body { color: red; }';
document.head.appendChild(style);
// Also forbidden with Obsidian helpers
containerEl.createEl('link');
containerEl.createEl('style');
```
✅ **CORRECT**:
```typescript
// Use styles.css file in your plugin root
// Obsidian automatically loads it for you
// No manual CSS loading needed!
```
Rationale: Creating and attaching `<link>` or `<style>` elements is not allowed. For loading CSS, use a `styles.css` file in your plugin directory, which Obsidian loads automatically.
---
## Use Obsidian CSS Variables
### Use Obsidian CSS Variables
Rule: Theme consistency and user customization
Always use Obsidian's CSS variables instead of hardcoded values to ensure your plugin respects user themes and customization.
❌ **INCORRECT**:
```css
.my-plugin-modal {
background: #1e1e1e;
color: #dadada;
padding: 16px;
border-radius: 8px;
font-size: 14px;
}
```
✅ **CORRECT**:
```css
.my-plugin-modal {
background: var(--modal-background);
color: var(--text-normal);
padding: var(--size-4-4);
border-radius: var(--radius-m);
font-size: var(--font-ui-medium);
}
```
### Common CSS Variables by Category
**Colors**:
- `--text-normal`, `--text-muted`, `--text-faint` - Text colors
- `--text-accent`, `--text-accent-hover` - Accent colors for links/buttons
- `--text-error`, `--text-success`, `--text-warning` - Status colors
- `--background-primary`, `--background-secondary` - Background colors
- `--interactive-normal`, `--interactive-hover`, `--interactive-accent` - Interactive elements
- `--background-modifier-border` - Border colors
**Spacing** (4px grid):
- `--size-4-1` (4px), `--size-4-2` (8px), `--size-4-3` (12px)
- `--size-4-4` (16px), `--size-4-6` (24px), `--size-4-8` (32px)
**Typography**:
- `--font-text-theme` - Editor text font
- `--font-interface-theme` - UI font
- `--font-monospace-theme` - Code font
- `--font-ui-small` (13px), `--font-ui-medium` (15px), `--font-ui-large` (20px)
- `--font-bold`, `--font-normal` - Font weights
**Borders & Radius**:
- `--radius-s`, `--radius-m`, `--radius-l` - Border radius
- `--input-radius` - Input field border radius
- `--border-width` - Standard border thickness
- `--background-modifier-border` - Standard border color
- `--background-modifier-border-focus` - Focus state border/shadow color
- `--background-modifier-border-hover` - Hover state border color
**Modal/Dialog**:
- `--modal-background`, `--modal-border-color`
- `--modal-max-width`, `--modal-max-height`
---
## Avoid `!important`
### Avoid `!important`
Rule: Scanner warning — style override
❌ **INCORRECT**:
```css
.my-plugin-button {
color: red !important;
background: blue !important;
}
```
✅ **CORRECT**:
```css
/* Increase specificity instead */
.my-plugin-container .my-plugin-button {
color: var(--text-error);
background: var(--interactive-accent);
}
/* Or use CSS variables for overridable values */
.my-plugin-button {
color: var(--my-plugin-button-color, var(--text-normal));
}
```
Rationale: `!important` overrides user themes and CSS snippets. Increase selector specificity or use CSS variables instead. The community scanner flags every use of `!important`.
---
## Avoid `:has` Selector
### Avoid `:has` Selector
Rule: Scanner warning — performance
❌ **INCORRECT**:
```css
.my-plugin-container:has(.active-item) {
border: 1px solid var(--interactive-accent);
}
div:has(> .my-plugin-icon) {
padding: var(--size-4-2);
}
```
✅ **CORRECT**:
```typescript
// Add a class from TypeScript when the condition is met
if (container.querySelector('.active-item')) {
container.addClass('my-plugin-has-active');
}
```
```css
.my-plugin-has-active {
border: 1px solid var(--interactive-accent);
}
```
Rationale: `:has` causes broad selector invalidation and significant performance issues. The community scanner flags all uses. Instead, toggle classes from TypeScript when the condition changes.
---
## Scope Plugin Styles
### Scope Plugin Styles
Rule: Avoid conflicts with Obsidian and other plugins
Always scope your CSS to your plugin's specific elements to prevent style conflicts.
❌ **INCORRECT**:
```css
/* Too broad - affects all buttons everywhere */
button {
background: blue;
}
/* Conflicts with Obsidian */
.modal {
width: 600px;
}
```
✅ **CORRECT**:
```css
/* Scoped to your plugin's view */
.my-plugin-view button {
background: var(--interactive-accent);
}
/* Scoped to your plugin's modal */
.modal.my-plugin-modal {
max-width: var(--modal-max-width);
}
/* Or use unique class names */
.my-plugin-custom-button {
background: var(--interactive-accent);
}
```
Rationale: Scoping prevents your styles from affecting Obsidian's UI or other plugins. Use unique class names or scope to your plugin's containers (views, modals, settings).
---
### Scope to Plugin Containers
Rule: Use view and modal class names
Obsidian automatically adds class names to your plugin's elements. Use these for scoping:
```css
/* Scope to your custom view */
.view-type-my-plugin {
/* Styles only affect your view */
}
/* Scope to your modal */
.modal.my-plugin-settings-modal {
/* Styles only affect your modal */
}
/* Scope to settings tab */
.my-plugin-settings-tab {
/* Styles only affect your settings */
}
```
Add these classes in your TypeScript:
```typescript
// In your view
export class MyPluginView extends ItemView {
getViewType() {
return "my-plugin";
}
async onOpen() {
const container = this.containerEl.children[1];
container.addClass('view-type-my-plugin');
}
}
// In your modal
export class MyModal extends Modal {
onOpen() {
this.modalEl.addClass('my-plugin-settings-modal');
}
}
```
---
## Theme Support
### Support Light and Dark Themes
Rule: Respect user theme preference
Test your plugin in both light and dark themes. Obsidian's CSS variables automatically adjust.
```css
/* ✅ CORRECT - Variables adapt automatically */
.my-plugin-element {
background: var(--background-secondary);
color: var(--text-normal);
border: 1px solid var(--background-modifier-border);
}
/* ❌ AVOID - Manual theme switching */
.theme-dark .my-plugin-element {
background: #1e1e1e;
color: #dadada;
}
.theme-light .my-plugin-element {
background: #ffffff;
color: #222222;
}
```
Rationale: Using CSS variables ensures your plugin works with any theme, including community themes. Manual theme detection is fragile and doesn't support custom themes.
---
## Spacing and Layout
### Use Consistent Spacing
Rule: Follow Obsidian's 4px grid system
Use Obsidian's spacing variables for consistent layouts:
```css
.my-plugin-container {
padding: var(--size-4-4); /* 16px */
margin-bottom: var(--size-4-6); /* 24px */
gap: var(--size-4-2); /* 8px */
}
.my-plugin-compact {
padding: var(--size-4-2); /* 8px */
gap: var(--size-4-1); /* 4px */
}
```
Rationale: Obsidian uses a 4px grid for spacing. Following this ensures your plugin feels native and works well across different DPI screens.
---
## Complete Examples
### Example: Complete Modal Styling
```css
/* Scope to plugin modal */
.modal.my-todo-plugin-modal {
/* Use modal variables */
background: var(--modal-background);
border: var(--modal-border-width) solid var(--modal-border-color);
border-radius: var(--modal-radius);
max-width: var(--modal-max-width);
/* Use spacing variables */
padding: var(--size-4-6);
}
.modal.my-todo-plugin-modal .modal-title {
/* Use typography variables */
font-size: var(--font-ui-large);
font-weight: var(--font-bold);
color: var(--text-normal);
margin-bottom: var(--size-4-4);
}
.modal.my-todo-plugin-modal .modal-content {
/* Use text and spacing */
color: var(--text-muted);
font-size: var(--font-ui-medium);
line-height: var(--line-height-normal);
padding: var(--size-4-4);
}
.modal.my-todo-plugin-modal button {
/* Use interactive colors */
background: var(--interactive-accent);
color: var(--text-on-accent);
border-radius: var(--radius-m);
padding: var(--size-4-2) var(--size-4-4);
}
.modal.my-todo-plugin-modal button:hover {
background: var(--interactive-accent-hover);
}
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |