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

package/skill/references/components/p-ai-tag/p-ai-tag.md

@@ -0,0 +1,47 @@
+# p-ai-tag
+
+`p-ai-tag` is used to indicate AI-generated or AI-modified content. It displays a localized and legally compliant AI label text (abbreviated or as long-form) combined with an icon.
+
+## Usage
+
+Use the AI tag to indicate that content has been generated or assisted by artificial intelligence.
+
+The following segment provides instructions for designers and developers regarding the appropriate utilization of this component in various situations.
+
+### Do:
+
+- Use to indicate AI-generated or AI-assisted content.
+- Use the appropriate `locale` to match the user's language.
+- Use the `abbreviation` variant for compact contexts where space is limited.
+- Use the `generated` or `modified` variant when a full label improves clarity.
+
+### Don't:
+
+- Don't use as a general-purpose tag — use `p-tag` instead.
+- Don't use for non-AI-related labeling or categorization.
+
+## Accessibility support
+
+For the `abbreviation` variant, the component uses an `<abbr>` element so the full “artificial intelligence” term is available as the expansion.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `locale` | `'bg_BG'` `'bs_BA'` `'cs_CZ'` `'da_DK'` `'de_DE'` `'el_GR'` `'en_CY'` `'en_GB'` `'en_US'` `'es_ES'` `'et_EE'` `'fi_FI'` `'fr_FR'` `'he_IL'` `'hr_HR'` `'hu_HU'` `'is_IS'` `'it_IT'` `'lt_LT'` `'lv_LV'` `'me_ME'` `'mk_MK'` `'mt_MT'` `'nb_NO'` `'nl_NL'` `'pl_PL'` `'pt_PT'` `'ro_RO'` `'ru_RU'` `'sk_SK'` `'sl_SI'` `'sr_RS'` `'sv_SE'` `'tr_TR'` `'uk_UA'` | `'en_US'` | Locale for the AI text (ISO format, e.g. "de_DE"). |
+| `variant` | `'abbreviation'` `'generated'` `'modified'` | `'generated'` | Variant to display: 'abbreviation' (e.g. "AI"), 'generated' (e.g. "AI-generated"), or 'modified' (e.g. "AI-modified"). |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.ts](./examples/Default.ts) |
+| Within Checkbox | The `p-ai-tag` can be used inline with other form components. | [./examples/WithinCheckbox.ts](./examples/WithinCheckbox.ts) |
+| Within Radio Group | The `p-ai-tag` can also be placed within the slotted label of a `p-radio-button-wrapper` to indicate AI-related content for individual radio options. | [./examples/WithinRadioGroup.ts](./examples/WithinRadioGroup.ts) |
+| Within Form Label | The `p-ai-tag` can be placed within a `label` of a `p-select` (or any other form component) to indicate AI-related content for selected options. | [./examples/WithinFormLabel.ts](./examples/WithinFormLabel.ts) |
+| Within Input Search | The `p-ai-tag` can be placed in the `end` slot of a `p-input-search` to indicate that the search results are AI-powered. | [./examples/WithinInputSearch.ts](./examples/WithinInputSearch.ts) |
+| Within Text | The `p-ai-tag` can be placed inline within a `p-text` to indicate that the surrounding text content is AI-related. | [./examples/WithinText.ts](./examples/WithinText.ts) |
+| Within Image | The `p-ai-tag` can be positioned as an overlay on images to indicate that the image content has been generated or modified by AI. | [./examples/WithinImage.ts](./examples/WithinImage.ts) |
+| Within Table | The `p-ai-tag` can sit inline in a `p-table-head-cell` next to the column title — for example on a **Status** column when that data is AI-assisted. | [./examples/WithinTable.ts](./examples/WithinTable.ts) |

package/skill/references/components/p-banner/examples/Customization.ts

@@ -0,0 +1,37 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-button type="button" (click)="onClick()">
+        Open Banner
+      </p-button>
+
+      <p-banner [open]="open" class="[--p-banner-top:8px] [--p-banner-bottom:8px] [--p-banner-inset-x:8px] [--p-banner-max-w:70ch]" (dismiss)="onDismiss()">
+        <p-heading slot="heading" size="sm" weight="semibold">
+          Some heading
+        </p-heading>
+        <p-text slot="description">
+          Some description. You can also add inline 
+          <p-link-pure href="https://porsche.com" icon="none" [underline]="true">
+            links
+          </p-link-pure>
+           to route to another page.
+        </p-text>
+      </p-banner>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {
+  open = false;
+
+  onClick() {
+    this.open = true;
+  }
+  onDismiss() {
+    this.open = false;
+  }
+}

package/skill/references/components/p-banner/examples/Default.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: `
+      <p-button type="button" (click)="onClick()">
+        Open Banner
+      </p-button>
+
+      <p-banner [open]="open" heading="Some Heading" headingTag="h3" description="Some Description" (dismiss)="onDismiss()"></p-banner>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {
+  open = false;
+
+  onClick() {
+    this.open = true;
+  }
+  onDismiss() {
+    this.open = false;
+  }
+}

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

@@ -0,0 +1,92 @@
+# 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.
+
+## 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.ts](./examples/Default.ts) |
+| Customization | Rich content for `heading` and `description` can be provided via named slots. | [./examples/Customization.ts](./examples/Customization.ts) |

package/skill/references/components/p-button/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>
+        Some label
+      </p-button>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skill/references/components/p-button/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 name="option" value="A" type="submit">Button A</p-button>
+      <p-button name="option" value="B" type="submit">Button B</p-button>
+    </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/skill/references/components/p-button/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 type="submit" form="some-form">Submit</p-button>
+      <p-button type="reset" form="some-form">Reset</p-button>
+    </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/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.ts](./examples/Default.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/skill/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/skill/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/skill/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/skill/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/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.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/skill/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/skill/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 {}