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

package/skills/pds-knowledge-react/references/components/p-banner/p-banner.md

@@ -0,0 +1,96 @@
+# p-banner
+
+The `p-banner` component provides action-based feedback messages (e.g. after performing a task) or to convey informational and/or critical notification like some site related topics.
+
+Review the [notification decision tree](https://designsystem.porsche.com/patterns/notifications/decision-tree) to determine which notification component is best for a particular scenario.
+
+For more information about the Usage of the `p-banner` checkout the [Notification](https://designsystem.porsche.com/patterns/notifications/introduction) page.
+
+## Accessibility support
+
+### Keyboard
+
+| Key / state | Function |
+| --- | --- |
+| `ESC` | Closes the Banner. |
+| `Tab`, `Shift-Tab` | Moves focus to the next focusable element. |
+| `focus` | Moves focus automatically to the close button. |
+
+### ARIA enhancements
+
+#### Internal **ARIA** that is managed by the component:
+
+| ARIA | Usage |
+| --- | --- |
+| `role="status"` | When content is populated or changed in `state="info"`, the component announces it unobtrusively. |
+| `role="alert"` | When content is populated or changed in `state="warning/error"`, the component announces it immediately. |
+| `aria-label="STRING"` | References the accessible name. |
+
+## Development considerations
+
+### Focus handling
+
+To support **keyboard navigation**, please take care of correct **focus handling** after closing the `Banner` with `ESC` or `Enter` key: The trigger element (e.g. a button) which has opened the `Banner` must receive focus state again after the `Banner` is closed. This is important to keep focus order consistent.
+
+### ARIA live announcements
+
+The `Banner` component uses `role="status"` and `role="alert"` to announce **content changes** for assistive technologies, but only if the component is **pre-rendered** and the content is added dynamically.
+
+### Common do's and don'ts
+
+- **Do** pre-render the banner in the DOM and update its content when showing feedback.
+- **Do** provide meaningful `heading` and `description` text for warnings and errors.
+- **Do** return focus to the trigger or at a logical place after the banner is dismissed.
+- **Don't** mount the entire banner only at the moment it should be announced.
+
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `description` | `string` | `''` | Sets the supporting description text shown below the heading. |
+| `dismissButton` | `boolean` | `true` | Shows a dismiss button so the user can manually close the banner. |
+| `heading` | `string` | `''` | Sets the heading text displayed at the top of the banner. |
+| `headingTag` | `'h1'` `'h2'` `'h3'` `'h4'` `'h5'` `'h6'` | `'h5'` | Sets the HTML heading tag (e.g. h2, h3) to maintain correct document structure for the heading. |
+| `open` _(required)_ | `boolean` | `false` | Controls whether the banner is visible. Set to `true` to show it and `false` to hide it. |
+| `position` | `'top'` `'bottom'`<br>`BreakpointCustomizable<BannerPosition>` | `{"base":"bottom","s":"top"}` | Sets the position of the banner on screen — `top` or `bottom`. Supports responsive breakpoint values. |
+| `state` | `'info'` `'success'` `'warning'` `'error'` | `'info'` | Sets the visual state of the banner — controls the icon and color scheme (`info`, `warning`, `error`, `success`). |
+
+### Events
+
+| Event | Type | Description |
+| --- | --- | --- |
+| `dismiss` | `CustomEvent<void>` | Emitted when the user closes the banner via the dismiss button or Escape key. |
+
+### Controlled properties
+
+- `open` — a controlled prop: the component does **not** update it itself. Handle the `dismiss` event and assign the new value to `open` yourself, or the change will not take effect.
+
+### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| `heading` | no | — | Defines the heading of the banner. Can be used as an alternative to the `heading` prop for rich content. |
+| _(default)_ | no | — | Default slot for the banner description content. |
+| `description` _(deprecated)_ | no | — | Deprecated: Use the default slot instead. |
+
+### CSS Variables
+
+| CSS Variable | Default | Description |
+| --- | --- | --- |
+| `--p-banner-max-w` | `100ch` | Defines the maximum width of the Banner. |
+| `--p-banner-top` | `56px` | Defines the distance from the top of the viewport. Only takes effect when the `position` property is set to `top` (at the respective breakpoint). |
+| `--p-banner-bottom` | `56px` | Defines the distance from the bottom of the viewport. Only takes effect when the `position` property is set to `bottom` (at the respective breakpoint). |
+| `--p-banner-inset-x` | `max(22px, 10.625vw - 12px)` | Defines the horizontal offset of the Banner from the edges of the viewport. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.tsx](./examples/Default.tsx) |
+| Customization | Rich content for `heading` and `description` can be provided via named slots. | [./examples/Customization.tsx](./examples/Customization.tsx) |

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

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

package/skills/pds-knowledge-react/references/components/p-button/examples/Default.tsx

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

package/skills/pds-knowledge-react/references/components/p-button/examples/Form.tsx

@@ -0,0 +1,28 @@
+import React from 'react';
+import { PButton, 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">
+        <PButton name="option" value="A" type="submit">
+          Button A
+        </PButton>
+        <PButton name="option" value="B" type="submit">
+          Button B
+        </PButton>
+      </form>
+
+      <PText>Last submitted data: {lastSubmittedData}</PText>
+    </>
+  );
+};

package/skills/pds-knowledge-react/references/components/p-button/examples/FormAttribute.tsx

@@ -0,0 +1,31 @@
+import React from 'react';
+import { PButton, 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">
+        <PButton type="submit" form="some-form">
+          Submit
+        </PButton>
+        <PButton type="reset" form="some-form">
+          Reset
+        </PButton>
+      </div>
+
+      <PText>Last submitted data: {lastSubmittedData}</PText>
+    </>
+  );
+};

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

@@ -0,0 +1,122 @@
+# 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.
+
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
+## 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/skills/pds-knowledge-react/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
+
+```tsx
+<PButtonPure aria-haspopup="dialog" aria-label="Open details of product XYZ">
+  Open details
+</PButtonPure>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PButtonPure aria={{'aria-haspopup': 'dialog', 'aria-label': 'Open details of product XYZ'}}>
+  Open details
+</PButtonPure>
+```
+
+### Icon-only button without accessible name
+
+#### ❌ Anti-pattern
+
+```tsx
+<PButtonPure icon="plus"></PButtonPure>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PButtonPure icon="plus" hideLabel={true}>
+  Add item XYZ to shopping cart
+</PButtonPure>
+```
+
+### Vague button label without context
+
+#### ❌ Anti-pattern
+
+```tsx
+<PButtonPure icon="plus">
+  Add
+</PButtonPure>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PButtonPure icon="plus" aria={{'aria-label': 'Add item XYZ to shopping cart'}}>
+  Add
+</PButtonPure>
+
+{/* or use descriptive visible text */}
+
+<PButtonPure icon="plus">
+  Add item XYZ to cart
+</PButtonPure>
+```

package/skills/pds-knowledge-react/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/skills/pds-knowledge-react/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/skills/pds-knowledge-react/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/skills/pds-knowledge-react/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/skills/pds-knowledge-react/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.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/skills/pds-knowledge-react/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
+
+```tsx
+<PButtonTile label="Open" aria-label="Open details of Porsche Taycan" aria-haspopup="dialog"></PButtonTile>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PButtonTile label="Open" aria={{'aria-haspopup': 'dialog', 'aria-label': 'Open details of Porsche Taycan'}}></PButtonTile>
+```
+
+### Vague tile label without context
+
+#### ❌ Anti-pattern
+
+```tsx
+<PButtonTile label="Open"></PButtonTile>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PButtonTile label="Configure Porsche Taycan"></PButtonTile>
+```