docs: change boilerplate, adapt files

convenience/generate-component/boilerplate/readme.md

@@ -1,11 +1,45 @@
-To be documented...
+> Explain the use and the purpose of the component, add minor details if needed, and provide a basic example.<br>
+> If you reference other components, link at least once their documentation page (the path must start from "/docs/...").<br>
+> Use triple backticks for the examples code block.
 
-### Prop, event, method, accessibility...
-
-Brief description
+The `__name__` is a component...
 
 ```html
 <__name__></__name__>
 ```
 
+> The following list of "## Paragraph" is only suggested; remove, create and adapt based on needs.
+
+## Slots
+
+> Describe slot naming and usage and provide an example of slotted content.
+
+## States
+
+> Describe the component states (`disabled`, `readonly`, etc.) and provide an example.
+
+## Style
+
+> Describe the properties which change the component visualization (`size`, `negative`, etc.) and provide an example.
+
+## Interactions
+
+> Describe how it's possible to interact with the component (open and close a `sbb-dialog`, dismiss a `sbb-alert`, etc.) and provide an example.
+
+## Events
+
+> Describe events triggered by the component and possibly how to get information from the payload.
+
+## Keyboard interaction
+
+> If the component has logic for keyboard navigation (as the `sbb-calendar` or the `sbb-select`) describe it.
+
+| Keyboard       | Action        |
+|----------------|---------------|
+| <kbd>Key</kbd> | What it does. |
+
+## Accessibility
+
+> Describe how accessibility is implemented and if there are issues or suggested best-practice for the consumers.
+
 <!-- Auto Generated Below -->

src/components/sbb-accordion/readme.md

@@ -14,7 +14,7 @@ for one or more [sbb-expansion-panel](/docs/components-sbb-accordion-sbb-expansi
 </sbb-accordion>
 ```
 
-### Variants
+## Variants
 
 The `multi` property, if set, allows having more than one `sbb-expansion-panel` expanded at the same time.
 
@@ -24,7 +24,7 @@ The `multi` property, if set, allows having more than one `sbb-expansion-panel`
 </sbb-accordion>
 ```
 
-### Style
+## Style
 
 The component has a `titleLevel` property, which is proxied to each inner `sbb-expansion-panel-header`, and can be used
 to wrap the header of each `sbb-expansion-panel` in a heading tag; if the property is unset, a `div` is used.

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

@@ -2,9 +2,9 @@ The `sbb-action-group` component is a generic content container which can contai
 ([sbb-button](/docs/components-sbb-button--docs) or [sbb-link](/docs/components-sbb-link--docs) or other HTML elements) 
 in various [allocations](#allocations).
 
-### Style
+## Style
 
-#### Orientation
+### Orientation
 
 The `orientation` property is used to set item's orientation. 
 Possible values are `horizontal` (default) and `vertical`.
@@ -26,7 +26,7 @@ indicate the minimum breakpoint from which the orientation changes to `horizonta
 </sbb-action-group>
 ```
 
-#### Button-size and link-size
+### Button-size and link-size
 
 The two props `button-size` and `link-size` can be used to override, respectively, the size of the inner `sbb-button` and `sbb-link`.
 Default values are `l` for `sbb-button` and `m` for `sbb-link`.
@@ -43,7 +43,7 @@ Default values are `l` for `sbb-button` and `m` for `sbb-link`.
 </sbb-action-group>
 ```
 
-#### Align-group and align-self
+### Align-group and align-self
 
 The `align-group` property can be used to set the default alignment of the contained elements; 
 possible values are `start`, `center`, `stretch` and `end`.
@@ -63,7 +63,7 @@ opposite direction to the group; possible values are `start`, `center` or `end`.
 </sbb-action-group>
 ```
 
-### Allocations
+## Allocations
 
 Items can be displayed inside `sbb-action-group` in different allocations.
 
@@ -82,7 +82,7 @@ and we consider a template like the following one (possibly removing the link fo
 
 The values for `align-group` and `align-self` for the various allocations are as follows:
 
-#### Horizontal
+### Horizontal
 
 | orientation='horizontal' | align-group |     align-self     |
 |:------------------------:|:-----------:|:------------------:|
@@ -93,7 +93,7 @@ The values for `align-group` and `align-self` for the various allocations are as
 |           2-0-0          |    start    |         /          |
 |           1-0-1          |    start    |  Button 2: 'end'   |
 
-#### Vertical
+### Vertical
 
 | orientation='vertical' | align-group | align-self |
 |:----------------------:|:-----------:|:----------:|

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

@@ -18,7 +18,7 @@ The `sbb-alert-group` manages the dismissal and accessibility of one or multiple
 </sbb-alert-group>
 ```
 
-### Interactions
+## Interactions
 
 If all the `sbb-alert`s are dismissed, it's recommended to completely remove the `sbb-alert-group` from DOM.
 

src/components/sbb-alert/readme.md

@@ -3,7 +3,7 @@ The `sbb-alert` is a component which should be used to display important message
 Multiple instances of this component can be used within 
 the [sbb-alert-group](/docs/components-sbb-alert-sbb-alert-group--docs) component.
 
-### Slots
+## Slots
 
 The text content is projected using and unnamed slot, while the title uses the slot named `title` or alternatively the `titleContent` property. 
 The component can optionally display a `sbb-icon` at the component start using the `iconName` property or via custom content using the `icon` slot.
@@ -24,7 +24,7 @@ The component can optionally display a `sbb-icon` at the component start using t
 </sbb-alert>
 ```
 
-### Interactions
+## Interactions
 
 It's possible to place an action, which by clicking navigates somewhere to display more information. 
 This can be done using the `linkContent` property combined with the `href` one. 
@@ -50,7 +50,7 @@ which automatically removes an alert after clicking the close button.
 </sbb-alert>
 ```
 
-### Style
+## Style
 
 Users can choose between two `size`, `m` (default) and `l`.
 

src/components/sbb-autocomplete/readme.md

@@ -18,7 +18,7 @@ Both accept an id or an element reference.
 </sbb-autocomplete>
 ```
 
-### In `sbb-form-field`
+## In `sbb-form-field`
 
 If the component is used within a [sbb-form-field](/docs/components-sbb-form-field-sbb-form-field--docs), 
 it will automatically connect to the native `<input>` as trigger and will display the option panel above or below the `sbb-form-field`.
@@ -38,14 +38,14 @@ it will automatically connect to the native `<input>` as trigger and will displa
 </sbb-form-field>
 ```
 
-### Style
+## Style
 
-#### Option highlight
+### Option highlight
 
 By default, the autocomplete will highlight the label of the `sbb-option` in the panel, if it matches the typed text.
 See the [sbb-option](/docs/components-sbb-option-sbb-option--docs) for more details.
 
-#### Option grouping
+### Option grouping
 
 The displayed `sbb-option` can be collected into groups using `sbb-optgroup` element:
 
@@ -68,11 +68,11 @@ The displayed `sbb-option` can be collected into groups using `sbb-optgroup` ele
 </sbb-form-field>
 ```
 
-### Events
+## Events
 
 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-breadcrumb-group/readme.md

@@ -13,7 +13,7 @@ which are meant to represent the hierarchy of visited pages before arriving to t
 </sbb-breadcrumb-group>
 ```
 
-### Style
+## Style
 
 If the width of all the nested `sbb-breadcrumb` exceeds the container width, 
 only the first and the last breadcrumb are displayed, and a new one with the ellipsis symbol appears between them. 

src/components/sbb-breadcrumb/readme.md

@@ -3,7 +3,7 @@ The `sbb-breadcrumb` is a component used to display a link to a page.
 When it's used within the [sbb-breadcrumb-group](/docs/components-sbb-breadcrumb-sbb-breadcrumb-group--docs) component, 
 it can display the list of the links the user visited to arrive at the current page.
 
-### Slots
+## Slots
 
 It is possible to provide a text 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.
@@ -20,7 +20,7 @@ Text and icon are not exclusive and can be used together.
 </sbb-breadcrumb>
 ```
 
-### Link properties
+## Link properties
 
 It's possible to set all the link related properties (`download`, `href`, `rel` and `target`).
 

src/components/sbb-button/readme.md

@@ -4,7 +4,7 @@ The `sbb-button` component provides the same functionality as a native `<button>
 <sbb-button>Button text</sbb-button>
 ```
 
-### Slots
+## Slots
 
 The button text is provided 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.
@@ -23,7 +23,7 @@ At least one is mandatory, so you can have a `sbb-button` with icon only, text o
 <sbb-button icon-name="info" aria-label='Click for more information.'></sbb-button>
 ```
 
-### Link / button properties
+## Link / button properties
 
 The component can be internally rendered as a button or as a link,
 depending on the value of the `href` property, so the associated properties are available
@@ -44,7 +44,7 @@ If the component is placed inside an `sbb-form-field`, it renders with the corre
 </sbb-button>
 ```
 
-### Style
+## Style
 
 The component has four color variants that can be set using the `variant` property (default: `primary`),
 and it has also a negative one which can be set using the `negative` property.
@@ -63,7 +63,7 @@ The component can be displayed in `disabled` state using the self-named property
 <sbb-button disabled>Button</sbb-button>
 ```
 
-#### Focus outline
+### Focus outline
 
 Please make sure that the focus outline appears in the correct color if the component is used on a dark background.
 You can set it by re-defining the css var on `sbb-button` or any parent element:

src/components/sbb-calendar/readme.md

@@ -20,7 +20,7 @@ It's recommended to set the time to 00:00:00.
 <sbb-calendar min="1600000000" max="1700000000" selected-date="1650000000"></sbb-calendar>
 ```
 
-### Style
+## Style
 
 The component displays one month by default; two months can be displayed setting the `wide` property to `true`.
 
@@ -31,12 +31,12 @@ The component displays one month by default; two months can be displayed setting
 It's also possible to filter out unwanted date using the `dateFilter` function property.
 Note that using the `dateFilter` function as a replacement for the `min` and `max` properties will most likely result in a significant loss of performance.
 
-### Events
+## Events
 
 Consumers can listen to the `dateSelected` event on the `sbb-calendar` component to intercept the selected date 
 which can be read from `event.detail`.
 
-### Keyboard interaction
+## Keyboard interaction
 
 It's possible to move within the component using the keyboard.
 

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

@@ -4,7 +4,7 @@ The `sbb-card-action` is the component used to turn a `sbb-card` into an action.
 <sbb-card-action href="https://www.sbb.ch">Check all the wonderful trips available.</sbb-card-action>
 ```
 
-### Link / button properties
+## Link / button properties
 
 As the [sbb-link](/docs/components-sbb-link--docs) and the [sbb-button](/docs/components-sbb-button--docs),
 the component can be internally rendered as a button or as a link,

src/components/sbb-card/readme.md

@@ -4,12 +4,12 @@ The `sbb-card` component is a generic content container; its task is to contain
 <sbb-card>Card content</sbb-card>
 ```
 
-### Slots
+## Slots
 
 The content is projected in an unnamed slot.
 It's possible to use the component together with the `sbb-card-badge` and the `sbb-card-action`.
 
-#### With `sbb-card-badge`
+### With `sbb-card-badge`
 
 The `sbb-card-badge` component can be used to display a badge in the upper right corner.
 The badge is hidden with card sizes are `xs` or `s`.
@@ -26,7 +26,7 @@ For API details, see the [sbb-card-badge](/docs/components-sbb-card-sbb-card-bad
 </sbb-card>
 ```
 
-#### With `sbb-card-action`
+### With `sbb-card-action`
 
 To add an action to a card, add a `sbb-card-action` to the main slot.
 With the `sbb-card-action` all the card area becomes clickable.
@@ -39,7 +39,7 @@ For API details (mainly accessibility), see the [sbb-card-action](/docs/componen
 </sbb-card>
 ```
 
-### Style
+## Style
 
 It's possible to choose among seven different values for the `size` property (from `xs` to `xxxl`, default `m`); 
 the choice mainly affect the content's padding. 

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

@@ -23,7 +23,7 @@ or, alternatively, for a collection of [sbb-selection-panel](/docs/components-sb
 </sbb-checkbox-group>
 ```
 
-### Slots
+## Slots
 
 The content is projected in an unnamed slot.
 
@@ -39,7 +39,7 @@ right below the `sbb-checkbox-group` using the `error` slot.
 </sbb-checkbox-group>
 ```
 
-### States
+## States
 
 It is possible to mark the entire group as disabled or required using the properties `disabled` and `required`.
 
@@ -55,7 +55,7 @@ It is possible to mark the entire group as disabled or required using the proper
 </sbb-checkbox-group>
 ```
 
-### Style
+## Style
 
 The `orientation` property is used to set item orientation. 
 Possible values are `horizontal` (default) and `vertical`.

src/components/sbb-checkbox/readme.md

@@ -1,6 +1,6 @@
 The `sbb-checkbox` component provides the same functionality as a native `<input type="checkbox"/>` enhanced with the SBB Design.
 
-### Slots
+## Slots
 
 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 SVG using the `icon` slot.
@@ -14,7 +14,7 @@ The icon can be placed before or after the label based on the value of the `icon
 <sbb-checkbox value="start-icon" icon-name="tickets-class-small" icon-placement="start">Icon at start</sbb-checkbox>
 ```
 
-### States
+## States
 
 The component could be checked or not depending on the value of the `checked` attribute.
 
@@ -39,15 +39,15 @@ The component can be displayed in `disabled` or `required` state by using the se
 <sbb-checkbox value="disabled-checkbox" disabled="true">Disabled</sbb-checkbox>
 ```
 
-### Style
+## Style
 
 The component has two `size`, named `s` (default) and `m`. 
 
 ```html
 <sbb-checkbox value="size" size='m'>Size</sbb-checkbox>
 ```
 
-### Events
+## Events
 
 Consumers can listen to the native `change` event on the `sbb-checkbox` component to intercept the input's change;
 the current state can be read from `event.target.checked`, while the value from `event.target.value`.