docs: add cross-reference links, general review (part four)

src/components/sbb-autocomplete/readme.md

@@ -72,7 +72,7 @@ The displayed `sbb-option` can be collected into groups using `sbb-optgroup` ele
 
 The `sbb-option` emits the `option-selected` event when selected via user interaction.
 
-## Keyboard interaction
+### Keyboard interaction
 
 The options panel opens on `focus`, `click` or `input` events on the trigger element, or on `ArrowDown` keypress;
 it can be closed on backdrop click, or using the `Escape` or `Tab` keys.

src/components/sbb-navigation-action/readme.md

@@ -1,5 +1,6 @@
 The `sbb-navigation-action` component is an action element contained by 
-a [sbb-navigation-list](../sbb-navigation-list/readme.md) component or a [sbb-navigation-marker](../sbb-navigation-marker/readme.md) component. 
+a [sbb-navigation-list](/docs/components-sbb-navigation-sbb-navigation-list--docs) component 
+or a [sbb-navigation-marker](/docs/components-sbb-navigation-sbb-navigation-marker--docs) component. 
 
 ### Link / button properties
 

src/components/sbb-navigation-list/readme.md

@@ -1,5 +1,5 @@
-The `sbb-navigation-list` component is a collection of [sbb-navigation-action](../sbb-navigation-action/readme.md).
-Its intended use is inside a [sbb-navigation-section](../sbb-navigation-section/readme.md) component.
+The `sbb-navigation-list` component is a collection of [sbb-navigation-action](/docs/components-sbb-navigation-sbb-navigation-action--docs).
+Its intended use is inside a [sbb-navigation-section](/docs/components-sbb-navigation-sbb-navigation-section--docs) component.
 Optionally, a label can be provided via slot via the self-named property or the self-named slot.
 
 ```html
@@ -10,7 +10,6 @@ Optionally, a label can be provided via slot via the self-named property or the
 </sbb-navigation-list>
 ```
 
-
 <!-- Auto Generated Below -->
 
 

src/components/sbb-navigation-marker/readme.md

@@ -1,5 +1,5 @@
-The `sbb-navigation-marker` component is a collection of [sbb-navigation-action](../sbb-navigation-action/readme.md).
-Its intended use is inside a [sbb-navigation](../sbb-navigation/readme.md) component. 
+The `sbb-navigation-marker` component is a collection of [sbb-navigation-action](/docs/components-sbb-navigation-sbb-navigation-action--docs).
+Its intended use is inside a [sbb-navigation](/docs/components-sbb-navigation-sbb-navigation--docs) component. 
 
 ```html
 <sbb-navigation-marker>

src/components/sbb-navigation/readme.md

@@ -6,15 +6,15 @@ Some of its features are:
 - creates a backdrop for disabling interaction below the navigation;
 - disables scrolling of the page content while open;
 - manages focus properly by setting it on the first focusable element;
-- can act as a host for components as [sbb-navigation-list](../sbb-navigation-list/readme.md), [sbb-navigation-marker](../sbb-navigation-marker/readme.md) and [sbb-navigation-section](../sbb-navigation-section/readme.md);
+- can act as a host for components as [sbb-navigation-list](/docs/components-sbb-navigation-sbb-navigation-list--docs), 
+ [sbb-navigation-marker](/docs/components-sbb-navigation-sbb-navigation-marker--docs) 
+ and [sbb-navigation-section](/docs/components-sbb-navigation-sbb-navigation-section--docs);
 
-## Trigger
+### Interaction
 
 To display the `sbb-navigation` component you can either provide a trigger element using the `trigger` property,
 or call the `open()` method on the `sbb-navigation` component.
 
-The default `z-index` of the component is set to `1000`; to specify a custom stack order, the `z-index` can be changed by defining the CSS variable `--sbb-navigation-z-index`. 
-
 ```html
 <!-- Trigger element -->
 <sbb-button id="nav-trigger">Navigation trigger</sbb-button>
@@ -48,6 +48,11 @@ The default `z-index` of the component is set to `1000`; to specify a custom sta
 </sbb-navigation>
 ```
 
+### Style
+
+The default `z-index` of the component is set to `1000`; 
+to specify a custom stack order, the `z-index` can be changed by defining the CSS variable `--sbb-navigation-z-index`.
+
 ## Accessibility
 
 When a navigation action is marked to indicate the user is currently on that page, `aria-current="page"` should be set on that action. 

src/components/sbb-notification/readme.md

@@ -21,7 +21,18 @@ The `sbb-notification` is structured in the following way:
 
 Note that the notification only supports inline links, therefore any slotted link will be forced to be a `variant="inline"` link.
 
-### Type
+### States
+
+It is possible to display the component in `readonly` state by using the self-named property.
+In this case, the close button will not be shown.
+
+```html
+<sbb-notification readonly>
+  ...
+</sbb-notification>
+```
+
+### Variants
 
 The `sbb-notification` supports four types: `info` (default), `success`, `warn` and `error`, based on the type of the information displayed.
 
@@ -33,15 +44,15 @@ The `sbb-notification` supports four types: `info` (default), `success`, `warn`
 <sbb-notification type="error">...</sbb-notification>
 ```
 
-### Dismissal
+### Interaction
 
 Inline notifications do not dismiss automatically. 
 They persist on the page until the user dismisses them or takes action that resolves the notification.
 
 By default, a close button is displayed to dismiss inline notifications. Including the close button is optional 
 and should not be included if it is critical for a user to read or interact with the notification by setting the `readonly` property to `true`.
 
-### Animation
+### Style
 
 If the `sbb-notification` host needs a margin, in order to properly animate it on open/close, 
 we suggest using the `--sbb-notification-margin` variable to set it. 
@@ -52,13 +63,13 @@ For example, use `--sbb-notification-margin: 0 0 var(--sbb-spacing-fixed-4x) 0`
 
 ## Properties
 
-| Property           | Attribute           | Description                                                                                             | Type                                       | Default     |
-| ------------------ | ------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ----------- |
-| `disableAnimation` | `disable-animation` | Whether the animation is enabled.                                                                       | `boolean`                                  | `false`     |
-| `readonly`         | `readonly`          | Whether the notification is readonly. In readonly mode, there is no dismiss button offered to the user. | `boolean`                                  | `false`     |
-| `titleContent`     | `title-content`     | Content of title.                                                                                       | `string`                                   | `undefined` |
-| `titleLevel`       | `title-level`       | Level of title, will be rendered as heading tag (e.g. h3). Defaults to level 3.                         | `"1" \| "2" \| "3" \| "4" \| "5" \| "6"`   | `'3'`       |
-| `type`             | `type`              | The type of the notification.                                                                           | `"error" \| "info" \| "success" \| "warn"` | `'info'`    |
+| Property           | Attribute           | Description                                                                                               | Type                                       | Default     |
+| ------------------ | ------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ----------- |
+| `disableAnimation` | `disable-animation` | Whether the animation is enabled.                                                                         | `boolean`                                  | `false`     |
+| `readonly`         | `readonly`          | Whether the notification is readonly. In readonly mode, there is no dismissal button offered to the user. | `boolean`                                  | `false`     |
+| `titleContent`     | `title-content`     | Content of title.                                                                                         | `string`                                   | `undefined` |
+| `titleLevel`       | `title-level`       | Level of title,0it  will be rendered as heading tag (e.g. h3). Defaults to level 3.                       | `"1" \| "2" \| "3" \| "4" \| "5" \| "6"`   | `'3'`       |
+| `type`             | `type`              | The type of the notification.                                                                             | `"error" \| "info" \| "success" \| "warn"` | `'info'`    |
 
 
 ## Events

src/components/sbb-optgroup/readme.md

@@ -1,7 +1,10 @@
-The `sbb-optgroup` is a component used to group more `sbb-option` within a `sbb-autocomplete` or a `sbb-select` component.
-A `sbb-divider` is displayed at the bottom of the component.
+The `sbb-optgroup` is a component used to group more [sbb-option](/docs/components-sbb-option-sbb-option--docs)
+within a [sbb-autocomplete](/docs/components-sbb-autocomplete--docs)
+or a [sbb-select](/docs/components-sbb-select--docs) component.
 
-### Slot
+A [sbb-divider](/docs/components-sbb-divider--docs) is displayed at the bottom of the component.
+
+### Slots
 
 It is possible to provide a set of `sbb-option` via an unnamed slot; 
 the component has also a `label` property as name of the group.
@@ -16,7 +19,7 @@ the component has also a `label` property as name of the group.
 
 ### States
 
-The component has a `disabled` property which, if set to `true`, sets all the `sbb-option` in the group as disabled.
+The component has a `disabled` property which sets all the `sbb-option` in the group as disabled.
 
 ```html
 <sbb-optgroup label="Disabled group" disabled>

src/components/sbb-option/readme.md

@@ -1,4 +1,5 @@
-The `sbb-option` is a component which can be used to display items in components like `sbb-autocomplete` or `sbb-select`.
+The `sbb-option` is a component which can be used to display items in components like
+[sbb-autocomplete](/docs/components-sbb-autocomplete--docs) or a [sbb-select](/docs/components-sbb-select--docs).
 
 ### Slots
 
@@ -14,8 +15,10 @@ Icon space can be reserved even if the `iconName` property is not set by overrid
 
 ### States
 
-Like the native `option`, the component has a `value` property. The `selected`, `disabled` and `active` properties are 
-connected to the self-named states. When disabled, the selection via click is prevented.
+Like the native `option`, the component has a `value` property. 
+
+The `selected`, `disabled` and `active` properties are connected to the self-named states. 
+When disabled, the selection via click is prevented.
 If the `sbb-option` is nested in a `sbb-optgroup` component, it inherits from the parent the `disabled` state.
 
 ```html

src/components/sbb-radio-button-group/readme.md

@@ -1,7 +1,6 @@
-The `sbb-radio-button-group` is a component which can be used as a wrapper for a collection of `sbb-radio-button`,
-or, alternatively, for a collection of `sbb-selection-panel`.
-Pressing a `sbb-radio-button` checks it and unchecks the previously selected one, if any. 
-They can also be controlled programmatically by setting the value property of the parent radio group to the value of the radio.
+The `sbb-radio-button-group` is a component which can be used as a wrapper for 
+a collection of [sbb-radio-button](/docs/components-sbb-radio-button-sbb-radio-button--docs)s,
+or, alternatively, for a collection of [sbb-selection-panel](/docs/components-sbb-selection-panel--docs)s.
 
 ```html
 <!-- The first option will be selected by default -->
@@ -12,6 +11,10 @@ They can also be controlled programmatically by setting the value property of th
 </sbb-radio-button-group>
 ```
 
+
+Pressing a `sbb-radio-button` checks it and unchecks the previously selected one, if any.
+They can also be controlled programmatically by setting the value property of the parent radio group to the value of the radio.
+
 Please note that within a `sbb-radio-button-group`, only one `sbb-radio-button` can be selected at a time;
 if you need to select more than one item, it is recommended to use the `sbb-checkbox-group` component.
 
@@ -34,8 +37,6 @@ The radio group can have different states:
 </sbb-radio-button-group>
 ```
 
-### Deselecting Radios
-
 In order to deselect a `sbb-radio-button` inside the `sbb-radio-button-group`,
 you can use the `allowEmptySelection` property, which will be proxied to the inner `sbb-radio-button` 
 enabling their deselection (by default, a selected `sbb-radio-button` cannot be deselected).
@@ -46,7 +47,7 @@ enabling their deselection (by default, a selected `sbb-radio-button` cannot be
 </sbb-radio-button-group>
 ```
 
-### Orientation
+### Style
 
 The `orientation` property is used to set item orientation. Possible values are `horizontal` (default) and `vertical`.
 The optional property `horizontalFrom` can be used in combination with `orientation='vertical'` to

src/components/sbb-radio-button/readme.md

@@ -1,5 +1,6 @@
-The `sbb-radio-button` component provides the same functionality as a native `<input type="radio">` 
-enhanced with the SBB Design: use multiple `sbb-radio-button` components inside a `sbb-radio-button-group` component 
+The `sbb-radio-button` component provides the same functionality 
+as a native `<input type="radio">` enhanced with the SBB Design: use multiple `sbb-radio-button` components 
+inside a [sbb-radio-button-group](/docs/components-sbb-radio-button-sbb-radio-button-group--docs) component 
 in order to display a radio input within a group.
 
 ```html
@@ -11,14 +12,22 @@ in order to display a radio input within a group.
 
 ### States
 
-It is possible to display the component in `disabled` or `checked` state by using the self-named property. 
-The component has a `required` property, which can be useful for setting a custom `sbb-form-error` message within a `sbb-form-field`.
+It is possible to display the component in `disabled` or `checked` state by using the self-named properties. 
+
+The component has a `required` property, which can be useful
+for setting a custom [sbb-form-error](/docs/components-sbb-form-field-sbb-form-error--docs) message 
+within a [sbb-form-field](/docs/components-sbb-form-field-sbb-form-field--docs).
+
 The `allowEmptySelection` property allows user to deselect the component.
 
 ```html
-<sbb-radio-button value="One" disabled>Option one</sbb-radio-button>
+<sbb-radio-button value="One" checked>Option one</sbb-radio-button>
+
+<sbb-radio-button value="Two" disabled>Option two</sbb-radio-button>
+
+<sbb-radio-button value="Three" required>Option three</sbb-radio-button>
 
-<sbb-radio-button value="Two" required>Option two</sbb-radio-button>
+<sbb-radio-button value="Four" allowEmptySelection>Option four</sbb-radio-button>
 ```
 
 ### Style

src/components/sbb-select/readme.md

@@ -1,11 +1,13 @@
 The `sbb-select` is a component which provides a list of selectable options in an overlay panel, 
-emulating the behaviour of a native `select`. 
+emulating the behaviour of a native `<select>`. 
 
 ### In `sbb-form-field`
 
 If the component is used within a `sbb-form-field`, it will automatically display the option panel above or below it; 
 otherwise, the panel takes the component's parent element as origin. 
-Options or groups of options (see `sbb-option`/`sbb-optgroup` components) can be provided via an unnamed slot.
+Options or groups of options (see [sbb-option](/docs/components-sbb-option-sbb-option--docs) /
+[sbb-option-group](/docs/components-sbb-option-sbb-option-group--docs) components) 
+can be provided via an unnamed slot.
 
 ```html
 <sbb-form-field label="Train types">
@@ -20,15 +22,32 @@ Options or groups of options (see `sbb-option`/`sbb-optgroup` components) can be
 The component has a `value` property, which can be a string or a string array (when `multiple` is set to true).
 If no `value` has been set, it is possible to display a placeholder using the `placeholder` property. 
 
-Also note that if the `value` is set on the `sbb-select`, 
-it will override all the `selected` attributes on the internal `sbb-option`s, 
+Also note that if the `value` is set on the `sbb-select`, it will override all the `selected` attributes on the internal `sbb-option`s, 
 so setting a default value should be done using the `value` attribute on the `sbb-select` and not by setting the
 `selected` attribute on the internal `sbb-option`s.
 
-### Multiple 
+### States
+
+It is possible to display the component in `disabled` or `readonly` state by using the self-named properties. The component 
+has a `required` property, which can be useful for setting a custom `sbb-form-error` message within a `sbb-form-field`.
+
+```html
+<sbb-form-field label="Pick one:">
+  <sbb-select placeholder="1st gen starters">
+    <sbb-option value="Bulbasaur">Bulbasaur</sbb-option>
+    <sbb-option value="Charmander">Charmander</sbb-option>
+    <sbb-option value="Squirtle">Squirtle</sbb-option>
+  </sbb-select>
+  <sbb-form-error>You must pick one!</sbb-form-error>
+</sbb-form-field>
+```
+
+#### Multiple
+
+If the `multiple` property is set to false, only one option can be selected: 
+in this case the placeholder will be replaced by the chosen value and a check mark will appear 
+on the right of the selected option in the panel.
 
-If the `multiple` property is set to false, only one option can be selected: in this case the placeholder will be replaced 
-by the chosen value and a check mark will appear on the right of the selected option in the panel.
 If the `multiple` attribute is set to true, a visual checkbox will appear on the left of any option in the panel, and
 the selected values will be displayed in selection order, separated by a comma.
 
@@ -48,22 +67,6 @@ the selected values will be displayed in selection order, separated by a comma.
 </sbb-form-field>
 ```
 
-### States
-
-It is possible to display the component in `disabled` or `readonly` state by using the self-named properties. The component 
-has a `required` property, which can be useful for setting a custom `sbb-form-error` message within a `sbb-form-field`.
-
-```html
-<sbb-form-field label="Pick one:">
-  <sbb-select placeholder="1st gen starters">
-    <sbb-option value="Bulbasaur">Bulbasaur</sbb-option>
-    <sbb-option value="Charmander">Charmander</sbb-option>
-    <sbb-option value="Squirtle">Squirtle</sbb-option>
-  </sbb-select>
-  <sbb-form-error>You must pick one!</sbb-form-error>
-</sbb-form-field>
-```
-
 ### Events
 
 Consumers can listen to the native `change`/`input` event on the `sbb-select` component to intercept the selection's change;

src/components/sbb-selection-panel/readme.md

@@ -1,10 +1,12 @@
-The `sbb-selection-panel` component wraps either a `sbb-checkbox` or a `sbb-radio-button` that can optionally toggle a content section.
+The `sbb-selection-panel` component wraps either a [sbb-checkbox](/docs/components-sbb-checkbox-sbb-checkbox--docs) 
+or a [sbb-radio-button](/docs/components-sbb-radio-button-sbb-radio-button--docs) that can optionally toggle a content section.
 
 The content section can be opened by checking `sbb-checkbox` or selecting the `sbb-radio-button`. 
 Additionally, clicking on all the upper area sets the checked state and therefore opens the content; 
 clicking on the content area does not toggle anything.
 
-The selection panel can also be used inside a `sbb-radio-button-group` or a `sbb-checkbox-group`.
+The selection panel can also be used inside a [sbb-radio-button-group](/docs/components-sbb-radio-button-sbb-radio-button-group--docs) 
+or a [sbb-checkbox-group](/docs/components-sbb-checkbox-sbb-checkbox-group--docs).
 
 #### With `sbb-radio-button-group`
 
@@ -58,11 +60,12 @@ The selection panel can also be used inside a `sbb-radio-button-group` or a `sbb
 </sbb-checkbox-group>
 ```
 
-As shown in the examples above, `sbb-checkbox` and `sbb-radio-button` placed in a `sbb-selection-panel` are extended with a slot named "subtext" for the subtext and a slot named "suffix" for the suffix items.
+As shown in the examples above, `sbb-checkbox` and `sbb-radio-button` placed in a `sbb-selection-panel` are extended 
+with a slot named `subtext` for the subtext and a slot named `suffix` for the suffix items.
 
 ### Style
 
-The component has two background options that can be set using the `color` variable: `milk` and `white`.
+The component has two background options that can be set using the `color` variable: `milk` and `white` (default).
 
 ```html
 <sbb-selection-panel color='milk'>