[Seb-GRAF]

Problem

Every bundled theme looked the same: floating tiles that differed only in colors and corner radius. A theme couldn't change the bar's shape. Removing the tiles also removed the popup background, because popups took their background from the tiles. The bar always filled its frame edge to edge. And the theme cards in Customize showed only three colors, so themes that differed in shape would have looked identical there.

Changes

• popupDefaults: a style every popup inherits, between its widget's style and defaults. Themes can set it. A theme that removes the tiles by setting defaults.background to null uses it to keep a surface under popups.

• bar.margin: insets the bar's background and widgets from every edge of the bar's frame, so a rounded bar.style floats. The frame keeps its height, so the space kept clear for windows doesn't change, and the notch range shifts by the margin. Like offset, it stays in screen points under displayScale.

• Four bundled themes, each with light and dark colors:

  • Menu Bar: one full-width strip with plain widgets and a hairline, like the macOS menu bar.
  • Island: one rounded bar that floats below the top edge and in from the sides, in Catppuccin colors.
  • Minimal: no backgrounds; text with a soft shadow sits on the wallpaper.
  • Terminal: Menlo, square outlined widgets on a solid strip, in Gruvbox colors.

  Each defines the tokens it uses, so it passes review on its own.

• Customize → Appearance: each theme card loads the theme's effective configuration and draws its bar strip, a widget with its border, corners and font, at the top of a small desktop. It no longer shows just three colors.

• Customize covers every property the bundled themes set, so any of their looks can be built there. All widgets gains Shadow, Accent text and Vertical padding. A new Popups section edits popupDefaults: background, border, shadow and weight. Bar gains Background, Border, Border width, Corner radius and Margin. The Bar rows edit bar.style, the properties themes use for the strip, so they win over the theme's.

• A popupDefaults edit action, so Customize and --batch edit it like defaults.

• Fix: a widget showing only an icon was shorter than one with text, because an SF Symbol is shorter than a line of text. It stood out in Built-in and Terminal, where every widget is a tile. An icon-only label now reserves the height of a line in its font. This happens on main too; I can split it into its own PR if you'd rather.

• Schema and README: Layout and style, Themes, the display scale note, Customize, the batch actions and Custom popups.

Left out, say if you want it: widgets packages still can't set popupDefaults, only themes and your own files. Built-in, Slate, Paper and Graphite are unchanged.

Testing

• swift test: all 130 tests pass, on top of feat: keep windows clear of StableBar without a tiling window manager #48. bundledThemesDefineEverySharedTokenForLightAndDark reviews and loads each new theme, and schemaListsTheSamePropertiesAsTheDecoders covers the new keys.
• StableBar --validate passes for each new theme and for popupDefaults and bar.margin in the main file and in a profile. A misspelled popupDefaults.backgrund fails with popupDefaults.backgrund: Unknown property.
• Ran the built app on a scratch configuration and switched Island → Menu Bar → Minimal → Terminal → Built-in → Island with margin 10 through --batch. There were no configuration errors, and nothing was written to the file.
• Rendered the real views offscreen at 2x, from this branch and from main, with scratch configurations and without putting a second bar on screen (as in feat: give themes light and dark colors and organize Customize around the bar's look #31): the bar under each theme in light and dark; a popup under Menu Bar with and without popupDefaults, and under Island and Minimal; and Customize → Appearance before and after.
• Measured widget tiles with a throwaway layout probe at font size 13: icon-only widgets were 27 pt against 28 pt for text, and all are 28 pt after the fix, with unchanged widths.
• The new Customize rows have no automated test. They reuse the existing style rows and the bar and popupDefaults edit actions, and the maintainer tried them on the branch build with their own configuration.
• Not checked: a notched display, since only an external display was available, so the notch shift by bar.margin is untested on hardware. Popups weren't opened by clicking in the live app, because the session has no Accessibility permission. The popup screenshots come from the offscreen render, which uses the same style chain as WidgetPopup.

Screenshots

Screenshots to follow.

Merging

Three feat commits and one fix. A merge commit lists each one in the changelog; a squash keeps only the title.

Claude Opus 5.5 via Claude Code in T3 Code

[stablebar-releases]

🎉 This PR is included in version 0.5.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀