Themes
Choose a built-in Zync color theme, import and export theme JSON, or review the separate plugin theme contract.
Color themes change the Zync app shell and terminal presentation. Choose one from the command palette or Settings > Appearance. File icons are a separate system. Choose an icon theme from Settings > Plugins > Installed > Select Icon Set.
Built-in themes
Section titled “Built-in themes”Zync 2.39.0 ships with 13 built-in color themes:
- Light
- Gruvbox Light
- Solarized Light
- Catppuccin Latte
- Tokyo Light
- Dark
- Dracula
- Oxide
- Monokai
- Midnight
- Monokai Pro
- Synthwave
- Nordic
System Default is an additional selector that follows the operating system’s light or dark preference. It is not a color theme package, so it is not included in the count above.
Oxide combines bright green text, mustard gold secondary text and soft red accents on a dark background. Michael Hart (@ThrownWolfCon) contributed it in PR #148.
Choose a theme
Section titled “Choose a theme”- Open Settings > Appearance.
- Open the color-theme picker.
- Choose a theme from the light or dark group.
- Optionally set a custom accent color.
You can also open the command palette with Mod+P and run Preferences: Color Theme. In Zync 2.39.0, selecting a theme replaces the previous theme’s global element-color overrides and clears an explicit custom accent. Set the accent or individual element colors again if you want to override the new theme. The saved imported theme remains available in Theme files; select it there to restore its own palette and element overrides.
Theme files
Section titled “Theme files”Open Settings > Appearance and scroll to Theme files:
- Choose Export theme JSON to save the current palette and saved global element-color overrides. Use that file as the starting point for your own colors.
- Edit the JSON in a text editor. Keep the required palette keys:
background,panel,surface,border,text,mutedandaccent. - Choose View theme keys for supported element names and a copyable
elementsexample. Add only the colors you want to change insideelements.overrides; omitted keys inherit the theme’s colors. The example is an elements block, not a complete theme file. - Choose Import theme JSON and select your file. Zync validates it before showing Preview imported theme, with palette and element samples and any contrast notices.
- Choose Apply theme to save and use it, or Cancel to leave your current colors unchanged. A low-contrast notice lets you review readability before deciding whether to apply.
Applying an import replaces the app palette and global element-color overrides. Host-specific themes, independently styled tabs, fonts, transparency, layout and connections stay unchanged. Built-in themes are not edited. Zync retains one imported theme; applying another import replaces that saved custom document. Export it first if you want to keep several alternatives as files.
Supported file contents
Section titled “Supported file contents”The file is a JSON document with format: "zync-theme", version: 1, a name, a light or dark mode, the complete palette, and an elements object containing version: 1 and overrides. Files must be 64 KiB or smaller. Colors use opaque six-digit hex values such as #334455.
Unknown keys, extra fields and unsupported versions are rejected. Fonts, sizes, transparency, images, gradients, CSS, URLs and executable plugin code are outside the version 1 format. Exporting includes saved overrides, not unsaved edits or every inherited color.
Plugin theme boundary
Section titled “Plugin theme boundary”Theme JSON is the user-facing way to share app colors. The current runtime injects host-global CSS only for trusted app-owned built-in themes. Installing a community plugin does not grant its stylesheet access to the complete Zync document; pane and editor styles stay inside their own frames. The legacy manifest and CSS sections below are a developer reference, not an alternative JSON import format or a promise of signed-marketplace support.
Legacy theme package manifest
Section titled “Legacy theme package manifest”The legacy asset format uses a manifest and stylesheet at the package root. This is a format reference for local testing and built-ins, not a complete Manifest v2 marketplace submission:
{ "id": "com.example.theme.my-theme", "name": "My Theme", "version": "1.0.0", "description": "A high-contrast dark theme.", "author": "Example", "style": "theme.css", "mode": "dark", "preview_bg": "#10131a", "preview_accent": "#7c9cff"}Required identity fields are id, name, and version. Use a globally unique reverse-domain ID. style points to the CSS file. Set mode to light or dark so the theme is grouped correctly. preview_bg and preview_accent provide marketplace and picker preview colors.
Theme CSS
Section titled “Theme CSS”Built-in themes define semantic app variables under a theme selector. A minimal theme stylesheet looks like this:
[data-theme='my-theme'] { --color-app-bg: #10131a; --color-app-panel: #171c25; --color-app-surface: #202938; --color-app-border: #344158; --color-app-text: #e6edf7; --color-app-muted: #9eabc0; --color-app-accent: #7c9cff;}Keep the variables semantic rather than styling individual component classes. Check text, muted text, borders, focus states, dialogs, and terminal output in both a normal and busy workspace.
| Variable | Role |
|---|---|
--color-app-bg |
Main workspace background |
--color-app-panel |
Sidebar, dialogs, and raised panels |
--color-app-surface |
Controls and nested surfaces |
--color-app-border |
Dividers and component outlines |
--color-app-text |
Primary readable text |
--color-app-muted |
Secondary text and inactive controls |
--color-app-accent |
Focus, selection, actions, and active states |
The terminal maps its foreground, background, cursor, and ANSI colors from the active application theme and accent. Test commands with red, green, yellow, blue, magenta, cyan, and white output. A readable app preview does not guarantee readable terminal ANSI colors.
Security and runtime limits
Section titled “Security and runtime limits”Filesystem plugins are not allowed to inject arbitrary stylesheet text into the host document. The runtime injects host-global theme CSS only for trusted app-owned built-ins. Third-party theme styles remain sandboxed, and editor-provider styles remain inside their editor iframe.
This means a community theme package can be installed and discovered by the plugin system, but it must not assume that its stylesheet can rewrite the entire Zync document. Follow the current runtime behavior described in Plugins and extensions and verify the package on the target Zync release.
Light and dark design guidance
Section titled “Light and dark design guidance”- Use high contrast between
--color-app-textand--color-app-bg. - Make
--color-app-mutedreadable on both the background and surface. - Keep borders visible without making every panel visually heavy.
- Ensure
--color-app-accentworks for buttons, links, selection, and focus rings. - Give the terminal cursor enough contrast against both its background and foreground.
- Test dialogs, notification toasts, file lists, and the Settings modal before publishing.
Package and publish
Section titled “Package and publish”Package the manifest and stylesheet with manifest.json at the archive root:
zip -r my-theme.zip manifest.json theme.cssUse a legacy theme archive only for compatible local Developer Mode testing. Do not submit this unsigned format to the current signed marketplace or assume it can restyle the host. Coordinate asset-only support with maintainers first. For supported Manifest v2 plugins, follow Sign and publish a plugin.
Icon themes are separate
Section titled “Icon themes are separate”Color themes do not change file icons. Under Settings > Plugins > Installed, choose Select Icon Set. Available choices come from enabled icon-theme plugins, including these bundled packs:
- VSCode Icons (Default)
- Lucide Minimalist
- Material Icon Theme (Bundled), with offline file and folder artwork
Installing or enabling a pack makes it available in the picker; it does not require changing your existing selection. Disabling a selected pack lets Zync fall back to its built-in artwork. Material icons need no network download during browsing.
New community packs use a data-only Manifest v2 iconTheme contribution with Plugin API 2.2 or later. Legacy iconsPath packages are a separate compatibility format, not the contract for new declarative packs. See the icon theme contract for mappings, validation and publishing requirements.