mirror of
https://github.com/microsoft/PowerToys.git
synced 2026-04-05 10:46:33 +02:00
bb604d87ca
## Problem
Input controls (ComboBoxes, ToggleSwitches, NumberBoxes) within
SettingsCards throughout the PowerToys Settings UI were not
programmatically associated with their visible labels. This caused
screen readers to announce only the control type (e.g., "combo box",
"toggle switch") without any context about the control's purpose, making
the settings inaccessible to screen reader users.
This violates WCAG 2.2 Success Criterion 1.3.1 (Info and Relationships)
- Level A requirement.
**User Impact**: Screen reader users navigating PowerToys settings would
hear only "edit text" or "combo box" with no description, making it
difficult or impossible to configure settings independently.
## Solution
Added `AutomationProperties.Name` bindings to controls, linking them to
their parent SettingsCard's `Header` property. This establishes the
programmatic relationship between labels and controls required by
assistive technologies.
### Pattern Applied
For controls inside SettingsCards with a `Name` attribute:
```xaml
<tkcontrols:SettingsCard Name="LanguageHeader" x:Uid="LanguageHeader">
<ComboBox
MinWidth="{StaticResource SettingActionControlMinWidth}"
AutomationProperties.Name="{Binding ElementName=LanguageHeader, Path=Header}"
DisplayMemberPath="Language"
ItemsSource="{Binding Languages, Mode=TwoWay}"
SelectedIndex="{Binding LanguagesIndex, Mode=TwoWay}" />
</tkcontrols:SettingsCard>
```
For data templates where headers are data-bound:
```xaml
<DataTemplate x:Key="ComboBoxTemplate" x:DataType="viewModels:PluginAdditionalOptionViewModel">
<tkcontrols:SettingsCard Header="{x:Bind Path=DisplayLabel}">
<ComboBox
AutomationProperties.Name="{x:Bind Path=DisplayLabel}"
ItemsSource="{x:Bind Path=ComboBoxItems}" />
</tkcontrols:SettingsCard>
</DataTemplate>
```
## Changes Made
### GeneralPage.xaml (7 controls)
- Language selection ComboBox
- Color mode/theme ComboBox
- Run at startup ToggleSwitch
- Show system tray icon ToggleSwitch
- Enable experimentation ToggleSwitch
- Enable data diagnostics ToggleSwitch
- Enable view diagnostic data ToggleSwitch
### PowerLauncherPage.xaml (4 data templates)
- ComboBoxTemplate - for plugin settings
- NumberBoxTemplate - for plugin numeric settings
- CheckBoxComboBoxTemplate - for conditional ComboBox settings
- CheckBoxNumberBoxTemplate - for conditional NumberBox settings
### PowerRenamePage.xaml (6 controls)
- Enable PowerRename ToggleSwitch
- Context menu mode ComboBox
- Enable auto-complete ToggleSwitch
- Max display list number NumberBox
- Restore flags on launch ToggleSwitch
- Use Boost library ToggleSwitch
### NewPlusPage.xaml (4 controls)
- Enable New+ ToggleSwitch
- Hide file extension ToggleSwitch
- Hide starting digits ToggleSwitch
- Replace variables ToggleSwitch
## Testing
Screen readers (Windows Narrator) now properly announce controls with
context:
- **Before**: "Combo box"
- **After**: "Language, Combo box"
No functional changes to application behavior. The fix only affects how
controls are announced to assistive technologies.
## Notes
This fix follows the existing pattern already used in
ColorPickerPage.xaml. Similar issues exist in approximately 23 other
Settings pages which can be addressed in future PRs using this
established pattern. The pages fixed in this PR represent
commonly-accessed settings and demonstrate the solution approach for
comprehensive coverage.
Closes #<issue_number>
## References
- WCAG 2.2 SC 1.3.1:
https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships
- UIA Name Property:
https://learn.microsoft.com/en-us/windows/apps/design/accessibility/accessible-text-requirements#name_property_alternative_and_description
<!-- START COPILOT CODING AGENT SUFFIX -->
<details>
<summary>Original prompt</summary>
>
> ----
>
> *This section details on the original issue you should resolve*
>
> <issue_title>Controls Inside Sections Are Not Associated with Their
Labels.</issue_title>
> <issue_description>### Microsoft PowerToys version
>
> v0.94.2
>
> ### Installation method
>
> PowerToys auto-update
>
> ### Area(s) with issue?
>
> New+
>
> ### Steps to reproduce
>
> **Repro Steps:**
>
> 1. Open the Power Toys.
> 2. Now navigate to the home present in the left navigation pane.
> 3. Now turn on the narrator using CTRL + Win + Enter.
> 4. Now navigate to the controls present inside the different sections.
> 5. Observe the issue.
>
> ### ✔️ Expected Behavior
>
> Each control should be programmatically associated with its
corresponding label so screen readers can accurately convey the purpose
of the control to users.
>
> ### ❌ Actual Behavior
>
> Input controls (e.g., checkboxes, text fields, dropdowns) located
within different sections of the UI are not programmatically associated
with their visible labels.
>
> ### Additional Information
>
> **User Impact:**
> Screen reader users may hear only the control type (e.g., “edit text”)
with no context or description of what it is for. This makes it
difficult or impossible for them to fill out forms or interact with the
UI correctly, leading to confusion and frustration.
>
> **WCAG Reference:**
> https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships
>
> **Attachments:**
>
>
https://github.com/user-attachments/assets/d25b9237-bee7-41d5-b564-df15df19b0d4
>
> ### Other Software
>
> _No response_</issue_description>
>
> ## Comments on the Issue (you are @copilot in this section)
>
> <comments>
> </comments>
>
</details>
Fixes microsoft/PowerToys#42419
<!-- START COPILOT CODING AGENT TIPS -->
---
✨ Let Copilot coding agent [set things up for
you](https://github.com/microsoft/PowerToys/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot)
— coding agent works faster and does higher quality work when set up for
your repo.
---------
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: niels9001 <9866362+niels9001@users.noreply.github.com>
Co-authored-by: Gordon Lam (SH) <yeelam@microsoft.com>