docs(material/theming): document strong focus indicators #22374

jelbourn · 2021-03-30T23:02:59Z

This adds documentation for strong focus indicators as part of the
theming guide. This feature has been "soft launched" inside Google, but
hasn't been documented for widespread adoption. At this stage, I'm
confident enough in the stability of the feature to document it for
public usage.

zelliott · 2021-03-31T00:28:24Z

guides/theming.md

+enable these strong focus indicators via two Sass mixins:
+`strong-focus-indicators` and `strong-focus-indicators-theme`.
+
+The `strong-focus-indicators` mixin emits structal indicator styles for all components. This mixin


Is "structal" supposed to be "structural" or "strong"?

I did intent to say "structural" versus the color styles from strong-focus-indicators-theme. Would it be better to say "base" or something similar here?

Structural makes sense, thanks!

zelliott

Just a quick note that I still have #19319 hanging over my head, which I'm hoping to find time to get to (someday). The proposed changes in that PR change the customization API, and we'll need to update these docs.

zelliott · 2021-03-31T00:32:28Z

guides/theming.md

+should be included exactly once in an application, similar to the `core` mixin described above.
+
+The `strong-focus-indicators-theme` mixin emits only the indicator's color styles. This mixin should
+be included once per theme, similar to the theme mixins described above.


I believe that the mixin also needs to be included in cases where the background color is not contrastive against the focus indicator's color. The example that comes to mind is mat-toolbar.

Good catch, added a sentence mentioning this.

guides/theming.md

crisbeto

LGTM

crisbeto · 2021-03-31T11:36:15Z

guides/theming.md

@@ -367,6 +367,83 @@ $my-palette: mat.define-palette(mat.$indigo-palette);
 }
 ```

+## Strong focus indicators
+
+By default, most components indicate browser focus by changing their background color as prescribed


Should it be "described" rather than "prescribed"?

"Prescribed" is what I intended, for the definition "state authoritatively or as a rule that (an action or procedure) should be carried out." Is it too weird?

As a non-native speaker, I've only heard "prescribed" as something somebody strongly recommends to you (e.g. prescribed medicine), but it might just be me.

Changed to "described"

jelbourn

@zelliott I forgot about #19319- what ended up stalling that one? How strongly do you feel about landing those changes any time in the near future? Once we formally "ship" this feature (by documenting it), future changes will be subject to Angular's breaking change policy.

jelbourn · 2021-03-31T21:18:14Z

guides/theming.md

@@ -367,6 +367,83 @@ $my-palette: mat.define-palette(mat.$indigo-palette);
 }
 ```

+## Strong focus indicators
+
+By default, most components indicate browser focus by changing their background color as prescribed


"Prescribed" is what I intended, for the definition "state authoritatively or as a rule that (an action or procedure) should be carried out." Is it too weird?

guides/theming.md

jelbourn · 2021-03-31T21:20:33Z

guides/theming.md

+enable these strong focus indicators via two Sass mixins:
+`strong-focus-indicators` and `strong-focus-indicators-theme`.
+
+The `strong-focus-indicators` mixin emits structal indicator styles for all components. This mixin


I did intent to say "structural" versus the color styles from strong-focus-indicators-theme. Would it be better to say "base" or something similar here?

jelbourn · 2021-03-31T21:23:03Z

guides/theming.md

+should be included exactly once in an application, similar to the `core` mixin described above.
+
+The `strong-focus-indicators-theme` mixin emits only the indicator's color styles. This mixin should
+be included once per theme, similar to the theme mixins described above.


Good catch, added a sentence mentioning this.

twerske · 2021-04-01T20:53:38Z

guides/theming.md

+## Strong focus indicators
+
+By default, most components indicate browser focus by changing their background color as prescribed
+by the Material Design specification. This behavior, however, can fall short of accessibility


I'm wondering if we can add when it can fall short, and if it does universally, why wouldn't I just always enable strong focus indication if it's a known shortcoming? When would I require a stronger indication of browser focus? Maybe just a visual example of what this looks like would be helpful

IIRC WCAG 2.2 implies that strong focus indicators are necessary but doesn't outright say it. Google'e internal requirements don't require it today, but probably will in the next year or so. We don't do this by default because it's not included in the Material Design spec. I've communicated to MD that it's a priority for us, but haven't seen any movement on it yet.

Ok, makes sense this is in the main theming guide then and likely should be built in!

This adds documentation for strong focus indicators as part of the theming guide. This feature has been "soft launched" inside Google, but hasn't been documented for widespread adoption. At this stage, I'm confident enough in the stability of the feature to document it for public usage.

angular-automatic-lock-bot · 2021-05-10T00:01:27Z

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}

jelbourn added P2 The issue is important to a large percentage of users, with a workaround docs This issue is related to documentation merge safe target: major This PR is targeted for the next major release labels Mar 30, 2021

jelbourn requested review from zelliott, mmalerba, twerske and TeriGlover March 30, 2021 23:03

google-cla bot added the cla: yes PR author has agreed to Google's Contributor License Agreement label Mar 30, 2021

jelbourn force-pushed the strong-focus-docs branch from 0467e72 to 95ade49 Compare March 30, 2021 23:11

zelliott reviewed Mar 31, 2021

View reviewed changes

zelliott approved these changes Mar 31, 2021

View reviewed changes

crisbeto approved these changes Mar 31, 2021

View reviewed changes

jelbourn commented Mar 31, 2021

View reviewed changes

twerske reviewed Apr 1, 2021

View reviewed changes

twerske approved these changes Apr 1, 2021

View reviewed changes

jelbourn force-pushed the strong-focus-docs branch from 95ade49 to f9bc34a Compare April 8, 2021 18:28

jelbourn removed request for mmalerba and TeriGlover April 8, 2021 18:28

jelbourn added the action: merge The PR is ready for merge by the caretaker label Apr 8, 2021

jelbourn force-pushed the strong-focus-docs branch from f9bc34a to b166363 Compare April 8, 2021 18:29

mmalerba merged commit 6720405 into angular:master Apr 9, 2021

jelbourn mentioned this pull request Apr 13, 2021

docs(focus indicators): Add documentation for focus indicators. #18724

Closed

angular-automatic-lock-bot bot locked and limited conversation to collaborators May 10, 2021

docs(material/theming): document strong focus indicators #22374

docs(material/theming): document strong focus indicators #22374

Uh oh!

Conversation

jelbourn commented Mar 30, 2021

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zelliott left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

crisbeto left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jelbourn left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

twerske Apr 1, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

angular-automatic-lock-bot bot commented May 10, 2021

Uh oh!

Uh oh!

twerske Apr 1, 2021 •

edited

Loading