Porsche Design System

AI Agent Accessibility Setup

Table of Contents

AGENTS.md overview
GitHub Copilot Instructions
Cursor Rules
Accessibility specific instructions
Download instruction files
Installation steps

AI coding assistants like GitHub Copilot and Cursor can significantly accelerate development, but without proper guidance they often generate code that lacks semantic HTML, keyboard accessibility, focus management, and proper ARIA patterns. By providing accessibility context to your AI agent, you ensure generated code follows WCAG 2.2 AA standards from the start.

AGENTS.md overview#

AGENTS.md is a tool-agnostic standard for providing AI agents with repository context. It should be the canonical source of instructions, with package-specific AGENTS.md files used to add scoped guidance.

Learn more at agents.md.

Recommended structure (monorepo example):

packages/
├── package1/AGENTS.md
├── package2/AGENTS.md
└── ...

Best practice: Keep AGENTS.md concise and link to detailed documentation. Use package-level files for deeper, context-specific rules (e.g., accessibility, build steps, test expectations).

GitHub Copilot Instructions#

GitHub Copilot supports custom instructions through Markdown files in your repository. We recommend:

Use AGENTS.md as the canonical source for repository guidance.

Keep .github/copilot-instructions.md in sync with AGENTS.md for Copilot compatibility.

Use scoped instruction files in .github/instructions/ for file-type specific rules (like accessibility).

Global Instructions

Create a file at .github/copilot-instructions.md in your repository root. This file applies to all Copilot interactions in your project.

.github/
└── copilot-instructions.md

Scoped Instructions

For more granular control, add instruction files to .github/instructions/ and include frontmatter specifying the target files using glob patterns:

.github/
└── instructions/
    ├── accessibility.instructions.md # Applies to all frontend files
    └── project.instructions.md # Project-specific rules

Each instruction file should include an applyTo frontmatter that uses glob patterns:

The applyTo pattern determines which files these instructions apply to. For accessibility rules, we recommend applying them to all frontend file types.

---
applyTo: '**/*.{html,css,scss,js,ts,tsx,jsx,vue,mdx}'
---

Cursor Rules#

Cursor uses a .cursor/rules/ directory structure for custom AI instructions:

.cursor/
└── rules/
    ├── accessibility.mdc    # Accessibility rules
    └── project.mdc          # Project-specific rules

Cursor rule files use the .mdc extension (Markdown with Cursor metadata). The format is similar to GitHub Copilot instructions:

---
description: Accessibility rules for frontend code
globs: ['**/*.{html,css,scss,js,ts,tsx,jsx,vue}']
---

Accessibility specific instructions#

Accessibility rules template

Below is a comprehensive accessibility rules template you can use with either GitHub Copilot or Cursor. This template includes the Porsche Design System's internal accessibility guidelines and ensures compliance with WCAG 2.2 AA.

As always, providing context to AI agents is not a one-time setup. Custom instruction files are living documents. Continuously refine and expand your instruction files based on the specific accessibility challenges you encounter in your project or if the AI agent is hallucinating and generates inaccessible code patterns.

Non-negotiable requirements

Must comply with WCAG 2.2 AA

Must be fully keyboard accessible (no mouse-only interactions, no keyboard traps)

Must provide visible focus for all interactive elements

Must support High Contrast Mode / forced-colors

Prefer Porsche Design System components where available

Semantics first

Prefer native HTML elements (button, a, input, select, details/summary, dialog) over custom div/span widgets

Use correct landmarks (header, nav, main, footer) and maintain consistent heading order

Every interactive element must have an accessible name via visible text, <label>, aria-label, or aria-labelledby

Keyboard interactions

Everything interactive must be reachable via Tab and operable via keyboard

Use standard key mappings: Enter/Space for buttons, arrow keys for roving focus patterns

Don't remove focus outlines globally; use :focus-visible for custom focus styling

When opening overlays/modals, move focus into the region and return focus to the trigger on close

High Contrast Mode

Ensure UI is usable with @media (forced-colors: active)

Avoid relying solely on background images or subtle shadows for affordances

Don't disable forced-color adjustments unless implementing a correct alternative

Porsche Design System (PDS) component usage

When using Porsche Design System components, include these rules:

Use @porsche-design-system/components-{react|angular|vue} for UI primitives

If a PDS component needs extra ARIA, use the aria property according to PDS documentation

Never place native aria attributes on PDS components :host elements directly

Preserve PDS focus styling; don't override focus rings unless required

Check PDS component documentation for accessibility best practices

Download instruction files#

Download ready-to-use instruction files for your project:

AGENTS.md

Copilot (accessibility.instructions.md)

Cursor (accessibility.mdc)

Installation steps#

For AGENTS.md:

Create AGENTS.md in the repository root

Add package-specific AGENTS.md files where needed (e.g., packages/package1/AGENTS.md)

Keep AGENTS.md in sync with Copilot/Cursor instruction files

For GitHub Copilot:

Download accessibility.instructions.md

Create .github/instructions/ directory in your repository root

Place the file in .github/instructions/accessibility.instructions.md

Commit and push to your repository

For Cursor Rules:

Download accessibility.mdc

Create .cursor/rules/ directory in your project root

Place the file in .cursor/rules/accessibility.mdc

Restart Cursor or reload the workspace

Once configured, your AI agent will automatically apply these accessibility rules when generating or modifying frontend code.