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

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

@@ -0,0 +1,142 @@
+# p-carousel
+
+The `p-carousel` component allows related or similar content to be consumed on a step by step basis with a better overview than just showing them in a grid or as a list. The reason for this is, that only a certain amount of slides is visible at the same time.
+
+Therefore, the `p-carousel`'s content has to be divided into multiple parts or slides. The amount of slides visible can be specified on a per-breakpoint basis.
+
+> **Layout hint**
+>
+> When using the `width` prop to align with the **[Porsche Grid](../../styles/tailwindcss.md)**, the component must span the full viewport width.
+>
+> When using the `--p-carousel-px` CSS variable, the component can be placed within any container, allowing you to customize the horizontal padding that reveals parts of the next/previous slide.
+>
+> When using the `--p-carousel-ps` and `--p-carousel-pe` CSS variables, the component can be placed within any container, allowing you to customize the horizontal padding asymmetric that reveals parts of the next/previous slide.
+
+> **Dynamic changes**
+>
+> This component has limited support for dynamic property changes due to the way it is implemented.
+>
+> If you need to use a specific property dynamically, please open a [feature request](https://designsystem.porsche.com/help/feature-request/).
+
+## Usage
+
+### Do:
+
+- Use to showcase a group of related featured content in a row, such as images or cards.
+- Use when you have five or fewer items of the same style to display.
+- Use when there is insufficient content space to display all items without overlapping or cluttering.
+- Keep the number of slides within the carousel to a minimum, preferably five or fewer.
+- Use specify the number of slides visible at the same time, either static or for each breakpoint individually.
+
+### Don't:
+
+- Don't vary the size of the items in its height.
+- Don't maintain the same layout or at least the same content structure with every item.
+
+## Accessibility support
+
+### Keyboard
+
+| Key / state | Function |
+| --- | --- |
+| `Tab`, `Shift-Tab` | - Moves focus to the next (or previous) focusable element. - Supports cycling through all items. - Activates "Skip" link (if set through `skipLinkTarget`). |
+
+### ARIA enhancements
+
+#### External **ARIA** provided by the `aria` property:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-label` | Defines a string value that labels the carousel. |
+
+#### Internal **ARIA** that is managed by the component:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-label="STRING"` | Defines a string value that labels prev/next and carousel items. |
+| `role="region"` | Defines the carousel as a semantic region. |
+| `role="group"` | Defines the carousel item as a semantic group. |
+| `aria-labelledby="IDREF"` | References the accessible name. |
+| `aria-roledescription="carousel"` | Specifies the role as "carousel". |
+| `aria-roledescription="slide"` | Specifies the role of the carousel item as "slide". |
+| `aria-live="polite"` | Announces current active slide item. |
+
+## Development considerations
+
+### Skip Carousel Entries
+
+Through the `skipLinkTarget` property, a skip link for keyboard users can be provided to give the possibility to skip over all carousel entries. The skip link is only visible when it receives focus from the keyboard.
+
+- Use the `skipLinkTarget` property if you have >5 carousel items
+- The target of the skip link should point to the next heading or element right after the carousel
+
+### Common do's and don'ts
+
+- **Do** configure `skip-link-target` for larger carousels or repeated content sections.
+- **Do** ensure the skip target points to the next meaningful section.
+- **Do** provide a descriptive carousel label via the `aria` property.
+- **Don't** force keyboard users to tab through every slide control when a skip path is needed.
+- **Don't** use vague labels that do not communicate carousel context.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `activeSlideIndex` | `number` | `0` | Sets the zero-based index of the currently visible slide. Update this to navigate programmatically. |
+| `alignControls` | `'start'` `'center'` `'auto'` | `'auto'` | Controls the alignment of custom slotted controls within the header area. |
+| `alignHeader` | `'start'` `'center'` | `'start'` | Controls the horizontal alignment of the heading and description. |
+| `aria` | `CarouselAriaAttribute` | `undefined` | Sets ARIA attributes on the carousel region element for improved accessibility. |
+| `description` | `string` | `undefined` | Sets the description text displayed below the heading for additional context. |
+| `focusOnCenterSlide` | `boolean` | `false` | When enabled, each slide is individually focusable and the carousel navigates one slide at a time instead of one page. |
+| `gradient` | `boolean` | `false` | Shows a gradient fade at the start and end edges to visually indicate more slides beyond the viewport. |
+| `heading` | `string` | `undefined` | Sets the heading text displayed above the carousel. Also used as the accessible label when no `aria` prop is set. |
+| `headingSize` | `'x-large'` `'xx-large'` | `'x-large'` | Sets the font size of the carousel heading. |
+| `intl` | `CarouselInternationalization` | `undefined` | Overrides the default label strings used for the previous, next, and page indicators — useful for localization. |
+| `pagination` | `boolean`<br>`BreakpointCustomizable<boolean>` | `false` | Shows pagination dot indicators below the carousel. Supports responsive breakpoint values. |
+| `rewind` | `boolean` | `false` | Enables infinite looping — navigating past the last slide wraps back to the first, and vice versa. |
+| `skipLinkTarget` | `string` | `undefined` | Sets the `href` of an in-page skip link that lets keyboard users jump past the carousel slides. |
+| `slidesPerPage` | `'auto'` `1` `2` `3` `4` `5` `6` `7` `8` `9` `10`<br>`BreakpointCustomizable<CarouselSlidesPerPage>` | `1` | Sets how many slides are visible at once. Use `auto` to control each slide's width via CSS. Supports responsive breakpoint values. |
+| `trimSpace` | `boolean` | `false` | Removes whitespace before the first and after the last slide when `focusOnCenterSlide` is enabled. |
+| `width` | `'basic'` `'extended'` `'wide'` `'full'` | `'basic'` | Sets the maximum width and outer spacing of the carousel, aligned to PDS grid widths. |
+
+### Events
+
+| Event | Type | Description |
+| --- | --- | --- |
+| `update` | `CustomEvent<CarouselUpdateEventDetail>`<br>`{ activeIndex: number; previousIndex: number }` | Emitted when the carousel navigates to a new slide, with the active and previous slide indexes in the event detail. |
+
+### Controlled properties
+
+- `activeSlideIndex` — a controlled prop, but the component also updates it internally. Listen for the `update` event to observe changes; you do not have to write the value back.
+
+### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| `heading` | no | — | Renders a heading above the carousel. |
+| `description` | no | — | Renders descriptive content below the heading. |
+| `controls` | no | — | Renders custom controls such as navigation buttons or indicators. |
+| _(default)_ | no | — | Default slot for the carousel slides. |
+
+### CSS Variables
+
+| CSS Variable | Default | Description |
+| --- | --- | --- |
+| `--p-carousel-px` | — | Defines the logical inline start and end padding of the carousel, the extra space is used to show parts of the next/previous slide. When used then the prop `width` has no effect anymore. |
+| `--p-carousel-ps` | — | Defines the logical inline start padding of the carousel, the extra space is used to show parts of the next/previous slide. Needs to be used in combination with `--p-carousel-px` or `--p-carousel-pe`. When used then the prop `width` has no effect anymore. |
+| `--p-carousel-pe` | — | Defines the logical inline end padding of the carousel, the extra space is used to show parts of the next/previous slide. Needs to be used in combination with `--p-carousel-px` or `--p-carousel-ps`. When used then the prop `width` has no effect anymore. |
+| `--p-carousel-prev-next-color-scheme` | — | Color Scheme applied to the navigation (prev/next buttons) |
+| `--p-carousel-border-radius` | `var(--p-radius-large, var(--p-radius-4xl))` | Sets the border radius of each carousel slide. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.ts](./examples/Default.ts) |
+| Slides with flexible widths | In case you want to have slides with different widths you can use `slidesPerPage` with a value of `auto`. | [./examples/FlexibleWidths.ts](./examples/FlexibleWidths.ts) |
+| Jump to slide (activeSlideIndex) | To control the `p-carousel` from the outside you can specify its `activeSlideIndex` initially but also later. | [./examples/JumpToSlide.ts](./examples/JumpToSlide.ts) |
+| Add/remove slides | Slides can be added and removed dynamically. | [./examples/DynamicSlides.ts](./examples/DynamicSlides.ts) |
+| Centered Slide and Gradient Customization | The carousel centers the active slide and loops through slides individually rather than by page when multiple slides are visible. | [./examples/FocusOnCenterSlide.ts](./examples/FocusOnCenterSlide.ts) |
+| Internationalization (i18n) | Default wordings for screen readers can be overridden or translated by passing an object to the `intl` property. | [./examples/Intl.ts](./examples/Intl.ts) |

package/skill/references/components/p-checkbox/examples/Default.ts

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

package/skill/references/components/p-checkbox/examples/Form.ts

@@ -0,0 +1,31 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { FormControl, FormGroup, FormsModule, ReactiveFormsModule, Validators } from '@angular/forms';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+    <form [formGroup]="form" (ngSubmit)="onSubmit()" class="flex flex-col gap-fluid-sm">
+      <p-checkbox formControlName="myCheckbox" [label]="'Some Label'" />
+      <div class="flex gap-fluid-sm">
+        <p-button type="submit">Submit</p-button>
+        <p-button type="reset">Reset</p-button>
+      </div>
+      <p-text>Last submitted data: {{ submittedValue }}</p-text>
+    </form>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule, FormsModule, ReactiveFormsModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {
+  form = new FormGroup({
+    myCheckbox: new FormControl<boolean>(false),
+  });
+
+  submittedValue: any = undefined;
+
+  onSubmit(): void {
+    this.submittedValue = JSON.stringify(this.form.value);
+  }
+}

package/skill/references/components/p-checkbox/examples/Indeterminate.ts

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

package/skill/references/components/p-checkbox/examples/Slots.ts

@@ -0,0 +1,57 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <div class="flex flex-col gap-static-sm">
+        <p-checkbox name="some-name">
+          <span slot="label">
+            <img src="assets/911.png" alt="" class="object-contain inline-block align-middle -mt-2 me-static-sm w-[70px]" />
+            Some slotted label with custom content and a "label-after" slot
+          </span>
+          <p-popover slot="label-after">
+            Some label with a 
+            <a href="https://designsystem.porsche.com" class="underline">
+              link
+            </a>
+          </p-popover>
+        </p-checkbox>
+        <p-checkbox name="some-name">
+          <span slot="label">
+            Some slotted label
+          </span>
+        </p-checkbox>
+        <p-checkbox name="some-name" disabled="true">
+          <span slot="label">
+            Disabled slotted label, a nested 
+            <a href="https://www.porsche.com" class="underline" tabindex="-1">
+              link
+            </a>
+             and a label-after slot.
+          </span>
+          <p-popover slot="label-after">
+            Some information about the disabled state.
+          </p-popover>
+        </p-checkbox>
+        <p-checkbox name="some-name" state="error">
+          <span slot="label">
+            Some slotted label with a nested 
+            <a href="https://www.porsche.com" class="underline">
+              link
+            </a>
+          </span>
+          <span slot="message">
+            Some slotted error message with a 
+            <a href="https://designsystem.porsche.com" class="underline">
+              link
+            </a>
+          </span>
+        </p-checkbox>
+      </div>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skill/references/components/p-checkbox/examples/WrappedLabel.ts

@@ -0,0 +1,27 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <div class="flex items-start w-64 border-2 border-contrast-lower rounded-md hover:border-primary transition-colors">
+        <label class="inline-flex flex-col p-fluid-xs gap-static-xs prose-text-sm cursor-pointer hover:[--p-checkbox-border-color:var(--color-primary)]" (click)="onClick()">
+          <span>
+            Some wrapped custom label besides a popover
+          </span>
+          <p-checkbox [checked]="false"></p-checkbox>
+        </label>
+        <p-popover class="mr-static-xs mt-static-xs">
+          Some additional content.
+        </p-popover>
+      </div>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {
+  onClick() {
+    this.checked = true;
+  }
+}

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

@@ -0,0 +1,122 @@
+# p-checkbox
+
+The `p-checkbox` component wraps the native HTML input type `checkbox` form element. Checking one box doesn't uncheck other Checkboxes. By default, Checkboxes are not selected.
+
+> **Firefox Form Restore Bug**
+>
+> Firefox has a known bug where it incorrectly restores form state for form-associated custom elements with shadow DOM on page reload. Checkbox values may appear inside unrelated `input-text` fields in the same form under certain conditions. To work around this, add the native HTML attribute `autocomplete="off"` to all checkbox form elements. See [Firefox Bug](https://bugzilla.mozilla.org/show_bug.cgi?id=1986953) for details.
+
+A `label` is a caption which informs the user what information a particular form field is asking for. The `p-checkbox` component can be used with or without a label, but it's recommended to keep the label visible for better accessibility whenever possible. When used without a label, it's best practice to provide a descriptive label text for screen readers.
+
+## Usage
+
+### Do:
+
+- Use for a list of options when you want the user to select one, none, or multiple options.
+- Use when an explicit action is required to apply to settings.
+- Use the default view for checkboxes when no option is selected.
+- Use the indeterminate state only as a visual state and not as a direct user interaction.
+- Nest when a parent and child relationship is needed.
+- Use short and descriptive label text for each checkbox option.
+- Provide validation messages for each checkbox option if needed.
+- Set vertically left-aligned for better scannability.
+
+### Don't:
+
+- Avoid using when you have more than 8 options to choose from or consider using a [Select](../p-select/p-select.md).
+- Don't mix [Radio Group](../p-radio-group/p-radio-group.md) options with checkboxes.
+- Don't change the selection of another checkbox when a nested one is clicked. The only exception is when a checkbox is used to make a bulk selection of multiple items.
+
+---
+
+## Related Components
+
+- [Radio Group](../p-radio-group/p-radio-group.md)
+- [Select](../p-select/p-select.md)
+
+## Accessibility support
+
+### Keyboard
+
+| Key / state | Function |
+| --- | --- |
+| `Tab`, `Shift-Tab` | Moves focus to the next (or previous) focusable element. |
+| `Space` | Activates/Deactivates checkbox. |
+
+### ARIA enhancements
+
+#### Internal **ARIA** that is managed by the component:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-describedby="IDREF"` | References the accessible description of status messages. |
+| `role="status"`, `role="alert"` | When `message` and `state` or `loading` prop change, the status message is announced. |
+| `aria-hidden="true"` | If `required` attribute is set, the visible asterisk indicator is hidden from assistive technologies. |
+| `aria-invalid="true"` | If `error` state is set. |
+
+## Development considerations
+
+### Disabled state
+
+In general, avoid using the `disabled` state. Disabled elements are no longer focusable and may be missed by screen reader users. They can also confuse sighted users if the reason they are disabled is not made clear.
+
+### Common do's and don'ts
+
+- **Do** provide a clear `label` that describes what the checkbox controls.
+- **Do** use the component state/message API so validation and status changes are announced.
+- **Do** use clear error wording that helps users recover.
+- **Don't** use `hide-label` without an accessible name.
+- **Don't** use `hide-label` when it is not clear what the checkbox controls.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `checked` | `boolean` | `false` | Reflects the checkbox's current checked state and allows setting the initial checked value on load. |
+| `compact` | `boolean` | `false` | Reduces the checkbox size and spacing for a more compact layout. |
+| `disabled` | `boolean` | `false` | Disables the checkbox, preventing all interaction. The value is not submitted with the form. |
+| `form` | `string` | `undefined` | Associates the checkbox with a form element by its ID when not directly nested inside it. |
+| `hideLabel` | `boolean`<br>`BreakpointCustomizable<boolean>` | `false` | Hides the visible label while keeping it accessible to screen readers. Supports responsive breakpoint values. |
+| `indeterminate` | `boolean` | `false` | Puts the checkbox into an indeterminate state, indicating that a group of child items is only partially selected. |
+| `label` | `string` | `''` | Sets the visible label text displayed next to the checkbox. |
+| `loading` _(experimental)_ | `boolean` | `false` | @experimental Disables the checkbox and displays a loading spinner to indicate an ongoing operation. |
+| `message` | `string` | `''` | Sets the validation feedback message displayed below the checkbox when `state` is `success` or `error`. |
+| `name` | `string` | `''` | Sets the name submitted with the form data to identify this checkbox's value on the server. |
+| `required` | `boolean` | `false` | Marks the checkbox as required — form submission is blocked unless the checkbox is checked. |
+| `state` | `'none'` `'error'` `'success'` | `'none'` | Sets the validation state, controlling the visual appearance and style of the feedback message (`none`, `success`, `error`). |
+| `value` | `string` | `'on'` | Sets the value submitted with the form data when the checkbox is checked. Unchecked checkboxes are excluded from form submissions. |
+
+### Events
+
+| Event | Type | Description |
+| --- | --- | --- |
+| `blur` | `CustomEvent<CheckboxBlurEventDetail>`<br>`Event` | Emitted when the checkbox loses focus. |
+| `change` | `CustomEvent<CheckboxChangeEventDetail>`<br>`Event` | Emitted when the user changes the checked state of the checkbox. |
+
+### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| `label` | no | — | Shows a label. Only [phrasing content](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content) is allowed. |
+| `label-after` | no | — | Places additional content after the label text (for content that should not be part of the label, e.g. external links or `p-popover`). |
+| `message` | no | — | Shows a state message. Only [phrasing content](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content) is allowed. |
+
+### CSS Variables
+
+| CSS Variable | Default | Description |
+| --- | --- | --- |
+| `--p-checkbox-border-color` | — | 🧪Experimental: Border colors of Checkbox. Should be used to override the default border color in different states (e.g., hover, focus, error), e.g. when the Checkbox is wrapped inside a custom label. |
+| `--p-checkbox-background-color` | — | 🧪Experimental: Background color of Checkbox. |
+| `--p-checkbox-icon-color` | — | 🧪Experimental: Checkmark icon color of Checkbox. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.ts](./examples/Default.ts) |
+| Form | The `p-checkbox` can be integrated into a form in two ways: **controlled** or **uncontrolled**, depending on your needs. | [./examples/Form.ts](./examples/Form.ts) |
+| Indeterminate | Mask the visual appearance of a checkbox which has a state in-between checked and unchecked. | [./examples/Indeterminate.ts](./examples/Indeterminate.ts) |
+| Slots | Use named slots when `label` or `message` need markup such as a link. | [./examples/Slots.ts](./examples/Slots.ts) |
+| Custom wrapped label (🧪Experimental) | The `p-checkbox` component also supports a custom wrapped `label` by wrapping the component in a `label` tag. | [./examples/WrappedLabel.ts](./examples/WrappedLabel.ts) |

package/skill/references/components/p-crest/examples/CustomClickableArea.ts

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

package/skill/references/components/p-crest/examples/Default.ts

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

package/skill/references/components/p-crest/examples/Link.ts

@@ -0,0 +1,13 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-crest href="https://porsche.com" [aria]="{'aria-label': 'Porsche Homepage'}"></p-crest>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

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

@@ -0,0 +1,65 @@
+# p-crest
+
+The `p-crest` gives the Porsche brand a distinctive look, sets it apart from others within the overall external image and represents the quality of the product.
+
+> **Usage hint**
+>
+> This component shall only be used on viewports below 480px (breakpoint "S"). Otherwise, [p-wordmark](../p-wordmark/p-wordmark.md) has to be used.
+
+You can use native `click`, `focus`, `focusin`, `blur` and `focusout` events on the `p-crest`.
+
+## Usage
+
+### Do:
+
+- Use the [Wordmark](../p-wordmark/p-wordmark.md) as the main brand identifier.
+- Use the crest only as an additional small brand identifier (e.g., within contact cards).
+- Switch from the wordmark to the crest on small viewports below 480px (automatically implemented in global navigation and footer).
+
+### Don't:
+
+- Use the crest as the primary brand identifier by default.
+
+---
+
+## Related Components
+
+- [Wordmark](../p-wordmark/p-wordmark.md)
+
+## Accessibility support
+
+### ARIA enhancements
+
+#### External **ARIA** provided by the `aria` property:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-label` | Defines a string value that labels 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
+
+### Common do's and don'ts
+
+- **Do** pass ARIA attributes through the `aria` prop when the crest is linked.
+- **Do** provide a descriptive `aria-label` for linked crests, for example "Porsche home".
+- **Don't** add native `aria-*` attributes directly on the component host.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `aria` | `CrestAriaAttribute` | `undefined` | Sets ARIA attributes on the anchor element to improve accessibility when the crest is used as a link. |
+| `href` | `string` | `undefined` | When set, renders the crest as an anchor element navigating to this URL when clicked. |
+| `target` | `'_self'` `'_blank'` `'_parent'` `'_top'` `'string'` | `'_self'` | Specifies where to open the linked URL (e.g. `_self`, `_blank`). Only applies when `href` is set. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.ts](./examples/Default.ts) |
+| Link | The Porsche Crest will be rendered as `<a>`-tag as soon as an `href` is provided. | [./examples/Link.ts](./examples/Link.ts) |
+| Custom clickable/focusable area | Sometimes it may be useful to enlarge the clickable/focusable area of the Porsche Crest. | [./examples/CustomClickableArea.ts](./examples/CustomClickableArea.ts) |

package/skill/references/components/p-display/examples/Color.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-display tag="h3" color="inherit" class="text-[deeppink]">
+        The quick brown fox jumps over the lazy dog
+      </p-display>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skill/references/components/p-display/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-display>
+        The quick brown fox jumps over the lazy dog
+      </p-display>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skill/references/components/p-display/examples/Semantics.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-display tag="h3">
+        The quick brown fox jumps over the lazy dog
+      </p-display>
+
+      <p-display>
+        <h3>
+          The quick brown fox jumps over the lazy dog
+        </h3>
+      </p-display>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skill/references/components/p-display/examples/Size.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-display tag="h3" size="inherit" class="text-[5rem]">
+        The quick brown fox jumps over the lazy dog
+      </p-display>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skill/references/components/p-display/examples/SizeResponsive.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-display tag="h3" [size]="{'base': 'medium', 'l': 'large'}">
+        The quick brown fox jumps over the lazy dog
+      </p-display>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}