Manifest: Add a way to explicitly colour the standalone window's title bar

[mgiuca]

I'm filing a bug here to raise a concern as more browsers move towards PWAs on more host platforms, including Desktop. However, after extensive internal discussions at Google, I'm happy to leave this and wait and see if it's an issue before acting.

The issue is this: should user agents theme standalone windows' title bars with a) the app's theme_color (from the web app manifest), or b) the user's OS preferred title bar colour? Obviously, the answer is "this is up to the user agent, not the spec". But, consider the likely answer for each OS (according to observed platform conventions):

• Windows: Probably (b) (but there are exceptions).
• Mac: Probably (b) (but there are exceptions; seemingly more so than Windows).
• Linux: (b) (apps cannot modify window title bars, unless they fully take over the window, and this behaviour interferes or plays poorly with the vast collection of different window managers including TWMs with no title bars at all).
• Android: (a) (no strong OS theme colour; top-bar is app branded).
• Chrome OS: (a) (no strong OS theme colour; top-bar is app branded).
• As future platforms come along, they may have either convention.

So the likely answer is that the user agent makes the decision, per-OS, as to whether to go with (a) or (b).

However, consider that many developers will want to override the choice of (b) wherever possible, and force their theme colour into the title bar. We see this with a lot of Electron apps on Windows and Mac (e.g., Spotify, Discord, WhatsApp). If the user agent chooses (b), those apps won't be happy. So, in order to satisfy those customers that want a "fancy" experience, the user agent is incentivized to choose (a) on all platforms. (This is the current direction we're heading with Chrome.)

So now we're in a place where user agents typically choose (a) on all platforms, but where does that leave developers who want the "normal" experience of (b) on Windows, Mac, Linux? They have two options:

1. Delete their theme_color, thus using the system default, or
2. Server-side user agent detection, and serve a different manifest on each platform.

Option 1 is bad because we want apps to have a theme_color; it's used for more than just the title bar (e.g., the splash screen background) and not having one makes them look "boring" on (a)-type platforms like Android and Chrome OS --- note that there is no user preference for title bar colour on these platforms, it's just grey. Option 2 is much worse, because then developers are forced to consider each platform, and won't be future-proofing their sites.

This leads me to the conclusion that we should give developers a way of making one of two different statements:

• "this is my theme colour; please use it wherever appropriate based on the host system conventions" (i.e., (a) on Android and Chrome OS, (b) on Windows, Mac and Linux).
• "please use this colour in the title bar wherever possible" (i.e., (a) everywhere possible; perhaps even draw a custom title bar on Linux instead of deferring to the system).

There is currently no way for developers to specify which of the above two statements they want to make. The proposal to allow this would be to introduce a new hex-colour member, title_bar_color, which expresses an explicit desire to theme the standalone window's title bar, as opposed to specifying a generic theme colour.

Thus, the following manifest:

{
  "theme_color": "#a5a"
}

Provides a general statement about theme colour, but has no strong opinion about the title bar, whereas:

{
  "theme_color": "#a5a",
  "title_bar_color": "#a5a"
}

Explicitly asks the title bar to be branded with the app's theme colour.

A few notes:

• On (a)-type platforms (which naturally theme the title bar), the UA would take the title_bar_color, with a fallback to theme_color.
• This also allows an app to show a different colour in the title bar than its generic theme colour. Which could be useful for having different shades of the same hue, for example.
• This wouldn't actually enshrine the concept of "title bar" into the web (of course, many platforms won't have a "title bar" as such). It would be specified as a hint to the user agent to use title_bar_color prominently in the border of the stand-alone window. The name is just suggestive of its most common meaning. Perhaps border_color is a better name.

Anyway, Chrome is going to proceed without this, choosing (a) on all platforms. The above proposal isn't strictly necessary, but we'll see if there is demand from developers.

@boyofgreen who may be interested in this (since Edge PWAs are currently taking the (b) approach on Windows 10).

[kenchris]

window_decoration_color maybe. It is a bit long, but quite descriptive

[kirupa]

Having a separate value for window color makes sense. On Windows, the (a) approach is where we would like to go as well, and it is fully supported in the platform today. We just haven’t done the wiring between the manifest theme value and window color in our templates and PWABuilder. That is something we will address soon.

Regarding the name, all of the suggestions sound good. I lean towards title_bar_color since it is clear what it modifies. I understand that not all user agents will have a title bar, but it does make it clear to the developer on what will get modified.

[mgiuca]

@kirupa can I clarify with you: is Windows moving towards a space where there is an expectation that all apps theme their own title bar (essentially deprecating the concept of a user-preference theme colour)? Or merely moving towards "fancy apps" being able to theme their title bar?

Linux is tricky because user agents can't override the default title bar, they can only create a fully custom title. However, on Chrome, we're going to need to create a custom title bar anyway in order to add our custom UI, so Linux will actually be a type-(a) as well, at least on Chrome.

Even on macOS, I was surprised to learn that a number of high-profile native apps, like Photoshop and Office, as well as Electron apps Spotify, Discord and WhatsApp, apply their own theming to the window. If the world is universally moving towards a model where apps theme their own window with their theme colour, then perhaps we don't need a separate switch for this (user agents can just always use the theme_color in the title bar).

On the other hand, if the "default" app experience on Windows, macOS and especially Linux, is non-branded theme colour, then I think it makes sense to add this new member to allow "fancy" apps to override that default.

On naming: I think there is precedent for calling things what they "commonly mean" as opposed to what the formal specification says they mean. For example, we don't use the word "browser" in standards, because formally a user agent can be something other than a web browser, but we still have "display: browser" which is the common name. "title_bar_color" is an appropriate name even though we wouldn't literally say "the title bar" in the standard.

[kirupa]

@mgiuca, there will need to be room for both. In the Windows world, apps that don't specify a preference will display using the user-preference theme. Only apps that want a custom titlebar (like PWAs with the appropriate entry set in the manifest, for example) will get them. This functionality is part of our public API surface that a lot of apps use already, so we would be continuing this tradition.

[bschoepke]

@mgiuca Windows 10 supports extensive title bar customization for UWP apps, so it makes sense for PWA's to have the same capabilities:
https://docs.microsoft.com/en-us/windows/uwp/design/shell/title-bar

This extends to the upcoming Sets feature (pre-release docs):
https://docs.microsoft.com/en-us/windows/uwp/design/shell/design-for-sets

[mgiuca]

Thanks, those docs are helpful.

I think at this time, web apps won't be able to take the "full customization" route (too much unknown here, especially for security where in Chrome at least, we show an origin in the title bar area and we don't want sites to be able to spoof that). Perhaps UWP PWAs will be able to directly use the windows APIs to control full customization.

For now, I think it's sufficient to get title bar color customization.

[kenchris]

I noticed that on Chrome OS, the title bar, actually doesn't contain the "title" for desktop PWAs, meaning that maybe we should use a different word than "title bar"

[mgiuca]

We still internally call it the "title bar" (which I think emphasizes how silly it is that we don't show a title!) I think it's fine to call it that in the spec. Again, it doesn't have to cover all the systems, it's just a name to give people a well-understood idea of what it will be used for.

[christianliebel]

The current practice seems to be applying the theme_color from the manifest to the window’s title bar. With meta[name=theme-color] it would also be possible to change the color if developers want to (https://github.com/w3c/manifest/issues/779).

@mgiuca Is this still needed?

[mgiuca]

Yeah, it's still something I "want" (not sure if "needed", we haven't had explicit developer demand for it).

The idea is that you may want an app with a theme colour, but _not_ a title-bar colour on platforms like Windows, Linux and macOS where windows are not expected to have a title-bar colour. Thus, the app still has its preferred theming in store pages, icons, etc, but windows look "standard" on each platform.

What we have now (at least in the Chrome implementation) is that we forcibly set the window title bar on Win/Lin/macOS to your theme colour, which is actually unusual on those platforms (where I expect the title bar colour to match the system default). Developers have two choices: a) do not set a theme_color, thus getting the correct title bar colour on Win/Lin/macOS, but losing the theming elsewhere, or b) set a theme colour and have an overly-colourful app on Win/Lin/macOS.

The proposed explicit title_bar_color lets you customize the title bar colour independent of the theme colour.

[alancutter]

The manifest "theme_color" field would be incomplete without the <meta name="theme-color"> tag to compliment it with dynamic per-window values. If "title_bar_color" becomes a supported field then a <meta name="title-bar-color"> probably should too.