Draft spec for theming, Mica #12530
Draft spec for theming, Mica #12530
Conversation
…icrosoft/terminal into dev/migrie/s/3327-xaml-theming
…icrosoft/terminal into dev/migrie/s/3327-xaml-theming # Conflicts: # .github/actions/spelling/allow/allow.txt # .github/actions/spelling/allow/apis.txt # .github/actions/spelling/allow/microsoft.txt # .github/actions/spelling/allow/names.txt # .github/actions/spelling/excludes.txt # .github/actions/spelling/expect/expect.txt # .github/actions/spelling/expect/web.txt # .github/actions/spelling/patterns/patterns.txt
This comment was marked as resolved.
This comment was marked as resolved.
zadjii-msft
added
the
Needs-Discussion
zadjii-msft
force-pushed
the
dev/migrie/s/3327-xaml-theming
branch
from
bfd8f73
to
a79edc5
Compare
This comment was marked as resolved.
This comment was marked as resolved.
|
Is there any chance of getting improved platform support for some of these limitations of Mica? I didn't see that called out anywhere. You say that we should make it ergonomic for our users to choose things here, but the platform is definitely making this hard. |
I'm under the impression that's by design. The way the platform seems to be designed prevents Mica from being used in other places where it's not really part of the design language. Like, perhaps adressing the fact that apps would just use acrylic wherever they wanted, multiple times in the same app, against the official guidance, which played into the performance concerns with acrylic. </baseless conjecture> Part of marking this as a draft is to get this out into the world as our baseline expectations of Mica in the Terminal, to help communicate our goals with the rest of the platform team 😉 |
zadjii-msft
added
Area-Theming
This comment was marked as outdated.
This comment was marked as outdated.
| elements. This didn't seem terribly hard at face value, considering [the Mica | ||
| recipe] is basically open-source. However, it seems to rely on some | ||
| closed-source `IGraphicsEffect`s from the `Composition.Effects` namespace. | ||
| Apparently, those effects are only [implemented in Win2D]. It's unclear at |
There was a problem hiding this comment.
These effects are implemented in Direct2D, and Win2D is just a thin wrapper over Direct2D. It's possible to write your own classes for these Direct2D effects to be able to use them without needing to import the whole of Win2D. This is actually what WinUI does to use these effects without making it depend on Win2D.
There was a problem hiding this comment.
I mean yea, we probably could do that. For ex:
https://github.com/microsoft/Win2D/blob/da3fa1e6caab9df443c43d0f7a211d9d159539f8/winrt/lib/effects/generated/ColorSourceEffect.cpp
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as resolved.
This comment was marked as resolved.
|
Note to reviewers: Probably read through at least "Highest priority theming properties", and then the sections titled "Theme Colors", "Titlebar complications" and "Light & dark mode theming". That's probably enough to get the gist here. |
There was a problem hiding this comment.
The only critique I have is:
I would strongly prefer #rrggbbaa (and rgba(r, g, b, a)) over #aarrggbb. The first two are in line with the CSS Color Module Level 4 draft and supported by all major browsers. I have a parser for rgba(r, g, b, a) at hand as well which I can share with you. 🙂
Some unimportant thoughts:
- Should themes get UUIDs?
- When the spec says
window.background.useMica, the first dot denotes a sub-object while the second dot is meant literally - I think this is a bit confusing at times and it makes me wonder whether we should make something likewindow.backgrounda sub-object as well. - Extendability always makes me a bit afraid that we're biting off more than we can chew / that we'll have a hard time keeping all features not just there but also stable and bug free with the current team size we have. This of course doesn't apply much to theming properties which can be 1:1 propagated to WinUI properties, but... Well you know what I mean...
There was a problem hiding this comment.
Looks good to me. A few responses to Leonard's comments:
Should themes get UUIDs?
I vote no, but mainly because I don't see the value in UUIDs? Today, the main value I see for profiles is that it allows you to have two profiles with the same name. Theme names don't really matter, as they're just user-friendly identifiers.
When the spec says window.background.useMica, the first dot denotes a sub-object while the second dot is meant literally - I think this is a bit confusing at times and it makes me wonder whether we should make something like window.background a sub-object as well.
Long-term, that's probably the right move. But I feel like it'll be a bit annoying at the beginning of themes since we won't have many settings. I think we should keep it as-is, and introduce sub-objects as necessary. That's how we handled profile.font and I think it worked out fine.
Extendability always makes me a bit afraid that we're biting off more than we can chew / that we'll have a hard time keeping all features not just there but also stable and bug free with the current team size we have. This of course doesn't apply much to theming properties which can be 1:1 propagated to WinUI properties, but... Well you know what I mean...
Yeah, we've got a while to go before taking on extensibility haha
| "background.useMica": true, // Use mica behind the window | ||
| }, | ||
| "tabRow":{ | ||
| "background": "#00000000", // Make the TabView Transparent |
There was a problem hiding this comment.
(double checking) if the background color is "red", but the color is fully transparent, this means that we'll have a red tint to the mica right?
| **TODO!**: We should make sure to have a Future Considerations section on how | ||
| we'd implement per-element Mica, should that option be available to us in the | ||
| future. |
| This is not a particularly ergonomic design. From a UX perspective, the user | ||
| needs to enable one setting in the UI to enable Mica, and then go to profile | ||
| settings to set the profile to _transparent_ for each of the profiles they want | ||
| with Mica. That's not very intuitive by any means. |
There was a problem hiding this comment.
This is a good problem to identify. We could probably be smart about it in the SUI. Do something like...
- In Themes page...
- "enable mica" "warning: this replaces the acrylic material with mica"
- when the user enables it, have a pop-up or a button that lets you directly adjust the transparency (or even just set transparency) for profiles
I definitely think we should have a design doc to tackle this before we start implementing the SUI for themes.
| would apply on top of the Mica layer. Either warnings would need to be | ||
| displayed, or one setting would have to disable the other. At the very least, | ||
| the documentation needs to be very clear about this. |
There was a problem hiding this comment.
(again, something very relevant for a design doc)
in the SUI, if mica is set and "acrylic in unfocused window" was set, display the warning saying "This will disable X. Continue?"
#####⚠️ targeting 1.15 ## Summary of the Pull Request Adds support for Themes, a new type of customization for the Terminal. Themes allow the user to customize elements of the Terminal window itself. In this first iteration, this PR adds support for two main properties: * enabling Mica as the window backdrop * changing the tab row color (read: changing the titelbar color) These represent the most important asks of theming in the Terminal. The properties added in this PR are: * Theme color variants: - `"#rrggbb"` or `"#aarrggbb"` - `"accent"` - `"terminalBackground"` * Properties (_listed here in dot notation, but implemented as sub-objects_) - `tabRow.background`: accepts a ThemeColor (above) - `window.applicationTheme`: accepts one of `{"system", "light", "dark"}` - `window.useMica`: accepts a boolean, defaults to false. ## References * As first described in #3327 * spec'd in #12530 ## PR Checklist * [x] Sorta enables #10509, but doesn't close it. That'll need more comprehensive changes to the titlebar code. * **update**: I totally disabled mica, but left the serialization code. It just seems silly without #10509. * [x] Closes #1963 * [x] Closes #3774 * [x] Closes #12939 * [x] Does the bulk of the #3327 work, but I'm going to leave that open since that's become my megathread for everything related to theming. * [x] I work here * [x] Tests added/passed * [ ] Requires documentation to be updated - **SURE DOES** ## Detailed Description of the Pull Request / Additional comments ### --> GO READ #12530 <-- Seriously. These themes aren't customizable in the SUI currently. You can change the active theme, and the UI will show all of the defined themes, but they're not editable there. They don't layer. You'll need to define your own themes. Thay can't come from fragments. This is a really cool future idea, but not implemented in this v0. The sub objects have some gnarly macros to generate a lot of the serialization code for you. ### TODOs * [x] I still have yet to establish what the accent color algorithm is. This might be proprietary and require a ThemeHelpers workaround. * [x] Make sure `terminalBackground` & the SUI result in something sensible * [x] Make sure runtime BG changes work with `terminalBackground`. One time, they didn't. `printf "\x1b]11;rgb:ff/00/ff\x07"` * [x] Acrylic Terminal BG's look weird, like, the opacity is always 50% or something. And the tab row looks all wrong then. ## Validation Steps Performed This is the blob I've been testing with: <details> ```jsonc // "useAcrylicInTabRow": true, "theme": "my dark", // "theme": "Edge", "theme": "orangey", "theme": "WHITE", // "theme": "terminal", "themes": [ { "name": "my dark", "window": { "applicationTheme": "dark", "useMica": true, }, "tabRow": { "background": "#00000000", }, }, { "name": "Edge", "tabRow": { "background": "accent" }, "window": { "applicationTheme": "system" } }, { "name": "orangey", "window": { "applicationTheme": "light", "useMica": true, }, "tabRow": { "background": "#ff8800", }, }, { "name": "WHITE", "window": { "applicationTheme": "dark", "useMica": true, }, "tabRow": { "background": "#FFFFFF", }, }, { "name": "terminal", "window": { "applicationTheme": "dark", "useMica": false, }, "tabRow": { "background": "terminalBackground", }, }, ] ``` </details>
|
Hey this is a DRAFT spec, not even a final version, so I've got a mind to merge this with 2 instead of 3. When we undraft the spec, we can go for 3 again. I'll give the bot a few hours for any NAKs. @msftbot merge this in 8 hours |
This is basically just like #14064, but with the `theme` instead. If you define a pair of `theme` names: ```json "theme": { "dark": "light", "light": "dark" }, ``` then the Terminal will use the one relevant for the current OS theme. This cooperates with #14064, who sets the `scheme` based on the app's theme. This was spec'd as a part of #3327 / #12530, but never promoted to its own issue. Gif below.
specs/drafts/folder, because it's CLEARLY not done yet.I discussed this a bit with Dustin. We felt it would be valuable to have these thoughts committed as a durable artifact. Better to have our Mica thoughts written down somewhere, with the context they belong in. That of course includes the bigger Theming spec, which never got finished.
I don't think we need to go through the fill spec review for this. Theming is clearly still a WIP. But committing this draft should give a better picture of what the vision is.
See also:
TODOs