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

package/skills/pds-knowledge-angular/references/components/p-tabs-bar/examples/Gradient.ts

@@ -0,0 +1,80 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule, type TabsBarUpdateEventDetail } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-tabs-bar [activeTabIndex]="activeTabIndex" [aria]="{'aria-label': 'Some label for the tablist', 'aria-description': 'Some description for the tablist'}" (update)="onUpdate($event)">
+        <button type="button">
+          Tab 0
+        </button>
+        <button type="button">
+          Tab 1
+        </button>
+        <button type="button">
+          Tab 2
+        </button>
+        <button type="button">
+          Tab 3
+        </button>
+        <button type="button">
+          Tab 4
+        </button>
+        <button type="button">
+          Tab 5
+        </button>
+        <button type="button">
+          Tab 6
+        </button>
+        <button type="button">
+          Tab 7
+        </button>
+        <button type="button">
+          Tab 8
+        </button>
+        <button type="button">
+          Tab 9
+        </button>
+        <button type="button">
+          Tab 10
+        </button>
+        <button type="button">
+          Tab 11
+        </button>
+        <button type="button">
+          Tab 12
+        </button>
+        <button type="button">
+          Tab 13
+        </button>
+        <button type="button">
+          Tab 14
+        </button>
+        <button type="button">
+          Tab 15
+        </button>
+        <button type="button">
+          Tab 16
+        </button>
+        <button type="button">
+          Tab 17
+        </button>
+        <button type="button">
+          Tab 18
+        </button>
+        <button type="button">
+          Tab 19
+        </button>
+      </p-tabs-bar>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {
+  activeTabIndex = 0;
+
+  onUpdate(e: CustomEvent<TabsBarUpdateEventDetail>) {
+    this.activeTabIndex = e.detail.activeTabIndex;
+  }
+}

package/skills/pds-knowledge-angular/references/components/p-tabs-bar/examples/Labelling.ts

@@ -0,0 +1,29 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule, type TabsBarUpdateEventDetail } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-tabs-bar [activeTabIndex]="activeTabIndex" [aria]="{'aria-label': 'Some label for the tablist', 'aria-description': 'Some description for the tablist'}" (update)="onUpdate($event)">
+        <button type="button">
+          Tab One
+        </button>
+        <button type="button">
+          Tab Two
+        </button>
+        <button type="button">
+          Tab Three
+        </button>
+      </p-tabs-bar>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {
+  activeTabIndex = 0;
+
+  onUpdate(e: CustomEvent<TabsBarUpdateEventDetail>) {
+    this.activeTabIndex = e.detail.activeTabIndex;
+  }
+}

package/skills/pds-knowledge-angular/references/components/p-tabs-bar/examples/Links.ts

@@ -0,0 +1,23 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-tabs-bar>
+        <a href="https://porsche.com/page-1">
+          Page One
+        </a>
+        <a href="https://porsche.com/page-2">
+          Page Two
+        </a>
+        <a href="https://porsche.com/page-3">
+          Page Three
+        </a>
+      </p-tabs-bar>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skills/pds-knowledge-angular/references/components/p-tabs-bar/p-tabs-bar.md

@@ -0,0 +1,185 @@
+# p-tabs-bar
+
+The `p-tabs-bar` component is a styled button/link list for multiple purposes. You can use it with your framework router to ensure your **window location** updates on tab click, use it for **hash routing** and displaying content accordingly to the hash, as **skip navigation** to move on a longer page or to **change the state** of another element and therefore change the appearance of your content.
+
+The component does not handle the display of your content. If you use the component you have to manually care for the content to be rendered beneath. To help with this task the component triggers an event called `update` with the index of the active tab.
+
+If you intend to only change content on tab-click without location changes and you are fine that the content needs to be pre-rendered then we prepared a component which also handles the correct display of content according to the active tab. Have a look at the [Tabs](../p-tabs/p-tabs.md) component.
+
+It is a controlled component. This means it does not contain any internal state, and you are in full control over its behavior.
+
+> **Important note**
+>
+> For documentation purpose we use `<button>` tags in the examples below to make them clickable without changing the route. For route changes it is mandatory to use `<a>` tags with `href` in your application. And be aware of that it's not allowed to mix and match `<button>` with `<a>` tags as direct children in the component!
+
+Basic implementation is a tab bar with tabs to switch between the content. Just put `<button>` tags if you need to change e.g. the state on tab-click or `<a>` tags, if you also have to manipulate the window location, inside the `<p-tabs-bar>` component and it will handle all styling behaviors.
+
+In order to get notified when the active tabs change, you need to register an event listener for the `update` event which is emitted by `p-tabs-bar`.
+
+## Usage
+
+### Do:
+
+- Use as an anchor navigation to jump to a section on a longer page.
+- Use it to switch between different stages of content.
+- Use it to show different types of elements.
+
+### Don't:
+
+- Don't place more than six tabs within a group.
+- Don't use more than two words for a tab label whenever possible.
+- Don't use it for primary navigation.
+
+---
+
+## Related Component
+
+- [Tabs](../p-tabs/p-tabs.md)
+- [Pagination](../p-pagination/p-pagination.md)
+
+## Accessibility support
+
+### Keyboard
+
+#### Tabs Bar as a tabbed interface
+
+| Key / state | Function |
+| --- | --- |
+| `Tab` | - Moves focus to the active tab. - When the tab list contains the focus, moves focus to the next element in the tab sequence, which is the `tabpanel` element. |
+| `Right Arrow`, `Left Arrow` | - Moves focus to the next tab. - Activates the newly focused tab. - If focus is on the last tab, moves focus to the first tab. |
+| `Home`, `End` | - Moves focus to the first/last tab and activates it. |
+
+#### Tabs Bar as link list
+
+| Key / state | Function |
+| --- | --- |
+| `Tab`, `Shift-Tab` | Moves focus to next (or previous) focusable element. |
+| `Enter` | Activates the link. |
+
+### ARIA enhancements
+
+#### External **ARIA** provided by the `aria` property:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-label="STRING"` | Defines a string value that labels the tablist when used as a tabbed interface. |
+| `aria-description="STRING"` | Defines a string value that adds a more detailed description of the tablist. |
+
+The `aria` property applies only when the component is used as a **tabbed interface** with `<button>` children. It is not applied when the component is used as a **link list** with `<a>` children.
+
+#### Internal **ARIA** that is managed by the component:
+
+| ARIA | Usage |
+| --- | --- |
+| `role="tablist"` | Indicates that the element serves as a container for a set of tabs. |
+| `role="tab"` | Indicates the button serves as a tab control. |
+| `aria-selected="BOOLEAN"` | Indicates whether the tab is selected and whether its associated tabpanel is visible. |
+
+## Development considerations
+
+### Labelling
+
+When multiple tab bars appear on the same page, or when the purpose of the tabs is not clear from the visible tab labels alone, provide a descriptive accessible name for the tablist using the `aria` property, e.g.: `<p-tabs-bar aria="{ 'aria-label': 'Some label for the tablist', 'aria-description': 'Some description for the tablist' }">`.
+
+### ARIA enhancements if used as a tabbed interface
+
+The `p-tabs-bar` component is detached from the content (`tabpanel`) which belongs to the active tab. To be truly accessible you need to provide additional ARIA attributes, because every tab (`button`) needs an `aria-controls` attribute which points to the corresponding `id` of the `tabpanel`. The content placeholder needs the `role="tabpanel"` and the attribute `aria-labelledby` which points to the unique `id` of the corresponding tab (`button`).
+
+You must also take care of the **focus handling** of the `tabpanel`. Therefore, the active tab panel must have a `tabindex="0"` to receive keyboard focus and the focus indicator must be styled accordingly. Use the provided focus style like this:
+
+```html
+<p-tabs-bar
+  aria="{ 'aria-label': 'Some label for the tablist', 'aria-description': 'Some description for the tablist' }"
+  active-tab-index="0"
+>
+  <button type="button" id="tab-item-0" aria-controls="tab-panel-0">Tab One</button>
+  <button type="button" id="tab-item-1" aria-controls="tab-panel-1">Tab Two</button>
+  <button type="button" id="tab-item-2" aria-controls="tab-panel-2">Tab Three</button>
+</p-tabs-bar>
+<div id="tab-panel-0" role="tabpanel" tabindex="0" aria-labelledby="tab-item-0">
+  <p-text>Your content of Tab 1</p-text>
+</div>
+<div id="tab-panel-1" role="tabpanel" hidden tabindex="-1" aria-labelledby="tab-item-1">
+  <p-text>Your content of Tab 2</p-text>
+</div>
+<div id="tab-panel-2" role="tabpanel" hidden tabindex="-1" aria-labelledby="tab-item-2">
+  <p-text>Your content of Tab 3</p-text>
+</div>
+```
+
+```scss
+p-tabs-bar ~ [tabindex='0'][role='tabpanel'] {
+  @include pds-focus;
+}
+```
+
+### ARIA enhancements if used as a link list
+
+#### Route based navigation
+
+If the `p-tabs-bar` is used as a link list (navigation context), the semantics of that UI component changes completely - from a **tabbed interface** where content changes happen **on-site** to a **list of links** where content changes are **route-based**. Therefore, additional ARIA attributes **must not** be provided for tab identification. The `p-tabs-bar` component manages this also internally.
+
+To enhance accessibility even further, wrap the `p-tabs-bar` in a `<nav>` element with an `aria-label` attribute. Additionally, an `aria-current="page"` attribute should be provided to the active link.
+
+```html
+<nav aria-label="Label for the navigation">
+  <p-tabs-bar>
+    <a href="https://porsche.com/page-1" aria-current="page">Page One</a>
+    <a href="https://porsche.com/page-2">Page Two</a>
+    <a href="https://porsche.com/page-3">Page Three</a>
+  </p-tabs-bar>
+</nav>
+```
+
+#### In-page jump navigation
+
+If the `p-tabs-bar` is used as an in-page jump navigation, you should follow the same rules as for the route-based variant except that `aria-current="page"` should not be used.
+
+### Common do's and don'ts
+
+- **Do** pass tablist ARIA through the `aria` prop when using a tabbed interface.
+- **Do** wrap route-based navigation in `<nav>` with a descriptive `aria-label`.
+- **Do** wire `aria-controls`, `role="tabpanel"`, and `aria-labelledby` in the host application for tab interfaces.
+- **Don't** add tab semantics when the component is used as a link list for route-based navigation.
+
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `activeTabIndex` | `number | undefined` | `undefined` | Sets the zero-based index of the currently active tab. Pass `undefined` to render all tabs in an unselected state. |
+| `aria` | `TabsBarAriaAttribute` | `undefined` | Sets ARIA attributes on the tablist, such as `aria-label` and `aria-description`. |
+| `background` | `'canvas'` `'surface'` `'frosted'` `'none'` | `'none'` | Sets the background color of the tabs bar. Use `frosted` only when placed on top of images, videos, or gradients. |
+| `compact` | `boolean` | `undefined` | Reduces the tab height and padding for use in dense layouts where vertical space is limited. |
+| `size` | `'small'` `'medium'`<br>`BreakpointCustomizable<TabsBarSize>` | `'small'` | Sets the font size of the tab labels using the PDS typographic scale. Supports responsive breakpoint values. |
+| `weight` _(deprecated)_ | `'regular'` `'semi-bold'` | `'regular'` | @deprecated Will be removed in the next major release. Has no effect anymore. |
+
+### Events
+
+| Event | Type | Description |
+| --- | --- | --- |
+| `update` | `CustomEvent<TabsBarUpdateEventDetail>`<br>`{ activeTabIndex: number }` | Emitted when the user clicks a different tab, carrying the new `activeTabIndex` in the event detail. |
+
+### Controlled properties
+
+- `activeTabIndex` — a controlled prop: the component does **not** update it itself. Handle the `update` event and assign the new value to `activeTabIndex` yourself, or the change will not take effect.
+
+### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| _(default)_ | no | — | Default slot for the `button` or `a` tags which will be rendered as tabs. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.ts](./examples/Default.ts) |
+| Links | If the `p-tabs-bar` is used as a link list (navigation context), the semantics of that UI component changes completely - from a **tabbed interface** where content changes happen **on-site** to a **list of links** where content changes are **route-based**. | [./examples/Links.ts](./examples/Links.ts) |
+| Gradient color | If the amount of tabs exceeds the viewport, the component renders arrow-buttons to help with horizontal scrolling. | [./examples/Gradient.ts](./examples/Gradient.ts) |
+| Labelling | Use the `aria` property to provide an accessible name and optional description for the tablist when the component is used as a tabbed interface with `<button>` children. | [./examples/Labelling.ts](./examples/Labelling.ts) |

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

@@ -0,0 +1,19 @@
+# p-tag accessibility integration examples
+
+## Integration examples
+
+### Status conveyed by color and icon only
+
+#### ❌ Anti-pattern
+
+```html
+<p-tag variant="success" icon="check"></p-tag>
+```
+
+#### ✅ Recommended
+
+```html
+<p-tag variant="success" icon="check">
+  Configuration saved
+</p-tag>
+```

package/skills/pds-knowledge-angular/references/components/p-tag/examples/Default.ts

@@ -0,0 +1,15 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-tag>
+        Some label
+      </p-tag>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skills/pds-knowledge-angular/references/components/p-tag/examples/Multiline.ts

@@ -0,0 +1,17 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <div class="w-[100px]">
+        <p-tag variant="success" class="whitespace-normal">
+          Some label with longer text wrapped in a narrow container
+        </p-tag>
+      </div>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skills/pds-knowledge-angular/references/components/p-tag/examples/SlottedButton.ts

@@ -0,0 +1,44 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <div class="flex flex-wrap gap-static-md">
+        <p-tag icon="car" variant="primary">
+          <button type="button">
+            Variant primary
+          </button>
+        </p-tag>
+        <p-tag variant="secondary">
+          <button type="button">
+            Variant secondary
+          </button>
+        </p-tag>
+        <p-tag variant="info">
+          <button type="button">
+            Variant info
+          </button>
+        </p-tag>
+        <p-tag variant="warning">
+          <button type="button">
+            Variant warning
+          </button>
+        </p-tag>
+        <p-tag variant="success">
+          <button type="button">
+            Variant success
+          </button>
+        </p-tag>
+        <p-tag variant="error">
+          <button type="button">
+            Variant error
+          </button>
+        </p-tag>
+      </div>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skills/pds-knowledge-angular/references/components/p-tag/examples/SlottedLink.ts

@@ -0,0 +1,44 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <div class="flex flex-wrap gap-static-md">
+        <p-tag icon="car" variant="primary">
+          <a href="https://porsche.com">
+            Variant primary
+          </a>
+        </p-tag>
+        <p-tag variant="secondary">
+          <a href="https://porsche.com">
+            Variant secondary
+          </a>
+        </p-tag>
+        <p-tag variant="info">
+          <a href="https://porsche.com">
+            Variant info
+          </a>
+        </p-tag>
+        <p-tag variant="warning">
+          <a href="https://porsche.com">
+            Variant warning
+          </a>
+        </p-tag>
+        <p-tag variant="success">
+          <a href="https://porsche.com">
+            Variant success
+          </a>
+        </p-tag>
+        <p-tag variant="error">
+          <a href="https://porsche.com">
+            Variant error
+          </a>
+        </p-tag>
+      </div>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

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

@@ -0,0 +1,70 @@
+# p-tag
+
+`p-tag` is used to label, categorize, or organize items by using keywords that describe them.
+
+## Usage
+
+Use tags to label, categorize, or organize items using keywords that describe them.
+
+### Do:
+
+- Use to indicate or highlight a certain attribute of an item.
+- Use to show that content is mapped to one or multiple categories.
+- Use to indicate that a certain filter is active.
+- Use short labeling for easy scanning.
+- Have a large number of tags horizontally scrollable, swipeable, or navigable with arrows.
+- Have tags in a predefined space and move to the next line once they meet the boundary.
+- Use color themes such as success, neutral, warning, and error for better visual perception
+- Include icons to improve the faster perception.
+- Add a link for further explanation about the tag for better understandability (With modal).
+- Add a link for additional information that is not necessary for the task completion (With modal).
+
+### Don't:
+
+- Don't use more than two words (only if necessary).
+- Don't implement something else than a link or button.
+- Don't use Tags for navigation.
+
+## Accessibility support
+
+This component does not include any special accessibility features.
+
+## Development considerations
+
+Tags should communicate status or category in visible text. Do not rely on color or icon alone.
+
+### Common do's and don'ts
+
+- **Do** include descriptive text in the default slot.
+- **Do** use color and icon as supporting cues, not the only indicator.
+- **Don't** use an icon-only tag without visible text.
+
+## Integration examples
+
+See [accessibility integration examples](./accessibility.md) for paired anti-pattern and recommended implementations.
+
+## API
+
+### Properties
+
+| 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 290 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`). |
+
+### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| _(default)_ | no | — | Default slot for the tag content. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.ts](./examples/Default.ts) |
+| With slotted button | It is possible to add a `<button>` tag into the `p-tag` component. | [./examples/SlottedButton.ts](./examples/SlottedButton.ts) |
+| With slotted link | It is possible to add an `<a>` tag to the `p-tag` component. | [./examples/SlottedLink.ts](./examples/SlottedLink.ts) |
+| Multiline | The contents of the `p-tag` component are rendered with `white-space: nowrap` by default. | [./examples/Multiline.ts](./examples/Multiline.ts) |

package/skills/pds-knowledge-angular/references/components/p-tag-dismissible/accessibility.md

@@ -0,0 +1,35 @@
+# p-tag-dismissible accessibility integration examples
+
+## Integration examples
+
+### Dismiss button ARIA on host vs aria prop
+
+#### ❌ Anti-pattern
+
+```html
+<p-tag-dismissible label="Sport Chrono" aria-label="Remove Sport Chrono filter"></p-tag-dismissible>
+```
+
+#### ✅ Recommended
+
+```html
+<p-tag-dismissible label="Sport Chrono" [aria]="{'aria-label': 'Remove Sport Chrono filter'}"></p-tag-dismissible>
+```
+
+### Tag without descriptive label
+
+#### ❌ Anti-pattern
+
+```html
+<p-tag-dismissible>
+  <p-icon name="watch-sport-chrono"></p-icon>
+</p-tag-dismissible>
+```
+
+#### ✅ Recommended
+
+```html
+<p-tag-dismissible label="Sport Chrono Package">
+  <p-icon name="watch-sport-chrono"></p-icon>
+</p-tag-dismissible>
+```

package/skills/pds-knowledge-angular/references/components/p-tag-dismissible/examples/Default.ts

@@ -0,0 +1,15 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-tag-dismissible>
+        Some label
+      </p-tag-dismissible>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

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

@@ -0,0 +1,79 @@
+# p-tag-dismissible
+
+`p-tag-dismissible` is used in contexts where the user can actively remove a tag. It is often seen in filtering.
+
+## Usage
+
+Allows users to quickly refine the result of data they want to be presented on the page.
+
+### Do:
+
+- Use to show that a certain filter is active.
+- Use this component with a label if additional information is needed (e.g. category an attribute/filter refers to).
+
+### Don't:
+
+- Don't use it for other interactions than dismissing a selection.
+- Don't have long content that causes multiline.
+
+## Accessibility support
+
+### Keyboard
+
+| Key / state | Function |
+| --- | --- |
+| `Tab`, `Shift-Tab` | Moves focus to the next (or previous) focusable element. |
+| `Enter`, `Space` | Removes the element. |
+
+### ARIA enhancements
+
+#### External **ARIA** provided by the `aria` property:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-label` | Defines a string value that labels the interactive element. |
+
+#### Internal **ARIA** that is managed by the component:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-hidden="true"` | The "close" icon is hidden from assistive technologies. |
+
+## Development considerations
+
+### Focus handling
+
+Ensure that when a `p-tag-dismissible` is removed, the focus is set to the previous or next `p-tag-dismissible` or to another focusable element. This prevents losing the focus order.
+
+### Common do's and don'ts
+
+- **Do** provide a visible `label` that describes the tag content.
+- **Do** pass dismiss-button ARIA through the `aria` prop when the default action text is insufficient.
+- **Do** move focus to a sensible target after removing a tag.
+- **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 |
+| --- | --- | --- | --- |
+| `aria` | `TagDismissibleAriaAttribute` | `undefined` | Sets ARIA attributes on the dismiss button element, for example use `aria-label` to provide a descriptive close action for screen readers. |
+| `compact` | `boolean` | `false` | Reduces the tag's padding and height for use in dense layouts where vertical space is limited. |
+| `label` | `string` | `undefined` | Sets the visible label text displayed inside the tag alongside the dismiss button. |
+
+### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| _(default)_ | no | — | Default slot for the tag content. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.ts](./examples/Default.ts) |