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

package/CHANGELOG.md

@@ -14,6 +14,30 @@ 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

package/bin/pds-skill.js

@@ -1,13 +1,16 @@
 #!/usr/bin/env node
 
-// Links a locally installed Porsche Design System wrapper skill into the consumer project. Every
-// wrapper exposes this same bin through the local node_modules/.bin directory; --package selects
-// which installed wrapper supplies the skill, independently of which wrapper supplies the bin.
+// 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 link (e.g. `.claude/skills`, `.agents`,
-// `.github/skills`). Relative locations resolve from the cwd.
+// --location is the destination parent directory for the skill links (e.g. `.claude/skills`,
+// `.agents`, `.github/skills`). Relative locations resolve from the cwd.
 //
-//   pds-skill --package <package> --location <dir>
+// --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.
@@ -23,13 +26,14 @@ const SUPPORTED_PACKAGES = [
   '@porsche-design-system/components-vue',
 ];
 const USAGE = [
-  'Usage: pds-skill --package <package> --location <dir>',
+  '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 link',
+  '  -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(', ')}`,
@@ -50,6 +54,7 @@ const parseOptions = (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,
@@ -60,8 +65,6 @@ const parseOptions = (args) => {
   }
 };
 
-const linkNameFromPackage = (packageName) => packageName.slice(1).replace('/', '-');
-
 const readPackageManifest = (packageJsonPath) => {
   let content;
   try {
@@ -86,7 +89,21 @@ const readPackageManifest = (packageJsonPath) => {
   }
 };
 
-const validateSkillEntry = (skillMdPath) => {
+/** 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);
@@ -104,18 +121,45 @@ const validateSkillEntry = (skillMdPath) => {
     fail(`${skillMdPath} is not a file. Reinstall the package and re-run.`);
   }
 
+  let content;
   try {
-    const descriptor = fs.openSync(skillMdPath, 'r');
-    fs.closeSync(descriptor);
+    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.`);
+  }
 };
 
-const skillDirFromPackage = (packageName, cwd) => {
+/** 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}`);
   }
@@ -130,9 +174,7 @@ const skillDirFromPackage = (packageName, cwd) => {
       if (installedName !== packageName) {
         fail(`Expected ${packageName} at ${packageDir}, but found ${installedName || 'a package without a name'}.`);
       }
-      const skillDir = path.join(packageDir, 'skill');
-      validateSkillEntry(path.join(skillDir, 'SKILL.md'));
-      return skillDir;
+      return packageDir;
     }
 
     const parent = path.dirname(dir);
@@ -143,20 +185,36 @@ const skillDirFromPackage = (packageName, cwd) => {
   }
 };
 
+/** 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);
+
+  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}`
-    );
+    fail(`Missing required option${missingOptions.length > 1 ? 's' : ''}: ${missingOptions.join(' and ')}\n${USAGE}`);
   }
 
   if (process.versions.pnp) {
@@ -168,92 +226,121 @@ const main = () => {
   const cwd = process.cwd();
   const packageName = options.package;
   const destArg = options.location;
-  const skillDir = skillDirFromPackage(packageName, cwd);
-  const linkName = linkNameFromPackage(packageName);
+  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 skillsDir = path.isAbsolute(destArg) ? destArg : path.resolve(cwd, destArg);
-  const linkPath = path.join(skillsDir, linkName);
+  const destDir = path.isAbsolute(destArg) ? destArg : path.resolve(cwd, destArg);
 
-  // Prefer a cwd-relative path in messages; use the absolute path when the link lives outside it.
+  // 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(skillsDir, { recursive: true });
+    fs.mkdirSync(destDir, { recursive: true });
   } catch (error) {
     if (error.code === 'ENOTDIR' || error.code === 'EEXIST') {
-      fail(`Cannot create ${show(skillsDir)}: a parent path exists as a file, not a directory. Remove it and re-run.`);
+      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(skillsDir)}: permission denied. Check the destination permissions and re-run.`);
+      fail(`Cannot create ${show(destDir)}: permission denied. Check the destination permissions and re-run.`);
     }
     throw error;
   }
 
-  // Idempotent, but only for the symlink we own: repoint an existing symlink (including a
-  // dangling one), and refuse to touch a real directory a user may have hand-maintained here —
-  // never recursively delete it.
-  let existing = null;
-  try {
-    existing = fs.lstatSync(linkPath);
-  } catch (error) {
-    if (error.code === 'ENOENT') {
-      existing = null;
-    } else if (isPermissionError(error)) {
-      fail(`Cannot inspect ${show(linkPath)}: permission denied. Check the destination permissions and re-run.`);
-    } else {
-      throw error;
-    }
+  // Preflight all destination links before any mutation.
+  for (const skillName of selected) {
+    preflightDestLink(path.join(destDir, skillName), show);
   }
-  if (existing) {
-    if (!existing.isSymbolicLink()) {
-      fail(`Refusing to replace ${show(linkPath)}: it exists and is not a symlink. Remove it manually and re-run.`);
-    }
 
+  // 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 {
-      if (fs.realpathSync(linkPath) === fs.realpathSync(skillDir)) {
-        console.log(`Porsche Design System skill already linked: ${show(linkPath)} -> ${skillDir}`);
-        return;
-      }
+      existingLink = fs.lstatSync(linkPath);
     } catch (error) {
-      if (error.code === 'ENOENT') {
-        // The existing link is dangling and can be replaced.
-      } else if (isPermissionError(error)) {
-        fail(`Cannot inspect ${show(linkPath)}: permission denied. Check the destination permissions and re-run.`);
-      } else {
+      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.rmSync(linkPath, { force: true });
+      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 replace ${show(linkPath)}: permission denied. Check the destination permissions and re-run.`);
+        fail(`Cannot create ${show(linkPath)}: permission denied. Check the destination permissions and re-run.`);
       }
       throw error;
     }
-  }
 
-  // Windows has no unprivileged directory symlink; a junction needs no elevation and works with
-  // the absolute target we already hold. macOS/Linux use a normal directory symlink.
-  const linkType = process.platform === 'win32' ? 'junction' : 'dir';
-  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}`);
   }
-
-  console.log(`Linked Porsche Design System skill: ${show(linkPath)} -> ${skillDir}`);
 };
 
 main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porsche-design-system/components-react",
-  "version": "4.6.0-rc.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.6.0-rc.0"
+    "@porsche-design-system/components-js": "4.6.0-rc.1"
   },
   "peerDependencies": {
     "ag-grid-community": ">= 36.0.0 <37.0.0",

package/{skill → skills/pds-knowledge-react}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: porsche-design-system-components-react
+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.
 ---
 
@@ -7,7 +7,7 @@ description: Build, style, or review web user interfaces with the Porsche Design
 
 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.
+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.
 
@@ -15,11 +15,11 @@ Prefer Porsche Design System components and tokens for new UI, even when the use
 
 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.0`; prefer the [exact-version Porsche Design System Storefront](https://designsystem.porsche.com/v4.6.0-rc.0/). 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.
+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 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.0/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 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.
 
@@ -110,7 +110,7 @@ import { PButton, PorscheDesignSystemProvider } from '@porsche-design-system/com
 
 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.0/developing/next-js/getting-started/) or the [React Router integration guide](https://designsystem.porsche.com/v4.6.0-rc.0/developing/react-router/getting-started/). Remix users should follow the React Router guidance because Remix v2 was upstreamed into React Router.
+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
 

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

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

@@ -42,6 +42,10 @@ The accordion summary should be a heading element (e.g.,`p-heading` or `<h1>` to
 - **Do** keep heading levels sequential across multiple accordions on a page.
 - **Don't** use plain text in the summary without a semantic heading.
 
+## 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-banner/accessibility.md

@@ -0,0 +1,37 @@
+# p-banner accessibility integration examples
+
+## Integration examples
+
+### Banner mounted only when shown
+
+#### ❌ Anti-pattern
+
+```tsx
+{hasError && (
+  <PBanner open heading="Error">
+    Something went wrong.
+  </PBanner>
+)}
+```
+
+#### ✅ Recommended
+
+```tsx
+{/* Pre-render the banner and update content when needed. */}
+
+<PBanner id="form-banner" heading="Error" description="Check the highlighted fields and try again." state="error"></PBanner>
+```
+
+### Error feedback without descriptive content
+
+#### ❌ Anti-pattern
+
+```tsx
+<PBanner open={true} state="error" description="Error"></PBanner>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PBanner open={true} state="error" heading="Payment could not be processed" description="Check your card details or try another payment method."></PBanner>
+```

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

@@ -43,6 +43,10 @@ The `Banner` component uses `role="status"` and `role="alert"` to announce **con
 - **Do** return focus to the trigger or at a logical place after the banner is dismissed.
 - **Don't** mount the entire banner only at the moment it 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-button/accessibility.md

@@ -0,0 +1,61 @@
+# p-button accessibility integration examples
+
+## Integration examples
+
+### ARIA on component host vs aria prop
+
+#### ❌ Anti-pattern
+
+```tsx
+<PButton aria-haspopup="dialog" aria-label="Open details of product XYZ">
+  Open details
+</PButton>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PButton aria={{'aria-haspopup': 'dialog', 'aria-label': 'Open details of product XYZ'}}>
+  Open details
+</PButton>
+```
+
+### Icon-only button without accessible name
+
+#### ❌ Anti-pattern
+
+```tsx
+<PButton icon="plus"></PButton>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PButton icon="plus" hideLabel={true}>
+  Add item XYZ to shopping cart
+</PButton>
+```
+
+### Vague button label without context
+
+#### ❌ Anti-pattern
+
+```tsx
+<PButton icon="plus">
+  Add
+</PButton>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PButton icon="plus" aria={{'aria-label': 'Add item XYZ to shopping cart'}}>
+  Add
+</PButton>
+
+{/* or use descriptive visible text */}
+
+<PButton icon="plus">
+  Add item XYZ to cart
+</PButton>
+```

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

@@ -84,6 +84,10 @@ If the text of a button does not clearly indicate what the button's behavior is,
 - **Don't** add native `aria-*` attributes directly on the component host.
 - **Don't** rely on short generic button labels like "Show" or "Add" without context.
 
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
 ## API
 
 ### Properties