Obsidian Theme Designer

Help users iteratively design Obsidian themes through visual browser previews, then generate an importable CSS snippet.

Language: Respond in the same language the user writes in. If they write in Chinese, reply in Chinese. If English, reply in English.

Process Flow

digraph theme_design {
  "1. Analyze Vault" [shape=box];
  "2. Extract Theme Variables" [shape=box];
  "3. Launch Visual Companion" [shape=box];
  "4. Gather Preferences" [shape=box];
  "5. Iterative Design Refinement" [shape=diamond];
  "5b. Install Fonts" [shape=box];
  "6. Generate CSS Snippet" [shape=box];
  "7. Import Guide" [shape=doublecircle];

  "1. Analyze Vault" -> "2. Extract Theme Variables";
  "2. Extract Theme Variables" -> "3. Launch Visual Companion";
  "3. Launch Visual Companion" -> "4. Gather Preferences";
  "4. Gather Preferences" -> "5. Iterative Design Refinement";
  "5. Iterative Design Refinement" -> "5. Iterative Design Refinement" [label="user requests changes"];
  "5. Iterative Design Refinement" -> "5b. Install Fonts" [label="user approves"];
  "5b. Install Fonts" -> "6. Generate CSS Snippet";
  "6. Generate CSS Snippet" -> "7. Import Guide";
}

Step 1: Analyze Vault

Read the following files to understand current configuration:

• .obsidian/appearance.json

  — current theme, font size, light/dark mode

• .obsidian/community-plugins.json

  — installed plugins (check for Style Settings)

• .obsidian/themes/

  — downloaded community themes

• .obsidian/snippets/

  — existing custom CSS

Also scan the vault directory structure to understand note types (papers, journals, project management, etc.) so preview content reflects real usage.

Step 2: Extract Theme CSS Variables

Use grep to extract key variables from each installed theme's

theme.css

--background-primary

--background-secondary

--color-base-00

--text-normal

--text-muted

--text-accent

--interactive-accent

--color-accent

--font-text-theme

--font-interface-theme

--h1-color

--h6-color

--size-h1

--size-h6

line-height

--p-spacing

font-size

Extract values for both

.theme-light

.theme-dark

Step 3: Launch Visual Companion

Use the superpowers brainstorming Visual Companion to show options in the browser.

Windows:

# run_in_background: true
scripts/start-server.sh --project-dir /path/to/vault

Then read

$STATE_DIR/server-info

Step 4: Gather Preferences

Ask one question at a time with multiple choices. Always provide a recommended default for users who are unsure ("if you're not sure, I recommend X because...").

4a. Reference Collection (ask first)

Before showing style options, ask the user:

"Do you have any references you like — a screenshot, website, or app whose look you want to emulate? If not, no worries, I'll show you some options."

If the user provides a reference, analyze its visual characteristics (color temperature, font style, density, decoration level) and use them to guide subsequent choices. If the reference clearly determines style direction and/or color preference, skip the corresponding sub-steps (4b, 4c) and go directly to the next undecided question. Don't ask what the user has already shown you.

4b. Overall Style Direction

Show style directions visually in the browser with mini mockups, not just text labels. Each option should include a relatable analogy so non-designers can understand:

If the user says "I don't know" or "any is fine", recommend the direction that best matches their vault content (e.g., academic for research-heavy vaults).

4c. Color Preference

Ask in plain terms, NOT hex codes:

"Do you prefer cool tones (blue, teal, gray), warm tones (gold, orange, brown), or neutral (pure black & white)?"

Then show 2-3 color palette options visually in the browser with the chosen direction applied. Never ask users to pick hex values directly.

4d. Light/Dark Mode

• Dark only / Light only / Dual mode
• If dual mode: each mode can have a different accent color — show side-by-side in browser

4e. Font Selection with frontend-design

REQUIRED: Invoke the

frontend-design:frontend-design

Critical: NEVER present font names in the terminal as the primary selection method. Users don't know what "Playfair Display" looks like. Always show fonts rendered in the browser — users choose by visual appearance, not by name.

Principles (from frontend-design):

• NEVER use generic fonts (Arial, Inter, Roboto, system-ui defaults). Choose fonts with character.
• Each variant should use a DIFFERENT font combination to give real contrast.
• For CJK + Latin bilingual content, pair Latin fonts with matching CJK fonts (e.g., Playfair Display + Noto Serif SC, DM Sans + Noto Sans SC).
• Load fonts via Google Fonts

  <link>

  tags in previews. In the final CSS snippet, use locally-installable font names with fallbacks.

Font showcase format: Create a full-page HTML gallery (not content fragments) with 8-10 font cards. Each card should render the SAME sample content (including bilingual text AND numbers/data) in that card's font pairing. Include a Dark/Light mode toggle at the top. Users can click cards to select. The sample text must include:

• A Chinese heading
• A paragraph with mixed Chinese and English
• A line with numbers and data (e.g., "从 127.4s 降至 48.6s，优化率达 61.8%")
• A code snippet in the monospace font
• Tags

Users may mix-and-match: A user may like the Chinese rendering from one card and the English/number rendering from another. Support this — the final CSS can combine fonts from different cards (e.g., Spectral for Latin + Noto Serif SC for CJK).

Step 5: Iterative Design Refinement

Show full simulation in browser (sidebar + editor), confirm step by step.

Critical rules (MUST follow):

• Bilingual content: Preview MUST include both Chinese and English text — headings, body, and quotes
• Dual-mode side-by-side: Use

  <div class="split">

  to show light/dark modes next to each other
• Unified fonts: Light and dark modes MUST use the same font family — only change colors
• Real elements: Preview must cover h1-h3 headings, body text, blockquotes, code blocks, inline code, tags, tables, and links
• Use real content: Read actual notes from the vault for preview text

Write a new file for each iteration (e.g.,

design-v2.html

Step 5b: Install Fonts

After the user approves the font selection, download and install the chosen fonts to the system so Obsidian can use them.

Download from Google Fonts CSS API:

# 1. Fetch the CSS which contains direct .ttf URLs
CSS=$(curl -s "https://fonts.googleapis.com/css2?family=FontName:wght@400;600;700" \
  -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)")

# 2. Extract and download all .ttf URLs
echo "$CSS" | grep -o 'https://[^)]*' | while read url; do
  curl -sL "$url" -o "/tmp/fonts/$(basename "$url")"
done

Install per platform:

• Windows: Copy

  .ttf

  files to

  $HOME/AppData/Local/Microsoft/Windows/Fonts/

  and register in registry:

  FONTDIR="$HOME/AppData/Local/Microsoft/Windows/Fonts"
  cp /tmp/fonts/*.ttf "$FONTDIR/"
  # Register each font in HKCU registry
  for f in /tmp/fonts/*.ttf; do
    fname=$(basename "$f")
    powershell.exe -Command "New-ItemProperty -Path 'HKCU:\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Fonts' -Name '$fname' -Value '$(cygpath -w "$FONTDIR")\\$fname' -PropertyType String -Force"
  done
  

• macOS: Copy to

  ~/Library/Fonts/

• Linux: Copy to

  ~/.local/share/fonts/

  then run

  fc-cache -f

Important: Remind user to restart Obsidian after font installation for changes to take effect.

Step 6: Generate CSS Snippet

Once the user approves, generate a CSS snippet file to

.obsidian/snippets/

CSS structure template:

/* Shared fonts */
body {
  --font-text-theme: '...';
  --font-interface-theme: '...';
}

/* Light mode */
.theme-light {
  --background-primary: ...;
  --text-accent: ...;
  --h1-color: ...; --h2-color: ...;
}

/* Dark mode */
.theme-dark {
  --background-primary: ...;
  --text-accent: ...;
  --h1-color: ...; --h2-color: ...;
}

/* Element-specific styles: headings, blockquotes, code, tags, etc. */

Notes:

• Use Obsidian's native CSS variable names for compatibility
• Use

  !important

  only when necessary to override a base theme
• Separate light/dark with

  .theme-light

  /

  .theme-dark

Step 7: Import Guide

Tell the user how to enable the snippet:

1. Open Obsidian Settings (Ctrl+,)
2. Go to Appearance
3. Optionally switch CSS theme back to default (or keep a base theme)
4. Scroll to CSS Snippets at the bottom
5. Click the refresh button, then toggle the new snippet on
6. Use Obsidian's built-in light/dark mode toggle to see both color schemes

Common Mistakes

.obsidian/snippets/