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

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/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

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,6 +36,10 @@ 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

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

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>
+```

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

@@ -0,0 +1,59 @@
+# p-input-search accessibility integration examples
+
+## Integration examples
+
+### Placeholder used as the only label
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInputSearch name="search" placeholder="Search"></PInputSearch>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInputSearch name="search" label="Search vehicles" description="Search by model name or VIN."></PInputSearch>
+```
+
+### ARIA on component host vs aria prop
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInputSearch name="search" label="Search vehicles" role="combobox" aria-expanded={false} aria-haspopup="listbox"></PInputSearch>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInputSearch name="search" label="Search vehicles" aria={{'role': 'combobox', 'aria-expanded': 'false', 'aria-haspopup': 'listbox'}}></PInputSearch>
+```
+
+### Hidden label without accessible name
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInputSearch name="search" hideLabel={true}></PInputSearch>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInputSearch name="search" hideLabel={true} label="Search vehicles"></PInputSearch>
+```
+
+### Validation feedback via state and message API
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInputSearch name="search" label="Search vehicles" aria-invalid={true} message="Invalid"></PInputSearch>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInputSearch name="search" label="Search vehicles" state="error" message="Enter at least 3 characters to search."></PInputSearch>
+```

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

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

@@ -0,0 +1,45 @@
+# p-input-tel accessibility integration examples
+
+## Integration examples
+
+### Placeholder used as the only label
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInputTel name="phone" placeholder="Phone"></PInputTel>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInputTel name="phone" label="Phone number" description="Include your country code, for example +49."></PInputTel>
+```
+
+### Hidden label without accessible name
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInputTel name="phone" hideLabel={true}></PInputTel>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInputTel name="phone" hideLabel={true} label="Phone number"></PInputTel>
+```
+
+### Validation feedback via state and message API
+
+#### ❌ Anti-pattern
+
+```tsx
+<PInputTel name="phone" label="Phone number" aria-invalid={true} message="Invalid"></PInputTel>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PInputTel name="phone" label="Phone number" state="error" message="Enter a valid phone number including your country code."></PInputTel>
+```

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