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

package/skills/pds-knowledge-react/references/components/p-button/examples/AiGradientGlow.tsx

@@ -0,0 +1,90 @@
+import React from 'react';
+import { PButton } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <style>
+{`        .custom-ai-orb {
+  --p-button-bg: var(--p-color-canvas);
+  --p-button-fg: var(--p-color-primary);
+  position: relative;
+  z-index: 0;
+}
+
+.custom-ai-orb:not(:disabled, :state(loading)):hover {
+  --p-button-bg: var(--p-color-frosted-strong);
+  --p-button-fg: #fff;
+}
+
+.custom-ai-orb::before,
+.custom-ai-orb::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  z-index: -1;
+  border-radius: inherit;
+  background: linear-gradient(45deg, #00a8ff, #0151e1, #2ae3ff, #bff0ff, #0151e1, #00a8ff);
+  background-size: 400%;
+  animation: custom-ai-orb-gradient 20s linear infinite;
+}
+
+.custom-ai-orb::after {
+  filter: blur(10px);
+  animation:
+    custom-ai-orb-gradient 20s linear infinite,
+    custom-ai-orb-float 8s ease-in-out infinite;
+}
+
+@keyframes custom-ai-orb-gradient {
+  0% {
+    background-position: 0 0;
+  }
+  50% {
+    background-position: 300% 0;
+  }
+  100% {
+    background-position: 0 0;
+  }
+}
+
+@keyframes custom-ai-orb-float {
+  0% {
+    transform: scale(1) rotate(0deg);
+  }
+  50% {
+    transform: scale(1.02) rotate(0.5deg);
+  }
+  100% {
+    transform: scale(1) rotate(0deg);
+  }
+}
+
+/* Respect the user's motion preference */
+@media (prefers-reduced-motion: reduce) {
+  .custom-ai-orb::before,
+  .custom-ai-orb::after {
+    animation: none;
+  }
+}
+
+/* Decorative gradient is not conveyed in forced-colors mode */
+@media (forced-colors: active) {
+  .custom-ai-orb::before,
+  .custom-ai-orb::after {
+    display: none;
+  }
+}`}
+      </style>
+
+      <div className="flex flex-wrap gap-static-lg items-start">
+        <PButton className="custom-ai-orb" icon="ai-chat" hideLabel={true}>
+          Ask AI assistant
+        </PButton>
+        <PButton className="custom-ai-orb" icon="ai-chat">
+          Ask AI assistant
+        </PButton>
+      </div>
+    </>
+  )
+}

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

@@ -25,6 +25,55 @@ You can use native `click`, `focus`, `focusin`, `blur` and `focusout` events on
 
 ---
 
+## Custom states
+
+🧪 **Experimental**: The button exposes its loading state as a [CSS custom state](https://developer.mozilla.org/en-US/docs/Web/CSS/:state), which can be targeted with the `:state()` pseudo-class. This is handy to conditionally override the exposed CSS variables (e.g. `--p-button-bg` and `--p-button-fg`) without having to duplicate the state logic in your application.
+
+| Custom state | Applied when |
+| --- | --- |
+| `loading` | `loading` is `true` |
+
+```scss
+p-button:state(loading) {
+  --p-button-bg: light-dark(#025b3f, #21eeae);
+  --p-button-fg: light-dark(#21eeae, #025b3f);
+}
+```
+
+Custom states are a progressive enhancement: browsers without support for `CustomStateSet` or the `:state()` pseudo-class simply ignore these rules, the button keeps working and falls back to its default styling. Be aware that custom states can't be expressed during server side rendering, they are only applied once the component is hydrated on the client. Therefore, don't rely on `:state()` for styling that has to be correct on first paint.
+
+For all other states and variants, use native CSS selectors instead:
+
+| Styling target | Selector |
+| --- | --- |
+| Disabled | `p-button:disabled` (the button is form-associated) |
+| Hover | `p-button:not(:disabled, :state(loading)):hover` |
+| Focus | `p-button:focus-visible` |
+| Variant | a custom class, e.g. `<p-button class="my-button" variant="secondary">` |
+
+Since the button is a form-associated custom element, it is matched by the native `:disabled` pseudo-class as soon as the `disabled` attribute is set — no custom state is needed for it.
+
+```scss
+p-button {
+  --p-button-bg: light-dark(#025b3f, #21eeae);
+  --p-button-fg: light-dark(#21eeae, #025b3f);
+}
+
+p-button:not(:disabled, :state(loading)):hover {
+  --p-button-bg: light-dark(#013d2a, #6ef7cf);
+  --p-button-fg: light-dark(#6ef7cf, #013d2a);
+}
+
+p-button:disabled {
+  --p-button-bg: light-dark(#6f3d0b, #ffaa4f);
+  --p-button-fg: light-dark(#ffaa4f, #6f3d0b);
+}
+```
+
+As with all color customizations, you are responsible for ensuring sufficient contrast and brand compliance.
+
+---
+
 ## Related components
 
 - [Links](../p-link/p-link.md)
@@ -99,13 +148,13 @@ See [accessibility integration examples](./accessibility.md) for paired anti-pat
 | `disabled` | `boolean` | `false` | Disables the button, preventing all interaction and blocking events. |
 | `form` | `string` | `undefined` | Associates the button with a form element by its ID, so it can submit or reset that form even when placed outside of it. |
 | `hideLabel` | `boolean`<br>`BreakpointCustomizable<boolean>` | `false` | Hides the visible label while keeping it accessible to screen readers. Supports responsive breakpoint values. |
-| `icon` | `'none'`<br>one of 293 icon names — see [icon names](references/icons.md) | `'none'` | Sets the icon displayed inside the button. Use `none` to show no icon. |
+| `icon` | `'none'`<br>one of 294 icon names — see [icon names](references/icons.md) | `'none'` | Sets the icon displayed inside the button. Use `none` to show no icon. |
 | `iconSource` | `string` | `undefined` | Sets a path to a custom SVG icon, used instead of the built-in icon set. |
 | `loading` | `boolean` | `false` | Disables the button and replaces its content with a loading spinner to indicate an ongoing operation. |
 | `name` | `string` | `undefined` | Sets the name submitted with the form data when this button triggers form submission. |
 | `type` | `'button'` `'submit'` `'reset'` | `'submit'` | Sets the button's HTML type — `submit` sends the form, `reset` clears it, `button` performs no default action. |
 | `value` | `string` | `undefined` | Sets the value submitted with the form data when this button triggers form submission, paired with `name`. |
-| `variant` | `'primary'` `'secondary'` | `'primary'` | Sets the visual style variant of the button (`primary` or `secondary`). |
+| `variant` | `'primary'` `'secondary'` `'destructive'` | `'primary'` | Sets the visual style variant of the button (`primary`, `secondary` or `destructive`). Use `destructive` for actions with irreversible consequences, e.g. deleting data. |
 
 ### Slots
 
@@ -113,6 +162,17 @@ See [accessibility integration examples](./accessibility.md) for paired anti-pat
 | --- | --- | --- | --- |
 | _(default)_ | no | — | Default slot for the button label. |
 
+### CSS Variables
+
+| CSS Variable | Default | Description |
+| --- | --- | --- |
+| `--p-button-bg` | — | Overrides the background color of the button in every state, including hover. You are responsible for ensuring sufficient contrast and brand compliance. |
+| `--p-button-fg` | — | Overrides the foreground color (label, icon and loading spinner) of the button in every state, including hover. You are responsible for ensuring sufficient contrast and brand compliance. |
+| `--p-button-px` | — | Horizontal padding of the button. |
+| `--p-button-py` | — | Vertical padding of the button. |
+| `--p-button-gap` | — | Gap between the button's content (label and icon). |
+| `--p-button-radius` | — | Radius of the button |
+
 ## Examples
 
 | Example | When to use | File |
@@ -120,3 +180,5 @@ See [accessibility integration examples](./accessibility.md) for paired anti-pat
 | Default | Minimal default configuration. | [./examples/Default.tsx](./examples/Default.tsx) |
 | Form | When used as a submit button, the `name` and `value` props are submitted as a pair as part of the form data. | [./examples/Form.tsx](./examples/Form.tsx) |
 | Form Attribute | When a button is used as a submit or reset button outside a form, the `form` attribute can be utilized to explicitly associate the button with a specific form element. | [./examples/FormAttribute.tsx](./examples/FormAttribute.tsx) |
+| Custom AI Styling: Drop Shadow | 🧪 **Experimental**: This example shows what's technically possible with the exposed `--p-button-bg` and `--p-button-fg` CSS variables. | [./examples/AiDropShadow.tsx](./examples/AiDropShadow.tsx) |
+| Custom AI Styling: Gradient Glow | 🧪 **Experimental**: This example demonstrates the technical possibilities of styling around the button host element. | [./examples/AiGradientGlow.tsx](./examples/AiGradientGlow.tsx) |

package/skills/pds-knowledge-react/references/components/p-button-pure/p-button-pure.md

@@ -96,7 +96,7 @@ See [accessibility integration examples](./accessibility.md) for paired anti-pat
 | `disabled` | `boolean` | `false` | Disables the button, preventing all interaction and blocking events. |
 | `form` | `string` | `undefined` | Associates the button with a form element by its ID, so it can submit or reset that form even when placed outside of it. |
 | `hideLabel` | `boolean`<br>`BreakpointCustomizable<boolean>` | `false` | Hides the visible label while keeping it accessible to screen readers. Supports responsive breakpoint values. |
-| `icon` | `''`<br>one of 293 icon names — see [icon names](references/icons.md) | `'arrow-right'` | Sets the icon displayed next to the label. |
+| `icon` | `''`<br>one of 294 icon names — see [icon names](references/icons.md) | `'arrow-right'` | Sets the icon displayed next to the label. |
 | `iconSource` | `string` | `undefined` | Sets a path to a custom SVG icon, used instead of the built-in icon set. |
 | `loading` | `boolean` | `false` | Disables the button and replaces its icon with a loading spinner to indicate an ongoing operation. |
 | `name` | `string` | `undefined` | Sets the name submitted with the form data when this button triggers form submission. |

package/skills/pds-knowledge-react/references/components/p-button-tile/p-button-tile.md

@@ -92,7 +92,7 @@ See [accessibility integration examples](./accessibility.md) for paired anti-pat
 | `description` _(required)_ | `string` | `undefined` | Sets the description text displayed in the tile's content area. |
 | `disabled` | `boolean` | `false` | Disables the tile, preventing button interaction. |
 | `gradient` | `boolean` | `false` | Shows a gradient overlay over the media slot to improve text legibility on bright images or videos. |
-| `icon` | `'none'`<br>one of 293 icon names — see [icon names](references/icons.md) | `'none'` | Sets the icon displayed in the tile's action button. Use `none` to show no icon. |
+| `icon` | `'none'`<br>one of 294 icon names — see [icon names](references/icons.md) | `'none'` | Sets the icon displayed in the tile's action button. Use `none` to show no icon. |
 | `iconSource` | `string` | `undefined` | Sets a path to a custom SVG icon for the action button, used instead of the built-in icon set. |
 | `label` _(required)_ | `string` | `undefined` | Sets the accessible label text of the action button rendered inside the tile. |
 | `loading` | `boolean` | `false` | Disables the tile and shows a loading spinner to indicate an ongoing operation. |

package/skills/pds-knowledge-react/references/components/p-icon/examples/Overview.tsx

@@ -20,6 +20,8 @@ export const Example = () => {
 
       <PIcon name="ai-3d-object" aria={{'aria-label': 'Ai 3d Object icon'}}></PIcon>
 
+      <PIcon name="ai-chat" aria={{'aria-label': 'Ai Chat icon'}}></PIcon>
+
       <PIcon name="ai-code" aria={{'aria-label': 'Ai Code icon'}}></PIcon>
 
       <PIcon name="ai-edit" aria={{'aria-label': 'Ai Edit icon'}}></PIcon>

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

@@ -67,7 +67,7 @@ See [accessibility integration examples](./accessibility.md) for paired anti-pat
 | --- | --- | --- | --- |
 | `aria` | `IconAriaAttribute` | `undefined` | Sets ARIA attributes on the icon — use `aria-label` to make the icon meaningful to screen readers when it conveys information. |
 | `color` | `'primary'` `'contrast-higher'` `'contrast-high'` `'contrast-medium'` `'contrast-low'` `'contrast-lower'` `'success'` `'warning'` `'error'` `'info'` `'inherit'` | `'primary'` | Sets the fill color of the icon using PDS color tokens. |
-| `name` | one of 293 icon names — see [icon names](references/icons.md) | `'arrow-right'` | Selects an icon from the built-in PDS icon library by name (e.g. `arrow-right`, `close`). |
+| `name` | one of 294 icon names — see [icon names](references/icons.md) | `'arrow-right'` | Selects an icon from the built-in PDS icon library by name (e.g. `arrow-right`, `close`). |
 | `size` | `'2xs'` `'xs'` `'sm'` `'md'` `'lg'` `'xl'` `'2xl'` `'3xl'` `'4xl'` `'5xl'` `'inherit'`<br>_deprecated:_ `'xx-small'` `'x-small'` `'small'` `'medium'` `'large'` `'x-large'` `'xx-large'`<br>`BreakpointCustomizable<IconSize>` | `'sm'` | Sets the icon size using the PDS typographic scale. Use `inherit` to derive size from the parent element. Supports responsive breakpoint values. |
 | `source` | `string` | `undefined` | Sets a path to a custom SVG icon, used instead of the built-in icon library. |
 

package/skills/pds-knowledge-react/references/components/p-inline-notification/p-inline-notification.md

@@ -46,7 +46,7 @@ See [accessibility integration examples](./accessibility.md) for paired anti-pat
 
 | Property | Type | Default | Description |
 | --- | --- | --- | --- |
-| `actionIcon` | `''`<br>one of 293 icon names — see [icon names](references/icons.md) | `'arrow-right'` | Sets the icon displayed inside the action button using a PDS icon name. |
+| `actionIcon` | `''`<br>one of 294 icon names — see [icon names](references/icons.md) | `'arrow-right'` | Sets the icon displayed inside the action button using a PDS icon name. |
 | `actionLabel` | `string` | `undefined` | Sets the label text of the optional action button inside the notification. |
 | `actionLoading` | `boolean` | `false` | Disables the action button and shows a spinner to indicate an ongoing operation. |
 | `description` | `string` | `''` | Sets the supporting description text shown below the heading. |

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

@@ -84,7 +84,7 @@ See [accessibility integration examples](./accessibility.md) for paired anti-pat
 | `download` | `string` | `undefined` | Sets the native `download` attribute to trigger a file download. Only applies when `href` is set. |
 | `hideLabel` | `boolean`<br>`BreakpointCustomizable<boolean>` | `false` | Hides the visible label while keeping it accessible to screen readers. Supports responsive breakpoint values. |
 | `href` | `string` | `undefined` | When set, the component renders as an anchor navigating to this URL. Otherwise, provide a slotted anchor element. |
-| `icon` | `'none'`<br>one of 293 icon names — see [icon names](references/icons.md) | `'none'` | Sets the icon displayed next to the link label. Use `none` to show no icon. |
+| `icon` | `'none'`<br>one of 294 icon names — see [icon names](references/icons.md) | `'none'` | Sets the icon displayed next to the link label. Use `none` to show no icon. |
 | `iconSource` | `string` | `undefined` | Sets a path to a custom SVG icon, used instead of the built-in icon set. |
 | `rel` | `string` | `undefined` | Sets the `rel` attribute on the link (e.g. `noopener`). Only applies when `href` is set. |
 | `target` | `'_self'` `'_blank'` `'_parent'` `'_top'` `'string'` | `'_self'` | Specifies where to open the linked URL (e.g. `_self`, `_blank`). Only applies when `href` is set. |
@@ -96,6 +96,17 @@ See [accessibility integration examples](./accessibility.md) for paired anti-pat
 | --- | --- | --- | --- |
 | _(default)_ | no | — | Default slot to render the link label. This slot can be used to slot an anchor tag instead of using the href prop. |
 
+### CSS Variables
+
+| CSS Variable | Default | Description |
+| --- | --- | --- |
+| `--p-link-bg` | — | Overrides the background color of the link in every state, including hover. You are responsible for ensuring sufficient contrast and brand compliance. |
+| `--p-link-fg` | — | Overrides the foreground color (label and icon) of the link in every state, including hover. You are responsible for ensuring sufficient contrast and brand compliance. |
+| `--p-link-px` | — | Horizontal padding of the link. |
+| `--p-link-py` | — | Vertical padding of the link. |
+| `--p-link-gap` | — | Gap between the link's content (label and icon). |
+| `--p-link-radius` | — | Radius of the link |
+
 ## Examples
 
 | Example | When to use | File |

package/skills/pds-knowledge-react/references/components/p-link-pure/p-link-pure.md

@@ -89,7 +89,7 @@ See [accessibility integration examples](./accessibility.md) for paired anti-pat
 | `download` | `string` | `undefined` | Sets the native `download` attribute to trigger a file download. Only applies when `href` is set. |
 | `hideLabel` | `boolean`<br>`BreakpointCustomizable<boolean>` | `false` | Hides the visible label while keeping it accessible to screen readers. Supports responsive breakpoint values. |
 | `href` | `string` | `undefined` | When set, the component renders as an anchor navigating to this URL. Otherwise, provide a slotted anchor element. |
-| `icon` | `''`<br>one of 293 icon names — see [icon names](references/icons.md) | `'arrow-right'` | Sets the icon displayed next to the label. |
+| `icon` | `''`<br>one of 294 icon names — see [icon names](references/icons.md) | `'arrow-right'` | Sets the icon displayed next to the label. |
 | `iconSource` | `string` | `undefined` | Sets a path to a custom SVG icon, used instead of the built-in icon set. |
 | `rel` | `string` | `undefined` | Sets the `rel` attribute on the link (e.g. `noopener`). Only applies when `href` is set. |
 | `size` | `'2xs'` `'xs'` `'sm'` `'md'` `'lg'` `'xl'` `'2xl'` `'3xl'` `'4xl'` `'5xl'` `'inherit'`<br>_deprecated:_ `'xx-small'` `'x-small'` `'small'` `'medium'` `'large'` `'x-large'`<br>`BreakpointCustomizable<LinkPureSize>` | `'sm'` | Sets the font size of the link label. Supports responsive breakpoint values. |

package/skills/pds-knowledge-react/references/components/p-segmented-control/p-segmented-control.md

@@ -145,7 +145,7 @@ Allowed parent: `p-segmented-control`.
 | --- | --- | --- | --- |
 | `aria` | `SegmentedControlItemAriaAttribute` | `undefined` | Sets ARIA attributes on the item's button element to improve accessibility for screen readers. |
 | `disabled` | `boolean` | `false` | Prevents this item from being selected and visually dims it; the parent's value will not change to this item's value. |
-| `icon` | `''`<br>one of 293 icon names — see [icon names](references/icons.md) | `undefined` | Sets an icon rendered inside the item button using an icon name from the PDS icon library. |
+| `icon` | `''`<br>one of 294 icon names — see [icon names](references/icons.md) | `undefined` | Sets an icon rendered inside the item button using an icon name from the PDS icon library. |
 | `iconSource` | `string` | `undefined` | Sets a URL to a custom SVG icon for the item button, overriding the built-in icon set. |
 | `label` | `string` | `undefined` | Sets a visible text label rendered inside the item button, used when no slotted content is provided. |
 | `value` _(required)_ | `string | number` | `undefined` | Sets the value emitted by the parent `p-segmented-control` when this item is selected. This property is*required**. |

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

@@ -50,7 +50,7 @@ See [accessibility integration examples](./accessibility.md) for paired anti-pat
 | Property | Type | Default | Description |
 | --- | --- | --- | --- |
 | `compact` | `boolean` | `false` | Reduces the tag's padding and height for use in dense layouts where vertical space is limited. |
-| `icon` | `'none'`<br>one of 293 icon names — see [icon names](references/icons.md) | `'none'` | Sets the icon displayed inside the tag alongside the label. Use `none` to render the tag without an icon. |
+| `icon` | `'none'`<br>one of 294 icon names — see [icon names](references/icons.md) | `'none'` | Sets the icon displayed inside the tag alongside the label. Use `none` to render the tag without an icon. |
 | `iconSource` | `string` | `undefined` | Sets a URL to a custom SVG icon, overriding the built-in icon set when a brand-specific icon is needed. |
 | `variant` | `'primary'` `'secondary'` `'info'` `'info-frosted'` `'warning'` `'warning-frosted'` `'success'` `'success-frosted'` `'error'` `'error-frosted'` | `'secondary'` | Sets the visual style of the tag, which controls its background and text colors (e.g. `primary`, `secondary`, `notification-info`). |