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

package/CHANGELOG.md

@@ -14,6 +14,38 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0),
 
 ## [Unreleased]
 
+## [4.6.0-rc.1] - 2026-08-03
+
+### Added
+
+- `Knowledge Skill`: Accessibility integration examples for each documented component, pairing anti-pattern and
+  recommended markup in the selected framework
+  ([#4613](https://github.com/porsche-design-system/porsche-design-system/pull/4613))
+- `pds-skill`: `--skill` option to link only the named skills instead of all discovered ones
+  ([#4613](https://github.com/porsche-design-system/porsche-design-system/pull/4613))
+
+### Changed
+
+- `Knowledge Skill`: Renamed from `porsche-design-system-components-{js|angular|react|vue}` to
+  `pds-knowledge-{js|angular|react|vue}`
+  ([#4613](https://github.com/porsche-design-system/porsche-design-system/pull/4613))
+- `Knowledge Skill`: Now shipped in the package's `skills/` directory with one directory per skill, replacing the single
+  `skill/` directory. Update any manually created symlink to the new location
+  ([#4613](https://github.com/porsche-design-system/porsche-design-system/pull/4613))
+
+### Fixed
+
+- `Segmented Control`: Improved `hover/selected` color visibility of items
+  ([#4610](https://github.com/porsche-design-system/porsche-design-system/pull/4610))
+
+## [4.6.0-rc.0] - 2026-07-21
+
+### Added
+
+- `Knowledge Skill`: providing version-exact guidance for PDS components, stylesheets, design tokens, and styling
+  integrations
+  ([#4555](https://github.com/porsche-design-system/porsche-design-system/pull/4555))
+
 ## [4.5.0] - 2026-07-21
 
 ## [4.5.0-rc.1] - 2026-07-20

package/bin/pds-skill.js

@@ -0,0 +1,346 @@
+#!/usr/bin/env node
+
+// Links locally installed Porsche Design System wrapper skills into the consumer project.
+// Every wrapper package exposes this same bin through the local node_modules/.bin directory;
+// --package selects which installed wrapper supplies the skills, independently of which
+// wrapper supplies the bin.
+//
+// --location is the destination parent directory for the skill links (e.g. `.claude/skills`,
+// `.agents`, `.github/skills`). Relative locations resolve from the cwd.
+//
+// --skill may be repeated to install only named skills. Omit it to install all discovered skills.
+//
+//   pds-skill --package <package> --location <dir> [--skill <name>...]
+//
+// This is the canonical source copied into all four wrapper package distributions by their
+// `build:subPackages:skill:bin` steps.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { parseArgs } = require('node:util');
+
+const SUPPORTED_PACKAGES = [
+  '@porsche-design-system/components-js',
+  '@porsche-design-system/components-angular',
+  '@porsche-design-system/components-react',
+  '@porsche-design-system/components-vue',
+];
+const USAGE = [
+  'Usage: pds-skill --package <package> --location <dir> [--skill <name>...]',
+  '',
+  'Required options:',
+  '  -p, --package <package>  locally installed Porsche Design System wrapper',
+  '  -l, --location <dir>     destination parent directory for the skill links',
+  '',
+  'Options:',
+  '  -s, --skill <name>       install only the named skill (repeatable); omit to install all',
+  '  -h, --help               print this usage',
+  '',
+  `Supported packages: ${SUPPORTED_PACKAGES.join(', ')}`,
+].join('\n');
+
+const fail = (message) => {
+  console.error(message);
+  process.exit(1);
+};
+
+const isMissingPathError = (error) => error.code === 'ENOENT' || error.code === 'ENOTDIR';
+const isPermissionError = (error) => error.code === 'EACCES' || error.code === 'EPERM';
+
+const parseOptions = (args) => {
+  try {
+    return parseArgs({
+      args,
+      options: {
+        package: { type: 'string', short: 'p' },
+        location: { type: 'string', short: 'l' },
+        skill: { type: 'string', short: 's', multiple: true },
+        help: { type: 'boolean', short: 'h' },
+      },
+      strict: true,
+      allowPositionals: false,
+    }).values;
+  } catch (error) {
+    fail(`${error.message}\n${USAGE}`);
+  }
+};
+
+const readPackageManifest = (packageJsonPath) => {
+  let content;
+  try {
+    content = fs.readFileSync(packageJsonPath, 'utf8');
+  } catch (error) {
+    if (isMissingPathError(error)) {
+      return undefined;
+    }
+    if (isPermissionError(error)) {
+      fail(`Cannot read ${packageJsonPath}: permission denied. Check the package permissions and re-run.`);
+    }
+    throw error;
+  }
+
+  try {
+    return JSON.parse(content);
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      fail(`Cannot read ${packageJsonPath}: invalid JSON. Reinstall the package and re-run.`);
+    }
+    throw error;
+  }
+};
+
+/** Parse the frontmatter `name:` value from SKILL.md content. Returns null if not found. */
+const parseFrontmatterName = (content) => {
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!fmMatch) {
+    return null;
+  }
+  const nameMatch = fmMatch[1].match(/^name:\s*(\S+)/m);
+  return nameMatch ? nameMatch[1] : null;
+};
+
+/**
+ * Validate that the SKILL.md at skillMdPath is a readable regular file with a frontmatter name
+ * matching expectedName. Calls fail() on any violation.
+ */
+const validateSkillMd = (skillMdPath, expectedName) => {
+  let stats;
+  try {
+    stats = fs.statSync(skillMdPath);
+  } catch (error) {
+    if (isMissingPathError(error)) {
+      fail(`The installed package does not ship a skill at ${skillMdPath}. Upgrade the package and re-run.`);
+    }
+    if (isPermissionError(error)) {
+      fail(`Cannot read ${skillMdPath}: permission denied. Check the package permissions and re-run.`);
+    }
+    throw error;
+  }
+
+  if (!stats.isFile()) {
+    fail(`${skillMdPath} is not a file. Reinstall the package and re-run.`);
+  }
+
+  let content;
+  try {
+    content = fs.readFileSync(skillMdPath, 'utf8');
+  } catch (error) {
+    if (isPermissionError(error)) {
+      fail(`Cannot read ${skillMdPath}: permission denied. Check the package permissions and re-run.`);
+    }
+    throw error;
+  }
+
+  const name = parseFrontmatterName(content);
+  if (name !== expectedName) {
+    fail(
+      `${skillMdPath} has frontmatter name "${name ?? '(none)'}" but its directory is "${expectedName}". Reinstall the package and re-run.`
+    );
+  }
+};
+
+/** Preflight the destination link path. Fails if something other than a symlink (or nothing) exists there. */
+const preflightDestLink = (linkPath, show) => {
+  let existing;
+  try {
+    existing = fs.lstatSync(linkPath);
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return;
+    }
+    if (isPermissionError(error)) {
+      fail(`Cannot inspect ${show(linkPath)}: permission denied. Check the destination permissions and re-run.`);
+    }
+    throw error;
+  }
+  if (!existing.isSymbolicLink()) {
+    fail(`Refusing to replace ${show(linkPath)}: it exists and is not a symlink. Remove it manually and re-run.`);
+  }
+};
+
+/** Resolve the installed package directory by walking up from cwd. Fails if not found. */
+const resolvePackageDir = (packageName, cwd) => {
+  if (!SUPPORTED_PACKAGES.includes(packageName)) {
+    fail(`Unsupported package: ${packageName}\n${USAGE}`);
+  }
+
+  let dir = cwd;
+  for (;;) {
+    const packageDir = path.join(dir, 'node_modules', ...packageName.split('/'));
+    const packageJsonPath = path.join(packageDir, 'package.json');
+    const pkg = readPackageManifest(packageJsonPath);
+    if (pkg !== undefined) {
+      const installedName = pkg && typeof pkg === 'object' ? pkg.name : undefined;
+      if (installedName !== packageName) {
+        fail(`Expected ${packageName} at ${packageDir}, but found ${installedName || 'a package without a name'}.`);
+      }
+      return packageDir;
+    }
+
+    const parent = path.dirname(dir);
+    if (parent === dir) {
+      fail(`Cannot find ${packageName} from ${cwd}. Install it in this project or workspace and re-run.`);
+    }
+    dir = parent;
+  }
+};
+
+/** Discover sorted child directory names under skillsDir. Returns empty array if the dir is absent. */
+const discoverSkillNames = (skillsDir) => {
+  let entries;
+  try {
+    entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+  } catch (error) {
+    if (isMissingPathError(error)) {
+      return [];
+    }
+    if (isPermissionError(error)) {
+      fail(`Cannot read ${skillsDir}: permission denied. Check the package permissions and re-run.`);
+    }
+    throw error;
+  }
+  return entries
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .sort();
+};
+
+const main = () => {
+  const options = parseOptions(process.argv.slice(2));
+  if (options.help) {
+    console.log(USAGE);
+    return;
+  }
+
+  const missingOptions = [!options.package && '--package', !options.location && '--location'].filter(Boolean);
+  if (missingOptions.length > 0) {
+    fail(`Missing required option${missingOptions.length > 1 ? 's' : ''}: ${missingOptions.join(' and ')}\n${USAGE}`);
+  }
+
+  if (process.versions.pnp) {
+    fail(
+      "Yarn Plug'n'Play is not supported because an operating-system symlink cannot target Yarn's virtual filesystem. Use `nodeLinker: node-modules`."
+    );
+  }
+
+  const cwd = process.cwd();
+  const packageName = options.package;
+  const destArg = options.location;
+  const requestedSkills = options.skill ?? [];
+
+  const packageDir = resolvePackageDir(packageName, cwd);
+  const skillsDir = path.join(packageDir, 'skills');
+  const discovered = discoverSkillNames(skillsDir);
+
+  if (discovered.length === 0) {
+    fail(`The installed package does not ship any skills at ${skillsDir}. Upgrade the package and re-run.`);
+  }
+
+  // Validate --skill filters; unknown names fail clearly.
+  if (requestedSkills.length > 0) {
+    const unknown = requestedSkills.filter((s) => !discovered.includes(s));
+    if (unknown.length > 0) {
+      fail(
+        `Unknown skill${unknown.length > 1 ? 's' : ''}: ${unknown.join(', ')}. ` +
+          `Available: ${[...discovered].sort().join(', ')}.`
+      );
+    }
+  }
+
+  // Deterministic sorted selection.
+  const selected =
+    requestedSkills.length > 0
+      ? [...new Set(requestedSkills)].filter((s) => discovered.includes(s)).sort()
+      : discovered;
+
+  const destDir = path.isAbsolute(destArg) ? destArg : path.resolve(cwd, destArg);
+
+  // Prefer a cwd-relative path in messages; fall back to absolute when outside.
+  const show = (target) => {
+    const rel = path.relative(cwd, target);
+    return rel && !rel.startsWith('..') && !path.isAbsolute(rel) ? rel : target;
+  };
+
+  // Preflight every selected skill tree before touching the destination at all.
+  for (const skillName of selected) {
+    validateSkillMd(path.join(skillsDir, skillName, 'SKILL.md'), skillName);
+  }
+
+  try {
+    fs.mkdirSync(destDir, { recursive: true });
+  } catch (error) {
+    if (error.code === 'ENOTDIR' || error.code === 'EEXIST') {
+      fail(`Cannot create ${show(destDir)}: a parent path exists as a file, not a directory. Remove it and re-run.`);
+    }
+    if (isPermissionError(error)) {
+      fail(`Cannot create ${show(destDir)}: permission denied. Check the destination permissions and re-run.`);
+    }
+    throw error;
+  }
+
+  // Preflight all destination links before any mutation.
+  for (const skillName of selected) {
+    preflightDestLink(path.join(destDir, skillName), show);
+  }
+
+  // All preflights passed — perform link operations.
+  const linkType = process.platform === 'win32' ? 'junction' : 'dir';
+  for (const skillName of selected) {
+    const skillDir = path.join(skillsDir, skillName);
+    const linkPath = path.join(destDir, skillName);
+
+    // Idempotent: repoint an existing symlink (including a dangling one), but never touch a
+    // real directory a user may have hand-maintained — the preflight above already rejected that.
+    let existingLink = null;
+    try {
+      existingLink = fs.lstatSync(linkPath);
+    } catch (error) {
+      if (error.code !== 'ENOENT') {
+        throw error;
+      }
+    }
+
+    if (existingLink?.isSymbolicLink()) {
+      try {
+        if (fs.realpathSync(linkPath) === fs.realpathSync(skillDir)) {
+          console.log(`Porsche Design System skill already linked: ${show(linkPath)} -> ${skillDir}`);
+          continue;
+        }
+      } catch (error) {
+        if (error.code !== 'ENOENT') {
+          if (isPermissionError(error)) {
+            fail(`Cannot inspect ${show(linkPath)}: permission denied. Check the destination permissions and re-run.`);
+          }
+          throw error;
+        }
+        // Dangling symlink — fall through to replace it.
+      }
+      try {
+        fs.rmSync(linkPath, { force: true });
+      } catch (error) {
+        if (isPermissionError(error)) {
+          fail(`Cannot replace ${show(linkPath)}: permission denied. Check the destination permissions and re-run.`);
+        }
+        throw error;
+      }
+    }
+
+    try {
+      fs.symlinkSync(skillDir, linkPath, linkType);
+    } catch (error) {
+      if (process.platform === 'win32' && error.code === 'EPERM') {
+        fail(
+          `Could not create the skill junction on Windows (EPERM). Check the destination permissions or create it manually:\n  mklink /J "${linkPath}" "${skillDir}"`
+        );
+      }
+      if (isPermissionError(error)) {
+        fail(`Cannot create ${show(linkPath)}: permission denied. Check the destination permissions and re-run.`);
+      }
+      throw error;
+    }
+
+    console.log(`Linked Porsche Design System skill: ${show(linkPath)} -> ${skillDir}`);
+  }
+};
+
+main();

package/esm/lib/components/button.wrapper.d.ts

@@ -52,7 +52,7 @@ export type PButtonProps = BaseProps & {
      */
     value?: string;
     /**
-     * Sets the visual style variant of the button (e.g. `primary`, `secondary`, `tertiary`).
+     * Sets the visual style variant of the button (`primary` or `secondary`).
      * @default 'primary'
      */
     variant?: ButtonVariant;
@@ -109,7 +109,7 @@ export declare const PButton: import("react").ForwardRefExoticComponent<Omit<imp
      */
     value?: string;
     /**
-     * Sets the visual style variant of the button (e.g. `primary`, `secondary`, `tertiary`).
+     * Sets the visual style variant of the button (`primary` or `secondary`).
      * @default 'primary'
      */
     variant?: ButtonVariant;

package/esm/lib/components/link.wrapper.d.ts

@@ -42,7 +42,7 @@ export type PLinkProps = BaseProps & {
      */
     target?: LinkTarget;
     /**
-     * Sets the visual style variant of the link (e.g. `primary`, `secondary`, `tertiary`).
+     * Sets the visual style variant of the link (`primary` or `secondary`).
      * @default 'primary'
      */
     variant?: LinkVariant;
@@ -89,7 +89,7 @@ export declare const PLink: import("react").ForwardRefExoticComponent<Omit<impor
      */
     target?: LinkTarget;
     /**
-     * Sets the visual style variant of the link (e.g. `primary`, `secondary`, `tertiary`).
+     * Sets the visual style variant of the link (`primary` or `secondary`).
      * @default 'primary'
      */
     variant?: LinkVariant;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porsche-design-system/components-react",
-  "version": "4.5.0",
+  "version": "4.6.0-rc.1",
   "description": "Porsche Design System is a component library designed to help developers create the best experience for software or services distributed by Dr. Ing. h.c. F. Porsche AG.",
   "keywords": [
     "porsche",
@@ -21,7 +21,7 @@
     "url": "https://github.com/porsche-design-system/porsche-design-system"
   },
   "dependencies": {
-    "@porsche-design-system/components-js": "4.5.0"
+    "@porsche-design-system/components-js": "4.6.0-rc.1"
   },
   "peerDependencies": {
     "ag-grid-community": ">= 36.0.0 <37.0.0",
@@ -134,6 +134,7 @@
   },
   "style": "./stylesheets/index.css",
   "bin": {
-    "patchRemixRunProcessBrowserGlobalIdentifier": "./bin/patchRemixRunProcessBrowserGlobalIdentifier.js"
+    "patchRemixRunProcessBrowserGlobalIdentifier": "./bin/patchRemixRunProcessBrowserGlobalIdentifier.js",
+    "pds-skill": "./bin/pds-skill.js"
   }
 }

package/skills/pds-knowledge-react/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: pds-knowledge-react
+description: Build, style, or review web user interfaces with the Porsche Design System (PDS), or author and review documents that specify PDS behavior. Use whenever a task touches frontend UI — adding or changing components (buttons, forms, inputs, cards, tables, modals, navigation, layouts), styling with Tailwind, SCSS, vanilla-extract or Emotion, applying design tokens, or scaffolding a new page or form. Also use whenever a requirement, spec, design doc, or acceptance criteria names a PDS component, prop, token, or theming. Prefer PDS for new UI even when it is not named by the user. Do not activate for backend or non-UI logic, unrelated tests or tooling, documentation or prose that does not assert PDS component, prop, token, or theming behavior, work that clearly targets a different UI library, or when the user opts out of PDS.
+---
+
+# Porsche Design System (`react`)
+
+Version-exact knowledge of the installed Porsche Design System: every fact, prop, token and example here matches the installed package exactly — never mix guidance across versions. Every reference path is relative to this skill root unless noted otherwise.
+
+This skill ships inside the installed wrapper package alongside its inspectable package artifacts: the typings, `component-meta` (`@porsche-design-system/components-js/meta`), the SCSS partials (`@porsche-design-system/components-js/scss`), the design tokens (`../../tokens`), the Tailwind theme (`../../tailwindcss/index.css`) and the shipped global CSS. The underlying Stencil component implementation is not included in the npm package; it is loaded from the Porsche Design System CDN at runtime. The wrapper's own `meta` and `scss` are re-export shims of the same-version `@porsche-design-system/components-js` peer, so those two point at the peer directly.
+
+Prefer Porsche Design System components and tokens for new UI, even when the user does not name PDS. Do not rewrite non-PDS UI unasked, and do not hijack work that targets another library.
+
+## Coverage and fallbacks
+
+This skill currently covers components, global stylesheets and theming, tokens, and styling integrations. It does not yet include complete getting-started, setup, and installation guidance; the v3-to-v4 migration guide; the changelog; partials; patterns and templates; the AG Grid theme; or the Storefront’s Must Know and Help sections.
+
+Before using documentation outside this skill or the installed package, match it to the installed PDS version. This skill was generated for `4.6.0-rc.1`; prefer the [exact-version Porsche Design System Storefront](https://designsystem.porsche.com/v4.6.0-rc.1/). Major-version URLs such as `/v4/` always serve the latest v4 release and may describe APIs or setup introduced after the installed version. Use them only as a fallback and verify relevant details against the installed package.
+
+For runnable patterns and templates, consult the [Porsche Design System examples repository](https://github.com/porsche-design-system/examples), selecting a release tag or commit that matches the installed package instead of assuming its default branch is compatible. For release-specific changes, read `../../CHANGELOG.md`.
+
+For exact API facts, inspect the installed typings and metadata first. When readable implementation details are necessary, use the [exact-version component source](https://github.com/porsche-design-system/porsche-design-system/tree/v4.6.0-rc.1/packages/components/src/components) under the repository's `packages/components/src/components/<component>` directory. Do not use the default branch, which may represent a newer release.
+
+For deployed browser behavior, inspect component requests in the Network panel. Treat these minified, content-hashed CDN artifacts as a debugging fallback; use the exact-version repository source for readable implementation details.
+
+## Components
+
+The Porsche Design System ships 58 components. Open a component's reference for its props, slots, events, CSS variables and examples before using it. Each reference's "Examples" table links runnable, framework-specific example files under `references/components/<tag>/examples/`.
+
+`component-meta` is authoritative: when it disagrees with the examples or prose here, follow `component-meta` (raw data at `@porsche-design-system/components-js/meta`).
+
+Every component is validated against the PDS accessibility test matrix (automated: AXE-Core WCAG 2.2 AA, high-contrast, text-zoom; manual: keyboard, screen reader). A component reference carries a `## Tests` section only to flag an exception (e.g. partial high-contrast support).
+
+**Framework syntax** (this differs from the custom-element tags the references show):
+- Import each component by name and use its **PascalCase** React component: `p-button` → `<PButton>`, `p-input-text` → `<PInputText>`.
+- Props are **camelCase** (`disableBackdropClick`, not `disable-backdrop-click`); use `className` for CSS classes and pass ARIA via the `aria={{ ... }}` prop.
+- Events are `on<Event>` handler props — the `dismiss` event is `onDismiss`, `update` is `onUpdate`.
+- Place a child into a named slot with the `slot="..."` attribute.
+
+Sub-components (e.g. `p-table-row`, `p-select-option`, `p-tabs-item`) have no separate row — they are only valid inside a parent, so their API is documented under a "Sub-components" section in that parent's reference.
+
+| Component | Summary | Reference |
+| --- | --- | --- |
+| `p-accordion` | The `p-accordion` is a component that reveals or hides associated sections of content. | [p-accordion.md](references/components/p-accordion/p-accordion.md) |
+| `p-ai-tag` | `p-ai-tag` is used to indicate AI-generated or AI-modified content. | [p-ai-tag.md](references/components/p-ai-tag/p-ai-tag.md) |
+| `p-banner` | The `p-banner` component provides action-based feedback messages (e.g. after performing a task) or to convey informational and/or critical notification like some site related topics. | [p-banner.md](references/components/p-banner/p-banner.md) |
+| `p-button` | The `p-button` component is essential for performing form or **interaction** events. | [p-button.md](references/components/p-button/p-button.md) |
+| `p-button-pure` | The `p-button-pure` component is essential to perform events for **interactions**. | [p-button-pure.md](references/components/p-button-pure/p-button-pure.md) |
+| `p-button-tile` | The `p-button-tile` is an interactive component that displays a provided image to tease content and performs form or **interaction** events within one container. | [p-button-tile.md](references/components/p-button-tile/p-button-tile.md) |
+| `p-canvas` _(experimental)_ | The `p-canvas` is an experimental layout component for productive web applications. | [p-canvas.md](references/components/p-canvas/p-canvas.md) |
+| `p-carousel` | The `p-carousel` component allows related or similar content to be consumed on a step by step basis with a better overview than just showing them in a grid or as a list. | [p-carousel.md](references/components/p-carousel/p-carousel.md) |
+| `p-checkbox` | The `p-checkbox` component wraps the native HTML input type `checkbox` form element. | [p-checkbox.md](references/components/p-checkbox/p-checkbox.md) |
+| `p-crest` | The `p-crest` gives the Porsche brand a distinctive look, sets it apart from others within the overall external image and represents the quality of the product. | [p-crest.md](references/components/p-crest/p-crest.md) |
+| `p-display` _(deprecated)_ | `p-display` is used to highlight and specify heading styling and hierarchy in documents. | [p-display.md](references/components/p-display/p-display.md) |
+| `p-divider` | The `p-divider` is used as 'horizontal or vertical rule' and displays a dividing line. | [p-divider.md](references/components/p-divider/p-divider.md) |
+| `p-drilldown` _(experimental)_ | The `p-drilldown` component is meant for displaying an infinite multilevel structure in a drilldown menu that overlays the page content from the start side of the screen. | [p-drilldown.md](references/components/p-drilldown/p-drilldown.md) |
+| `p-fieldset` | The `p-fieldset` is a grouping component for wrapping contextual associated form elements. | [p-fieldset.md](references/components/p-fieldset/p-fieldset.md) |
+| `p-flag` | The `p-flag` component displays a country or region flag and should be used to communicate geographic context visually. | [p-flag.md](references/components/p-flag/p-flag.md) |
+| `p-flyout` | The `p-flyout` is a overlay from the left or right side of the screen. | [p-flyout.md](references/components/p-flyout/p-flyout.md) |
+| `p-heading` | `p-heading` is used to highlight and specify heading styling and hierarchy in documents. | [p-heading.md](references/components/p-heading/p-heading.md) |
+| `p-icon` | Along with other Porsche basic elements - such as colors, typography and the Porsche marque - icons are core components of the Porsche design. | [p-icon.md](references/components/p-icon/p-icon.md) |
+| `p-inline-notification` | The `p-inline-notification` is a controlled component that provides action-based feedback messages (e.g. after performing a task) or to convey informational and/or critical notification like some site related topics. | [p-inline-notification.md](references/components/p-inline-notification/p-inline-notification.md) |
+| `p-input-date` | The `p-input-date` component provides a versatile, user‑friendly interface for entering date values. | [p-input-date.md](references/components/p-input-date/p-input-date.md) |
+| `p-input-email` | The `p-input-email` component provides a user-friendly, accessible interface for entering valid email addresses. | [p-input-email.md](references/components/p-input-email/p-input-email.md) |
+| `p-input-month` | The `p-input-month` component provides a versatile, user‑friendly interface for entering month values. | [p-input-month.md](references/components/p-input-month/p-input-month.md) |
+| `p-input-number` | The `p-input-number` component provides a versatile, user‑friendly interface for entering numeric values. | [p-input-number.md](references/components/p-input-number/p-input-number.md) |
+| `p-input-password` | The `p-input-password` component enables secure password entry by obscuring the typed characters. | [p-input-password.md](references/components/p-input-password/p-input-password.md) |
+| `p-input-search` | The `p-input-search` component offers a versatile, user-friendly interface for entering and submitting search queries. | [p-input-search.md](references/components/p-input-search/p-input-search.md) |
+| `p-input-tel` | The `p-input-tel` component provides a user-friendly, accessible interface for entering valid telephone numbers. | [p-input-tel.md](references/components/p-input-tel/p-input-tel.md) |
+| `p-input-text` | The `p-input-text` component provides a versatile, user‑friendly interface for entering freeform text. | [p-input-text.md](references/components/p-input-text/p-input-text.md) |
+| `p-input-time` | The `p-input-time` component provides a versatile, user‑friendly interface for entering time values. | [p-input-time.md](references/components/p-input-time/p-input-time.md) |
+| `p-input-url` | The `p-input-url` component provides a user-friendly, accessible interface for entering valid website URLs. | [p-input-url.md](references/components/p-input-url/p-input-url.md) |
+| `p-input-week` | The `p-input-week` component provides a versatile, user‑friendly interface for entering week values. | [p-input-week.md](references/components/p-input-week/p-input-week.md) |
+| `p-link` | The `p-link` component is essential to perform changes in **page routes**. | [p-link.md](references/components/p-link/p-link.md) |
+| `p-link-pure` | The `p-link-pure` component is essential for performing changes in **page routes**. | [p-link-pure.md](references/components/p-link-pure/p-link-pure.md) |
+| `p-link-tile` | The `p-link-tile` is a navigational component that displays a provided image to tease content and navigate to further information within one container. | [p-link-tile.md](references/components/p-link-tile/p-link-tile.md) |
+| `p-link-tile-product` _(experimental)_ | The `p-link-tile-product` is a navigational component designed to showcase a featured product within a store. | [p-link-tile-product.md](references/components/p-link-tile-product/p-link-tile-product.md) |
+| `p-modal` | The `p-modal` is a temporary overlay to focus the user's attention on one task while interactions with the underlying page are blocked. | [p-modal.md](references/components/p-modal/p-modal.md) |
+| `p-model-signature` | The `p-model-signature` component is purely visual and renders the different signatures of Porsche car models. | [p-model-signature.md](references/components/p-model-signature/p-model-signature.md) |
+| `p-multi-select` | The `p-multi-select` component is a versatile custom form element that facilitates the selection of multiple options. | [p-multi-select.md](references/components/p-multi-select/p-multi-select.md) |
+| `p-pagination` | The `p-pagination` component divides large content sets into pages and should be used when all items cannot be displayed at once. | [p-pagination.md](references/components/p-pagination/p-pagination.md) |
+| `p-pin-code` | The `p-pin-code` component is optimized for entering sequences of digits. | [p-pin-code.md](references/components/p-pin-code/p-pin-code.md) |
+| `p-popover` | The `p-popover` component displays additional contextual content in an overlay and should be used when users need optional details without leaving their current context. | [p-popover.md](references/components/p-popover/p-popover.md) |
+| `p-radio-group` | The `p-radio-group` component is a versatile custom form element that enables the selection of a single option. | [p-radio-group.md](references/components/p-radio-group/p-radio-group.md) |
+| `p-scroller` | The `p-scroller` component forces its child nodes to be rendered horizontally next to each other. | [p-scroller.md](references/components/p-scroller/p-scroller.md) |
+| `p-segmented-control` | The `p-segmented-control` component is similar to the native `select` element while showing all available options right away. | [p-segmented-control.md](references/components/p-segmented-control/p-segmented-control.md) |
+| `p-select` | The `p-select` component is a versatile custom form element that enables the selection of a single option. | [p-select.md](references/components/p-select/p-select.md) |
+| `p-sheet` | The `p-sheet` is a temporary overlay to focus the user's attention on one or multiple tasks while the underlying page is still visible but interactions with it are blocked. | [p-sheet.md](references/components/p-sheet/p-sheet.md) |
+| `p-spinner` | The `p-spinner` component indicates an indeterminate ongoing process and should be used when users must wait for loading or processing to finish. | [p-spinner.md](references/components/p-spinner/p-spinner.md) |
+| `p-stepper-horizontal` | The `p-stepper-horizontal` component displays progress through a sequence of logical and numbered steps. | [p-stepper-horizontal.md](references/components/p-stepper-horizontal/p-stepper-horizontal.md) |
+| `p-switch` | The `p-switch` component is a control that is used to quickly switch between two possible states. | [p-switch.md](references/components/p-switch/p-switch.md) |
+| `p-table` | The `p-table` component displays tabular data and offers column-wise sorting options. | [p-table.md](references/components/p-table/p-table.md) |
+| `p-tabs` | The `p-tabs` component makes it easy to explore and switch between different views. | [p-tabs.md](references/components/p-tabs/p-tabs.md) |
+| `p-tabs-bar` | The `p-tabs-bar` component is a styled button/link list for multiple purposes. | [p-tabs-bar.md](references/components/p-tabs-bar/p-tabs-bar.md) |
+| `p-tag` | `p-tag` is used to label, categorize, or organize items by using keywords that describe them. | [p-tag.md](references/components/p-tag/p-tag.md) |
+| `p-tag-dismissible` | `p-tag-dismissible` is used in contexts where the user can actively remove a tag. | [p-tag-dismissible.md](references/components/p-tag-dismissible/p-tag-dismissible.md) |
+| `p-text` | `p-text` is used to specify paragraph styling in documents. | [p-text.md](references/components/p-text/p-text.md) |
+| `p-text-list` | The `p-text-list` component is used to display listed data in form of an unordered or ordered list. | [p-text-list.md](references/components/p-text-list/p-text-list.md) |
+| `p-textarea` | The `p-textarea` component is a multi-line text input control. | [p-textarea.md](references/components/p-textarea/p-textarea.md) |
+| `p-toast` | The `p-toast` component manages both, the queue and display of toast messages. | [p-toast.md](references/components/p-toast/p-toast.md) |
+| `p-wordmark` | The `p-wordmark` gives the Porsche brand a distinctive look, sets it apart from others within the overall external image and represents the quality of the product. | [p-wordmark.md](references/components/p-wordmark/p-wordmark.md) |
+
+## Server-side rendering (SSR)
+
+React applications that render on the server — Next.js, Remix, or React Router with SSR enabled — must import `PorscheDesignSystemProvider` and every PDS component from `@porsche-design-system/components-react/ssr`. Use the package root only for client-rendered React applications; do not mix the two entry points.
+
+```tsx
+import { PButton, PorscheDesignSystemProvider } from '@porsche-design-system/components-react/ssr';
+```
+
+On the server, the `/ssr` build emits component markup and styles as Declarative Shadow DOM so the browser can create the Shadow DOM before JavaScript runs. In the browser, it initializes like the standard React wrapper. The framework build must replace `process.browser` for its server and client targets and eliminate the unused branch.
+
+Framework setup differs. Follow the [Next.js integration guide](https://designsystem.porsche.com/v4.6.0-rc.1/developing/next-js/getting-started/) or the [React Router integration guide](https://designsystem.porsche.com/v4.6.0-rc.1/developing/react-router/getting-started/). Remix users should follow the React Router guidance because Remix v2 was upstreamed into React Router.
+
+## Stylesheets
+
+The required global stylesheets every component depends on (CSS variables, font-face, normalize/reset) and light/dark theming via the `.scheme-*` classes and `color-scheme`. Open this whenever installing or setting up PDS, before rendering any component, when components look unstyled or use the wrong font/colors, or for anything about themes, dark mode, or color scheme — it applies to most PDS work. See [stylesheets.md](references/stylesheets.md) for the exact files, their import order and the full `.scheme-*` list.
+
+**Theming is one mechanism — CSS `color-scheme`, nothing else** (the `.scheme-*` mechanics live in [stylesheets.md](references/stylesheets.md)). There is **no** `theme` prop — not on `PorscheDesignSystemProvider` (it takes only `prefix` and `cdn`) and not on components. A `theme="light|dark|auto"` prop existed in earlier majors and was removed; if you recall one, it is a stale prior — do not add it, verify against the installed types.
+
+## Tokens
+
+Design tokens — the source values for color, spacing, typography, motion, breakpoints and more, provided as JS constants. The entire system is built on these tokens: the global stylesheets, the components and the custom styling themes all depend on them. They can also be used standalone to support other styling solutions or to build custom UI directly. Open [tokens.md](references/tokens.md) when using tokens directly in custom UI.
+
+## Styling
+
+The Porsche Design System offers a ready-made integration for four styling solutions. Use them to build layout and custom components or patterns not yet available in the component library — typography, surfaces, boxes, the layout grid, spacing and responsive breakpoints. They are independent of the components, but build on the same design tokens and the same `color-scheme` (light/dark) theming (see the **Stylesheets** section above), so custom UI shares the exact palette, spacing and typography as PDS components. Pick one solution per project and open its reference for setup and the full catalog.
+
+Note: the code examples in the component references use PDS Tailwind utility classes (e.g. `flex`, `flex-col`, `gap-fluid-sm`) for layout. These only take effect with the Tailwind CSS solution installed (`references/styles/tailwindcss.md`) — without it they are inert, so replace them with your own layout CSS.
+
+| Styling solution | Use this when | Reference |
+| --- | --- | --- |
+| Tailwind CSS | utility-first styling on a PDS Tailwind v4 theme | [tailwindcss.md](references/styles/tailwindcss.md) |
+| SCSS | Sass variables and mixins under the `pds` namespace | [scss.md](references/styles/scss.md) |
+| vanilla-extract | typed tokens and utilities in `*.css.ts` files | [vanilla-extract.md](references/styles/vanilla-extract.md) |
+| Emotion | tokens and utilities in `css`/`styled` styles | [emotion.md](references/styles/emotion.md) |

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

@@ -0,0 +1,63 @@
+# p-accordion accessibility integration examples
+
+## Integration examples
+
+### Accordion summary without semantic heading
+
+#### ❌ Anti-pattern
+
+```tsx
+<PAccordion>
+  <span slot="summary">
+    Delivery options
+  </span>
+  <PText>
+    Content about delivery.
+  </PText>
+</PAccordion>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PAccordion>
+  <PHeading slot="summary" tag="h2" size="sm">
+    Delivery options
+  </PHeading>
+  <PText>
+    Content about delivery.
+  </PText>
+</PAccordion>
+```
+
+### Skipped heading level
+
+#### ❌ Anti-pattern
+
+```tsx
+<PHeading tag="h1">
+  Configure your Porsche
+</PHeading>
+
+<PAccordion>
+  <PHeading slot="summary" tag="h4" size="sm">
+    Delivery options
+  </PHeading>
+  ...
+</PAccordion>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PHeading tag="h1">
+  Configure your Porsche
+</PHeading>
+
+<PAccordion>
+  <PHeading slot="summary" tag="h2" size="sm">
+    Delivery options
+  </PHeading>
+  ...
+</PAccordion>
+```