prime-ui-kit 0.0.1

package/src/components/textarea/examples/02-comment.tsx

@@ -0,0 +1,34 @@
+import { Label, Textarea } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const FIELD_ID = "order-comment";
+const MAX = 240;
+
+/**
+ * Order comment: caption above the field chrome via Label + shared id on Textarea.Root.
+ */
+export default function TextareaExampleComment() {
+  const [comment, setComment] = React.useState("");
+
+  return (
+    <div className={styles.labelBlock}>
+      <Label.Root htmlFor={FIELD_ID}>
+        Comment for the courier
+        <Label.Sub>Optional — visible to logistics until the order ships.</Label.Sub>
+      </Label.Root>
+      <Textarea.Root
+        id={FIELD_ID}
+        name="courierComment"
+        value={comment}
+        onChange={(e) => setComment(e.target.value)}
+        maxLength={MAX}
+        placeholder="Gate code, safe drop spot, or delivery window"
+      >
+        <Textarea.CharCounter current={comment.length} max={MAX} />
+        <Textarea.Hint>Keep it short; the driver sees this on the handheld.</Textarea.Hint>
+      </Textarea.Root>
+    </div>
+  );
+}

package/src/components/textarea/examples/composition.tsx

@@ -0,0 +1,21 @@
+import { Textarea, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/** Section title via `Typography`, counter + hint, and a second field with `Textarea.Error`. */
+export default function TextareaCompositionExample() {
+  return (
+    <div className={styles.compositionStack}>
+      <Typography.Root variant="body-small" weight="medium" as="div">
+        Order comment
+      </Typography.Root>
+      <Textarea.Root placeholder="Delivery notes or time window">
+        <Textarea.CharCounter current={0} max={240} />
+        <Textarea.Hint>Logistics sees this until the order ships.</Textarea.Hint>
+      </Textarea.Root>
+      <Textarea.Root variant="error" placeholder="Describe the return reason">
+        <Textarea.Error>A description is required to submit</Textarea.Error>
+      </Textarea.Root>
+    </div>
+  );
+}

package/src/components/textarea/examples/controlled.tsx

@@ -0,0 +1,17 @@
+import { Textarea } from "prime-ui-kit";
+import * as React from "react";
+
+/** Parent-owned `value` / `onChange`; character count in `Textarea.Hint`. */
+export default function TextareaControlledExample() {
+  const [notes, setNotes] = React.useState("Draft text is stored in parent state.");
+
+  return (
+    <Textarea.Root
+      value={notes}
+      onChange={(e) => setNotes(e.target.value)}
+      placeholder="Type here…"
+    >
+      <Textarea.Hint>Characters: {notes.length}</Textarea.Hint>
+    </Textarea.Root>
+  );
+}

package/src/components/textarea/examples/examples.module.css

@@ -0,0 +1,33 @@
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-m);
+}
+
+.compositionStack {
+  display: grid;
+  gap: var(--prime-sys-spacing-x3);
+  max-width: min(100%, 28rem);
+}
+
+.blockSpacer {
+  margin-top: var(--prime-sys-spacing-l);
+  width: 100%;
+  min-width: 0;
+}
+
+.labelBlock {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-s);
+}
+
+.fullWidthCard {
+  box-sizing: border-box;
+  width: 100%;
+  max-width: min(100%, 22rem);
+  padding: var(--prime-sys-spacing-x3);
+  border-radius: var(--prime-sys-radius-m);
+  border: 1px dashed var(--prime-sys-color-border-subtle);
+  background: var(--prime-sys-color-surface-raised);
+}

package/src/components/textarea/examples/features.tsx

@@ -0,0 +1,56 @@
+import { Textarea } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const OVERFLOW_DEMO =
+  "This string is longer than the 30-character demo cap so the counter shows overflow.";
+
+/** Default `autoResize`, turning it off, counter, overflow styling, and `maxLength` + counter. */
+export default function TextareaFeaturesExample() {
+  const maxLen = 120;
+  const overflowMax = 30;
+  const nativeLimit = 80;
+  const [value, setValue] = React.useState("");
+  const [overflowValue, setOverflowValue] = React.useState(OVERFLOW_DEMO);
+  const [limited, setLimited] = React.useState("");
+
+  return (
+    <>
+      <Textarea.Root placeholder="Multiple lines — height grows with content (autoResize default)">
+        <Textarea.Hint>Height follows content via wrapper `data-value`.</Textarea.Hint>
+      </Textarea.Root>
+      <div className={styles.blockSpacer}>
+        <Textarea.Root autoResize={false} placeholder="Fixed height; native resize handle">
+          <Textarea.Hint>autoResize=false</Textarea.Hint>
+        </Textarea.Root>
+      </div>
+      <div className={styles.blockSpacer}>
+        <Textarea.Root
+          placeholder="Character counter in the field footer"
+          value={value}
+          onChange={(e) => setValue(e.target.value)}
+        >
+          <Textarea.CharCounter current={value.length} max={maxLen} />
+        </Textarea.Root>
+      </div>
+      <div className={styles.blockSpacer}>
+        <Textarea.Root value={overflowValue} onChange={(e) => setOverflowValue(e.target.value)}>
+          <Textarea.CharCounter current={overflowValue.length} max={overflowMax} />
+          <Textarea.Hint>When current &gt; max, the counter gets data-overflow.</Textarea.Hint>
+        </Textarea.Root>
+      </div>
+      <div className={styles.blockSpacer}>
+        <Textarea.Root
+          placeholder={`Up to ${nativeLimit} characters`}
+          value={limited}
+          maxLength={nativeLimit}
+          onChange={(e) => setLimited(e.target.value)}
+        >
+          <Textarea.CharCounter current={limited.length} max={nativeLimit} />
+          <Textarea.Hint>Native maxLength blocks extra input.</Textarea.Hint>
+        </Textarea.Root>
+      </div>
+    </>
+  );
+}

package/src/components/textarea/examples/full-width.tsx

@@ -0,0 +1,14 @@
+import { Textarea } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/** Narrow parent column; `Textarea.Root` stretches to 100% of the track (`min-width: 0` on the field). */
+export default function TextareaFullWidthExample() {
+  return (
+    <div className={styles.fullWidthCard}>
+      <Textarea.Root placeholder="Field spans the card column width">
+        <Textarea.Hint>Parent sets width; the control root uses width: 100%.</Textarea.Hint>
+      </Textarea.Root>
+    </div>
+  );
+}

package/src/components/textarea/examples/sizes.tsx

@@ -0,0 +1,21 @@
+import { Textarea } from "prime-ui-kit";
+
+/** Four `size` tiers — one field per size with a matching `Textarea.Hint` label. */
+export default function TextareaSizesExample() {
+  return (
+    <>
+      <Textarea.Root size="s" placeholder="Size s">
+        <Textarea.Hint>size=&quot;s&quot;</Textarea.Hint>
+      </Textarea.Root>
+      <Textarea.Root size="m" placeholder="Size m">
+        <Textarea.Hint>size=&quot;m&quot;</Textarea.Hint>
+      </Textarea.Root>
+      <Textarea.Root size="l" placeholder="Size l">
+        <Textarea.Hint>size=&quot;l&quot;</Textarea.Hint>
+      </Textarea.Root>
+      <Textarea.Root size="xl" placeholder="Size xl">
+        <Textarea.Hint>size=&quot;xl&quot;</Textarea.Hint>
+      </Textarea.Root>
+    </>
+  );
+}

package/src/components/textarea/examples/states.tsx

@@ -0,0 +1,19 @@
+import { Textarea } from "prime-ui-kit";
+
+/** Default with hint, `disabled`, `readOnly`, and native `required` on the textarea. */
+export default function TextareaStatesExample() {
+  return (
+    <>
+      <Textarea.Root placeholder="With hint">
+        <Textarea.Hint>Default state</Textarea.Hint>
+      </Textarea.Root>
+      <Textarea.Root placeholder="Not editable" disabled>
+        <Textarea.Hint>disabled</Textarea.Hint>
+      </Textarea.Root>
+      <Textarea.Root defaultValue="Read only copy" readOnly>
+        <Textarea.Hint>readOnly</Textarea.Hint>
+      </Textarea.Root>
+      <Textarea.Root required placeholder="Required field" />
+    </>
+  );
+}

package/src/components/textarea/examples/variants.tsx

@@ -0,0 +1,15 @@
+import { Textarea } from "prime-ui-kit";
+
+/** `variant="default"` vs `variant="error"` with paired `Textarea.Error` (aria wiring). */
+export default function TextareaVariantsExample() {
+  return (
+    <>
+      <Textarea.Root variant="default" placeholder="Default variant">
+        <Textarea.Hint>Helper text below the field</Textarea.Hint>
+      </Textarea.Root>
+      <Textarea.Root variant="error" placeholder="Validation error">
+        <Textarea.Error>Description is required</Textarea.Error>
+      </Textarea.Root>
+    </>
+  );
+}

package/src/components/tooltip/COMPONENT.md

@@ -0,0 +1,148 @@
+# Tooltip
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+A composite tooltip: optional delay provider, root with open state, trigger that wraps a single element, and content rendered in a portal and positioned relative to the trigger.
+
+- **Use** to clarify icon-only controls, abbreviated labels, dense table cells, or non-obvious metrics on hover or keyboard focus.
+- **Use** when the extra text is short and supplementary; keep the trigger’s visible label or `aria-label` as the primary affordance where possible.
+- **Do not use** for long explanations or content that should stay visible without hover—prefer inline help, a hint, or a dedicated panel.
+- **Do not use** for interactive content inside the layer (links, buttons, inputs); tooltip content is non-interactive and uses `pointer-events: none` in styles.
+- **Do not use** one root for multiple anchors—each trigger needs its own `Tooltip.Root` (or separate instances).
+- **Do not rely** on tooltips opening for natively `disabled` controls; disabled elements often do not receive hover/focus—wrap or use a different focusable pattern if a tooltip is required.
+
+## Composition
+
+- **`Tooltip.Provider`** (optional) — wraps a subtree to share **`delayDuration`** (default **400** ms) for nested **`Tooltip.Root`** instances. Omit it when the default delay is fine.
+- **`Tooltip.Root`** — holds open state (controlled or uncontrolled). Children must include **`Tooltip.Trigger`** and **`Tooltip.Content`** (order in the tree is conventional; both participate via context).
+- **`Tooltip.Trigger`** — accepts **exactly one** **`React.ReactElement`** child. The implementation **`cloneElement`s** it: merges **`ref`**, **`className`**, **`aria-describedby`**, and pointer/focus handlers. The child must forward refs and accept standard DOM props.
+- **`Tooltip.Content`** — tooltip body; rendered through **`Portal`** as a **`div`** with **`role="tooltip"`** and **`id`** matching the trigger’s **`aria-describedby`**. Sets **`data-size`** and **`data-side`** for styling (including the arrow). Wraps children in **`ControlSizeProvider`** for the chosen **`size`**.
+
+### Minimal example
+
+```tsx
+import { Tooltip } from "prime-ui-kit";
+
+export function Example() {
+  return (
+    <Tooltip.Root>
+      <Tooltip.Trigger>
+        <button type="button">Hover</button>
+      </Tooltip.Trigger>
+      <Tooltip.Content>Help text</Tooltip.Content>
+    </Tooltip.Root>
+  );
+}
+```
+
+### Canonical example (icon-only control)
+
+Use this as the default copy-paste shell: **`aria-label`** (or another accessible name) on the **focusable** trigger, **`Button.Icon`** + **`Icon`**, and a short **`Tooltip.Content`** (often **`size="s"`** next to a **`size="m"`** control).
+
+```tsx
+import { Button, Icon, Tooltip } from "prime-ui-kit";
+
+export function CopyLinkHint() {
+  return (
+    <Tooltip.Root>
+      <Tooltip.Trigger>
+        <Button.Root
+          type="button"
+          variant="neutral"
+          mode="ghost"
+          aria-label="Copy link"
+        >
+          <Button.Icon>
+            <Icon name="action.copy" size="s" tone="subtle" />
+          </Button.Icon>
+        </Button.Root>
+      </Tooltip.Trigger>
+      <Tooltip.Content size="s">Copy page link to clipboard</Tooltip.Content>
+    </Tooltip.Root>
+  );
+}
+```
+
+Source of truth (stays in sync with the snippet above): `examples/canonical-icon-hint.tsx`.
+
+The **playground** (`playground/sections/TooltipSection.tsx`) renders the same scenarios as **`playground/snippets/tooltip/*.tsx`** (internal `@/` imports). **`examples/`** below mirrors those snippets with **`"prime-ui-kit"`** imports; playground copy may differ (e.g. Russian labels) but structure and props match.
+
+### Example files in `examples/`
+
+| File | Scenario (aligned with `playground/snippets/tooltip/`) |
+|------|----------|
+| `sizes.tsx` | Four **`Tooltip.Content`** sizes **`s`–`xl`** on the same trigger pattern |
+| `surfaces.tsx` | Same tooltip on **`surface-default`** vs **`surface-raised`** panels |
+| `states.tsx` | Default trigger; native **`disabled`** (tooltip does not open); glossary-style **`button`** trigger |
+| `side.tsx` | **`side`** **`top`** \| **`bottom`** \| **`left`** \| **`right`** |
+| `controlled.tsx` | **`open`** / **`onOpenChange`** with **`Tooltip.Provider`** **`delayDuration={0}`** and **`Switch`** |
+| `composition.tsx` | **`LinkButton`** + **`Typography`** in content; icon-only **`Button`** with **`aria-label`** |
+| `delay.tsx` | **`Tooltip.Provider`** **`delayDuration={800}`** |
+| `long-content.tsx` | Multi-line copy; **`size="m"`**; theme **`max-width`** / wrapping |
+
+| File | Extra recipe |
+|------|----------|
+| `canonical-icon-hint.tsx` | Minimal icon-only shell: **`aria-label`**, **`size="s"`** hint |
+
+### Extended usage
+
+- **Delay:** wrap a subtree in **`Tooltip.Provider`** and set **`delayDuration`** (ms). Default is **400**; use a longer value to reduce accidental flashes, or **`0`** for tests and controlled demos.
+- **Long text:** rely on the built-in **`max-width`** and **`word-break`** on the content surface; prefer shorter copy when possible—if users must read a paragraph, use inline help, **Hint**, or **Popover** instead.
+- **Placement:** set **`side`** on **`Tooltip.Content`** when **top** clips; coordinates are **viewport-clamped** (**8px** inset) but the kit does **not** auto-flip to the opposite side.
+- **Controlled:** pass **`open`** and **`onOpenChange`** on **`Tooltip.Root`**; pointer/focus on the trigger still updates the same state. Pair with **`delayDuration={0}`** when an external control should show the tooltip immediately.
+- **Disabled triggers:** native **`disabled`** elements often skip hover/focus—wrap with a focusable container or use **`aria-disabled`** + custom styling if a tooltip on a “disabled” control is required.
+
+### Note for LLMs
+
+When generating **Tooltip** markup for this library: (1) **`Tooltip.Trigger`** takes **exactly one** **`ReactElement`** child (the implementation uses **`cloneElement`**). (2) Put the **accessible name** on the trigger (**`aria-label`**, visible text, or **`aria-labelledby`**)—the tooltip supplements it; do not rely on the tooltip alone for the control’s name. (3) Do not put **links, buttons, or inputs** inside **`Tooltip.Content`** (non-interactive layer, **`pointer-events: none`**). (4) Use **one** **`Tooltip.Root`** per anchor; do not attach one root to multiple triggers. (5) For starting points, mirror **`examples/canonical-icon-hint.tsx`**, then adapt the named files in **`examples/`** (same scenarios as **`playground/snippets/tooltip/`**).
+
+## Rules
+
+- **Uncontrolled:** omit **`open`**; optional **`defaultOpen`** (defaults to **`false`**). **Controlled:** pass **`open`** and **`onOpenChange`**; the same open state drives visibility together with hover/focus on the trigger.
+- Opening is **delayed** by **`Tooltip.Provider`**’s **`delayDuration`** after **`mouseenter`** or **`focus`**; leaving or **blur** clears the timer and closes. Cleanup runs on unmount.
+- **Position:** **`side`** is **`top`** \| **`bottom`** \| **`left`** \| **`right`** (default **`top`**). Coordinates are **clamped** to the viewport (**8px** inset); there is **no automatic flip** to the opposite side when space is tight—choose **`side`** explicitly if needed.
+- **Accessibility:** trigger gets **`aria-describedby`** pointing at the content **`id`**; content uses **`role="tooltip"`**. For inline glossary-style terms, prefer **`button type="button"`** as the trigger so keyboard focus is predictable.
+- **Portal:** content does not sit in the trigger’s DOM subtree; it won’t inherit layout/CSS from ancestors of the trigger (only what you pass as children and classes on **`Tooltip.Content`**).
+- **`Tooltip.Content`** defaults **`size`** to **`m`** and **`side`** to **`top`**; visual scale and arrow follow **`data-size`** / **`data-side`** and theme tokens—there is no separate **`variant`** prop.
+
+## API
+
+The package exports the **`Tooltip`** namespace object and types **`TooltipSize`**, **`TooltipSide`**, **`TooltipProviderProps`**, **`TooltipRootProps`**, **`TooltipTriggerProps`**, **`TooltipContentProps`**.
+
+### Tooltip.Provider
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| delayDuration | `number` | `400` | No | Milliseconds to wait before opening after pointer enters or the trigger receives focus |
+| children | `React.ReactNode` | — | Yes | Subtree whose tooltips use this delay |
+
+### Tooltip.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | Yes | Typically `Tooltip.Trigger` and `Tooltip.Content` |
+| open | `boolean` | — | No | Controlled open state |
+| defaultOpen | `boolean` | `false` | No | Initial open state when uncontrolled |
+| onOpenChange | `(open: boolean) => void` | — | No | Called when open state changes |
+
+### Tooltip.Trigger
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactElement` | — | Yes | Single element; receives ref, `aria-describedby`, and open/close handlers |
+| className | `string` | — | No | Merged with the child’s `className` via `cx()` |
+
+### Tooltip.Content
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | Yes | Tooltip body; wrapped in `ControlSizeProvider` for nested controls that read control size |
+| size | `TooltipSize` (`"s"` \| `"m"` \| `"l"` \| `"xl"`) | `"m"` | No | Padding, typography, and arrow scale |
+| side | `TooltipSide` (`"top"` \| `"bottom"` \| `"left"` \| `"right"`) | `"top"` | No | Placement relative to the trigger before viewport clamping |
+| className | `string` | — | No | Additional class on the portal root |
+
+## Related
+
+[Button](../button/COMPONENT.md) — typical focusable trigger; [Label](../label/COMPONENT.md) and [Hint](../hint/COMPONENT.md) — persistent field labeling and helper text; [Popover](../popover/COMPONENT.md) — focusable, interactive overlay content.

package/src/components/tooltip/examples/canonical-icon-hint.tsx

@@ -0,0 +1,19 @@
+import { Button, Icon, Tooltip } from "prime-ui-kit";
+
+/**
+ * Icon-only control: accessible name on the trigger plus a short tooltip on hover/focus.
+ */
+export default function TooltipCanonicalIconHint() {
+  return (
+    <Tooltip.Root>
+      <Tooltip.Trigger>
+        <Button.Root type="button" variant="neutral" mode="ghost" aria-label="Copy link">
+          <Button.Icon>
+            <Icon name="action.copy" size="s" tone="subtle" />
+          </Button.Icon>
+        </Button.Root>
+      </Tooltip.Trigger>
+      <Tooltip.Content size="s">Copy page link to clipboard</Tooltip.Content>
+    </Tooltip.Root>
+  );
+}

package/src/components/tooltip/examples/composition.tsx

@@ -0,0 +1,38 @@
+import { Button, Icon, LinkButton, Tooltip, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/** Link trigger with rich content; icon-only button with `aria-label` (mirrors `playground/snippets/tooltip/composition.tsx`). */
+export default function TooltipCompositionExample() {
+  return (
+    <div className={styles.rowWrapXlCenter}>
+      <Tooltip.Provider delayDuration={200}>
+        <Tooltip.Root>
+          <Tooltip.Trigger>
+            <LinkButton.Root href="#" onClick={(e) => e.preventDefault()}>
+              Promotion terms
+            </LinkButton.Root>
+          </Tooltip.Trigger>
+          <Tooltip.Content>
+            <Typography.Root variant="body-small" as="p" className={styles.tooltipContentP}>
+              Discount applies through month-end on orders over $100.
+            </Typography.Root>
+          </Tooltip.Content>
+        </Tooltip.Root>
+      </Tooltip.Provider>
+
+      <Tooltip.Provider delayDuration={200}>
+        <Tooltip.Root>
+          <Tooltip.Trigger>
+            <Button.Root type="button" variant="neutral" mode="ghost" aria-label="Copy link">
+              <Button.Icon>
+                <Icon name="action.copy" size="s" tone="subtle" />
+              </Button.Icon>
+            </Button.Root>
+          </Tooltip.Trigger>
+          <Tooltip.Content size="s">Copy link to clipboard</Tooltip.Content>
+        </Tooltip.Root>
+      </Tooltip.Provider>
+    </div>
+  );
+}

package/src/components/tooltip/examples/controlled.tsx

@@ -0,0 +1,31 @@
+import { Button, Switch, Tooltip } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/** `open` / `onOpenChange` on `Tooltip.Root` with `delayDuration={0}` (mirrors `playground/snippets/tooltip/controlled.tsx`). */
+export default function TooltipControlledExample() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <div className={styles.controlledStack}>
+      <Switch.Root checked={open} onCheckedChange={setOpen}>
+        <Switch.Label>Tooltip open (programmatic)</Switch.Label>
+        <Switch.Hint>
+          State stays in sync with <code>open</code> and <code>onOpenChange</code> on{" "}
+          <code>Tooltip.Root</code>; hovering the button updates the same state.
+        </Switch.Hint>
+      </Switch.Root>
+      <Tooltip.Provider delayDuration={0}>
+        <Tooltip.Root open={open} onOpenChange={setOpen}>
+          <Tooltip.Trigger>
+            <Button.Root type="button" variant="neutral" mode="stroke">
+              Trigger
+            </Button.Root>
+          </Tooltip.Trigger>
+          <Tooltip.Content>Controlled tooltip</Tooltip.Content>
+        </Tooltip.Root>
+      </Tooltip.Provider>
+    </div>
+  );
+}

package/src/components/tooltip/examples/delay.tsx

@@ -0,0 +1,31 @@
+import { Button, Label, Tooltip } from "prime-ui-kit";
+import type * as React from "react";
+
+import styles from "./examples.module.css";
+
+function TooltipDemoItem({ label, children }: { label: string; children: React.ReactNode }) {
+  return (
+    <div className={styles.demoItem}>
+      <Label.Root size="s">{label}</Label.Root>
+      {children}
+    </div>
+  );
+}
+
+/** `Tooltip.Provider` with `delayDuration={800}` (mirrors `playground/snippets/tooltip/delay.tsx`). */
+export default function TooltipDelayExample() {
+  return (
+    <TooltipDemoItem label="Delay 800 ms">
+      <Tooltip.Provider delayDuration={800}>
+        <Tooltip.Root>
+          <Tooltip.Trigger>
+            <Button.Root type="button" variant="neutral" mode="stroke">
+              Hover me slowly
+            </Button.Root>
+          </Tooltip.Trigger>
+          <Tooltip.Content>Appears after 800ms</Tooltip.Content>
+        </Tooltip.Root>
+      </Tooltip.Provider>
+    </TooltipDemoItem>
+  );
+}

package/src/components/tooltip/examples/examples.module.css

@@ -0,0 +1,67 @@
+/* Mirrors playground/snippets/tooltip/snippets.module.css — layout for package examples */
+
+.demoItem {
+  display: grid;
+  gap: var(--prime-sys-spacing-s);
+  justify-items: center;
+}
+
+.rowWrapXlCenter {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--prime-sys-spacing-xl);
+  align-items: center;
+}
+
+.rowWrapXlJustifyCenter {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--prime-sys-spacing-xl);
+  justify-content: center;
+}
+
+.rowWrapMStretch {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--prime-sys-spacing-m);
+  align-items: stretch;
+}
+
+.controlledStack {
+  display: grid;
+  gap: var(--prime-sys-spacing-l);
+  max-width: 22.5rem;
+}
+
+.surfacePanel {
+  display: grid;
+  gap: var(--prime-sys-spacing-m);
+  justify-items: center;
+  padding: var(--prime-sys-spacing-l);
+  border-radius: var(--prime-sys-radius-m);
+}
+
+.surfaceDefault {
+  background: var(--prime-sys-color-surface-default);
+}
+
+.surfaceRaised {
+  background: var(--prime-sys-color-surface-raised);
+  box-shadow: var(--prime-sys-elevation-shadow-surface);
+}
+
+.inlineHelpTrigger {
+  margin: 0;
+  padding: 0;
+  border: none;
+  background: none;
+  font: inherit;
+  color: inherit;
+  cursor: help;
+  text-decoration: underline dotted;
+  text-underline-offset: 2px;
+}
+
+.tooltipContentP {
+  margin: 0;
+}

package/src/components/tooltip/examples/long-content.tsx

@@ -0,0 +1,34 @@
+import { Button, Label, Tooltip } from "prime-ui-kit";
+import type * as React from "react";
+
+import styles from "./examples.module.css";
+
+function TooltipDemoItem({ label, children }: { label: string; children: React.ReactNode }) {
+  return (
+    <div className={styles.demoItem}>
+      <Label.Root size="s">{label}</Label.Root>
+      {children}
+    </div>
+  );
+}
+
+/** Multi-line body, `size="m"`, theme max-width and wrapping (mirrors `playground/snippets/tooltip/long-content.tsx`). */
+export default function TooltipLongContentExample() {
+  return (
+    <TooltipDemoItem label="Long copy, size m">
+      <Tooltip.Provider delayDuration={200}>
+        <Tooltip.Root>
+          <Tooltip.Trigger>
+            <Button.Root type="button" variant="neutral" mode="stroke">
+              Details
+            </Button.Root>
+          </Tooltip.Trigger>
+          <Tooltip.Content>
+            Password must be at least 12 characters and include upper and lower case letters and
+            numbers. Do not reuse passwords from other services.
+          </Tooltip.Content>
+        </Tooltip.Root>
+      </Tooltip.Provider>
+    </TooltipDemoItem>
+  );
+}