Skip to content

aidenlx/zotlit / .agents/skills/obsidian-css

obsidian-css

Verified

Style Obsidian plugin UI Tailwind-first with native components. Use when writing or reviewing any styled React/JSX or CSS in apps/obsidian/ — picking colors, spacing, typography, borders, radius, shadows, dark-mode tokens, the `zt:` prefix, `.zt-root` preflight setup, component wrapper selection, or deciding between a utility, a native element, and a stylesheet.

Obsidian Plugin CSS & Tailwind Style Guide

Plugin UI should feel like part of Obsidian under whatever theme the user installed. Theme authors get that by overriding Obsidian's CSS variables; plugin authors get it by consuming them — through Tailwind tokens that are backed by those variables.

Tailwind-first

Use zt:-prefixed utilities on the styled element. Feature stylesheets sit beside their owning code when a utility cannot reach host-owned DOM or override host CSS.

  • The zt: prefix is on every utility — zt:flex, zt:gap-2, zt:bg-background, zt:rounded-md — and variants chain after it: zt:hover:opacity-100, zt:@md:columns-2. Tailwind v4's prefix() scopes the compiled selectors so they never collide with another plugin's output. The @theme variables in src/zt-main.css keep their authored names (no prefix).
  • No token for an Obsidian variable → reference it directly with the arbitrary-variable syntax — zt:bg-(--modal-background), zt:p-(--size-4-3) — or extend zt-main.css following the existing pattern.
  • Merge with cn() from @/lib/utils (prefix-aware twMerge), and compose variants with tv from @/lib/tw rather than tailwind-variants directly.
  • Obsidian's control classes stay in the wrappers. clickable-icon, mod-cta, setting-item* and the like reach a component only through src/components/obsidian/; a control or layout of your own is zt: utilities over Obsidian's variables (zt:rounded-(--clickable-icon-radius), zt:text-(--icon-color)). In a React tree a form row is JSX — a label, the wrapper's control, utilities — rather than new Setting. The zotlit-css lint rules hold .tsx files to both.

The three rules

  1. Tokens, never literals. A #hex, an rgb(…), or an 8px looks right in the default theme and breaks in every other one. Semantic tokens also already track light/dark and the user's accent, so manual dark-mode variants are dead weight.

    <div className="zt:bg-[#2a2a2a] zt:text-[#ddd] zt:p-[8px_12px]" />   // bad
    <div className="zt:bg-white dark:zt:bg-[#1e1e1e]" />                  // bad
    <div className="zt:bg-background zt:text-foreground zt:px-3 zt:py-2" /> // good
    
  2. Native elements bare. Obsidian fully styles <button>, <input> (every type), <textarea>, <select>, and the toggle — background, border, padding, radius, height, focus and disabled states. Utilities on them cover layout only (zt:flex, zt:w-full, zt:mt-2); appearance utilities fight Obsidian and drift across releases.

    <button className="zt:bg-primary zt:rounded-md zt:px-3 zt:py-1">Save</button>  // bad
    <Button variant="cta">Save</Button>                                            // good
    
  3. No !important; scope custom CSS low. !important blocks user snippets from ever overriding you. Scope under a zt--prefixed class, target your own DOM rather than Obsidian internals (.workspace-leaf-content[data-type=…] .callout-title breaks on the next release), and expose knobs as --zt-… properties defaulted to an Obsidian variable.

Quick decision tree

  1. A native component exists → the React wrapper from src/components/obsidian/, or the imperative obsidian class in DOM-built UI (see Native components). A control that draws its own appearance is the exception — a chip whose whole look is the caller's utilities, where the wrapper's supply, Obsidian's button box and its mod-* variants, is exactly what the chip takes back off. Build the bare element and record there why the wrapper would add nothing; src/components/chooser.tsx's Trigger is the recorded case.
  2. The value is only known at runtime → the declaration stays in the class list and style carries the datum alone (see Runtime values).
  3. Color → a semantic token (zt:text-muted, zt:bg-background, zt:text-accent-foreground), never a raw palette one. For an RGB overlay, pair the -rgb variant: rgba(var(--color-red-rgb), 0.2).
  4. Spacing / size → Tailwind's default scale (zt:gap-2, zt:p-3). Obsidian's --size-4-N are fixed 4px multiples no theme overrides, so they map 1:1.
  5. Radius → zt:rounded-sm/md/lg/xl (--radius-s/m/l/xl). Typography → zt:text-xs/sm/base/lg.
  6. A modal body can outgrow the window → mod-scrollable-content on modalEl plus a .modal-button-container; read modal-layout.md.
  7. A component variable exists (--modal-background, --button-radius, --tab-text-color) → arbitrary-variable syntax, or extend zt-main.css.

references/foundations.md is where to look first when you don't know which variable to use.

Runtime values

A value the build cannot see — a colour Zotero stored, a measured width — has no class of its own. Keep the declaration in the class list and let style carry the datum:

<blockquote
  className="zt:border-l-2 zt:border-l-(--zt-annot-color)"
  style={{ "--zt-annot-color": annot.color } as React.CSSProperties}
/>

A finite state is an attribute rather than a value, so every class it can take is one the build already generated:

// Present or absent — `zt:data-selected:` matches presence, so pass `undefined`, not "false".
<div data-selected={selected ? "" : undefined} className="zt:data-selected:border-primary" />

A state a descendant styles against travels by selector, so the child reads the ancestor instead of taking a prop:

<div className="zt:group" data-selected="">
  <div className="zt:opacity-70 zt:group-hover:opacity-100 zt:group-data-selected:opacity-100" />
</div>

The check: style holds --zt-* keys only. A CSS property name there means the declaration left the class list, where the theme's tokens, the variants, and cn() can no longer reach it.

Scoped preflight (.zt-root)

src/zt-main.css applies Tailwind's preflight scoped to plugin UI roots, never globally:

@layer theme, base, components, utilities;          /* explicit order: utilities > base */
@import "tailwindcss/theme.css" layer(theme) prefix(zt);
@import "tailwindcss/utilities.css" layer(utilities) prefix(zt);

@layer base {
  .zt-root { @import "tailwindcss/preflight.css"; }  /* Tailwind inlines + scopes this at build */
}

Mark the container the view owns — ItemView.contentEl, a modal's contentEl, a settings pane — rather than a node inside the React tree:

class AnnotationView extends ItemView {
  async onOpen() {
    this.contentEl.classList.add("zt-root");
    createRoot(this.contentEl).render(<AnnotView />);
  }
}

Inside it, write semantic HTML — <blockquote>, <p>, <ul>/<li>, <h2>, <hr> — and a width utility is a full border (zt:border-l-2, zt:divide-y zt:divide-border) because preflight supplies border-style: solid. For a data-driven color keep the width in the utility and pass the color as a custom property — see Runtime values.

It is safe because preflight sits in @layer base: your zt: utilities (@layer utilities) outrank it, and Obsidian's unlayered stylesheet outranks every layer. So preflight only clears browser UA defaults — <blockquote>'s margin: 1em 40px, <p>'s margin: 1em 0, the 40px list indent.

That same cascade means Obsidian's own unlayered bare-element rules survive inside .zt-root, and the set is wider than it looks (<hr>, headings, <ol>, a, kbd, button, :focus { outline: none }, …). references/preflights.md has the full list, plus what to do outside a scoped root. Markdown rendered by MarkdownRenderer inside .zt-root still looks right for the same reason — .markdown-rendered rules are unlayered and win.

Native components

  • React — wrappers in src/components/obsidian/ for anything needing modifier-class logic: Button, IconButton, Toggle, Dropdown (+ DropdownItem, DropdownGroup), Slider, Color, Icon, SearchInput. Read the source for each API.
  • Bare in JSX — <input type="text/search/email/password/number/date/datetime-local">, <input type="checkbox">, <input type="radio">, <textarea>. Obsidian's preflight styles these fully, so they take no wrapper. Reach for AutosizeTextarea from react-textarea-autosize when a textarea should grow with its content.
  • Imperative DOM (setting tabs, API-built modals) — ButtonComponent, ToggleComponent, TextComponent, TextAreaComponent, DropdownComponent, ColorComponent, SliderComponent from the obsidian module.
  • Tooltips are aria-label, spread through tooltipAttrs; apps/obsidian/src/lib/utils.ts owns the helper.

Verifying

Run /obsidian-debug for the build → reload → eval → screenshot loop. The probes worth running in it:

  • getComputedStyle(el) to confirm a token resolved, and to catch a leaked UA style (a bare <blockquote> outside .zt-root reporting marginLeft: "40px").
  • getBoundingClientRect() to compare left edges and heights across components.
  • document.body.className to confirm which scheme is live, then toggle Settings → Appearance → Base color scheme and change the accent — both should need no extra CSS. A popular community theme (Minimal, Things) is the last check; anything that looks off is usually a hardcoded value the theme is overriding.

Reference files

Catalogs of Obsidian variables — read on demand, one topic at a time.

  • references/foundations.md — colors (semantic + accent palette), spacing, typography, radiuses, borders, layers, icons, cursors. Start here.
  • references/preflights.md — which bare elements Obsidian styles, which unlayered rules survive .zt-root, and the no-preflight fallback.
  • references/components.md — buttons, inputs, dropdowns, checkboxes, toggles, sliders, modals, popovers, prompts, tabs, navigation, pills, color inputs, indentation guides, dragging.
  • references/editor.md — markdown content: headings, links, tables, callouts, code, blockquotes, lists, tags, embeds, footnotes, properties, bases, inline title.
  • references/window.md — workspace chrome: ribbon, sidebar, status bar, dividers, scrollbars, scroll containers (overlay scrollbar, pane background, sticky edges), window frame, vault profile.
  • references/plugins.md — built-in plugin views: file explorer, search, graph, canvas, sync.
  • ../../../apps/obsidian/docs/bases-toolbar-menu.md — a Bases-style menu, page, or form: the anatomy, keyboard, and save behaviour of Bases toolbar menus.

When a catalog leaves a question open — exactly what Obsidian applies to an element, whether a rule is layered — read Obsidian's own stylesheet: /obsidian-asar-extract writes app.css next to app.js in node_modules/.ob-rev-<version>/, and rg over it answers against the exact version you build for.

The catalogs drift as Obsidian renames or drops variables. After you extract a new Obsidian version, run node .claude/skills/obsidian-css/check-references.mjs; each file:line it lists names a variable that build no longer carries — correct the row against app.css or delete it.

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: 319kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall