docs: describe css properties (#2460)

scripts/docs_generate.ts

@@ -128,7 +128,6 @@ const markdown: string = customElementsManifestToMarkdown(manifest, {
   omitDeclarations: ['exports'],
   omitSections: [
     'super-class',
-    'css-properties',
     'css-parts',
     'main-heading',
     'static-fields',

src/components/autocomplete/autocomplete.ts

@@ -37,6 +37,9 @@ let nextId = 0;
  * @event {CustomEvent<void>} didOpen - Emits whenever the `sbb-autocomplete` is opened.
  * @event {CustomEvent<void>} willClose - Emits whenever the `sbb-autocomplete` begins the closing transition. Can be canceled.
  * @event {CustomEvent<void>} didClose - Emits whenever the `sbb-autocomplete` is closed.
+ * @cssprop [--sbb-autocomplete-z-index=var(--sbb-overlay-z-index)] - To specify a custom stack order,
+ * the `z-index` can be overridden by defining this CSS variable. The default `z-index` of the
+ * component is set to `var(--sbb-overlay-z-index)` with a value of `1000`.
  */
 @hostAttributes({
   dir: getDocumentWritingMode(),

src/components/autocomplete/readme.md

@@ -121,6 +121,12 @@ using `aria-activedescendant` to support navigation though the autocomplete opti
 | `willClose` | `CustomEvent<void>` | Emits whenever the `sbb-autocomplete` begins the closing transition. Can be canceled. |                |
 | `didClose`  | `CustomEvent<void>` | Emits whenever the `sbb-autocomplete` is closed.                                      |                |
 
+## CSS Properties
+
+| Name                         | Default                      | Description                                                                                                                                                                                           |
+| ---------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--sbb-autocomplete-z-index` | `var(--sbb-overlay-z-index)` | To specify a custom stack order, the `z-index` can be overridden by defining this CSS variable. The default `z-index` of the component is set to `var(--sbb-overlay-z-index)` with a value of `1000`. |
+
 ## Slots
 
 | Name | Description                                                                                    |

src/components/container/sticky-bar/readme.md

@@ -27,6 +27,12 @@ Optionally the user can set the `color` property on the `sbb-sticky-bar` in orde
 | `color`            | `color`             | public  | `'white' \| 'milk' \| undefined` |         | Color of the container, like transparent, white etc. |
 | `disableAnimation` | `disable-animation` | public  | `boolean`                        | `false` | Whether the animation is enabled.                    |
 
+## CSS Properties
+
+| Name                             | Default                              | Description                      |
+| -------------------------------- | ------------------------------------ | -------------------------------- |
+| `--sbb-sticky-bar-padding-block` | `var(--sbb-spacing-responsive-xxxs)` | Block padding of the sticky bar. |
+
 ## Slots
 
 | Name | Description                                            |

src/components/container/sticky-bar/sticky-bar.ts

@@ -11,6 +11,7 @@ import style from './sticky-bar.scss?lit&inline';
  * A container that sticks to the bottom of the page if slotted into `sbb-container`.
  *
  * @slot - Use the unnamed slot to add content to the sticky bar.
+ * @cssprop [--sbb-sticky-bar-padding-block=var(--sbb-spacing-responsive-xxxs)] - Block padding of the sticky bar.
  */
 @hostAttributes({
   slot: 'sticky-bar',

src/components/dialog/dialog.ts

@@ -42,6 +42,9 @@ let nextId = 0;
  * @event {CustomEvent<void>} willClose - Emits whenever the `sbb-dialog` begins the closing transition. Can be canceled.
  * @event {CustomEvent<void>} didClose - Emits whenever the `sbb-dialog` is closed.
  * @event {CustomEvent<void>} requestBackAction - Emits whenever the back button is clicked.
+ * @cssprop [--sbb-dialog-z-index=var(--sbb-overlay-z-index)] - To specify a custom stack order,
+ * the `z-index` can be overridden by defining this CSS variable. The default `z-index` of the
+ * component is set to `var(--sbb-overlay-z-index)` with a value of `1000`.
  */
 @customElement('sbb-dialog')
 export class SbbDialogElement extends SbbNegativeMixin(LitElement) {

src/components/dialog/readme.md

@@ -74,9 +74,6 @@ You can also set the property `titleBackButton` to display the back button in th
 
 It's possible to display the component in `negative` variant using the self-named property.
 
-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-dialog-z-index`.
-
 <!-- Auto Generated Below -->
 
 ## Properties
@@ -110,6 +107,12 @@ The default `z-index` of the component is set to `1000`; to specify a custom sta
 | `didClose`          | `CustomEvent<void>` | Emits whenever the `sbb-dialog` is closed.                                      |                |
 | `requestBackAction` | `CustomEvent<void>` | Emits whenever the back button is clicked.                                      |                |
 
+## CSS Properties
+
+| Name                   | Default                      | Description                                                                                                                                                                                           |
+| ---------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--sbb-dialog-z-index` | `var(--sbb-overlay-z-index)` | To specify a custom stack order, the `z-index` can be overridden by defining this CSS variable. The default `z-index` of the component is set to `var(--sbb-overlay-z-index)` with a value of `1000`. |
+
 ## Slots
 
 | Name           | Description                                                  |

src/components/header/header/header.ts

@@ -16,6 +16,8 @@ const IS_MENU_OPENED_QUERY = "[aria-controls][aria-expanded='true']";
  *
  * @slot - Use the unnamed slot to add actions or content to the header.
  * @slot logo - Slot used to render the logo on the right side (sbb-logo as default).
+ * @cssprop [--sbb-header-z-index=10] - Can be used to modify the z-index of the header.
+ * @cssprop [--sbb-header-height=zero-small:var(--sbb-spacing-fixed-14x);medium-ultra:var(--sbb-spacing-fixed-24x)] - Can be used to modify height of the header.
  */
 @customElement('sbb-header')
 export class SbbHeaderElement extends SlotChildObserver(LitElement) {

src/components/header/header/readme.md

@@ -22,14 +22,10 @@ and it can contain a logo, which by default is the [sbb-logo](/docs/components-s
 
 Setting the `expanded` property will cause the `sbb-header` component to take up the full width of the page.
 
-The height of the header can be overridden by re-defining the css variable `--sbb-header-height`.
 To avoid that tabbed/focused elements get hidden behind the header,
 it's recommended to set on the `<html>` tag the CSS property `scroll-padding-top` to `var(--sbb-header-height)` or to a greater value.
 With this, it's ensured that content will be visible all the time.
 
-The default `z-index` of the component is set to `10`; to specify a custom stack order, the `z-index` can
-be changed by defining the CSS variable `--sbb-header-z-index`.
-
 ### Positioning and visibility
 
 By default, the `sbb-header` has a fixed position at the top of the page;
@@ -112,6 +108,13 @@ so they were wrapped into a `style` tag and added to the Storybook's configurati
 | `scrollOrigin` | `scroll-origin`  | public  | `string \| HTMLElement \| Document` |         | The element's id or the element on which the scroll listener is attached.                                            |
 | `hideOnScroll` | `hide-on-scroll` | public  | `boolean`                           | `false` | Whether the header should hide and show on scroll.                                                                   |
 
+## CSS Properties
+
+| Name                   | Default                                                                             | Description                                      |
+| ---------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------ |
+| `--sbb-header-z-index` | `10`                                                                                | Can be used to modify the z-index of the header. |
+| `--sbb-header-height`  | `zero-small:var(--sbb-spacing-fixed-14x);medium-ultra:var(--sbb-spacing-fixed-24x)` | Can be used to modify height of the header.      |
+
 ## Slots
 
 | Name   | Description                                                           |

src/components/icon/icon-base.ts

@@ -11,6 +11,10 @@ import { hostAttributes } from '../core/common-behaviors';
 import { getSvgContent } from './icon-request';
 import style from './icon.scss?lit&inline';
 
+/**
+ * @cssprop [--sbb-icon-svg-width=auto] - Can be used to set a custom width.
+ * @cssprop [--sbb-icon-svg-height=auto] - Can be used to set a custom height.
+ */
 @hostAttributes({
   'data-namespace': SbbIconBase._defaultNamespace,
   'data-empty': '',

src/components/icon/readme.md

@@ -35,3 +35,10 @@ In thinking about accessibility, it is useful to place icon use into one of thre
 | ------------ | ------------- | ------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `name`       | `name`        | public  | `string`  |         | The provided name consisting of the namespace and the name of the icon. If the namespace is missing, the default namespace "sbb" will be used. E.g. `name` (will use "sbb" as namespace) or `namespace:name`. |
 | `noSanitize` | `no-sanitize` | public  | `boolean` | `false` | When set to `true`, SVG content that is HTTP fetched will not be checked if the response SVG content has any `<script>` elements, or any attributes that start with `on`, such as `onclick`.                  |
+
+## CSS Properties
+
+| Name                    | Default | Description                         |
+| ----------------------- | ------- | ----------------------------------- |
+| `--sbb-icon-svg-width`  | `auto`  | Can be used to set a custom width.  |
+| `--sbb-icon-svg-height` | `auto`  | Can be used to set a custom height. |

src/components/logo/logo.ts

@@ -9,6 +9,8 @@ import style from './logo.scss?lit&inline';
 
 /**
  * It displays the SBB logo.
+ *
+ * @cssprop [--sbb-logo-height=auto] - Can be used to set the height of the logo.
  */
 @customElement('sbb-logo')
 export class SbbLogoElement extends SbbNegativeMixin(LitElement) {

src/components/logo/readme.md

@@ -34,3 +34,9 @@ Possible values are `ideal` (default), `minimal` and `none`.
 | `protectiveRoom`     | `protective-room`     | public  | `SbbProtectiveRoom \| undefined` | `'ideal'` | Visual protective room around logo.                          |
 | `accessibilityLabel` | `accessibility-label` | public  | `string`                         | `'Logo'`  | Accessibility label which will be forwarded to the SVG logo. |
 | `negative`           | `negative`            | public  | `boolean`                        | `false`   | Negative coloring variant flag.                              |
+
+## CSS Properties
+
+| Name                | Default | Description                                |
+| ------------------- | ------- | ------------------------------------------ |
+| `--sbb-logo-height` | `auto`  | Can be used to set the height of the logo. |

src/components/map-container/map-container.ts

@@ -17,6 +17,11 @@ import style from './map-container.scss?lit&inline';
  *
  * @slot - Use the unnamed slot to add content to the sidebar.
  * @slot map - Used for slotting the map.
+ * @cssprop [--sbb-map-container-margin-start=var(--sbb-header-height)] - The component
+ * comes along with a height calculation that subtracts the height of the header.
+ * For specific use cases, this variable can be used to modify the preset height.
+ * @cssprop [--sbb-map-container-sidebar-width=zero-large:400px;wide-ultra:480px] - Can be used
+ * to modify the width of the left sidebar.
  */
 @customElement('sbb-map-container')
 export class SbbMapContainerElement extends LitElement {

src/components/map-container/readme.md

@@ -14,11 +14,6 @@ It provides two slots: one unnamed slot for the sidebar content, and one named `
 On mobile, the map is sticky above the sidebar, and the sidebar content is scrolling over the map.
 On desktop, the sidebar and the map are shown in a two column layout side by side.
 
-## Style
-
-The component comes along with a height calculation that subtracts the height of the header.
-The header height can be overridden setting the variable `--sbb-map-container-margin-start`, if needed.
-
 <!-- Auto Generated Below -->
 
 ## Properties
@@ -27,6 +22,13 @@ The header height can be overridden setting the variable `--sbb-map-container-ma
 | -------------------- | ----------------------- | ------- | --------- | ------- | -------------------------------------------------------------------- |
 | `hideScrollUpButton` | `hide-scroll-up-button` | public  | `boolean` | `false` | Flag to show/hide the scroll up button inside the sidebar on mobile. |
 
+## CSS Properties
+
+| Name                                | Default                             | Description                                                                                                                                                                 |
+| ----------------------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--sbb-map-container-margin-start`  | `var(--sbb-header-height)`          | The component comes along with a height calculation that subtracts the height of the header. For specific use cases, this variable can be used to modify the preset height. |
+| `--sbb-map-container-sidebar-width` | `zero-large:400px;wide-ultra:480px` | Can be used to modify the width of the left sidebar.                                                                                                                        |
+
 ## Slots
 
 | Name  | Description                                         |

src/components/menu/menu-button/menu-button.ts

@@ -1,13 +1,15 @@
 import { customElement } from 'lit/decorators.js';
 
 import { SbbButtonBaseElement } from '../../core/common-behaviors';
-import { SbbMenuActionCommonElementMixin } from '../common/menu-action-common';
+import { SbbMenuActionCommonElementMixin } from '../common';
 
 /**
  * It displays a button element that can be used in the `sbb-menu` component.
  *
  * @slot - Use the unnamed slot to add content to the `sbb-menu-button`.
  * @slot icon - Use this slot to provide an icon. If `icon-name` is set, a `sbb-icon` will be used.
+ * @cssprop [--sbb-menu-action-outer-horizontal-padding=var(--sbb-spacing-fixed-3x)] - Can be used
+ * to modify horizontal padding.
  */
 @customElement('sbb-menu-button')
 export class SbbMenuButtonElement extends SbbMenuActionCommonElementMixin(SbbButtonBaseElement) {}

src/components/menu/menu-button/readme.md

@@ -26,11 +26,6 @@ accepting its associated properties (`type`, `name`, `value` and `form`).
 <sbb-menu-button value="menu" name="menu">Button</sbb-menu-button>
 ```
 
-## Style
-
-For cases where smaller outer paddings are needed,
-you can set the css variable `--sbb-menu-action-outer-horizontal-padding` to your desired outer padding.
-
 <!-- Auto Generated Below -->
 
 ## Properties
@@ -45,6 +40,12 @@ you can set the css variable `--sbb-menu-action-outer-horizontal-padding` to you
 | `value`    | `value`     | public  | `string \| undefined` |            | The value attribute to use for the button.                                                                                       |
 | `form`     | `form`      | public  | `string \| undefined` |            | The <form> element to associate the button with.                                                                                 |
 
+## CSS Properties
+
+| Name                                         | Default                       | Description                               |
+| -------------------------------------------- | ----------------------------- | ----------------------------------------- |
+| `--sbb-menu-action-outer-horizontal-padding` | `var(--sbb-spacing-fixed-3x)` | Can be used to modify horizontal padding. |
+
 ## Slots
 
 | Name   | Description                                                                         |

src/components/menu/menu-link/menu-link.ts

@@ -8,6 +8,8 @@ import { SbbMenuActionCommonElementMixin } from '../common/menu-action-common';
  *
  * @slot - Use the unnamed slot to add content to the `sbb-menu-link`.
  * @slot icon - Use this slot to provide an icon. If `icon-name` is set, a `sbb-icon` will be used.
+ * @cssprop [--sbb-menu-action-outer-horizontal-padding=var(--sbb-spacing-fixed-3x)] - Can be used
+ * to modify horizontal padding.
  */
 @customElement('sbb-menu-link')
 export class SbbMenuLinkElement extends SbbMenuActionCommonElementMixin(SbbLinkBaseElement) {}

src/components/menu/menu-link/readme.md

@@ -26,11 +26,6 @@ accepting its associated properties (`href`, `target`, `rel` and `download`).
 <sbb-menu-link href="#info" target="_blank">Link</sbb-menu-link>
 ```
 
-## Style
-
-For cases where smaller outer paddings are needed,
-you can set the css variable `--sbb-menu-action-outer-horizontal-padding` to your desired outer padding.
-
 <!-- Auto Generated Below -->
 
 ## Properties
@@ -45,6 +40,12 @@ you can set the css variable `--sbb-menu-action-outer-horizontal-padding` to you
 | `rel`      | `rel`       | public  | `string \| undefined`                   |         | The relationship of the linked URL as space-separated link types.                                                                |
 | `download` | `download`  | public  | `boolean \| undefined`                  |         | Whether the browser will show the download dialog on click.                                                                      |
 
+## CSS Properties
+
+| Name                                         | Default                       | Description                               |
+| -------------------------------------------- | ----------------------------- | ----------------------------------------- |
+| `--sbb-menu-action-outer-horizontal-padding` | `var(--sbb-spacing-fixed-3x)` | Can be used to modify horizontal padding. |
+
 ## Slots
 
 | Name   | Description                                                                         |

src/components/menu/menu/menu.ts

@@ -54,6 +54,9 @@ let nextId = 0;
  * @event {CustomEvent<void>} didOpen - Emits whenever the `sbb-menu` is opened.
  * @event {CustomEvent<void>} willClose - Emits whenever the `sbb-menu` begins the closing transition. Can be canceled.
  * @event {CustomEvent<void>} didClose - Emits whenever the `sbb-menu` is closed.
+ * @cssprop [--sbb-menu-z-index=var(--sbb-overlay-z-index)] - To specify a custom stack order,
+ * the `z-index` can be overridden by defining this CSS variable. The default `z-index` of the
+ * component is set to `var(--sbb-overlay-z-index)` with a value of `1000`.
  */
 @customElement('sbb-menu')
 export class SbbMenuElement extends SbbNamedSlotListElementMixin<