Modern UI Elements

A matching set of compact graphite UI elements for Zen Browser. Soft corners, subtle borders and readable controls, in one installable CSS file.

Download CSS · Installation · Options · Compatibility · Report an issue

Components

Component	Appearance	Default
Fullscreen notification	Compact surface, native domain and exit button	On
Background-tab notification	Quiet notification with the native switch-to-tab button	On
Action confirmations	Matching copy-link, rename, pinned-tab and workspace-routing confirmations	Off
Link status	Small rounded address label when hovering over a link	Off
Pointer-lock notification	Matching surface with native domain and exit instructions	Off
Downloads panel	Graphite surface, rounded rows and refined action buttons	Off
Findbar	Appearance-only styling for stock Zen and Better Find Bar	Off

New components are opt-in. The two original notifications keep their existing appearance and preference names. Native actions, localization and lifecycle remain in the browser; the mod installs no JavaScript.

Settings dialog

The Zen Mod includes 11 checkboxes in the browser's native configuration dialog: seven component flags and four size/transparency options. In a registry installation, open Settings → Zen Mods → Modern UI Elements → Configure (the gear button). Checkbox changes are saved by Zen and update the browser UI.

The dialog is generated from preferences.json; no custom extension or settings script is required. The registry package and dialog have been tested through Zen's actual mod manager. Public submission is currently blocked because the official theme-store repository is archived. A manual userChrome.css installation does not create a Zen Mods entry; use the preference table below for that installation method.

Installation

No other mod is required. Install manually with userChrome.css; this project is not yet listed in the Zen Mods registry.

As of 2026-09-10, GitHub rejects new submissions to the archived official theme store. See submission status. There is no registry install link yet.

1. Open about:support in Zen and open its Profile Folder.

2. In about:config, set toolkit.legacyUserProfileCustomizations.stylesheets to true.

3. Create the profile's chrome directory if needed. Download chrome.css and save it there as modern-ui-elements.css.

4. Add the following at the beginning of chrome/userChrome.css, before any style rules. Keep existing imports and customizations.

   @import url("modern-ui-elements.css");

5. Enable the additional components you want using the Boolean options below.

6. Fully quit and reopen Zen.

To update, replace modern-ui-elements.css with the latest version and restart Zen. For local development, the import can point to the absolute file:/// URL of the checkout's chrome.css instead of a copy.

Upgrading from Modern Fullscreen Toast

Replace the old import with the one above. Load only one copy of the stylesheet. Existing mod.modern-fullscreen-toast.* and mod.modern-tab-toast.* preferences continue to work.

Options

For a native Zen Mod installation, use the configuration dialog. For a manual installation, create the following Boolean preferences in about:config. Missing fullscreen/background-tab flags preserve their original enabled behavior; all other missing flags behave like false.

Preference	Default	When enabled
mod.modern-ui-elements.fullscreen-toast	true	Style fullscreen notifications
mod.modern-ui-elements.background-tab-toast	true	Style background-tab notifications
mod.modern-ui-elements.action-toasts	false	Style action confirmations
mod.modern-ui-elements.link-status	false	Style the link address label
mod.modern-ui-elements.pointer-lock	false	Style pointer-lock notifications
mod.modern-ui-elements.downloads	false	Style the downloads panel
mod.modern-ui-elements.findbar	false	Style the existing findbar
mod.modern-fullscreen-toast.roomy	false	Fullscreen: larger text and padding
mod.modern-fullscreen-toast.opaque	false	Fullscreen: solid background without blur
mod.modern-tab-toast.roomy	false	Background tab: larger text and padding
mod.modern-tab-toast.opaque	false	Background tab: solid background without blur

The same options are defined in preferences.json for the native settings dialog.

Compatibility

Stock Zen

All components work without Better Find Bar or any other theme. The findbar keeps its native layout. The mod styles existing controls rather than enabling browser features:

• The background-tab notification normally appears with the sidebar hidden in Compact Mode.
• Pointer-lock notifications require a site to request pointer capture.

Zen with other mods

The findbar layer changes colors, borders, radii and control states. It does not set its width, height, position, padding, transforms, display, visibility or transitions. Better Find Bar continues to control its placement, layout and animations. Search results, disabled controls and the not-found state remain native.

Better Find Bar was tested on either side of our import, including its top-left placement. The currently installed CSS bundle containing Better Find Bar, Animations Plus, Extensions List, Zen Context Menu and other mods was also used in compatibility checks. These are checks of those stylesheets, not a guarantee for every future release or combination of custom preferences.

Each optional component is scoped to its own UI. Extension menus, context menus, the URL bar and browser tabs are not globally restyled. If another mod styles the same component, disable the corresponding option here to let that mod own it.

Accessibility and behavior

• Keyboard focus remains visible; error and disabled states stay distinguishable.
• Reduced-motion mode keeps the native cleanup events and animation promises.
• Reduced-transparency mode uses solid notification surfaces.
• Forced colors use system colors or fall back to the native component styling.
• Blur is compositor-dependent; surfaces remain readable without it.
• Download progress and warning states retain their native behavior.
• Action confirmations use an explicit localization-ID allowlist. Invalid pinned URLs and split-view-limit warnings are not included.

Before and after

Comparisons use the same build, synthetic page, viewport and scale within each pair. The notification examples use a red workspace accent. Click an image to view it at its original size.

Fullscreen notification

Without mod

With mod

Background-tab notification

Without mod	With mod

Action confirmation

Without mod	With mod

Link status

Without mod	With mod

Pointer-lock notification

Without mod

With mod

Stock findbar

Without mod

With mod

Better Find Bar

Better Find Bar is enabled in both images. Only our appearance layer changes.

Without our mod

With our mod

The downloads panel is a native popup window. Its behavioral and style checks run in Zen, but native-window screenshot capture was unavailable on the test machine. Its comparison is pending; browser screenshots that omit that window are intentionally not presented as previews.

Verification

Development baseline: Zen 1.22b / Gecko 155.0.1 on macOS, checked on 2026-09-10. Other platforms have not been runtime-tested.

The repository contains a Python-standard-library runner, browser-side scenarios and local HTTP fixtures. These are development tools and are not loaded by the mod.

python3 tools/check.py --browser /path/to/zen --all
python3 tools/check.py --browser /path/to/zen --all --all-features
python3 tools/check.py --browser /path/to/zen --all --install-mode zen-mod

Check Better Find Bar, including the reverse stylesheet order:

python3 tools/check.py --browser /path/to/zen \
  --scenario downloads-and-findbar --compat-css /path/to/better-find-bar/chrome.css
python3 tools/check.py --browser /path/to/zen \
  --scenario downloads-and-findbar --compat-css /path/to/better-find-bar/chrome.css \
  --compat-order after

--compat-css can be repeated or point to the generated zen-themes.css bundle. The runner copies no user profile, history, cookies or accounts. Downloads stay in a temporary test directory, and clipboard operations use a test adapter.

Capture before/after images into the ignored output directory:

python3 tools/check.py --browser /path/to/zen --all --screenshots

Use --headed for a visible disposable browser. On macOS, native popup captures use the OS window-capture command and are explicitly skipped if unavailable. Normal browser captures and cropping are performed by Zen itself. Images and logs default to .test-output/; --output selects another directory.

Scenarios cover:

• Real fullscreen and pointer capture, exit actions, hiding and reappearance.
• Background-tab switching, reuse, hover-to-hold and timer cleanup.
• Action-confirmation allowlist, copy commands with a clipboard adapter and actual link hover.
• Real downloads, cancel, retry and controlled HTTP failure.
• Search counts, next/previous, not-found styling, options and Esc.
• Component toggles and findbar geometry with and without compatibility styles.
• Native mod loading, preference defaults, all 11 configuration-dialog checkboxes, live updates and disabling/re-enabling the entire mod.

System share-sheet appearance and video-compositor blur still need manual visual checks. Do not interpret style checks as coverage of every OS accessibility setting.

Removal

Remove the import from chrome/userChrome.css and restart Zen. If installed by copying, remove chrome/modern-ui-elements.css. Reset any custom preferences you created. If you enabled preferences through a profile user.js, remove those lines there as well before resetting them in about:config.

Contributing

Include the Zen version, OS, enabled options, other UI mods and reproduction steps in bug reports. Keep styles scoped to the relevant component. Run the relevant scenario and update its before/after comparison when changing appearance.

The implementation plan and progress notes live in vibe/.

Zen Mods submission

The submission package uses the concise registry README in store/description.md and the 600×400 preview in image.png.

python3 tools/package_mod.py --check
python3 tools/package_mod.py

This builds a ZIP, an issue-body draft and a checksum in dist/. See SUBMITTING.md for the official form, required licensing consent and submission steps. The registry assigns the real mod ID after submission.

License

Copyright 2026 Dmitrii Bragin. MIT License.