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

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

@@ -0,0 +1,37 @@
+# p-fieldset accessibility integration examples
+
+## Integration examples
+
+### Unlabeled field group
+
+#### ❌ Anti-pattern
+
+```tsx
+<PFieldset>
+  <PInputText name="street" label="Street"></PInputText>
+  <PInputText name="city" label="City"></PInputText>
+</PFieldset>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PFieldset label="Delivery address">
+  <PInputText name="street" label="Street"></PInputText>
+  <PInputText name="city" label="City"></PInputText>
+</PFieldset>
+```
+
+### Error state without recovery guidance
+
+#### ❌ Anti-pattern
+
+```tsx
+<PFieldset label="Delivery address" state="error" message="Invalid"></PFieldset>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PFieldset label="Delivery address" required={true} state="error" message="Complete all required address fields to continue."></PFieldset>
+```

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

@@ -57,6 +57,10 @@ The `p-fieldset` is a grouping component for wrapping contextual associated form
 - **Do** use `aria="{ 'role': 'radiogroup' }"` only when the fieldset contains custom radio controls.
 - **Don't** set `state="error"` without a descriptive `message`.
 
+## 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-flag/accessibility.md

@@ -0,0 +1,39 @@
+# p-flag accessibility integration examples
+
+## Integration examples
+
+### Informative flag without accessible name
+
+#### ❌ Anti-pattern
+
+```tsx
+<PFlag name="germany"></PFlag>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PFlag name="germany" aria={{'aria-label': 'Germany'}}></PFlag>
+```
+
+### Decorative flag with redundant label
+
+#### ❌ Anti-pattern
+
+```tsx
+<PFlag name="germany" aria={{'aria-label': 'Germany'}}></PFlag>
+
+<PText>
+  Germany
+</PText>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PFlag name="germany" ariaHidden={true}></PFlag>
+
+<PText>
+  Germany
+</PText>
+```

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

@@ -42,6 +42,10 @@ The following guidelines provide instructions for designers and developers on th
 - **Do** hide decorative flags from assistive technologies when adjacent text already names the country or region.
 - **Don't** leave informative flags 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-flyout/accessibility.md

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

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

@@ -72,6 +72,10 @@ To inform users that the trigger button opens a `dialog`, set `aria-haspopup` on
 - **Don't** add raw host-level ARIA attributes as a workaround.
 - **Don't** use unclear trigger copy like "Menu" when the flyout 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-heading/accessibility.md

@@ -0,0 +1,29 @@
+# p-heading accessibility integration examples
+
+## Integration examples
+
+### Skipped heading level
+
+#### ❌ Anti-pattern
+
+```tsx
+<PHeading tag="h1" size="xl">
+  Configure your Porsche
+</PHeading>
+
+<PHeading tag="h4" size="md">
+  Delivery options
+</PHeading>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PHeading tag="h1" size="xl">
+  Configure your Porsche
+</PHeading>
+
+<PHeading tag="h2" size="md">
+  Delivery options
+</PHeading>
+```

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

@@ -49,6 +49,10 @@ While using the `Heading` component, take care of the correct heading hierarchy
 - **Don't** choose a heading level based on appearance alone.
 - **Don't** skip heading levels when nesting sections.
 
+## 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-icon/accessibility.md

@@ -0,0 +1,39 @@
+# p-icon accessibility integration examples
+
+## Integration examples
+
+### Meaningful icon without accessible name
+
+#### ❌ Anti-pattern
+
+```tsx
+<PIcon name="warning"></PIcon>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PIcon name="warning" aria={{'aria-label': 'Warning'}}></PIcon>
+```
+
+### Decorative icon with redundant label
+
+#### ❌ Anti-pattern
+
+```tsx
+<PIcon name="phone" aria={{'aria-label': 'Phone'}}></PIcon>
+
+<PText>
+  +49 711 911 0
+</PText>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PIcon ariaHidden={true} name="phone"></PIcon>
+
+<PText>
+  +49 711 911 0
+</PText>
+```

package/{skill → skills/pds-knowledge-react}/references/components/p-icon/examples/Overview.tsx

@@ -166,6 +166,8 @@ export const Example = () => {
 
       <PIcon name="configurate" aria={{'aria-label': 'Configurate icon'}}></PIcon>
 
+      <PIcon name="connect-services" aria={{'aria-label': 'Connect Services icon'}}></PIcon>
+
       <PIcon name="copy" aria={{'aria-label': 'Copy icon'}}></PIcon>
 
       <PIcon name="country-road" aria={{'aria-label': 'Country Road icon'}}></PIcon>
@@ -174,6 +176,8 @@ export const Example = () => {
 
       <PIcon name="cubic-capacity" aria={{'aria-label': 'Cubic Capacity icon'}}></PIcon>
 
+      <PIcon name="customer-support" aria={{'aria-label': 'Customer Support icon'}}></PIcon>
+
       <PIcon name="cut" aria={{'aria-label': 'Cut icon'}}></PIcon>
 
       <PIcon name="delete" aria={{'aria-label': 'Delete icon'}}></PIcon>
@@ -492,6 +496,8 @@ export const Example = () => {
 
       <PIcon name="shopping-cart-filled" aria={{'aria-label': 'Shopping Cart Filled icon'}}></PIcon>
 
+      <PIcon name="shopping-cart-off" aria={{'aria-label': 'Shopping Cart Off icon'}}></PIcon>
+
       <PIcon name="sidebar" aria={{'aria-label': 'Sidebar icon'}}></PIcon>
 
       <PIcon name="sidelights" aria={{'aria-label': 'Sidelights icon'}}></PIcon>

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

@@ -39,6 +39,10 @@ Sometimes icons are used purely for **decorative purposes** and do not convey an
 - **Do** hide decorative icons from assistive technologies when adjacent text provides the meaning.
 - **Don't** add redundant `aria-label` to decorative icons beside visible text.
 
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
 ## Tests
 
 ### Automated
@@ -63,7 +67,7 @@ Sometimes icons are used purely for **decorative purposes** and do not convey an
 | --- | --- | --- | --- |
 | `aria` | `IconAriaAttribute` | `undefined` | Sets ARIA attributes on the icon — use `aria-label` to make the icon meaningful to screen readers when it conveys information. |
 | `color` | `'primary'` `'contrast-higher'` `'contrast-high'` `'contrast-medium'` `'contrast-low'` `'contrast-lower'` `'success'` `'warning'` `'error'` `'info'` `'inherit'` | `'primary'` | Sets the fill color of the icon using PDS color tokens. |
-| `name` | one of 290 icon names — see [icon names](references/icons.md) | `'arrow-right'` | Selects an icon from the built-in PDS icon library by name (e.g. `arrow-right`, `close`). |
+| `name` | one of 293 icon names — see [icon names](references/icons.md) | `'arrow-right'` | Selects an icon from the built-in PDS icon library by name (e.g. `arrow-right`, `close`). |
 | `size` | `'2xs'` `'xs'` `'sm'` `'md'` `'lg'` `'xl'` `'2xl'` `'3xl'` `'4xl'` `'5xl'` `'inherit'`<br>_deprecated:_ `'xx-small'` `'x-small'` `'small'` `'medium'` `'large'` `'x-large'` `'xx-large'`<br>`BreakpointCustomizable<IconSize>` | `'sm'` | Sets the icon size using the PDS typographic scale. Use `inherit` to derive size from the parent element. Supports responsive breakpoint values. |
 | `source` | `string` | `undefined` | Sets a path to a custom SVG icon, used instead of the built-in icon library. |
 

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

@@ -0,0 +1,36 @@
+# p-inline-notification accessibility integration examples
+
+## Integration examples
+
+### Notification mounted only when needed
+
+#### ❌ Anti-pattern
+
+```tsx
+{hasWarning && <PInlineNotification state="warning" description="Warning" />}
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInlineNotification
+  id="account-warning"
+  state="warning"
+  heading="Verify your email address"
+  description="Confirm your email to receive order updates."
+/>
+```
+
+### Warning without descriptive heading
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInlineNotification state="warning" description="Something went wrong"></PInlineNotification>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInlineNotification state="warning" heading="Delivery date unavailable" description="Choose another date or contact your Porsche Centre."></PInlineNotification>
+```

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

@@ -36,13 +36,17 @@ The `Inline Notification` component uses `role="status"` and `role="alert"` to a
 - **Do** use `state="warning"` or `state="error"` with descriptive content for urgent issues.
 - **Don't** conditionally mount the component only when an alert should be announced.
 
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
 ## API
 
 ### Properties
 
 | Property | Type | Default | Description |
 | --- | --- | --- | --- |
-| `actionIcon` | `''`<br>one of 290 icon names — see [icon names](references/icons.md) | `'arrow-right'` | Sets the icon displayed inside the action button using a PDS icon name. |
+| `actionIcon` | `''`<br>one of 293 icon names — see [icon names](references/icons.md) | `'arrow-right'` | Sets the icon displayed inside the action button using a PDS icon name. |
 | `actionLabel` | `string` | `undefined` | Sets the label text of the optional action button inside the notification. |
 | `actionLoading` | `boolean` | `false` | Disables the action button and shows a spinner to indicate an ongoing operation. |
 | `description` | `string` | `''` | Sets the supporting description text shown below the heading. |

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

@@ -0,0 +1,45 @@
+# p-input-date accessibility integration examples
+
+## Integration examples
+
+### Placeholder used as the only label
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInputDate name="birthdate" placeholder="Date of birth"></PInputDate>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInputDate name="birthdate" label="Date of birth" description="Enter day, month, and year."></PInputDate>
+```
+
+### Hidden label without accessible name
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInputDate name="birthdate" hideLabel={true}></PInputDate>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInputDate name="birthdate" hideLabel={true} label="Date of birth"></PInputDate>
+```
+
+### Validation feedback via state and message API
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInputDate name="birthdate" label="Date of birth" aria-invalid={true} message="Invalid"></PInputDate>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInputDate name="birthdate" label="Date of birth" state="error" message="Enter a valid date of birth."></PInputDate>
+```

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

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

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

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

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

@@ -0,0 +1,45 @@
+# p-input-number accessibility integration examples
+
+## Integration examples
+
+### Placeholder used as the only label
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInputNumber name="speed" placeholder="Top speed" unit="kmh"></PInputNumber>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInputNumber name="speed" label="Top speed" unit="kmh" description="Enter the maximum speed in kilometers per hour."></PInputNumber>
+```
+
+### Hidden label without accessible name
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInputNumber name="speed" hideLabel={true}></PInputNumber>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInputNumber name="speed" hideLabel={true} label="Top speed"></PInputNumber>
+```
+
+### Validation feedback via state and message API
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInputNumber name="speed" label="Top speed" aria-invalid={true} message="Invalid"></PInputNumber>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInputNumber name="speed" label="Top speed" unit="kmh" description="Enter the maximum speed in kilometers per hour." state="error" message="Enter a speed between 0 and 350 kilometers per hour."></PInputNumber>
+```

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

@@ -89,6 +89,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
@@ -113,15 +117,15 @@ Due to the nature of **Web Components** and **shadow DOM**, there are limitation
 | `required` | `boolean` | `false` | Marks the field as required — form submission is blocked while this field is empty. |
 | `state` | `'none'` `'error'` `'success'` | `'none'` | Sets the validation state, controlling the visual appearance and style of the feedback message (`none`, `success`, `error`). |
 | `step` | `number` | `1` | Sets the stepping granularity — the value must be a multiple of this number. Also controls step button increment size. |
-| `value` | `string | number | null` | `''` | Sets the current numeric value of the field. |
+| `value` | `string | number | null` | `''` | Sets the current numeric value. Strings and numbers are accepted for programmatic assignment, but user input updates the value as a string to mirror native input behavior. |
 
 ### Events
 
 | Event | Type | Description |
 | --- | --- | --- |
 | `blur` | `CustomEvent<InputNumberBlurEventDetail>`<br>`Event` | Emitted when the number input has lost focus. |
-| `change` | `CustomEvent<InputNumberChangeEventDetail>`<br>`Event` | Emitted when the number input loses focus after its value was changed. |
-| `input` | `CustomEvent<InputNumberInputEventDetail>`<br>`InputEvent` | Emitted when the value has been changed as a direct result of a user action. |
+| `change` | `CustomEvent<InputNumberChangeEventDetail>`<br>`Event` | Emitted when the number input loses focus after its value was changed. The component value and native event target value are strings after user input. |
+| `input` | `CustomEvent<InputNumberInputEventDetail>`<br>`InputEvent` | Emitted when the value has been changed as a direct result of a user action. The component value and native event target value are strings. |
 
 ### Slots
 

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

@@ -0,0 +1,45 @@
+# p-input-password accessibility integration examples
+
+## Integration examples
+
+### Placeholder used as the only label
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInputPassword name="password" placeholder="Password"></PInputPassword>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInputPassword name="password" label="Password" description="Use at least 8 characters with one number."></PInputPassword>
+```
+
+### Hidden label without accessible name
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInputPassword name="password" hideLabel={true}></PInputPassword>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInputPassword name="password" hideLabel={true} label="Password"></PInputPassword>
+```
+
+### Validation feedback via state and message API
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInputPassword name="password" label="Password" aria-invalid={true} message="Invalid"></PInputPassword>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInputPassword name="password" label="Password" state="error" message="Enter a password with at least 8 characters and one number."></PInputPassword>
+```