Appearance and themes

Wrengle themes change the workspace through semantic colors such as background, surface, text, accent, status, border, and focus. Choose a ready-made theme or save several named custom themes for different environments.

Open Settings → Appearance to manage themes.

Choose the app mode

The app mode and the selected themes are separate controls:

• Light always uses the theme assigned to the Light slot.
• Dark always uses the theme assigned to the Dark slot.
• System follows the operating-system appearance and switches between those two assignments as the operating-system setting changes.

Use the Light theme and Dark theme tabs to configure each slot independently. For example, System can use Paper & Ink during the day and Midnight Blue at night. Editing one slot does not replace the other.

Built-in themes

Built-in themes are ready to use and cannot be overwritten. To make one your own, choose Create theme, then select it as the starting palette.

Theme cards show representative background, surface, text, accent, and status colors. Select a card to inspect it in the preview. Choose Apply to assign it to the active Light or Dark slot. Cancel leaves the current assignment unchanged.

Where themes apply

The active palette follows you across Wrengle's first-party surfaces, including the note canvas and editor chrome, dialogs, workflows, graphs, charts, and the terminal. App-owned canvas defaults, controls, menus, focus states, and native form controls update with the resolved Light or Dark theme.

The terminal's app-owned background, text, muted text, borders, hover states, cursor, and selection are derived from that same semantic palette. Explicit terminal values set through Advanced colors take precedence for a custom theme. ANSI prompt and command-output colors remain shell-owned so changing the app theme does not rewrite a user's shell color configuration.

Themes change app-owned presentation, not the meaning of saved content. Explicit document colors and non-Neutral chart swatches are preserved, as are embedded images, audio, video, and other media. The chart Neutral swatch is the intentional exception: it opts a shape or connector back into theme-relative app defaults, so those channels follow the active palette. Choosing another named chart swatch keeps its authored colors when the app theme changes.

The chart format stores channel colors, but not whether a value came from a swatch or the Custom field. A Custom channel equal to one of Wrengle's default shape, frame, text, or connector colors is therefore also theme-relative by value. Choose a different hex value when that channel must remain fixed across themes. Charts saved with the earlier Contrast swatch remain fixed.

Create a custom theme

Choose Create theme, select whether it is a Light or Dark theme, give it a name, and choose a built-in starting point. Theme names are trimmed, may contain 1–40 characters, and must be unique within that mode without regard to letter case.

The guided editor starts with the colors that make the largest visual difference:

• Background
• Surface
• Text
• Muted text
• Accent
• Accent text

The preview updates while you work without recoloring the rest of the app. Choose Save to add the theme to Your themes, or Cancel to discard the draft. Saving a theme does not silently change the other appearance slot.

Open Advanced colors to search and edit the complete registered token set, including status, recording, sidebar, chart chrome, border, input, and focus roles. Custom themes store only their differences from the selected built-in starting point, so a small edit stays understandable.

From Your themes, you can apply, duplicate, rename, or delete a theme. The library-level Export control copies all custom themes together. Deleting an assigned theme requires confirmation. Wrengle falls back to that theme's built-in starting point and offers an immediate Undo action.

Contrast and color checks

Wrengle checks color syntax and the important foreground/background pairs before saving:

• Normal text on the background, text on surfaces, and text on the accent must reach 4.5:1.
• Muted text is checked against the same 4.5:1 target.
• The focus indicator is checked against a 3:1 target.

An invalid color, low-contrast normal text, or low-contrast accent text blocks saving and identifies the field to fix. Lower-priority muted-text or focus warnings show the affected pair and require the explicit Save anyway acknowledgement. That acknowledgement can be useful for a personal theme, but it does not make the low-contrast choice accessible to other users. Start with a High Contrast preset when stronger separation is the priority.

Import and export

Export creates versioned JSON containing appearance mode, Light and Dark assignments, custom theme names, starting presets, and color overrides. It does not contain notes, transcripts, vault paths, account details, credentials, or plugin state. Internal revision and theme activity timestamps are reset in the portable export rather than copied to the clipboard.

Import accepts a Wrengle theme JSON document only after it passes the same schema, registered-token, name, and safe color-literal checks used by the editor. Import is limited to 256 KiB per document and 100 custom themes. Oversized, malformed, unsupported, or executable content is refused; JSON is treated as data and is never run as code.

Import is a safe merge: it adds remapped copies of the custom themes and does not change the current app mode or either live assignment. Review an imported theme in the scoped preview, then choose Apply yourself. Exports from the earlier per-mode color editor (mode plus overrides) are also accepted and converted into named Light and Dark themes. If an imported or legacy theme has low required-text contrast, Apply remains disabled until you explicitly acknowledge Apply anyway beside the preview.

Keep an export if you want to transfer a library to another Wrengle installation. Theme settings are app-local and are not stored in the note vault, so vault sync alone does not move them between devices.

Storage, privacy, and upgrades

The canonical theme library is stored in Wrengle's local application settings. A small materialized Light/Dark cache is also kept locally so the correct colors can be painted during startup before the settings screen loads. Theme selection, editing, import, and export make no theme-specific network request.

When upgrading from the earlier theme editor, Wrengle preserves the selected Light, Dark, or System mode and migrates existing per-mode token overrides into named custom themes. Safe legacy CSS color literals such as short hex, named colors, and rgb(...) remain valid. Light and Dark overrides stay independent. This release also performs a one-time move from the earlier built-in preset versions to theme-aware versions for saved assignments and custom-theme starting points. That move makes previously fixed terminal chrome follow the selected palette while retaining authored semantic and explicit terminal overrides. Historical built-in versions remain resolvable for compatibility; future versions are not applied implicitly.

If local theme settings cannot be read, Wrengle keeps persistence blocked so an unread saved library is not overwritten. Appearance shows a retry notice; session changes remain temporary until storage succeeds. A native close request or app restart first waits for startup theme loading and every queued canonical theme write. That wait is bounded: if the local settings bridge stalls or still fails after a retry, Wrengle returns control, keeps the window open, clears any Settings search, opens Appearance, and asks you to retry instead of silently discarding the change. The close notice also offers an explicit Discard & close action when you intentionally want to leave without saving the session-only theme change.

While a custom-theme form contains changes, Wrengle keeps the designer mounted. Closing Settings with the close button, Escape, or the backdrop; switching Settings category, search, app mode, or Light/Dark theme tab; and automatic restart are held until you choose Save theme or Cancel. Native app close returns you to the same intact designer and offers Discard & close only as an explicit recovery action. If an app update has already installed, its banner keeps a Restart now action available; using it after Save or Cancel retries only the safe restart and does not download or install the update again.

Plugin theme delivery remains compatible. A plugin view continues to receive { theme, themeTokens }, where theme is the resolved light or dark value and themeTokens is the materialized palette. Plugin-authored CSS must consume that payload to follow the active palette; Wrengle does not rewrite a plugin's own styles. Custom theme names, the theme library, and the inactive appearance slot are not added to the plugin bridge.