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

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

@@ -0,0 +1,41 @@
+# p-divider accessibility integration examples
+
+## Integration examples
+
+### Divider as the only section separator
+
+#### ❌ Anti-pattern
+
+```html
+<p-text>
+  Delivery details
+</p-text>
+
+<p-divider></p-divider>
+
+<p-text>
+  Payment details
+</p-text>
+```
+
+#### ✅ Recommended
+
+```html
+<p-heading tag="h2" size="md">
+  Delivery details
+</p-heading>
+
+<p-text>
+  ...
+</p-text>
+
+<p-divider></p-divider>
+
+<p-heading tag="h2" size="md">
+  Payment details
+</p-heading>
+
+<p-text>
+  ...
+</p-text>
+```

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

@@ -31,6 +31,10 @@ A divider is visual separation only. Use headings, landmarks, or section structu
 - **Do** pair dividers with headings or landmarks that describe the sections they separate.
 - **Don't** rely on a divider alone to communicate a new major section.
 
+## 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-drilldown/accessibility.md

@@ -0,0 +1,65 @@
+# p-drilldown accessibility integration examples
+
+## Integration examples
+
+### ARIA on trigger button host vs aria prop
+
+#### ❌ Anti-pattern
+
+```html
+<p-button aria-haspopup="dialog">
+  Menu
+</p-button>
+```
+
+#### ✅ Recommended
+
+```html
+<p-button [aria]="{'aria-haspopup': 'dialog'}">
+  Vehicle menu
+</p-button>
+```
+
+### Drilldown label on component host vs aria prop
+
+#### ❌ Anti-pattern
+
+```html
+<p-drilldown [open]="true" aria-label="Navigation">
+  ...
+</p-drilldown>
+```
+
+#### ✅ Recommended
+
+```html
+<p-drilldown [open]="true" [aria]="{'aria-label': 'Vehicle navigation'}">
+  ...
+</p-drilldown>
+```
+
+### Trigger without popup semantics or context
+
+#### ❌ Anti-pattern
+
+```html
+<p-button>
+  Menu
+</p-button>
+
+<p-drilldown>
+  ...
+</p-drilldown>
+```
+
+#### ✅ Recommended
+
+```html
+<p-button [aria]="{'aria-haspopup': 'dialog'}">
+  Vehicle menu
+</p-button>
+
+<p-drilldown [aria]="{'aria-label': 'Vehicle navigation'}">
+  ...
+</p-drilldown>
+```

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

@@ -74,6 +74,10 @@ To inform users that the trigger button opens a `dialog`, the `aria-haspopup` at
 - **Do** provide a meaningful dialog label through the drilldown `aria` prop when needed.
 - **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-fieldset/accessibility.md

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

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

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

package/{skill → skills/pds-knowledge-angular}/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-angular/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
+
+```html
+<p-button aria-haspopup="dialog">
+  Open dialog
+</p-button>
+```
+
+#### ✅ Recommended
+
+```html
+<p-button [aria]="{'aria-haspopup': 'dialog'}">
+  Open dialog
+</p-button>
+```
+
+### Dialog label on component host vs header slot
+
+#### ❌ Anti-pattern
+
+```html
+<p-flyout aria-label="Navigation">
+  ...
+</p-flyout>
+```
+
+#### ✅ Recommended
+
+```html
+<p-flyout>
+  <p-heading slot="header" tag="h2" size="lg">
+    Main navigation
+  </p-heading>
+  ...
+</p-flyout>
+
+<!-- or with aria prop when no visible header is shown -->
+
+<p-flyout [aria]="{'aria-label': 'Main navigation'}">
+  ...
+</p-flyout>
+```
+
+### Flyout trigger without popup semantics
+
+#### ❌ Anti-pattern
+
+```html
+<p-button>
+  Open dialog
+</p-button>
+
+<p-flyout>
+  <p-heading slot="header" tag="h2" size="lg">
+    Dialog heading
+  </p-heading>
+  ...
+</p-flyout>
+```
+
+#### ✅ Recommended
+
+```html
+<p-button [aria]="{'aria-haspopup': 'dialog'}">
+  Open dialog
+</p-button>
+
+<p-flyout>
+  <p-heading slot="header" tag="h2" size="lg">
+    Dialog heading
+  </p-heading>
+  ...
+</p-flyout>
+```

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

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

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

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

package/{skill → skills/pds-knowledge-angular}/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-angular/references/components/p-inline-notification/accessibility.md

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

package/{skill → skills/pds-knowledge-angular}/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-angular/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
+
+```html
+<p-input-date name="birthdate" placeholder="Date of birth"></p-input-date>
+```
+
+#### ✅ Recommended
+
+```html
+<p-input-date name="birthdate" label="Date of birth" description="Enter day, month, and year."></p-input-date>
+```
+
+### Hidden label without accessible name
+
+#### ❌ Anti-pattern
+
+```html
+<p-input-date name="birthdate" [hideLabel]="true"></p-input-date>
+```
+
+#### ✅ Recommended
+
+```html
+<p-input-date name="birthdate" [hideLabel]="true" label="Date of birth"></p-input-date>
+```
+
+### Validation feedback via state and message API
+
+#### ❌ Anti-pattern
+
+```html
+<p-input-date name="birthdate" label="Date of birth" [aria-invalid]="true" message="Invalid"></p-input-date>
+```
+
+#### ✅ Recommended
+
+```html
+<p-input-date name="birthdate" label="Date of birth" state="error" message="Enter a valid date of birth."></p-input-date>
+```

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

@@ -79,6 +79,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-angular/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
+
+```html
+<p-input-email name="email" placeholder="Email"></p-input-email>
+```
+
+#### ✅ Recommended
+
+```html
+<p-input-email name="email" label="Email address" description="We use this to send your confirmation."></p-input-email>
+```
+
+### Hidden label without accessible name
+
+#### ❌ Anti-pattern
+
+```html
+<p-input-email name="email" [hideLabel]="true"></p-input-email>
+```
+
+#### ✅ Recommended
+
+```html
+<p-input-email name="email" [hideLabel]="true" label="Email address"></p-input-email>
+```
+
+### Validation feedback via state and message API
+
+#### ❌ Anti-pattern
+
+```html
+<p-input-email name="email" label="Email" [aria-invalid]="true" message="Invalid"></p-input-email>
+```
+
+#### ✅ Recommended
+
+```html
+<p-input-email name="email" label="Email address" state="error" message="Enter a valid email address, for example name@example.com."></p-input-email>
+```

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

@@ -80,6 +80,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-angular/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
+
+```html
+<p-input-month name="month" placeholder="Month"></p-input-month>
+```
+
+#### ✅ Recommended
+
+```html
+<p-input-month name="month" label="Delivery month" description="Select the month for your delivery."></p-input-month>
+```
+
+### Hidden label without accessible name
+
+#### ❌ Anti-pattern
+
+```html
+<p-input-month name="month" [hideLabel]="true"></p-input-month>
+```
+
+#### ✅ Recommended
+
+```html
+<p-input-month name="month" [hideLabel]="true" label="Delivery month"></p-input-month>
+```
+
+### Validation feedback via state and message API
+
+#### ❌ Anti-pattern
+
+```html
+<p-input-month name="month" label="Delivery month" [aria-invalid]="true" message="Required"></p-input-month>
+```
+
+#### ✅ Recommended
+
+```html
+<p-input-month name="month" label="Delivery month" state="error" message="Select a delivery month to continue."></p-input-month>
+```

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

@@ -79,6 +79,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-angular/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
+
+```html
+<p-input-number name="speed" placeholder="Top speed" unit="kmh"></p-input-number>
+```
+
+#### ✅ Recommended
+
+```html
+<p-input-number name="speed" label="Top speed" unit="kmh" description="Enter the maximum speed in kilometers per hour."></p-input-number>
+```
+
+### Hidden label without accessible name
+
+#### ❌ Anti-pattern
+
+```html
+<p-input-number name="speed" [hideLabel]="true"></p-input-number>
+```
+
+#### ✅ Recommended
+
+```html
+<p-input-number name="speed" [hideLabel]="true" label="Top speed"></p-input-number>
+```
+
+### Validation feedback via state and message API
+
+#### ❌ Anti-pattern
+
+```html
+<p-input-number name="speed" label="Top speed" [aria-invalid]="true" message="Invalid"></p-input-number>
+```
+
+#### ✅ Recommended
+
+```html
+<p-input-number 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."></p-input-number>
+```