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

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

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

package/{skill → skills/pds-knowledge-react}/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-react/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
+
+```tsx
+<PPopover aria-label="Specification details" description="Additional specification details."></PPopover>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PPopover aria={{'aria-label': 'Specification details'}} description="Additional specification details."></PPopover>
+```
+
+### Custom slotted trigger without accessible name
+
+#### ❌ Anti-pattern
+
+```tsx
+<PPopover>
+  <button slot="button" type="button"></button>
+  Additional specification details.
+</PPopover>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PPopover description="Additional specification details."></PPopover>
+
+{/* or provide an accessible name on a custom slotted button */}
+
+<PPopover>
+  <button slot="button" type="button" ariaLabel="Specification details">
+    i
+  </button>
+  Additional specification details.
+</PPopover>
+```
+
+### Custom slotted trigger without aria-expanded
+
+#### ❌ Anti-pattern
+
+```tsx
+<PPopover>
+  <button slot="button" type="button"></button>
+</PPopover>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PPopover>
+  <button slot="button" type="button" ariaExpanded="false"></button>
+</PPopover>
+```

package/{skill → skills/pds-knowledge-react}/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-react/references/components/p-radio-group/accessibility.md

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

package/{skill → skills/pds-knowledge-react}/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-react/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
+
+```tsx
+<PScroller aria-label="Section tags" aria-description="Section tags for the section overview">
+  <PTag>
+    Overview
+  </PTag>
+  <PTag>
+    Equipment
+  </PTag>
+</PScroller>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PScroller aria={{'aria-label': 'Section tags', 'aria-description': 'Section tags for the section overview'}}>
+  <PTag>
+    Overview
+  </PTag>
+  <PTag>
+    Equipment
+  </PTag>
+</PScroller>
+```

package/{skill → skills/pds-knowledge-react}/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-react/references/components/p-segmented-control/accessibility.md

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

package/{skill → skills/pds-knowledge-react}/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-react/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
+
+```tsx
+<PSelect name="model">
+  <PSelectOption value="">
+    Select a model
+  </PSelectOption>
+  <PSelectOption value="carrera">
+    911 Carrera
+  </PSelectOption>
+  <PSelectOption value="carrera-s">
+    911 Carrera S
+  </PSelectOption>
+</PSelect>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PSelect label="Porsche model" name="model" description="Choose the model for your configuration.">
+  <PSelectOption value="carrera">
+    911 Carrera
+  </PSelectOption>
+  <PSelectOption value="carrera-s">
+    911 Carrera S
+  </PSelectOption>
+</PSelect>
+```
+
+### Ambiguous option labels without field context
+
+#### ❌ Anti-pattern
+
+```tsx
+<PSelect label="Model" name="model">
+  <PSelectOption value="base">
+    Base
+  </PSelectOption>
+  <PSelectOption value="s">
+    S
+  </PSelectOption>
+</PSelect>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PSelect label="Porsche 911 trim" name="model" description="Select the trim level for your configuration.">
+  <PSelectOption value="carrera">
+    911 Carrera
+  </PSelectOption>
+  <PSelectOption value="carrera-s">
+    911 Carrera S
+  </PSelectOption>
+</PSelect>
+```
+
+### Hidden label without accessible name
+
+#### ❌ Anti-pattern
+
+```tsx
+<PSelect name="model" hideLabel={true}>
+  <PSelectOption value="carrera">
+    911 Carrera
+  </PSelectOption>
+</PSelect>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PSelect label="Porsche model" name="model" hideLabel={true}>
+  <PSelectOption value="carrera">
+    911 Carrera
+  </PSelectOption>
+</PSelect>
+```
+
+### Validation feedback via state and message API
+
+#### ❌ Anti-pattern
+
+```tsx
+<PSelect label="Porsche model" name="model" aria-invalid={true} message="Required">
+  <PSelectOption value="carrera">
+    911 Carrera
+  </PSelectOption>
+  <PSelectOption value="carrera-s">
+    911 Carrera S
+  </PSelectOption>
+</PSelect>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PSelect label="Porsche model" name="model" state="error" message="Select a model to continue with your configuration.">
+  <PSelectOption value="carrera">
+    911 Carrera
+  </PSelectOption>
+  <PSelectOption value="carrera-s">
+    911 Carrera S
+  </PSelectOption>
+</PSelect>
+```
+
+### Error state without recovery guidance
+
+#### ❌ Anti-pattern
+
+```tsx
+<PSelect label="Porsche model" name="model" state="error" message="Invalid">
+  <PSelectOption value="carrera">
+    911 Carrera
+  </PSelectOption>
+  <PSelectOption value="carrera-s">
+    911 Carrera S
+  </PSelectOption>
+</PSelect>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PSelect label="Porsche model" name="model" required={true} state="error" message="Select a Porsche model. This field is required to continue.">
+  <PSelectOption value="carrera">
+    911 Carrera
+  </PSelectOption>
+  <PSelectOption value="carrera-s">
+    911 Carrera S
+  </PSelectOption>
+</PSelect>
+```

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

@@ -79,6 +79,10 @@ In general, avoid using the `disabled` state. Disabled elements are no longer fo
 - **Don't** use very short or ambiguous option labels when context is important.
 - **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-react/references/components/p-sheet/accessibility.md

@@ -0,0 +1,80 @@
+# p-sheet accessibility integration examples
+
+## Integration examples
+
+### ARIA on trigger button host vs aria prop
+
+#### ❌ Anti-pattern
+
+```tsx
+<PButton aria-haspopup="dialog">
+  Filter results
+</PButton>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PButton aria={{'aria-haspopup': 'dialog'}}>
+  Filter results
+</PButton>
+```
+
+### Dialog label on component host vs header slot
+
+#### ❌ Anti-pattern
+
+```tsx
+<PSheet aria-label="Filters">
+  ...
+</PSheet>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PSheet>
+  <PHeading slot="header" tag="h2" size="lg">
+    Filter results
+  </PHeading>
+  ...
+</PSheet>
+
+{/* or with aria prop when no visible header is shown */}
+
+<PSheet aria={{'aria-label': 'Filter results'}}>
+  ...
+</PSheet>
+```
+
+### Sheet trigger without popup semantics
+
+#### ❌ Anti-pattern
+
+```tsx
+<PButton>
+  Open
+</PButton>
+
+<PSheet>
+  <PHeading slot="header" tag="h2" size="lg">
+    Filters
+  </PHeading>
+  ...
+</PSheet>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PButton aria={{'aria-haspopup': 'dialog'}}>
+  Filter results
+</PButton>
+
+<PSheet>
+  <PHeading slot="header" tag="h2" size="lg">
+    Filter results
+  </PHeading>
+  ...
+</PSheet>
+```

package/{skill → skills/pds-knowledge-react}/references/components/p-sheet/p-sheet.md

@@ -75,6 +75,10 @@ Set `aria-haspopup` on the trigger so users know a dialog will open. Ensure the
 - **Don't** add raw host-level ARIA attributes as a workaround.
 - **Don't** use unclear trigger copy like "Open" when the sheet purpose is not obvious.
 
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
 ## API
 
 ### Properties

package/skills/pds-knowledge-react/references/components/p-spinner/accessibility.md

@@ -0,0 +1,31 @@
+# p-spinner accessibility integration examples
+
+## Integration examples
+
+### Spinner mounted only when loading starts
+
+#### ❌ Anti-pattern
+
+```tsx
+{isLoading && <PSpinner />}
+```
+
+#### ✅ Recommended
+
+```tsx
+<PSpinner aria={{'aria-label': 'Loading vehicle configuration'}}></PSpinner>
+```
+
+### Spinner without loading message
+
+#### ❌ Anti-pattern
+
+```tsx
+<PSpinner></PSpinner>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PSpinner aria={{'aria-label': 'Loading vehicle configuration'}}></PSpinner>
+```

package/{skill → skills/pds-knowledge-react}/references/components/p-spinner/p-spinner.md

@@ -54,6 +54,10 @@ To provide feedback to screen reader users, it is mandatory to announce the load
 - **Do** provide a specific loading message through the `aria` prop.
 - **Don't** mount the spinner only at the moment loading starts without a label.
 
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
 ## Notes
 
 ### Disable animation

package/skills/pds-knowledge-react/references/components/p-stepper-horizontal/accessibility.md

@@ -0,0 +1,34 @@
+# p-stepper-horizontal accessibility integration examples
+
+## Integration examples
+
+### Generic step labels without context
+
+#### ❌ Anti-pattern
+
+```tsx
+<PStepperHorizontal>
+  <PStepperHorizontalItem state="complete">
+    Step 1
+  </PStepperHorizontalItem>
+  <PStepperHorizontalItem state="current">
+    Step 2
+  </PStepperHorizontalItem>
+</PStepperHorizontal>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PStepperHorizontal>
+  <PStepperHorizontalItem state="complete">
+    Configure vehicle
+  </PStepperHorizontalItem>
+  <PStepperHorizontalItem state="current">
+    Choose delivery date
+  </PStepperHorizontalItem>
+  <PStepperHorizontalItem>
+    Review and confirm
+  </PStepperHorizontalItem>
+</PStepperHorizontal>
+```

package/{skill → skills/pds-knowledge-react}/references/components/p-stepper-horizontal/p-stepper-horizontal.md

@@ -60,6 +60,10 @@ By clicking on a previous step, the `p-stepper-horizontal` emits the `update` ev
 - **Do** reflect the current step with the item `state` prop (`current`, `complete`, `warning`).
 - **Don't** use generic labels like "Step 1" without describing the step purpose.
 
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
 ## API
 
 ### Properties