Settings and Themes

Open Settings with Mod+, or from the command palette. Settings are persisted as a workspace document at .zudotext.settings.json in the workspace root, so they sync to every device signed into that workspace (see Sync).

The Settings dialog has tabs for: General, Styles, Editor, Preview, Slides, Vim, Shortcuts, Move Buttons, Quick Actions, Inline AI Command, Sync, Access Tokens, Notification Center, Frontmatter Schema, Menu Bar, Device Override, and Raw Settings. The Quick Actions tab opens the Quick Actions Builder. iOS adds additional tabs when running on iOS. Pins are managed via the Header Pins dialog, not through Settings.

General Settings

Note Tray toolbar

General Settings has two groups for the Note Tray toolbar — Note Tray toolbar (position, launcher visibility, and title display) and Note Tray layout (number order, which is tray-wide because Pile View inherits its sort direction from it):

The Show titles checkbox is disabled when Toolbar position is Top or Bottom — expanded title rows are only available on a vertical rail. See Note Tray Toolbar Layout for details on title derivation and the in-bar controls.

Color Mode

Settings → Styles → Colors has a Color mode control with three options:

• System (default) — follows the OS light/dark appearance setting and repaints automatically when it changes.

• Light — always shows the light palette, regardless of the OS setting.

• Dark — always shows the dark palette, regardless of the OS setting.

There is one color scheme ("Default"), and it carries both a light and a dark palette rather than being two separate schemes to pick between — Color mode is what selects which of the two the app actually displays. Switching modes repaints instantly. A per-device override of Color mode (Settings → Device Override) also applies, the same way any other per-device setting does.

Ramp Tweaker (Settings → Styles → Colors)

The Colors tab does not expose a flat list of hex fields — it edits the same {ramps, map} structure that is persisted to .zudotext.settings.json, via a small ramp-tweaker toolkit shared with the ROOT's generate-child wizard.

• Color scheme — a dropdown that (today) offers the single "Default" preset; a reset button next to it restores the scheme's default ramps and mapping.

• Color mode — the System/Light/Dark picker described above. This is the app-wide appearance setting, separate from which palette you are editing (see Editing, next).

• Editing — a Light/Dark toggle at the top of the Styles section, independent of Color mode, that picks which of the scheme's two palettes the editors below read and write. It starts on whichever palette is on screen when the dialog opens and does not move on its own — pinning Color mode to Light or Dark also moves it (you almost always want to edit what you just chose to see), but leaving Color mode on System does not, since "System" does not name a single palette to point the editors at.

• Base ramp / Accent ramp / State ramps — each ramp renders as an interactive chart of OKLCH stops (lightness/chroma/hue) that can be dragged or numerically edited. The base ramp has 5 stops (lightest → darkest neutral), the accent ramp has 3 stops, and the state ramps each hold a single color for danger, success, warning, and info. Ramps are shared by both palettes, so a ramp edit previews live no matter which one you are editing.

• Color mapping — rows that assign a semantic token (bg, fg, cursor, selectionBg, plus every other semantic key not already owned by the Editor or Preview sub-sections) to a ramp reference: a base-ramp index, an accent-ramp index, a state role, or a literal color. Changing a ramp stop updates every token that references it. Mapping rows apply to the palette selected under Editing.

• WCAG checks — a live pass/fail table (foreground × background) built from the same contrast pair matrix (PAIR_MATRIX) used by the package's automated tests, so a ramp edit that breaks contrast is visible immediately.

There is no separate "Reset All to Scheme Defaults" button distinct from the scheme picker — because every token is a ramp reference, re-selecting the current scheme's default resets the entire structure.

Editor Markdown

A separate Editor Markdown sub-section (Settings → Styles → Editor) controls the ramp references used for Markdown auto-coloring in the editor pane (headings, bold, italic, links, blockquote, inline code):

These tokens live in the semantic block of the color map. Each row uses the same ramp-reference picker as the Colors tab's mapping section.

Editor Settings

Vim Settings

The Vim tab configures Vim-specific behavior.

Clipboard Sync

When enabled, the system clipboard is synchronized with Vim's * and + registers. Yanking text in Vim copies it to the system clipboard. When the editor regains focus, the system clipboard contents are read into the Vim register, so text copied from other applications is available for pasting in Vim.

Vimrc

The Vimrc textarea lets you define custom Vim key mappings. Supported commands:

• nmap — Normal mode key mapping

• imap — Insert mode key mapping

• set — Vim option settings

Lines starting with " are treated as comments. If the content exceeds 4096 characters, the entire vimrc is reset to empty on load — keep it concise. This textarea is the only vimrc mechanism — there is no file-based vimrc.

Keyboard Shortcuts

All keyboard shortcuts can be customized in Settings → Shortcuts. The shortcut engine supports:

• Single shortcuts — Mod+E, Mod+K, Mod+,

• Chord shortcuts — Two-key sequences like Mod+B → S (press Mod+B, release, then press S within 1.5 seconds). Enable chords with the "Chord Enabled" checkbox.

Mod maps to Cmd on macOS and Ctrl on Windows/Linux.

To set a shortcut, click the shortcut button and press the desired key combination. Press Escape to cancel or Mod+Backspace to clear the shortcut. Duplicate shortcuts are highlighted in red.

When a chord is in progress, a chord indicator appears in the UI showing the first key pressed.

Default Shortcuts

Sync Settings

The Sync tab configures sync preferences. Sync is the storage itself, not an opt-in backup of local files — workspace identity and the server connection are established during cloud-first onboarding and are not stored as preferences.

The Sync tab also provides:

• Sign In / Sign Out — Manage the Better Auth session

• Sync History — View a log of recent sync operations

See Sync for a detailed guide.

Settings Validation

Settings are validated via validateSettings() both on load and when saving from the Settings dialog. Invalid or missing values are automatically filled with defaults, and numeric fields are clamped to their allowed ranges (e.g., font size 10–24px, line height 1.0–2.0). This ensures the app always has a valid configuration even if the settings file is manually edited or corrupted.

Raw Settings (Power User)

The Raw Settings tab exposes .zudotext.settings.json directly as an editable JSON textarea. Edit the JSON and click Apply to save. The contents are pretty-printed on load with 2-space indentation. Saves go through the same backend path as the form UI, so the app's mtime-based settings cache stays in sync and other Settings tabs reflect your changes without a reload.

Validation happens in two stages:

1. Parser check — Invalid JSON blocks the save and the parser error is shown inline.

2. Sanitizer check — Parsed JSON is run through validateSettings(). If any top-level sections were coerced (for example, a font size outside the allowed range), a non-blocking warning lists the affected sections. Choose Apply anyway to save the sanitized values, or Cancel to keep editing.

Use this tab for bulk edits, scripted migrations, or recovering a manually-corrupted config. For day-to-day tweaks, the dedicated tabs are safer.

Troubleshooting color problems

If the app's colors look wrong at startup, the Settings Doctor runs automatically in the background and tries to repair the problem. If it cannot fix the issue on its own, a brief toast guides you to Settings → Styles → Reset to defaults.

See Settings Doctor for a full walkthrough, including what the Doctor detects, how to run it manually from the command palette, and how to reset the settings document from another client as a last resort.