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

package/skills/pds-knowledge-react/references/components/p-drilldown/examples/Default.tsx

@@ -0,0 +1,117 @@
+import React from 'react';
+import { useState } from 'react';
+import { PButton, PDrilldown, PDrilldownItem, PDrilldownLink, type DrilldownUpdateEventDetail } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  const [activeIdentifier, setActiveIdentifier] = useState(undefined);
+  const [open, setOpen] = useState(false);
+
+  const onClick = () => {
+    setOpen(true);
+  }
+  const onUpdate = (e: CustomEvent<DrilldownUpdateEventDetail>) => {
+    setActiveIdentifier(e.detail.activeIdentifier);
+  }
+  const onDismiss = () => {
+    setOpen(false);
+  }
+
+  return (
+    <>
+      <nav aria-label="Main">
+        <PButton type="button" aria={{'aria-haspopup': 'dialog'}} onClick={onClick}>
+          Open Drilldown
+        </PButton>
+        <PDrilldown open={open} activeIdentifier={activeIdentifier} onUpdate={onUpdate} onDismiss={onDismiss}>
+          <PDrilldownItem identifier="id-1" label="Some Label (1)">
+            <PDrilldownItem identifier="id-1-1" label="Some Label (1-1)">
+              <PDrilldownLink href="#">
+                Some anchor (1-1)
+              </PDrilldownLink>
+              <PDrilldownLink>
+                <a href="#">
+                  Some anchor (1-1)
+                </a>
+              </PDrilldownLink>
+            </PDrilldownItem>
+            <PDrilldownItem identifier="id-1-2" label="Some Label (1-2)">
+              <PDrilldownLink href="#">
+                Some anchor (1-2)
+              </PDrilldownLink>
+              <PDrilldownLink href="#">
+                Some anchor (1-2)
+              </PDrilldownLink>
+              <PDrilldownLink href="#">
+                Some anchor (1-2)
+              </PDrilldownLink>
+              <PDrilldownItem identifier="id-1-2-1" label="Some Label (1-2-1)">
+                <PDrilldownLink href="#">
+                  Some anchor (1-2-1)
+                </PDrilldownLink>
+                <PDrilldownLink href="#">
+                  Some anchor (1-2-1)
+                </PDrilldownLink>
+              </PDrilldownItem>
+              <PDrilldownLink href="#">
+                Some anchor (1-2)
+              </PDrilldownLink>
+            </PDrilldownItem>
+            <PDrilldownLink href="#">
+              Some anchor (1-1)
+            </PDrilldownLink>
+            <PDrilldownLink href="#">
+              Some anchor (1-1)
+            </PDrilldownLink>
+            <PDrilldownLink href="#">
+              Some anchor (1-1)
+            </PDrilldownLink>
+          </PDrilldownItem>
+          <PDrilldownItem identifier="id-2" label="Some Label (2)">
+            <PDrilldownLink href="#">
+              Some anchor (2)
+            </PDrilldownLink>
+            <PDrilldownLink href="#">
+              Some anchor (2)
+            </PDrilldownLink>
+            <PDrilldownLink href="#">
+              Some anchor (2)
+            </PDrilldownLink>
+            <PDrilldownLink href="#">
+              Some anchor (2)
+            </PDrilldownLink>
+          </PDrilldownItem>
+          <PDrilldownItem identifier="id-3" label="Some Label (3)">
+            <PDrilldownLink href="#">
+              Some anchor (3)
+            </PDrilldownLink>
+            <PDrilldownLink href="#">
+              Some anchor (3)
+            </PDrilldownLink>
+            <PDrilldownLink href="#">
+              Some anchor (3)
+            </PDrilldownLink>
+          </PDrilldownItem>
+          <PDrilldownItem identifier="id-4" label="Some Label (4)">
+            <PDrilldownLink href="#">
+              Some anchor (4)
+            </PDrilldownLink>
+            <PDrilldownLink href="#">
+              Some anchor (4)
+            </PDrilldownLink>
+            <PDrilldownLink href="#">
+              Some anchor (4)
+            </PDrilldownLink>
+          </PDrilldownItem>
+          <PDrilldownItem identifier="id-5" label="Some Label (5)">
+            <PDrilldownLink href="#">
+              Some anchor (5)
+            </PDrilldownLink>
+            <PDrilldownLink href="#">
+              Some anchor (5)
+            </PDrilldownLink>
+          </PDrilldownItem>
+        </PDrilldown>
+      </nav>
+    </>
+  )
+}

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

@@ -0,0 +1,172 @@
+# p-drilldown
+
+> **Experimental:** This component is experimental — its API may change in any release. Avoid relying on it in production.
+
+> **Experimental Component**
+>
+> The `p-drilldown` component is experimental and might be changed or removed in a future release.
+
+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. It is a controlled component that gives you flexible control over its behavior.
+
+The basic concept of the component is to have a button that opens the `p-drilldown` with an infinite multilevel structure. The levels are generated out of `p-drilldown-item` which generates a list of cascade buttons to navigate to a deeper level, back buttons and a header section on mobile view. These items can be filled with e.g. `p-drilldown-link`, another `p-drilldown-item` or any HTML element.
+
+The visibility of `p-drilldown` can be controlled by its `open` property.
+
+It's **obligatory** that each `p-drilldown-item` has a unique `identifier` and `label` defined.
+
+Since it's a controlled component it's necessary to register an event listener for the `dismiss` and `update` event in order to get notified when `p-drilldown` needs to be closed or navigated to another hierarchy level.
+
+## Usage
+
+### Do:
+
+- Use Drilldown for multilevel purposes.
+- Use Drilldown for multilevel on desktop & mobile.
+- Use a button-pure with a burger icon as the main trigger for the Drilldown component.
+- Use additional interaction items to trigger component.
+- Use a multilevel hierarchy that matches the two-layer capability of the component.
+- Use the first layer for multilevel targets or categories for link lists.
+- Use the second layer only if necessary.
+- Use section headings on the second layer for a group of links.
+- Use link-tile on the second layer for important links.
+
+### Don't:
+
+- Don't put too much additional information into the component.
+- Don't use other interaction components than mentioned.
+- Don't manipulate the heading in the second layer.
+- Don't implement external links without indicators.
+
+---
+
+## Related components
+
+- [Flyout](../p-flyout/p-flyout.md)
+
+## Accessibility support
+
+The `Drilldown` component uses the native `dialog` element to provide a modal dialog which comes with browser-specific behavior. As a result, accessibility features may vary across different browsers.
+
+### Keyboard
+
+| Key / state | Function |
+| --- | --- |
+| `Tab`, `Shift-Tab` | Moves focus to the next (or previous) focusable element inside the dialog. Focus is trapped (browser behavior). |
+| `ESC` | Closes the dialog. |
+| `focus` on trigger element | The focus is returned to the trigger element after closing the dialog (browser behavior). |
+
+### ARIA enhancements
+
+#### External **ARIA** provided by the `aria` property:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-label` | Defines a string value that labels the dialog element. |
+
+## Development considerations
+
+To inform users that the trigger button opens a `dialog`, the `aria-haspopup` attribute must be set using the `aria` property, e.g.: `aria="{ 'aria-haspopup': 'dialog' }"`.
+
+### Common do's and don'ts
+
+- **Do** use a semantic trigger (usually a button) with a meaningful accessible name.
+- **Do** set `aria-haspopup` through the trigger component `aria` prop.
+- **Do** provide a meaningful dialog label through the drilldown `aria` prop when needed.
+- **Don't** add native `aria-*` attributes directly on the component host.
+
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `activeIdentifier` | `string | undefined` | `undefined` | Sets which `p-drilldown-item` (by `identifier`) is currently expanded to show its sub-navigation level. |
+| `aria` | `DrilldownAriaAttribute` | `undefined` | Sets ARIA attributes on the drilldown dialog element for improved screen reader accessibility. |
+| `open` | `boolean` | `false` | Controls whether the drilldown navigation panel is visible. |
+
+### Events
+
+| Event | Type | Description |
+| --- | --- | --- |
+| `dismiss` | `CustomEvent<void>` | Emitted when the user closes the drilldown via the close button or Escape key. |
+| `update` | `CustomEvent<DrilldownUpdateEventDetail>`<br>`{ activeIdentifier: string | undefined }` | Emitted when the active navigation level changes, with the new `activeIdentifier` in the event detail. |
+
+### Controlled properties
+
+- `open` — a controlled prop: the component does **not** update it itself. Handle the `dismiss` event and assign the new value to `open` yourself, or the change will not take effect.
+- `activeIdentifier` — a controlled prop: the component does **not** update it itself. Handle the `update` event and assign the new value to `activeIdentifier` yourself, or the change will not take effect.
+
+### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| _(default)_ | no | — | Default slot to render p-drilldown items. |
+
+### CSS Variables
+
+| CSS Variable | Default | Description |
+| --- | --- | --- |
+| `--p-drilldown-grid-template` | `auto/auto` | Overrides the CSS `grid-template` of the default slot container, allowing custom grid layout for drilldown items. |
+| `--p-drilldown-gap` | `8px` | Overrides the gap between drilldown items in the default slot container. |
+
+## Sub-components
+
+These tags are only valid inside the parent(s) listed under each one — often this component, but some are shared and list a different parent (e.g. a tag documented here via a common ancestor). Their APIs come from the same authoritative `component-meta` as the parent above.
+
+### `p-drilldown-item` _(experimental)_
+
+> **Experimental:** This component is experimental — its API may change in any release. Avoid relying on it in production.
+
+Allowed parents: `p-drilldown`, `p-drilldown-item`.
+
+#### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `cascade` | `boolean` | `false` | Private property set by the component itself. |
+| `identifier` _(required)_ | `string` | `undefined` | Sets the unique identifier matched against the drilldown's `activeIdentifier` to determine if this item is shown. |
+| `label` | `string` | `undefined` | Sets the text used for the back button, sticky header, and cascade button that navigates into this navigation level. |
+| `primary` | `boolean` | `false` | Private property set by the component itself. |
+| `secondary` | `boolean` | `false` | Private property set by the component itself. |
+
+#### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| _(default)_ | no | — | Default slot for the main content. |
+| `button` | no | — | Shows a custom button to reach a deeper level of the navigation structure. |
+| `header` | no | — | Shows a custom header section on mobile view. |
+
+### `p-drilldown-link` _(experimental)_
+
+> **Experimental:** This component is experimental — its API may change in any release. Avoid relying on it in production.
+
+Allowed parents: `p-drilldown`, `p-drilldown-item`.
+
+#### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `active` | `boolean` | `false` | Visually marks the link as the currently active navigation item, e.g. the current page. |
+| `aria` | `DrilldownLinkAriaAttribute` | `undefined` | Sets ARIA attributes on the link for improved accessibility. Only applies when `href` is set. |
+| `download` | `string` | `undefined` | Sets the native `download` attribute to trigger a file download. Only applies when `href` is set. |
+| `href` | `string` | `undefined` | When set, the component renders as an anchor navigating to this URL. Otherwise, provide a slotted anchor element. |
+| `rel` | `string` | `undefined` | Sets the `rel` attribute on the link element (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. |
+
+#### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| _(default)_ | no | — | Default slot to render the link label. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.tsx](./examples/Default.tsx) |
+| Example with custom content | To give more flexibility, it's possible to use custom slots `slot="button"` (renders a custom cascade button) and/or `slot="header"` (renders a custom header on mobile view). | [./examples/CustomContent.tsx](./examples/CustomContent.tsx) |

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

@@ -0,0 +1,37 @@
+# p-fieldset accessibility integration examples
+
+## Integration examples
+
+### Unlabeled field group
+
+#### ❌ Anti-pattern
+
+```tsx
+<PFieldset>
+  <PInputText name="street" label="Street"></PInputText>
+  <PInputText name="city" label="City"></PInputText>
+</PFieldset>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PFieldset label="Delivery address">
+  <PInputText name="street" label="Street"></PInputText>
+  <PInputText name="city" label="City"></PInputText>
+</PFieldset>
+```
+
+### Error state without recovery guidance
+
+#### ❌ Anti-pattern
+
+```tsx
+<PFieldset label="Delivery address" state="error" message="Invalid"></PFieldset>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PFieldset label="Delivery address" required={true} state="error" message="Complete all required address fields to continue."></PFieldset>
+```

package/skills/pds-knowledge-react/references/components/p-fieldset/examples/Default.tsx

@@ -0,0 +1,12 @@
+import React from 'react';
+import { PFieldset, PInputText } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PFieldset label="Some legend label">
+        <PInputText label="Some label" name="some-name"></PInputText>
+      </PFieldset>
+    </>
+  )
+}

package/skills/pds-knowledge-react/references/components/p-fieldset/examples/Required.tsx

@@ -0,0 +1,13 @@
+import React from 'react';
+import { PFieldset, PInputText } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PFieldset label="Some legend label" required={true}>
+        <PInputText label="Some label" name="some-name-1" required={true}></PInputText>
+        <PInputText label="Some label" name="some-name-2" required={true} className="mt-fluid-sm"></PInputText>
+      </PFieldset>
+    </>
+  )
+}

package/skills/pds-knowledge-react/references/components/p-fieldset/examples/SlottedLabel.tsx

@@ -0,0 +1,15 @@
+import React from 'react';
+import { PFieldset, PInputText } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PFieldset>
+        <span slot="label">
+          Some legend label
+        </span>
+        <PInputText label="Some label" name="some-name"></PInputText>
+      </PFieldset>
+    </>
+  )
+}

package/skills/pds-knowledge-react/references/components/p-fieldset/examples/SlottedMessage.tsx

@@ -0,0 +1,15 @@
+import React from 'react';
+import { PFieldset, PInputText } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PFieldset label="Some legend label" state="error">
+        <PInputText label="Some label" name="some-name"></PInputText>
+        <span slot="message">
+          Some error message
+        </span>
+      </PFieldset>
+    </>
+  )
+}

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

@@ -0,0 +1,92 @@
+# p-fieldset
+
+The `p-fieldset` is a grouping component for wrapping contextual associated form elements. Its visible part is an HTML *legend* element, which can be seen like a headline for describing the meaning of a form block. You can see some usage examples on our [form patterns section](https://designsystem.porsche.com/patterns/forms/resources/).
+
+## Usage
+
+### Do:
+
+- Use to group related fields together to make them more organized and easier to understand for users.
+- Use descriptive and clear labels for the field sets to help users quickly understand what information is being requested.
+- Use for grouping several form controls as well as labels within a form.
+- Use it for grouping several checkboxes.
+- Use it for creating a date picker.
+- Use consistent formatting and styling for field sets to maintain visual consistency and improve the overall user experience.
+- Use field sets to control the visibility of groups of fields that are not always necessary, such as advanced options or additional information.
+- Test your field sets with users to ensure they are effective in improving the usability of your forms or page layouts.
+
+### Don't:
+
+- Don't use too many field sets on a single form or page layout.
+- Don't use to hide important information or fields that users need to complete a form.
+- Don't rely solely on field sets to improve the usability of your forms or page layouts.
+
+---
+
+## Behavior
+
+### Sections including form elements
+
+[Form pattern guideline](https://designsystem.porsche.com/patterns/forms).
+
+## Accessibility support
+
+### ARIA enhancements
+
+#### External **ARIA** provided by the `aria` property:
+
+| ARIA | Usage |
+| --- | --- |
+| `role="radiogroup"` | Changes the default role of `group` to `radiogroup` |
+
+#### Internal **ARIA** that is managed by the component:
+
+| ARIA | Usage |
+| --- | --- |
+| `role="alert"` | When content is populated or changed in `state="error"`, the component announces it immediately. |
+| `aria-required="true"` | Indicates if all children of the fieldset group are required. |
+| `aria-invalid="true"` | If `error` state is set. |
+| `aria-describedby="IDREF"` | References the accessible description when `state` message is provided. |
+
+## Development considerations
+
+### Common do's and don'ts
+
+- **Do** provide a clear `label` that describes the grouped fields.
+- **Do** use the component state/message API so group validation is announced.
+- **Do** use `aria="{ 'role': 'radiogroup' }"` only when the fieldset contains custom radio controls.
+- **Don't** set `state="error"` without a descriptive `message`.
+
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `aria` | `'radiogroup'` | `undefined` | Overrides the ARIA role on the fieldset — use `radiogroup` when grouping radio buttons. |
+| `label` | `string` | `''` | Sets the visible legend text displayed above the grouped form controls. |
+| `labelSize` | `'small'` `'medium'` | `'medium'` | Sets the font size of the fieldset label (`small`, `medium`, or `large`). |
+| `message` | `string` | `''` | Sets the validation feedback message displayed below the fieldset when `state` is `success` or `error`. |
+| `required` | `boolean` | `false` | Marks all controls within the fieldset as required and adds a required indicator to the label. |
+| `state` | `'none'` `'error'` `'success'` | `'none'` | Sets the validation state of the fieldset, controlling the color and style of the feedback message. |
+
+### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| `label` | no | — | Shows a label. Only [phrasing content](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content) is allowed. |
+| _(default)_ | no | — | Default slot for the main content. |
+| `message` | no | — | Shows a state message. Only [phrasing content](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content) is allowed. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.tsx](./examples/Default.tsx) |
+| Slotted label | Slotted label | [./examples/SlottedLabel.tsx](./examples/SlottedLabel.tsx) |
+| Slotted message | Slotted message | [./examples/SlottedMessage.tsx](./examples/SlottedMessage.tsx) |
+| Required | Setting `required="true"` on `p-fieldset` only renders the asterisk on the legend and sets `aria-required` on the underlying `<fieldset>` element. | [./examples/Required.tsx](./examples/Required.tsx) |

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

@@ -0,0 +1,39 @@
+# p-flag accessibility integration examples
+
+## Integration examples
+
+### Informative flag without accessible name
+
+#### ❌ Anti-pattern
+
+```tsx
+<PFlag name="germany"></PFlag>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PFlag name="germany" aria={{'aria-label': 'Germany'}}></PFlag>
+```
+
+### Decorative flag with redundant label
+
+#### ❌ Anti-pattern
+
+```tsx
+<PFlag name="germany" aria={{'aria-label': 'Germany'}}></PFlag>
+
+<PText>
+  Germany
+</PText>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PFlag name="germany" ariaHidden={true}></PFlag>
+
+<PText>
+  Germany
+</PText>
+```

package/skills/pds-knowledge-react/references/components/p-flag/examples/Default.tsx

@@ -0,0 +1,10 @@
+import React from 'react';
+import { PFlag } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PFlag aria={{'aria-label': 'Flag of Germany'}}></PFlag>
+    </>
+  )
+}

package/skills/pds-knowledge-react/references/components/p-flag/examples/ResponsiveSize.tsx

@@ -0,0 +1,10 @@
+import React from 'react';
+import { PFlag } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PFlag name="de" size={{'base': 'sm', 'l': '2xl'}} aria={{'aria-label': 'Flag of Germany'}}></PFlag>
+    </>
+  )
+}

package/skills/pds-knowledge-react/references/components/p-flag/examples/Size.tsx

@@ -0,0 +1,13 @@
+import React from 'react';
+import { PFlag, PText } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PText className="text-[48px]" size="inherit">
+        <PFlag className="me-static-sm" size="inherit" name="de" aria={{'aria-label': 'Flag of Germany'}}></PFlag>
+        Some text
+      </PText>
+    </>
+  )
+}

package/skills/pds-knowledge-react/references/components/p-flag/examples/SizeCssVar.tsx

@@ -0,0 +1,10 @@
+import React from 'react';
+import { PFlag } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PFlag className="[--p-flag-size:48px]" name="de" aria={{'aria-label': 'Flag of Germany'}}></PFlag>
+    </>
+  )
+}

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

@@ -0,0 +1,72 @@
+# p-flag
+
+The `p-flag` component displays a country or region flag and should be used to communicate geographic context visually.
+
+Flags are universally recognized symbols that enable rapid visual communication. Alongside icons, colors, and typography, they are a fundamental part of the Porsche design language and help create a seamless user experience.
+
+## Usage
+
+The following guidelines provide instructions for designers and developers on the appropriate use of the `flag` component for effective communication and user experience.
+
+### Do:
+
+- **Use the `flag` component for country identification.** The primary purpose is to represent a nation, such as specifying a user's country of origin, shipping location, or detailing product availability.
+
+- **Pair the flag with a label for clarity.** While flags are great for quick visual recognition, they can be ambiguous. Always accompany a flag with a country name or an appropriate label to avoid confusion.
+
+- **Use the two-letter ISO 3166-1 alpha-2 code.** This standard ensures consistency, reduces errors, and makes it easier to integrate with other systems and APIs.
+
+### Don't:
+
+- **Don't use flags to represent a language.** Many languages are spoken in multiple countries (e.g., Spanish). A flag represents a nation, not a language. Use language codes or names instead.
+
+- **Don't use flags to represent an emotion or concept.** Flags are powerful symbols of national identity. Using them as generic icons can dilute their meaning and cause user confusion.
+
+- **Don't rely solely on the flag icon.** Always provide an aria-label for accessibility. Screen readers cannot interpret flags, and without a descriptive label, you create an inaccessible user experience.
+
+## Accessibility support
+
+### ARIA enhancements
+
+#### External **ARIA** provided by the `aria` property:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-label` | Defines a string value that labels the element (through the `alt` attribute). |
+
+## Development considerations
+
+### Common do's and don'ts
+
+- **Do** pass a country or region name through the `aria` prop when the flag conveys meaning.
+- **Do** hide decorative flags from assistive technologies when adjacent text already names the country or region.
+- **Don't** leave informative flags without an accessible name.
+
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `aria` | `FlagAriaAttribute` | `undefined` | A map of ARIA attributes to enhance the flag's accessibility. For example, use `{ 'aria-label': 'German flag' }` to provide a descriptive label for screen readers. |
+| `name` | `'ad'` `'ae'` `'al'` `'am'` `'ar'` `'at'` `'au'` `'az'` `'ba'` `'bd'` `'be'` `'bg'` `'bh'` `'bn'` `'bo'` `'br'` `'by'` `'ca'` `'ch'` `'cl'` `'cn'` `'co'` `'cr'` `'cw'` `'cy'` `'cz'` `'de'` `'dk'` `'do'` `'dz'` `'ec'` `'ee'` `'eg'` `'es'` `'fi'` `'fr'` `'gb'` `'ge'` `'gh'` `'gi'` `'gr'` `'gt'` `'hk'` `'hn'` `'hr'` `'ht'` `'hu'` `'id'` `'ie'` `'il'` `'in'` `'is'` `'it'` `'jm'` `'jo'` `'jp'` `'ke'` `'kh'` `'kr'` `'kw'` `'kz'` `'lb'` `'li'` `'lk'` `'lt'` `'lu'` `'lv'` `'ma'` `'mc'` `'md'` `'me'` `'mk'` `'mn'` `'mo'` `'mq'` `'mt'` `'mu'` `'mx'` `'my'` `'ng'` `'nl'` `'no'` `'nz'` `'om'` `'pa'` `'pe'` `'pf'` `'ph'` `'pk'` `'pl'` `'pr'` `'pt'` `'py'` `'qa'` `'re'` `'ro'` `'rs'` `'ru'` `'sa'` `'se'` `'sg'` `'si'` `'sk'` `'sv'` `'th'` `'tn'` `'tr'` `'tt'` `'tw'` `'ua'` `'us'` `'uy'` `'uz'` `'ve'` `'vn'` `'xx'` `'za'` | `'de'` | Specifies the country flag to display. Use the two-letter ISO 3166-1 alpha-2 country code. For example, use `us` for the United States, `de` for Germany, `gb` for Great Britain. |
+| `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<FlagSize>` | `'sm'` | Defines the size of the flag, aligned with the typographic scale used by components such as p-icon, p-spinner, p-text, and p-heading. When set to `inherit`, the size is derived from a custom font-size defined on a parent element, calculated against the global line-height (based on `ex`-unit) to remain visually consistent with other typographic-scale-based components. |
+
+### CSS Variables
+
+| CSS Variable | Default | Description |
+| --- | --- | --- |
+| `--p-flag-size` | — | Defines the width and height of the flag. Overrides the `size` property when set. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.tsx](./examples/Default.tsx) |
+| Size via Prop | The `size` property offers a set of predefined sizes that cover most use cases. | [./examples/Size.tsx](./examples/Size.tsx) |
+| Size via CSS Variable | For full control over the flag's dimensions, use the custom CSS variable `--p-flag-size`, which accepts any valid CSS length value. | [./examples/SizeCssVar.tsx](./examples/SizeCssVar.tsx) |
+| Responsive Size | The `size` property supports `BreakpointCustomizable` values, allowing you to define different sizes for each major breakpoint (`xs`, `s`, `m`, `l`, `xl`). | [./examples/ResponsiveSize.tsx](./examples/ResponsiveSize.tsx) |