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

package/skill/references/components/p-link/examples/FrameworkRouting.tsx

@@ -0,0 +1,14 @@
+import React from 'react';
+import { PLink } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PLink>
+        <a href="https://porsche.com">
+          Some label
+        </a>
+      </PLink>
+    </>
+  )
+}

package/skill/references/components/p-link/examples/Icon.tsx

@@ -0,0 +1,17 @@
+import React from 'react';
+import { PLink } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <div className="flex gap-static-sm">
+        <PLink href="https://porsche.com" icon="phone">
+          Some label
+        </PLink>
+        <PLink href="https://porsche.com" iconSource="assets/icon-custom-kaixin.svg" hideLabel={true}>
+          Some label
+        </PLink>
+      </div>
+    </>
+  )
+}

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

@@ -0,0 +1,101 @@
+# p-link
+
+The `p-link` component is essential to perform changes in **page routes**. For an optimal user guidance and dedicated pursuit of business or sales goals, different types of Links (**Primary** and **Secondary**) are available for usage. A Link 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. In case you want the user to execute an action, you should select the [Button](../p-button/p-button.md) component instead.
+
+You can use native `click`, `focus`, `focusin`, `blur` and `focusout` events on the `p-link`.
+
+## Usage
+
+### Do:
+
+- Use a Link to navigate to another page.
+- Use a [Button](../p-button/p-button.md) instead of a Link if you want to change a state (e.g. send form)
+- Use a Primary Link filled for one or two high-priority actions within a page.
+- Use a Secondary Link for all other stand-alone Links that aren't high priority.
+- Use a [Link Pure](../p-link-pure/p-link-pure.md) as a subordinated link version in combination with a filled link (primary or secondary) or stand-alone when the priority of the action is lower compared to all other link actions within the page.
+- Use an Icon and text variant only when appropriate (e.g. external link).
+- Use an Icon-only variant only in cases where the user is fully aware of the link function.
+- Ensure that the link remains legible even in a multiline state by using max. 100 characters per line.
+
+### Don't:
+
+- Don't use a Primary Link for all links on a page.
+- Don't use a multiline Link, as it is recommended to keep the text label short and avoid multiline links.
+- Don't use a width that's too wide and makes the link difficult to read.
+
+---
+
+## Related components
+
+- [Button](../p-button/p-button.md)
+- [Link Pure](../p-link-pure/p-link-pure.md)
+
+## Accessibility support
+
+### Keyboard
+
+| Key / state | Function |
+| --- | --- |
+| `Tab`, `Shift-Tab` | Moves focus to the next (or previous) focusable element. |
+| `Enter` | Activates the link. |
+
+### 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-current` | Exposes the current state of the link. |
+| `aria-haspopup` | Defines that the link opens a popup (e.g. `dialog`). |
+
+#### Internal **ARIA** that is managed by the component:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-hidden="true"` | When the `icon` prop is set, the icon is hidden from the screen reader. |
+
+## Development considerations
+
+### Labelling
+
+If the text of a link does not clearly indicate what the link's target 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 "Click" 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 "Details of product XYZ."
+
+### Common do's and don'ts
+
+- **Do** pass ARIA attributes via the `aria` prop, for example `aria="{ 'aria-current': 'page' }"` when indicating the current page.
+- **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 link labels like "Show" or "Add" without context.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `aria` | `LinkAriaAttribute` | `undefined` | Sets ARIA attributes on the link element to improve accessibility for screen readers. |
+| `compact` | `boolean`<br>`BreakpointCustomizable<boolean>` | `false` | Reduces the link's padding and height for denser layouts. Supports responsive breakpoint values. |
+| `download` | `string` | `undefined` | Sets the native `download` attribute to trigger a file download. Only applies when `href` is set. |
+| `hideLabel` | `boolean`<br>`BreakpointCustomizable<boolean>` | `false` | Hides the visible label while keeping it accessible to screen readers. Supports responsive breakpoint values. |
+| `href` | `string` | `undefined` | When set, the component renders as an anchor navigating to this URL. Otherwise, provide a slotted anchor element. |
+| `icon` | `'none'`<br>one of 290 icon names — see [icon names](references/icons.md) | `'none'` | Sets the icon displayed next to the link label. 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. |
+| `rel` | `string` | `undefined` | Sets the `rel` attribute on the link (e.g. `noopener`). Only applies when `href` is set. |
+| `target` | `'_self'` `'_blank'` `'_parent'` `'_top'` `'string'` | `'_self'` | Specifies where to open the linked URL (e.g. `_self`, `_blank`). Only applies when `href` is set. |
+| `variant` | `'primary'` `'secondary'` | `'primary'` | Sets the visual style variant of the link (`primary` or `secondary`). |
+
+### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| _(default)_ | no | — | Default slot to render the link label. This slot can be used to slot an anchor tag instead of using the href prop. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.tsx](./examples/Default.tsx) |
+| Framework routing (anchor nesting) | To support custom anchor tags (e.g. framework specific routing) you can provide them as a **slotted element** of the component. | [./examples/FrameworkRouting.tsx](./examples/FrameworkRouting.tsx) |
+| Link with specific icon | If an icon needs to be implemented, just set another predefined icon. | [./examples/Icon.tsx](./examples/Icon.tsx) |

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

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

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

@@ -0,0 +1,12 @@
+import React from 'react';
+import { PLinkPure } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PLinkPure href="https://porsche.com">
+        Some label
+      </PLinkPure>
+    </>
+  )
+}

package/skill/references/components/p-link-pure/examples/FrameworkRouting.tsx

@@ -0,0 +1,14 @@
+import React from 'react';
+import { PLinkPure } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PLinkPure>
+        <a href="https://porsche.com">
+          Some label
+        </a>
+      </PLinkPure>
+    </>
+  )
+}

package/skill/references/components/p-link-pure/examples/Icon.tsx

@@ -0,0 +1,17 @@
+import React from 'react';
+import { PLinkPure } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <div className="flex gap-static-sm">
+        <PLinkPure href="https://porsche.com" icon="phone">
+          Some label
+        </PLinkPure>
+        <PLinkPure href="https://porsche.com" iconSource="assets/icon-custom-kaixin.svg" hideLabel={true}>
+          Some label
+        </PLinkPure>
+      </div>
+    </>
+  )
+}

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

@@ -0,0 +1,110 @@
+# p-link-pure
+
+The `p-link-pure` component is essential for performing changes in **page routes**. A Link Pure 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.
+
+In case you want the user to execute an action, you should select the [Button](../p-button/p-button.md) or [Button Pure](../p-button-pure/p-button-pure.md) component instead.
+
+You can use native `click`, `focus`, `focusin`, `blur` and `focusout` events on the `p-link-pure`.
+
+## Usage
+
+### Do:
+
+- Use a Link Pure as a more subtle call to action compared to the normal Link.
+- Use a [Button Pure](../p-button-pure/p-button-pure.md) instead of a Link Pure if you want to change a state (e.g. send form)
+- Use a Link Pure to navigate the user to another page.
+- Use the Icon and Text variant of Link Pure whenever possible as icons should preferably always be paired with text for better comprehensibility and accessibility.
+- Use the Text only variant when the use of icons causes interference (e.g. in-text placement, no matching icon, complex lists or tables, alignment to elements, navigation).
+- Use the Text only variant with an underline to ensure intuitive clickability.
+- Use the Icon only variant only when an icon alone is sufficient to indicate the action and the user is fully aware of the function due to an expressive and internationally comprehensible icon.
+- Use the stretch variant only on small viewports or areas (e.g. mobile views or sidebars).
+- Use the default arrow-right-icon in most cases but replace it with another symbol if it is more appropriate.
+- Use short and descriptive text labels within a link.
+
+### Don't:
+
+- Don't use Link Pure as the main call to action if you need to draw more attention to the link.
+- Don't use Link Pure on images unless it is necessary, e.g. when using it as an additional link on image sliders or teaser images that are clickable themselves.
+- Don't group more than two Links Pure in a row to ensure scannability and legibility.
+
+---
+
+## Related components
+
+- [Button Pure](../p-button-pure/p-button-pure.md)
+
+## Accessibility support
+
+### Keyboard
+
+| Key / state | Function |
+| --- | --- |
+| `Tab`, `Shift-Tab` | Moves focus to the next (or previous) focusable element. |
+| `Enter` | Activates the link. |
+
+### 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-current` | Exposes the current state of the link. |
+| `aria-haspopup` | Defines that the link opens a popup (e.g. `dialog`). |
+
+#### Internal **ARIA** that is managed by the component:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-hidden="true"` | When the `icon` prop is set, the icon is hidden from the screen reader. |
+
+## Development considerations
+
+### Labelling
+
+If the text of a link does not clearly indicate what the link's target 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 "Click" 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 "Details of product XYZ."
+
+### Common do's and don'ts
+
+- **Do** pass ARIA attributes via the `aria` prop, for example `aria="{ 'aria-current': 'page' }"` when indicating the current page.
+- **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 link labels like "Show" or "Add" without context.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `active` | `boolean` | `false` | Visually marks the link as the currently active navigation item, e.g. the current page. |
+| `alignLabel` | `'start'` `'end'`<br>`BreakpointCustomizable<LinkPureAlignLabel>` | `'end'` | Sets the label position relative to the icon — `start` places it before, `end` places it after. Supports responsive breakpoint values. |
+| `aria` | `LinkPureAriaAttribute` | `undefined` | Sets ARIA attributes on the link element to improve accessibility for screen readers. |
+| `color` | `'primary'` `'contrast-higher'` `'contrast-high'` `'contrast-medium'` `'inherit'` | `'primary'` | Sets the foreground color of the link's icon and label text. |
+| `download` | `string` | `undefined` | Sets the native `download` attribute to trigger a file download. Only applies when `href` is set. |
+| `hideLabel` | `boolean`<br>`BreakpointCustomizable<boolean>` | `false` | Hides the visible label while keeping it accessible to screen readers. Supports responsive breakpoint values. |
+| `href` | `string` | `undefined` | When set, the component renders as an anchor navigating to this URL. Otherwise, provide a slotted anchor element. |
+| `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. |
+| `rel` | `string` | `undefined` | Sets the `rel` attribute on the link (e.g. `noopener`). Only applies when `href` is set. |
+| `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<LinkPureSize>` | `'sm'` | Sets the font size of the link 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. |
+| `target` | `'_self'` `'_blank'` `'_parent'` `'_top'` `'string'` | `'_self'` | Specifies where to open the linked URL (e.g. `_self`, `_blank`). Only applies when `href` is set. |
+| `underline` | `boolean` | `false` | Adds a text underline to the label to reinforce its link-like appearance. |
+
+### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| _(default)_ | no | — | Default slot to render the link label. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.tsx](./examples/Default.tsx) |
+| Link with specific icon | If another icon needs to be implemented, just replace the default icon with another predefined icon. | [./examples/Icon.tsx](./examples/Icon.tsx) |
+| Framework routing (anchor nesting) | To support custom anchor tags (e.g. framework specific routing) you can provide them as a **slotted element** (recommended) of the component. | [./examples/FrameworkRouting.tsx](./examples/FrameworkRouting.tsx) |
+| Framework specific router with "active state" support | Examples how to use the component together with a framework specific router with "active state" support. | — |
+| Link Pure with custom clickable/focusable area | Sometimes it might be useful to enlarge the clickable/focusable area of a link to fulfill accessibility guidelines. | [./examples/CustomClickableArea.tsx](./examples/CustomClickableArea.tsx) |

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

@@ -0,0 +1,15 @@
+import React from 'react';
+import { PLinkTile, PTag } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PLinkTile href="https://porsche.com" 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" />
+      </PLinkTile>
+    </>
+  )
+}

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

@@ -0,0 +1,18 @@
+import React from 'react';
+import { PLinkTile, PTag, PText } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PLinkTile href="https://porsche.com" 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>
+      </PLinkTile>
+    </>
+  )
+}

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

@@ -0,0 +1,29 @@
+import React from 'react';
+import { PLinkTile, PTag, PText } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <div className="grid grid-cols-2 gap-static-md">
+        <PLinkTile href="https://porsche.com" 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>
+        </PLinkTile>
+        <PLinkTile href="https://porsche.com" 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>
+        </PLinkTile>
+      </div>
+    </>
+  )
+}

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

@@ -0,0 +1,34 @@
+import React from 'react';
+import { PLinkTile, 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>
+
+      <PLinkTile
+        href="https://porsche.com"
+        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" />
+      </PLinkTile>
+    </>
+  );
+};

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

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

package/skill/references/components/p-link-tile/examples/WithVideo.tsx

@@ -0,0 +1,15 @@
+import React from 'react';
+import { PLinkTile, PTag } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PLinkTile href="https://porsche.com" label="Some label" description="Some Description">
+        <PTag slot="header" color="background-frosted" compact={true}>
+          Some tag
+        </PTag>
+        <video poster="assets/ocean.jpg" src="assets/ocean.mp4" loop={true} muted={true} autoPlay={true} aria-label="Some video description"></video>
+      </PLinkTile>
+    </>
+  )
+}

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

@@ -0,0 +1,105 @@
+# p-link-tile
+
+The `p-link-tile` is a navigational component that displays a provided image to tease content and navigate to further information within one container. In case you want the user to execute an action, you should select the [Button Tile](../p-button-tile/p-button-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 `href`, `description` and `label` are required. The `description` property is used as a teaser with a more detailed description of the link and where it leads to.
+
+The `label` property is used to describe the anchor.
+
+## Usage
+
+### Do:
+
+- Use Link-Tile for prominent links with appropriate aspect ratios and short descriptions (80 characters or fewer).
+- Use [Button-Tile](../p-button-tile/p-button-tile.md) instead if you want on-page interactivity.
+- Use basic Link-Tile for better perception tests and compact Link-Tile for improved spacing (especially on mobile).
+- Use gradient Link-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 Link Tile. Create assets upfront for image processing.
+
+### Don't:
+
+- Don't manipulate images. Keep them natural and ensure sufficient contrast.
+- Don't write long descriptions that overflow content (especially on mobile).
+
+---
+
+## Related components
+
+- [Button Tile](../p-button-tile/p-button-tile.md)
+
+## Accessibility support
+
+### Keyboard
+
+| Key / state | Function |
+| --- | --- |
+| `Tab`, `Shift-Tab` | Moves focus to the next (or previous) focusable element. |
+| `Enter` | Activates the link. |
+
+### 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-current` | Exposes the current state of the link. |
+| `aria-haspopup` | Defines that the link opens a popup (e.g. `dialog`). |
+
+## Development considerations
+
+### Labelling
+
+If the text of a link does not clearly indicate what the link's target 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 "Click" 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 "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 link destination.
+- **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 link — `top` or `bottom`. |
+| `aria` | `LinkTileAriaAttribute` | `undefined` | Sets ARIA attributes on the tile's anchor element to improve accessibility for screen readers. |
+| `aspectRatio` | `'1/1'` `'4/3'` `'3/4'` `'16/9'` `'9/16'` `'auto'`<br>`BreakpointCustomizable<LinkTileAspectRatio>` | `'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 link without the full label. Supports responsive breakpoint values. |
+| `description` _(required)_ | `string` | `undefined` | Sets the description text displayed in the tile's content area. |
+| `download` | `string` | `undefined` | Sets the native `download` attribute to trigger a file download. |
+| `gradient` | `boolean` | `false` | Shows a gradient overlay over the media slot to improve text legibility on bright images or videos. |
+| `href` _(required)_ | `string` | `undefined` | Sets the URL the tile's anchor element navigates to when clicked. |
+| `label` _(required)_ | `string` | `undefined` | Sets the accessible label text of the link rendered inside the tile. |
+| `rel` | `string` | `undefined` | Sets the `rel` attribute on the link (e.g. `noopener`). |
+| `size` | `'medium'` `'large'` `'inherit'`<br>`BreakpointCustomizable<LinkTileSize>` | `'medium'` | Sets the font size of the description text in the tile content area. Supports responsive breakpoint values. |
+| `target` | `'_self'` `'_blank'` `'_parent'` `'_top'` `'string'` | `'_self'` | Specifies where to open the linked URL (e.g. `_self`, `_blank`). |
+| `weight` | `'regular'` `'semi-bold'`<br>`BreakpointCustomizable<LinkTileWeight>` | `'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) |
+| With video | With video | [./examples/WithVideo.tsx](./examples/WithVideo.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 Link Tile. | [./examples/ColorScheme.tsx](./examples/ColorScheme.tsx) |

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

@@ -0,0 +1,22 @@
+import React from 'react';
+import { useState } from 'react';
+import { PLinkTileProduct, PTag, type LinkTileProductLikeEvent } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  const [liked, setLiked] = useState(false);
+
+  const onLike = (e: CustomEvent<LinkTileProductLikeEvent>) => {
+    setLiked(!e.detail.liked);
+  }
+
+  return (
+    <>
+      <PLinkTileProduct liked={liked} heading="Some product" price="718,00 €" priceOriginal="911,00 €" description="Some description" href="https://porsche.com" onLike={onLike}>
+        <PTag slot="header" color="background-base">
+          New
+        </PTag>
+        <img src="assets/placeholder_800x900.svg" width={800} height={900} alt="Some alt text" />
+      </PLinkTileProduct>
+    </>
+  )
+}

package/skill/references/components/p-link-tile-product/examples/FrameworkRouting.tsx

@@ -0,0 +1,25 @@
+import React from 'react';
+import { useState } from 'react';
+import { PLinkTileProduct, type LinkTileProductLikeEvent } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  const [liked, setLiked] = useState(false);
+
+  const onLike = (e: CustomEvent<LinkTileProductLikeEvent>) => {
+    setLiked(!e.detail.liked);
+  }
+
+  return (
+    <>
+      <PLinkTileProduct liked={liked} heading="Some product" price="718,00 €" priceOriginal="911,00 €" description="Some description" onLike={onLike}>
+        <a slot="anchor" href="https://porsche.com">
+          Weekender, sale price 718,00 €, original price 
+          <s>
+            911,00 €
+          </s>
+        </a>
+        <img src="assets/placeholder_800x900.svg" width={800} height={900} alt="Some alt text" />
+      </PLinkTileProduct>
+    </>
+  )
+}