aidenlx/zotlit / .agents/skills/obsidian-css
obsidian-css
VerifiedStyle 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'sprefix()scopes the compiled selectors so they never collide with another plugin's output. The@themevariables insrc/zt-main.csskeep 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 extendzt-main.cssfollowing the existing pattern. - Merge with
cn()from@/lib/utils(prefix-awaretwMerge), and compose variants withtvfrom@/lib/twrather thantailwind-variantsdirectly. - Obsidian's control classes stay in the wrappers.
clickable-icon,mod-cta,setting-item*and the like reach a component only throughsrc/components/obsidian/; a control or layout of your own iszt: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 thannew Setting. Thezotlit-csslint rules hold.tsxfiles to both.
The three rules
-
Tokens, never literals. A
#hex, anrgb(…), or an8pxlooks 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 -
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 -
No
!important; scope custom CSS low.!importantblocks user snippets from ever overriding you. Scope under azt--prefixed class, target your own DOM rather than Obsidian internals (.workspace-leaf-content[data-type=…] .callout-titlebreaks on the next release), and expose knobs as--zt-…properties defaulted to an Obsidian variable.
Quick decision tree
- A native component exists → the React wrapper from
src/components/obsidian/, or the imperativeobsidianclass 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 itsmod-*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'sTriggeris the recorded case. - The value is only known at runtime → the declaration stays in the class list and
stylecarries the datum alone (see Runtime values). - 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-rgbvariant:rgba(var(--color-red-rgb), 0.2). - Spacing / size → Tailwind's default scale (
zt:gap-2,zt:p-3). Obsidian's--size-4-Nare fixed 4px multiples no theme overrides, so they map 1:1. - Radius →
zt:rounded-sm/md/lg/xl(--radius-s/m/l/xl). Typography →zt:text-xs/sm/base/lg. - A modal body can outgrow the window →
mod-scrollable-contentonmodalElplus a.modal-button-container; readmodal-layout.md. - A component variable exists (
--modal-background,--button-radius,--tab-text-color) → arbitrary-variable syntax, or extendzt-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 forAutosizeTextareafromreact-textarea-autosizewhen a textarea should grow with its content. - Imperative DOM (setting tabs, API-built modals) —
ButtonComponent,ToggleComponent,TextComponent,TextAreaComponent,DropdownComponent,ColorComponent,SliderComponentfrom theobsidianmodule. - Tooltips are
aria-label, spread throughtooltipAttrs;apps/obsidian/src/lib/utils.tsowns 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-rootreportingmarginLeft: "40px").getBoundingClientRect()to compare left edges and heights across components.document.body.classNameto 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.
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: 319k | 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: 196k | 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: 196k | 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: 196k | Updated | Claude CodeCodex | Verified | Install |