polymorph-ui-components-mcp 0.0.1

package/build/docs/GUIDELINES.md

@@ -0,0 +1,380 @@
+# Code Guidelines
+
+Guidelines for writing TypeScript and Svelte code in this project. These rules apply to all components, utilities, and modules.
+
+---
+
+## 1. No Double-Bang (`!!`) Coercion
+
+Do not use `!!` to convert values to booleans. It obscures intent and bypasses proper type narrowing.
+
+```ts
+// Bad
+let showImage = $derived(!!src && !imageError);
+
+// Good
+let showImage = $derived(typeof src === 'string' && src.length > 0 && !imageError);
+```
+
+---
+
+## 2. Safe Index Access
+
+### Arrays and strings: use `.at()` instead of bracket notation with numeric literals
+
+`.at()` returns `T | undefined`, making the caller handle the missing case explicitly. It also supports negative indices for end-relative access.
+
+```ts
+// Bad
+const first = words[0];
+const last = words[words.length - 1];
+
+// Good
+const first = words.at(0);
+const last = words.at(-1);
+```
+
+### DOM lists (`NodeList`, `TouchList`, etc.): use `.item()` instead of bracket notation
+
+These types do not support `.at()`. The `.item()` method returns `T | null`, which makes the null case explicit.
+
+```ts
+// Bad
+const el = focusable[0];
+const touch = event.touches[0];
+
+// Good
+const el = focusable.item(0);
+const touch = event.touches.item(0);
+```
+
+### String character access: use `.charAt()` instead of bracket notation
+
+`.charAt()` returns `''` for out-of-bounds access instead of `undefined`, making the behavior predictable.
+
+```ts
+// Bad
+const initial = word[0];
+
+// Good
+const initial = word.charAt(0);
+```
+
+---
+
+## 3. No Falsy/Truthy Checks for Non-Boolean Values
+
+Do not rely on JavaScript's implicit falsy coercion (`if (x)`, `if (!x)`, `x || default`, `x && expr`) for values that are not booleans. Use explicit type narrowing with `typeof` instead.
+
+Do **not** use `=== undefined` or `!== undefined` — always prefer `typeof` checks, which are safer (no risk of `undefined` being shadowed) and express the expected type clearly.
+
+### Strings (`string | undefined`)
+
+```ts
+// Bad
+if (!name) { ... }
+if (title) { ... }
+aria-label={title || 'Sheet'}
+
+// Good
+if (typeof name !== 'string' || name.length === 0) { ... }
+if (typeof title === 'string') { ... }
+aria-label={title ?? 'Sheet'}
+```
+
+### Functions (`(() => void) | undefined`)
+
+```ts
+// Bad
+{#if onclick}
+
+// Good
+{#if typeof onclick === 'function'}
+```
+
+### Objects / Snippets (`T | undefined`)
+
+Use `typeof` to check for the expected type rather than comparing against `undefined`. Snippets are functions at runtime; objects are `'object'`.
+
+```ts
+// Bad
+{#if footer}
+{#if previousIcon}
+{#if view.properties}
+{#if footer !== undefined}
+{#if previousIcon !== undefined}
+
+// Good — snippets are functions
+{#if typeof footer === 'function'}
+{#if typeof previousIcon === 'function'}
+
+// Good — objects / records
+{#if typeof view.properties === 'object'}
+```
+
+### DOM references (`HTMLElement | null`)
+
+```ts
+// Bad
+if (sheetPanel) { ... }
+
+// Good
+if (sheetPanel !== null) { ... }
+```
+
+### Numeric values (array `.length`, counts, etc.)
+
+```ts
+// Bad
+{#if views.length}
+
+// Good
+{#if views.length > 0}
+```
+
+### When `||` vs `??` matters
+
+Use `??` (nullish coalescing) when the intent is to fall back only for `null` / `undefined`. Use `||` only when you genuinely want to fall back for all falsy values (including `0`, `''`, `false`).
+
+```ts
+// Bad - falls back for '' which may be a valid value
+const label = title || 'Default';
+
+// Good - falls back only for null/undefined
+const label = title ?? 'Default';
+```
+
+---
+
+## 4. Reuse Existing Components
+
+Before implementing behaviour that already exists in the component library (error handling, fallback rendering, loading states, etc.), check if an existing component already handles it. Compose components rather than duplicating logic.
+
+**Example:** The `Img` component handles image error-based fallback rendering. The `Avatar` component should reuse `Img` instead of implementing its own `<img onerror={...}>` logic.
+
+```svelte
+<!-- Bad - duplicating Img's error handling logic -->
+<img {src} {alt} onerror={handleError} />
+
+<!-- Good - reusing the Img component -->
+<Img {src} {alt} onerror={handleImageError} />
+```
+
+When a child component does not expose the exact hook you need, extend its interface (e.g. add an `onerror` callback prop) rather than bypassing it with a raw HTML element.
+
+---
+
+## 5. Remove Redundant Guards
+
+Do not guard against conditions that are already guaranteed by the type system or the runtime.
+
+```ts
+// Bad - event parameter is always provided by the handler
+if (event && Object.keys(event).length > 0 && typeof event.clientX !== 'undefined') {
+
+// Good - MouseEvent always has clientX
+if (typeof event.clientX !== 'undefined') {
+```
+
+```ts
+// Bad - TouchList is always present on TouchEvent
+if (event.touches && Object.keys(event.touches).length > 0) {
+
+// Good
+if (event.touches.length > 0) {
+```
+
+```ts
+// Bad - redundant null check before strict equality
+if (event.target && event.target === overlayDiv) {
+
+// Good - strict equality already handles null
+if (event.target === overlayDiv) {
+```
+
+---
+
+## 6. Reuse the `Button` Component for Generic Action Buttons
+
+Replace raw `<button>` elements with the reusable `Button` component for generic action buttons: submit, dismiss, close, copy, action, navigation arrows, and similar.
+
+**Do not replace** specialized interactive elements: calendar day cells, pagination page buttons, tab items, command menu items, theme switcher segments, emotion selector buttons, page indicator dots.
+
+### CSS Variable Bridging
+
+When replacing `<button>` with `<Button>`, wrap `<Button>` in a `<div>` with the original class name, and set `--button-*` CSS variables on that div to map to the component-specific CSS variables. This preserves the existing CSS variable API for consumers.
+
+```svelte
+<!-- Before -->
+<button class="close-btn" onclick={onclose} aria-label="Close">
+  {@render closeIcon()}
+</button>
+
+<!-- After -->
+<div class="close-btn">
+  <Button onclick={onclose} ariaLabel="Close">
+    {#snippet children()}
+      {@render closeIcon()}
+    {/snippet}
+  </Button>
+</div>
+
+<style>
+  .close-btn {
+    --button-background: var(--sheet-close-bg, transparent);
+    --button-border: none;
+    --button-color: var(--sheet-close-color, #666);
+    --button-hover-background: var(--sheet-close-hover-bg, #f0f0f0);
+  }
+</style>
+```
+
+### Props Available on `Button`
+
+- `text` — Optional label text
+- `icon` — Snippet for an icon
+- `children` — Snippet for arbitrary content (use instead of `text` + `icon` for custom layouts)
+- `ariaLabel` — Maps to `aria-label` on the underlying `<button>`
+- `disabled` — Disables the button (reconciled with legacy `enable` prop)
+- `onclick` / `onkeyup` — Event handlers
+- `type` — Button type (`'button'` / `'submit'` / `'reset'`)
+- `testId` — Maps to `data-pw` for test automation
+
+---
+
+## 7. `$bindable` Usage
+
+Use `$bindable` only when the component **internally mutates** the prop (e.g., `open = false` in a close handler, `checked = !checked` on click). This is Svelte 5's intended mechanism for components that self-manage state transitions. Components should be **self-sufficient** — they work out of the box without requiring the parent to wire up callbacks.
+
+**Do not use `$bindable`** for props that the component only reads. If the component never assigns to the prop, a regular prop is sufficient.
+
+```svelte
+<!-- Good — component internally sets open = false on close -->
+let {((open = $bindable(false)), onclose)}: Props = $props();
+
+<!-- Bad — component never assigns to initialPage, only reads it -->
+let {(initialPage = $bindable(0))}: Props = $props();
+```
+
+When `$bindable` is used, also provide a corresponding callback prop (`onclose`, `onchange`, `ontoggle`, `onpagechange`, etc.) so the parent can react to state changes without relying on two-way binding. Both patterns are supported — consumers choose one:
+
+- **`bind:`** — parent observes state reactively, no callback needed
+- **callback** — parent reacts imperatively in a handler, no `bind:` needed
+
+**Warning:** Consumers should avoid using **both** `bind:prop` and a callback that sets the same prop, as this creates two mutation channels for the same value and risks infinite update loops.
+
+---
+
+## 8. No `auto` for Layout/Spacing CSS Properties
+
+Do not use `auto` as a value or CSS variable default for `margin`, `padding`, `width`, `height`, `top`, `bottom`, `left`, or `right`. The meaning of `auto` varies by property and layout context, making it unpredictable.
+
+**Allowed:** `auto` is permitted for `overflow`, `overflow-x`, `overflow-y`, `pointer-events`, and `cursor`, where its behavior is well-defined and has no equivalent replacement.
+
+### Replacements
+
+| Instead of                                   | Use                                                                                                                  |
+| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `width: auto` / `height: auto`               | `fit-content`                                                                                                        |
+| `margin-left: auto` (flex push-right)        | `flex: 1` on the preceding sibling                                                                                   |
+| `margin: auto` (centering)                   | `top: 50%; left: 50%; transform: translate(-50%, -50%)` for absolute positioning, or flexbox centering on the parent |
+| `bottom: auto` / `right: auto` (positioning) | Remove the declaration entirely — only set the sides that apply                                                      |
+
+```css
+/* Bad */
+width: var(--toast-width, auto);
+margin-left: auto;
+bottom: var(--menu-dropdown-bottom, auto);
+
+/* Good */
+width: var(--toast-width, fit-content);
+/* preceding sibling has flex: 1, pushing this element right */
+/* only declare the sides that apply */
+top: var(--menu-dropdown-top, 100%);
+left: var(--menu-dropdown-left, 0);
+```
+
+---
+
+## 9. Custom Classes via `classes` Prop
+
+Every component exposes a `classes` prop (`classes?: string`) that attaches directly to the topmost container element. This allows consumers to apply custom CSS classes without wrapper elements.
+
+```svelte
+<!-- Usage -->
+<Button classes="my-custom-class another-class" text="Click me" />
+
+<!-- Renders as -->
+<div class="button-container my-custom-class another-class">
+  <button>Click me</button>
+</div>
+```
+
+### Implementation Pattern
+
+In the component template, append `{classes ?? ''}` to the topmost element's class attribute:
+
+```svelte
+<!-- Single top-level element -->
+<div class="container {classes ?? ''}">...</div>
+
+<!-- Conditional top-level elements (e.g., Avatar) — add to ALL branches -->
+{#if typeof onclick === 'function'}
+  <button class="avatar {classes ?? ''}">...</button>
+{:else}
+  <div class="avatar {classes ?? ''}">...</div>
+{/if}
+```
+
+In `properties.ts`, add `classes?: string` to the optional properties sub-type.
+
+### Theming with Classes
+
+The `classes` prop is the recommended way to implement theme variants (primary, secondary, danger, etc.). Define CSS classes that set the component's CSS variables, then pass the class name via `classes`:
+
+```css
+/* app.css or a shared stylesheet */
+.btn-primary {
+  --button-color: #0070f3;
+  --button-text-color: white;
+  --button-hover-color: #0060df;
+  --button-border-radius: 6px;
+}
+
+.btn-secondary {
+  --button-color: transparent;
+  --button-text-color: #0070f3;
+  --button-border: 1px solid #0070f3;
+  --button-hover-color: #f0f7ff;
+}
+
+.btn-danger {
+  --button-color: #e00;
+  --button-text-color: white;
+  --button-hover-color: #c00;
+}
+
+.banner-success {
+  --banner-background: #e6f9ed;
+  --banner-color: #1a7f37;
+  --banner-icon-color: #1a7f37;
+}
+
+.banner-warning {
+  --banner-background: #fff8e6;
+  --banner-color: #9a6700;
+  --banner-icon-color: #9a6700;
+}
+```
+
+```svelte
+<!-- Usage — apply theme variants via classes -->
+<Button classes="btn-primary" text="Save" />
+<Button classes="btn-secondary" text="Cancel" />
+<Button classes="btn-danger" text="Delete" />
+
+<Banner classes="banner-success" text="Deployment complete" />
+<Banner classes="banner-warning" text="API rate limit approaching" />
+```
+
+This approach keeps components free from hardcoded design presets while giving consumers full control over theming. Multiple variant systems can coexist, and variants compose naturally with space-separated class names.

package/build/docs/Gauge.md

@@ -0,0 +1,46 @@
+# Gauge
+
+A circular visual indicator for displaying percentages. Uses an SVG ring where the filled arc represents the current value. The `value` prop controls the filled portion (0-100) and an optional centered label displays the rounded percentage. The fill arc animates smoothly when the value changes.
+
+## Usage
+
+```svelte
+<script>
+  import { Gauge } from 'polymorph-ui-components';
+</script>
+
+<Gauge value={75} />
+```
+
+## Props
+
+| Prop      | Type      | Required | Default | Description                                                                                                                                                            |
+| --------- | --------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| value     | `number`  | Yes      | `-`     | Current percentage value (0-100). Values are clamped to the 0-100 range. Controls how much of the circular arc is filled.                                              |
+| showLabel | `boolean` | No       | `true`  | Whether to display the rounded percentage text centered inside the gauge ring.                                                                                         |
+| testId    | `string`  | No       | `-`     | Value for the data-pw attribute, used for end-to-end testing selectors.                                                                                                |
+| classes   | `string`  | No       | `-`     | CSS class string applied to the component's top-level element. Useful for theming — define classes with CSS variable overrides and pass them to create variant styles. |
+
+## CSS Variables
+
+Override these custom properties to theme the component.
+
+| Variable                      | Default   | CSS Property        | Description                                                    |
+| ----------------------------- | --------- | ------------------- | -------------------------------------------------------------- |
+| `--gauge-size`                | `120px`   | width, height       | Diameter of the gauge container.                               |
+| `--gauge-stroke-width`        | `8`       | stroke-width        | Width of the circular track and fill arc.                      |
+| `--gauge-track-color`         | `#a1a1aa` | stroke              | Color of the background ring (unfilled portion of the circle). |
+| `--gauge-bar-color`           | `currentColor` | stroke              | Color of the filled arc that represents the current value.     |
+| `--gauge-transition-duration` | `0.3s`    | transition-duration | Duration of the animation when the filled arc changes.         |
+| `--gauge-label-font-size`     | `24px`    | font-size           | Font size of the centered percentage label.                    |
+| `--gauge-label-font-weight`   | `600`     | font-weight         | Font weight of the centered percentage label.                  |
+| `--gauge-label-font-family`   | `inherit` | font-family         | Font family of the centered percentage label.                  |
+| `--gauge-label-color`         | `currentColor` | color               | Text color of the centered percentage label.                   |
+
+## Web Component
+
+Tag: `<pui-gauge>`
+
+```html
+<pui-gauge value="75" show-label></pui-gauge>
+```

package/build/docs/GridItem.md

@@ -0,0 +1,78 @@
+# GridItem
+
+A square grid cell with a header icon (top-right), centered main icon, and text label below. Clicking toggles a loading overlay animation (clip-path radial sweep). The `showLoader` state is bindable and toggles on each click. Good for payment method or app icon grids.
+
+## Usage
+
+```svelte
+<script>
+  import { GridItem } from 'polymorph-ui-components';
+</script>
+
+<GridItem icon={'...'} text={'...'} />
+```
+
+## Props
+
+| Prop       | Type             | Required | Default | Description                                                                                                                                                            |
+| ---------- | ---------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| icon       | `string`         | Yes      | `''`    | URL of the main center icon image.                                                                                                                                     |
+| text       | `string`         | Yes      | `''`    | Label text displayed below the icon.                                                                                                                                   |
+| headerIcon | `string \| null` | No       | `''`    | URL of a small icon displayed in the top-right corner of the grid cell (e.g., an offer tag or badge).                                                                  |
+| showLoader | `boolean`        | No       | `false` | Bindable. When true, shows a rotating clip-path animation overlay on the icon area. Toggles on each click.                                                             |
+| testId     | `string`         | No       | `-`     | Test selector value applied as `data-pw` on the outermost element.                                                                                                    |
+| classes    | `string`         | No       | `-`     | CSS class string applied to the component's top-level element. Useful for theming — define classes with CSS variable overrides and pass them to create variant styles. |
+
+## Events
+
+| Event     | Type                             | Description                                                                                   |
+| --------- | -------------------------------- | --------------------------------------------------------------------------------------------- |
+| onclick   | `(event: MouseEvent) => void`    | Fires when the grid cell is clicked. The showLoader state toggles before this callback fires. |
+| onkeydown | `(event: KeyboardEvent) => void` | Fires when a key is pressed while the grid cell has focus.                                    |
+
+## CSS Variables
+
+Override these custom properties to theme the component.
+
+| Variable                             | Default                | CSS Property     | Description                                                  |
+| ------------------------------------ | ---------------------- | ---------------- | ------------------------------------------------------------ |
+| `--grid-item-height`                 | `98px`                 | height           | Height of the grid cell.                                     |
+| `--grid-item-width`                  | `66px`                 | width            | Width of the grid cell.                                      |
+| `--grid-item-header-width`                | `100%`                 | width            | Width of the header icon row.                                |
+| `--grid-item-header-justify-content`      | `end`                  | justify-content  | Horizontal alignment of the header icon.                     |
+| `--grid-item-header-position`             | `absolute`             | position         | CSS position of the header icon.                             |
+| `--grid-item-header-top`                  | `5px`                  | top              | Top offset of the header icon.                               |
+| `--grid-item-header-z-index`              | `100`                  | z-index          | Z-index of the header icon.                                  |
+| `--grid-item-header-icon-height`     | `16px`                 | height           | Height of the header icon image.                             |
+| `--grid-item-header-icon-width`      | `fit-content`          | width            | Width of the header icon image.                              |
+| `--grid-item-header-icon-object-fit` | `contain`              | object-fit       | Object-fit of the header icon image.                         |
+| `--grid-item-header-icon-z-index`    | `2`                    | z-index          | Z-index of the header icon image.                            |
+| `--grid-item-body-height`            | `64px`                 | height           | Height of the main icon container.                           |
+| `--grid-item-body-width`             | `64px`                 | width            | Width of the main icon container.                            |
+| `--grid-item-background-color`       | `transparent`          | background-color | Background color of the grid cell body.                      |
+| `--grid-item-border`                 | `1px solid currentColor` | border         | Border of the grid cell body.                                |
+| `--grid-item-border-radius`          | `8px`                  | border-radius    | Corner rounding of the grid cell body.                       |
+| `--grid-item-margin`                 | `8px 0 0 0`            | margin           | Margin of the grid cell body.                                |
+| `--grid-item-icon-height`            | `32px`                 | height           | Height of the main center icon.                              |
+| `--grid-item-icon-width`             | `fit-content`          | width            | Width of the main center icon.                               |
+| `--grid-item-icon-object-fit`        | `contain`              | object-fit       | Object-fit of the main center icon.                          |
+| `--grid-item-icon-z-index`           | `100`                  | z-index          | Z-index of the main center icon.                             |
+| `--grid-item-footer-margin`          | `8px 0 0 0`            | margin           | Margin above the text label.                                 |
+| `--grid-item-font-size`              | `inherit`              | font-size        | Font size of the text label.                                 |
+| `--grid-item-color`                  | `inherit`                 | color            | Color of the text label.                                     |
+| `--grid-item-footer-text-overflow`   | `ellipsis`             | text-overflow    | Text overflow style for the label (ellipsis for truncation). |
+| `--grid-item-footer-white-space`     | `nowrap`               | white-space      | White space handling for the label.                          |
+| `--grid-item-footer-overflow`        | `hidden`               | overflow         | Overflow behavior of the label.                              |
+| `--grid-item-footer-width`           | `100%`                 | width            | Width of the label area.                                     |
+| `--grid-item-footer-text-align`      | `center`               | text-align       | Text alignment of the label.                                 |
+| `--grid-item-footer-height`          | `fit-content`          | height           | Height of the label area.                                    |
+| `--grid-item-loader-border`                | `32px solid currentColor` | border        | Border style for the loading animation overlay.              |
+| `--grid-item-loader-duration`        | `3s`                   | animation        | Duration of the loading animation.                           |
+
+## Web Component
+
+Tag: `<pui-grid-item>`
+
+```html
+<pui-grid-item icon="/icon.svg" text="Item"></pui-grid-item>
+```

package/build/docs/Icon.md

@@ -0,0 +1,66 @@
+# Icon
+
+A clickable icon component that displays an image or inline SVG with an optional text label. The entire container is a button for accessibility. Layout direction (row or column) is controlled via CSS variable `--icon-container-direction`. Supports two rendering modes: image URL via `icon` prop, or raw SVG markup via `svg` prop.
+
+## Usage
+
+```svelte
+<script>
+  import { Icon } from 'polymorph-ui-components';
+</script>
+
+<!-- Image-based icon -->
+<Icon icon="/icons/home.svg" text="Home" />
+
+<!-- Inline SVG icon -->
+<Icon svg={'<svg viewBox="0 0 24 24" fill="currentColor"><path d="M12 2l3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z"/></svg>'} text="Star" />
+```
+
+## Props
+
+| Prop    | Type             | Required | Default | Description                                                                                                                                                            |
+| ------- | ---------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| icon    | `string`         | No       | `-`     | URL of the icon image to display. Rendered as `<img src>`.                                                                                                             |
+| svg     | `string`         | No       | `-`     | Raw SVG markup string to render inline via `{@html}`. When provided, takes priority over `icon`. Inherits `currentColor` for styling. **Must be trusted content** — never pass unsanitized user input (see Security note below). |
+| text    | `string \| null` | No       | `-`     | Optional text label displayed below the icon.                                                                                                                          |
+| classes | `string`         | No       | `-`     | CSS class string applied to the component's top-level element. Useful for theming — define classes with CSS variable overrides and pass them to create variant styles. |
+| testId  | `string`         | No       | `-`     | Test selector value applied as `data-pw` on the outermost element.                                                                                                    |
+
+> **Note:** At least one of `icon` or `svg` should be provided. If both are provided, `svg` takes priority.
+
+> **Security:** The `svg` prop uses `{@html}` for rendering and is **not sanitized**. Only pass trusted SVG markup — never pass unsanitized user input, as it may enable XSS attacks (e.g. `<svg onload="...">`).
+
+## Events
+
+| Event     | Type                             | Description                                                     |
+| --------- | -------------------------------- | --------------------------------------------------------------- |
+| onclick   | `(event: MouseEvent) => void`    | Fires when the icon container is clicked.                       |
+| onkeydown | `(event: KeyboardEvent) => void` | Fires when a key is pressed while the icon container has focus. |
+
+## CSS Variables
+
+Override these custom properties to theme the component.
+
+| Variable                     | Default        | CSS Property   | Description                                                                |
+| ---------------------------- | -------------- | -------------- | -------------------------------------------------------------------------- |
+| `--icon-container-padding`   | `4px`          | padding        | Inner padding of the icon container.                                       |
+| `--icon-container-direction` | `column`       | flex-direction | Layout direction of icon + text (column for vertical, row for horizontal). |
+| `--icon-height`              | `20px`         | height         | Height of the icon image or SVG container.                                 |
+| `--icon-width`               | `20px`         | width          | Width of the icon image or SVG container.                                  |
+| `--icon-padding`             | `4px`          | padding        | Padding around the icon image or SVG container.                            |
+| `--icon-svg-color`           | `currentColor` | color          | Color of the inline SVG icon (only applies when using `svg` prop).         |
+| `--icon-text-padding`        | `4px`          | padding        | Padding around the text label.                                             |
+| `--icon-text-direction`      | `column`       | flex-direction | Layout direction of the text area.                                         |
+| `--icon-text-font-size`      | `inherit`      | font-size      | Font size of the text label.                                               |
+
+## Web Component
+
+Tag: `<pui-icon>`
+
+```html
+<!-- Image-based -->
+<pui-icon icon="/icons/home.svg" text="Home"></pui-icon>
+
+<!-- Inline SVG -->
+<pui-icon svg="<svg viewBox='0 0 24 24' fill='currentColor'><path d='M12 2l3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z'/></svg>" text="Star"></pui-icon>
+```

package/build/docs/IconStack.md

@@ -0,0 +1,68 @@
+# IconStack
+
+A horizontal stack of circular icons/avatars with negative margin layering (each icon overlaps the previous one). Each item can be either an `image` (renders an `<img>`) or `text` (renders a text span). Icons are z-indexed so the first icon appears on top. Commonly used for showing multiple user avatars or bank icons in a compact space.
+
+## Usage
+
+```svelte
+<script>
+  import { IconStack } from 'polymorph-ui-components';
+</script>
+
+<IconStack />
+```
+
+## Props
+
+| Prop    | Type              | Required | Default | Description                                                                                                                                                            |
+| ------- | ----------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| icons   | `IconStackItem[]` | Yes      | `-`     | Array of IconStackItem objects. Each item has a `type` ('image' or 'text') and a `content` string (URL for images, display text for text items).                       |
+| testId  | `string`          | No       | `-`     | Test selector value applied as `data-pw` on the outermost element.                                                                                                     |
+| classes | `string`          | No       | `-`     | CSS class string applied to the component's top-level element. Useful for theming — define classes with CSS variable overrides and pass them to create variant styles. |
+
+## CSS Variables
+
+Override these custom properties to theme the component.
+
+| Variable                           | Default               | CSS Property    | Description                                             |
+| ---------------------------------- | --------------------- | --------------- | ------------------------------------------------------- |
+| `--icon-stack-container-margin`         | `0px`                 | margin          | Margin of the icon stack container.                     |
+| `--icon-stack-icon-width`               | `36px`                | width           | Width of each icon circle.                              |
+| `--icon-stack-icon-height`              | `36px`                | height          | Height of each icon circle.                             |
+| `--icon-stack-icon-bg`                  | `white`               | background      | Background color of each icon circle.                   |
+| `--icon-stack-icon-radius`              | `50%`                 | border-radius   | Corner rounding of each icon (50% for circle).          |
+| `--icon-stack-icon-margin`              | `0px 0px 0px -14px`   | margin          | Margin of each icon (negative left for overlap effect). |
+| `--icon-stack-icon-align-items`         | `center`              | align-items     | Vertical alignment of content inside each icon.         |
+| `--icon-stack-icon-border`              | `1px solid currentColor` | border          | Border of each icon circle.                             |
+| `--icon-stack-icon-justify-content`     | `center`              | justify-content | Horizontal alignment of content inside each icon.       |
+| `--icon-stack-icon-shadow`              | `0 2px 4px #00000026` | box-shadow      | Box shadow of each icon circle.                         |
+| `--icon-stack-img-width`                | `36px`                | width           | Width of the image inside each icon.                    |
+| `--icon-stack-img-height`               | `36px`                | height          | Height of the image inside each icon.                   |
+| `--icon-stack-text-container-width`           | `36px`                | width           | Width of text-type icon containers.                     |
+| `--icon-stack-text-container-height`          | `36px`                | height          | Height of text-type icon containers.                    |
+| `--icon-stack-text-container-align-items`     | `center`              | align-items     | Vertical alignment inside text-type icons.              |
+| `--icon-stack-text-container-justify-content` | `center`              | justify-content | Horizontal alignment inside text-type icons.            |
+| `--icon-stack-text-color`                     | `inherit`                | color           | Text color inside text-type icons.                      |
+| `--icon-stack-text-size`                      | `inherit`             | font-size       | Font size inside text-type icons.                       |
+| `--icon-stack-text-weight`                    | `inherit`             | font-weight     | Font weight inside text-type icons.                     |
+| `--icon-stack-text-align`                     | `center`              | text-align      | Text alignment inside text-type icons.                  |
+
+## Type Reference
+
+Custom types used by this component's props and events:
+
+### IconStackItem
+
+```typescript
+type IconStackItem = { type: 'image' | 'text'; content: string };
+```
+
+## Web Component
+
+Tag: `<pui-icon-stack>`
+
+```html
+<pui-icon-stack></pui-icon-stack>
+```
+
+> **Note:** The `icons` prop is an array — set it via JavaScript property.