@porsche-design-system/components-react 4.5.0 → 4.6.0-rc.0

package/skill/references/components/p-button/p-button.md

@@ -0,0 +1,118 @@
+# p-button
+
+The `p-button` component is essential for performing form or **interaction** events. For an optimal user guidance and dedicated pursuit of business or sales goals, different types of Buttons (**Primary** and **Secondary**) are available for usage. 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) component instead.
+
+You can use native `click`, `focus`, `focusin`, `blur` and `focusout` events on the `p-button`.
+
+## Usage
+
+### Do:
+
+- Use buttons for actions that have clear consequences, such as submitting a form or initiating a purchase.
+- Use buttons to indicate the next step in a process, such as "Continue" or "Next".
+- Use buttons with clear and concise labels that accurately describe the action they perform.
+- Use the primary button for the most important or desired action, and use the secondary button for less important or secondary actions.
+- Use icons in buttons to enhance their meaning, but ensure the icon is relevant and easily recognizable.
+- Use disabled buttons to indicate actions that are currently unavailable or incomplete, and provide context for why the button is disabled.
+
+### Don't:
+
+- Don't use buttons for non-actionable elements, such as decorative graphics or text.
+- Don't use ambiguous or unclear labels for buttons, as it can lead to confusion for users.
+- Don't use too many buttons on a page or in a single section, as it can overwhelm users and reduce usability.
+- Don't use primary and secondary buttons interchangeably, as it can confuse users and reduce the clarity of your interface.
+- Don't use disabled buttons without providing context for why the button is disabled. This can lead to confusion and frustration for users.
+
+---
+
+## Related components
+
+- [Links](../p-link/p-link.md)
+
+## 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.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `aria` | `ButtonAriaAttribute` | `undefined` | Sets ARIA attributes on the button to improve accessibility for screen readers. |
+| `compact` | `boolean`<br>`BreakpointCustomizable<boolean>` | `false` | Reduces the button's height and padding for denser layouts. Supports responsive breakpoint values. |
+| `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` | `'none'`<br>one of 290 icon names — see [icon names](references/icons.md) | `'none'` | Sets the icon displayed inside the button. Use `none` to show no icon. |
+| `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 content 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. |
+| `type` | `'button'` `'submit'` `'reset'` | `'submit'` | Sets the button's HTML type — `submit` sends the form, `reset` clears it, `button` performs no default action. |
+| `value` | `string` | `undefined` | Sets the value submitted with the form data when this button triggers form submission, paired with `name`. |
+| `variant` | `'primary'` `'secondary'` | `'primary'` | Sets the visual style variant of the button (`primary` or `secondary`). |
+
+### 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.tsx](./examples/Default.tsx) |
+| 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.tsx](./examples/Form.tsx) |
+| 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.tsx](./examples/FormAttribute.tsx) |

package/skill/references/components/p-button-pure/examples/CustomClickableArea.tsx

@@ -0,0 +1,12 @@
+import React from 'react';
+import { PButtonPure } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PButtonPure className="p-static-md">
+        Some label
+      </PButtonPure>
+    </>
+  )
+}

package/skill/references/components/p-button-pure/examples/Default.tsx

@@ -0,0 +1,12 @@
+import React from 'react';
+import { PButtonPure } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PButtonPure>
+        Some label
+      </PButtonPure>
+    </>
+  )
+}

package/skill/references/components/p-button-pure/examples/Form.tsx

@@ -0,0 +1,28 @@
+import React from 'react';
+import { PButtonPure, PText } from '@porsche-design-system/components-react';
+import { type FormEvent, useState } from 'react';
+
+export const Example = () => {
+  const [lastSubmittedData, setLastSubmittedData] = useState('none');
+
+  const handleSubmit = (e: FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = Array.from(new FormData(e.currentTarget, (e.nativeEvent as SubmitEvent).submitter).entries())[0];
+    setLastSubmittedData(formData.join('=') || 'none');
+  };
+
+  return (
+    <>
+      <form onSubmit={handleSubmit} className="flex gap-fluid-sm">
+        <PButtonPure name="option" value="A" type="submit">
+          Button A
+        </PButtonPure>
+        <PButtonPure name="option" value="B" type="submit">
+          Button B
+        </PButtonPure>
+      </form>
+
+      <PText>Last submitted data: {lastSubmittedData}</PText>
+    </>
+  );
+};

package/skill/references/components/p-button-pure/examples/FormAttribute.tsx

@@ -0,0 +1,32 @@
+import React from 'react';
+import { PButtonPure, PText, PTextarea } from '@porsche-design-system/components-react';
+import { type FormEvent, useState } from 'react';
+
+export const Example = () => {
+  const [lastSubmittedData, setLastSubmittedData] = useState('none');
+
+  const handleSubmit = (e: FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    setLastSubmittedData((formData.get('some-name') as string) || 'none');
+  };
+
+  return (
+    <>
+      <form onSubmit={handleSubmit} id="some-form">
+        <PTextarea name="some-name" label="Some Label"></PTextarea>
+      </form>
+
+      <div className="flex gap-fluid-sm mt-fluid-sm">
+        <PButtonPure type="submit" form="some-form">
+          Submit
+        </PButtonPure>
+        <PButtonPure type="reset" form="some-form">
+          Reset
+        </PButtonPure>
+      </div>
+
+      <PText>Last submitted data: {lastSubmittedData}</PText>
+    </>
+  );
+};

package/skill/references/components/p-button-pure/p-button-pure.md

@@ -0,0 +1,118 @@
+# 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.
+
+## 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.tsx](./examples/Default.tsx) |
+| 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.tsx](./examples/CustomClickableArea.tsx) |
+| 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.tsx](./examples/Form.tsx) |
+| 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.tsx](./examples/FormAttribute.tsx) |

package/skill/references/components/p-button-tile/examples/ColorScheme.tsx

@@ -0,0 +1,15 @@
+import React from 'react';
+import { PButtonTile, PTag } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PButtonTile label="Some label" description="Some Description" gradient={true}>
+        <PTag slot="header" color="background-frosted" compact={true} style={{'colorScheme': 'only light'}}>
+          Some tag
+        </PTag>
+        <img src="assets/lights.jpg" alt="Some image description" />
+      </PButtonTile>
+    </>
+  )
+}

package/skill/references/components/p-button-tile/examples/Default.tsx

@@ -0,0 +1,18 @@
+import React from 'react';
+import { PButtonTile, PTag, PText } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PButtonTile label="Some label" description="Some Description" gradient={true}>
+        <PTag slot="header" color="background-frosted" compact={true}>
+          Some tag
+        </PTag>
+        <img src="assets/lights.jpg" alt="Some image description" />
+        <PText slot="footer">
+          Some footer text
+        </PText>
+      </PButtonTile>
+    </>
+  )
+}

package/skill/references/components/p-button-tile/examples/FooterSlot.tsx

@@ -0,0 +1,29 @@
+import React from 'react';
+import { PButtonTile, PTag, PText } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <div className="grid grid-cols-2 gap-static-md">
+        <PButtonTile label="Some label" description="Some Description">
+          <PTag slot="header" color="background-frosted" compact={true}>
+            Some tag
+          </PTag>
+          <img src="assets/lights.jpg" alt="Some image description" />
+          <PText slot="footer">
+            Some footer text
+          </PText>
+        </PButtonTile>
+        <PButtonTile label="Some label" description="Some Description" compact={true}>
+          <PTag slot="header" color="background-frosted" compact={true}>
+            Some tag
+          </PTag>
+          <img src="assets/lights.jpg" alt="Some image description" />
+          <PText slot="footer">
+            Some footer text
+          </PText>
+        </PButtonTile>
+      </div>
+    </>
+  )
+}

package/skill/references/components/p-button-tile/examples/Hyphens.tsx

@@ -0,0 +1,33 @@
+import React from 'react';
+import { PButtonTile, PSelect, PSelectOption, SelectChangeEventDetail } from '@porsche-design-system/components-react';
+import { Property } from 'csstype';
+import { useState } from 'react';
+
+export const Example = () => {
+  const [hyphens, setHyphens] = useState<Property.Hyphens>('auto');
+
+  const onChange = (e: CustomEvent<SelectChangeEventDetail>) => {
+    setHyphens(e.detail.value as Property.Hyphens);
+  };
+
+  return (
+    <>
+      <PSelect label="Select hyphens" name="hyphens" value={hyphens} onChange={onChange}>
+        <PSelectOption value="auto">style="hyphens: auto;"</PSelectOption>
+        <PSelectOption value="manual">style="hyphens: manual;"</PSelectOption>
+        <PSelectOption value="none">style="hyphens: none;"</PSelectOption>
+      </PSelect>
+
+      <PButtonTile
+        label="Some label"
+        description="An extra&shy;ordinarily Porsche"
+        compact={true}
+        size="inherit"
+        style={{ colorScheme: 'dark', maxWidth: '400px', fontSize: '45px', hyphens }}
+        className="mt-fluid-sm"
+      >
+        <img src="assets/lights.jpg" alt="Some image description" />
+      </PButtonTile>
+    </>
+  );
+};

package/skill/references/components/p-button-tile/examples/UiBehaviour.tsx

@@ -0,0 +1,41 @@
+import React from 'react';
+import { PButtonTile, PTag } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <div className="grid grid-cols-2 gap-static-md">
+        <PButtonTile 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">
+          <PTag slot="header" color="background-frosted" compact="true">
+            4/3
+          </PTag>
+          <img src="assets/lights.jpg" alt="Some image description" />
+        </PButtonTile>
+        <PButtonTile aspectRatio="4/3" label="Some Label" description="Some description">
+          <PTag slot="header" color="background-frosted" compact="true">
+            4/3
+          </PTag>
+          <img src="assets/lights.jpg" alt="Some image description" />
+        </PButtonTile>
+        <PButtonTile aspectRatio="1/1" label="Some Label" description="Some description">
+          <PTag slot="header" color="background-frosted" compact="true">
+            1/1
+          </PTag>
+          <img src="assets/lights.jpg" alt="Some image description" />
+        </PButtonTile>
+        <PButtonTile aspectRatio="9/16" label="Some Label" description="Some description">
+          <PTag slot="header" color="background-frosted" compact="true">
+            9/16
+          </PTag>
+          <img src="assets/lights.jpg" alt="Some image description" />
+        </PButtonTile>
+        <PButtonTile aspectRatio="1/1" label="Some Label" description="Some description">
+          <PTag slot="header" color="background-frosted" compact="true">
+            1/1
+          </PTag>
+          <img src="assets/lights.jpg" alt="Some image description" />
+        </PButtonTile>
+      </div>
+    </>
+  )
+}

package/skill/references/components/p-button-tile/p-button-tile.md

@@ -0,0 +1,115 @@
+# 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.
+
+## 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.tsx](./examples/Default.tsx) |
+| 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.tsx](./examples/UiBehaviour.tsx) |
+| Hyphens | It is possible to overwrite the hyphens style on the host element and use 'soft' hyphens. | [./examples/Hyphens.tsx](./examples/Hyphens.tsx) |
+| Footer slot | You can also use a `footer` slot to display additional text below the description, providing more flexibility for custom content. | [./examples/FooterSlot.tsx](./examples/FooterSlot.tsx) |
+| 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.tsx](./examples/ColorScheme.tsx) |

package/skill/references/components/p-canvas/examples/Default.tsx

@@ -0,0 +1,10 @@
+import React from 'react';
+import { PCanvas } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PCanvas></PCanvas>
+    </>
+  )
+}