Porsche Design System

Accessibility: Do's and Don'ts

Table of Contents

Why this page exists
Top 5 audit mistakes
General do's
General don'ts
Mistake to better solution
Before-merge checklist

Why this page exists#

Most accessibility regressions found in audits are not caused by missing component features, but by incorrect integration or semantic misuse. This page focuses on practical integration guidance so developers can avoid recurring issues while using PDS components.

This is different from the Usage tab on component pages, which covers design and UX guidance. The Accessibility tab documents keyboard behavior, ARIA support, and component-specific integration patterns.

Top 5 audit mistakes#

Adding aria-* directly on a PDS component root element instead of using the aria prop.

Missing accessible names for icon-only action buttons or links.

Missing focus indicators on custom UI components.

Missing skip links for repeated, long content blocks (e.g. large carousels).

Missing semantic structure (e.g. wrong heading hierarchy or missing landmarks).

General do's#

Use semantic landmarks (header, nav, main, footer) and add aria-label or aria-labelledby where appropriate.

Keep heading order logical (use h1 → h2 → h3 and avoid skipping levels).

Pass ARIA through the component aria prop where supported.

Add clear, distinguishable labels for actions, especially icon-only controls.

Keep focus visible and keyboard behavior/order complete.

Use skip links when users would otherwise tab through long repeated blocks.

General don'ts#

Do not put raw aria-* attributes on PDS component host elements as a workaround.

Do not remove focus outlines or build custom focus styles without using PDS focus styling as a reference.

Do not pick headings by visual size, pick them by document structure.

Do not rely on placeholder text as the only form label.

Do not use "click here" link text without context.

Do not create mouse-only interactions.

Mistake to better solution#

ARIA on PDS component host vs aria prop

❌ Anti-pattern

<p-button aria-haspopup="dialog" aria-label="Open details of product XYZ">
  Open details
</p-button>

✅ Recommended

<p-button aria="{ 'aria-haspopup': 'dialog', 'aria-label': 'Open details of product XYZ' }">Open details</p-button>

Icon-only action without accessible name

❌ Anti-pattern

<p-link icon="arrow-right" href="https://porsche.com"></p-link>

✅ Recommended

<p-link icon="arrow-right" hide-label="true" href="https://porsche.com">Some label</p-link>

// or with more contextual label for screen readers

<p-link
  icon="arrow-right"
  hide-label="true"
  aria="{ 'aria-label': 'Some label with more information about XYZ' }"
  href="https://porsche.com"
>
  Some label
</p-link>

Large carousel without skip behavior

❌ Anti-pattern

<p-carousel>
  <!-- many slides -->
</p-carousel>

<p-heading tag="h2">Next content area</p-heading>

✅ Recommended

<p-carousel skip-link-target="#next-content-area">
  <!-- many slides -->
</p-carousel>

<p-heading tag="h2" id="next-content-area">Next content area</p-heading>

Make sure the skip target points to the next meaningful element after the carousel.

Before-merge checklist#

Check the component's Accessibility tab for component-specific requirements.

All interactive controls are keyboard reachable and operable.

Focus indicators are visible in default state and use PDS focus styling.

Icon-only actions have clear accessible names.

ARIA is passed via supported PDS component APIs.

Repeated blocks include a skip strategy when needed.

Use semantic structural elements and maintain logical heading order.