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

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

@@ -0,0 +1,45 @@
+# p-input-text accessibility integration examples
+
+## Integration examples
+
+### Placeholder used as the only label
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInputText name="email" placeholder="Email"></PInputText>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInputText name="email" label="Email address" description="We use this to send your confirmation."></PInputText>
+```
+
+### Hidden label without accessible name
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInputText name="reference" hideLabel={true}></PInputText>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInputText name="reference" hideLabel={true} label="Order reference"></PInputText>
+```
+
+### Validation feedback via state and message API
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInputText name="email" label="Email" aria-invalid={true} message="Invalid"></PInputText>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInputText name="email" label="Email address" state="error" message="Enter a valid email address, for example name@example.com."></PInputText>
+```

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

@@ -88,6 +88,10 @@ Due to the nature of **Web Components** and **shadow DOM**, there are limitation
 | `aria-labelledby` | 🚫 |
 | `aria-describedby` | 🚫 |
 
+## 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-input-time/accessibility.md

@@ -0,0 +1,45 @@
+# p-input-time accessibility integration examples
+
+## Integration examples
+
+### Placeholder used as the only label
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInputTime name="time" placeholder="Time"></PInputTime>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInputTime name="time" label="Appointment time" description="Use 24-hour format, for example 14:30."></PInputTime>
+```
+
+### Hidden label without accessible name
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInputTime name="time" hideLabel={true}></PInputTime>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInputTime name="time" hideLabel={true} label="Appointment time"></PInputTime>
+```
+
+### Validation feedback via state and message API
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInputTime name="time" label="Appointment time" aria-invalid={true} message="Invalid"></PInputTime>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInputTime name="time" label="Appointment time" state="error" message="Enter a valid appointment time."></PInputTime>
+```

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

@@ -85,6 +85,10 @@ Due to the nature of **Web Components** and **shadow DOM**, there are limitation
 | `aria-labelledby` | 🚫 |
 | `aria-describedby` | 🚫 |
 
+## 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-input-url/accessibility.md

@@ -0,0 +1,45 @@
+# p-input-url accessibility integration examples
+
+## Integration examples
+
+### Placeholder used as the only label
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInputUrl name="website" placeholder="https://"></PInputUrl>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInputUrl name="website" label="Website URL" description="Include https:// at the beginning."></PInputUrl>
+```
+
+### Hidden label without accessible name
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInputUrl name="website" hideLabel={true}></PInputUrl>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInputUrl name="website" hideLabel={true} label="Website URL"></PInputUrl>
+```
+
+### Validation feedback via state and message API
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInputUrl name="website" label="Website URL" aria-invalid={true} message="Invalid"></PInputUrl>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInputUrl name="website" label="Website URL" state="error" message="Enter a valid URL, for example https://www.porsche.com."></PInputUrl>
+```

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

@@ -84,6 +84,10 @@ Due to the nature of **Web Components** and **shadow DOM**, there are limitation
 | `aria-labelledby` | 🚫 |
 | `aria-describedby` | 🚫 |
 
+## 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-input-week/accessibility.md

@@ -0,0 +1,45 @@
+# p-input-week accessibility integration examples
+
+## Integration examples
+
+### Placeholder used as the only label
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInputWeek name="week" placeholder="Week"></PInputWeek>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInputWeek name="week" label="Calendar week" description="Select the week for your test drive."></PInputWeek>
+```
+
+### Hidden label without accessible name
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInputWeek name="week" hideLabel={true}></PInputWeek>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInputWeek name="week" hideLabel={true} label="Calendar week"></PInputWeek>
+```
+
+### Validation feedback via state and message API
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInputWeek name="week" label="Calendar week" aria-invalid={true} message="Required"></PInputWeek>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInputWeek name="week" label="Calendar week" state="error" message="Select a calendar week to continue."></PInputWeek>
+```

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

@@ -83,6 +83,10 @@ Due to the nature of **Web Components** and **shadow DOM**, there are limitation
 | `aria-labelledby` | 🚫 |
 | `aria-describedby` | 🚫 |
 
+## 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-link/accessibility.md

@@ -0,0 +1,73 @@
+# p-link accessibility integration examples
+
+## Integration examples
+
+### ARIA on component host vs aria prop
+
+#### ❌ Anti-pattern
+
+```tsx
+<PLink href="https://porsche.com" aria-label="Details of product XYZ">
+  Details
+</PLink>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PLink href="https://porsche.com" aria={{'aria-label': 'Details of product XYZ'}}>
+  Details
+</PLink>
+```
+
+### Icon-only link without accessible name
+
+#### ❌ Anti-pattern
+
+```tsx
+<PLink icon="arrow-right" href="https://porsche.com"></PLink>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PLink icon="arrow-right" hideLabel={true} href="https://porsche.com">
+  Product details
+</PLink>
+```
+
+### Indicating the current page
+
+#### ❌ Anti-pattern
+
+```tsx
+<PLink href="/models/911" aria-current="page">
+  911
+</PLink>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PLink href="/models/911" aria={{'aria-current': 'page'}}>
+  911 Carrera
+</PLink>
+```
+
+### Vague link label without context
+
+#### ❌ Anti-pattern
+
+```tsx
+<PLink href="https://porsche.com">
+  Show
+</PLink>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PLink href="https://porsche.com" aria={{'aria-label': 'Show details of product XYZ'}}>
+  Show details
+</PLink>
+```

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

@@ -69,6 +69,10 @@ If the text of a link does not clearly indicate what the link's target is, add a
 - **Don't** add native `aria-*` attributes directly on the component host.
 - **Don't** rely on short generic link labels like "Show" or "Add" without context.
 
+## 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-link-pure/accessibility.md

@@ -0,0 +1,73 @@
+# p-link-pure accessibility integration examples
+
+## Integration examples
+
+### ARIA on component host vs aria prop
+
+#### ❌ Anti-pattern
+
+```tsx
+<PLinkPure href="https://porsche.com" aria-label="Details of product XYZ">
+  Details
+</PLinkPure>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PLinkPure href="https://porsche.com" aria={{'aria-label': 'Details of product XYZ'}}>
+  Details
+</PLinkPure>
+```
+
+### Icon-only link without accessible name
+
+#### ❌ Anti-pattern
+
+```tsx
+<PLinkPure icon="arrow-right" href="https://porsche.com"></PLinkPure>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PLinkPure icon="arrow-right" hideLabel={true} href="https://porsche.com">
+  Product details
+</PLinkPure>
+```
+
+### Indicating the current page
+
+#### ❌ Anti-pattern
+
+```tsx
+<PLinkPure href="/models/911" aria-current="page">
+  911
+</PLinkPure>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PLinkPure href="/models/911" aria={{'aria-current': 'page'}}>
+  911 Carrera
+</PLinkPure>
+```
+
+### Vague link label without context
+
+#### ❌ Anti-pattern
+
+```tsx
+<PLinkPure href="https://porsche.com">
+  Show
+</PLinkPure>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PLinkPure href="https://porsche.com" aria={{'aria-label': 'Show details of product XYZ'}}>
+  Show details
+</PLinkPure>
+```

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

@@ -72,6 +72,10 @@ If the text of a link does not clearly indicate what the link's target is, add a
 - **Don't** add native `aria-*` attributes directly on the component host.
 - **Don't** rely on short generic link labels like "Show" or "Add" without context.
 
+## 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-link-tile/accessibility.md

@@ -0,0 +1,31 @@
+# p-link-tile accessibility integration examples
+
+## Integration examples
+
+### ARIA on component host vs aria prop
+
+#### ❌ Anti-pattern
+
+```tsx
+<PLinkTile label="Details" href="#" aria-label="Details of Porsche Taycan"></PLinkTile>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PLinkTile label="Details" href="#" aria={{'aria-label': 'Details of Porsche Taycan'}}></PLinkTile>
+```
+
+### Vague link label without context
+
+#### ❌ Anti-pattern
+
+```tsx
+<PLinkTile label="Details" href="#"></PLinkTile>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PLinkTile label="Porsche Taycan details" href="#"></PLinkTile>
+```

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

@@ -65,6 +65,10 @@ If the text of a link does not clearly indicate what the link's target is, add a
 - **Do** add `aria-label` on slotted `<video>` elements used as backgrounds.
 - **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-modal/accessibility.md

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

package/{skill → skills/pds-knowledge-react}/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-react/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
+
+```tsx
+<PMultiSelect name="features">
+  <PMultiSelectOption value="">
+    Select features
+  </PMultiSelectOption>
+  <PMultiSelectOption value="sport">
+    Sport Chrono Package
+  </PMultiSelectOption>
+</PMultiSelect>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PMultiSelect label="Optional features" name="features" description="Select all features for your configuration.">
+  <PMultiSelectOption value="sport">
+    Sport Chrono Package
+  </PMultiSelectOption>
+  <PMultiSelectOption value="audio">
+    BOSE Surround Sound
+  </PMultiSelectOption>
+</PMultiSelect>
+```
+
+### Hidden label without accessible name
+
+#### ❌ Anti-pattern
+
+```tsx
+<PMultiSelect name="features" hideLabel={true}>
+  <PMultiSelectOption value="sport">
+    Sport Chrono Package
+  </PMultiSelectOption>
+</PMultiSelect>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PMultiSelect label="Optional features" name="features" hideLabel={true}>
+  <PMultiSelectOption value="sport">
+    Sport Chrono Package
+  </PMultiSelectOption>
+</PMultiSelect>
+```
+
+### Validation feedback via state and message API
+
+#### ❌ Anti-pattern
+
+```tsx
+<PMultiSelect label="Optional features" name="features" aria-invalid={true} message="Required">
+  <PMultiSelectOption value="sport">
+    Sport Chrono Package
+  </PMultiSelectOption>
+</PMultiSelect>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PMultiSelect label="Optional features" name="features" required={true} state="error" message="Select at least one feature to continue.">
+  <PMultiSelectOption value="sport">
+    Sport Chrono Package
+  </PMultiSelectOption>
+  <PMultiSelectOption value="audio">
+    BOSE Surround Sound
+  </PMultiSelectOption>
+</PMultiSelect>
+```

package/{skill → skills/pds-knowledge-react}/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-react/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
+
+```tsx
+<html lang="de_DE">
+  ...
+  <PPagination totalItemsCount={120} itemsPerPage={10} activePage={1}></PPagination>
+</html>
+```
+
+#### ✅ Recommended
+
+```tsx
+<html lang="de_DE">
+  ...
+  <PPagination totalItemsCount={120} itemsPerPage={10} activePage={1} intl={{'root': 'Seitennavigation', 'prev': 'Vorherige Seite', 'next': 'Nächste Seite', 'page': 'Seite'}}></PPagination>
+</html>
+```

package/{skill → skills/pds-knowledge-react}/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