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

src/components/sbb-tab-group/readme.md

@@ -1,6 +1,7 @@
 The `sbb-tab-group` is a component used to organize and gather tabs that the user can navigate through; 
 use it when you want to provide navigation within blocks of content, instead of showing everything in one place 
 or requiring the user to navigate between several different views. 
+
 Each tab has a related content, distinct from other tabs' content; 
 tab panels can present different sections of content and include text, images, forms, other tab groups, etc.
 
@@ -17,16 +18,18 @@ tab panels can present different sections of content and include text, images, f
 </sbb-tab-group>
 ```
 
-In order to display a tab label within the tab bar, provide an `sbb-tab-title` right before the related tab content; 
-please refer to the `sbb-tab-title` documentation for more details.
-The content element should be wrapped in a `div`, a `section` or an `article` and placed right after its relative tab title.
+In order to display a tab label within the tab bar, provide a `sbb-tab-title` right before its related tab content; 
+please refer to the [sbb-tab-title](/docs/components-sbb-tab-sbb-tab-title--docs) documentation for more details.
+
+**Note:** the content element should be wrapped in a `div`, a `section` or an `article` and placed right after its relative `sbb-tab-title`.
 Tab groups can also be nested, which means that a tab's content block can be represented by another `sbb-tab-group`, 
 as shown in the "Nested Tab Groups" example.
 
 ### States
 
 A tab can be selected, unselected, or in `disabled` state; disable a tab to mark it as unavailable. 
 Disabled tabs cannot be focused and may be invisible to assistive technologies such as screen readers.
+
 It's possible to set the first selected tab using the `initialSelectedIndex` property.
 
 ```html

src/components/sbb-tab-title/readme.md

@@ -1,47 +1,40 @@
-The `sbb-tab-title` is a component which is meant to be used in combination with the `sbb-tab-group` component 
+The `sbb-tab-title` is a component which is meant to be used in combination with the 
+[sbb-tab-group](/docs/components-sbb-tab-sbb-tab-group--docs) component 
 in order to display a tab label within the tab bar.
 
 ```html
-<sbb-tab-group>
-  <sbb-tab-title>
-    Tab Label
-  </sbb-tab-title>
-</sbb-tab-group>
+<sbb-tab-title>Tab Label</sbb-tab-title>
 ```
 
 ### Slots
 
 It is possible to provide a label via an unnamed slot; the component can optionally display a `sbb-icon`
 at the component start using the `iconName` property or via custom content using the `icon` slot.
+
 It's also possible to display a numeric amount at the component's end using the `amount` property or slot.
-It's possible to change the label's heading tag using the `level` property.
+
+The label's heading tag can be changed using the `level` property.
 
 ```html
-<sbb-tab-group>
-  <sbb-tab-title icon-name="app-icon-small" amount="123">
-    Tab Label
-  </sbb-tab-title>
-</sbb-tab-group>
-
-<sbb-tab-group>
-  <sbb-tab-title>
-    <sbb-icon slot="icon" name="circle-information-small"></sbb-icon>
-    Tab Label
-    <span slot="amount">123</span>
-  </sbb-tab-title>
-</sbb-tab-group>
+<sbb-tab-title icon-name="app-icon-small" amount="123">
+  Tab Label
+</sbb-tab-title>
+
+<sbb-tab-title>
+  <sbb-icon slot="icon" name="circle-information-small"></sbb-icon>
+  Tab Label
+  <span slot="amount">123</span>
+</sbb-tab-title>
 ```
 
 ### States
 
 It is possible to display the component in `disabled` state by using the self-named property.
 
 ```html
-<sbb-tab-group disabled>
-  <sbb-tab-title>
-    Tab Label
-  </sbb-tab-title>
-</sbb-tab-group>
+<sbb-tab-title disabled>
+  Tab Label
+</sbb-tab-title>
 ```
 
 <!-- Auto Generated Below -->

src/components/sbb-tag-group/readme.md

@@ -1,7 +1,8 @@
 The `sbb-tag-group` component is used as a container for one or multiple `sbb-tag` components,
 which are projected inside the unnamed slot.
 
-To work properly, it's mandatory to provide a value to each `sbb-tag`. See its documentation for more details.
+To work properly, it's mandatory to provide a value to each `sbb-tag`. 
+See [its documentation]((/docs/components-sbb-tag-sbb-tag--docs)) for more details.
 
 ```html
 <sbb-tag-group>
@@ -12,7 +13,9 @@ To work properly, it's mandatory to provide a value to each `sbb-tag`. See its d
 </sbb-tag-group>
 ```
 
-## Exclusive selection vs. multiple selection
+### Interaction
+
+#### Exclusive selection vs. multiple selection
 
 By default, `sbb-tag-group` acts like a radio-button group: only one item can be selected. 
 In this mode, the value of the `sbb-tag-group` will reflect the value of the selected `sbb-tag`.
@@ -29,12 +32,12 @@ In this mode the value of the `sbb-tag-group` is an array containing all values
 </sbb-tag-group>
 ```
 
-### Changing multiple property during run time
+#### Changing multiple property during run time
 
 There is no support for changing multiple mode during run time (e.g., update value automatically).
 So this flag should be provided at component's instantiation time.
 
-### Advanced usage: multiple and exclusive mixed
+#### Advanced usage: multiple and exclusive mixed
 
 ```ts
 const uncheckAllTag = () => {
@@ -65,8 +68,8 @@ const uncheckTags = () => {
 The property `listAccessibilityLabel` is forwarded as `aria-label` to the inner list that the component uses to display the tags,
 to use the implicit `role="list"` of the `ul`.
 
-If the `listAccessibilityLabel` property is not defined, the `sbb-tag-group` surrounding the buttons 
-applies `role="group"` to convey the association between the individual `sbb-tag`s. 
+If the `listAccessibilityLabel` property is not defined, the `sbb-tag-group` surrounding the buttons applies `role="group"` 
+to convey the association between the individual `sbb-tag`s. 
 
 When using the `role="group"`, each `sbb-tag-group` element should be given a label with `aria-label` or `aria-labelledby`,
 that communicates the collective meaning of all `sbb-tag`s.

src/components/sbb-tag/readme.md

@@ -1,5 +1,5 @@
 The `sbb-tag` is a component that can be used as a filter in order to categorize a large amount of information.
-It's intended to be used inside an `sbb-tag-group`.
+It's intended to be used inside the [sbb-tag-group](/docs/components-sbb-tag-sbb-tag-group--docs) component.
 
 ```html
 <sbb-tag value="All">All</sbb-tag>
@@ -9,6 +9,7 @@ It's intended to be used inside an `sbb-tag-group`.
 
 It is possible to provide a label via an unnamed slot; the component can optionally display a `sbb-icon` 
 at the component start using the `iconName` property or via custom content using the `icon` slot.
+
 It's also possible to display a numeric amount at the component's end using the `amount` property or slot.
 
 ```html
@@ -44,7 +45,6 @@ It's recommended to check the parent's `sbb-tag-group` for the value.
 The component imitates an `button` element to provide an accessible experience. 
 The state is reflected via `aria-pressed` attribute.
 
-
 <!-- Auto Generated Below -->
 
 

src/components/sbb-time-input/readme.md

@@ -1,7 +1,7 @@
 The `sbb-time-input` is a component that displays the typed value as a formatted time (HH:mm).
 
 The component allows the insertion of up to 4 numbers, possibly with a separator char like `.`, `:`, `,` or `-`, 
-then automatically formats the value as time and displays it (see the "Format example" paragraph).
+then automatically formats the value as time and displays it (see ["Format example"](#format-example)).
 
 The component and the native `input` can be connected using the `input` property,
 which accepts the id of the native input, or directly its reference.
@@ -25,11 +25,12 @@ If the `sbb-time-input` is used within a `sbb-form-field` with a native input, t
 The initial value can be set using the `value` property (string) of the `input`or the `setValueAsDate()` method of the `sbb-time-input`.
 
 When the input changes, if it is valid, the component updates the `value` of the `input`. 
+
 To get the value as a `Date` object, the `getValueAsDate()` method of the `sbb-time-input` can be called.
 The date is constructed like following: the start date is set to 01.01.1970, 00:00:00 UTC, then the typed hours and minuted are added, 
 e.g.: with a value of `12:34`, the `getValueAsDate()` will be 01.01.1970, 12:34:00 UTC.
 
-If the value is invalid because not real (e.g., 12:61 or 25:30), the component does not format the `value`,
+If the value is invalid because not real (e.g. 12:61 or 25:30), the component does not format the `value`,
 and will return `null` if  `getValueAsDate()` was called.
 
 ### Format example
@@ -51,7 +52,7 @@ See the table below for some formatting examples:
 | 12,34 | 12:34  |
 | 12-34 | 12:34  |
 
-## Validation Change
+## Events
 
 Whenever the validation state changes (e.g., a valid value becomes invalid or vice-versa), the `validationChange` event is emitted.
 

src/components/sbb-title/readme.md

@@ -1,4 +1,4 @@
-The `sbb-title` is a component which renders an heading element according to the provided `level` (default: `1`).
+The `sbb-title` is a component which renders a heading element according to the provided `level` (default: `1`).
 
 ```html
 <sbb-title>Hello</sbb-title>

src/components/sbb-toast/readme.md

@@ -13,7 +13,7 @@ if a new `sbb-toast` is opened while a previous message is still showing, the ol
 ### Important note
 
 You should carefully consider every use of the `sbb-toast` component since it can be a source of stress for people with visual impairments
-(see the [accessibility](#accessibility) section for more info).
+(see the ["Accessibility"](#accessibility) section for more info).
 
 Here are a few tips for correct usage:
 * Try to avoid actions inside a `sbb-toast` since they are not easily reachable;
@@ -54,7 +54,7 @@ The time before the component auto-closing can be set with the `timeout` propert
 
 The position on the page where the toast will be opened can be configured with the `position` property,
 which accepts all the combinations of the vertical positions `top` and `bottom` 
-with the horizontal positions `left`, `start`, `center`, `right` and `end` (default: 'bottom-center').
+with the horizontal positions `left`, `start`, `center`, `right` and `end` (default: `bottom-center`).
 
 ```html
 <sbb-button onClick={() => document.querySelector('sbb-toast').open() } />
@@ -77,7 +77,7 @@ Check [ARIA live regions](https://developer.mozilla.org/en-US/docs/Web/Accessibi
 The `sbb-toast` does not move focus to the toast element, because it would disrupt users in the middle of a workflow. 
 
 For any action offered in the `sbb-toast`, your application should provide an alternative way to perform the action 
-(e.g., a keyboard combination).
+(e.g. a keyboard combination).
 
 Avoid setting a `timeout` for toasts that have an action available,
 as screen reader users may want to navigate to the toast element to activate the action.

src/components/sbb-toggle-check/readme.md

@@ -9,7 +9,7 @@ enhanced with the SBB Design.
 
 It is possible to provide a label via an unnamed slot; the component can optionally display a `sbb-icon`
 using the `iconName` property or via custom content using the `icon` slot. 
-The icon can be at the component start or end based on the value of `labelPosition` property (default: `after`).
+The icon can be at the component start or end based on the value of the `labelPosition` property (default: `after`).
 
 ```html
 <sbb-toggle-check value="single-checkbox" icon-name='pie-small'>
@@ -21,8 +21,6 @@ The icon can be at the component start or end based on the value of `labelPositi
 </sbb-toggle-check>
 ```
 
-If you don't want the label to appear next to the toggle-check, you can use `aria-label` to specify an appropriate label.
-
 ### States
 
 The component can be displayed in `checked` or `disabled` states using the self-named properties.
@@ -44,7 +42,8 @@ The `sbb-toggle-check` component uses an internal `<input type="checkbox"/>` to
 This internal checkbox receives focus and is automatically labelled by the text content of the `sbb-toggle-check` element. 
 Avoid adding other interactive controls into the content of `sbb-toggle-check`, as this degrades the experience for users of assistive technology.
 
-Always provide an accessible label via `aria-label` for checkboxes without descriptive text content.
+If you don't want the label to appear next to the `sbb-toggle-check` component,
+you can not provide it and then use `aria-label` to specify an appropriate label for screen-readers.
 
 ```html
 <sbb-toggle-check aria-label="Subscribed to email message" />

src/components/sbb-toggle-option/readme.md

@@ -1,4 +1,5 @@
-The `sbb-toggle-option` component is used inside the `sbb-toggle` in order to render the toggle's options. 
+The `sbb-toggle-option` component is used inside the 
+[sbb-toggle](/docs/components-sbb-toggle-sbb-toggle--docs) in order to render the toggle's options. 
 
 ```html
 <sbb-toggle-option value="Value">Option</sbb-toggle-option>

src/components/sbb-toggle/readme.md

@@ -1,7 +1,9 @@
-The `sbb-toggle` component is a wrapper for two `sbb-toggle-option` that can be selected by the user. 
+The `sbb-toggle` component is a wrapper for a couple of [sbb-toggle-option](/docs/components-sbb-toggle-sbb-toggle-option--docs)s
+that can be selected by the user; it is useful for switching between views within the content 
 
-Their behavior is similar to `sbb-tab-group` or `sbb-radio-button-group`, where selecting an option deselects the previously selected one. 
-The `sbb-toggle` component is useful for switching between views within the content.
+Their behavior is similar to [sbb-tab-group](/docs/components-sbb-tab-sbb-tab-group--docs) 
+or [sbb-radio-button-group](/docs/components-sbb-radio-button-sbb-radio-button-group--docs), 
+where selecting an option deselects the previously selected one. 
 
 ```html
 <sbb-toggle value="Value 1">

src/components/sbb-tooltip-trigger/readme.md

@@ -1,4 +1,5 @@
-The `sbb-tooltip-trigger` component is used to trigger a tooltip by pressing or hovering on a button. 
+The `sbb-tooltip-trigger` component is used to trigger a [sbb-tooltip](/docs/components-sbb-tooltip-sbb-tooltip--docs) 
+by pressing or hovering on it. 
 
 ```html
 <sbb-tooltip-trigger id="tooltip-trigger"></sbb-tooltip-trigger>

src/components/sbb-tooltip/readme.md

@@ -1,9 +1,15 @@
-The `sbb-tooltip` component can be useful for displaying additional information on mouse hover or click of a trigger element. 
-The information included should be contextual, useful, and provide additional communication and clarity to the user.
+The `sbb-tooltip` component can be useful for displaying contextual and additional information on mouse hover or click of a trigger element. 
+
+The component could be used:
+
+- to describe icons and buttons;
+- when more information is useful to help a user make decisions;
+- when an element needs more context or explanation;
+- when defining a term or inline item.
 
 The component must be connected with the trigger element using the `trigger` property,
 which accepts the id of the element, or directly its reference;
-the `sbb-tooltip-trigger` is meant to be used as trigger.
+the [sbb-tooltip-trigger](/docs/components-sbb-tooltip-sbb-tooltip-trigger--docs) is meant to be used as trigger.
 
 ```html
 <sbb-tooltip-trigger id="tooltip-trigger"></sbb-tooltip-trigger>
@@ -13,8 +19,11 @@ the `sbb-tooltip-trigger` is meant to be used as trigger.
 </sbb-tooltip>
 ```
 
+### Interaction
+
 The `sbb-tooltip` can be dismissed by clicking on an interactive element within its content, 
 by clicking on the close button or by performing another action on the page.
+
 You can also indicate that an element within the tooltip content should close the `sbb-tooltip` when clicked 
 by marking it with the `sbb-tooltip-close` attribute; 
 it's also possible to hide the default close button using the `hideCloseButton` property.
@@ -32,6 +41,7 @@ it's also possible to hide the default close button using the `hideCloseButton`
 You can also indicate that the `sbb-tooltip` should be shown on hover with the property `hoverTrigger`
 and set a custom delay for the open and close animations (defaults to 0). 
 In this case, the default close button is hidden.
+
 If hover is not supported by the current device, the component will be triggered on click/tap as default.
 The `sbb-tooltip` will automatically disappear after the hiding delay 
 if neither the trigger element nor the tooltip are on hover or if another action is performed on the page.
@@ -52,17 +62,13 @@ The `sbb-tooltip` automatically calculates where it should place itself, based o
 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-tooltip-z-index`.
 
-### When to use
-
-- Describe icons and buttons.
-- When more information is useful to help a user make decisions.
-- When an element needs more context or explanation.
-- When defining a term or inline item.
-
 ## Accessibility
 
+As the tooltip opens, the focus will automatically be set to the first focusable item within the component.
+
 To make screen-readers announce the tooltip content when the trigger is focused, 
 associate the trigger with the `sbb-tooltip` via `aria-describedby` and `id` as shown below. 
+
 If the tooltip trigger is a `sbb-tooltip-trigger` component, set `role="button"` on it, 
 since the `aria-describedby` attribute can be used with semantic HTML elements and with elements 
 that have an ARIA `role`.
@@ -89,8 +95,6 @@ that have an ARIA `role`.
 </sbb-tooltip>
 ```
 
-As the tooltip opens, the focus will automatically be set to the first focusable item within the component.
-
 <!-- Auto Generated Below -->