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

package/skills/pds-knowledge-angular/references/components/p-checkbox/accessibility.md

@@ -0,0 +1,31 @@
+# p-checkbox accessibility integration examples
+
+## Integration examples
+
+### Hidden label without accessible name
+
+#### ❌ Anti-pattern
+
+```html
+<p-checkbox name="terms" [hideLabel]="true"></p-checkbox>
+```
+
+#### ✅ Recommended
+
+```html
+<p-checkbox name="terms" [hideLabel]="true" label="I accept the terms and conditions"></p-checkbox>
+```
+
+### Validation feedback via state and message API
+
+#### ❌ Anti-pattern
+
+```html
+<p-checkbox name="terms" label="I accept the terms and conditions" [aria-invalid]="true" message="Required"></p-checkbox>
+```
+
+#### ✅ Recommended
+
+```html
+<p-checkbox name="terms" label="I accept the terms and conditions" [required]="true" state="error" message="Accept the terms and conditions to continue."></p-checkbox>
+```

package/skills/pds-knowledge-angular/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/skills/pds-knowledge-angular/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/skills/pds-knowledge-angular/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/skills/pds-knowledge-angular/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/skills/pds-knowledge-angular/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/skills/pds-knowledge-angular/references/components/p-checkbox/p-checkbox.md

@@ -0,0 +1,126 @@
+# 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.
+
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
+## 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/skills/pds-knowledge-angular/references/components/p-crest/accessibility.md

@@ -0,0 +1,17 @@
+# p-crest accessibility integration examples
+
+## Integration examples
+
+### ARIA on component host vs aria prop
+
+#### ❌ Anti-pattern
+
+```html
+<p-crest href="/" aria-label="Porsche home"></p-crest>
+```
+
+#### ✅ Recommended
+
+```html
+<p-crest href="/" [aria]="{'aria-label': 'Porsche home'}"></p-crest>
+```

package/skills/pds-knowledge-angular/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/skills/pds-knowledge-angular/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/skills/pds-knowledge-angular/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/skills/pds-knowledge-angular/references/components/p-crest/p-crest.md

@@ -0,0 +1,69 @@
+# 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.
+
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
+## 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/skills/pds-knowledge-angular/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/skills/pds-knowledge-angular/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/skills/pds-knowledge-angular/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/skills/pds-knowledge-angular/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/skills/pds-knowledge-angular/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 {}

package/skills/pds-knowledge-angular/references/components/p-display/p-display.md

@@ -0,0 +1,78 @@
+# p-display
+
+> **Deprecated:** since v4.0.0, will be removed with next major release. Please use `p-heading` instead.
+
+`p-display` is used to highlight and specify heading styling and hierarchy in documents.
+
+> **Recommendation**
+>
+> Although the component is very sophisticated, it's recommended (if possible) to use the corresponding utility classes of the "@porsche-design-system/components-{js | angular | react | vue}/tailwindcss" sub-package or any of the other styling solutions for best performance since way less DOM nodes are required to render. Further information can be found [here](../../styles/tailwindcss.md).
+
+## Usage
+
+p-display is used to highlight and specify heading styling and hierarchy.
+
+### Do's:
+
+- Use p-display for standout moments like hero intros, emotional statements, or key statistics.
+- Choose from display-small, display-medium, or display-large depending on the visual weight required.
+- Center-align p-display styles for marketing, landing, or intro sections to enhance visual impact.
+- Ensure generous spacing around p-display elements to give them room to breathe.
+
+### Don't:
+
+- Don’t use p-display styles for standard section headings or body text—use p-heading or p-text instead.
+- Don’t mix multiple p-display sizes on the same screen unless clearly structured (e.g. in a visual hierarchy).
+
+## Accessibility support
+
+This component does not include any special accessibility features.
+
+## Development considerations
+
+### Heading hierarchy
+
+While using the `Display` component, take care of the correct heading hierarchy which can be adjusted through the `tag` property. Keep in mind that the visual appearance must not always be identical with the semantic hierarchy.
+
+#### Best practices
+
+- Use one unique `h1` per page that describes what that page is about.
+- Use headings to describe the content below. Do not use an HTML heading just to make the text appear bigger or stand out.
+- Use heading levels like the index of a book: hierarchical.
+- Do not choose a heading by its size, but by its level in the context of the content.
+- Heading hierarchy should not increase by more than one level at a time.
+- Do not skip a heading level from the top down.
+
+### Common do's and don'ts
+
+- **Do** use the `tag` prop to reflect semantic hierarchy, not just visual `size`.
+- **Do** keep one unique `h1` per page for the primary page topic.
+- **Don't** use `tag="h1"` on display text that is not the main page title.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `align` | `'start'` `'center'` `'end'` `'inherit'` | `'start'` | Sets the horizontal text alignment (`start`, `center`, `end`, or `inherit`). |
+| `color` | `'primary'` `'inherit'` | `'primary'` | Sets the text color using PDS color tokens. |
+| `ellipsis` | `boolean` | `false` | Truncates the text with an ellipsis when it overflows the container on a single line. |
+| `size` | `'small'` `'medium'` `'large'` `'inherit'`<br>`BreakpointCustomizable<DisplaySize>` | `'large'` | Sets the visual text size. Supports responsive breakpoint values. |
+| `tag` | `undefined` `'h1'` `'h2'` `'h3'` `'h4'` `'h5'` `'h6'` | `undefined` | Sets the HTML heading tag (h1–h6) for correct document outline placement. When omitted, the tag is inferred from `size`. |
+
+### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| _(default)_ | no | — | Default slot for the display text. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.ts](./examples/Default.ts) |
+| Size | There are predefined fluid text sizes for the component which should cover most use cases. | [./examples/Size.ts](./examples/Size.ts) |
+| Responsive | Responsive | [./examples/SizeResponsive.ts](./examples/SizeResponsive.ts) |
+| Semantics | To provide more contextual HTML semantics you can either pass them with the `tag` property or directly inside a slot. | [./examples/Semantics.ts](./examples/Semantics.ts) |
+| Color | Predefined theme-based colors are available, but `inherit` can also be used to define a custom color. | [./examples/Color.ts](./examples/Color.ts) |

package/skills/pds-knowledge-angular/references/components/p-divider/accessibility.md

@@ -0,0 +1,41 @@
+# p-divider accessibility integration examples
+
+## Integration examples
+
+### Divider as the only section separator
+
+#### ❌ Anti-pattern
+
+```html
+<p-text>
+  Delivery details
+</p-text>
+
+<p-divider></p-divider>
+
+<p-text>
+  Payment details
+</p-text>
+```
+
+#### ✅ Recommended
+
+```html
+<p-heading tag="h2" size="md">
+  Delivery details
+</p-heading>
+
+<p-text>
+  ...
+</p-text>
+
+<p-divider></p-divider>
+
+<p-heading tag="h2" size="md">
+  Payment details
+</p-heading>
+
+<p-text>
+  ...
+</p-text>
+```