docs: add section about focus outlines (#2634)

Co-authored-by: Tommmaso Menga <[email protected]>

docs/GETTING_STARTED.md

@@ -305,6 +305,28 @@ All our tokens and components use `rem` as size unit.
 We strongly recommend using the `rem` unit to guarantee consistent scaling
 when font size changes in browsers.
 
+### Focus outline
+
+Focus outlines should only be displayed when users are navigating by keyboard.
+Lyne components use the CSS selector `:focus-visible`, to achieve that. Whenever you have custom interactive elements,
+you should use the `:focus-visible` selector as well and include our SASS mixin `focus-outline`.
+
+```scss
+@use '../../core/styles' as sbb;
+
+button:focus-visible {
+  @include sbb.focus-outline;
+}
+```
+
+#### Dark background
+
+If a container element has a dark background color, all containing interactive elements should get a white outline.
+By setting `--sbb-focus-outline-color: var(--sbb-focus-outline-color-dark);` all descendants elements using the
+Lyne focus outline mixin (Lyne components included) receive the white outline because the variable gets inherited.
+Note: If a Lyne component has a `negative` property, the correct focus outline color gets automatically applied  
+to all contained interactive elements.
+
 ### Stacking
 
 As we can't use popover API yet, stacking of overlay context is done manually.

src/storybook/styles/layout/readme.md

@@ -53,22 +53,22 @@ Two items placed on grid using each 2 of 4 columns.
 
 Using columns in the middle of the grid (e.g. alerts in home stories).
 
-```sass
-  @use '@sbb-esta/lyne-components' as sbb;
-
-  .grid-reduced-width {
-    grid-column: 1/-1;
-
-    @include sbb.mq($from: large) {
-      grid-column: 2/-2;
-    }
-    @include sbb.mq($from: wide) {
-      grid-column: 3/-3;
-    }
-    @include sbb.mq($from: ultra) {
-      grid-column: 4/-4;
-    }
+```scss
+@use '@sbb-esta/lyne-components' as sbb;
+
+.grid-reduced-width {
+  grid-column: 1/-1;
+
+  @include sbb.mq($from: large) {
+    grid-column: 2/-2;
+  }
+  @include sbb.mq($from: wide) {
+    grid-column: 3/-3;
+  }
+  @include sbb.mq($from: ultra) {
+    grid-column: 4/-4;
   }
+}
 ```
 
 ```html