@porsche-design-system/components-angular 4.5.0 → 4.6.0-rc.1

package/skills/pds-knowledge-angular/references/components/p-button-pure/accessibility.md

@@ -0,0 +1,61 @@
+# p-button-pure accessibility integration examples
+
+## Integration examples
+
+### ARIA on component host vs aria prop
+
+#### ❌ Anti-pattern
+
+```html
+<p-button-pure aria-haspopup="dialog" aria-label="Open details of product XYZ">
+  Open details
+</p-button-pure>
+```
+
+#### ✅ Recommended
+
+```html
+<p-button-pure [aria]="{'aria-haspopup': 'dialog', 'aria-label': 'Open details of product XYZ'}">
+  Open details
+</p-button-pure>
+```
+
+### Icon-only button without accessible name
+
+#### ❌ Anti-pattern
+
+```html
+<p-button-pure icon="plus"></p-button-pure>
+```
+
+#### ✅ Recommended
+
+```html
+<p-button-pure icon="plus" [hideLabel]="true">
+  Add item XYZ to shopping cart
+</p-button-pure>
+```
+
+### Vague button label without context
+
+#### ❌ Anti-pattern
+
+```html
+<p-button-pure icon="plus">
+  Add
+</p-button-pure>
+```
+
+#### ✅ Recommended
+
+```html
+<p-button-pure icon="plus" [aria]="{'aria-label': 'Add item XYZ to shopping cart'}">
+  Add
+</p-button-pure>
+
+<!-- or use descriptive visible text -->
+
+<p-button-pure icon="plus">
+  Add item XYZ to cart
+</p-button-pure>
+```

package/skills/pds-knowledge-angular/references/components/p-button-pure/examples/CustomClickableArea.ts

@@ -0,0 +1,15 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-button-pure class="p-static-md">
+        Some label
+      </p-button-pure>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skills/pds-knowledge-angular/references/components/p-button-pure/examples/Default.ts

@@ -0,0 +1,15 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-button-pure>
+        Some label
+      </p-button-pure>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skills/pds-knowledge-angular/references/components/p-button-pure/examples/Form.ts

@@ -0,0 +1,26 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+    <form (submit)="handleSubmit($event)" class="flex gap-fluid-sm">
+      <p-button-pure name="option" value="A" type="submit">Button A</p-button-pure>
+      <p-button-pure name="option" value="B" type="submit">Button B</p-button-pure>
+    </form>
+
+    <p-text>Last submitted data: {{ lastSubmittedData }}</p-text>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule],
+})
+export class ExampleComponent {
+  lastSubmittedData: string = 'none';
+
+  handleSubmit(e: Event): void {
+    e.preventDefault();
+    const submitter = (e as SubmitEvent).submitter as HTMLButtonElement;
+    this.lastSubmittedData = submitter.name + '=' + submitter.value || 'none';
+  }
+}

package/skills/pds-knowledge-angular/references/components/p-button-pure/examples/FormAttribute.ts

@@ -0,0 +1,30 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+    <form (submit)="handleSubmit($event)" id="some-form">
+      <p-textarea name="some-name" label="Some Label"></p-textarea>
+    </form>
+    
+    <div class="flex gap-fluid-sm mt-fluid-sm">
+      <p-button-pure type="submit" form="some-form">Submit</p-button-pure>
+      <p-button-pure type="reset" form="some-form">Reset</p-button-pure>
+    </div>
+
+    <p-text>Last submitted data: {{ lastSubmittedData }}</p-text>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule],
+})
+export class ExampleComponent {
+  lastSubmittedData: string = 'none';
+
+  handleSubmit(e: Event): void {
+    e.preventDefault();
+    const formData = new FormData(e.target as HTMLFormElement);
+    this.lastSubmittedData = (formData.get('some-name') as string) || 'none';
+  }
+}

package/skills/pds-knowledge-angular/references/components/p-button-pure/p-button-pure.md

@@ -0,0 +1,122 @@
+# p-button-pure
+
+The `p-button-pure` component is essential to perform events for **interactions**. A Button can be used with or without a label, but it's recommended to keep the **label visible** for better **usability** whenever possible. When used without a label, it is mandatory for **accessibility** to provide a descriptive label text for screen readers.
+
+Whenever you want to provide navigational elements, stick to the [Link](../p-link/p-link.md) or [Link Pure](../p-link-pure/p-link-pure.md) component instead.
+
+Similarly to the `p-button`, the `p-button-pure` can be used as a submit button within a form for which a `name` and `value` prop can be passed. See the [Button Form Example](../p-button/p-button.md) for more information.
+
+You can use native `click`, `focus`, `focusin`, `blur` and `focusout` events on the `p-button-pure`.
+
+## Usage
+
+### Do:
+
+- Use Button Pure as a more subtle call to action or to execute an action.
+- Choose the appropriate variant for your use case, such as Icon and Text or Text only.
+- Use Icon left as the default state and stretch only on small viewports or areas.
+- Keep the label short and include active verbs to indicate the action.
+- Stack Button Pure groups left-aligned to guarantee scannability and legibility.
+
+### Don't:
+
+- Don't use Button Pure as the primary or only call to action.
+- Don't use long labels that do not give a clear indication of the action.
+- Don't use buttons to link/navigate to other pages. Use regular [Link](../p-link/p-link.md) instead.
+
+## Accessibility support
+
+### Keyboard
+
+| Key / state | Function |
+| --- | --- |
+| `Tab`, `Shift-Tab` | Moves focus to the next (or previous) focusable element. |
+| `Enter`, `Space` | Activates the button. |
+| `disabled` | Button still focusable. |
+
+### ARIA enhancements
+
+#### External **ARIA** provided by the `aria` property:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-label` | Defines a string value that labels the interactive element. |
+| `aria-description` | Defines a string value that adds a more detailed description of the interactive element. |
+| `aria-expanded` | Exposes a visual state (e.g. expanded/collapsed) of another element. |
+| `aria-pressed` | Exposes the `pressed` state of a toggle button. |
+| `aria-haspopup` | Defines that the button opens a popup (e.g. `dialog`). It can be used in combination with `aria-expanded` to indicate the state of the popup. |
+
+#### Internal **ARIA** that is managed by the component:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-disabled="true"` | When `disabled` prop is set, this ARIA attribute is set on the button element. |
+| `role="status"` | When `loading` prop is set, the component announces the loading state (start and finish). |
+| `aria-hidden="true"` | When the `icon` prop is set, the icon is hidden from the screen reader. |
+
+## Limitations
+
+Due to the nature of **Web Components** and **shadow DOM**, there are limitations when using some **ARIA** attributes to define relationships between elements across different shadow DOMs or shadow DOM/light DOM combinations.
+
+| ARIA | Support |
+| --- | --- |
+| `aria-labelledby` | 🚫 |
+| `aria-describedby` | 🚫 |
+| `aria-owns` | 🚫 |
+| `aria-controls` | 🚫 |
+| `aria-activedescendant` | 🚫 |
+
+## Development considerations
+
+### Labelling
+
+If the text of a button does not clearly indicate what the button's behavior is, add a brief, descriptive label using the `aria` property with the `aria-label` value to provide more context for screen reader users. Phrases like "Add," "Detail," or "Show" can be unclear when read out of context by a screen reader. In such instances, provide an alternative text that offers more detailed information, such as "Add item XYZ to shopping cart" or "Details of product XYZ."
+
+### Common do's and don'ts
+
+- **Do** pass ARIA attributes via the `aria` prop, for example `aria="{ 'aria-haspopup': 'dialog' }"` when opening a dialog.
+- **Do** provide a clear accessible name for icon-only actions via slotted label or `aria` property.
+- **Don't** add native `aria-*` attributes directly on the component host.
+- **Don't** rely on short generic button labels like "Show" or "Add" without context.
+
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `active` | `boolean` | `false` | Visually marks the button as the currently active or selected item, useful for navigation and toggle patterns. |
+| `alignLabel` | `'start'` `'end'`<br>`BreakpointCustomizable<ButtonPureAlignLabel>` | `'end'` | Sets the label position relative to the icon — `start` places it before, `end` places it after. Supports responsive breakpoint values. |
+| `aria` | `ButtonPureAriaAttribute` | `undefined` | Sets ARIA attributes on the button to improve accessibility for screen readers. |
+| `color` | `'primary'` `'contrast-higher'` `'contrast-high'` `'contrast-medium'` `'inherit'` | `'primary'` | Sets the foreground color of the button's icon and label text. |
+| `disabled` | `boolean` | `false` | Disables the button, preventing all interaction and blocking events. |
+| `form` | `string` | `undefined` | Associates the button with a form element by its ID, so it can submit or reset that form even when placed outside of it. |
+| `hideLabel` | `boolean`<br>`BreakpointCustomizable<boolean>` | `false` | Hides the visible label while keeping it accessible to screen readers. Supports responsive breakpoint values. |
+| `icon` | `''`<br>one of 290 icon names — see [icon names](references/icons.md) | `'arrow-right'` | Sets the icon displayed next to the label. |
+| `iconSource` | `string` | `undefined` | Sets a path to a custom SVG icon, used instead of the built-in icon set. |
+| `loading` | `boolean` | `false` | Disables the button and replaces its icon with a loading spinner to indicate an ongoing operation. |
+| `name` | `string` | `undefined` | Sets the name submitted with the form data when this button triggers form submission. |
+| `size` | `'2xs'` `'xs'` `'sm'` `'md'` `'lg'` `'xl'` `'2xl'` `'3xl'` `'4xl'` `'5xl'` `'inherit'`<br>_deprecated:_ `'xx-small'` `'x-small'` `'small'` `'medium'` `'large'` `'x-large'`<br>`BreakpointCustomizable<ButtonPureSize>` | `'sm'` | Sets the font size of the button label. Supports responsive breakpoint values. |
+| `stretch` | `boolean`<br>`BreakpointCustomizable<boolean>` | `false` | Expands the space between icon and label to fill the full container width. Supports responsive breakpoint values. |
+| `type` | `'button'` `'submit'` `'reset'` | `'submit'` | Sets the button's HTML type — `submit` sends the form, `reset` clears it, `button` performs no default action. |
+| `underline` | `boolean` | `false` | Adds a text underline to the label to reinforce the button's link-like appearance. |
+| `value` | `string` | `undefined` | Sets the value submitted with the form data when this button triggers form submission, paired with `name`. |
+
+### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| _(default)_ | no | — | Default slot for the button label. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.ts](./examples/Default.ts) |
+| Button Pure with custom clickable/focusable area | Sometimes it might be useful to enlarge the clickable/focusable area of a button to fulfill accessibility guidelines. | [./examples/CustomClickableArea.ts](./examples/CustomClickableArea.ts) |
+| Form | When used as a submit button, the `name` and `value` props are submitted as a pair as part of the form data. | [./examples/Form.ts](./examples/Form.ts) |
+| Form Attribute | When a button is used as a submit or reset button outside a form, the `form` attribute can be utilized to explicitly associate the button with a specific form element. | [./examples/FormAttribute.ts](./examples/FormAttribute.ts) |

package/skills/pds-knowledge-angular/references/components/p-button-tile/accessibility.md

@@ -0,0 +1,31 @@
+# p-button-tile accessibility integration examples
+
+## Integration examples
+
+### ARIA on component host vs aria prop
+
+#### ❌ Anti-pattern
+
+```html
+<p-button-tile label="Open" aria-label="Open details of Porsche Taycan" aria-haspopup="dialog"></p-button-tile>
+```
+
+#### ✅ Recommended
+
+```html
+<p-button-tile label="Open" [aria]="{'aria-haspopup': 'dialog', 'aria-label': 'Open details of Porsche Taycan'}"></p-button-tile>
+```
+
+### Vague tile label without context
+
+#### ❌ Anti-pattern
+
+```html
+<p-button-tile label="Open"></p-button-tile>
+```
+
+#### ✅ Recommended
+
+```html
+<p-button-tile label="Configure Porsche Taycan"></p-button-tile>
+```

package/skills/pds-knowledge-angular/references/components/p-button-tile/examples/ColorScheme.ts

@@ -0,0 +1,18 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-button-tile label="Some label" description="Some Description" [gradient]="true">
+        <p-tag slot="header" color="background-frosted" [compact]="true" [style]="{'colorScheme': 'only light'}">
+          Some tag
+        </p-tag>
+        <img src="assets/lights.jpg" alt="Some image description" />
+      </p-button-tile>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skills/pds-knowledge-angular/references/components/p-button-tile/examples/Default.ts

@@ -0,0 +1,21 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-button-tile label="Some label" description="Some Description" [gradient]="true">
+        <p-tag slot="header" color="background-frosted" [compact]="true">
+          Some tag
+        </p-tag>
+        <img src="assets/lights.jpg" alt="Some image description" />
+        <p-text slot="footer">
+          Some footer text
+        </p-text>
+      </p-button-tile>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skills/pds-knowledge-angular/references/components/p-button-tile/examples/FooterSlot.ts

@@ -0,0 +1,32 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <div class="grid grid-cols-2 gap-static-md">
+        <p-button-tile label="Some label" description="Some Description">
+          <p-tag slot="header" color="background-frosted" [compact]="true">
+            Some tag
+          </p-tag>
+          <img src="assets/lights.jpg" alt="Some image description" />
+          <p-text slot="footer">
+            Some footer text
+          </p-text>
+        </p-button-tile>
+        <p-button-tile label="Some label" description="Some Description" [compact]="true">
+          <p-tag slot="header" color="background-frosted" [compact]="true">
+            Some tag
+          </p-tag>
+          <img src="assets/lights.jpg" alt="Some image description" />
+          <p-text slot="footer">
+            Some footer text
+          </p-text>
+        </p-button-tile>
+      </div>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skills/pds-knowledge-angular/references/components/p-button-tile/examples/Hyphens.ts

@@ -0,0 +1,38 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import {
+  PorscheDesignSystemModule,
+  PSelect,
+  type SelectChangeEventDetail,
+} from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+    <p-select name="hyphens" label="Select hyphens" [value]="selectedValue" (change)="onChange($event)">
+      <p-select-option value="auto">style="hyphens: auto;"</p-select-option>
+      <p-select-option value="manual">style="hyphens: manual;"</p-select-option>
+      <p-select-option value="none">style="hyphens: none;"</p-select-option>
+    </p-select>
+
+    <p-button-tile
+      label="Some label"
+      description="An extra&shy;ordinarily Porsche"
+      [compact]="true"
+      size="inherit"
+      [style]="{ maxWidth: '400px', fontSize: '45px', hyphens: selectedValue }"
+      class="mt-fluid-sm"
+    >
+      <img src="assets/lights.jpg" alt="Some image description" />
+    </p-button-tile>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule],
+})
+export class ExampleComponent {
+  selectedValue: PSelect['value'] = 'auto';
+
+  onChange(e: CustomEvent<SelectChangeEventDetail>) {
+    this.selectedValue = e.detail.value;
+  }
+}

package/skills/pds-knowledge-angular/references/components/p-button-tile/examples/UiBehaviour.ts

@@ -0,0 +1,44 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <div class="grid grid-cols-2 gap-static-md">
+        <p-button-tile aspectRatio="4/3" label="Some Label" description="Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum." size="large">
+          <p-tag slot="header" color="background-frosted" compact="true">
+            4/3
+          </p-tag>
+          <img src="assets/lights.jpg" alt="Some image description" />
+        </p-button-tile>
+        <p-button-tile aspectRatio="4/3" label="Some Label" description="Some description">
+          <p-tag slot="header" color="background-frosted" compact="true">
+            4/3
+          </p-tag>
+          <img src="assets/lights.jpg" alt="Some image description" />
+        </p-button-tile>
+        <p-button-tile aspectRatio="1/1" label="Some Label" description="Some description">
+          <p-tag slot="header" color="background-frosted" compact="true">
+            1/1
+          </p-tag>
+          <img src="assets/lights.jpg" alt="Some image description" />
+        </p-button-tile>
+        <p-button-tile aspectRatio="9/16" label="Some Label" description="Some description">
+          <p-tag slot="header" color="background-frosted" compact="true">
+            9/16
+          </p-tag>
+          <img src="assets/lights.jpg" alt="Some image description" />
+        </p-button-tile>
+        <p-button-tile aspectRatio="1/1" label="Some Label" description="Some description">
+          <p-tag slot="header" color="background-frosted" compact="true">
+            1/1
+          </p-tag>
+          <img src="assets/lights.jpg" alt="Some image description" />
+        </p-button-tile>
+      </div>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skills/pds-knowledge-angular/references/components/p-button-tile/p-button-tile.md

@@ -0,0 +1,119 @@
+# p-button-tile
+
+The `p-button-tile` is an interactive component that displays a provided image to tease content and performs form or **interaction** events within one container. Whenever you want to provide navigational elements, stick to the [Link Tile](../p-link-tile/p-link-tile.md) component instead.
+
+**Note:** The component does not take care of processing and aligning the image.
+
+An `<img/>`, `<picture/>` or `<video/>` tag has to be provided as default slot.
+
+Additionally, the properties `description` and `label` are required. The `description` property is used as a teaser with a more detailed description of the button and its action.
+
+The `label` property is used to describe the button.
+
+## Usage
+
+### Do:
+
+- Use Button Tile for **on-page interactivity**.
+- Use [Link Tile](../p-link-tile/p-link-tile.md) instead if you want to **navigate** to another page.
+- Use Button Tile with appropriate aspect ratios and short descriptions (80 characters or fewer).
+- Use basic Button Tile for better perception tests and compact Button Tile for improved spacing (especially on mobile).
+- Use gradient Button Tile when image contrast is insufficient and select images with natural contrast.
+- Use font size for visual hierarchy and customize image type and font size for responsiveness.
+- Use engaging verbs and product names in compact Button Tile.
+- Create assets upfront for image processing.
+
+### Don't:
+
+- Don't manipulate images, keep them natural and contrasted.
+- Don't write long descriptions that overflow content (especially on mobile).
+
+## Accessibility support
+
+### Keyboard
+
+| Key / state | Function |
+| --- | --- |
+| `Tab`, `Shift-Tab` | Moves focus to the next (or previous) focusable element. |
+| `Enter`, `Space` | Activates the button. |
+| `disabled` | Button still focusable. |
+
+### ARIA enhancements
+
+#### External **ARIA** provided by the `aria` property:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-label` | Defines a string value that labels an interactive element. It's required for buttons with `hideLabel="true"`. |
+| `aria-description` | Defines a string value that adds a more detailed description of the interactive element. |
+| `aria-expanded` | Exposes a visual state (e.g. expanded/collapsed) of another element. |
+| `aria-pressed` | Exposes the `pressed` state of a toggle button. |
+| `aria-haspopup` | Defines that the button opens a popup (e.g. `dialog`). It can be used in combination with `aria-expanded` to indicate the state of the popup. |
+
+## Limitations
+
+Due to the nature of **Web Components** and **shadow DOM**, there are limitations when using some **ARIA** attributes to define relationships between elements across different shadow DOMs or shadow DOM/light DOM combinations.
+
+| ARIA | Support |
+| --- | --- |
+| `aria-labelledby` | 🚫 |
+| `aria-describedby` | 🚫 |
+| `aria-owns` | 🚫 |
+| `aria-controls` | 🚫 |
+| `aria-activedescendant` | 🚫 |
+
+## Development considerations
+
+### Labelling
+
+If the text of the button does not clearly indicate what the button's function is, add a brief, descriptive label using the `aria` property with the `aria-label` value to provide more context for screen reader users. Phrases like "Detail" or "Open" can be unclear when read out of context by a screen reader. In such instances, provide an alternative text that offers more detailed information, such as "Open details of product XYZ."
+
+### Common do's and don'ts
+
+- **Do** pass ARIA attributes via the `aria` prop when the visible label needs more context.
+- **Do** provide a descriptive `label` that explains the tile action.
+- **Do** add `aria-label` on slotted `<video>` elements used as backgrounds.
+- **Don't** add native `aria-*` attributes directly on the component host.
+
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `align` | `'top'` `'bottom'` | `'bottom'` | Controls the vertical placement of the description and button — `top` or `bottom`. |
+| `aria` | `ButtonTileAriaAttribute` | `undefined` | Sets ARIA attributes on the tile's action button to improve accessibility for screen readers. |
+| `aspectRatio` | `'1/1'` `'4/3'` `'3/4'` `'16/9'` `'9/16'` `'auto'`<br>`BreakpointCustomizable<ButtonTileAspectRatio>` | `'4/3'` | Sets the width-to-height ratio of the tile media area. Supports responsive breakpoint values. |
+| `compact` | `boolean`<br>`BreakpointCustomizable<boolean>` | `false` | Renders only the icon button without the full label. Supports responsive breakpoint values. |
+| `description` _(required)_ | `string` | `undefined` | Sets the description text displayed in the tile's content area. |
+| `disabled` | `boolean` | `false` | Disables the tile, preventing button interaction. |
+| `gradient` | `boolean` | `false` | Shows a gradient overlay over the media slot to improve text legibility on bright images or videos. |
+| `icon` | `'none'`<br>one of 290 icon names — see [icon names](references/icons.md) | `'none'` | Sets the icon displayed in the tile's action button. Use `none` to show no icon. |
+| `iconSource` | `string` | `undefined` | Sets a path to a custom SVG icon for the action button, used instead of the built-in icon set. |
+| `label` _(required)_ | `string` | `undefined` | Sets the accessible label text of the action button rendered inside the tile. |
+| `loading` | `boolean` | `false` | Disables the tile and shows a loading spinner to indicate an ongoing operation. |
+| `size` | `'medium'` `'large'` `'inherit'`<br>`BreakpointCustomizable<ButtonTileSize>` | `'medium'` | Sets the font size of the description text in the tile content area. Supports responsive breakpoint values. |
+| `type` | `'button'` `'submit'` `'reset'` | `'submit'` | Sets the button's HTML type — `submit` sends the form, `reset` clears it, `button` performs no default action. |
+| `weight` | `'regular'` `'semi-bold'`<br>`BreakpointCustomizable<ButtonTileWeight>` | `'semi-bold'` | Sets the font weight of the description text in the tile content area. Supports responsive breakpoint values. |
+
+### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| `header` | no | — | Renders a header section above the content area. |
+| _(default)_ | no | — | Default slot for the img or picture tag. |
+| `footer` | no | — | Renders a footer section below the description. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.ts](./examples/Default.ts) |
+| UI behaviour | The component is able to break out of its aspect ratio in case content overflows to be accessibility compliant (see first row in example). | [./examples/UiBehaviour.ts](./examples/UiBehaviour.ts) |
+| Hyphens | It is possible to overwrite the hyphens style on the host element and use 'soft' hyphens. | [./examples/Hyphens.ts](./examples/Hyphens.ts) |
+| Footer slot | You can also use a `footer` slot to display additional text below the description, providing more flexibility for custom content. | [./examples/FooterSlot.ts](./examples/FooterSlot.ts) |
+| Color scheme | The component defines `color-scheme: dark` internally, independently of the scheme defined globally or on an ancestor outside the Button Tile. | [./examples/ColorScheme.ts](./examples/ColorScheme.ts) |