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

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

@@ -0,0 +1,80 @@
+# p-modal accessibility integration examples
+
+## Integration examples
+
+### ARIA on component host vs aria prop
+
+#### ❌ Anti-pattern
+
+```html
+<p-button aria-haspopup="dialog">
+  Details of product XYZ
+</p-button>
+```
+
+#### ✅ Recommended
+
+```html
+<p-button [aria]="{'aria-haspopup': 'dialog'}">
+  Details of product XYZ
+</p-button>
+```
+
+### Dialog label on component host vs header slot
+
+#### ❌ Anti-pattern
+
+```html
+<p-modal aria-label="Details">
+  ...
+</p-modal>
+```
+
+#### ✅ Recommended
+
+```html
+<p-modal>
+  <p-heading slot="header" tag="h2" size="lg">
+    Details of product XYZ
+  </p-heading>
+  ...
+</p-modal>
+
+<!-- or with aria prop when no visible header is shown -->
+
+<p-modal [aria]="{'aria-label': 'Details of product XYZ'}">
+  ...
+</p-modal>
+```
+
+### Modal trigger without popup semantics or context
+
+#### ❌ Anti-pattern
+
+```html
+<p-button>
+  Open
+</p-button>
+
+<p-modal>
+  <p-heading slot="header" tag="h2" size="lg">
+    Details
+  </p-heading>
+  ...
+</p-modal>
+```
+
+#### ✅ Recommended
+
+```html
+<p-button [aria]="{'aria-haspopup': 'dialog'}">
+  Details of product XYZ
+</p-button>
+
+<p-modal>
+  <p-heading slot="header" tag="h2" size="lg">
+    Details of product XYZ
+  </p-heading>
+  ...
+</p-modal>
+```

package/{skill → skills/pds-knowledge-angular}/references/components/p-modal/p-modal.md

@@ -80,6 +80,10 @@ To inform users that the trigger button opens a `dialog`, the `aria-haspopup` at
 - **Don't** add raw host-level ARIA attributes as a workaround.
 - **Don't** use unclear trigger copy like "Open" when the destination is not obvious.
 
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
 ## API
 
 ### Properties

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

@@ -0,0 +1,78 @@
+# p-multi-select accessibility integration examples
+
+## Integration examples
+
+### Prompt option used instead of a label
+
+#### ❌ Anti-pattern
+
+```html
+<p-multi-select name="features">
+  <p-multi-select-option value="">
+    Select features
+  </p-multi-select-option>
+  <p-multi-select-option value="sport">
+    Sport Chrono Package
+  </p-multi-select-option>
+</p-multi-select>
+```
+
+#### ✅ Recommended
+
+```html
+<p-multi-select label="Optional features" name="features" description="Select all features for your configuration.">
+  <p-multi-select-option value="sport">
+    Sport Chrono Package
+  </p-multi-select-option>
+  <p-multi-select-option value="audio">
+    BOSE Surround Sound
+  </p-multi-select-option>
+</p-multi-select>
+```
+
+### Hidden label without accessible name
+
+#### ❌ Anti-pattern
+
+```html
+<p-multi-select name="features" [hideLabel]="true">
+  <p-multi-select-option value="sport">
+    Sport Chrono Package
+  </p-multi-select-option>
+</p-multi-select>
+```
+
+#### ✅ Recommended
+
+```html
+<p-multi-select label="Optional features" name="features" [hideLabel]="true">
+  <p-multi-select-option value="sport">
+    Sport Chrono Package
+  </p-multi-select-option>
+</p-multi-select>
+```
+
+### Validation feedback via state and message API
+
+#### ❌ Anti-pattern
+
+```html
+<p-multi-select label="Optional features" name="features" [aria-invalid]="true" message="Required">
+  <p-multi-select-option value="sport">
+    Sport Chrono Package
+  </p-multi-select-option>
+</p-multi-select>
+```
+
+#### ✅ Recommended
+
+```html
+<p-multi-select label="Optional features" name="features" [required]="true" state="error" message="Select at least one feature to continue.">
+  <p-multi-select-option value="sport">
+    Sport Chrono Package
+  </p-multi-select-option>
+  <p-multi-select-option value="audio">
+    BOSE Surround Sound
+  </p-multi-select-option>
+</p-multi-select>
+```

package/{skill → skills/pds-knowledge-angular}/references/components/p-multi-select/p-multi-select.md

@@ -85,6 +85,10 @@ In general, avoid using the `disabled` state. Disabled elements are no longer fo
 - **Don't** use a prompt option or adjacent text as a substitute for a field label.
 - **Don't** use `hide-label` without an accessible name.
 
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
 ## API
 
 ### Properties

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

@@ -0,0 +1,23 @@
+# p-pagination accessibility integration examples
+
+## Integration examples
+
+### Default English labels on a localized page
+
+#### ❌ Anti-pattern
+
+```html
+<html lang="de_DE">
+  ...
+  <p-pagination [totalItemsCount]="120" [itemsPerPage]="10" [activePage]="1"></p-pagination>
+</html>
+```
+
+#### ✅ Recommended
+
+```html
+<html lang="de_DE">
+  ...
+  <p-pagination [totalItemsCount]="120" [itemsPerPage]="10" [activePage]="1" [intl]="{'root': 'Seitennavigation', 'prev': 'Vorherige Seite', 'next': 'Nächste Seite', 'page': 'Seite'}"></p-pagination>
+</html>
+```

package/{skill → skills/pds-knowledge-angular}/references/components/p-pagination/p-pagination.md

@@ -54,6 +54,10 @@ To adapt the pagination to the specific viewport context, the amount of displaye
 - **Do** keep prev/next and page button labels specific enough to identify the pagination control.
 - **Don't** rely on default English `intl` strings on localized pages.
 
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
 ## API
 
 ### Properties

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

@@ -0,0 +1,45 @@
+# p-pin-code accessibility integration examples
+
+## Integration examples
+
+### Missing field label
+
+#### ❌ Anti-pattern
+
+```html
+<p-pin-code name="verification" [length]="6"></p-pin-code>
+```
+
+#### ✅ Recommended
+
+```html
+<p-pin-code name="verification" [length]="6" label="Verification code" description="Enter the 6-digit code from your email."></p-pin-code>
+```
+
+### Hidden label without accessible name
+
+#### ❌ Anti-pattern
+
+```html
+<p-pin-code name="verification" [length]="6" [hideLabel]="true"></p-pin-code>
+```
+
+#### ✅ Recommended
+
+```html
+<p-pin-code name="verification" [length]="6" [hideLabel]="true" label="Verification code"></p-pin-code>
+```
+
+### Validation feedback via state and message API
+
+#### ❌ Anti-pattern
+
+```html
+<p-pin-code name="verification" label="Verification code" [aria-invalid]="true" message="Invalid"></p-pin-code>
+```
+
+#### ✅ Recommended
+
+```html
+<p-pin-code name="verification" [length]="6" label="Verification code" state="error" message="Enter the complete 6-digit verification code."></p-pin-code>
+```

package/{skill → skills/pds-knowledge-angular}/references/components/p-pin-code/p-pin-code.md

@@ -58,6 +58,10 @@ In general, avoid using the `disabled="true"` state. Disabled elements are no lo
 - **Do** use the component state/message API so validation and status changes are announced.
 - **Don't** use `hide-label` without an accessible name.
 
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
 ## API
 
 ### Properties

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

@@ -0,0 +1,61 @@
+# p-popover accessibility integration examples
+
+## Integration examples
+
+### ARIA on component host vs aria prop
+
+#### ❌ Anti-pattern
+
+```html
+<p-popover aria-label="Specification details" description="Additional specification details."></p-popover>
+```
+
+#### ✅ Recommended
+
+```html
+<p-popover [aria]="{'aria-label': 'Specification details'}" description="Additional specification details."></p-popover>
+```
+
+### Custom slotted trigger without accessible name
+
+#### ❌ Anti-pattern
+
+```html
+<p-popover>
+  <button slot="button" type="button"></button>
+  Additional specification details.
+</p-popover>
+```
+
+#### ✅ Recommended
+
+```html
+<p-popover description="Additional specification details."></p-popover>
+
+<!-- or provide an accessible name on a custom slotted button -->
+
+<p-popover>
+  <button slot="button" type="button" ariaLabel="Specification details">
+    i
+  </button>
+  Additional specification details.
+</p-popover>
+```
+
+### Custom slotted trigger without aria-expanded
+
+#### ❌ Anti-pattern
+
+```html
+<p-popover>
+  <button slot="button" type="button"></button>
+</p-popover>
+```
+
+#### ✅ Recommended
+
+```html
+<p-popover>
+  <button slot="button" type="button" ariaExpanded="false"></button>
+</p-popover>
+```

package/{skill → skills/pds-knowledge-angular}/references/components/p-popover/p-popover.md

@@ -65,6 +65,10 @@ In **controlled** mode the consumer owns the `open` state, so the slotted trigge
 - **Don't** use an unnamed custom slotted trigger button.
 - **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

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

@@ -0,0 +1,63 @@
+# p-radio-group accessibility integration examples
+
+## Integration examples
+
+### Missing group label
+
+#### ❌ Anti-pattern
+
+```html
+<p-radio-group name="fuel">
+  <p-radio-group-option value="electric" label="Electric"></p-radio-group-option>
+  <p-radio-group-option value="hybrid" label="Hybrid"></p-radio-group-option>
+</p-radio-group>
+```
+
+#### ✅ Recommended
+
+```html
+<p-radio-group label="Powertrain" name="fuel" description="Select your preferred powertrain.">
+  <p-radio-group-option value="electric" label="Electric"></p-radio-group-option>
+  <p-radio-group-option value="hybrid" label="Hybrid"></p-radio-group-option>
+</p-radio-group>
+```
+
+### Hidden label without accessible name
+
+#### ❌ Anti-pattern
+
+```html
+<p-radio-group name="fuel" [hideLabel]="true">
+  <p-radio-group-option value="electric" label="Electric"></p-radio-group-option>
+  <p-radio-group-option value="hybrid" label="Hybrid"></p-radio-group-option>
+</p-radio-group>
+```
+
+#### ✅ Recommended
+
+```html
+<p-radio-group label="Powertrain" name="fuel" [hideLabel]="true">
+  <p-radio-group-option value="electric" label="Electric"></p-radio-group-option>
+  <p-radio-group-option value="hybrid" label="Hybrid"></p-radio-group-option>
+</p-radio-group>
+```
+
+### Validation feedback via state and message API
+
+#### ❌ Anti-pattern
+
+```html
+<p-radio-group label="Powertrain" name="fuel" [aria-invalid]="true" message="Required">
+  <p-radio-group-option value="electric" label="Electric"></p-radio-group-option>
+  <p-radio-group-option value="hybrid" label="Hybrid"></p-radio-group-option>
+</p-radio-group>
+```
+
+#### ✅ Recommended
+
+```html
+<p-radio-group label="Powertrain" name="fuel" [required]="true" state="error" message="Select a powertrain to continue.">
+  <p-radio-group-option value="electric" label="Electric"></p-radio-group-option>
+  <p-radio-group-option value="hybrid" label="Hybrid"></p-radio-group-option>
+</p-radio-group>
+```

package/{skill → skills/pds-knowledge-angular}/references/components/p-radio-group/p-radio-group.md

@@ -70,6 +70,10 @@ In general, avoid using the `disabled` state. Disabled elements are no longer fo
 - **Don't** rely on adjacent text instead of the group `label` prop.
 - **Don't** use `hide-label` without an accessible name.
 
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
 ## Tests
 
 ### Automated

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

@@ -0,0 +1,31 @@
+# p-scroller accessibility integration examples
+
+## Integration examples
+
+### ARIA on component host vs aria prop
+
+#### ❌ Anti-pattern
+
+```html
+<p-scroller aria-label="Section tags" aria-description="Section tags for the section overview">
+  <p-tag>
+    Overview
+  </p-tag>
+  <p-tag>
+    Equipment
+  </p-tag>
+</p-scroller>
+```
+
+#### ✅ Recommended
+
+```html
+<p-scroller [aria]="{'aria-label': 'Section tags', 'aria-description': 'Section tags for the section overview'}">
+  <p-tag>
+    Overview
+  </p-tag>
+  <p-tag>
+    Equipment
+  </p-tag>
+</p-scroller>
+```

package/{skill → skills/pds-knowledge-angular}/references/components/p-scroller/p-scroller.md

@@ -57,6 +57,10 @@ If the `p-scroller` component is accessed by keyboard navigation and is focused,
 - **Do** pass `aria-label` and `aria-description` via the `aria` prop, not as host attributes.
 - **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

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

@@ -0,0 +1,67 @@
+# p-segmented-control accessibility integration examples
+
+## Integration examples
+
+### Missing group label
+
+#### ❌ Anti-pattern
+
+```html
+<p-segmented-control name="size">
+  <p-segmented-control-item value="s">
+    S
+  </p-segmented-control-item>
+  <p-segmented-control-item value="m">
+    M
+  </p-segmented-control-item>
+</p-segmented-control>
+```
+
+#### ✅ Recommended
+
+```html
+<p-segmented-control label="T-shirt size" name="size" description="Select your preferred size.">
+  <p-segmented-control-item value="s">
+    S
+  </p-segmented-control-item>
+  <p-segmented-control-item value="m">
+    M
+  </p-segmented-control-item>
+</p-segmented-control>
+```
+
+### Hidden label without accessible name
+
+#### ❌ Anti-pattern
+
+```html
+<p-segmented-control name="size" [hideLabel]="true">
+  <p-segmented-control-item value="s">
+    S
+  </p-segmented-control-item>
+</p-segmented-control>
+```
+
+#### ✅ Recommended
+
+```html
+<p-segmented-control label="T-shirt size" name="size" [hideLabel]="true">
+  <p-segmented-control-item value="s">
+    S
+  </p-segmented-control-item>
+</p-segmented-control>
+```
+
+### Validation feedback via state and message API
+
+#### ❌ Anti-pattern
+
+```html
+<p-segmented-control label="T-shirt size" name="size" [aria-invalid]="true" message="Required"></p-segmented-control>
+```
+
+#### ✅ Recommended
+
+```html
+<p-segmented-control label="T-shirt size" name="size" [required]="true" state="error" message="Select a size to continue."></p-segmented-control>
+```

package/{skill → skills/pds-knowledge-angular}/references/components/p-segmented-control/p-segmented-control.md

@@ -86,6 +86,10 @@ In general, avoid using the `disabled` state. Disabled elements are no longer fo
 - **Don't** add native `aria-*` attributes directly on the component host.
 - **Don't** use `hide-label` without an accessible name.
 
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
 ## API
 
 ### Properties

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

@@ -0,0 +1,140 @@
+# p-select accessibility integration examples
+
+## Integration examples
+
+### Prompt option used instead of a label
+
+#### ❌ Anti-pattern
+
+```html
+<p-select name="model">
+  <p-select-option value="">
+    Select a model
+  </p-select-option>
+  <p-select-option value="carrera">
+    911 Carrera
+  </p-select-option>
+  <p-select-option value="carrera-s">
+    911 Carrera S
+  </p-select-option>
+</p-select>
+```
+
+#### ✅ Recommended
+
+```html
+<p-select label="Porsche model" name="model" description="Choose the model for your configuration.">
+  <p-select-option value="carrera">
+    911 Carrera
+  </p-select-option>
+  <p-select-option value="carrera-s">
+    911 Carrera S
+  </p-select-option>
+</p-select>
+```
+
+### Ambiguous option labels without field context
+
+#### ❌ Anti-pattern
+
+```html
+<p-select label="Model" name="model">
+  <p-select-option value="base">
+    Base
+  </p-select-option>
+  <p-select-option value="s">
+    S
+  </p-select-option>
+</p-select>
+```
+
+#### ✅ Recommended
+
+```html
+<p-select label="Porsche 911 trim" name="model" description="Select the trim level for your configuration.">
+  <p-select-option value="carrera">
+    911 Carrera
+  </p-select-option>
+  <p-select-option value="carrera-s">
+    911 Carrera S
+  </p-select-option>
+</p-select>
+```
+
+### Hidden label without accessible name
+
+#### ❌ Anti-pattern
+
+```html
+<p-select name="model" [hideLabel]="true">
+  <p-select-option value="carrera">
+    911 Carrera
+  </p-select-option>
+</p-select>
+```
+
+#### ✅ Recommended
+
+```html
+<p-select label="Porsche model" name="model" [hideLabel]="true">
+  <p-select-option value="carrera">
+    911 Carrera
+  </p-select-option>
+</p-select>
+```
+
+### Validation feedback via state and message API
+
+#### ❌ Anti-pattern
+
+```html
+<p-select label="Porsche model" name="model" [aria-invalid]="true" message="Required">
+  <p-select-option value="carrera">
+    911 Carrera
+  </p-select-option>
+  <p-select-option value="carrera-s">
+    911 Carrera S
+  </p-select-option>
+</p-select>
+```
+
+#### ✅ Recommended
+
+```html
+<p-select label="Porsche model" name="model" state="error" message="Select a model to continue with your configuration.">
+  <p-select-option value="carrera">
+    911 Carrera
+  </p-select-option>
+  <p-select-option value="carrera-s">
+    911 Carrera S
+  </p-select-option>
+</p-select>
+```
+
+### Error state without recovery guidance
+
+#### ❌ Anti-pattern
+
+```html
+<p-select label="Porsche model" name="model" state="error" message="Invalid">
+  <p-select-option value="carrera">
+    911 Carrera
+  </p-select-option>
+  <p-select-option value="carrera-s">
+    911 Carrera S
+  </p-select-option>
+</p-select>
+```
+
+#### ✅ Recommended
+
+```html
+<p-select label="Porsche model" name="model" [required]="true" state="error" message="Select a Porsche model. This field is required to continue.">
+  <p-select-option value="carrera">
+    911 Carrera
+  </p-select-option>
+  <p-select-option value="carrera-s">
+    911 Carrera S
+  </p-select-option>
+</p-select>
+```