Skip to content

Port SettingsCard/Expander from WCT and update SUI to use it#20232

Open
carlos-zamora wants to merge 16 commits into
mainfrom
dev/cazamor/sui-rejuv/setting-container
Open

Port SettingsCard/Expander from WCT and update SUI to use it#20232
carlos-zamora wants to merge 16 commits into
mainfrom
dev/cazamor/sui-rejuv/setting-container

Conversation

@carlos-zamora

@carlos-zamora carlos-zamora commented May 15, 2026

Copy link
Copy Markdown
Member

Summary of the Pull Request

Ports the SettingsCard and SettingsExpander from Windows Community Toolkit to the TerminalSettingsEditor project:

  • Windows Community Toolkit code: https://github.com/CommunityToolkit/Windows/tree/main/components/SettingsControls/src
    • SettingsCard and SettingsExpander were ported over and reuse our macros to reduce boilerplate.
    • A few deviations exist since WCT targets WinUI 3 but TSE uses WinUI 2 (i.e. chevron rendering)
    • One deviation specific to TSE: Description is applied as AutomationProperties.FullDescription for accessibility. This is for accessibility compliance. Description text should be read out by the screen reader (scan mode isn't enough). Prior to this change, we would expose it as HelpText. This change exposes it as FullDescription which is more fitting as it's generally an opt-in behavior for screen reader users to hear. This prevents the user from being overwhelmed with information.
  • SettingsControlsHelpers is used to make this much easier to review. Any converters, triggers, or other classes that are used for the migration were added there.

Additionally, this PR performs the migration to use these new controls and removes SettingContainer entirely. Associated changes:

  • Resources: renamed keys .HelpText --> .Description
  • Deleting SettingContainerStyle.xaml and moving anything that's still used to CommonResources.xaml
  • Appearances: BackgroundImageSettingsVisible --> BackgroundImageSettingsEnabled to make use of the disabled styling
  • GenerateSettingsIndex.ps1 was updated to target SettingsCard/SettingsExpander for the search index

Other notable changes as a part of using the new controls:

  • Navigators (i.e. "Advanced" button in Profiles page, Extensions page) were also converted to use SettingsCard
  • Utils.h/cpp includes a fix for deep link to work for nested settings (i.e. "Foreground", "Columns")

Switching to use the WCT port directly allows us to iterate faster on the settings UI and be more consistent with the Windows ecosystem. However, this does mean that the "reset button" had to be removed from the individual settings. This was already a weird pattern, so removing it shouldn't be too much of an issue. However, there was value to being able to reset settings. To provide this kind of functionality, a "reset" button is being added to the profile pages. This clears all settings in a profile so that they can apply their own customizations on top. It sacrifices granularity for simplicity and is a better understood concept.

Validation Steps Performed

  • settings search should pick up and navigate to settings properly
  • accessibility audit

PR Checklist

Related to #17000

Comment thread src/cascadia/TerminalSettingsEditor/SettingsExpander.cpp Fixed
@github-actions

This comment has been minimized.

@carlos-zamora

Copy link
Copy Markdown
Member Author

UI changes I noticed while poking around:

  • Clicking middle of expander doesn't open anymore
  • Profile > Icon: expander contents are much larger
  • Container height changed 64 px -> 66 px
  • Expander chevron has additional padding to left (against preview value)
  • Profile > Appearance > Color scheme: padding inside expander looks bad
  • Profile > Appearance > "Variable font axes" & "Font features": "+ Add new" button is misaligned

I hit a point where I could go in and make everything look the same as we have it now, but I felt that that mildly contradicted the idea behind trying to make the UI "consistent" by using these controls.

@niels9001 I'll go through and do a second pass fixing the things above. Can you also go through it and point out any inconsistencies with the UI that should be addressed? The main files that are probably of interest are:

  • src/cascadia/TerminalSettingsEditor/SettingsControlsStyle.xaml
  • src/cascadia/TerminalSettingsEditor/SettingContainerStyle.xaml

Once we figure that out and this gets reviewed/merged, we can probably use SettingsCards in #20215.

@niels9001

Copy link
Copy Markdown
Contributor

UI changes I noticed while poking around:

  • Clicking middle of expander doesn't open anymore
  • Profile > Icon: expander contents are much larger
  • Container height changed 64 px -> 66 px
  • Expander chevron has additional padding to left (against preview value)
  • Profile > Appearance > Color scheme: padding inside expander looks bad
  • Profile > Appearance > "Variable font axes" & "Font features": "+ Add new" button is misaligned

I hit a point where I could go in and make everything look the same as we have it now, but I felt that that mildly contradicted the idea behind trying to make the UI "consistent" by using these controls.

@niels9001 I'll go through and do a second pass fixing the things above. Can you also go through it and point out any inconsistencies with the UI that should be addressed? The main files that are probably of interest are:

  • src/cascadia/TerminalSettingsEditor/SettingsControlsStyle.xaml
  • src/cascadia/TerminalSettingsEditor/SettingContainerStyle.xaml

Once we figure that out and this gets reviewed/merged, we can probably use SettingsCards in #20215.

The issue is that we are now mixing-and-matching SettingsCard/SettingsExpander with SettingsContainer. The Toolkit's settings controls have all visual states and logic built-in: for example, if you host a ToggleSwitch as part of the Content, it will automatically apply the right style to make it right-aligned. Now, we are overriding that style again with a manual style. Therefore, you see a lot of inconsistencies because there are style overrides happening.

How big is the gap between SettingsContainer and the Settings controls? Like, could we deprecate it completely and port over the things that are required to SettingsCard (which gets hosted by the Expander too?

Comment thread src/cascadia/TerminalSettingsEditor/SettingContainer.cpp Fixed
Comment thread src/cascadia/TerminalSettingsEditor/SettingsControlsStyle.xaml Fixed
@github-actions

This comment has been minimized.

Comment thread src/cascadia/TerminalSettingsEditor/SettingsCard.cpp Fixed
Comment thread src/cascadia/TerminalSettingsEditor/SettingsCard.cpp Fixed
Comment thread src/cascadia/TerminalSettingsEditor/SettingsCard.cpp Fixed
Comment thread src/cascadia/TerminalSettingsEditor/SettingsCard.cpp Fixed
Comment thread src/cascadia/TerminalSettingsEditor/SettingsCard.cpp Fixed
Comment thread src/cascadia/TerminalSettingsEditor/SettingsControlsStyle.xaml Fixed
Comment thread src/cascadia/TerminalSettingsEditor/SettingsExpander.idl Fixed
Comment thread src/cascadia/TerminalSettingsEditor/StyleExtensions.idl Fixed
@github-actions

This comment has been minimized.

Comment thread src/cascadia/TerminalSettingsEditor/SettingsCard.cpp Fixed
@github-actions

This comment has been minimized.

@carlos-zamora carlos-zamora force-pushed the dev/cazamor/sui-rejuv/setting-container branch from 834a37e to f7eb2fb Compare May 21, 2026 02:19
@github-actions

This comment has been minimized.

@github-actions

This comment has been minimized.

Comment thread src/cascadia/TerminalSettingsEditor/SettingsControlsStyle.xaml Fixed
@github-actions

This comment has been minimized.

@carlos-zamora carlos-zamora marked this pull request as ready for review June 11, 2026 20:15
@carlos-zamora

Copy link
Copy Markdown
Member Author

⚠️TODO: Need to figure out a new "reset value" system with the designer

  • The "clear all" system doesn't really work well.
  • Scenario:
    • User changes a profile's icon and realizes (s)he doesn't like it.
    • main: use "reset value" button on the setting
    • current: use "reset all" button (loses all other changes!)
    • other ideas:
      • maybe we can add a "..." next to the setting control that allows users to reset?
      • this is an opportunity to educate more about the "reset value" + inheritance system
      • I guess we could also add in the "reset value" button into SettingsCard/Expander like we have it in SettingContainer

Aside from that, this PR is ready for review. Unfortunately, it's a decently large thing to figure out 😅

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants