Update focus outline color to meet WCAG 2.2 contrast standards

packages/core/src/common/_color-aliases.scss

@@ -25,6 +25,11 @@ $pt-app-elevated-background-color: $light-gray4 !default;
 $pt-dark-app-elevated-background-color: $dark-gray3 !default;
 
 $pt-outline-color: rgba($blue3, 0.6) !default;
+// 0.752 opacity to meet WCCAG 2.2 minimum contrast guidelines with all light-gray backgrounds in light theme
+// and all dark-gray backgrounds in dark theme
+$pt-focus-indicator-color: rgba($blue2, 0.752) !default;
+// between $blue4 and $blue5
+$pt-dark-focus-indicator-color: rgba(#7BB0FB, 0.752) !default;
 
 $pt-text-color: $dark-gray1 !default;
 $pt-text-color-muted: $gray1 !default;

packages/core/src/common/_mixins.scss

@@ -91,6 +91,15 @@ $pt-dark-intent-text-colors: (
   outline: $pt-outline-color solid 2px;
   outline-offset: $offset;
   -moz-outline-radius: 6px;
+
+  // this should become default in bp6, providing new behavior as a class for now to avoid breaking changes
+  // to focus colors
+  .bp5-focus-enhanced-contrast & {
+    outline: $pt-focus-indicator-color solid 2px;
+  }
+  .#{$ns}-dark.bp5-focus-enhanced-contrast & {
+    outline-color: $pt-dark-focus-indicator-color;
+  }
 }
 
 @function border-shadow($alpha, $color: $black, $size: 1px) {

packages/core/src/components/forms/_common.scss

@@ -15,13 +15,15 @@ $input-color-disabled: $button-color-disabled !default;
 $input-placeholder-color: $pt-text-color-muted !default;
 $input-background-color: $white !default;
 $input-background-color-disabled: rgba($light-gray1, 0.5) !default;
-$input-shadow-color-focus: $pt-intent-primary !default;
+// should become $input-shadow-color-focus: $pt-intent-primary !default; in bp6
+$input-shadow-color-focus: $pt-focus-indicator-color !default;
 
 $dark-input-color: $pt-dark-text-color !default;
 $dark-input-color-disabled: $dark-button-color-disabled !default;
 $dark-input-placeholder-color: $pt-dark-text-color-muted !default;
 $dark-input-background-color: rgba($black, 0.3) !default;
 $dark-input-background-color-disabled: rgba($dark-gray5, 0.5) !default;
+// should become $dark-input-shadow-color-focus: $pt-dark-focus-indicator-color !default; in bp6
 $dark-input-shadow-color-focus: $blue4 !default;
 
 $control-indicator-size: $pt-icon-size-standard !default;
@@ -100,6 +102,10 @@ $control-group-stack: (
   transition: $input-transition;
   vertical-align: middle;
 
+  .bp5-focus-enhanced-contrast & {
+    outline: none;
+  }
+
   &:focus,
   &.#{$ns}-active {
     box-shadow: input-transition-shadow($input-shadow-color-focus, true), $input-box-shadow-focus;

packages/core/src/components/forms/_controls.scss

@@ -197,7 +197,7 @@ $control-indicator-spacing: $pt-grid-size !default;
 
   input:focus ~ .#{$ns}-control-indicator {
     @include focus-outline();
-    outline: $blue3 solid 2px;
+    outline: $blue3 solid 2px; // remove this line for bp6 for a consistent focus outline style
   }
 
   // right-aligned indicator is glued to the right side of the container

packages/core/src/docs/accessibility.md

@@ -59,4 +59,14 @@ const MyComponent = () => ({
 
 Colors have been designed to be accessible to as many people as possible, even those who are
 visually impaired or experiencing any kind of colorblindness. Our colors have not only been chosen
-to go well together but to also adhere to [WCAG 2.0](https://www.w3.org/TR/WCAG20/) standards.
+to go well together, but to also adhere to [WCAG 2.0](https://www.w3.org/TR/WCAG20/) standards.
+
+@### Enhanced focus indication [WCAG 2.2 focus appearance](https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance.html)
+
+All Blueprint elements descending from an element with the `bp5-focus-enhanced-contrast` class, will
+received enhanced focus indication. With this class applied at the root, the focus contrast meets the
+3:1 minimum contrast requirement against all light-gray colors in light theme, and all dark-gray colors
+in dark theme. If using other background colors you may need to style custom focus indication depending
+on the background color used to meet minimum contrast requirements.
+
+In Blueprint 6 this will become the default behavior without needing to add a wrapping class.

packages/docs-theme/src/components/documentation.tsx

@@ -166,6 +166,7 @@ export class Documentation extends React.PureComponent<DocumentationProps, Docum
         const { nav, pages } = this.props.docs;
         const rootClasses = classNames(
             "docs-root",
+            "bp5-focus-enhanced-contrast",
             { "docs-examples-only": location.search === "?examples" },
             this.props.className,
         );