Kami Reader

English | 简体中文

Optional immersive workspace layer

For a more continuous Folio Shell across New Tab, Reading, Editing, sidebars, Outline, Ribbon, and Reading Stage, optionally install Kami Reader Companion. Kami Reader works independently, and Companion also supports Obsidian's Default Theme.

Last updated: 2026-08-11

Inspired by tw93/kami. Not affiliated with or endorsed by tw93. All visual design tokens trace to the original kami project (MIT); this repo is an unofficial Obsidian adaptation.

An unofficial Obsidian Workspace adaptation inspired by tw93/kami. It translates kami's print-grade typographic system — warm parchment surface, ink-blue accent, serif-led hierarchy, warm-gray neutrals — onto the Obsidian editor without changing Obsidian's navigation model.

Status: Published on the Obsidian Theme Gallery. Public repo: https://github.com/KKenny0/obsidian-kami · Latest release: 0.2.1

Visual Language

Reviewed against Kami v1.11.0 on 2026-08-02. The complete Workspace shell is an unofficial Obsidian adaptation. Dark mode intentionally retains --bold-weight: 600 for screen readability; it is an exception to Kami's print-emphasis rule, not a claim of exact conformance.

All neutrals carry a yellow-brown warm undertone (no cold blue-grays) in both light and dark variants. Ink blue is used sparingly — the print-design ≤5% rule is relaxed for the editor context but the intent holds: accent only, never chrome.

Screenshots

Reading View (Light)	Editing View (Light)

Reading View (Dark)	Callout Severity Ladder

Featured Card Embed	Command Palette	Settings Panel

Task Completion in Nested Lists

Screenshots are captured in screenshots/. See screenshots/SCREENSHOTS.md when refreshing the set for a new release. Release screenshots must use the synthetic fixture vault described there; never capture a personal or production vault.

Style Settings

This theme ships a Style Settings schema for the variables users are most likely to tune. No CSS editing is required.

After installing the Style Settings community plugin, go to Settings → Style Settings → Kami Reader to adjust:

• Body font family — swap LXGW WenKai Screen (kaiti) for Source Han Serif (songti) if kaiti fatigues
• Body line-height — 1.55 default, range 1.3–1.9 (Live Preview needs Cmd+E toggle after change; Reading View updates instantly)
• Note max width — 700px default
• Bold emphasis strength — without a Style Settings override, 500 in Light and 600 in Dark by default; choose 500, 600, or 700 if your font setup needs a different calibration
• Accent color (light + dark) — single accent swap, instantly re-themes
• Primary background (light + dark) — tune parchment warmth

The schema intentionally exposes only 6 high-leverage variables. Everything else stays fixed in theme.css to honor kami's restraint principle: too many switches would dilute the design system.

Typography

--font-text-theme: "Charter", "Georgia",
                   "LXGW WenKai Screen", "LXGW WenKai",
                   "Source Han Serif SC", "Noto Serif CJK SC",
                   "Songti SC", "STSong", "SimSun", serif;

• Charter — English serif. macOS-native (/System/Library/Fonts/Charter.ttc), no install needed. Falls back to Georgia on other platforms. This is the font kami itself uses for English.
• LXGW WenKai Screen — CJK 楷书, OFL 1.1. Screen variant optimized for low-DPI displays. Closes the gap with kami's original 仓耳今楷02 (which is commercial-restricted).
• JetBrains Mono — Code, OFL 1.1.
• Inter — UI / interface, OFL 1.1.

Optional font install

Only LXGW WenKai Screen needs manual install. Without it, CJK falls back to Songti SC (macOS) / SimSun (Windows) — readable but loses the kaiti warmth.

• LXGW WenKai Screen — https://github.com/lxgw/LxgwWenKai-Screen/releases (grab LXGWWenKaiScreen-Regular.ttf + Bold.ttf)
• JetBrains Mono (optional, code already falls back to SF Mono / Cascadia): https://www.jetbrains.com/lp/mono/

Installation

From Obsidian Theme Gallery (recommended)

1. Obsidian → Settings → Appearance → click Manage next to Themes
2. Browse → search "Kami Reader" → Install → Use
3. (Optional) Install the Style Settings community plugin for the 6 tunable variables (font, line-height, width, bold emphasis, accent, background)

Gallery installs are unaffected by the macOS Sequoia sandbox issue described below. Obsidian writes the theme files itself, so App Store users can install Kami Reader cleanly from Browse Themes.

Manual install / developer iteration (macOS Sequoia sandbox workaround)

⚠️ Why this section exists. Mac App Store Obsidian runs in a sandbox. macOS Sequoia 15+ tags every file created by cp from Terminal with com.apple.provenance. The sandbox then refuses to load those files as theme resources — Obsidian silently skips the theme folder. This matters for developers iterating on theme.css who copy files into their own vault's .obsidian/themes/ directory. End users installing via Gallery (the path above) are not affected.

The workaround for local iteration: ship kami as a CSS snippet instead of a theme, and inject it via Obsidian's own Vault API from the DevTools console. Files written by app.vault carry Obsidian provenance and load normally.

One-time setup

1. Confirm Appearance → Themes is set to Default (no other theme should be active; another theme's body.<name>-theme class will out-spec kami's body.theme-light selector).
2. From this directory, generate the inject script:

   ./sync.sh
   

3. Open the generated inject-kami-snippet.js, Cmd+A select all, Cmd+C copy.
4. In Obsidian: Cmd+Option+I → Console tab → Cmd+V paste → Enter. You should see ✓ kami.css created (... chars).
5. Settings → Appearance → scroll to CSS Snippets → enable kami.

Iterating on the CSS

# Edit theme.css, then:
./sync.sh
# Re-copy inject-kami-snippet.js contents → paste into Obsidian Console.
# Then toggle the kami snippet off → on to force reload.

Hot-reload of modified snippets is not automatic — Obsidian reads snippet files at startup. After re-injecting via app.vault.modify, toggle the snippet off and on in Settings → Appearance → CSS Snippets to pull the new content.

Coverage

Current coverage includes a complete Workspace shell:

• ✅ Base color tokens (60+ variables, both light and dark palettes)
• ✅ Dark variant — Deep Dark #141413 + Ink Light #2D5A8A, preserving the same yellow-brown undertone and single-accent restraint as light mode.
• ✅ Reading View: headings, body, lists (native markers), tables, blockquote (2pt ink-blue rail + olive text, no bg), code, frontmatter, embeds
• ✅ Editing View (CodeMirror 6): syntax tokens, cursor, selection, active line, formatting marks
• ✅ Complete Workspace shell: titlebar, root and sidebar tabs, ribbon, left/right sidebars, pane dividers, file explorer/search, view header, and attached status bar
• ✅ Command palette, quick switcher, settings panel, modals, menus, toggles, checkboxes, and scrollbars
• ✅ Reduced-motion preference respected

Not covered (deferred):

• PDF Export stylesheet (kami is print-native; this is a Phase 1.5 candidate)
• Plugin-specific overrides (Dataview, Templater, Excalidraw) — verify as encountered

Publishing Notes

Kami Reader is published on the Obsidian Theme Gallery: https://community.obsidian.md/themes/kami-reader.

Obsidian pulls theme files from the GitHub release tag matching manifest.json.version exactly, with no v prefix.

Design Decisions

1. Forked from Obsidian Default, not Minimal. Minimal carries its own design language; mixing parchment into it produces visual dissonance. Minimal also uses body.minimal-theme class selectors (specificity 0,1,1) that beat kami's old :root (0,0,1). Default has no such class.
2. Variables on body.theme-light / body.theme-dark, not :root. Obsidian's built-in app.css defines base vars under .theme-light / .theme-dark (specificity 0,1,0). :root (0,0,1) loses the cascade; body.theme-light (0,1,1) wins.
3. Charter, not Newsreader. Kami v1.11.0 was reviewed on 2026-08-02 and specifies Charter for English; it's also macOS-native, removing a font-install step.
4. Tag backgrounds use solid #E4ECF5, never rgba. kami explicitly bans rgba tag backgrounds (WeasyPrint double-rect bug in PDF export).
5. Ring + whisper shadows, never hard drop shadows. kami spec; hard drop shadows look heavy in print and on screen.
6. Native list markers across Reading and Live Preview. A Reading-only em-dash marker looked elegant but made editing and reading disagree; kami's restraint now comes from quiet marker color and tighter nested spacing.
7. Blockquote: 2pt ink-blue rail + olive text, no background, no italic. Restraint over decoration.
8. LXGW WenKai Screen over Source Han Serif. Kami's original (仓耳今楷02) is a kaiti; Source Han Serif is a print songti. The kaiti keeps the calligraphic warmth that defines kami's character.
9. No synthetic bold weights. Kami forbids fake bold; headings use 500/600 actual weights only. Dark mode intentionally keeps --bold-weight: 600 for screen readability as an Obsidian-specific exception.
10. Shipped as snippet, not theme, in Phase 1. Workaround for macOS Sequoia sandbox; see Installation section.

Known Tradeoffs

1. The parchment surface is warmer than most editor themes. If it feels too yellow for long sessions, tune Primary background in Style Settings.
2. Kaiti gives Kami Reader its CJK texture, but not every reader likes it for daily editing. If LXGW WenKai Screen feels tiring, switch Body font family to a songti-style stack such as Source Han Serif SC.
3. Bold is calibrated per theme: without a Style Settings override, restrained 500 in Light and more salient 600 in Dark. If your platform or font needs a different calibration, use Bold emphasis strength at 500, 600, or 700.

File Layout

kami-obsidian/
├── manifest.json              # Theme metadata (name, version, minAppVersion)
├── theme.css                  # Source of truth for all kami styles + inline @settings YAML
├── data-theme.json            # Style Settings schema for theme-folder mode
├── sync.sh                    # Regenerates inject-kami-snippet.js from theme.css
├── inject-kami-snippet.js     # Generated by sync.sh — paste into Obsidian Console
├── screenshots/               # 9-shot set (see SCREENSHOTS.md)
├── LICENSE                    # MIT (pure text so GitHub licensee detects SPDX:MIT)
├── README.md                  # English docs (this file)
└── README.zh-CN.md            # 简体中文文档

inject-kami-snippet.js is a build artifact, not source. Regenerate via ./sync.sh after any theme.css change.

Releases

Release tags match manifest.json version exactly (no v prefix) — Obsidian pulls theme files from the GitHub release tagged with the manifest version.

License

MIT — see LICENSE.

Visual design system source: tw93/kami (MIT). This theme is a derivative adaptation; all design token values trace to the original kami project.

Fonts referenced but not bundled:

• Charter (OFL, macOS-native)
• LXGW WenKai / LXGW WenKai Screen (OFL, https://github.com/lxgw/LxgwWenKai)
• JetBrains Mono (OFL)
• Inter (OFL)

Credits

• Visual style & design tokens: tw93/kami — MIT. This is an unofficial third-party adaptation; see the upstream maintainer's response.
• Fonts: Charter (OFL, macOS-native), LXGW WenKai (OFL), JetBrains Mono (OFL), Inter (OFL)